VIRTUAL DISK DRIVER -- VDDRIVER


This driver implements a "virtual disk" device using a contiguous
container file residing on a real (or other virtual) physical disk.
While previous SIG tapes have contained a VDDRIVER, I had trouble
following what the driver was doing and had reservations
about its handling of segmented virtual I/O.  So, this version
was born.  Assemble and link VDDRIVER by executing the VDBLD.COM
procedure.  The driver is loaded and one unit connected via the
VDLOAD.COM procedure; up to 32 more units may be connected as required.


CAVEAT EMPTOR

Once a virtual disk device is associated with a container file,
the container file must not be deleted or serious file system
errors will occur.  Using the VDASSIGN utility supplied, virtual disk
container files are created with read-only file protection for
system, owner, group and world.  However, this protection will
not block a user with BYPASS privilege from deleting the file.
If anyone knows of a relatively simple, sure fire way to
block file deletion regardless of a user's privileges, please
let the author know.



BASIC LOGIC

VDDRIVER appears to VMS as a normal disk driver complete with
everything except a real physical device.  The IO$_SETCHAR!IO$M_VD_STARTUP
QIO function associates a VDDRIVER unit with a container file
residing on a physical or other virtual disk.  Read and write
QIOs directed to the virtual disk are then remapped based on
the starting logical block number of the container file
on the physical disk and queued to the physical disk driver
to perform the data transfer.

A special case must be recognized when the XQP/ACP segments
a virtual I/O request into multiple contiguous logical block
transfers.  Prior to calling the physical disk driver, VDDRIVER
alters the IRP$L_PID field to force VMS I/O post processing
to recall VDDRIVER.  When called on I/O completion, VDDRIVER
restores the IRP$L_PID field, and resets the IRP$L_UCB field
so the XQP/ACP will queue the next segment to VDDRIVER
rather then the disk driver.  The IRP is then completed
in the normal fashion.



SPECIAL I/O FUNCTIONS -- DEFINITIONS

The VDDEFIN.MAR module declares most of the data structures and special
I/O function code modifiers used by VDDRIVER.  The VD$IODEF macro
contained in VDDRIVER.MLB may be invoked by applications to declare
these symbols for their reference.  These symbols are also declared as
globals and available at link time from the VDDRIVER.OLB object library.



SPECIAL I/O FUNCTIONS -- IO$_SETCHAR/IO$_SETMODE

VDDRIVER uses the IO$_SETCHAR/IO$_SETMODE functions along with
special function modifiers to control the virtual disk:

   IO$M_VD_STARTUP  - Associates the VD unit with a container file.
   IO$M_VD_SHUTDOWN - Disassociates the file from the virtual disk device.

These modifiers are mutually exclusive; specifying more than one
results in SS$_ILLIOFUNC return condition.

The IO$_SETMODE!IO$M_CD_STARTUP QIO function associates the
VDDRIVER device unit assigned to the channel specified in the
QIO "chan" argument (eg. VDA0:, VDA3:) with a container
file.  The container file must have been opened by the process
when the startup function is executed, and QIO parameter 1 (P1)
must specify, by value, the process's channel number assigned to
this container file.  VDDRIVER uses system control structures
(Window and File Control Blocks) associated with this channel/file
to determine the size of the virtual disk and perform some validity
checks on the target file.  On successful completion, the
virtual disk device may be handled like any other physical
disk volume (ie. init, mount, etc.).

The IO$_SETMODE!IO$M_VD_SHUTDOWN disassociates a virtual
disk from the container file.  VDDRIVER makes sure that the
virtual disk has been dismounted (VDDRIVER blocks dismounting
of a virtual disk that contains other virtual disks).



SPECIAL I/O FUNCTIONS -- IO$_SENSECHAR/IO$_SENSEMODE

VDDRIVER uses the IO$_SENSECHAR/IO$_SENSEMODE functions to return
information regarding the virtual disk device.  The standard
IO$_SENSEMODE/SENSECHAR QIO is handled identically to all
other disk devices; the I/O status block returns:

   +--------------------+--------------------+
   |          0         | Status (SS$_NORMAL)|
   +--------------------+--------------------+
   |    # Cylinders     | # Tracks |# Sectors|
   +--------------------+--------------------+

When the special function modifier, IO$M_VD_GETINFO, is specified,
VDDRIVER returns detailed information regarding the virtual disk
device in the user's data buffer defined by QIO parameters
1 (address) and 2 (size).  On return, the contents of the
user's data buffer contains:


   +--------------------+--------------------+  0
   |    Generic device name of host disk     |
   |         (counted ASCII string)          |
   /                    .                    /
   /                    .                    / 
   +--------------------+--------------------+ 16
   |  File number (id)  |   Disk unit number |
   +--------------------+--------------------+ 20
   | Relative vol number|  File sequence num |
   +--------------------+--------------------+ 24
   |     Size of virtual disk in blocks      |
   +--------------------+--------------------+ 28
   |     Starting LBN of container file      |
   +--------------------+--------------------+ 32

and the I/O status block contains:

   +--------------------+--------------------+
   | # bytes in buffer  | Status (SS$_NORMAL)|
   +--------------------+--------------------+
   |         Host disk's UCB address         |
   +--------------------+--------------------+



VIRTUAL DISK UTILITIES

Three utility programs have been supplied in the TEST subdirectory.
The VDASSIGN utility will create a virtual disk container file if
it does not exist and assign a VDDRIVER device unit to the file.
VDDEASSIGN removes the association between the VDDRIVER device and
the container file.  VDINFO may be used to display detailed information
regarding any virtual disk device.

The VDASSIGN utility recognizes the following command format:

	VDASSIGN VDan: file_name[/SIZE=nnn]

   where:
          VDan      - Virtual disk device controller/unit specification
          file_name - Name of the container file
          /SIZE=nnn - Optional parameter specifying size of container file
                      to be created if it does not already exit (default=1024)

The VDDEASSIGN and VDINFO utilities recognize the following command format:

        VDDEASSIGN VDan:
        VDINFO VDan:

   where:
          VDan      - Virtual disk device controller/unit specification



TEST PROGRAMS

A subdirectory of test programs has been included with this submission.
These programs along with the test procedures written for CDDRIVER
may be used checkout VDDRIVER; they may be in various states of
(in)completion so don't judge them too harshly.





                        Paul R. Sorenson
                        AEP/Engineering Computer Support Center
                        1 Riverside Plaza
                        Columbus, OH 43215