Building an OS/2 Virtual Disk Driver

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 describes how to program and build an OS/2 virtual disk driver. In order to successfully build a virtual disk driver, should be familiar with the OS/2 2.0 operating system or later, and have previous experience developing OS/2 device drivers.

In the IBM Developer Connection Device Driver Kit for OS/2, you will find an OS/2 virtual disk driver. After reading this chapter and examining the code, you can use this information to write your own virtual device driver.

Virtual Disk Driver Code

The virtual disk driver code provides access to a virtual disk in random access memory. The virtual disk driver runs in a multi-tasking environment and is a protected resource.

In this chapter you will find:

  • A table listing the virtual disk parameters
  • A table listing the virtual disk commands
  • An explanation of how the virtual disk initialization routine works
  • Information for performing time-critical tasks
  • A procedure for building the virtual disk device driver code that is provided with the IBM Device Driver Source Kit for OS/2

Using the Virtual Disk Parameters: To allocate the virtual disk driver volume, modify the following device statement in the CONFIG.SYS file.

DEVICE = .\PATHNAME\VDISK.SYS [bbbb] [ssss] [dddd]

Where:

bbbb
Determines the disk size in K bytes. The default value is 64KB. The minimum is 16KB. The maximum is 524 288 (512MB).
ssss
Determines the sector size in bytes. The default value is 128. Acceptable values are increments of 128 which include 128, 256, 512, and 1024.
dddd
Determines the number of root directory entries. The default is 64; with a minimum of 2 and a maximum of 1024. The value is rounded up to the nearest sector size boundary.

The virtual disk driver adjusts the value of dddd to the nearest sector size boundary. For example if you give a value of 25, and the sector size is 512 bytes, 25 will be rounded up to 32 which is the next multiple of 16. The parameters you use to specify byte and sector size and the number of directory entries are positional parameters. This means that if you omit a parameter, you should not leave it blank. You should use a comma in the parameter field to separate this field from the next. The only time you can use blank spaces as separators is in the instance where you are coding blanks for all the parameters. In the event that there is not enough memory to create the virtual disk driver volume, the driver attempts to create a DOS volume with 16 directory entries. This may result in a volume with a different number of directories than you specified on the device statement (dddd). To ensure system reliability, specify 32 megabytes or less for disk size.

Example 1

C:\OS2\VDISK.SYS ,128,64

where the disk size is 64KB, the sector size is 128 bytes, and there are 64 directory entries.

Example 2

C:\OS2\VDISK.SYS 2048,,32

where the disk size is 2 048 KB, the sector size is 128 bytes, and there are 32 directory entries.

Example 3

C:\OS2\VDISK.SYS 2048,512,

where the disk size is 2 048 KB, the sector size is 512 bytes, and there are 64 directory entries.

Example 4

C:\OS2\VDISK.SYS ,128,32

where the disk size is 64 KB, the sector size is 128 bytes, and there are 32 directory entries.

Supported Physical Device Driver Strategy Commands: The virtual disk driver is a block device driver and cannot be partitioned. For this reason, the virtual disk driver uses a limited set of physical device driver strategy commands. These are listed below:

CodeFunction 0h
Init 1h
Media Check 2h
Build BPB 4h
Read (Input) 8h
Write (Output) 9h
Write With Verify Dh
Open Device Eh
Close Device Fh
Removable Media 10h
Generic IOCtl 11h
Reset Media 12h

Get Logical Drive Map 13hSet Logical Drive Map 1AhNo Caching (Write With Verify) 1DhGet Driver Capabilities If the virtual disk driver uses any commands other than those shown above, the driver returns an unknown command error code. For more information on these commands, refer to the OS/2 Physical Device Driver Reference. The virtual disk driver supports the Extended Device Driver Interface which is implemented through the Get Driver Capabilities command. This interface issues a Request List of prioritized commands. VDisk_Strat2, specified in the driver capabilities structure, is the entry point for all the commands. CHKDSK uses the category 08h and function 63h IOCtl command from the kernel . This is the only command supported by the virtual disk driver in the general IOCtl commands category. Virtual Disk Driver Initialization: The virtual disk driver initialization routine does the following:

  • Initializes various global values and initializes the DevHelp function router address.
  • Parses the command line and sets the values accordingly.

The "DEVICE = xxxxxxxxx" line pointer provided in request packet searches for the various device parameters. The pointer searches through the device name field to obtain the arguments. Then the pointer parses the arguments as they are encountered. All parameter errors are detected at this time. The static initialization routine sets the parameter variables to the default settings.

  • Allocates the memory for the virtual disk driver.

The routine issues the DevHlp_VMAlloc command to allocate random access memory for the virtual disk driver.

  • Initializes the DOS volume in random access memory for the virtual disk driver.

To so, the routine sets the BPB and initializes the RESERVED (boot) sector, FAT sectors, and root directory sectors and writes them to the virtual disk driver. First the routine initializes the BPB values. Then the routine writes the BOOT record, containing the BPB, to sector 0. The routine writes to a FAT file with all of the clusters free, and writes to the root directory with ONE entry (the Volume ID at VOLID).

  • Prints a report of the RAMDrive parameters.

You can print the BPB values. To do so, use the DosGetMessage and DosPutMessage functions in your virtual disk driver. From this report, you can determine the device size, cluster size, and directory size.

  • Specifies the return INIT I/O packet values.

The INIT I/O packet return values for number of units are set, as well as the BPB array pointer.

At any time during the initialization steps an error may be detected. When this happens, the system prints an error message. The virtual disk driver uninstalls and returns a unit count of 0 in the INIT device I/O packet.

Performing Time-Critical Tasks: To perform time-critical tasks, you must call the DevHlp_GetDOSVar service from the virtual disk driver code. The virtual disk driver periodically checks the TCYield flag and calls the TCYield function to yield the CPU to a time-critical thread. The location of the TCYield flag is obtained from a call to DevHlp_GetDosVar. The virtual disk driver checks the TCYield flag each time 32,768 bytes of data have been transferred. Refer to the OS/2 Physical Device Driver Reference for more information.

Building the OS/2 2.0 (and later) Virtual Disk Driver sample code: To build the sample virtual disk driver code, complete the following steps:

  1. Add the TOOLS directory to the OS/2 IBM Developer Connection Device Driver Kit for OS/2 and set it to the current path.
  2. Set the TMP environment variable to point to a work area. This is shown below:
    SET TMP=E:\
  3. NMAKE the following makefiles in the DDK:
    SRC\DEV\VDISK\MAKEFILE
    CD\DDK\SRC\DEV\VDISK
    NMAKE