PDDREF:Physical Device Driver Strategy Commands
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 (See 17h.) | X | |
| 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.
0h
INIT - This command initializes the physical device driver.
| Field | Length |
|---|---|
| Request Header | 13 BYTES |
| Data_1 | BYTE |
| Pointer_1 | DWORD |
| Pointer_2 | DWORD |
| Data_2 | BYTE |
On entry, the request block contains the following fields as inputs to the physical device driver:
- Pointer_1 Points to the DevHlp entry point
- Pointer_2 Points to the INIT arguments
- Data_2 Drive number for the first block device unit
The arguments for installable device drivers from the DEVICE= line in the CONFIG.SYS file allow the physical device driver to use configurable parameters to initialize itself and its device.
At initialization time, the physical device driver runs as a thread under a protected-mode process at application level with I/O privilege. The device driver can issue certain OS/2 dynamic link function calls at this time. Refer to Physical Device Driver Initialization for more details. On completion of initialization, the physical device driver must set fields in the request packet as described:
| Fields | Output Information for INIT Success |
|---|---|
| Data_1 | Number of logical block devices or units (block devices only) |
| Pointer_1 | WORD offset to end of code segment and WORD offset to end of data segment |
| Pointer_2 | Points to the BIOS Parameter Block (BPB) array for the logical block devices or units (block devices only) |
| Status | Set the status WORD in the request header to 0100h. |
A block device driver must return in Data_1 the number of logical devices or units that are available. The kernel's file system layer assigns sequential drive letters to these units. A character device driver then sets Data_1 to 0.
Both block device drivers and character device drivers must set Pointer_1 with the offsets of the code and data segments. This allows a physical device driver to release code and data needed only by the device driver's initialization routine. First, the initialization code and data must be located at the end of the appropriate segments. Then, as the final step in initialization, the physical device driver sets the offsets to the end of the code segment and the end of the data segment. This also permits a physical device driver to load with a maximum-sized data segment (64KB) and let it release the amount that it does not need.
A block device driver must return an array of BPBs for the logical units that it supports in Pointer_2. A character device driver sets Pointer_2 to 0.
The Status field in the request packet header must be set to indicate no error and done. If the physical device driver determines it cannot set up the device and wants to quit, it must return with the error bit in the request packet Status field set to 1. The physical device driver can also return the following:
| Fields | Output Information for INIT Failure |
|---|---|
| Data_1 | BYTE 00h |
| Pointer_1 | WORD 0000h, and WORD 0000h |
| Status | 810Ch or 8115 |
The Status field in the request packet header must be set to indicate the failure of the INIT request with the general failure error return code. The Status must also indicate that the request is done.
One of the above techniques must be used to return device initialization failures from the physical device driver to the system initialization process. A character device driver that contains multiple device driver headers can fail initialization on a subset of the headers in its header chain.
The system initialization process remembers the last nonzero size code and data segment offsets returned for the devices in the device driver that completed initialization. These last values are used to resize the physical device driver's code and data segments after INIT packets have been sent to the physical device driver for each device in the physical device driver header chain.
When a device in the header chain cannot be initialized, the physical device driver can set the code and data segments to 0, and set the error bit in the request packet Status field to indicate initialization failure for that device. The physical device driver will not receive any future request packets for a specific device if it returns a failure for the INIT request packet for that device.
If none of the devices in the device driver header chain passes initialization, and the device driver returns an error code other than Initialization Failed (noncritical) (15h) for at least one device in the device driver chain, a failure message appears and the physical device driver does not remain loaded.
If at least one of the devices in the device driver header chain passes initialization, a failure message does not appear and the physical device driver remains loaded.
Because the system initialization process maintains the pass/fail return status for each device header in a physical device driver header chain, the physical device driver must not manipulate the linkages of the headers.
- 1h
- MEDIA CHECK - This command determines the state of the media.
- 2h
- BUILD BIOS PARAMETER BLOCK (BPB) - This command is requested when the media has changed or when the media type is uncertain.
- 4h, 8h, 9h
- READ/WRITE/WRITE WITH VERIFY - This command reads from or writes to a device (read from, 4h, write to, 8h, and write with verify, 9h).
- 5h
- NONDESTRUCTIVE READ NO WAIT - This command reads a character from the buffer but does not remove it.
- 6h
- INPUT OR OUTPUT STATUS - 6h, Ah
- 7h
- FLUSH INPUT OR OUTPUT - 7h, Bh
- Dh
- OPEN OR CLOSE DEVICE - Dh, Eh
- Fh
- REMOVABLE MEDIA - Fh
- 10h
- GENERIC IOCtl - 10h
- 11h
- RESET MEDIA - 11h
- 12h
- GET OR SET LOGICAL DRIVE MAP - 12h, 13h
- 14h
- DEINSTALL - 14h
- 16h
- PARTITIONABLE HARD DISKS - 16h
- 17h
- GET HARD DISK/LOGICAL UNIT MAP - 17h
- 1Bh
- BASEDEVINIT - 1bh
- 1Ch
- SHUTDOWN - 1Ch
- 1Dh
- GET DRIVER CAPABILITIES - 1Dh
- 1Fh
- INITIALIZATION COMPLETE - 1Fh