Input/Output Device Driver Reference/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: The C++ source code for DDTPCMC.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2.
 * DDTPCMC.DLL
 * PCMC.GRA.
 * PCMCIATS.SYS

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

 * 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:
 * Logged Data:None.

PCMC_CLOSE
This function closes the PCMCIA$ test device driver.


 * Input Parameter Keywords:


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


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


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


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


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


 * 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:
 * 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. Number of adapters First adapter
 * Output Parameter Keywords:None.
 * Logged Data:Compliance

PCMC_GETVENDORINFO
This function gets information about the vendor that implemented the Socket Services for the specified adapter. ASCII string describing the implementer
 * Output Parameter Keywords:None.
 * Logged Data:Release Number

PCMC_INQADAPTER
This function gets the capability information for the specified adapter.


 * Input Parameter Keywords:
 * 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:


 * Output Parameter Keywords:None.
 * Logged Data:None.

PCMC_VENDORSPECIFIC
This function defines a vendor-specific function for implementing proprietary functions.


 * Input Parameter Keywords:
 * Output Parameter Keywords:None.
 * Logged Data:None.

PCMC_GETSOCKET
This function gets the current configuration of the specified socket.


 * Input Parameter Keywords:


 * 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:
 * 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:
 * Output Parameter Keywords:None.

Reporting Capabilities Control Capabilities Socket Characteristics
 * Logged Data:Interrupt Capabilities

PCMC_RESETSOCKET
This function resets the PC card in the specified socket.


 * Input Parameter Keywords:
 * Output Parameter Keywords:None.
 * Logged Data:None.

PCMC_SETSOCKET
This function sets the configuration for the specified socket.


 * Input Parameter Keywords:
 * 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:
 * 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:
 * 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.

Assignable Sockets
 * Input Parameter Keywords:
 * Output Parameter Keywords:None.
 * Logged Data:Capabilities

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


 * Input Parameter Keywords:


 * Output Parameter Keywords:None.
 * Logged Data:None.

PCMC_SETWINDOW
This function sets the configuration for the specified window.


 * Input Parameter Keywords:


 * Output Parameter Keywords:None.
 * Logged Data:None.

PCMC_GETEDC
This function gets the current configuration of the specified EDC generator.


 * Input Parameter Keywords:


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