Input/Output Device Driver Reference/Keyboard Inter-Device-Driver Communication Interfaces
This chapter describes the inter-device-driver communication (IDC) interfaces for the IBM keyboard device drivers provided by the OS/2 operating system - both device-independent to device-dependent and device-dependent to device-independent.
The division of the keyboard device driver has allowed new functions to be included that were not previously available. These functions are found in the following IDC functions.
Note: If an independent-device driver changes the state of one of the drivers by making an IDC call, it is not always reflected in the other driver. For example, if a driver changes the state of the LEDs in the device-dependent (DD) driver, the change will not be reflected in the device-independent (DI) driver and the device-independent driver might change the LEDs to another state at any time.
Device-Independent Supplied IDC's
The following are the device-independent IDC functions.
- Note
- For compatibility purposes, the data segment should not be changed by the dependent-device driver. The device-independent driver will load up the correct data segment required.
The following are the device-independent IDC functions that are currently available.
- 00 Open
- 01 Close
- 02 Process Keystroke
- 03 Process Reinit
- 04 Pen Functions
Open
This function registers the device-dependent driver with the device-independent driver. The independent-device driver will use this registry to notify device-dependent drivers of updates (such as LED, type rate/delay, and so on). If a driver does not want to be notified of updates, then it sends in a 0000h Code Segment value.
Input:
Func: Open_IDC code (0000h) Var1: Code Offset of DD IDC routine Var2: Data Segment of DD Driver Var3: Code Segment of DD IDC routine
Output:
AX = Handle (0FFFFh=error, could not open)
Close
This function deletes the driver from the registry.
Input:
Func: Close_IDC code (0001h) Var1: NULL Var2: Data Segment of DD Driver Var3: Handle from Open Call
Output:
If the handle or data segment are incorrect, AX=0FFFFh is returned.
Process Keystroke
This function is called by the device-dependent driver when it has a complete keystroke to report to the device-independent driver. The buffer may be reused immediately after this call.
Input:
Func: Process_Keystroke code (0002h) Var1: Data Offset of keystroke buffer Var2: Data Segment of keystroke buffer and DD Driver Var3: Handle from Open Call
Output:
If the handle or data segment are incorrect, AX=0FFFFh is returned.
Process Reinit
This IDC informs the device-independent driver that a reinit/hot-plug condition has occurred. The device-independent driver now checks the attached keyboard type (and all that a keyboard change entails), and resends the appropriate LED state to the device-dependent driver.
Input:
Func: Process_Reinit Code (0003h) Var1: NULL Var2: Data Segment of DD Driver Var3: Handle from Open call
Output:
If the handle or data segment are incorrect, AX=0FFFFh is returned.
Pen Functions
This function allows the keyboard device driver to create system keyboard events on behalf of the Pen for OS/2 subsystem.
Input:
Func: Pen_Functions code (04XXh) Var1: Index to SINFO data structure Var2: Data Segment Var3: Internal Pen function variable
Output:
Carry set if error occurs.
Device-Dependent Supplied IDC's
The following are the device-dependent IDC functions.
- 00 Open
- 01 Close
- 02 Query Capabilities
- 03 Query Typematic & Delay
- 04 Query LEDs
- 05 Query ID codes
- 06 Query Disabled
- 07 Disable Keyboard
- 08 Enable Keyboard
- 09 Reset Hardware
- 0A Set Typematic & Delay
- 0B Set LEDs
- 0E Send Generic Command
- 0F Query Keyboard Ready
- 10 Flush Partial Keys
- 12 Save State
- 13 Restore State
- 87 Disable Keyboard (Interrupt Time)
- 88 Enable Keyboard (Interrupt Time)
- 89 Reset Hardware (Interrupt Time)
- 8A Set Typematic & Delay (Interrupt Time)
- 8B Set LEDs (Interrupt Time)
Open
The open function is not a prerequisite for implementing other functions within this device driver.
Input:
Func: Open Device Driver code (0000h)
Var1: NULL
Var2: NULL
Output:
AX = 0: Keyboard is ready for any command.
0FFFFh: Keyboard is busy. OK to query, but thread will be
blocked or unexecuted (if interrupt time) if an
attempt is made to send a command to the keyboard
hardware.
Close
This function is null and is used for compatibility purposes only.
Input:
Func: Close Device Driver code (0001h)
Var1: NULL
Var2: NULL
Output:
None.
Query Capabilities
This request is issued by the device-independent driver to find out what capabilities the attached driver has.
Input:
Func: Query_Capabilities code (0002h)
Var1: CapStruc buffer address offset
Var2: CapStruc buffer address segment
Output:
AX = 0 (and structure is filled in)
struct CapStruc {
USHORT DevFlags;
USHORT KeyCount;
USHORT MaxTypa;
USHORT MinTypa;
USHORT MaxDelay;
USHORT MinDelay;
}
Device Flags: 0000 0000 0ccc 00ba
│ ││
│ │└─ True Keyboard
│ └── Hotplug Detection
└───── Number of LEDs (0-7)
Device Flags: 0000 0000 0ccc 00ba
│ ││
│ │└─ True Keyboard
│ └── Hotplug Detection
└───── Number of LEDs (0-7)
Query Typematic Rate and Delay
This function queries the current type rate and delay of the keyboard hardware.
Input:
Func: Query_Typematic code (0003h)
Var1: NULL
Var2: NULL
Output:
AX = Bits 15-7 -> Reserved
Bits 6-5 -> Delay value in milliseconds
(values in binary)
00 - 250
01 - 500
10 - 750
11 - 1000
Bits 4-0 -> Rate value in characters per second
(values in binary)
00000 - 30.0 10000 - 7.5
00001 - 26.7 10001 - 6.7
00010 - 24.0 10010 - 6.0
00011 - 21.8 10011 - 5.5
00100 - 20.0 10100 - 5.0
00101 - 18.5 10101 - 4.6
00110 - 17.1 10110 - 4.3
00111 - 16.0 10111 - 4.0
01000 - 15.0 11000 - 3.7
01001 - 13.3 11001 - 3.3
01010 - 12.0 11010 - 3.0
01011 - 10.9 11011 - 2.7
01100 - 10.0 11100 - 2.5
01101 - 9.2 11101 - 2.3
01110 - 8.6 11110 - 2.1
01111 - 8.0 11111 - 2.0
Query LEDs
This function queries the current LED state of the keyboard hardware.
Input:
Func: Query_LEDs code (0004h)
Var1: NULL
Var2: NULL
Output:
AX = Bits 15 to 3 - Reserved
Bit 2 - CapsLock
Bit 1 - NumLock
Bit 0 - ScrollLock
Query ID Codes
This function queries the current ID of the keyboard hardware.
Input:
Func: Query_ID (0005h)
Var1: IDstruc buffer address offset
Var2: IDstruc buffer address segment
Output:
AX = key count (88/101/122/etc), 0=undetermined (IDstruc buffer is filled in, also).
struc IDstruc {
USHORT idlen; /* length of returned ID code */
UCHAR idbytes[8]; /* buffer for ID bytes */
}
Query Disabled
This function queries if the keyboard hardware is disabled.
Input:
Func: Query_Disabled (0006h)
Var1: NULL
Var2: NULL
Output:
AX = Disabled Flag (0 enabled, 0FFFFh disabled)
Disable Keyboard
This function disables the keyboard and does not allow keystrokes to be accepted.
Input:
Func: Disable_Keyboard (0007h)+[Interrupt Time +80h]
Var1: NULL
Var2: NULL
Output:
AX = Disable Function (0 was already disabled, 1 disabled)
Enable Keyboard
This function enables the keyboard and allows keystrokes to be accepted.
Input:
Func: Enable_Keyboard (0008h)+[Interrupt Time +80h]
Var1: NULL
Var2: NULL
Output:
AX=0FFFFh if error occurs.
Reset Hardware
This function is issued when the device-independent portion wants to place the physical hardware into a known, reset state. This call should reset the physical keyboard and the attaching device (Kbd section of 8042).
Input:
Func: Reset_Hardware (0009h)+[Interrupt Time +80h]
Var1: NULL
Var2: NULL
Output:
AX=0FFFFh if error occurs.
Set Typematic Rate and Delay
This function sets the keyboard hardware to a specified type rate and delay.
Input:
Func: Set_Typematic code (000Ah)+[Interrupt Time +80h]
Var1: Parameter word
Var2: NULL
Parameter word:
AX = Bits 15-7 -> Reserved (must be set to zero)
Bits 6-5 -> Delay value in milliseconds
(values in binary)
00 - 250
01 - 500
10 - 750
11 - 1000
Bits 4-0 -> Rate value in characters per second
(values in binary)
00000 - 30.0 10000 - 7.5
00001 - 26.7 10001 - 6.7
00010 - 24.0 10010 - 6.0
00011 - 21.8 10011 - 5.5
00100 - 20.0 10100 - 5.0
00101 - 18.5 10101 - 4.6
00110 - 17.1 10110 - 4.3
00111 - 16.0 10111 - 4.0
01000 - 15.0 11000 - 3.7
01001 - 13.3 11001 - 3.3
01010 - 12.0 11010 - 3.0
01011 - 10.9 11011 - 2.7
01100 - 10.0 11100 - 2.5
01101 - 9.2 11101 - 2.3
01110 - 8.6 11110 - 2.1
01111 - 8.0 11111 - 2.0
Output:
AX=0FFFFh if error occurs.
Set LEDs
This function sets the state of the keyboard LEDs. Bits 0-2 must set the LEDs labeled below. The other bits of BL are reserved for future support of keyboards with greater LED counts.
Input:
Func: Set_LEDs code (000Bh)+[Interrupt Time +80h]
Var1: Parameter word
Var2: NULL
Parameter word:
bit 15 - bit 3 - Reserved
bit 2 - CapsLock
bit 1 - NumLock
bit 0 - ScrollLock
Output:
AX=0FFFFh if error occurs.
Send Generic Command
This function will send any command to the keyboard.
Input:
Func: Send_Generic code (000Eh)
Var1: CmdStruc buffer address offset
Var2: CmdStruc buffer address segment
struc CmdStruc {
USHORT wait; /* 1 wait for ACK between bytes, 0 no wait */
USHORT strlen; /* length of following string */
UCHAR bytes[strlen]; /* string of bytes to send to keyboard */
}
Output:
AX=0FFFFh if error occurs.
Query Keyboard Ready
This function determines if the keyboard is currently executing a command or ready for input.
Input:
Func: Query_Kbd_Rdy code (000Fh)
Var1: NULL
Var2: NULL
Output:
AX = Ready Flag (0=No, 0FFFFh=Yes)
Flush Partial Keys
This request instructs the device-dependent keyboard driver to flush any partial keys it has accumulated and return to a quiescent state. Because most physical drivers will be implemented using a finite state machine, this is a forced transition to the start state.
Input:
Func: Flush_Partial code (0010h)
Var1: NULL
Var2: NULL
Output:
AX=0.
Save State
This function informs device-dependent drivers to save all hardware state information for a later time. This function is used for Advanced Power Management (APM) support.
Input:
Func: Save_State code (0012h)
Var1: NULL
Var2: NULL
Output:
AX=0FFFFh if error occurs.
Restore State
This function restores all hardware state information from the last save. If a Save State has not receded this call, the keyboard defaults to no LEDs lit, and a 0 type rate and delay. This function is used for Advanced Power Management (APM) support.
Input:
Func: Save_State code (0013h)
Var1: NULL
Var2: NULL
Output:
AX=0FFFFh if error occurs.