Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OPENFIRM(4)	       FreeBSD Kernel Interfaces Manual		   OPENFIRM(4)

NAME
     openfirm -- Open Firmware interface

SYNOPSIS
     #include <sys/types.h>
     #include <sys/ioctl.h>
     #include <dev/ofw/openfirmio.h>

DESCRIPTION
     The /dev/openfirm device is an interface to the Open Firmware device
     tree.  This interface is highly stylized.	It uses	ioctl(2) calls for all
     operations.  These	calls refer to the nodes in the	Open Firmware device
     tree.  The	nodes are represented by package handles, which	are simply in-
     teger values describing data areas.  Occasionally a package handle	of 0
     may be used or returned instead, as described below.

     The calls that only take and/or return the	package	handle of a node use a
     pointer to	a phandle_t for	this purpose.  The others use a	pointer	to a
     struct ofiocdesc descriptor, which	has the	following definition:

     struct ofiocdesc {
	     phandle_t	     of_nodeid;
	     int	     of_namelen;
	     const char	     *of_name;
	     int	     of_buflen;
	     char	     *of_buf;
     };

     The of_nodeid member is the package handle	of the node that is passed in
     or	returned.  Strings are passed in via the of_name member	of of_namelen
     length.  The maximum accepted length of of_name is	OFIOCMAXNAME.  The
     of_buf member is used to return strings except for	the OFIOCSET call
     where it is also used to pass in a	string.	 In the	latter case the	maxi-
     mum accepted length of of_buf is OFIOCMAXVALUE.  Generally, of_buf	works
     in	a value-result fashion.	 At entry to the ioctl(2) call,	of_buflen is
     expected to reflect the buffer size.  On return, of_buflen	is updated to
     reflect the buffer	contents.

     The following ioctl(2) calls are supported:

     OFIOCGETOPTNODE  Uses a phandle_t.	 Takes nothing and returns the package
		      handle of	the /options node.

     OFIOCGETNEXT     Uses a phandle_t.	 Takes the package handle of a node
		      and returns the package handle of	the next node in the
		      Open Firmware device tree.  The node following the last
		      node has a package handle	of 0.  The node	following the
		      node with	the package handle of 0	is the first node.

     OFIOCGETCHILD    Uses a phandle_t.	 Takes the package handle of a node
		      and returns the package handle of	the first child	of
		      that node.  This child may have siblings.	 These can be
		      determined by using OFIOCGETNEXT.	 If the	node does not
		      have a child, a package handle of	0 is returned.

     OFIOCGET	      Uses a struct ofiocdesc.	Takes the package handle of a
		      node and the name	of a property.	Returns	the property
		      value and	its length.  If	no such	property is associated
		      with that	node, the length of the	value is set to	-1.
		      If the named property exists but has no value, the
		      length of	the value is set to 0.

     OFIOCGETPROPLEN  Uses a struct ofiocdesc.	Takes the package handle of a
		      node and the name	of a property.	Returns	the length of
		      the property value.  This	call is	the same as OFIOCGET
		      except that only the length of the property value	is re-
		      turned.  It can be used to determine whether a node has
		      a	particular property or whether a property has a	value
		      without the need to provide memory for storing the
		      value.

     OFIOCSET	      Uses a struct ofiocdesc.	Takes the package handle of a
		      node, the	name of	a property and a property value.  Re-
		      turns the	property value and the length that actually
		      have been	written.  The Open Firmware may	choose to
		      truncate the value if it is too long or write a valid
		      value instead if the given value is invalid for the par-
		      ticular property.	 Therefore the returned	value should
		      be checked.  The Open Firmware may also completely
		      refuse to	write the given	value to the property.	In
		      this case	EINVAL is returned.

     OFIOCNEXTPROP    Uses a struct ofiocdesc.	Takes the package handle of a
		      node and the name	of a property.	Returns	the name and
		      the length of the	next property of the node.  If the
		      property referenced by the given name is the last	prop-
		      erty of the node,	ENOENT is returned.

     OFIOCFINDDEVICE  Uses a struct ofiocdesc.	Takes the name or alias	name
		      of a device node.	 Returns package handle	of the node.
		      If no matching node is found, ENOENT is returned.

FILES
     /dev/openfirm  Open Firmware interface node

DIAGNOSTICS
     The following may result in rejection of an operation:

     [EBADF]		The requested operation	requires permissions not spec-
			ified at the call to open().

     [EINVAL]		The given package handle is not	0 and does not corre-
			spond to any valid node, or the	given package handle
			is 0 where 0 is	not allowed.

     [ENAMETOOLONG]	The given name or value	exceeds	the maximum allowed
			length of OFIOCMAXNAME and OFIOCMAXVALUE bytes respec-
			tively.

SEE ALSO
     ioctl(2), ofwdump(8)

     IEEE Std 1275-1994: IEEE Standard for Boot	Firmware (Initialization
     Configuration) Firmware: Core Requirements	and Practices",	IEEE Standards
     Organization, ISBN	1-55937-426-8.

HISTORY
     The openfirm interface first appeared in NetBSD 1.6.  The first FreeBSD
     version to	include	it was FreeBSD 5.0.

AUTHORS
     The openfirm interface was	ported to FreeBSD by Thomas Moestl
     <tmm@FreeBSD.org>.	 This manual page was written by Marius	Strobl
     <marius@FreeBSD.org> based	on the OpenBSD manual page for openprom(4).

CAVEATS
     Due to limitations	within Open Firmware itself, these functions run at
     elevated priority and may adversely affect	system performance.

     For at least the /options node the	property value passed in to the
     OFIOCSET call has to be null-terminated and the value length passed in
     has to include the	terminating `\0'.  However, as with the	OFIOCGET call,
     the returned value	length does not	include	the terminating	`\0'.

FreeBSD	13.0		       January 16, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | FILES | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=openfirm&sektion=4&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help