Input/Output Device Driver Reference/Keyboard Device Driver Test Tool
This chapter explains how to use the keyboard Device Driver Test Tool.
Overview
The keyboard Functional Verification Tests (FVTs) exercise the Inter-Device-Driver Communication (IDC)interfaces defined for the keyboard device drivers. The tests are implemented with the Device Driver Test Tool (DDTT) and a test device driver (TEST KBD.SYS). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate keyboard function and performance. Errors are reported and isolated to a specific test sequence and API.
User input and output from each keyboard test is performed by way of a separate Presentation Manager window. Test cases log all information to a log files, clearly indicating the actual execution sequence in the event of errors.
Keyboard Test Architecture
The DDTT provides a common front-end parser for test-case scripts and also tests several devices and APIs. The following DDTT keyboard-specific files are required:
- DDTKBD.DLL
- KBD.GRA
- TESTKBD.SYS
The C++ source code for DDTKWD.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc.
The following required, common components of the DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:
- DDTT.EXE
- DDTT.DLL
- GLOBAL.DLL
- GLOBAL.GRA
Installation
There are two directory structures utilizing test suites in the IBM Developer Connection Device Driver Kit for OS/2. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.
The following procedure describes installation for running test cases:
- Copy the executable and parallel port test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTKBD. Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTKBD and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the parallel port test suite:
[C:\]md testkbd
[C:\]cd testkbd
[C:\testkbd]copy e:\ddk_x86\testcert\inputout\function\keyboard\*
[C:\testkbd]copy e:\ddk_x86\testcert\general\ddtt\* - Add C:\TESTKBD to the LIBPATH and PATH in the CONFIG.SYS file.
- To install the device driver, edit your system's CONFIG.SYS file and add the following line:
DEVICE=c:\testkbd\testkbd.sys - Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.
Test Case-Execution
To run one script file at a time, refer to #Description of Test Cases for a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name:
[C:\TESTKBD]DDTT QUERY.SCR
After the script has finished executing, CONTROL will transfer back to the OS/2 Window.
KBDDD.SYS Test Grammar Function Calls
The following is a list of the KBDDD.SYS Test Grammar Function Calls:
- KBD_OPEN
- KBD_CLOSE
- KBD_QUERY_CAPS
- KBD_QUERY_TYPEMATIC
- KBD_QUERY_LEDS
- KBD_QUERY_IDS
- KBD_QUERY_DISABLED
- KBD_SEND_CMD
- KBD_FLUSH
- KBD_SAVE_STATE
- KBD_RESTORE_STATE
- KBD_DISABLE and KBD_DISABLE_I
- KBD_ENABLE and KBD_ENABLE_I
- KBD_RESET and KBD_RESET_I
- KBD_OPEN_DI
- KBD_CLOSE_DI
- KBD_PROCESS_KEY
- KBD_PROCESS_REINIT
- KBD_PRINT_LAST_IDC
KBD_OPEN
This function opens the TESTKBD.SYS device driver and sends an open IDC to IBMKBD.SYS.
- Input Parameter Keywords
- None.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Logged Data
None.
KBD_CLOSE
This function sends a close IDC to KBDDD.SYS and closes the TESTKBD.SYS device driver.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_QUERY_CAPS
This function queries the capabilities of the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
| Keyword | Type | Description |
|---|---|---|
| MAXTYPA | NUM | Max typematic rate selector (0-31) |
| MINTYPA | NUM | Min typematic rate selector (0-31) |
| MAXDELAY | NUM | Max delay value selector (0-3) |
| MINDELAY | NUM | Min delay value selector (0-3) |
| KEYCOUNT | NUM | Number of keys |
| NUMLEDS | NUM | Number of LEDs |
- Logged Data
- Max typematic rate selector (0-31)
- Min typematic rate selector (0-31)
- Max delay value selector (0-3)
- Min delay value selector (0-3)
- Number of keys
- Number of LEDs
- (No) Hotplug Detection
- (Not) True keyboard
KBD_QUERY_TYPEMATIC
This function queries the current typematic rate and delay of the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
| Keyword | Type | Description |
|---|---|---|
| TYPASEL | NUM | Typematic rate selector (0-31) |
| DELAYSEL | NUM | Delay value selector (0-3) |
- Logged Data
- Typematic rate selector (0-31)
- Delay value selector (0-3)
KBD_QUERY_LEDS
This function queries to determine which LEDs are lit.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- Scroll Lock is ON/OFF
- Num Lock is ON/OFF
- Caps Lock is ON/OFF
KBD_QUERY_IDS
This function queries the ID value and keycount of the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
| Keyword | Type | Description |
|---|---|---|
| KEYCOUNT | NUM | Number of keys |
| ID | NUM | ID code for keyboard hardware |
- Logged Data
- Number of keys
- ID code for keyboard hardware
KBD_QUERY_DISABLED
This function queries to determine if the keyboard has been disabled.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- Keyboard enabled or disabled
KBD_QUERY_READY
This function queries whether the keyboard is ready.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- Keyboard ready or not ready
KBD_SEND_CMD
This function sends a generic command to the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
| COMMAND | STRING | Command string |
| ACK | NUM | Nonzero if acknowledgement is required |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_FLUSH
This function flushes partial keystrokes and returns the keyboard to a start state.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_SAVE_STATE
This function saves the keyboard state and is used by the Advanced Power Management System.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_RESTORE_STATE
This function restores the keyboard's saved state. This function is used by the Advanced Power Management System.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- None.
Paired Functions
The following functions are paired according to interrupt-mode processing and non-interrupt mode processing. If the function is an interrupt-mode function, it has a _I suffix. The functionality of the pairs of functions is identical whether the _I suffix is there or not.
KBD_DISABLE and KBD_DISABLE_I
These functions disable the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_ENABLE and KBD_ENABLE_I
These functions enable the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_RESET and KBD_RESET_I
These functions reset the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
- Output Parameter Keywords
None.
- Logged Data
None.
KBD_SET_TYPEMATIC and KBD_SET_TYPEMATIC_I
These functions set the typematic rate and delay of the keyboard.
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
| TYPASEL | NUM | Typematic rate selector (0-31) |
| DELAYSEL | NUM | Delay value selector (0-3) |
- Output Parameter Keywords
- None.
- Logged Data
- None.
KBD_SET_LEDS and KBD_SET_LEDS_I
These functions set the LEDs.
- Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| HANDLE | NUM | Handle for TESTKBD.SYS |
| LEDS | NUM | THE LEDS KEYWORD IS A 3-BIT BINARY NUMBER, where:
Bit 0 = Scroll Lock Bit 1 = Num Lock Bit 2 = Caps Lock |
- Output Parameter Keywords
- None.
- Logged Data
- None.
Description of Test Cases
Each of the keyboard test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the keyboard grammar files.
All test scripts close the channels opened to the keyboard device and verify successful status returns from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, track, channel, or drive), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has been completed.
- INTERACT.SCR
- Human interaction script - This script tests the enable/ disable feature of the keyboard driver. When the keyboard is disabled, the user is asked to type at a prompt. If the disable is successful, the keyboard re-enables after a timeout of five seconds.
- SET.SCR
- LED and Typematic selection script - This script sets the typematic rate and delay, as well as playing with the LEDs. It allows the user to verify that the rate and delay have been changed by allowing typing at the prompt. If no input is received, the prompt times out after 10 seconds.
- QUERY.SCR
- This is a multi-threaded test that attempts to run some IDCs in parallel.