Part I Designing Device Drivers for the Solaris Platform
1. Overview of Solaris Device Drivers
2. Solaris Kernel and Device Tree
5. Managing Events and Queueing Tasks
Data Structures Required for Drivers
Device Instances and Instance Numbers
Lock Variable and Conditional Variable Initialization
7. Device Access: Programmed I/O
10. Mapping Device and Kernel Memory
14. Layered Driver Interface (LDI)
Part II Designing Specific Kinds of Device Drivers
15. Drivers for Character Devices
18. SCSI Host Bus Adapter Drivers
19. Drivers for Network Devices
Part III Building a Device Driver
21. Compiling, Loading, Packaging, and Testing Drivers
22. Debugging, Testing, and Tuning Device Drivers
23. Recommended Coding Practices
B. Summary of Solaris DDI/DKI Services
C. Making a Device Driver 64-Bit Ready
The Solaris DDI interfaces enable drivers to provide the device ID, a persistent unique identifier for a device. The device ID can be used to identify or locate a device. The device ID is independent of the /devices name or device number (dev_t). Applications can use the functions defined in libdevid(3LIB) to read and manipulate the device IDs registered by the drivers.
Before a driver can export a device ID, the driver needs to verify the device is capable of either providing a unique ID or of storing a host-generated unique ID in a not normally accessible area. WWN (world-wide number) is an example of a unique ID that is provided by the device. Device NVRAM and reserved sectors are examples of non-accessible areas where host-generated unique IDs can be safely stored.
Drivers typically initialize and register device IDs in the driver's attach(9E) handler. As mentioned above, the driver is responsible for registering a device ID that is persistent. As such, the driver might be required to handle both devices that can provide a unique ID directly (WWN) and devices where fabricated IDs are written to and read from stable storage.
If the device can supply the driver with an identifier that is unique, the driver can simply initialize the device ID with this identifier and register the ID with the Solaris DDI.
/* * The device provides a guaranteed unique identifier, * in this case a SCSI3-WWN. The WWN for the device has been * stored in the device's soft state. */ if (ddi_devid_init(dip, DEVID_SCSI3_WWN, un->un_wwn_len, un->un_wwn, &un->un_devid) != DDI_SUCCESS) return (DDI_FAILURE); (void) ddi_devid_register(dip, un->un_devid);
A driver might also register device IDs for devices that do not directly supply a unique ID. Registering these IDs requires the device to be capable of storing and retrieving a small amount of data in a reserved area. The driver can then create a fabricated device ID and write it to the reserved area.
/* * the device doesn't supply a unique ID, attempt to read * a fabricated ID from the device's reserved data. */ if (xxx_read_deviceid(un, &devid_buf) == XXX_OK) { if (ddi_devid_valid(devid_buf) == DDI_SUCCESS) { devid_sz = ddi_devi_sizeof(devid_buf); un->un_devid = kmem_alloc(devid_sz, KM_SLEEP); bcopy(devid_buf, un->un_devid, devid_sz); ddi_devid_register(dip, un->un_devid); return (XXX_OK); } } /* * we failed to read a valid device ID from the device * fabricate an ID, store it on the device, and register * it with the DDI */ if (ddi_devid_init(dip, DEVID_FAB, 0, NULL, &un->un_devid) == DDI_FAILURE) { return (XXX_FAILURE); } if (xxx_write_deviceid(un) != XXX_OK) { ddi_devid_free(un->un_devid); un->un_devid = NULL; return (XXX_FAILURE); } ddi_devid_register(dip, un->un_devid); return (XXX_OK);
Drivers typically unregister and free any device IDs that are allocated as part of the detach(9E) handling. The driver first calls ddi_devid_unregister(9F) to unregister the device ID for the device instance. The driver must then free the device ID handle itself by calling ddi_devid_free(9F), and then passing the handle that had been returned by ddi_devid_init(9F). The driver is responsible for managing any space allocated for WWN or Serial Number data.