libdevinfo(3DEVINFO) (man pages section 3: Extended Library Functions)

man pages section 3: Extended Library Functions

libdevinfo(3DEVINFO)

NAME

libdevinfo– library of device information functions

SYNOPSIS

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

DESCRIPTION

libdevinfo is a set of interfaces used to access device configuration data.

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

data defined for all device nodes (attributes)
properties specific to each device
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 attributes are accessed by calling interfaces listed on the di_binding_name(3DEVINFO) man 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 may 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 returned. For each di_prop_t, use interfaces on the di_prop_bytes(3DEVINFO) man 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 interface 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) may be obtained 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:

Creating a snapshot of the device tree
Traversing the device tree to get information of interest
Destroying the snapshot of the device tree

di_init(3DEVINFO)

di_fini(3DEVINFO)

di_init(3DEVINFO)

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(3DEVINFO), one can find all children by first calling di_child_node(3DEVINFO), followed by successive calls to di_sibling_node(3DEVINFO), until DI_NODE_NIL is returned. By following this procedure recursively, an application can visit all device nodes contained in the snapshot. Two interfaces, di_walk_node(3DEVINFO) and di_walk_minor(3DEVINFO), are provided to facilitate device tree traversal. The di_walk_node(3DEVINFO) interface visits all device nodes and executes a user-supplied callback function for each node visited. The di_walk_minor(3DEVINFO) does the same for each minor node in the device 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(3DEVINFO), an application can find all device nodes bound to a driver by first calling di_drv_first_node(3DEVINFO), followed by successive calls to di_drv_next_node(3DEVINFO) until DI_NODE_NIL is returned. Note that traversing the per-driver device node list works only when the snapshot includes all device nodes.

See libdevinfo(3LIB) for a complete list of libdevinfo interfaces. See di_init(3DEVINFO) for examples of libdevinfo usage. See Writing Device Drivers for details of Solaris device configuration.

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)

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT Level	Safe
Interface Stability	Evolving