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.