Input/Output Device Driver Reference/PCMCIA Socket Services Device Driver Test Tool

Input/Output Device Driver Reference
Advanced Power Management Architecture APM IOCtl Device Driver Test Tool Asynchronous (RS232-C) Communications Device Driver CLOCK$ Device Driver Joystick Device Driver Keyboard Device Driver Keyboard Inter-Device-Driver Communication Interfaces Keyboard Device Driver Test Tool Mouse Device Driver Mouse (DOS) Device Driver Test Tool Parallel Port Device Driver Physical Bidirectional Parallel Port Device Driver Parallel Port Device Driver Test Tool PCMCIA Architecture PCMCIA Socket Services Device Driver Test Tool Touch Display Device Driver Touch Inter-Device-Driver Communication Interfaces USB Device Driver Stack for OS/2 Warp Glossary

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

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

Change to the directory where the socket services test script files were copied, for example C:\TESTPCMC.
For machines with one socket, start SSSCR1.CMD. For machines with two sockets, start SSSCR2.CMD.
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.