openSolaris 2008 - User Interfaces - Writing Device Drivers

User Interfaces

The LDI includes user-level library and command interfaces to report device layering and usage information. Device Information Library Interfaces discusses the libdevinfo(3LIB) interfaces for reporting device layering information. Print System Configuration Command Interfaces discusses the prtconf(1M) interfaces for reporting kernel device usage information. Device User Command Interfaces discusses the fuser(1M) interfaces for reporting device consumer information.

Device Information Library Interfaces

The LDI includes libdevinfo(3LIB) interfaces that report a snapshot of device layering information. Device layering occurs when one device in the system is a consumer of another device in the system. Device layering information is reported only if both the consumer and the target are bound to a device node that is contained within the snapshot.

Device layering information is reported by the libdevinfo(3LIB) interfaces as a directed graph. An lnode is an abstraction that represents a vertex in the graph and is bound to a device node. You can use libdevinfo(3LIB) interfaces to access properties of an lnode, such as the name and device number of the node.

The edges in the graph are represented by a link. A link has a source lnode that represents the device consumer. A link also has a target lnode that represents the target device.

The following describes the libdevinfo(3LIB) device layering information interfaces:

DINFOLYR: Snapshot flag that enables you to capture device layering information.
di_link_t: A directed link between two endpoints. Each endpoint is a di_lnode_t. An opaque structure.
di_lnode_t: The endpoint of a link. An opaque structure. A di_lnode_t is bound to a di_node_t.
di_node_t: Represents a device node. An opaque structure. A di_node_t is not necessarily bound to a di_lnode_t.
di_walk_link(3DEVINFO): Walk all links in the snapshot.
di_walk_lnode(3DEVINFO): Walk all lnodes in the snapshot.
di_link_next_by_node(3DEVINFO): Get a handle to the next link where the specified di_node_t node is either the source or the target.
di_link_next_by_lnode(3DEVINFO): Get a handle to the next link where the specified di_lnode_t lnode is either the source or the target.
di_link_to_lnode(3DEVINFO): Get the lnode that corresponds to the specified endpoint of a di_link_t link.
di_link_spectype(3DEVINFO): Get the link spectype. The spectype indicates how the target device is being accessed. The target device is represented by the target lnode.
di_lnode_next(3DEVINFO): Get a handle to the next occurrence of the specified di_lnode_t lnode associated with the specified di_node_t device node.
di_lnode_name(3DEVINFO): Get the name that is associated with the specified lnode.
di_lnode_devinfo(3DEVINFO): Get a handle to the device node that is associated with the specified lnode.
di_lnode_devt(3DEVINFO): Get the device number of the device node that is associated with the specified lnode.

The device layering information returned by the LDI can be quite complex. Therefore, the LDI provides interfaces to help you traverse the device tree and the device usage graph. These interfaces enable the consumer of a device tree snapshot to associate custom data pointers with different structures within the snapshot. For example, as an application traverses lnodes, the application can update the custom pointer associated with each lnode to mark which lnodes already have been seen.

The following describes the libdevinfo(3LIB) node and link marking interfaces:

di_lnode_private_set(3DEVINFO): Associate the specified data with the specified lnode. This association enables you to traverse lnodes in the snapshot.
di_lnode_private_get(3DEVINFO): Retrieve a pointer to data that was associated with an lnode through a call to di_lnode_private_set(3DEVINFO).
di_link_private_set(3DEVINFO): Associate the specified data with the specified link. This association enables you to traverse links in the snapshot.
di_link_private_get(3DEVINFO): Retrieve a pointer to data that was associated with a link through a call to di_link_private_set(3DEVINFO).

Print System Configuration Command Interfaces

The prtconf(1M) command is enhanced to display kernel device usage information. The default prtconf(1M) output is not changed. Device usage information is displayed when you specify the verbose option (-v) with the prtconf(1M) command. Usage information about a particular device is displayed when you specify a path to that device on the prtconf(1M) command line.

prtconf -v: Display device minor node and device usage information. Show kernel consumers and the minor nodes each kernel consumer currently has open.
prtconf path: Display device usage information for the device specified by path.
prtconf -a path: Display device usage information for the device specified by path and all device nodes that are ancestors of path.
prtconf -c path: Display device usage information for the device specified by path and all device nodes that are children of path.

Example 14-6 Device Usage Information

When you want usage information about a particular device, the value of the path parameter can be any valid device path.

% prtconf /dev/cfg/c0
SUNW,isptwo, instance #0

Example 14-7 Ancestor Node Usage Information

To display usage information about a particular device and all device nodes that are ancestors of that particular device, specify the -a flag with the prtconf(1M) command. Ancestors include all nodes up to the root of the device tree. If you specify the -a flag with the prtconf(1M) command, then you must also specify a device path name.

% prtconf -a /dev/cfg/c0
SUNW,Sun-Fire
    ssm, instance #0
        pci, instance #0
            pci, instance #0
                SUNW,isptwo, instance #0

Example 14-8 Child Node Usage Information

To display usage information about a particular device and all device nodes that are children of that particular device, specify the -c flag with the prtconf(1M) command. If you specify the -c flag with the prtconf(1M) command, then you must also specify a device path name.

% prtconf -c /dev/cfg/c0
SUNW,isptwo, instance #0
    sd (driver not attached)
    st (driver not attached)
    sd, instance #1
    sd, instance #0
    sd, instance #6
    st, instance #1 (driver not attached)
    st, instance #0 (driver not attached)
    st, instance #2 (driver not attached)
    st, instance #3 (driver not attached)
    st, instance #4 (driver not attached)
    st, instance #5 (driver not attached)
    st, instance #6 (driver not attached)
    ses, instance #0 (driver not attached)
    ...

Example 14-9 Layering and Device Minor Node Information – Keyboard

To display device layering and device minor node information about a particular device, specify the -v flag with the prtconf(1M) command.

% prtconf -v /dev/kbd
conskbd, instance #0
    System properties:
        ...
    Device Layered Over:
        mod=kb8042 dev=(101,0)
            dev_path=/isa/i8042@1,60/keyboard@0
    Device Minor Nodes:
        dev=(103,0)
            dev_path=/pseudo/conskbd@0:kbd
                spectype=chr type=minor
                dev_link=/dev/kbd
        dev=(103,1)
            dev_path=/pseudo/conskbd@0:conskbd
                spectype=chr type=internal
            Device Minor Layered Under:
                mod=wc accesstype=chr
                    dev_path=/pseudo/wc@0

This example shows that the /dev/kbd device is layered on top of the hardware keyboard device (/isa/i8042@1,60/keyboard@0). This example also shows that the /dev/kbd device has two device minor nodes. The first minor node has a /dev link that can be used to access the node. The second minor node is an internal node that is not accessible through the file system. The second minor node has been opened by the wc driver, which is the workstation console. Compare the output from this example to the output from Example 14-12.

Example 14-10 Layering and Device Minor Node Information – Network Device

This example shows which devices are using the currently plumbed network device.

% prtconf -v /dev/iprb0
pci1028,145, instance #0
    Hardware properties:
        ...
    Interrupt Specifications:
        ...
    Device Minor Nodes:
        dev=(27,1)
            dev_path=/pci@0,0/pci8086,244e@1e/pci1028,145@c:iprb0
                spectype=chr type=minor
                alias=/dev/iprb0
        dev=(27,4098)
            dev_path=<clone>
            Device Minor Layered Under:
                mod=udp6 accesstype=chr
                    dev_path=/pseudo/udp6@0
        dev=(27,4097)
            dev_path=<clone>
            Device Minor Layered Under:
                mod=udp accesstype=chr
                    dev_path=/pseudo/udp@0
        dev=(27,4096)
            dev_path=<clone>
            Device Minor Layered Under:
                mod=udp accesstype=chr
                    dev_path=/pseudo/udp@0

This example shows that the iprb0 device has been linked under udp and udp6. Notice that no paths are shown to the minor nodes that udp and udp6 are using. No paths are shown in this case because the minor nodes were created through clone opens of the iprb driver, and therefore there are no file system paths by which these nodes can be accessed. Compare the output from this example to the output from Example 14-11.

Device User Command Interfaces

The fuser(1M) command is enhanced to display device usage information. The fuser(1M) command displays device usage information only if path represents a device minor node. The -d flag is valid for the fuser(1M) command only if you specify a path that represents a device minor node.

fuser path: Display information about application device consumers and kernel device consumers if path represents a device minor node.
fuser -d path: Display all users of the underlying device that is associated with the device minor node represented by path.

Kernel device consumers are reported in one of the following four formats. Kernel device consumers always are surrounded by square brackets ([]).

        [kernel_module_name]
        [kernel_module_name,dev_path=path]
        [kernel_module_name,dev=(major,minor)]
        [kernel_module_name,dev=(major,minor),dev_path=path]

When the fuser(1M) command displays file or device users, the output consists of a process ID on stdout followed by a character on stderr. The character on stderr describes how the file or device is being used. All kernel consumer information is displayed to stderr. No kernel consumer information is displayed to stdout.

If you do not use the -d flag, then the fuser(1M) command reports consumers of only the device minor node that is specified by path. If you use the -d flag, then the fuser(1M) command reports consumers of the device node that underlies the minor node specified by path. The following example illustrates the difference in report output in these two cases.

Example 14-11 Consumers of Underlying Device Nodes

Most network devices clone their minor node when the device is opened. If you request device usage information for the clone minor node, the usage information might show that no process is using the device. If instead you request device usage information for the underlying device node, the usage information might show that a process is using the device. In this example, no device consumers are reported when only a device path is passed to the fuser(1M) command. When the -d flag is used, the output shows that the device is being accessed by udp and udp6.

% fuser /dev/iprb0
/dev/iprb0:
% fuser -d /dev/iprb0
/dev/iprb0:  [udp,dev_path=/pseudo/udp@0] [udp6,dev_path=/pseudo/udp6@0]

Compare the output from this example to the output from Example 14-10.

Example 14-12 Consumer of the Keyboard Device

In this example, a kernel consumer is accessing /dev/kbd. The kernel consumer that is accessing the /dev/kbd device is the workstation console driver.

% fuser -d /dev/kbd
/dev/kbd:  [genunix] [wc,dev_path=/pseudo/wc@0]

Compare the output from this example to the output from Example 14-9.