DASD IOCtl Device Driver Test Tool

From EDM2
Jump to: navigation, search
Storage Device Driver Reference
  1. About This Book
  2. Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
  3. Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers
  4. Adapter Device Driver Development Considerations
  5. DASD, SCSI, and CD-ROM Device Manager Interface Specification
  6. Error Handling
  7. Adapter Device Driver Command-Line Parameters
  8. DASD IOCtl Device Driver Test Tool
  9. Optical IOCtl Device Driver Test Tool
  10. Using Filter Device Drivers
  11. Library and Services
  12. CD-ROM Device Manager Interface Specification
  13. CD-ROM Device Driver Test Tool
  14. Building an OS/2 Virtual Disk Driver
  15. OS2DASD.DMD - Technical Reference
  16. Boot Record Architecture
  17. Extended Device Driver Interface Specification
  18. I/O Request Block - C Definitions
  19. OS/2 SCSI Device Driver Interface Specification
  20. Advanced SCSI Programming Interface (ASPI) OS/2 Specification
  21. Adapter Device Driver Interface Questions and Answers
  22. Device Driver Test Tool (DDTT)
  23. Glossary

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

This chapter explains how to use the DDTT to test a DASD Device Driver by executing disk/diskette-oriented test scripts.

Overview

DASD functional verification tests exercise the Application Program Interfaces (APIs) - mainly DosDevIOCtl variations - that interface with DASD device drivers. The test environment is defined by the Device Driver Test Tool (DDTT) and each test is written as a DDTT script using Global and DASD grammars. See Device Driver Test Tool (DDTT) for a description of the DDTT. The tests described herein give the user a repeatable set of scripts for verifying disk and diskette functions. They may also be used as examples for creating additional specialized test cases.

As the DDTT parses and executes each test script, it simultaneously creates a disk log file that timestamps the activity and logs each script command. If the command initiates an API call, then the result of the command is logged, be it failure with a return code or success with possible returned data. If the script fails to complete, the log, up to the point of failure, is available for diagnosis.

These tests can be used to verify correct interaction between the DASD device and the following OS/2 components:

  • DOSDevIOCtl API interface
  • FAT and HPFS file systems
  • OS2DASD.DMD, OS2SCSI.DMD and OS2ASPI.DMD device managers
  • SCSI Adapter device drivers
  • Non-SCSI Adapter device drivers

Installation

This CD-ROM contains the executables, libraries, grammars, and test cases necessary to run DASD test suites.

The following procedure describes installation for running test cases:

1. Copy the component files from the Device Driver Kit for OS/2 CD-ROM to the hard drive. All files should reside in a common directory, such as \TDASDIO. If the target directory is C:\TDASDIO and the E: drive contains the information from the Device Driver Kit for OS/2, then use the following commands to copy the DASD test suite:

[C:\]md tdasdio
[C:\]cd tdasdio
[C:\tdasdio]copy e:\ddk\testcert\storage\function\dasd\*
[C:\tdasdio]copy e:\ddk\testcert\general\ddtt\*

2. Add C:\TDASDIO to the LIBPATH and PATH in the CONFIG.SYS file.

3. Reboot your machine so the new LIBPATH entry takes effect.

The following DDTT files are required for execution of CD-ROM scripts:

  • DDTT.EXE
  • DDTT.DLL
  • GLOBAL.DLL
  • GLOBAL.GRA
  • DDTDASD.DLL
  • DASD.GRA

Storage-img1.gif

Test-Case Execution

Test case scripts are driven by the DDTT. The DDTT can be initiated via an OS/2 command line or from a batch file or REXX statement:

[C:\TDASDIO]DDTT DASDSTD1.SCR

The DDTT creates a Presentation Manager thread window that consists of:

  • a multi-line, scrolled output field for logging script progress
  • a single-line entry field for operator input
  • a single-line text output field for script-initiated prompts and messages

The DDTT DASD tests must be executed on a directly-attached DASD device. These tests will not work when executed against a DASD device accessed by way of a network connection.

DASD IOCtl Test Grammar Function Calls

The following is a list of DASD IOCtl Test Grammar Function Calls:

  • DASD_OPEN
  • DASD_CLOSE
  • LOCK_LOGICAL
  • UNLOCK_LOGICAL
  • QUERY_LOCK
  • GET_LOGICAL_PARAMS
  • QMEDIA_SENSE
  • QLOGICAL_MAP
  • SET_LOGICAL_MAP
  • BLOCK_REMOVABLE
  • REDETERMINE_MEDIA
  • READ_LOGICAL
  • WRITE_LOGICAL
  • VERIFY_LOGICAL
  • FORMAT_TRACK
  • OPEN_PHYSICAL
  • CLOSE_PHYSICAL
  • LOCK_PHYSICAL
  • UNLOCK_PHYSICAL
  • GET_PHYSICAL_PARAMS
  • QUERY_DISK_COUNT
  • WRITE_PHYSICAL
  • READ_PHYSICAL
  • VERIFY_PHYSICAL
  • READ_FILE
  • WRITE_FILE
  • SET_DEVICEPARAMS
  • CHECKRETURN
  • CHECKVALUE

DASD_OPEN

This function opens a logical partition on a physical drive. In the case of removable media devices, the entire device will be opened. The media must be mounted for successful completion.

Input Parameter Keywords
Keyword Type Description
DEVICENAME STRING Drive letter for logical disk
Output Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Logged Data

None.

DASD_CLOSE

This function closes a logical partition on a physical drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
DDRC NUM Function return code
Output Parameter Keywords

None.

Logged Data

None.

LOCK_LOGICAL

Category 8h Function 00h - Lock Drive This function locks a logical partition on a physical drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data

None.

UNLOCK_LOGICAL

Category 8h Function 01h - Unlock Drive This function unlocks a logical partition on a physical drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

QUERY_LOCK

Category 8h Function 66h - Get Lock Status This function indicates if the drive is locked with or without media in it.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
PRESENCE NUM Media presence flag
LOCKCODE NUM 2-bit lock code
DDRC NUM Function return code
Logged Data
Lock status and Lock/Unlock/Eject command support statement
Media presence status

GET_LOGICAL_PARAMS

Category 8h Function 63h - Query Device Parameters This function gets the logical parameters for the addressed drive. Not all parameters are defined for all drive types.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
SECTORSIZE NUM Sector size in bytes
CLUSTERSIZE NUM Cluster size in sectors
FATCOUNT NUM Number of FATs
ROOTCOUNT NUM Number of root directory entries
SECTORCOUNT NUM Number of sectors (small disk)
FATSIZE NUM Number of sectors per FAT
TRACKSIZE NUM Size of tracks
HEADCOUNT NUM Number of heads
CYLINDER NUM Number of physical drive cylinders
HIDDEN NUM Number of hidden sectors
RESERVED NUM Number of reserved sectors
LGSECTORCOUNT NUM Number of sectors (large disk)
$SECTORCOUNT NUM Applicable sector count
DEVICETYPE NUM Device layout code
MEDIATYPE NUM Media descriptor
HARDDISK NUM Hard disk flag (1=yes)
ADDR16 NUM 16MB size flag (1=greater)
DDRC NUM Function return code
Logged Data (where defined)
Size of sectors
Size of clusters
Fat count
Root directory size
Number of sectors per FAT
Sectors per track
Reserved sector count
Hidden sector count
Number of heads
Total sector count
Number of cylinders
Media descriptor
Device attributes

QMEDIA_SENSE

Category 8h Function 60h - Query Media Sense This function returns the media sense information for a removable media drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data

Media Sense Information

Returns a byte that corresponds to the type of disk that is in the 3.5-inch drive. Where:
1 = 702KB Disk
2 = 1.44MB Disk
3 = 2.88MB Disk

QLOGICAL_MAP

Category 8h Function 21h - Query Logical Map This function returns the logical drive letter that was last used to reference (open) the drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data

Logical drive number of the last drive letter that was used to reference the drive (or zero if only one drive is defined).

SET_LOGICAL_MAP

Category 8h Function 03h - Set Logical Map This function sets the next logical drive letter that is used to reference the drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
Logical drive currently mapped to the drive opened per the file handle specified.

BLOCK_REMOVABLE

Category 8h Function 20h - Block Removable This function is used to determine if the media is removable or fixed.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
REMOVABLE NUM 1 if true; 0 if false
Logged Data

Removable Media Returns a byte that specifies if the media is removable or not. Where:

0 = Removable media
1 = Nonremovable media

REDETERMINE_MEDIA

Category 8h Function 02h - Redetermine Media This function redetermines the media for removable media devices.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

READ_LOGICAL

Category 8h Function 64h - Read Track This function reads sectors from a logical partition on a physical drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
HEAD NUM The target head value
CYLINDER NUM The target cylinder value
SECTORSTART NUM The target start sector value
TRACKSIZE NUM Track size in sectors
SECTORSIZE NUM Sector size in bytes
SECTORCOUNT NUM Number of sectors to be read
$BUFFER STRING Buffer name
Output Parameter Keywords
Keyword Type Description
BUFFER NUM Pointer to Read buffer
DDRC NUM Function return code
Logged Data
None.

WRITE_LOGICAL

Category 8h Function 44h - Write Track This function writes sectors to a logical partition on a physical drive. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer. The sector count is defaulted to the read buffer size.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
HEAD NUM The target head value
CYLINDER NUM The target cylinder value
SECTORSTART NUM The target start sector value
TRACKSIZE NUM Track size in sectors
SECTORSIZE NUM Sector size in bytes
$BUFFER STRING Name of an existing Read buffer
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

VERIFY_LOGICAL

Category 8h Function 65h - Verify Track This function verifies sectors in a logical partition on a physical drive.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
HEAD NUM The target head value
CYLINDER NUM The target cylinder value
SECTORSTART NUM The target start sector
TRACKSIZE NUM Track size in sectors
SECTORSIZE NUM Sector size in bytes
SECTORCOUNT NUM Number of sectors to verify
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

FORMAT_TRACK

Category 8h Function 45h - Format Track This function formats and verifies a track. (Removable media devices only. )

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM File handle for DASD device being tested
HEAD NUM The target head value
TRACKSIZE NUM Track size in sectors
SECTORSIZE NUM Sector size in bytes
TRACKNUM NUM Number of tracks to format
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

OPEN_PHYSICAL

This function opens a physical disk. It will only operate on drives designated as fixed disks. This may or may not correspond to the physical characteristics of the drive.

Input Parameter Keywords
Keyword Type Description
DISKNUMBER STRING Disk number of DASD device to test.

Example: 1: for first fixed disk

Output Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Disk handle for the request
DDRC NUM Function return code
Logged Data
None.

CLOSE_PHYSICAL

This function closes a physical disk.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

LOCK_PHYSICAL

Category 9h Function 00h - Lock Physical This function locks a physical disk.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

UNLOCK_PHYSICAL

Category 9h Function 01h - Unlock Physical This function unlocks a physical disk.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

GET_DISK_COUNT

Query Number of Physical Disks This function returns the number of system physical disks.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
Output Parameter Keywords
Keyword Type Description
DISKCOUNT NUM Number of system hard disks
DDRC NUM Function return code
Logged Data
System hard disk count.

GET_PHYSICAL_PARAMS

Category 9h Function 01h - Query Physical Device Parameters This function gets the parameters of a physical disk.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
Output Parameter Keywords
Keyword Type Description
CYLINDERCOUNT NUM Number of cylinders on the physical disk
HEADCOUNT NUM Number of heads on the physical disk
TRACKSIZE NUM Number of sectors per track on the physical disk
DDRC NUM Function return code
Logged Data
Number of cylinders on the physical disk
Number of heads on the physical disk
Number of sectors per track on the physical disk

WRITE_PHYSICAL

Category 9h Function 44h - Write Physical This function writes to a physical disk. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
HEAD NUM The physical head on the drive
CYLINDER NUM The cylinder to write to
SECTORSTART NUM The target start sector
SECTORSIZE NUM Sector size in bytes
TRACKSIZE NUM Track size in sectors
$BUFFER STRING Name of Read buffer
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

READ_PHYSICAL

Category 9h Function 64h - Read Physical This function reads sectors from a physical disk.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
HEAD NUM The physical head on the drive
CYLINDER NUM The cylinder to read from
SECTORSTART NUM The target start sector
SECTORCOUNT NUM The number of physical sectors to read
SECTORSIZE NUM Sector size in bytes
TRACKSIZE NUM Track size in sectors
$BUFFER STRING Name of Read buffer
Output Parameter Keywords
Keyword Type Description
BUFFER NUM Pointer to Read buffer
DDRC NUM Function return code
Logged Data
None.

VERIFY_PHYSICAL

Category 9h Function 65h - Verify Physical This function verifies sectors on a physical disk.

Input Parameter Keywords
Keyword Type Description
DISKHANDLE NUM Open handle for disk being tested
HEAD NUM The target head value
CYLINDER NUM The target cylinder value
SECTORSTART NUM The target start sector
SECTORCOUNT NUM The number of physical sectors to verify
SECTORSIZE NUM Sector size in bytes
TRACKSIZE NUM Track size in sectors
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

READ_FILE

This function reads from a disk file.

Input Parameter Keywords
Keyword Type Description
FILENAME STRING The qualified name of the file to read
BYTESTART NUM The byte offset within the file
BYTECOUNT NUM The number of bytes to read
$BUFFER STRING Name of the Read buffer
Output Parameter Keywords
Keyword Type Description
BUFFER NUM Read buffer reference
DDRC NUM Function return code
Logged Data
None.

WRITE_FILE

This function writes to a disk file. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer.

Input Parameter Keywords
Keyword Type Description
FILENAME STRING The qualified name of the target file
BYTESTART NUM The byte offset within the file
$BUFFER STRING Name of the Read buffer
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

SET_DEVICEPARAMS

Category 8h Function 43h - Set Device Parameters This function sets the device parameters. Input parameters are most easily set by issuing a GET_DEVICEPARAMS.

Input Parameter Keywords
Keyword Type Description
DRIVEHANDLE NUM Drive handle for DASD device being tested
SECTORSIZE NUM Sector size in bytes
CLUSTERSIZE NUM Cluster size in sectors
FATCOUNT NUM Number of FATs
ROOTCOUNT NUM Number of root directory entries
HIDDEN NUM Number of hidden sectors
RESERVED NUM Number of reserved sectors
LGSECTORCOUNT NUM Number of sectors (large disk)
SECTORCOUNT NUM Number of sectors (small disk)
FATSIZE NUM Number of sectors per FAT
TRACKSIZE NUM Size of the tracks on the specified device
HEADCOUNT NUM Number of heads on the physical disk
CYLINDER NUM The number of cylinders
MEDIATYPE NUM Media descriptor
DEVICETYPE NUM Device layout code
ADDR16 NUM 16MB size flag (1=greater)
HARDDISK NUM Hard disk flag (1=yes)
Output Parameter Keywords
Keyword Type Description
DDRC NUM Function return code
Logged Data
None.

CHECKRETURN

Check Return Code Diagnostic Function This function verifies that the return code from a previous function is equal to a given value. The function is used for error testing to verify expected return codes. It is assumed that a previous function has set the DDRC parameter. $RC is set by the script author to the expected value.

Required Input Parameter Keywords
Keyword Type Description
$RC NUM The expected return code
Logged Data
Message stating the result of the comparison - either failure or success.

CHECKVALUE

Check Parameter Value Diagnostic Function This function verifies that a parameter returned by a previous DASD function is equal to a given numeric value. $PARM must be explicitly equated to the parameter being tested and $EXPECT set to the expected value.

Required Input Parameter Keywords
Keyword Type Description
$PARM NUM The returned parameter value
$EXPECT NUM The expected value
Logged Data
Message stating the result of the comparison - either failure or success.

Description of Test Cases

Each of the DASD test cases can be executed by invoking the DDTT from either a command line, a batch file, or a REXX file. Test scripts are described below. The user is free to create additional tests or construct multi-threaded test cases after becoming familiar with the DDTT and the DASD grammar files. Test scripts generally start by opening to the physical or logical disk and closing at completion. File operations do not require Open or Close operations as they do this internally. All test scripts log information to a log file of the same file name, but with a file name extension of .LOG. When lock status or device parameters are queried, the data is written to the DDTT's scroll output window and to the log file. Log files can be examined with a text editor after the test case has completed. Disk sectors are addressed by cylinder, head, and sector. The maximum values for these parameters can be found with either GET_LOGICAL_PARAMS or GET_PHYSICAL_PARAMS.

DASDSTD1.SCR
This script exercises all DASD physical API commands. It should be directed to a fixed disk not currently booted.
DASDSTD2.SCR
This script exercises all DASD logical API commands. It should be directed to a logical drive on a fixed disk, preferably not the boot partition.
DASDERR1.SCR
This script exercises the device driver's ability to detect errors related to invalid data and invalid command sequences for a physical disk. It requires a fixed disk target.
DASDERR2.SCR
This script exercises the device driver's ability to detect errors related to invalid data and invalid command sequences for a logical disk. It requires a fixed disk target.
FLOPSTD.SCR
This script exercises all DASD logical API commands for a removable media device. It should be directed to a floppy drive. This test script should be copied to the floppy media where it will serve as the test file.
FLOPFILE.SCR
This script exercises file-oriented API commands for a removable media device. It should be directed to a floppy drive. This test script should be copied to the floppy media where it will serve as the test file.
FLOPERR.SCR
This script exercises the device driver's ability to detect errors related to invalid handle and device-not-ready conditions. It requires a removable media target drive.
FLOPERR2.SCR
This script exercises the device driver's ability to detect errors related to invalid data conditions. It requires a removable media target drive.
FLOPZIP.SCR
This script exercises all DASD logical API commands for a removable media device. It should be directed to drives that use media larger than a standard floppy diskette.

Evaluation of Test Case Results

Standard (non-error) test cases are expected to succeed and there should be no ERROR statements in the logs. However, the Lock command may fail if the system has already locked the logical or physical drive. For this reason, it is suggested that if possible the target drive (logical or physical) be one that is defined but inactive. Error test cases will have many ERROR statements but should have no failure statements. Failure statements indicate that an expected error code was not received. Test case logs need to be examined to verify that data is returned as expected. Not all returned data is automatically checked. Script comments will note what data is expected.