Managing Device State

The _init(9E) and _fini(9E) entry points and all six new entry points defined in this driver maintain a soft state for the device. Most device drivers maintain state information with each instance of the device they control. An instance usually is a sub-device. For example, a disk driver might communicate with a hardware controller device that has several disk drives attached. See Retrieving Driver Soft State Information in Writing Device Drivers for more information about soft states.

This sample driver allows only one instance. The instance number is assigned in the configuration file. See Example 3–4. Most device drivers allow any number of instances of a device to be created. The system manages the device instance numbers, and the DDI soft state functions manage the instances.

The following flow gives an overview of how DDI soft state functions manage a state pointer and the state of a device instance:

1. The ddi_soft_state_init(9F) function initializes the state pointer. The state pointer is an opaque handle that enables allocation, deallocation, and tracking of a state structure for each instance of a device. The state structure is a user-defined type that maintains data specific to this instance of the device. In this example, the state pointer and state structure are declared after the entry point declarations. See qotd_state_head and qotd_state in Example 3–3.

2. The ddi_soft_state_zalloc(9F) function uses the state pointer and the device instance to create the state structure for this instance.

3. The ddi_get_soft_state(9F) function uses the state pointer and the device instance to retrieve the state structure for this instance of the device.

4. The ddi_soft_state_free(9F) function uses the state pointer and the device instance to free the state structure for this instance.

5. The ddi_soft_state_fini(9F) function uses the state pointer to destroy the state pointer and the state structures for all instances of this device.

The ddi_soft_state_zalloc(9F), ddi_get_soft_state(9F), and ddi_soft_state_free(9F) functions coordinate access to the underlying data structures in a way that is safe for multithreading. No additional locks should be necessary.