device_desc(D4X)device_desc(D4X)NAMEdevice_desc - concepts and use of device descriptors
DESCRIPTION
An administrator may choose to explicitly control certain behaviors of an
instance of a device, or information associated with that device. For
example, an administrator may explicitly select an interrupt target (a
CPU) for a particular instance of a PCI device. The administrator
specifies such information via DEVICE_ADMIN directives in a configuration
file as documented in system(4).
If a device driver doesn't do anything at all with device descriptors,
the I/O infrastructure automatically adheres to all relevant information
specified by the administrator. For example, when connecting an
interrupt, if the device driver does not explicitly specify an interrupt
target, then the I/O infrastructure searches for default interrupt target
information in the device descriptor associated with the device being
connected. If no per-device information exists, the I/O infrastructure
uses system-wide defaults. So device drivers generally have no need to
manage device descriptors.
A device driver may decide to manage device descriptors explicitly either
by overriding the administratively-specified default for an invocation of
an I/O interface, or by permanently altering the device's default
behavior. These actions are done by calling kernel functions whose
syntax is documented in device_desc_ops(D3X).
Retrieving Default Device Descriptor Information
In order to examine the default administratively-supplied information
associated with a device (if any), first retrieve a handle for the
default device descriptor using device_desc_default_get(). If the
returned handle is not NULL, use one of the device_desc_*_get() functions
to extract the item.
Using Default Device Descriptor Information
In order to use whatever information the administrator has supplied for a
device when invoking the I/O infrastructure interface, simply pass NULL
for the device_desc parameter of an infrastructure call. For example, to
use the interrupt target specified by the administrator (or system
defaults, if none specified), when allocating an interrupt for a PCI
device, use:
pciio_intr_alloc(mydev, NULL, PCIIO_INTR_LINE_A, mydev);
This function is documented in pciio_intr(D3).
Overriding Default Device Descriptor Information
In order to override an administratively-defined default in a function
that takes a device_desc parameter, first create a copy of the default
device_desc using device_desc_dup(). Then use one of the
device_desc_*_set() functions to set the overriding items. Pass the
modified copy device descriptor to the I/O interface. For example, to
Page 1
device_desc(D4X)device_desc(D4X)
override the administratively-defined interrupt target when allocating an
interrupt for a PCI device "mydev":
new_desc = device_desc_dup(mydev);
device_desc_intr_target_set(new_desc, target);
pciio_intr_alloc(mydev, new_desc, PCIIO_INTR_LINE_A, mydev);
Modifying Default Device Descriptor Information
In order to modify a default behavior for a device, first get the handle
of the default descriptor using device_desc_default_get(). If the
returned handle is not NULL, update the field of interest using one of
the device_desc_*_set() functions. Note: This should be a very
uncommon operation.
Eliminating Default Device Descriptor Information
In order to eliminate a default behavior for the device (and just use the
system default), call device_desc_default_set(dev,NULL); Note: This
should be a very uncommon operation.
Usage
In order to use any of the device_desc interfaces, a driver should
include these header files in this order:
#include <sys/types.h>
#include <sys/iobus.h>
Types
A device_desc_t is a pointer to an opaque descriptor that holds
administratively-defined defaults for devices. It is accessed only
through the interfaces provided. Currently, there are very few items of
general interest in the device descriptor. More may be added in future
releases.
SEE ALSOsystem(4), device_desc_ops(D3X), pciio(D3), pciio_intr(D3), IRIX Device
Driver Programmer's Guide.
Page 2
