View source for 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==
[[Image:Ioddr-04.gif|right]]
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:<br /><tt>[C:\]md testkbd<br />[C:\]cd testkbd<br />[C:\testkbd]copy e:\ddk_x86\testcert\inputout\function\keyboard\*<br />[C:\testkbd]copy e:\ddk_x86\testcert\general\ddtt\*</tt>
# 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:<br /><tt>DEVICE=c:\testkbd\testkbd.sys</tt>
# 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:
<pre> [C:\TESTKBD]DDTT QUERY.SCR</pre>
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.

{|class="wikitable"
|+Output Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!Keyword||Type||Description
|-
|HANDLE
|NUM
|Handle for TESTKBD.SYS
|}

{|class="wikitable"
|+Output Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!Keyword||Type||Description
|-
|HANDLE
|NUM
|Handle for TESTKBD.SYS
|}

{|class="wikitable"
|+Output Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!Keyword||Type||Description
|-
|HANDLE
|NUM
|Handle for TESTKBD.SYS
|}

{|class="wikitable"
|+Output Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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.

{|class="wikitable"
|+Input Parameter Keywords
!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
{|class="wikitable"
!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.

[[Category:I/O Device Driver Reference]]