Jump to content

Adapter Device Driver Interface Questions and Answers: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
Line 2: Line 2:
{{IBM-Reprint}}
{{IBM-Reprint}}


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.  
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===
==Scatter/Gather Lists==
;Question:
;Question:Is there a limit on the length of an individual scatter/gather element?
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.


;Answer:
;Question:Is there a limit on the number of elements in a scatter/gather list?
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.
;Answer:No.


;Question:
;Question:What is the meaning of the field:
Is there a limit on the number of elements in a scatter/gather list?
::<tt>AdapterInfo->UnitInfo->MaxHWSGList</tt>
;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.


;Answer:
;Question:What about s/g lists associated with CDB PassThru commands?
No.
;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:
;Question:What is the meaning of the field:
What is the meaning of the field:
::<tt>AdapterInfo->UnitInfo->MaxCDBXferLen</tt>
AdapterInfo->UnitInfo->MaxHWSGList
;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.


;Answer:
;Question:My adapter requires a s/g list format different from the one provided. Do I need to allocate storage for separate lists?
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.
;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.


;Question:
==Adapter Device Driver Functionality==
What about s/g lists associated with CDB PassThru commands?
;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.


;Answer:
;Question:Some commands do not appear to be used by the current OS/2 2.0 device managers. Must I implement these commands?
adapter device drivers are not required to iterate commands through the CDB PassThru mechanism.
;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.


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 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:
;Question:SCSI defines different command formats for different device types. Do I need to support all the different CDB formats?
What is the meaning of the field:
;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.
AdapterInfo->UnitInfo->MaxCDBXferLen


;Answer:
;Question:Do I need to support the IORB_CHAIN RequestControl flag on every IORB command type?
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.
;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.


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: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:
;Question:What kind of error recovery is an adapter device driver required to perform?
My adapter requires a s/g list format different from the one provided. Do I need to allocate storage for separate lists?
;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.


;Answer:
;Question:Must the adapter device driver retry commands that were disrupted due to an adapter reset for a hang condition?
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.
;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.


===Adapter Device Driver Functionality===
;Question:Does the adapter device driver have to report media removal with an error code to the device manager?
;Question:
;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.
Do I need to support every command in this specification?
:If the unit does not support media removal, the adapter device driver should retry the operation.


;Answer:
;Question:Must my adapter device driver perform SCSI sense code->IOERR_* translation?
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.
;Answer:Yes. The OS/2 DASD device manager expects a uniform set of error codes and will not examine SCSI sense codes.


Where possible, mandatory commands for particular device types are indicated.
;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.
;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.


[[Category:Storage Device Driver Reference]]
[[Category:Storage Device Driver Reference]]

Latest revision as of 23:09, 1 February 2020

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 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.
Retrieved from "https://www.edm2.com/index.php?title=Adapter_Device_Driver_Interface_Questions_and_Answers&oldid=70193"