Input/Output Device Driver Reference

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.

The Physical Device Driver Reference
The Storage Device Driver Reference
The Input/Output Device Driver Reference
The Pen for OS/2 Device Driver Reference
The Virtual Device Driver Reference
The Presentation Device Driver Reference
The Display Device Driver Reference
The Printer Device Driver Reference
The Graphics Adapter Device Driver Reference
The MMPM/2 Device Driver Reference (Multimedia)

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.

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

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:
[C:\]md testpara

[C:\]cd testpara

[C:\testpara]copy e:\ddk_x86\testcert\inputout\function\parallel\*

[C:\testpara]copy e:\ddk_x86\testcert\general\ddtt\*
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:
DEVICE=c:\testpara\gendrv.sys
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:

 [C:\TESTPARA]DDTT QFONT.SCR

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:

 PLEASE ENTER THE OUTPUT PORT OF YOUR PRINTER, SUCH AS LPT1

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

Keyword	Type	Description
DEVICENAME	STRING	Output port identification, such as LPT1

Output Parameter Keywords

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
FILENAME	STRING	Name of file to write
$BUFFER	STRING

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

Installation

There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2that 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/2CD-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/2CD-ROM disc, then use the following commands to copy the PCMCIA socket services test suite:

[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\*

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.

BASEDEV=ICRMU01.SYS
BASEDEV=IBM2SS01.SYS

2.Next, make sure the following lines are commented out of the CONFIG.SYS file.

rem BASEDEV=PCMCIA.SYS
rem DEVICE=VPCMCIA.SYS
rem DEVICE=AUTODRV2.SYS AUTODRV2.INI
rem DEVICE=$ICPMOS2.SYS

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

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

|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |

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

|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |

Output Parameter Keywords: None.

Logged Data: Total number of adapters
Signature "SS"

PCMC_ACKINTERRUPT

This function gets the oldest status change interrupt information from the PCMCIA$ test device driver.

Input Parameter Keywords

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

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

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
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

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

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.

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
Number of adapters
First adapter

PCMC_GETVENDORINFO

This function gets information about the vendor that implemented the Socket Services for the specified adapter.

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
ASCII string describing the implementer

PCMC_INQADAPTER

This function gets the capability information for the specified adapter.

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: Number of sockets
Number of windows
Number of EDCS
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

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

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

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

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

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
Reporting Capabilities
Control Capabilities
Socket Characteristics

PCMC_RESETSOCKET

This function resets the PC card in the specified socket.

Input Parameter Keywords

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

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

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

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

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
Assignable Sockets

PCMC_SETPAGE

This function sets the configuration for the specified page in the specified window.

Input Parameter Keywords

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

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

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
State
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.

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.

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

IBM SDK/DDK Glossary