device_desc(D4X)

NAME
     device_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
     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 ALSO
     system(4), device_desc_ops(D3X), pciio(D3), pciio_intr(D3), IRIX Device
     Driver Programmer's Guide.