Adapter Device Driver Interface Questions and Answers

From EDM2
Jump to: navigation, search
Storage Device Driver Reference
  1. About This Book
  2. Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
  3. Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers
  4. Adapter Device Driver Development Considerations
  5. DASD, SCSI, and CD-ROM Device Manager Interface Specification
  6. Error Handling
  7. Adapter Device Driver Command-Line Parameters
  8. DASD IOCtl Device Driver Test Tool
  9. Optical IOCtl Device Driver Test Tool
  10. Using Filter Device Drivers
  11. Library and Services
  12. CD-ROM Device Manager Interface Specification
  13. CD-ROM Device Driver Test Tool
  14. Building an OS/2 Virtual Disk Driver
  15. OS2DASD.DMD - Technical Reference
  16. Boot Record Architecture
  17. Extended Device Driver Interface Specification
  18. I/O Request Block - C Definitions
  19. OS/2 SCSI Device Driver Interface Specification
  20. Advanced SCSI Programming Interface (ASPI) OS/2 Specification
  21. Adapter Device Driver Interface Questions and Answers
  22. Device Driver Test Tool (DDTT)
  23. Glossary

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.