#ident "@(#)libdevinfo.3lib.txt.changebar 1.2 09/08/09 SMI" Interface Libraries libdevinfo(3LIB) NAME libdevinfo - device information library SYNOPSIS cc [ flag... ] file... -ldevinfo [ library... ] #include DESCRIPTION Functions in this library access device configuration infor- mation. 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. The types of data associated with device nodes are: o data defined for all device nodes (attributes) o data defined for all multipath path nodes o data defined for all minor node data o properties specific to nodes | o data defined for all hotplug connections | 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 inter- faces listed on the di_binding_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 returned. For each di_prop_t, use interfaces on the di_prop_bytes(3DEVINFO) 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 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 of minor nodes (di_minor_t) can 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. In some configurations, multipath device access via a vir- tual host controller interface (vHCI) abstraction is possi- ble. An example of a driver using this abstraction is scsi_vhci(7D). In such cases, devices are not directly represented as children of their physical host controller interface (pHCI) bus adapter. Instead, devices have an identity-oriented representation as a child of a vHCI. All paths leading to the same identity are represented by a com- mon child endpoint of the vHCI called the "client" device node. The vHCI virtualizes access among the underlying pHCI physical paths. The underlying connection between vHCI- managed client endpoints and the pHCI paths to that endpoint is represented by a class of nodes called "path" nodes (di_path_t). Each path node is associated with two device nodes: its pHCI device node, and its client device node. A list of paths associated with a specific pHCI device node can be obtained using di_path_phci_next_path(3DEVINFO), and a list of paths associated with a specific client device node can be obtained using di_path_client_next_path(3DEVINFO). These functions return DI_PATH_NIL when the end of the list of path nodes is reached. For each path node, di_path_state(3DEVINFO) and related interfaces are called to get path node data. | Hotplug connections are locations in the device tree where | devices can be dynamically inserted or removed. A hotplug | connection represents a control point where child devices | can be hotplugged. Each device node has 0 or more hotplug | connection nodes associated with it. A list of hotplug nodes | (di_hp_t) can be obtained by making successive calls to | di_hp_next(3DEVINFO) until DI_HP_NIL is returned. For each | hotplug node, di_hp_name(3DEVINFO) and related interfaces | are called to get hotplug connection 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 configuration 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), fol- lowed by successive calls to di_sibling_node(3DEVINFO) until DI_NODE_NIL is returned. By following this procedure recur- sively, an application can visit all device nodes contained in the snapshot. Two interfaces,The di_walk_node(3DEVINFO) and di_walk_minor(3DEVINFO) functions are provided to facil- itate device tree traversal. The di_walk_node() function visits all device nodes and executes a user-supplied call- back function for each node visited. The di_walk_minor() function 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(), 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. 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 Device Drivers for information about Solaris device configuration. INTERFACES The shared object libdevinfo.so.1 provides the public inter- faces defined 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_hp_child di_hp_connection | di_hp_depends_on di_hp_description | di_hp_last_change di_hp_name | di_hp_next di_hp_state | di_hp_type 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_node_private_get di_node_private_set | di_nodeid di_parent_node | di_path_bus_addr di_path_client_devfs_path | di_path_client_next_path di_path_client_node | di_path_devfs_path di_path_instance | di_path_node_name di_path_phci_next_path | di_path_phci_node di_path_prop_bytes | di_path_prop_int64s di_path_prop_ints | di_path_prop_len di_path_prop_lookup_bytes | di_path_prop_lookup_int64s di_path_prop_lookup_ints | di_path_prop_lookup_strings di_path_prop_name | di_path_prop_strings di_path_prop_next | di_path_prop_type di_path_state | 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_hp di_walk_link di_walk_lnode di_walk_minor di_walk_node EXAMPLES Example 1 Information accessible through libdevinfo inter- faces 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 attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsl, SUNWstatl (32-bit) | | | SUNWcslx (64-bit) | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | 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_hp_name(3DEVINFO), | di_hp_next(3DEVINFO), di_init(3DEVINFO), di_minor_devt(3DEVINFO), di_minor_next(3DEVINFO), di_path_bus_addr(3DEVINFO), di_path_client_next_path(3DEVINFO), di_path_prop_bytes(3DEVINFO), di_path_prop_lookup_bytes(3DEVINFO), di_path_prop_next(3DEVINFO), di_prom_init(3DEVINFO), di_prop_bytes(3DEVINFO), di_prop_lookup_bytes(3DEVINFO), | di_prop_next(3DEVINFO), di_walk_hp(3DEVINFO), | di_walk_minor(3DEVINFO), di_walk_node(3DEVINFO), | attributes(5) Writing Device Drivers