PDDREF:Generic IOCtl Commands

OS/2 device drivers are used to access the I/O hardware. The IOCtl functions provide a method for an application, or subsystem, to send device-specific control commands to a physical device driver. These IOCtls are subfunctions that are issued through the DosDevIOCtl API function request. The DosDevIOCtl function request can be used only by OS/2 applications; the INT 21h IOCtl request can be used only by DOS applications.

The category and function fields are as follows. Each code is contained in a byte: Category       Code 0xxx xxxx      OS/2-defined 1xxx xxxx      User-defined _xxx xxxx      Code.

Function       Code 0xxx xxxx      Return error, if unsupported 1xxx xxxx      Ignore, if unsupported x0xx xxxx      Intercepted by the OS/2 operating system x1xx xxxx      Passed to driver xx0x xxxx      Sends data and commands to device xx1x xxxx      Queries data and information from device ___x xxxx      Subfunction. Notice that the send/query data bit is intended only to standardize the function set; it plays no critical role. Some functions can contain both command and query elements. Such commands are defined as sends data.

Generic IOCtl Example
The DosDevIOCtl function sends the request to the physical device driver request packet. The physical device driver receives the request packet, and looks for the Command Code (Command 16 is the generic IOCtl command) to identify the request. Notice that each device driver can define the structure of the Data Packet and the Parameter Packet, but all device drivers use the same request header.

The 16-bit calling sequence for DosDevIOCtl is shown below:  EXTRN  DosDevIOCtl:Far

PUSH@  OTHER  Data        ; Data Packet address PUSH@  OTHER  ParmList    ; Parameter Packet address PUSH   WORD   Function    ; Function code PUSH   WORD   Category    ; Category code PUSH   WORD   DevHandle   ; User's device driver file handle

CALL   DosDevIOCtl  The 32-bit calling sequence for DosDevIOCtl is shown below:  PUSH@  DWORD  DataLengthInOut   ; Data Length Address PUSH   DWORD  DataLengthMAX     ; Max size of Data Packet PUSH@  OTHER  Data              ; Data Packet Address PUSH@  DWORD  ParmLengthInOut   ; Parm Length Address PUSH   DWORD  ParmLengthMax     ; Max size of Parm List PUSH@  OTHER  ParmList          ; Parameter Packet Address PUSH   DWORD  Function          ; Function Code PUSH   DWORD  Category          ; Category Code PUSH   DWORD  DevHandle         ; User's device driver file handle

Call DOSDevIOCtl  DosDevIOCtl2 performs the same function as DosDevIOCtl, and also provides Length fields for the Data and Parameter List buffers. These Length fields should be passed to the Device Helper service VerifyAccess when the physical device driver is determining whether it has access to the application's Data and Parameter List buffers. The Length fields also tell physical network device drivers the amount of data residing in these buffers for the transfer to other network nodes.

The 16-bit calling sequence for DosDevIOCtl2 is shown below:  EXTRN  DosDevIOCtl2:Far

PUSH@  OTHER  Data        ; Data Packet address PUSH   WORD   DataLength  ; Data Packet length PUSH@  OTHER  ParmList    ; Parameter Packet address PUSH   WORD   ParmLength  ; Parameter Packet length PUSH   WORD   Function    ; Function code PUSH   WORD   Category    ; Category code PUSH   WORD   DevHandle   ; User's device driver file handle

CALL   DosDevIOCtl2 

Generic IOCtl Function Table
The list of categories and functions for the generic IOCtl requests are as follows:

Category 01h ASYNC (RS232-C) Control IOCtl Commands
Whenever an IOCtl command calls for a NULL pointer, it is the responsibility of the application to set one up for the appropriate Parameter or Data Packet pointer before calling the physical device driver. IOCtls can be interpreted differently by future releases if the pointer is not a NULL pointer. If a NULL pointer is called for and it is not received by the device driver, it is considered an invalid Parameter or Data Packet value.

The physical device driver services each communications port (COM1, COM2, and so forth) independently. IOCtls issued to the physical device driver for a given port have no effect on any other communications ports that the physical device driver is servicing. The application cannot assume a given timing relationship between when the IOCtls are executed and when data is received or transmitted by the ASYNC hardware. Data Carrier Detect (DCD) is the same signal as Receiver Line Signal Detect (RLSD).

The following is a summary of the Category 01h IOCtl Commands:

Category 03h Video Control IOCtl Commands
The following is a summary of the Category 03h Video Control IOCtl Commands:  Function Description 70h   Allocate an LDT Selector 71h   Deallocate an LDT Selector 72h   Query Pointer Draw Address 73h   Initialize Call Vector Table 74h   ABIOS Pass-Through 75h   Allocate an LDT Selector with Offset 76h   Allocate an LDT Selector with Background Validation Options 7Eh   Allocate Video Buffer 7Fh   Get Address to ROM Font 

Category 04h Keyboard Control IOCtl Commands
The following is a summary of the Category 04h IOCtl Commands:  Function Description 50h   Set Code Page 51h   Set Input Mode (Default ASCII) 52h   Set Interim Character Flags 53h   Set Shift State 54h   Set Typematic Rate and Delay 55h   Reserved 56h   Set Session Manager Hot Key 57h   Set KCB 58h   Set Code Page Number 59h   Set Read/Peek Notification 5Ah   Alter Keyboard LEDs 5Bh   Reserved 5Ch   Set NLS and Custom Code Page 5Dh   Create a New Logical Keyboard 5Eh   Destroy a Logical Keyboard 71h   Query Input Mode 72h   Query Interim Character Flags 73h   Query Shift State 74h   Read Character Data Records 75h   Peek Character Data Record 76h   Query Session Manager Hot Key 77h   Query Keyboard Type 78h   Query Code Page Number 79h   Translate Scan Code to ASCII 7Ah   Query Keyboard Hardware ID   7Bh    Query Keyboard Code Page Support Information 

Category 05h Parallel Port Control IOCtl Commands
The following is a summary of Category 05h IOCtl Commands:  Function Description 42h   Set Frame Control (CPL, LPI) 43h   Reserved 44h   Set Infinite Retry 45h   Reserved 46h   Initialize Parallel Port 47h   Reserved 48h   Activate Font 49h   Reserved 4Bh   Reserved 4Ch   Reserved 4Dh   Set Print-Job Title 4Eh   Set Parallel Port Write Timeout Value 4Fh   Reserved 50h   Reserved 51h   Reserved 52h   Set Parallel Port Communication Mode 53h   Set Parallel Port Data Transfer Mode 62h   Query Frame Control 63h   Reserved 64h   Query Infinite Retry 65h   Reserved 66h   Query Parallel Port Status 67h   Reserved 68h   Reserved 69h   Query Active Font 6Ah   Verify Font 6Bh   Reserved 6Ch   Reserved 6Dh   Reserved 6Eh   Query Parallel Port Write Timeout Value 6Fh   Reserved 70h   Reserved 71h   Reserved 72h   Query Parallel Port Communication Mode 73h   Query Parallel Port Data Transfer Mode 74h   Query Parallel Port Device ID 

Category 07h Mouse Control IOCtl Commands
The following is a summary of Category 07h IOCtl Commands:  Function Description 50h   Reserved 51h   Notification of Display Mode Change 52h   Reserved 53h   Reassign Current Mouse Scaling Factors 54h   Assign New Mouse Event Mask 55h   Reassign Mouse Threshold Values 56h   Set Pointer Shape 57h   Unmark Collision Area 58h   Mark Collision Area 59h   Specify/Replace Pointer Screen Position 5Ah   Set OS/2 Mode Pointer Draw Device Driver Address 5Bh   Reserved 5Ch   Set Current Physical Mouse Device Driver Status Flags 5Dh   Notification of Mode Switch Completion 60h   Query Number of Mouse Buttons Supported 61h   Query Mouse Device Motion Sensitivity 62h   Query Current Physical Mouse Device Driver Status Flags 63h   Read Mouse Event Queue 64h   Query Current Event Queue Status 65h   Query Current Mouse Event Mask 66h   Query Current Mouse Scaling Factors 67h   Query Current Pointer Screen Position 68h   Query Current Pointer Shape 69h   Query Mouse Threshold Values 6Ah   Query Physical Mouse Device Driver Level/Version Number 6Bh   Query Pointing Device ID 

Category 08h Logical Disk Control IOCtl Commands
The following is a summary of Category 08h IOCtl Commands:

Category 09h Physical Disk Control IOCtl Commands
Category 09h is used to access physical partitionable hard disks. The handle used for Category 09h command is returned by the DosPhysicalDisk (Function 2) API function. (See the OS/2 Control Program Programming Reference for more information). This handle is used to tell the system which physical disk is accessed by the IOCtl command.

The Physical Disk Control commands relate to the entire partitionable hard disk. Direct track and sector I/O start at the beginning of the physical drive. PDSK_GETPHYSDEVICEPARAMS, describes the entire physical device.

The following is a summary of Category 09h IOCtl Commands:  Function      Description 00h        Lock Physical Drive 01h        Unlock Physical Drive 44h        Write Physical Track 63h        Query Physical Device Parameters 64h        Read Physical Track 65h        Verify Physical Track 

Category 0Ah Character Device Monitor IOCtl Command
The following is the Category 0Ah IOCtl Command:  Function Description 40h   Register Monitor </PRE>

Category 0Bh General Device Control IOCtl Commands
The following is a summary of Category 0Bh IOCtl Commands:  Function Description 01h   Flush Input Buffer 02h   Flush Output Buffer 41h   System Notifications for Physical Device Drivers 60h   Query Monitor Support </PRE>

Category 0Ch Advanced Power Management
 Function Description 40h      Send Power Event 41h      Set Power Event Resource 42h - 44h Reserved 45h      OEM APM Function 60h      Query Power Status 61h      Query Power Event 62h      Query Power Information 63h      Query Power State </PRE>

Category 80h Screen Control IOCtl Commands
The following video IOCtls are defined and supported by the SCREENDD$ device driver, by way of the DosDevIOCtl call. The IOCtl category code is 80h (defined as SCREENDD_CATEGORY).

The function codes within the SCREENDD_CATEGORY are:  Function Description 00h      Get Current Video Memory Bank 01h      Set Current Video Memory Bank 02h-07h  Reserved 08h      Return Adapter Video Configuration 09h      Return Manufacturer-Specific Adapter Data 0Ah      Update Adapter Video Memory Information 0Bh      Return Linear Address Mapped to Physical Address 0Ch-7Fh  Reserved </PRE> An example of the DosDevIOCtl calling convention for the Screen IOCtls follows:  int PASCAL near videoIoctl(VOID *data,VOID *parm,USHORT function) { unsigned hScreenDD;                  /* handle of SCREENDD$ dev driver */ unsigned OpenAction;                /* action taken to open device    */ unsigned rc;                        /* function return code           */

if (!(rc = DosOpen(SCREENDD_NAME, (PHFILE)&hScreenDD, (PUSHORT)&OpenAction,    NO_SIZE, NO_ATTRIBUTES, OPEN_IF_EXISTS, NO_INHERIT+DENY_NONE+READ_WRITE,     RESERVED_LONG))) {   rc = DosDevIOCtl(data,                     parm,                     function,                     SCREENDD_CATEGORY,                     (HFILE)hScreenDD); DosClose(hScreenDD); } return (rc); </PRE>

Category 80h OEMHLP IOCtls
The OEMHLP interface was originally designed to allow Original Equipment Manufacturers (OEMs) to modify and adapt the OS/2 operating system to run on their hardware. In the past, IBM supported the OS/2 operating system on IBM hardware only. Therefore, OEMs had to build modified versions of the OS/2 operating system. The OEMHLP interface facilitated this process.

IBM currently tests the OS/2 operating system on a wide variety of OEM hardware. It is no longer necessary for OEMs to adapt the OS/2 operating system to their machines. Now the OEMHLP interface can be used to obtain real-mode information. This information can be passed to applications and device drivers running in protect mode. Applications and physical device drivers running in protect mode cannot access BIOS through the INT interface. The OEMHLP interface allows access to BIOS information and functions that are essential to these programs.

For example, you might want to issue INT 15h calls from your device driver initialization code to determine if an Extended Industry Standard Architecture (EISA) adapter is present. The following examples show the methods to determine if a specific EISA or Micro Channel adapter is present.

Using the Query Adapter ID to Verify EISA Adapter
The following example uses the OEMHLP IOCtl interface to verify the EISA card ID:  USHORT FindMyEISACard(void) { HFILE filehandle; USHORT action;

EISAFunctionInfo.efi_SubFunc = OEM_GET_SLOT_INFO; /* EISA Get Slot Info */ EISAFunctionInfo.efi_Slot   = 0;                 /* Slot 0             */

rc = DosOpen("OEMHLP$",              &filehandle,               &action,               0L,               0,               1,               0x40,               0L); if (rc == 0) {   for(index=1;index<CFG_MAX_EISA_SLOTS;index++)   /* For each slot      */ {     EISAFunctionInfo.efi_Slot    = (UCHAR) index; /* Slot Number        */ EISASlotInfo.esi_CardID = 0;                 /* Reset Card ID value*/ rc = DosDevIOCtl((PVOID)&EISASlotInfo,       /* Data Packet */                       (PVOID)&EISAFunctionInfo,    /* Parm Packet */                       (USHORT)OEMHLP_QUERYEISACONFIG,                       (USHORT)OEMHLP_CATEGORY,                       (HFILE)filehandle); /* If IOCtl successful and slot has adapter, then store away the adapter ID, otherwise mark as empty with a zero. */     if((rc==0)&&(EISASlotInfo.esi_Error==0)) {       if (EISASlotInfo.esi_CardID == MYCARDID) DosClose(filehandle);       /* Close handle to OEMHLP$ */ return(FOUND); }     }      DosClose(filehandle);             /* Close handle to OEMHLP$ */ }  return(NOTFOUND); } </PRE>

Using the DevHlp_ABIOSCall to Verify Micro Channel Adapter
The following example uses the DevHlp_ABIOSCall to verify the Micro Channel POS ID:  USHORT FindMyMicroChannelCard(void) { USHORT i,rc;             /* Index and return code    */ USHORT LID;             /* Logical ID               */

if (GetLIDEntry(POS,0,1,&LID)) return(NOTFOUND);

/* Get length of RB to use for reading POS data. */

POSLenRB.rb.RBLen = sizeof(POSLENRB); POSLenRB.rb.Func = 0x01; POSLenRB.rb.LID  = LID; POSLenRB.rb.Unit = 0; POSLenRB.rb.Resv1 = 0; POSLenRB.rb.Resv2 = 0; POSLenRB.Rsv1    = 0; POSLenRB.Rsv2    = 0; POSLenRB.Rsv3    = 0; rc = ABIOSCall( LID, &POSLenRB, 0);

/*Is my request block big enough? */

if ((rc==0) && (sizeof(POSRB) >= POSLenRB.RBLen)) {      RB.rb.RBLen = POSLenRB.RBLen;       /* request block length        */ RB.rb.Func = 0x0b;                 /* read stored POS data to mem */ RB.rb.LID  = LID;                  /* Logical ID                  */ RB.rb.Unit = 0; RB.DataBuf = (ULONG)(FARPOINTER)&POSData;

for(i=0;i<=CFG_MAX_POS_SLOTS;i++)  /* For each slot, get POS ID   */ {          RB.Slot = (UCHAR)i; rc = ABIOSCall(LID,&RB,0); if((rc==0)&&(RB.rb.RetCode==0)) if (RB.AdapterID == MYCARD) {                 FreeLIDEntry(LID); return(FOUND); }         }     }

FreeLIDEntry(LID);            /* Release LID Entry */ return(NOTFOUND); } </PRE>

OEMHLP IOCtls Summary
The following is a summary of Category 80h OEMHLP IOCtl Commands:  Function Description 00h      Query OEM Adaptation Information 01h      Query Machine Information 02h      Query Display Combination Code 03h      Return Video Fonts 04h      Read EISA Slot Configuration Information     - Subfunction 00 04h      Read EISA Function Configuration Information - Subfunction 01 05h      Query ROM BIOS Information 06h      Query Miscellaneous Video Information 07h      Query Video Adapter 08h      Query SVGA Information 09h      Query Memory Information 0Ah      Query Display Mode, Query and Set (DMQS) Information 0Bh      Access PCI BIOS Information 0Bh      Query PCI BIOS Information - Subfunction 00h 0Bh      Find PCI Device - Subfunction 01h 0Bh      Find PCI Class Code - Subfunction 02h 0Bh      Read PCI Configuration Space - Subfunction 03h 0Bh      Write PCI Configuration Space - Subfunction 04h </PRE>

Category 80h Adapter Presence-Check Services (TESTCFG.SYS)
The TESTCFG device driver provides services for automatic detection of Original Equipment Manufacturer (OEM) hardware interfaces. Functions provided by this driver are accessed entirely by opening the device name TESTCFG$ and using the following Category 80h IOCtls.  Function Description 40H      Get Copy of BIOS/Adapter Memory 41H      Issue an "IN" I/O Instruction 42H      Issue an "OUT" I/O Instruction 60H      Get Bus Architecture Function 61H      Return All POS IDs 62H      Return All EISA IDs </PRE>

Category 80h Resource Manager IOCtl Commands
RESOURCE.SYS provides two IOCtls that allow a ring 3 application to obtain a "snapshot" of the Resource Management data structures. Obtaining a snapshot of the Resource Management data structures consists of the following two steps:

1.- A data structure representing a depth-first traversal of the Resource Manager node structure is obtained.

2.- For each node traversed, the following information is provided:
 * A Resource Manager handle to access the node.
 * The depth of the node in the tree structure.

3.- A copy of each Resource Manager node can be obtained by supplying the node handle returned in Step 1.  Function Description 01h      Get Resource Manager Node Data 02h      Enumerate Resource Manager Nodes </PRE>

Category 80h CD-ROM Drive and Disc IOCtl Commands
The OS/2 CD-ROM Device Manager provides an interface through generic IOCtls.

The CD-ROM device driver returns error values in the range of hex FF00 through FF14. DOS DevIOCtl return codes are described in the OS/2 Programming Reference manuals.  Function Description 40h      Reset Drive 44h      Eject Disc 45h      Close Tray 46h      Lock/Unlock Door 50h      Seek 60h      Return Device Status 61h      Identify CD-ROM Driver 63h      Return Sector Size 70h      Report Location of Drive Head 72h      Read Long 78h      Return Volume Size 79h      Get UPC </PRE>

Category 81h CD-ROM Audio IOCtl Commands
The OS/2 CD-ROM Device Manager provides an interface through generic IOCtls.

The CD-ROM device driver returns error values in the range of hex FF00 through FF14. DOSDevIOCtl return codes are described in the OS/2 Programming Reference manuals.  Function Description 40h      Set Audio Channel Control 50h      Play Audio 51h      Stop Audio 52h      Resume Audio 60h      Return Audio-Channel Information 61h      Return Audio-Disk Information 62h      Return Audio-Track Information 63h      Return Audio-Subchannel Q Information 65h      Return Audio-Status Information </PRE>

Category 81h Touch Device-Dependent Driver
All Touch device driver IOCtl commands share Category 81h commands, which are distinguished by the device name used in the device Open (PDITOU$ for the device-dependent driver, TOUCH$ for the device-independent driver).

Device-Dependent Device Driver Command Summary
The following table describes the Category 81h Touch Device-Dependent Driver IOCtl commands:  Function Description 50h      Reserved. 51h      Reserved. 52h      Set Calibration Constants 53h      Read Data 54h      Set Data Mode 55h      Set Click-Lock Parameters 56h      Set Touch Thresholds 57h      Set Emulation XY Offset 58h      Set Data Report Rate 59h      Set Low Pass Filter 5Ah      Write Memory Location 5Bh      Reserved. 5Ch      Reserved. 5Dh      Reserved. 5Eh      Reserved. 5Fh      Reserved. 60h      Get Calibration Constants 61h      Get Data Mode 62h      Get Click-Lock Parameters 63h      Get Touch Thresholds 64h      Get Emulation XY Offset 65h      Get Data Report Rate 66h      Get Low Pass Filter 67h      Read Memory Location </PRE>

Category 81h Touch Device-Independent Driver
All Touch device driver IOCtl commands share Category 81h commands, which are distinguished by the device name used in the device Open (PDITOU$ for the device-dependent driver, TOUCH$ for the device-independent driver).

The following lists and describes the Category 81h Touch Device-Independent Driver:  Function Description 50h     Set Coordinate System 51h     Reserved 52h     Set Selection Mechanism 53h     Set Event Mask 54h     Set Queue Size 55h     Set Emulation State 60h     Get Coordinate System 61h     Reserved 62h     Get Selection Mechanism 63h     Get Event Mask 64h     Get Queue Size 65h     Get Emulation State 66h     Get Read Event Queue </PRE>