Building an OS/2 Virtual Disk Driver
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 | 13h |
Set Logical Drive Map | 1Ah |
No Caching (Write With Verify) | 1Dh |
Get 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:
- Add the TOOLS directory to the OS/2 IBM Developer Connection Device Driver Kit for OS/2 and set it to the current path.
- Set the TMP environment variable to point to a work area. This is shown below:
SET TMP=E:\ - NMAKE the following makefiles in the DDK:
SRC\DEV\VDISK\MAKEFILE
CD\DDK\SRC\DEV\VDISK
NMAKE