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 dinodet in the libdevinfo interfaces.
Each dinodet 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
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 dibindingname(3DEVINFO) manual page.
Each device node also has a physical path, which is accessed
by calling didevfspath(3DEVINFO).
Properties provide device specific information for device
configuration and usage. Properties can be defined by
software (dipropt) or by firmware (diprompropt). One
way to access each dipropt is to make successive calls to
dipropnext(3DEVINFO) until DIPROPNIL is returned. For
each dipropt, use interfaces on the
dipropbytes(3DEVINFO) manual page to obtain property names
and values. Another way to access these properties is to
call diproplookupbytes(3DEVINFO) to find the value of a
property with a given name. Accessing a diprompropt is
similar to accessing a dipropt, except that the interface
names start with dipromprop and additional calls to
diprominit(3DEVINFO) and dipromfini(3DEVINFO) are
required.
SunOS 5.11 Last change: 15 May 2008 1
Interface Libraries libdevinfo(3LIB)
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 (diminort) can be obtained by making successive
calls to diminornext(3DEVINFO) until DIMINORNIL is
returned. For each minor node, diminordevt(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
scsivhci(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
(dipatht).
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 dipathphcinextpath(3DEVINFO), and a list of paths
associated with a specific client device node can be
obtained using dipathclientnextpath(3DEVINFO). These
functions return DIPATHNIL when the end of the list of
path nodes is reached.
For each path node, dipathstate(3DEVINFO) and related
interfaces are called to get path 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
diinit(3DEVINFO) and destroyed by calling
difini(3DEVINFO). An application can specify the data to be
SunOS 5.11 Last change: 15 May 2008 2
Interface Libraries libdevinfo(3LIB)
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 diinit(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 dinodet returned from diinit(), one can find
all children by first calling dichildnode(3DEVINFO), fol-
lowed by successive calls to disiblingnode(3DEVINFO) until
DINODENIL is returned. By following this procedure recur-
sively, an application can visit all device nodes contained
in the snapshot. Two interfaces,The diwalknode(3DEVINFO)
and diwalkminor(3DEVINFO) functions are provided to facil-
itate device tree traversal. The diwalknode() function
visits all device nodes and executes a user-supplied call-
back function for each node visited. The diwalkminor()
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 dinodet returned from diinit(), an application
can find all device nodes bound to a driver by first calling
didrvfirstnode(3DEVINFO), followed by successive calls to
didrvnextnode(3DEVINFO) until DINODENIL is returned.
Traversing the per-driver device node list works only when
the snapshot includes all device nodes.
See diinit(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.
dibindingname dibusaddr
dichildnode dicompatiblenames
didevfsminorpath didevfspath
didevfspathfree didevid
didrivermajor didrivername
didriverops didrvfirstnode
SunOS 5.11 Last change: 15 May 2008 3
Interface Libraries libdevinfo(3LIB)
didrvnextnode difini
diinit diinstance
dilinknextbylnode dilinknextbynode
dilinkprivateget dilinkprivateset
dilinkspectype dilinktolnode
dilnodedevinfo dilnodedevt
dilnodename dilnodenext
dilnodeprivateget dilnodeprivateset
diminordevt diminorname
diminornext diminornodetype
diminorprivateget diminorprivateset
diminorspectype diminortype
dinodename dinodeprivateget
dinodeprivateset dinodeid
diparentnode dipathbusaddr
dipathclientdevfspath dipathclientnextpath
dipathclientnode dipathdevfspath
dipathinstance dipathnodename
dipathphcinextpath dipathphcinode
dipathpropbytes dipathpropint64s
dipathpropints dipathproplen
dipathproplookupbytes dipathproplookupint64s
dipathproplookupints dipathproplookupstrings
dipathpropname dipathpropstrings
dipathpropnext dipathproptype
dipathstate dipromfini
diprominit diprompropdata
dipromproplookupbytes dipromproplookupints
dipromproplookupstrings diprompropname
diprompropnext dipropbytes
dipropdevt dipropint64
dipropints diproplookupbytes
diproplookupint64 diproplookupints
diproplookupstrings dipropname
dipropnext dipropstrings
diproptype disiblingnode
distate diwalklink
diwalklnode diwalkminor
diwalknode
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
SunOS 5.11 Last change: 15 May 2008 4
Interface Libraries libdevinfo(3LIB)
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
devt: 0x0080010 (32/16)
spectype: IFBLK (block special)
(disk partition /dev/rdsk/c0t2d0s2)
name: c,raw
devt: 0x0080012 (32/18)
spectype: IFCHR (character special)
FILES
/lib/libdevinfo.so.1
shared object
/usr/lib/64/libdevinfo.so.1
64-bit shared object
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 15 May 2008 5
Interface Libraries libdevinfo(3LIB)
ATRIBUTE TYPE ATRIBUTE 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),
dibindingname(3DEVINFO), dichildnode(3DEVINFO),
didevfspath(3DEVINFO), diinit(3DEVINFO),
diminordevt(3DEVINFO), diminornext(3DEVINFO),
dipathbusaddr(3DEVINFO),
dipathclientnextpath(3DEVINFO),
dipathpropbytes(3DEVINFO),
dipathproplookupbytes(3DEVINFO),
dipathpropnext(3DEVINFO), diprominit(3DEVINFO),
dipropbytes(3DEVINFO), diproplookupbytes(3DEVINFO),
dipropnext(3DEVINFO), diwalkminor(3DEVINFO),
diwalknode(3DEVINFO), attributes(5)
Writing Device Drivers
SunOS 5.11 Last change: 15 May 2008 6
|
