Virtual Disk Driver Package for RSX-11M-Plus User Guide and Release Notes Version 3.00 February 9, 1987 1.0 Introduction This package consists of an upgrade of the Virtual Disk software for RSX originally written by Ralph Stamerjohn, and later modi- fied by R. Mearns and Glen Everhart. Substantial changes have been made to the package. The driver and utilities have been rewritten, and incorporate the following new features: 1. Shadowing support 2. Dynamic device database creation 3. Device naming liberties 4. Up to sixteen container files per device 5. Use of secondary pool for data structures 6. Use of advanced RSX-11M-Plus features This package is designed to work with RSX-11M-Plus systems, Ver- sion 3.0 and higher. Changes are required to the RSX Executive to support this package under earlier versions. The components of the package utilize the device mnemonic "VF" as opposed to "VD" or "VE." This was done so that the new package may coexist with the earlier releases. 2.0 How to use the package Briefly, the following steps are used to create, assign, and deassign a virtual disk: - Load the Virtual Disk driver (VF:) - Bring the prototype unit (VF0:) online - Use AVF to assign a virtual disk to a container file - 1 - Virtual Disk Driver Version 3.00 User Guide and Release Notes - Mount the virtual disk and operate on it - Dismount the virtual disk - Use DVF to deassign the virtual disk The following sections describe these steps in detail. 2.1 Loading the Virtual Disk Driver The virtual disk driver, VF:, is loaded in the same manner as any other normal RSX device driver. The driver may be loaded into a system image file using VMR, or it may be loaded at anytime into a running system. Refer to the VMR LOA and MCR LOA command do- cumentation for driver load options. The driver code occupies 349. words of memory. (It is larger if packet logging support is enabled.) The driver database consists of a single unit, VF0:, and its corresponding DCB, UCB, and SCB. Since the virtual disk has no controller, there is no CTB or KRB. 2.2 Bring the Prototype Unit Online Before using any virtual units, the prototype unit, VF0:, must be brought online using the Online Reconfiguration utility, CON. This will happen automatically if the driver is loaded into the system before the typical "CONFIGURE ONLINE ALL" command is is- sued during system startup. Even though VF0: must be brought online, this unit is _n_e_v_e_r used. The purpose for the prototype unit is twofold. First, VF0: is the "mold" used to create additional virtual disk units as they are created. Second, VF0: acts as a listhead of all virtual units in the system. All virtual units are linked to- gether through a special pointer in the UCB. This list is used to verify that all virtual units have been deassigned before the VF: driver is unloaded. 2.3 Assigning a Virtual Disk A virtual disk is created by the utility AVF (Assign Virtual Disk). The AVF command line uses the format: >AVF ddnn:/outswitch = filespec1/insw [, filespec2/insw ...] "ddnn:" is the name of the virtual disk to be assigned. This may be a device not already defined in the system, or a previously created virtual disk which is currently unassigned. If the vir- tual device is not already defined in the system, AVF creates a - 2 - Virtual Disk Driver Version 3.00 User Guide and Release Notes new device database from the prototype database (VF0:). "filespec1" is the name of the first container file whose con- tents become the logical contents of the virtual device. A con- tainer file may be any contiguous file on a file-structured disk volume. Up to sixteen container files may be "concatenated" into one virtual disk. (The limit of sixteen container files may be changed by editing the assembly prefix file, VFPRE.MAC.) Con- tainer files may reside on different disk volumes (including other virtual disks), as long as they are mounted volumes. Output switches ("/outswitch") are used to set characteristics of the virtual device. These switches are: /WP -- Virtual device is to be read-only (write-protected) /ONL -- Bring device online after creation (default action) Input switches ("/insw") are used to create and set characteris- tics of the container files. These switches are: /CR:nnnn -- Create a container file "nnnn" blocks large /RO -- Container file is read-only (denies write attempts) /LO -- Lock container file from future access by others /IN -- Increment volume transaction count on target device The default settings for input switches are: /-CR/-RO/LO/IN. AVF may accept an indirect command file as input. Indirect com- mand files may be nested to a depth of three. 2.4 Deassigning Virtual Disks Deassigning a virtual disk involves the following steps: verify- ing that the device is quiescent, deaccessing the container files, deleting the secondary control block structure, and mark- ing the device offline. The syntax for DVF (Deassign Virtual Disk) is: >DVF ddnn: where "ddnn:" is the name of the Virtual Disk to be assigned. There are no switches for the DVF command. DVF can accept input from an indirect command file. - 3 - Virtual Disk Driver Version 3.00 User Guide and Release Notes 2.5 Creating Virtual Devices There is great flexibility allowed in naming the Virtual Disk. Any valid RSX device name with a two letter mnemonic and an octal unit number from 0 to 377 is valid. This can offer the benefit of creating Virtual Disks whose names offer insight into their function. For example, two shadowed Virtual Disks which collect data may be called SD0: and SD1:, for "Shadowed Disk 0 and 1." A new device database is created for a Virtual Disk if the device name and unit number do not already exist in the system. Once a database is created, it remains in the system until the system is rebooted. The database is not deleted due to potential side ef- fects, as other system data structures may still point to the da- tabase after the database is deleted. An existing database for a Virtual Disk may be reused repeatedly. This is recommended over creating a new database for each use. 2.6 Creating Container Files A container file is simply a contiguous file on a mounted volume. It does not necessarily have to be created by AVF; as long as it is contiguous, AVF will accept it. If AVF is used to create a container file (/CR:nnnn), it will create the file with a default protection of System:RW, Owner:RW, Group:RW, and World:None. If this is not satisfactory, a Global Definition in the Task Build command file for AVF may be changed to set a different protection level for created files. AVF must have write access to the directory into which the new container file is entered. If this is not the case, an error message is printed, and the space for the container file is deal- located. 2.7 Accessing Existing Container Files When accessing an existing container file, AVF must be running from a UIC with sufficient privilege to access the file. By default, which may be overridden by a switch option, AVF locks the container file from additional read or write access. This action is recorded in the Virtual Disk database so that DVF will unlock the container file. DVF must have write access to the container file to unlock it. If a container file is being accessed for read-only operations (/RO), then the container file is not locked, regardless of the prescence of the /LO switch. - 4 - Virtual Disk Driver Version 3.00 User Guide and Release Notes 2.8 Possible Applications Since Files-11 Level 1 does not support subdirectories, there are many applications for Virtual Disks that extend the usefulness of the file structure. Some applications are: - Maintaining layered products (languages, DECnet) on Vir- tual Disks. - Partitioning users and projects into separate Virtual Disks. - Restoring foreign backup sets (such as DECUS tapes) onto Virtual Disks to avoid creating directories on the main volume. - Shadowing applications with low data rates. 3.0 Installation Installing the package is virtually (sic) painless. The follow- ing files from the running system are required: LB:[1,1]EXEMC.MLB - Executive Macro Library [11,10]RSXMC.MAC - Executive configuration LB:[1,1]EXELIB.OLB - System global symbols LB:[1,54]RSX11M.STB - Executive global symbols LB:[3,54]RSXVEC.STB - Executive vectored symbols The command file VFGEN.CMD will assemble the driver and the utilities, and will task build them all. The AVF and DVF utilities are fully vectored for interfacing to the RSX-11M-Plus Executive. Once built, the utilities should not have to be rebuilt again. The one known exception is if the driver database changes in size. If this happens, AVF needs to be rebuilt so that it is still able to initialize a new database. (If you are running on an earlier version of the system, you can use the non-vectored versions of the source files, AVF.SAV and DVF.SAV, and build against RSX11M.STB.) To finish installation, log onto a privileged account, and copy VFDRV.TSK and VFDRV.STB into the system UIC. The driver can be loaded by MCR or in VMR. The utilities, AVF and DVF, should be copied into a non-privileged utility account or into the Library UIC directory and installed. - 5 - Virtual Disk Driver Version 3.00 User Guide and Release Notes 4.0 Known Bugs and Restrictions, and Possible Improvements Several problems exist with the interface to CON and HRC. Non-privileged users are not allowed to bring devices online or to take them offline. AVF and DVF attempt to use CON to perform the online and offline transitions. If this fails, then AVF and DVF directly manipulate the UCB extension for the Virtual Disk and mark the unit online or offline. Hopefully, this code will not require changes in the future. Another problem with the CON interface is that for some reason, spawning CON directly causes HRC to hang because it cannot in- crease its buffer size to accomodate a new database. However, if AVF calls HRC directly (which is does), then everything works. A Virtual Disk cannot be cached. If a SET /CACHE command is is- sued to a Virtual Disk, the command will be accepted, but caching will not occur. This is because the IO.STC function which con- trols caching has been set as a no-op function. The author has tried to make caching work; it does for about 15 seconds before the system crashes. If anybody can figure out why, I'd certainly like to know. If you want to cache a Virtual Disk, I recommend that caching be enabled for logical I/O on the physical disk which holds the con- tainer file. That seems to work correctly. One nice feature to implement, which was in Stamerjohn's original package, was a list option which displayed the container file in- formation for a particular Virtual Disk. The author's wish is to create a "LVF" utility to perform this function. 5.0 Theory of Operation The following subsections describe the way the package works. It is intended for users who are interested in the functional de- tails. A listing of the source files is helpful; the source is well-documented. 5.1 Driver Logic Details When the driver is loaded, the driver code and a single unit da- tabase are loaded. The single unit, VF0:, serves as the proto- type database, and can never be used as a Virtual Disk. When an I/O request is made to a Virtual Device, the driver is called before the I/O packet is queued to the driver. This is done because the prototype unit always appears to be busy, and all requests to the prototype unit are rejected at this time. If - 6 - Virtual Disk Driver Version 3.00 User Guide and Release Notes the request is being made to a usable Virtual Disk, the I/O packet is entered into the queue for the particular device. When the driver dequeues a packet, it performs some preliminary checks and processing. Note the special processing performed to be certain that UCB offsets are initialized correctly. The re- quest is then block checked, and a write-protect check is made. Next, initialization of the I/O procedure is done. The I/O status block data from the I/O packet is saved in the UCB and replaced by Internal I/O information and the Virtual Disk's UCB address. A pointer is initialized to point to the first con- tainer file control structure in secondary pool. The driver next calculates which container file in the virtual disk will be used to initiate the I/O. For the typical device with one container file, this code trivializes to the only con- tainer file. Next, the I/O procedure is entered. The driver calculates how much of the I/O request can be satisfied with the current con- tainer file. If the request crosses a container file boundary, then I/O is performed up to the boundary, and the I/O packet and buffer addresses are updated accordingly. The I/O packet is manipulated to hold the correct LBN and size information for the container file device, and the I/O packet is then queued via $DRQRQ to the target device. Note the special code to create an ML node which is executed if the target device is shadowed. When the target device completes the I/O, $IOFIN notices the spe- cial values placed in the I/O status block, and calls VFDRV with the I/O packet. The driver determines if the I/O is complete. If it is not, then it re-enters the I/O procedure to use the next container file. If the I/O is completed, the original contents of the I/O packet are restored, and the I/O is finished. 5.2 Driver Database Creation If a device which does not yet already exist in the system is re- quested from the AVF utility, then a new database structure, in- cluding DCB, UCB, and SCB, is created. This is done by allocating primary pool space, copying the prototype database, and initializing sensitive offsets. The new database is placed at the end of the system device list, just before the first pseudo-device database. Container file information is kept in secondary pool. Two words in the device UCB, U.CTLP and U.CTLP+2, contain the APR6 bias and displacement, respectfully, of the secondary control block. For each container file associated with a device, the container file's UCB, LBN offset, size, Virtual Disk base LBN, File ID, and - 7 - Virtual Disk Driver Version 3.00 User Guide and Release Notes flags are kept in the secondary block. Refer to VFPRE.MAC and the source files for details on the secondary control block. During an I/O operation, U.CTLP+2 points to the data structure for the current container file. 5.3 Extension to Device Database In addition to the secondary control block pointers, U.CTLP and U.CTLP+2, there are other offsets in the UCB which are specific to the Virtual Disk driver. These are: U.XFLG: Flags byte U.XFIL: Number of active file segments U.CTLP: Secondary block bias U.CTLP+2: Secondary block displacement U.IOSB: Three word save area for I/O packet I/O status U.XLBN: Base LBN for current transfer U.ISB2: Bytes transferred thus far U.VLNK: Link of all virtual disk UCBs 5.4 Virtual Device Linkages With the ability to give any name to a Virtual Disk, and with the ability to reuse a database, an added difficulty of keeping track of all Virtual Disk databases arises. The offset U.VLNK serves to link all Virtual Disk UCBs together in the system, with the listhead beginning at the prototype database, VF0:. When AVF is requested to reuse a database, it scans this list, ensuring that the requested database is in the Virtual Disk list. If it is, the request is accepted. 5.5 Online and Offline Transitions AVF and DVF are responsible for putting a Virtual Disk in the on- line or offline state. (This can be overridden in AVF.) The Vir- tual Disk driver does not take any special action during an online or offline transition for a real Virtual Disk. The prototype unit is treated as a special case by the driver. When the prototype unit is brought online after the driver is loaded, the driver marks the prototype unit as being busy (S.STS nonzero). This effectively prevents any attempts to unload the driver. When the prototype unit is taken offline, the driver checks all devices in the Virtual Disk list. Every device must have been deassigned by DVF before the offline transition is accepted. If all devices are deassigned, then the driver clears the D.DSP and - 8 - Virtual Disk Driver Version 3.00 User Guide and Release Notes D.PCB offsets in the DCB for each device, making it appear that the driver is unloaded. After this is done, the driver marks the prototype unit idle, and the driver may be loaded. If the driver is reloaded and brought online, the driver will set the D.PCB and D.DSP offsets in all Virtual Disks, so that they may be used again. 6.0 User Comments and Suggestions Comments, suggestions, and bug reports are welcome. The author's address is Gary L. Maxwell U.S. Geological Survey 345 Middlefield Road Mailstop 977 Menlo Park, CA 94025 Phone calls are discouraged. If you really must call, please call between 8:30 and 9:30 AM, Pacific Time. - 9 -