Adapter Device Driver Interface Questions and Answers
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
This appendix covers the most commonly asked questions about adapter device driver interfaces, including discussion of scatter/gather lists and functionality. The answers are presented in detail.
Scatter/Gather Lists
- Question
Is there a limit on the length of an individual scatter/gather element?
- Answer
No. We are aware that some SCSI PIO drivers have a 64KB limitation on scatter/gather elements. At present, OS/2 2.0 appears to remain within this limitation. However, it is recommended that this restriction be lifted because there is no guarantee that adapter device drivers with such a limitation will be compatible with future OS/2 operating system releases.
- Question
Is there a limit on the number of elements in a scatter/gather list?
- Answer
No.
- Question
What is the meaning of the field:
AdapterInfo->UnitInfo->MaxHWSGList
- Answer
This is the maximum number of scatter/gather list entries your adapter hardware can handle. The OS/2 operating system will ensure that the adapter device driver is not required to split a sector across a MaxHWSGList boundary. However, the adapter device driver is responsible for iterating an I/O command because of limitations in its s/g support.
- Question
What about s/g lists associated with CDB PassThru commands?
- Answer
adapter device drivers are not required to iterate commands through the CDB PassThru mechanism.
Commands received from SCSI.SYS device class drivers will require a minimum of 16 s/g elements. At present, the number of s/g elements required by device modules written to ASPI interfaces is not known. If the OS2SCSI or OS2ASPI device managers receive an s/g list that does not conform to the adapter device driver's s/g requirement, these device managers will reject the request.
- Question
What is the meaning of the field:
AdapterInfo->UnitInfo->MaxCDBXferLen
- Answer
This field is not the maximum CDB length. The purpose of this field relates to the limitations on s/g list lengths and their effect on PassThru commands.
For adapter device drivers written for adapters that have severe s/g list limitations or unusual s/g address limitations, the adapter device driver might emulate s/g functionality using an I/O buffer. In this case, the adapter device driver would inform the OS2SCSI or OS2ASPI device managers of the length of its emulation buffer by way of the above field. It is up to the adapter device driver to perform this emulation.
- Question
My adapter requires an s/g list format different from the one provided. Do I need to allocate storage for separate lists?
- Answer
No. Provided that your transformations are reversible, you can reformat the passed s/g list to what your adapter can accept. You must reverse the reformatting prior to performing your notification call out.
Adapter Device Driver Functionality
- Question
Do I need to support every command in this specification?
- Answer
No. For specific device types, some commands are mandatory and others are optional. For example, there are several commands that apply only to floppy controllers. We must support these commands due to the unusual characteristics of diskette media.
Where possible, mandatory commands for particular device types are indicated.
- Question
Some commands do not appear to be used by the current OS/2 2.0 device managers. Must I implement these commands?
- Answer
Yes. To preclude compatibility problems with future releases of OS/2, you should follow this specification as closely as possible with respect to mandatory commands.
- Question
What happens if IBM-supplied sample code differs in some way from this specification?
- Answer
This specification takes precedence over IBM-supplied samples. Obtain clarification from IBM if you have questions on a particular code sample.
- Question
SCSI defines different command formats for different device types. Do I need to support all the different CDB formats?
- Answer
No. You must support the DASD type formats only. The remainder of the device types will be supported by way of CDB PassThru; that is, the adapter device driver will be supplied with an appropriate CDB.
- Question
Do I need to support the IORB_CHAIN RequestControl flag on every IORB command type?
- Answer
No. The chain flag is used only on IOCC_EXECUTE_IO commands. In addition, all IORBs contained in the chained request will reference the same UnitHandle.
- Question
Do I need to support any unusual SCSI commands?
- Answer
No. We expect most DASD devices to conform to CCS. Regarding SCSI Write/ Verify, adapter device driver writers are encouraged to emulate this command for drives that do not provide this function directly. Suppliers of devices that have unusual command requirements are expected to provide filter device drivers.
- Question
What kind of error recovery is an adapter device driver required to perform?
- Answer
Adapter device drivers are responsible for error recovery. An error reported to the layers above the adapter device driver is considered not recoverable. In general, SCSI devices retry at the device level, so the adapter device driver does not need to retry commands that failed at the device. However, the adapter device driver should retry commands that failed due to errors on the SCSI bus during either the command or data transfer phases.
- Question
Must the adapter device driver retry commands that were disrupted due to an adapter reset for a hang condition?
- Answer
Yes, the adapter device driver is responsible for retrying commands disrupted by an adapter device driver-initiated reset of an adapter to clear a hang condition.
- Question
Does the adapter device driver have to report media removal with an error code to the device manager?
- Answer
If the unit supports media removal, the adapter device driver is required to report media removal to the device manager by way of the appropriate IOERR_* code. In addition, the adapter device driver should return the same error code for all work queued for the unit. The adapter device driver should not retry this error. The adapter device driver should treat a power-on condition the same as media removal. The adapter device driver should return the appropriate IOERR_* code for all queued work after a not ready condition.
If the unit does not support media removal, the adapter device driver should retry the operation.
- Question
Must my adapter device driver perform SCSI sense code->IOERR_* translation?
- Answer
Yes. The OS/2 DASD device manager expects a uniform set of error codes and will not examine SCSI sense codes.
- Question
Must my adapter device driver return sense data when requested?
- Answer
Yes. The OS2SCSI and OS2ASPI device mangers need to return this data to their clients.