PDDREF:Physical Device Driver Strategy Commands: Difference between revisions

Revision as of 01:52, 24 August 2018

Physical Device Driver Reference
Introduction Physical Device Driver Overview Physical Device Driver Architecture and Structure OS/2 Physical Device Driver Operations OS/2 Physical Device Driver Design Issues Character Device Monitors Installation of External Loadable Device Drivers Physical Device Driver Strategy Commands Device Helper (DevHlp) Services Resource Management Linking Resource Manager Services Generic IOCtl Commands Appendixes OS/2 Version Compatibility Considerations Running OS/2 Version 1.3 16-Bit PDDs on OS/2 Using Advanced Bios Notices Glossary

The physical device driver strategy routine is called with ES:BX pointing to the request packet.

Request Packets

The operating system does not guarantee that the order of API requests issued by multiple threads will be preserved in the order that the corresponding request packets arrive at the physical device driver. Multiple application threads, or threads created due to DosReadAsync and DosWriteAsync, can get blocked in the operating system. This allows a physical device driver request packet (for an API request by a subsequent thread that does not get blocked) to arrive out of order. If a device driver supports multiple outstanding requests, it is responsible for providing a synchronization mechanism between itself and application processes. Also, request packet ordering must be preserved.

A request packet consists of two parts, the request header and the command-specific data field. The structure of the request packet is detailed below:

Field	Length
Length of Request Packet	BYTE
Block Device Unit Code	BYTE
Command Code	BYTE
Request Packet Status	WORD
Reserved	DWORD
Queue Linkage	DWORD
Command-Specific Data	BYTES

Length of Request Packet: Set to the total length, in bytes, of the request packet (the length of the request header, plus the length of the command-specific data).
Block Device Unit Code: Identifies the unit for which the request is intended. This field has no meaning for character devices.
Command Code: Indicates the requested device driver function. The physical device driver command codes are summarized in Summary of Strategy Commands.
Request Packet Status: Defined only for OPEN and CLOSE request packets on entry to the strategy routine. For all other request packets, the Status field is undefined on entry. For an OPEN request packet, bit 3 (08h) of the Status field is set if the packet was generated from a DosMonOpen; otherwise, it is a DosOpen.; For a CLOSE request packet, bit 3 (08h) of the Status field is set if the packet was generated by a DosMonClose, or by a DosClose of a handle that was generated by a DosMonOpen. In this way, monitor handles generated and left open when a process exits are closed properly. Otherwise, it was generated by a DosClose on a nonmonitor handle.; On exit from the strategy routine, the Status field describes the resulting state of the request, as shown in the following table.

Bits           Description
 
15             Error
14             Driver Defined Error
13-10          Reserved
9              Busy
8              Done
7-0            ERROR CODE (bit 15 on)

Bit 15: The error bit. If this bit is set, the low 8 bits of the status WORD (7-0) indicate the error code, which is processed by the operating system in one of the following ways:

If the IOCtl category is User Defined (refer to the Category Code under Generic IOCtl Commands), FF00H is ORed with the byte-wide error code.
If not User Defined and bit 14 (device driver defined error code) is set, FE00H is ORed with the byte-wide error code.
Otherwise, the error code must be one of those shown in the Status Field Error Code table, and is mapped into one of the standard OS/2 API return codes.

Bit 14: A device driver-defined error, if set in conjunction with bit 15.
Bits 13-10: Reserved.
Bit 9: The busy bit. It is set only by Status and Removable Media. See 6h, Ah and Fh for more information.
Bit 8: The done bit. MUST be set, even when bit 15 (the error bit) is set. That is, whenever you return with the error bit set, you must also set the done bit. The physical device driver sets the done bit to 1 when exiting or calls DevHlp_DevDone when the request is complete.
Bits 7-0: The low 8 bits of the status WORD. If bit 15 is set, bits 7-0 contain the error code.

Error Codes    Description

  00h          Write Protect Violation
  01h          Unknown Unit
  02h          Device Not Ready
  03h          Unknown Command
  04h          CRC Error
  05h          Bad Drive Request Structure Length
  06h          Seek Error
  07h          Unknown Media
  08h          Sector Not Found
  09h          Printer Out of Paper
  0Ah          Write Fault
  0Bh          Read Fault
  0Ch          General Failure
  0Dh          Change Disk (logical switch)
  0Eh          Reserved
  0Fh          Reserved
  10h          Uncertain Media
  11h          Character I/O Call Interrupted
  12h          Monitors Not Supported
  13h          Invalid Parameter
  14h          Device Already in Use
  15h          Initialization Failed (non-critical)

Uncertain Media (10h): Returned when the state of the media in the drive is uncertain. This response should not be returned to the INIT command. For hard disks, the physical device driver must begin in a media-uncertain state in order to have the media correctly labelled. In general, the following guidelines can be used to determine when to respond with uncertain media:

When a drive-not-ready condition is detected. In this case, return uncertain media to all subsequent commands until a reset media command is received.
When accessing removable media without change-line support, and a time delay of two or more seconds has occurred.
When the state of the change-line indicates that the media might have changed.

Character I/O Call Interrupted (11h): Returned when the thread performing the I/O was interrupted out of a DevHlp_Block, before completing the requested operation.
Monitors Not Supported (12h): Returned for monitor commands (monitor open/close, register IOCtl), if monitors are not supported by the physical device driver.
Invalid Parameter (13h): Returned when one or more fields of the request packet contain invalid values.

Initialization Failed (noncritical) (15h) Returned when the device driver initialization fails, but a message does not appear indicating a failure.

Queue Linkage: Provided to maintain a linked list of request packets. The device driver can use the request queue management DevHlp services, or it can use its own queue management.
Command-Specific Data: The parameters required for the physical device driver command. The commands and actual formats of the corresponding request packets are discussed in the following sections.

Summary of Strategy Commands

The following table lists the physical device driver strategy commands:

³Code    ³Function                                ³Block   ³Char    ³

³ 0h     ³INIT (See 0h.)                          ³  X     ³ X      ³
³ 1h     ³MEDIA CHECK (See 1h.)                   ³  X     ³        ³
³ 2h     ³BUILD BPB (See 2h.)                     ³  X     ³        ³
³ 3h     ³Reserved                                ³        ³        ³
³ 4h     ³READ (input) (See 4h, 8h, 9h.)          ³  X     ³ X      ³
³ 5h     ³NONDESTRUCTIVE READ NO WAIT (See 5h.)   ³        ³ X      ³
³ 6h     ³INPUT STATUS (See 6h, Ah.)              ³        ³ X      ³
³ 7h     ³INPUT FLUSH (See 7h, Bh.)               ³        ³ X      ³
³ 8h     ³WRITE (output) (See 4h, 8h, 9h.)        ³  X     ³ X      ³
³ 9h     ³WRITE WITH VERIFY (See 4h, 8h, 9h.)     ³  X     ³ X      ³
³ Ah     ³OUTPUT STATUS (See 6h, Ah.)             ³        ³ X      ³
³ Bh     ³OUTPUT FLUSH (See 7h, Bh.)              ³        ³ X      ³
³ Ch     ³Reserved                                ³        ³        ³
³ Dh     ³OPEN DEVICE (See Dh, Eh.)               ³  X     ³ X      ³
³ Eh     ³CLOSE DEVICE (See Dh, Eh.)              ³  X     ³ X      ³
³ Fh     ³REMOVABLE MEDIA (See Fh.)               ³  X     ³        ³
³10h     ³GENERIC IOCtl (See 10h.)                ³  X     ³ X      ³
³11h     ³RESET MEDIA (See 11h.)                  ³  X     ³        ³
³12h     ³GET LOGICAL DRIVE MAP (See 12h, 13h.)   ³  X     ³        ³
³13h     ³SET LOGICAL DRIVE MAP (See 12h, 13h.)   ³  X     ³        ³
³14h     ³DEINSTALL (See 14h.)                    ³        ³ X      ³
³15h     ³Reserved                                ³        ³        ³
³16h     ³PARTITIONABLE HARD DISKS (See 16h.)     ³  X     ³        ³
³17h     ³GET HARD DISK/LOGICAL UNIT MAP          ³  X     ³        ³
³        ³(See 17h.)                              ³        ³        ³
³18h     ³Reserved                                ³        ³        ³
³19h     ³Reserved                                ³        ³        ³
³1Ah     ³Reserved                                ³        ³        ³
³1Bh     ³Reserved                                ³        ³        ³
³1Ch     ³SHUTDOWN (See 1Ch.)                     ³  X     ³ X      ³
³1Dh     ³GET DRIVER CAPABILITIES (See 1Dh.)      ³  X     ³        ³
³1Eh     ³Reserved                                ³        ³        ³
³1Fh     ³INITIALIZATION COMPLETE (See 1Fh.)      ³        ³ X      ³

Note: All DWORD pointers are stored with offset first, then segment.

       INIT - 0h
       MEDIA CHECK - 1h
       BUILD BIOS PARAMETER BLOCK (BPB) - 2h
       READ/WRITE/WRITE WITH VERIFY - 4h, 8h, 9h
       NONDESTRUCTIVE READ NO WAIT - 5h
       INPUT OR OUTPUT STATUS - 6h, Ah
       FLUSH INPUT OR OUTPUT - 7h, Bh
       OPEN OR CLOSE DEVICE - Dh, Eh
       REMOVABLE MEDIA - Fh
       GENERIC IOCtl - 10h
       RESET MEDIA - 11h
       GET OR SET LOGICAL DRIVE MAP - 12h, 13h
       DEINSTALL - 14h
       PARTITIONABLE HARD DISKS - 16h
       GET HARD DISK/LOGICAL UNIT MAP - 17h
       BASEDEVINIT - 1bh
       SHUTDOWN - 1Ch
       GET DRIVER CAPABILITIES - 1Dh
       INITIALIZATION COMPLETE - 1Fh