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

FreeBSD Manual Pages

  
 
  

home | help
libdevinfo(3LIB)	      Interface	Libraries	      libdevinfo(3LIB)

NAME
       libdevinfo - device information library

SYNOPSIS
       cc [ flag... ] file... -ldevinfo	[ library... ]
       #include	<libdevinfo.h>

DESCRIPTION
       Functions in this library access	device configuration information.

       Device  configuration  data is organized	as a tree of device nodes, de-
       fined as	di_node_t in the libdevinfo interfaces.	Each di_node_t	repre-
       sents  a	 physical  or logical (pseudo) device. Three types of data are
       associated with device nodes:

	 o  data defined for all device	nodes (attributes)

	 o  properties specific	to each	device

	 o  minor node data

       All device nodes	have a set of common attributes, such as a node	 name,
       an  instance  number, and a driver binding name.	Common device node at-
       tributes	are accessed by	calling	 interfaces  listed  on	 the  di_bind-
       ing_name(3DEVINFO)  manual  page.  Each device node also	has a physical
       path, which is accessed by calling di_devfs_path(3DEVINFO).

       Properties provide device specific information for device configuration
       and  usage.  Properties	can  be	 defined by software (di_prop_t) or by
       firmware	(di_prom_prop_t). One way to access each di_prop_t is to  make
       successive  calls  to  di_prop_next(3DEVINFO)  until DI_PROP_NIL	is re-
       turned. For each	di_prop_t, use interfaces on  the  di_prop_bytes(3DEV-
       INFO)  manual  page to obtain property names and	values.	Another	way to
       access these properties is to  call  di_prop_lookup_bytes(3DEVINFO)  to
       find   the  value  of  a	 property  with	 a  given  name.  Accessing  a
       di_prom_prop_t is similar to accessing a	di_prop_t, except that the in-
       terface	 names	 start	with  di_prom_prop  and	 additional  calls  to
       di_prom_init(3DEVINFO) and di_prom_fini(3DEVINFO) are required.

       Minor nodes contain information exported	by  the	 device	 for  creating
       special	files  for  the	 device.  Each device node has 0 or more minor
       nodes associated	with it. A list	minor nodes (di_minor_t)  can  be  ob-
       tained  by  making  successive  calls  to di_minor_next(3DEVINFO) until
       DI_MINOR_NIL is returned. For each minor	node,  di_minor_devt(3DEVINFO)
       and related interfaces are called to get	minor node data.

       Using libdevinfo	involves three steps:

	 o  Creating a snapshot	of the device tree

	 o  Traversing the device tree to get information of interest

	 o  Destroying the snapshot of the device tree

       A  snapshot  of the device tree is created by calling di_init(3DEVINFO)
       and destroyed by	calling	di_fini(3DEVINFO). An application can  specify
       the  data to be included	in the snapshot	(full or partial tree, include
       or exclude properties and minor nodes) and get a	handle to the root  of
       the  device  tree.  See	di_init(3DEVINFO) for details. The application
       then traverses the device tree in the snapshot to obtain	device config-
       uration data.

       The  device  tree  is  normally	traversed through parent-child-sibling
       linkage.	Each device node contains references to	its parent,  its  next
       sibling,	 and  the  first of its	children. Given	the di_node_t returned
       from  di_init(),	 one  can  find	 all   children	  by   first   calling
       di_child_node(3DEVINFO),	  followed  by	successive  calls  to  di_sib-
       ling_node(3DEVINFO) until DI_NODE_NIL is	returned.  By  following  this
       procedure  recursively,	an application can visit all device nodes con-
       tained in the snapshot. Two interfaces,The  di_walk_node(3DEVINFO)  and
       di_walk_minor(3DEVINFO)	functions  are	provided  to facilitate	device
       tree traversal. The di_walk_node() function visits all device nodes and
       executes	 a  user-supplied callback function for	each node visited. The
       di_walk_minor() function	does the same for each minor node in  the  de-
       vice tree.

       An  alternative	way  to	 traverse  the device tree is through the per-
       driver device node linkage. Device nodes	contain	 a  reference  to  the
       next device node	bound to the same driver. Given	the di_node_t returned
       from di_init(), an application can find all device  nodes  bound	 to  a
       driver  by  first calling di_drv_first_node(3DEVINFO), followed by suc-
       cessive calls to	di_drv_next_node(3DEVINFO) until  DI_NODE_NIL  is  re-
       turned.	Traversing the per-driver device node list works only when the
       snapshot	includes all device nodes.

       See di_init(3DEVINFO) for examples of libdevinfo	usage. See Writing De-
       vice Drivers for	information about Solaris device configuration.

INTERFACES
       The  shared  object  libdevinfo.so.1 provides the public	interfaces de-
       fined below. See	intro(3) for additional	information on	shared	object
       interfaces.

       di_binding_name		     di_bus_addr
       di_child_node		     di_compatible_names
       di_devfs_minor_path	     di_devfs_path
       di_devfs_path_free	     di_devid
       di_driver_major		     di_driver_name
       di_driver_ops		     di_drv_first_node
       di_drv_next_node		     di_fini
       di_init			     di_instance
       di_link_next_by_lnode	     di_link_next_by_node
       di_link_private_get	     di_link_private_set
       di_link_spectype		     di_link_to_lnode
       di_lnode_devinfo		     di_lnode_devt
       di_lnode_name		     di_lnode_next
       di_lnode_private_get	     di_lnode_private_set
       di_minor_devt		     di_minor_name
       di_minor_next		     di_minor_nodetype
       di_minor_private_get	     di_minor_private_set
       di_minor_spectype	     di_minor_type
       di_node_name		     di_nodeid
       di_parent_node		     di_node_private_get
       di_node_private_set	     di_prom_fini
       di_prom_init		     di_prom_prop_data
       di_prom_prop_lookup_bytes     di_prom_prop_lookup_ints
       di_prom_prop_lookup_strings   di_prom_prop_name
       di_prom_prop_next	     di_prop_bytes
       di_prop_devt		     di_prop_int64
       di_prop_ints		     di_prop_lookup_bytes
       di_prop_lookup_int64	     di_prop_lookup_ints
       di_prop_lookup_strings	     di_prop_name
       di_prop_next		     di_prop_strings
       di_prop_type		     di_sibling_node

       di_state			     di_walk_link
       di_walk_lnode		     di_walk_minor
       di_walk_node

EXAMPLES
       Example 1: Information accessible through libdevinfo interfaces

       The  following  example	illustrates the	kind of	information accessible
       through libdevinfo interfaces for a device  node	 representing  a  hard
       disk (sd2):

       Attributes
	   node	name:  sd
	   instance:   2
	   physical path:  /sbus@1f,0/espdma@e,8400000/esp@e,8800000/sd@2,0

       Properties
	   target=2
	   lun=0

       Minor nodes
	   (disk partition /dev/dsk/c0t2d0s0)
	       name:	   a
	       dev_t:	   0x0080010 (32/16)
	       spectype:   IF_BLK (block special)
	   (disk partition /dev/rdsk/c0t2d0s2)
	       name:	   c,raw
	       dev_t:	   0x0080012 (32/18)
	       spectype:   IF_CHR (character special)

FILES
       /lib/libdevinfo.so.1		       shared object

       /usr/lib/64/libdevinfo.so.1	       64-bit shared object

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsl, SUNWstatl (32-bit)  |
       +-----------------------------+-----------------------------+
       |			     |SUNWcslx (64-bit)		   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       pvs(1), devlinks(1M), prtconf(1M), intro(3), di_binding_name(3DEVINFO),
       di_child_node(3DEVINFO),			      di_devfs_path(3DEVINFO),
       di_drv_first_node(3DEVINFO),  di_drv_next_node(3DEVINFO), di_fini(3DEV-
       INFO),	 di_prom_init(3DEVINFO),    di_minor_devt(3DEVINFO),	di_mi-
       nor_next(3DEVINFO),   di_prom_fini(3DEVINFO),   di_prom_init(3DEVINFO),
       di_prop_bytes(3DEVINFO),		       di_prop_lookup_bytes(3DEVINFO),
       di_prop_next(3DEVINFO),	di_sibling_node(3DEVINFO), di_walk_minor(3DEV-
       INFO), di_walk_node(3DEVINFO), attributes(5)

       Writing Device Drivers

SunOS 5.10			  28 Sep 2004		      libdevinfo(3LIB)

NAME | SYNOPSIS | DESCRIPTION | INTERFACES | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libdevinfo&sektion=3lib&manpath=SunOS+5.10>

home | help