Adapter Device Driver Interface Questions and Answers
From EDM2
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 a 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 a 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.