Jump to content

Input/Output Device Driver Reference: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
Ak120 (talk | contribs)
35,819 edits
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{IORef}}
{{IBM-Reprint}}
{{IBM-Reprint}}


Line 64: Line 65:


=== Ordering Information ===
=== Ordering Information ===
In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.
In addition to the actual tools and source code available on The [[IBM Developer Connection Device Driver Kit for OS/2]], it also includes the following DDK reference books in online format.
*The Physical Device Driver Reference
*[[Physical Device Driver Reference|The Physical Device Driver Reference]]
*The Storage Device Driver Reference
*[[Storage Device Driver Reference|The Storage Device Driver Reference]]
*The Input/Output Device Driver Reference
*[[Input/Output Device Driver Reference|The Input/Output Device Driver Reference]]
*The Pen for OS/2 Device Driver Reference
*[[Pen for OS/2 Device Driver Reference|The Pen for OS/2 Device Driver Reference]]
*The Virtual Device Driver Reference
*[[Virtual Device Driver Reference for OS/2|The Virtual Device Driver Reference]]
*The Presentation Device Driver Reference
*[[Presentation Device Driver Reference for OS/2|The Presentation Device Driver Reference]]
*The Display Device Driver Reference
*[[Display Device Driver Reference for OS/2|The Display Device Driver Reference]]
*The Printer Device Driver Reference
*[[Printer Device Driver Reference for OS/2|The Printer Device Driver Reference]]
*The Graphics Adapter Device Driver Reference
*[[Graphics Adapter Device Driver Reference|The Graphics Adapter Device Driver Reference]]
*The MMPM/2 Device Driver Reference (Multimedia)
*[[MMPM/2 Device Driver Reference|The MMPM/2 Device Driver Reference (Multimedia)]]


=== What's New ===
=== What's New ===
Line 122: Line 123:
Header and include files are shipped with OS/2 to provide support for building presentation drivers that are written in C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Presentation Device Driver Reference''.
Header and include files are shipped with OS/2 to provide support for building presentation drivers that are written in C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Presentation Device Driver Reference''.


==Keyboard Device Driver Test Tool==
==OS/2 Version Compatibility Considerations==
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.
 
;Output Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|HANDLE
|NUM
|Handle for TESTKBD.SYS
|}
 
;Output Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|HANDLE
|NUM
|Handle for TESTKBD.SYS
|}
 
;Output Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|HANDLE
|NUM
|Handle for TESTKBD.SYS
|}
 
;Output Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
;Input Parameter Keywords
{|class="wikitable"
!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.
 
== Mouse (DOS) Device Driver Test Tool ==
This chapter explains how to use the mouse (DOS) Device Driver Test Tool.
 
===Overview===
The mouse Functional Verification Tests (FVTs) exercise the Int86() DOS interface for mouse functions. The tests are implemented with a special variation of the Device Driver Test Tool (called DOSMOUSE), which uses much of the Device Driver Test Tool code; however, DOSMOUSE does not use the multithread capability. Specific mouse function code is included in the DOSMOUSE.EXE, not in a DLL, as is it done for the DDTT running in OS/2.
 
These tests run in a DOS window. 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 mouse functions.
 
Test cases log all information to a log file, clearly indicating the actual execution sequence.
 
====Mouse Test Architecture====
DOSMOUSE uses the DDTT common front-end parser code for test case scripts. DOSMOUSE is specific to test mouse functions. The mouse grammar file is required:
*DOSMOUSE.EXE
*MOUSE.GRA.
 
The following required, common component of the DDTT allows use of the DDTT's common test functions such as SET, LOOP, and PAUSE:
*GLOBAL.GRA
 
====Installation====
The mouse test files reside on the ''IBM Developer Connection Device Driver Kit for OS/2'' CD-ROM disc. These files utilize the test suites in the TESTCERT substructure, which also contain the executables and test cases.
 
The following procedure describes the installation process for running test cases:
 
1. Copy the executable and mouse test case files from the ''IBM Developer Connection Device Driver Kit for OS/2''CD-ROM disc to the hard drive. The executable (DOSMOUSE.EXE) files can reside in one directory (for example, \MOUSE). Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\MOUSE 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 mouse test suite:
<pre>
[C:\]md mouse
[C:\]cd mouse
[C:\mouse]copy e:\ddk_x86\testcert\inputout\function\mouse\*
[C:\mouse]copy e:\ddk_x86\testcert\general\ddtt\GLOBAL.GRA
</pre>
 
====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 DOSMOUSE followed by the script file name:
[C:\MOUSE]DOSMOUSE ALL.SCR
After the script has finished executing, control will transfer back to the DOS window. Results are logged in the file identified following the @THREAD line.
 
====DDTT Mouse Test Grammar Function Calls====
The following is a list of the DDTT Parallel Port Test Grammar Function Calls:
*MOUSE_RESETANDSTATUS
*MOUSE_SHOWCURSOR
*MOUSE_HIDECURSOR
*MOUSE_GETBUTTONMPOS
*MOUSE_SETCURPOS
*MOUSE_GETBPRESS
*MOUSE_GETBRELEASE
*MOUSE_SETMINMAXHCPOS
*MOUSE_SETMINMAXVCPOS
*MOUSE_READMCOUNT
*MOUSE_GETDRVVERTYPIRQ
*MOUSE_GETGENINFO
*MOUSE_GETMAXVCOOR
*MOUSE_GETCURMSKMCNT
*MOUSE_GETCURHSPT
*MOUSE_HDWRESET
*MOUSE_SETGETBPT
*MOUSE_GETMINMAX
*MOUSE_GETADVFCN
*MOUSE_GETSWSET
 
=====MOUSE_RESETANDSTATUS=====
'''Mouse Function 0'''
 
This function returns the current status of the mouse hardware and software.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
;Logged Data:M1% Mouse status (found and reset = -1, otherwise = 0) <br />M2% Number of buttons (if mouse found and reset = 2)
 
=====MOUSE_SHOWCURSOR=====
'''Mouse Function 1'''
 
This function increments the internal cursor flag and if the value of the flag is 0, displays the cursor on the screen.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
;Logged Data:None.
 
=====MOUSE_HIDECURSOR=====
'''Mouse Function 2'''
 
This function removes the cursor from the screen, decrements the internal cursor flag, and hides the cursor. The mouse driver continues to track the motion of the mouse, changing the cursor's position as the mouse changes position.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
;Logged Data:None.
 
=====MOUSE_GETBUTTONMPOS=====
'''Mouse Function 3'''
 
This function returns the state of the left-hand and right-hand mouse buttons and also returns the state of the cursor's horizontal and vertical virtual screen coordinates.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
;Logged Data:Button status <br />Horizontal cursor coordinates <br />Vertical cursor coordinates
 
=====MOUSE_SETCURPOS=====
'''Mouse Function 4'''
 
This function sets the cursor position at the location of the specified horizontal vertical virtual coordinates.
 
;Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|HORIZC||NUM||Horizontal cursor coordinate
|-
|VERTC||NUM||Vertical cursor coordinates
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:None.
 
=====MOUSE_GETBPRESS=====
'''Mouse Function 5'''
 
This function returns the current status of both buttons, counts the number of times the specified button was pressed since the last call to this function, and reports the cursor's horizontal and vertical coordinates the last time the specified button was pressed.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|BUTTON||NUM||Left hand button=0 or right hand button =1
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:Button status
:Number of button presses
:Horizontal coordinate
:Vertical coordinate
 
=====MOUSE_GETBRELEASE=====
'''Mouse Function 6'''
 
This function returns the current status of both buttons, counts the number of times the specified button was released since the last call to this function, and reports the cursor's horizontal and vertical coordinates the last time the specified button was released.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|BUTTON||NUM||Left hand button=0 or right hand button =1
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:Button status Button releases
:Horizontal coordinate
:Vertical coordinate
 
=====MOUSE_SETMINMAXHCPOS=====
'''Mouse Function 7'''
 
This function sets the position of the minimum and maximum horizontal cursor coordinates on the screen.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|HMIN||NUM||Horizontal minimum position
|-
|HMAX||NUM||Horizontal maximum position
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:None.
 
=====MOUSE_SETMINMAXVCPOS=====
'''Mouse Function 8'''
 
This function sets the position of the minimum and maximum vertical cursor coordinates on the screen.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|VMIN||NUM||Vertical minimum position
|-
|VMAX||NUM||Vertical maximum position
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:None.
 
=====MOUSE_READMCOUNT=====
'''Mouse Function 11'''
 
This function returns the horizontal and vertical mickey counts since the last call of this function.
 
;Input Parameter Keywords:
None.
 
;Output Parameter Keywords:None.
 
;Logged Data:Horizontal mickey count
:Vertical mickey count
 
=====MOUSE_GETDRVVERTYPIRQ=====
'''Mouse Function 36'''
 
This function returns the version number of the mouse driver, reports the type of mouse the driver requires, and returns the number of the interrupt request type (IRQ).
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Major version
:Minor version
:Mouse type
:IRQ number
 
=====MOUSE_GETGENINFO=====
'''Mouse Function 37'''
 
This function returns general information about the mouse.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:General information <br />fCursorLock <br />fInMouseCode <br />fMouseBusy
 
=====MOUSE_GETMAXVCOOR=====
'''Mouse Function 38'''
 
This function returns a flag indicating whether the mouse driver is disabled and indicates maximum virtual coordinates.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Mouse-disabled flag
:Maximum virtual ''x''
:Maximum virtual ''y''
 
=====MOUSE_GETCURMSKMCNT=====
'''Mouse Function 39'''
 
This function returns cursor information and accumulated raw mickey counts.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Screen-mask or Scan-line start
:Cursor-mask or Scan-line stop
:Horizontal mickey count
:Vertical mickey count
 
=====MOUSE_GETCURHSPT=====
'''Mouse Function 42'''
 
This function returns the cursor hot-spot location, reports the type of mouse in use, and returns the internal counter that controls cursor visibility.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:fCursor
:Horizontal cursor hot spot
:Vertical cursor hot spot
:Type of mouse
 
=====MOUSE_HDWRESET=====
'''Mouse Function 47'''
 
This function returns cursor information and accumulated raw mickey counts
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Success flag
 
=====MOUSE_SETGETBPT=====
'''Mouse Function 48'''
 
This function sets or returns cursor ballpoint-orientation and buttonmask information.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|ROTANGLE||NUM||Rotation angle
|-
|CMDINFO||NUM||Command
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:Status
:Rotation angle
:Button mask
 
=====MOUSE_GETMINMAX=====
'''Mouse Function 49'''
 
This function returns the minimum and maximum horizontal and vertical coordinates for the current video mode.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Status
:Virtual ''x''minimum
:Virtual ''y''minimum
:Virtual ''x''maximum
:Virtual ''y''maximum
 
=====MOUSE_GETADVFCN=====
'''Mouse Function 50'''
 
This function returns the flags that indicate active advanced functions.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Active function flags
 
=====MOUSE_GETSWSET=====
'''Mouse Function 51'''
 
This function returns the current settings of switch values that can be passed to the mouse driver.
 
;Input Parameter Keywords:None.
;Output Parameter Keywords:None.
 
;Logged Data:Mouse type
:Mouse port
:Language
:Horizontal sensitivity
:Vertical sensitivity
:Double threshold
:Ballistic curve
:Interrupt rate
:Cursor Override Mask
:Laptop adjustment
:Memory type
:Super VGA support
:Rotation angle
:Primary button
:Secondary button
:Clip lock enabled
:Acceleration curve data
 
===Description of Test Cases===
Each of the mouse test cases can be executed individually as previously described. The test scripts are described below. The user can create additional tests or combine tests into test cases after becoming familiar with DOSMOUSE and the MOUSE grammar file.
;ALL.SCR:This runs all the mouse functions.
;BUTTON.SCR:This tests button press and release functions.
 
===Evaluation of Test Case Results===
Unless otherwise stated in the test case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DOSMOUSE, then the token "ERROR" will be written to the corresponding log file.
 
==Parallel Port Device Driver Test Tool==
This chapter explains how to use the parallel port Device Driver Test Tool.
 
===Overview===
The parallel port Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). 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 parallel port function and performance. Errors are reported and are isolated to a specific test sequence and API.
 
User input and output from each thread of the parallel port tests 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.
 
===Parallel Port Test Architecture===
[[Image:ioddr-05.gif|right]]
The DDTT provides a common front-end parser for test-case scripts. The following DDTT parallel-specific files are required:
*DDTPARA.DLL
*PARALLEL.GRA
*GEN.GRA - needed for test script file, REQEX.SCR
*GENDRV.SYS - needed for test script file, REQEX.SCR
The C++ source code for DDTPARA.DLL is available on the ''IBM Developer Connection Device Driver Kit for OS/2''.
 
The following required, common components of the DDTT implement the 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 that utilize 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 \TESTPARA. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTPARA 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:
#:<tt>[C:\]md testpara</tt>
#:<tt>[C:\]cd testpara</tt>
#:<tt>[C:\testpara]copy e:\ddk_x86\testcert\inputout\function\parallel\*</tt>
#:<tt>[C:\testpara]copy e:\ddk_x86\testcert\general\ddtt\*</tt>
# Add the C:\TESTPARA to the LIBPATH and PATH in the CONFIG.SYS file.
# For script testcase REQEX.SCR, which requests and releases exclusive access, a generic driver named GENDRV.SYS must be installed. Edit your system's CONFIG.SYS file and add the following line:
#:<tt>DEVICE=c:\testpara\gendrv.sys</tt>
# Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.
 
=== Test-Case Execution ===
The DDTT parallel port tests must be executed on a directly-attached printer device. These tests will not work when executed against a printer device accessed by way of a network connection.
 
There are two ways to run parallel port tests. To run the program from a command file, be sure the files are installed in the current directory. Then, execute the TESTFONT or TESTPARA command files. The command file will run a set of script files. The TESTFONT executes scripts related to font testing and requires the spooler to be enabled. The TESTPARA executes scripts using other printer functions that require the spooler to be disabled.
 
To run one script file at a time, see [[#Description of Test Cases]] of the file to get 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:\TESTPARA]DDTT QFONT.SCR</pre>
 
After the script has finished executing, control will transfer back to the OS/2 Window. If the script files are run individually, and a TESTxxx command file has not been run first, then run SETINFO to set up your printer device.
 
There are three different sets of script files in the DDTT parallel port package. The first set is the font script files, the second set is the general printer script files, and the third is only one script file, REQEX. SCR, which requests and releases exclusive access. When TESTFONT or TESTPARA is run, it will ask for the printer device (such as LPT1 or LPT2).
 
The SETINFO command file will set up the necessary information that is needed for the parallel port script files. The command file will ask the following question:
<pre> PLEASE ENTER THE OUTPUT PORT OF YOUR PRINTER, SUCH AS LPT1</pre>
 
After this information is entered, the command file will store this information in the SYSINFO.TXT file. The contents of the file is
PARA SET DEVICENAME=LPT1
 
=== DDTT Parallel Port Test Grammar Function Calls ===
The following is a list of the DDTT Parallel Port Test Grammar Function Calls:
*PARA_OPEN
*PARA_CLOSE
*PARA_SETRAMECTRL
*PARA_SETRETRY
*PARA_INIT
*PARA_ACTIVATEFONT
*PARA_SETTITLE
*PARA_SETWRTTIMEOUT
*PARA_QFRAMECTRL
*PARA_QRETRY
*PARA_QPORT
*PARA_QACTIVEFONT
*PARA_VERIFYFONT
*PARA_QWRTTIMEOUT
*PARA_READFILE
*PARA_WRITEFILE
 
==== PARA_OPEN ====
This function opens the given parallel port.
 
;Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DEVICENAME
|STRING
|Output port identification, such as LPT1
|}
 
;Output Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|}
 
;Logged Data
None.
 
==== PARA_CLOSE ====
This function closes the opened parallel port.
 
;Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
None.
 
==== PARA_SETFRAMECTRL ====
'''Category 05h - Function 42h'''
 
This function sets frame control (characters-per-line, lines-per-inch).
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|-
|CPL
|NUM
|Characters-per-line
|-
|LPI
|NUM
|Lines-per-inch
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Frame Control Message with characters-per-line and lines-per-inch.
 
==== PARA_SETRETRY ====
'''Category 05h - Function 44h'''
 
This function sets infinite retry on/off (0=OFF, 1=ON).
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|-
|RETRY
|NUM
|ON or OFF setting
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Retry state Message with Infinite Retry Disabled/Enabled
 
==== PARA_INIT ====
'''Category 05h - Function 46h'''
 
This function initializes parallel port.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
None.
 
==== PARA_ACTIVATEFONT ====
'''Category 05h - Function 48h'''
 
This function activates a font.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|-
|CODEPAGE
|NUM
|Number of code page
|-
|FONTID
|NUM
|Number of font
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Font information Message with CODEPAGE and FONTID
 
==== PARA_SETTITLE ====
'''Category 05h - Function 4Dh'''
 
This function sets job title.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|-
|JOBTITLE
|STRING
|Job title identification
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Job title information Length and address with job title information.
 
==== PARA_SETWRTTIMEOUT ====
'''Category 05h - Function 4Eh'''
 
This function sets write timeout.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|-
|PPWRTTIMEOUT
|NUM
|Seconds for write timeout
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Write time out value Parallel Port Write Time Out Value in seconds
 
==== PARA_QFRAMECTRL ====
'''Category 05h - Function 62h'''
 
This function queries frame control (characters-per-line, lines-per-inch).
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Frame Control Message with characters-per-line and lines-per-inch.
 
==== PARA_QRETRY ====
'''Category 05h - Function 64h'''
 
This function queries infinite retry.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Retry state Message with Infinite Retry Disabled/Enabled
 
==== PARA_QPORT ====
'''Category 05h - Function 66h'''
 
This function queries port.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|Handle number of output parallel port
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Data Value in data field
 
==== PARA_QACTIVEFONT ====
'''Category 05h - Function 69h'''
 
This function queries active font.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Handle number of output parallel port
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Font information Message with CODEPAGE and FONTID
 
==== PARA_VERIFYFONT ====
'''Category 05h - Function 6Ah'''
 
This function verifies font.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Handle number of output parallel port
|-
|CODEPAGE||NUM||Number of code page
|-
|FONTID||NUM||Number of font id
|}
 
;Output Parameter Keywords
None.
 
;Logged Data
Font information Message with CODEPAGE and FONTID
 
==== PARA_QWRTTIMEOUT ====
'''Category 05h - Function 6Eh'''
 
This function queries write time out.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Handle number of output parallel port
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:
Time out information Message with PP Write Time Out Value in seconds.
 
====PARA_READFILE====
This function reads a file.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Handle number of output parallel port
|-
|FILENAME||STRING||File to be read
|-
|BYTECOUNT||NUM||Number of bytes to read
|-
|$BUFFER||STRING||Buffer to hold data
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:None.
 
====PARA_WRITEFILE====
This function writes a file.
 
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Handle number of output parallel port
|-
|FILENAME||STRING||Name of file to write
|-
|$BUFFER||STRING||Buffer of write data|
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:None.
 
===Description of Test Cases===
Each of the parallel port 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 parallel grammar file.
 
All of the parallel port test cases use the DDTT @IMPORT command to include one script file:
*SYSINFO.TXT
*:The content of the SYSINFO.TXT files is set by the SETINFO.CMD command file. SETINFO.CMD should be executed once to establish values for the following DDTT parameter keywords:
*DEVICENAME - drive name of the parallel port device under test, such as LPT1.
 
All test scripts open and close the parallel port device and verify successful status return 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, the font, timeout, or port), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed.
 
;ACTFONT.SCR:Activates and logs the font identified by the CODEPAGE and FONTID.
;FRAMES.SCR:Sets and queries the frame controls for four combinations of characters-per-line and lines-per-inch.
;INITPAR.SCR:Initializes the parallel port.
;QFONT.SCR:Queries the activefont, logging, CODEPAGE, and FONTID.
;QFRAME.SCR:Queries frame control, logging characters-per-line, and lines-per-inch settings.
;QPARPORT.SCR:Queries the parallel port and logs the value in the data field.
;QPPWTOUT.SCR:Queries write time out and logs time, in seconds.
;QRETRY.SCR:Queries to determine if infinite retry is enabled.
;REQEX.SCR:Requests exclusive access of LPT1 and displays Have exclusive access, pauses for two minutes, and then releases exclusive access. This process requires installation of the generic device driver, GENDRV.SYS.
;RETRY.SCR:Enables infinite retry, queries retry, disables infinite retry, and queries retry, again.
;SETFRAME.SCR:Sets frame control of 80 characters-per-line and 6 lines-per-inch.
;SPPWTOUT.SCR:Sets parallel port write time out value to 10 seconds.
;SRETRY.SCR:Sets infinite retry enabled.
;TITLERD.SCR:Sets jobtitle to BIDI TEST JOB-TITLE, reads file READ.SCR, and writes file.
;VFONT.SCR:Verifies font with CODEPAGE=34000 and FONTID=34000.
 
===Evaluation of Test Case Results===
Unless otherwise stated in the test-case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DDTT, then the token "ERROR" will be written to the corresponding log file.
 
The script files test all of the different parallel port functions. After each script file has finished executing, it will log all of the test information out to a log file. When all of the script files have finished executing, the command file will search all of the log files for any errors that have occurred. The results from this search are stored in the '''RESULTS.TXT''' file.
 
When the command file has completed searching the log files, it also displays the results on the screen. The command file is searching only for the word "ERROR".
 
== PCMCIA Socket Services Device Driver Test Tool ==
This chapter explains explains how to use the Socket Services Device Driver Test Tool.
 
=== Overview ===
PCMCIA Socket Services Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA Socket Services device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). 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 PCMCIA Socket Services function and performance. Errors are reported and are easily isolated to a specific test sequence and API.
 
User input and output from each thread of the PCMCIA Socket Services tests is performed by way of a separate Presentation Manager window. Multi- threaded test cases log all information to a single log file, clearly indicating the actual execution sequence in the event of errors.
 
=== PCMCIA Socket Services Test Architecture ===
The DDTT provides a common front-end parser for test case scripts. The following DDTT PCMCIA-specific files are required:
*DDTPCMC.DLL
*PCMC.GRA.
*PCMCIATS.SYS
 
The C++ source code for DDTPCMC.DLL is available on the ''IBM Developer Connection Device Driver Kit for OS/2''.
 
The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:
*DDTT.EXE
*DDTT.DLL
*GLOBAL.DLL
*GLOBAL.GRA
 
[[Image:Ioddr-12.gif]]
 
=== Installation ===
There are two directory structures in the ''IBM Developer Connection Device Driver Kit for OS/2''that utilize test suites. 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:
 
1.Copy the executable and PCMCIA socket services 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 \TESTPCMC. Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C: \TESTPCMC 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 PCMCIA socket services test suite:
<pre>
[C:\]md testpcmc
[C:\]cd testkpcmc
[C:\testpcmc]copy e:\ddk_x86\testcert\storage\function\pcmcia\socket\*
[C:\testpcmc]copy e:\ddk_x86\testcert\general\ddtt\*
</pre>
2.Copy the PCMCIATS.SYS file to your root system directory. If your system drive is C, execute the following:
[C:\testpcmc]copy PCMCIATS.SYS c:\
 
1.To install the test device driver, add BASEDEV=PCMCIATS.SYS immediately before the following two lines (which are used for a Think Pad system). Other systems use different names for the PCMCIA socket services and Resource Map Utility device drivers. These lines load the system's Resource Map Utility device driver and Socket Services device driver. The PCMCIATS. SYS test device driver enables an IOCtl interface for calling Socket Services from the DDTT script files.
<pre>
BASEDEV=ICRMU01.SYS
BASEDEV=IBM2SS01.SYS
</pre>
2.Next, make sure the following lines are commented out of the CONFIG.SYS file.
<pre>
rem BASEDEV=PCMCIA.SYS
rem DEVICE=VPCMCIA.SYS
rem DEVICE=AUTODRV2.SYS AUTODRV2.INI
rem DEVICE=$ICPMOS2.SYS
</pre>
Loading any of the above PCMCIA support drivers will interfere with Socket Services testing.
 
3.Add C:\TESTPCMC\BIN to the LIBPATH and PATH in CONFIG.SYS.
 
4.Reboot your machine so the new LIBPATH entry and CONFIG.SYS changes take effect.
 
=== Test-Case Execution ===
1.Change to the directory where the socket services test script files were copied, for example C:\TESTPCMC.
 
2.For machines with one socket, start SSSCR1.CMD. For machines with two sockets, start SSSCR2.CMD.
 
3.The output is written to the corresponding filenames with a .LOG extension. After executing the command file, all the log files are concatenated and written into the file SSLOG1.
 
=== DDTT PCMCIA Socket Services Test Grammar Function Calls ===
The following are the names of the PCMCIA Socket Services Test Grammar Function Calls:
*PCMC_OPEN
*PCMC_CLOSE
*PCMC_GETADAPTERCOUNT
*PCMC_ACKINTERRUPT
*PCMC_PRIORHANDLER
*PCMC_SSADDR
*PCMC_ACCESSOFFSETS
*PCMC_GETADAPTER
*PCMC_GETSSINFO
*PCMC_GETVENDORINFO
*PCMC_INQADAPTER
*PCMC_SETADAPTER
*PCMC_VENDORSPECIFIC
*PCMC_GETSOCKET
*PCMC_GETSTATUS
*PCMC_INQSOCKET
*PCMC_RESETSOCKET
*PCMC_SETSOCKET
*PCMC_GETPAGE
*PCMC_GETWINDOW
*PCMC_INQWINDOW
*PCMC_SETPAGE
*PCMC_SETWINDOW
*PCMC_GETEDC
 
=== PCMC_OPEN ===
This function opens the PCMCIA$ test device driver.
 
;Input Parameter Keywords:None.
 
;Output Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|}
;Logged Data:None.
 
=== PCMC_CLOSE ===
This function closes the PCMCIA$ test device driver.
 
;Input Parameter Keywords:
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |
</pre>
 
;Output Parameter Keywords:None.
 
;Logged Data:None.
 
=== PCMC_GETADAPTERCOUNT ===
This function gets the number of adapters supported by Socket Services and the signature "SS".
 
;Input Parameter Keywords:
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |
</pre>
 
;Output Parameter Keywords:None.
 
;Logged Data:Total number of adapters <br />Signature "SS"
 
=== PCMC_ACKINTERRUPT ===
This function gets the oldest status change interrupt information from the PCMCIA$ test device driver.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SOCKET||NUM||Socket number
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:Number of interrupts
 
=== PCMC_PRIORHANDLER ===
This function gets or sets the prior Socket Services handler for the specified adapter.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|MODE||NUM||Function mode where
:0 = function performs a GET
:1 = function performs a SET
|}
 
;Output Parameter Keywords:
 
;Logged Data:Mode ( 0 = Get, 1 = Set )
 
=== PCMC_SSADDR ===
This function gets or sets mode and data area descriptors.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|PROCMODE||NUM||Processor mode where:
:00 = Real Mode
:01 = 16:16 Protect
:02 = 16:32 Protect
:03 = 00:32 Protect
|-
|FUNCTION||NUM||Requested function where:
:0 = Get code and main data segments
:1 = Get additional data segments
:2 = Set additional data segments (NEEDED FOR SET ONLY)
|-
|NUM_SEGS||NUM||Number of additional data segments to GET or SET (NEEDED FOR SET ONLY)
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:Requested function <br />Number of additional data segments to get or set
 
=== PCMC_ACCESSOFFSETS ===
This function gets an array of offsets for low-level, adapter-specific optimized PC card-access routines.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|PROCMODE||NUM||Processor mode where:
:00 = Real Mode
:01 = 16:16 Protect
:02 = 16:32 Protect
:03 = 00:32 Protect
|-
|FUNCTION||NUM||Requested function where:
:0 = Get code and main data segments
:1 = Get additional data segments
:2 = Set additional data segments (NEEDED FOR SET ONLY)
|-
|NUM_DESIRED||NUM||Number of offsets to be reported, a value between 0 and 18
|}
 
;Output Parameter Keywords:None.
 
;Logged Data:Number of offsets supported
 
=== PCMC_GETADAPTER ===
This function gets the current configuration of the specified adapter.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|}
;Output Parameter Keywords:None.
;Logged Data:Adapter Attributes
:IRQ level for status change interrupts
 
=== PCMC_GETSSINFO ===
This function gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported.
{|class="wikitable"
|+Input Parameter Keywords:
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|}
;Output Parameter Keywords:None.
;Logged Data:Compliance<br />Number of adapters <br />First adapter
 
=== PCMC_GETVENDORINFO ===
This function gets information about the vendor that implemented the Socket Services for the specified adapter.
{|class="wikitable"
|+Input Parameter Keywords:
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|}
;Output Parameter Keywords:None.
;Logged Data:Release Number <br />ASCII string describing the implementer
 
=== PCMC_INQADAPTER ===
This function gets the capability information for the specified adapter.
 
;Input Parameter Keywords:
<pre>
|Keyword        |Type    |Description
|----------------+---------+-------------------
|DRIVEHANDLE    |NUM      |Drive handle for
|                |        |PCMCIA device under
|                |        |test
|----------------+---------+-------------------
|ADAPTER        |NUM      |Adapter number
</pre>
 
;Output Parameter Keywords:None.
 
;Logged Data:Number of sockets <br />Number of windows <br />Number of EDCS <br />Contains the information on the adapter capabilities, the IRQ state and level, and the power management specifications.
 
=== PCMC_SETADAPTER ===
This function sets the configuration of the specified adapter.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|ADPSTATE||NUM||Adapter attributes where:
:Bit 0 = Reduce power consumption (1 = True)
:Bit 2 = Preserve State Information (1 = Preserve)
All other bits are reserved and must be zero.
|-
|IRQ||ALNUM||IRQ level to use for status change interrupts (if bit 7 is enabled)
|}
 
;Output Parameter Keywords:None.
;Logged Data:None.
 
=== PCMC_VENDORSPECIFIC ===
This function defines a vendor-specific function for implementing proprietary functions.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SUBFUNCTION||NUM||Subfunction codes where:
:1 = InquireBootSocket
:2 = UnlockBootSocket
|}
;Output Parameter Keywords:None.
;Logged Data:None.
 
=== PCMC_GETSOCKET ===
This function gets the current configuration of the specified socket.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SOCKET||NUM||Socket Number
|}
 
;Output Parameter Keywords:None.
;Logged Data:Interrupt Mask
:Vcc Level
:Vpp Level
:Socket State variables
:Socket Control Variables
:IRQ level and status change interrupts
 
=== PCMC_GETSTATUS ===
This function gets the status of the card in the specified socket on the specified adapter.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SOCKET||NUM||Socket Number
|}
;Output Parameter Keywords:None.
;Logged Data:Card Attributes
:Socket State
:Control and Indicator State
:IRQ level and status change interrupts
 
=== PCMC_INQSOCKET ===
This function gets the capability information for the specified socket.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SOCKET||NUM||Socket Number
|}
;Output Parameter Keywords:None.
 
;Logged Data:Interrupt Capabilities <br />Reporting Capabilities <br />Control Capabilities <br />Socket Characteristics
 
=== PCMC_RESETSOCKET ===
This function resets the PC card in the specified socket.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SOCKET||NUM||Socket Number
|}
;Output Parameter Keywords:None.
;Logged Data:None.
 
=== PCMC_SETSOCKET ===
This function sets the configuration for the specified socket.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|SOCKET||NUM||Socket Number
|-
|INTERRUPTMASK||ALNUM||Status change interrupt mask where:
:Bit 0 = Write Protect Change (must be zero)
:Bit 1 = Card Lock Change (must be zero)
:Bit 2 = Ejection Request (set = enable for PS/2-E)
:Bit 3 = Insertion Request (must be zero)
:Bit 4 = Battery Dead Change (set = enabled)
:Bit 5 = Battery Warning Change (set = enabled)
:Bit 6 = Ready Change (set = enabled)
:Bit 7 = Card Detect Change (set = enabled)
|-
|VCCLEVEL||NUM||Lower nibble - Vcc Level
|-
|VPPLEVEL||NUM||Upper Nibble - Vpp Level, Lower Nibble - Vpp2 Level
|-
|SOCKETSTATE||NUM||Socket state where:
:Bit 0 = Write Protect Change
:Bit 1 = Card Lock Change
:Bit 2 = Ejection Request(For PS/2-E)
:Bit 3 = Insertion Request(must be zero)
:Bit 4 = Battery Dead Change
:Bit 5 = Battery Warning Change
:Bit 6 = Ready Change
:Bit 7 = Card Detect Change
|-
|SOCKETCONTROL||NUM||Socket Control where:
:Bit 4 = Lock Control(PS/2-e only)
:Bit 6 = Busy Status
All other bits are reserved and are set to zero
|-
|IFIRQ||ALNUM||IRQ Steering and Interface Type Control where:
:Bit 0..3 = IRQ Level (0..15) (16..19 must be zero)
:Bit 4    = Reserved (always zero)
:Bit 5    = Reserved (always zero)
:Bit 6    = IRQ Inverter enabled (set to one = enable)
:Bit 7    = IRQ Steering enabled (set to one = enable)
:Bit 8    = Memory only interface (mutually exclusive of I/O and Memory interface)
:Bit 9    = I/O and Memory interface (mutually exclusive of Memory only interface)
All other bits are reserved and are set to zero
|}
;Output Parameter Keywords:None.
;Logged Data:None.
 
=== PCMC_GETPAGE ===
This function gets the current configuration of the specified page in the specified window.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|WINDOW||NUM||Window Number
|-
|PAGE||NUM||Page number
|}
;Output Parameter Keywords:None.
;Logged Data:Page Attributes
:Offset
 
=== PCMC_GETWINDOW ===
This function gets the current configuration of the specified window on the specified adapter.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|WINDOW||NUM||Window Number
|}
;Output Parameter Keywords:None.
;Logged Data:Socket
:Window Size
:Window Attributes
:Access speed
:Window Base Address
 
=== PCMC_INQWINDOW ===
This function gets the capability information for the specified window on the specified window.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|WINDOW||NUM||Window Number
|}
;Output Parameter Keywords:None.
;Logged Data:Capabilities <br />Assignable Sockets
 
=== PCMC_SETPAGE ===
This function sets the configuration for the specified page in the specified window.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|WINDOW||NUM||Window Number
|-
|PGSTATE||NUM||Page Attributes where.
:Bit 0  set = Attribute Memory, reset = Common Memory
:Bit 1  set = Enable, reset = Disable
:All other bits are reserved and must be set to zero
|-
|OFFSET||NUM||4KB units
|}
 
;Output Parameter Keywords:None.
;Logged Data:None.
 
=== PCMC_SETWINDOW ===
This function sets the configuration for the specified window.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|WINDOW||NUM||Window Number
|-
|SOCKET||NUM||Socket number
|-
|SIZE||ALNUM||Number of bytes for I/O, number of 4KB units for memory
|-
|WINSTATE||NUM||Window State where:
:Bit 0  set = Memory, reset = I/O
:Bit 1  set = Enabled, reset = Disabled
:Bit 2  set = 16-bit, reset = 8-bit
All other bits are set to zero
|-
|SPEED||NUM||Actual access speed 1 = 250nSec  Only speed supported
|-
|BASE||ALNUM||Base address where:
:0x00A0 - First Byte addressable
:0x00FF - Last Byte addressable
|}
 
;Output Parameter Keywords:None.
;Logged Data:None.
 
=== PCMC_GETEDC ===
This function gets the current configuration of the specified EDC generator.
 
;Input Parameter Keywords:
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for PCMCIA device under test
|-
|ADAPTER||NUM||Adapter number
|-
|EDC||NUM||EDC generator number
|}
 
;Output Parameter Keywords:Socket <br />State <br />Type
 
=== Description of Test Cases ===
Each of the PCMCIA Socket Services test cases can be executed individually as previously described. The corresponding test scripts are described below. You can create additional tests or combine tests into multi- threaded test cases after becoming familiar with the DDTT and the PCMCIA grammar files.
 
All test scripts close the channels opened to the PCMCIA device and verify successful status return 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 completed.
 
ACKINT.SCR Gets the number of Status Change Interrupts from the test device driver since the last time ACKINT was called. The count is reset to zero.
 
ADAPTER.SCR Calls the SetAdapter function with different values for State and IRQ. SetAdapter sets the configuration for the specified adapter. Each time the SetAdapter function is called, the GetAdapter function is also called to verify the configuration.
 
GETAOFS.SCR Gets an array of offsets for low-level, adapter-specific, optimized PC-card access routines. Can return UNSUPPORTED FUNCTION.
 
GETADP.SCR Gets the current configuration of the specified adapter,
 
GTADPCT.SCR Gets the number of adapters supported by Socket Services and the Signature "SS".
 
GETEDC.SCR Gets the current configuration of the specified EDC generator. Can return UNSUPPORTED FUNCTION.
 
GETPAGE.SCR Gets the current configuration of the specified memory page in the specified window.
 
GETSOC.SCR Formats the information and sends it to the log file.
 
GTSSINF.SCR Gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported.
 
GETSTAT.SCR Gets the status of the card in the specified socket on a specified adapter.
 
GTVNINF.SCR Gets information about the vendor that implemented the Socket Services for the specified PCMCIA adapter.
 
GETWIN.SCR Gets the current configuration of the specified memory window on the specified adapter.
 
GSPRHND.SCR Gets the prior Socket Services handler for the specified socket . Can return UNSUPPORTED FUNCTION.
 
GSSSADR.SCR Gets or sets mode and data area descriptors.
 
INQADP.SCR Gets the capability information for the specified adapter.
 
INQSOC.SCR Gets the capability information for the specified socket.
 
INQWIN.SCR Gets the capability information for the specified window on the specified adapter.
 
INTRUPT.SCR Calls the AckInterrupts function after various combinations of insert and remove operations on the socket. The AckInterrupts function gets the oldest Status Change Interrupt information from the test version of the PCMCIA$ device driver.
 
'''Note:'''Each call to AckInterrupts from the test IOCtl resets the current count of interrupts. This count is kept and reported for diagnostic purposes only.
 
MAXPAGE.SCR Calls the GetPage function with different values for the Window number. GetPage gets the current configuration for the specified Page.
 
MAXWIN.SCR Calls the GetWindow function with different values for the Window number. GetWindow gets the current configuration for the specified Window.
 
RSETSOC.SCR Resets the PC card in the specified socket.
 
'''Note:'''There must be a card in the socket to call this function successfully.
 
SETADP.SCR Sets the configuration of the specified adapter.
 
SETPAGE.SCR Sets the configuration for the specified page in the specified window.
 
SETSOC.SCR Sets the configuration for the specified socket.
 
SETWIN.SCR Sets the configuration for the specified memory window.
 
SETWP.SCR Calls the SetWindow and SetPage functions with different values. After setting the values it calls GetWindow and GetPage to verify configuration.
 
VNSPEC.SCR Defines a vendor-specific function for implementing proprietary functions. Can return UNSUPPORTED FUNCTION.
 
WINDOW.SCR Calls the SetWindow function with different combinations of values for Base, Window and Size. SetWindow sets the configuration for the specified Window. Each time the SetWindow function is called, GetWindow function is called before and after the SetWindow to compare the configuration.
 
==OS/2 Version Compatibility Considerations===
The following table lists any items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.
The following table lists any items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.
{|class="wikitable"
{|class="wikitable"
Line 2,105: Line 131:
|}
|}


== Notices ==
{{DDK-Notices|Date=September 1997|C=1997}}
'''IBM Developer Connection Device Driver Kit for OS/2, Version 4.02 Edition ( September 1997)'''
 
'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:''' INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.
 
=== Copyright Notices ===
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.
 
Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."
 
'''(C) Copyright International Business Machines Corporation 1997. All rights reserved.'''<br />Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
=== Disclaimers ===
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.
 
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
:IBM Director of Licensing
:IBM Corporation
:500 Columbus Avenue
:Thornwood, NY 10594
:U.S.A.
 
=== Trademarks ===
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
:IBM
:Multimedia Presentation Manager/2
:OS/2
:Ultimotion
The following terms are trademarks of other companies:
:Helvetica Linotype Company
:MASM Microsoft Corporation
:Mitsumi Mitsumi Denki Kabushki Kaisha
:Panasonic Matsushita Electric Industrial Co., Ltd.
:OPTi OPTi, Inc.
:Pioneer Pioneer Electric Corporation
:ProAudio Spectrum Media Vision, Inc.
:ProAudio Spectrum 16 Media Vision, Inc.
:QuickVia Jovian Logic Corp.
:ReelMagic Sigma Designs, Inc.
:Sound Blaster Creative Technology Ltd.
:SuperVia Jovian Logic Corp.
:Super VideoWindows New Media Graphics Corporation
:Video Blaster Creative Technology, Inc.
:Yamaha Yamaha Corporation
 
Windows is a trademark of Microsoft Corporation.
 
UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.
 
Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.


== Glossary ==
== Glossary ==

Latest revision as of 16:53, 4 December 2019

Input/Output Device Driver Reference
  1. Advanced Power Management Architecture
  2. APM IOCtl Device Driver Test Tool
  3. Asynchronous (RS232-C) Communications Device Driver
  4. CLOCK$ Device Driver
  5. Joystick Device Driver
  6. Keyboard Device Driver
  7. Keyboard Inter-Device-Driver Communication Interfaces
  8. Keyboard Device Driver Test Tool
  9. Mouse Device Driver
  10. Mouse (DOS) Device Driver Test Tool
  11. Parallel Port Device Driver
  12. Physical Bidirectional Parallel Port Device Driver
  13. Parallel Port Device Driver Test Tool
  14. PCMCIA Architecture
  15. PCMCIA Socket Services Device Driver Test Tool
  16. Touch Display Device Driver
  17. Touch Inter-Device-Driver Communication Interfaces
  18. USB Device Driver Stack for OS/2 Warp
  19. Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

About This Book

The Input/Output Device Driver Reference for OS/2 contains specific character device drivers that are shipped with OS/2. A generic discussion of character and block device drivers can be found in the Physical Device Driver Reference for OS/2 and the Storage Device Driver Reference for OS/2.

How This Book is Organized

Advanced Power Management Architecture describes the Advanced Power Management specification, a component of the OS/2 operating system that is used to manage power (AC/DC) consumption and utilization for PC systems.

APM IOCtl Device Driver Test Tool explains the test tool and its various test cases.

Asynchronous (RS232-C) Communications Device Driver presents the physical asynchronous (RS232-C) communications device driver and describes how it enables OS/2 applications to utilize the RS232-C device hardware.

CLOCK$ Device Driver describes the physical clock device driver.

Joystick Device Driver describes the Advanced OS/2 Joystick Device Driver.

Keyboard Device Driver describes the KBD$ (device-independent) driver.

Keyboard Inter-Device-Driver Communication Interfaces describes the IBMKBD (device-dependent) driver.

Keyboard Device Driver Test Tool describes how to use the keyboard Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of keyboard device drivers.

Mouse Device Driver describes a physical mouse device driver (MOUSE.SYS) whose job it is to detect the types of pointing devices currently installed on the OS/2 operating system. When a pointing device is identified, support for it is set up dynamically.

Mouse (DOS) Device Driver Test Tool describes how to use the mouse Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of mouse device drivers.

Parallel Port Device Driver describes the parallel port device driver, which supports the parallel port device interface for OS/2, Versions 2.0 and later.

Physical Bidirectional Parallel Port Device Driver describes the function the new PAR1284.SYS device driver provides.

Parallel Port Device Driver Test Tool describes how to use the parallel port Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers.

PCMCIA Architecture contains a description of the PCMCIA architecture as it applies to the OS/2 operating system. Also included is a list of the supported functions and information on deviations from the PCMCIA standard.

PCMCIA Socket Services Device Driver Test Tool describes how to use the PCMCIA Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA device drivers.

Touch Display Device Driver introduces and describes the IBM Touch Display device driver, which, in addition to the video cable connection to a VGA/ XGA port, has a touch data cable that attaches to the IBM PS/2 Mouse (pointing device) port on the system unit. OS/2 protect-mode and DOS real-mode applications are supported by the touch component.

Touch Inter-Device-Driver Communication Interfaces describes the IBM interfaces for the Touch Display device driver.

USB Device Driver Stack for OS/2 Warp briefly describes OS/2 USB stack implementation and gives guidelines for host controller driver and class/client driver implementation together with stack driver communication API specification.

Notices contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.

A glossary and an index are included at the back of this book.

Conventions

Double-Byte Character Set

Throughout this publication, there are references to specific values for character strings. These values are for the Single-Byte Character Set (SBCS). When using the Double-Byte Character Set, note that one DBCS character equals two SBCS characters.

Version

Unless otherwise stated, "OS/2" as used in this book refers to the Warp Version of the IBM Operating System/2.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DDSC BBS, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com
US/Canada: 800-627-8363
International: 770-835-9902
International Fax: 770-835-9444

Ordering Information

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.

What's New

A new chapter, #APM IOCtl Device Driver Test Tool is provided. This chapter explains the Advanced Power Management test tool.

A new chapter, #Physical Bidirectional Parallel Port Device Driver was added which describes the PAR1284.SYS device driver.

For information on any items discussed in this reference that have been added to OS/2 beginning with OS/2 Warp Version 3.0 and their compatibility with different versions of OS/2, see #OS/2 Version Compatibility Considerations.

Introduction

Device drivers are software modules that act as an interface between OS/2 (or its applications) and physical devices. In DOS, applications are responsible for knowing and managing all the differences between different devices of like types. The device drivers of OS/2 enable applications to focus on the logic of the actual application and treat devices in a device-independent way.

This device-independence is a fundamental benefit of the OS/2 programming environment. For example, drawing a circle on the screen or on a printer is as easy as opening a device context for the correct output device and performing the drawing operations. By placing the drawing operation into the device context, the programmer does not have to be concerned about whether the device is a printer or a display.

Types of OS/2 Device Drivers

Three types of device drivers are used in OS/2 Version 3:

  • Physical device drivers
  • Virtual device drivers
  • Presentation drivers

Physical Device Drivers

Physical device drivers, in most cases, resolve device-independent input and output (I/O) requests from the operating system and its applications with the device-dependent physical attributes of the device. The physical device drivers shipped with OS/2 Version 3 include support for the following:

  • Advanced Power Management
  • Asynchronous Communication (RS-232C)
  • CD-ROM
  • Hard Disk and Diskette
  • Keyboard
  • Mouse
  • Parallel Port Printer
  • PCMCIA
  • System Clock
  • Touch Screen
  • Video

Virtual Device Drivers

The virtual device driver is an installable module that virtualizes a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers that operate at Ring 0. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.

Further information on virtual device drivers, virtual device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Virtual Device Driver Reference.

Presentation Drivers

The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API call interface, which uses the program stack to communicate with, or pass parameters to, the presentation drivers. These drivers are special purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.

Presentation drivers are dynamic link library modules that are supplied as files and identified by the extension DRV. When the Presentation Manager interface is initialized, the display presentation driver is loaded and enabled automatically. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the DevOpenDC function to open the device.

Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.

Header and include files are shipped with OS/2 to provide support for building presentation drivers that are written in C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Presentation Device Driver Reference.

OS/2 Version Compatibility Considerations

The following table lists any items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.

Item Added or Changed Date Item Added or Changed Compatibility of Addition or Change
Joystick Driver November 1995 OS/2 Warp, Version 3.0 and Later

Notices

IBM Developer Connection Device Driver Kit for OS/2, Version 4.02 Edition (September 1997)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

(C) Copyright International Business Machines Corporation 1997. All rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

  • Common User Access - CUA
  • IBM
  • Information Presentation Facility - IPF
  • Multimedia Presentation Manager/2
  • OS/2 - Operating System/2
  • Ultimotion
  • Ultimedia
  • Presentation Manager - PM
  • System Application Architecture - SAA
  • Workplace Shell

The following terms are trademarks of other companies:

  • ActionMedia - Intel Corporation
  • Adobe- Adobe Systems Incorporated
  • Intel - Intel Corporation
  • Indeo - Intel Corporation
  • PostScript - Adobe Systems Incorporated
  • Times New Roman - Monotype
  • Helvetica - Linotype Company
  • MASM - Microsoft Corporation
  • Mitsumi - Mitsumi Denki Kabushki Kaisha
  • Panasonic - Matsushita Electric Industrial Co., Ltd.
  • OPTi - OPTi, Inc.
  • Pioneer - Pioneer Electric Corporation
  • ProAudio Spectrum Media Vision, Inc.
  • ProAudio Spectrum 16 Media Vision, Inc.
  • QuickVia - Jovian Logic Corp.
  • ReelMagic - Sigma Designs, Inc.
  • RealMagic - Sigma Designs, Inc.
  • Sound Blaster - Creative Technology Ltd.
  • SuperVia - Jovian Logic Corp.
  • Super VideoWindows - New Media Graphics Corporation
  • Video Blaster - Creative Technology, Inc.
  • Yamaha - Yamaha Corporation

Windows is a trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.

Glossary

Retrieved from "https://www.edm2.com/index.php?title=Input/Output_Device_Driver_Reference&oldid=67170"