Kernel Extensions and Device Support Programming Concepts

Device Dependent Structure (DDS) Overview

A device dependent structure (DDS) contains information that describes a device instance to the device driver. It typically contains information about device-dependent attributes as well as other information the driver needs to communicate with the device. In many cases, information about a device's parent is included. (For instance, a driver needs information about the adapter and the bus the adapter is plugged into to communicate with a device connected to an adapter.)

A device's DDS is built each time the device is configured. The Configure method can fill in the DDS with fixed values, computed values, and information from the Configuration database. Most of the information from the Configuration database usually comes from the attributes for the device in the Customized Attribute (CuAt) object class, but can come from any of the object classes. Information from the database for the device's parent device or parent's parent device can also be included. The DDS is passed to the device driver with the SYS_CFGDD flag of the sysconfig subroutine, which calls the device driver's ddconfig subroutine with the CFG_INIT command.

How the Change Method Updates the DDS

The Change method is invoked when changing the configuration of a device. The Change method must ensure consistency between the Configuration database and the view that any device driver might have of the device. This is accomplished by:

Not allowing the configuration to be changed if the device has configured children; that is, children in either the Available or Stopped states. This ensures that a DDS built using information in the database about a parent device remains valid because the parent cannot be changed.
If a device has a device driver and the device is in either the Available or Stopped state, the Change method must communicate to the device driver any changes that would affect the DDS. This can be accomplished with ioctl operations, if the device driver provides the support to do so. It can also be accomplished by taking the following steps:
1. Terminating the device instance by calling the sysconfig subroutine with the SYS_CFGDD operation. This operation calls the device driver's ddconfig subroutine with the CFG_TERM command.
2. Rebuilding the DDS using the changed information.
3. Passing the new DDS to the device driver by calling the sysconfig subroutine SYS_CFGDD operation. This operation then calls the ddconfig subroutine with the CFG_INIT command.

Many Change methods simply invoke the device's Unconfigure method, apply changes to the database, and then invoke the device's Configure method. This process ensures the two stipulated conditions since the Unconfigure method, and thus the change, will fail, if the device has Available or Stopped children. Also, if the device has a device driver, its Unconfigure method terminates the device instance. Its Configure method also rebuilds the DDS and passes it to the driver.

Guidelines for DDS Structure

There is no single defined DDS format. Writers of device drivers and device methods must agree upon a particular device's DDS format. When obtaining information about a parent device, you might want to group that information together in the DDS.

When building a DDS for a device connected to an adapter card, you will typically need the following adapter information:

slot number	Obtained from the connwhere descriptor of the adapter's Customized Device (CuDv) object.
bus resources	Obtained from attributes for the adapter in the Customized Attribute (CuAt) or Predefined Attribute (PdAt) object classes. These include attributes for bus interrupt levels, interrupt priorities, bus memory addresses, bus I/O addresses, and DMA arbitration levels.

The following attribute must be obtained for the adapter's parent bus device:

bus_id

Identifies the I/O bus. This field is needed by the device driver to access the I/O bus.

Note

The getattr device configuration subroutine should be used whenever attributes are obtained from the Configuration database. This subroutine returns the Customized attribute value if the attribute is represented in the Customized Attribute object class. Otherwise, it returns the default value from the Predefined Attribute object class.

Finally, a DDS generally includes the device's logical name. This is used by the device driver to identify the device when logging an error for the device.

Example of DDS

The following example provides a guide for using DDS format.

/* Device DDS */
struct device_dds {
     /* Bus information */
     ulong  bus_id;         /* I/O bus id                      */
     ushort us_type;        /* Bus type, i.e. BUS_MICRO_CHANNEL*/
     /* Adapter information */
     int   slot_num;         /* Slot number                    */
     ulong io_addr_base;     /* Base bus i/o address           */
     int   bus_intr_lvl;     /* bus interrupt level            */
     int   intr_priority;    /* System interrupt priority      */
     int   dma_lvl;          /* DMA arbitration level          */
     /* Device specific information */
     int   block_size;        /* Size of block in bytes        */
     int   abc_attr;          /* The abc attribute             */
     int   xyz_attr;          /* The xyz attribute             */
     char  resource_name[16]; /* Device logical name           */
};