Super Virtual Disk Swappable/Lockable/Removable Virtual Disk for OS/2 SVDISK Version 1.01 07/08/94 TABLE OF CONTENTS _________________________________________________________________ 1.0. INTRODUCTION TO Super Virtual Disk ..................3 1.1. What is Super Virtual Disk? ....................3 1.2. Features of SVDisk .............................3 2.0. SYSTEM REQUIREMENTS .................................4 3.0. COPYRIGHT NOTICE ....................................4 4.0. WARRANTY ............................................4 5.0. COST OF Super Virtual Disk ..........................4 6.0. CONTENTS OF THIS PACKAGE ............................5 7.0. INSTALLATION ........................................6 7.1. Quick start ....................................6 7.2. SVDisk.sys parameters ..........................7 8.0. CONTROLLING Super Virtual Disk ......................8 8.1. Super Virtual Disk Control (SVDC.EXE) help screen ..............................................8 8.2. Options for SVDC ...............................9 8.3. PM Super Virtual Disk Control ..................11 8.4. Diskette boot bypass using VFloppy .............11 9.0. PROGRAMMING INFORMATION .............................11 10.0. EXAMPLES ...........................................13 10.1. Example 1: Locking non-swappable memory and querying status .....................................13 10.2. Example 2: Ejecting virtual media .............13 10.3. Example 3: Reconfiguring VFloppy device .......14 10.4. Example 4: Inserting virtual media ............14 10.5. Example 5: Multiple operations ................14 11.0. ERROR MESSAGES .....................................15 11.1. List of error messages ........................15 2 1.0. INTRODUCTION TO Super Virtual Disk _________________________________________________________________ 1.1. What is Super Virtual Disk? Super Virtual Disk (SVDisk) is a 32-bit OS/2 device driver that emulates either a removable Virtual Disk (VDisk) or a removable Virtual Floppy (VFloppy) drive. By using OS/2's virtual memory management facility, SVDisk allows the entire contents of the disk to be swapped out via the paging mechanism. If the SVDisk is frequently accessed, OS/2 will keep the most recently used memory pages in RAM, and SVDisk will essentially behave like a RAM Disk. 1.2. Features of SVDisk - Emulates multiple VDisk devices up to 16MB each even on a 4MB system. Cluster size is maintained at 512 bytes by varying the size of the File Allocation Table (FAT) to reduce file slack. - Emulates multiple VFloppy devices, ranging from 360KB to 2.88MB. Virtual media support ranges from 160KB to 1.2MB for 5.25" VFloppy device, and from 720K to 2.88MB for 3.5" VFloppy device. If the VFloppy is a 3.5" device, automatic media sensing is supported. - Media in SVDisk is removable. This allows SVDisk to release all memory used by the device back to the system. - Dynamic device reconfiguration is supported for the VFloppy device. If you load a 1.44MB VFloppy device, it can be reconfigured later (without rebooting) as a 360KB, 720KB, 1.2MB or 1.44MB drive. - Special boot sector on VFloppy device to allow bypassing of floppy boot if the image of the VFloppy is transferred to the a real diskette using DISKCOPY. - Formatting and sector/track read/write are supported. - SVDisk allows locking of swappable memory into non-swappable memory. Once memory is locked, SVDisk will behave like a RAM drive without paging delay. The size of the lock can be specified by the user, since locking the entire disk as non- swappable can have serious performance impact to OS/2's virtual memory operation. - A 32-bit command line utility and a 32-bit PM application are included to provide complete control of all the capabilities of SVDisk. 3 2.0. SYSTEM REQUIREMENTS _________________________________________________________________ Machines equipped with an Intel 386SX compatible or higher processor. OS/2 2.1 or higher, with minimum 4MB of memory. 3.0. COPYRIGHT NOTICE _________________________________________________________________ SVDisk (Super Virtual Disk) Version 1.01 07/08/94 (c) Copyright 1994 by Albert J. Shan. All Rights Reserved. No part of this program may be disassembled, modified or altered by any means. 4.0. WARRANTY _________________________________________________________________ I, Albert J. Shan, make no warranties, expressed or implied, including, but not limited to, merchantability or fitness for any particular purpose. In no event shall Albert J. Shan be liable for indirect or consequential damages arising from the use of the software program. You are free to redistribute this shareware package in its entirety. No part of this package may be included as part of a commercial package. If you have any questions about commercial distribution of Super Virtual Disk, I can be contacted at: Albert J. Shan 4620 Granville Avenue Richmond, B.C. CANADA V7C 1E4 or via CompuServe, ID 70730,401 or via Internet, 70730.401@compuserve.com 5.0. COST OF Super Virtual Disk _________________________________________________________________ The user is granted a 30 days trial period, after which he or she is required to register the product. The cost of a single machine license is $30 U.S. Please refer to the file ORDER.FRM for details. 4 6.0. CONTENTS OF THIS PACKAGE _________________________________________________________________ The following files are included in this package: SVDISK.SYS - Super Virtual Disk device driver SVDC.EXE - Super Virtual Disk Control PMSVDC.EXE - PM version of SVDC SVDISK.DOC - This documentation SVDISK.HST - History of SVDisk ORDER.FRM - Order form README - Last minute information 5 7.0. INSTALLATION _________________________________________________________________ 7.1. Quick start To install SVDisk, make a subdirectory called SVDISK, and copy all the SVDisk files into \SVDISK. Then edit your OS/2 CONFIG.SYS to include a line: DEVICE=D:\SVDISK\SVDISK.SYS Where D: is the drive where you created the SVDISK subdirectory. You may want to add SVDISK to the path by appending D:\SVDISK at the end of the PATH= statement in CONFIG.SYS. When you load SVDisk without any parameter as in the above example, it will create a 1.44MB VFloppy device after you reboot the system. When SVDisk is loaded, it does not put a media in the virtual drive. You have to manually insert it with SVDC or PMSVDC. To insert a virtual media after the system is booted, you type: SVDC X: /i:720 Where X: is the drive letter of the SVDisk after boot. This will insert a 720KB virtual media into the drive. If you specify /i without any parameter, SVDC will insert a media with the maximum capacity as defined by the SVDisk.sys device in CONFIG.SYS. To make media insertion automatic, simply edit STARTUP.CMD on your OS/2 boot drive and add the SVDC line to it. Alternatively, you can insert the virtual media by using the CALL= statement in CONFIG.SYS: CALL=D:\SVDISK\SVDC.EXE X: /i:720 If you want to install a 8MB VDisk type device, edit your CONFIG.SYS by adding a line: DEVICE=D:\SVDISK\SVDISK 8192 512 This will create a 8MB VDisk device with 512 root directory entries after you reboot the system. 6 7.2. SVDisk.sys parameters SVDisk.sys can be loaded with no parameter to up to two parameters. To load SVDisk as a VFloppy device, you must specify the size of the VFloppy device in KB. For example: REM *** Load a 1.44MB VFloppy device *** DEVICE=\SVDISK\SVDISK.SYS 1440 REM *** Load a 2.88MB VFloppy device *** DEVICE=\SVDISK\SVDISK.SYS 2880 REM *** Load a 360KB VFloppy device *** DEVICE=\SVDISK\SVDISK.SYS 360 The possible values for VFloppy device are: 360, 720, 1200, 1440, and 2880. Since SVDisk defaults to a 1.44MB VFloppy device, the 1440 parameter can be omitted. To load SVDisk as a VDisk device, you can specify up to two parameters: DEVICE=\SVDISK\SVDISK.SYS ssss eeee Where ssss is the size of the VDisk device, and eeee is the root directory entries for the device. eeee is optional, and if you do not specify it, SVDisk will default to 64 root directory entries. The possible values for ssss are from 16 to 16384 (16KB to 16MB.) The VDisk device will always round up the size into 16KB boundary. If you specify a 250KB VDisk device, it will be loaded as 256KB. The possible values for eeee are from 16 to 1024. This value is also rounded up in multiple of 16. If you load a VDisk device near the size of 4MB, it will attempt to resolve the File Allocation Table (FAT) size as either 12-bit or 16-bit. In the case of conflict due to a large root directory entries specification, SVDisk will slightly reduce the VDisk size in favor of a 12-bit FAT for lower disk sector overhead in the system area on the virtual media. SVDisk distinguishes a VDisk device from a VFloppy device solely by the ssss (size) parameter. If ssss is one of the possible values for a VFloppy device, it will load itself as a VFloppy device, and the second parameter is ignored. 7 8.0. CONTROLLING Super Virtual Disk _________________________________________________________________ Two programs are provided to control the SVDisks: SVDC.EXE and PMSVDC.EXE. PMSVDC.EXE is the Presentation Manager version of SVDC.EXE. 8.1. Super Virtual Disk Control (SVDC.EXE) help screen Type SVDC at the OS/2 command prompt to receive this help screen: Super Virtual Disk Control (32-bit) Version 1.01 SHAREWARE VERSION (c) Copyright 1994 Albert J. Shan. All Rights Reserved. For use with Super Virtual Disk driver (SVDISK.SYS) Usage: SVDC [options] Drive: [options] /c Fake a disk change. /e[f] Eject media [f = forced eject]. /i[:size] Insert media (if size is not specified, default to max. drive capacity.) Size can only be specified for the VFloppy device. Valid sizes are: 160, 180, 320, 360, 720, 1.2, 1.44, 2.88. /l:size Lock SVDisk in non-swappable memory. Size is anywhere from 0 (KB) to the max. media size. /q Query SVDisk status /r[:size] Reconfigure VFloppy device capacity (if size is not specified, default to max. drive capacity.) Valid sizes are: 360, 720, 1.2, 1.44, 2.88. /u Unlock non-swappable memory used by the SVDisk. Drive: Drive letter of the Super Virtual Disk. NOTE: The drive must not contain any media before reconfiguring with /r. *** Note: parameters within [] are optional. If you specify the drive letter of a SVDisk and without specifying any other options, SVDC will report the current status of the SVDisk drive as if the Query Status switch (/q) is specified. For example: [C:\SVDISK]svdc j: SVDISK.SYS Version: 1.01 Reconfigurable device size: 2.88MB Current device size: 2.88MB Current media size: 1.44MB Non-swappable memory locked: 128KB 8 8.2. Options for SVDC /c Fake a disk change. This command will cause the SVDisk specified to appear as if it has been changed (ejected then reinserted.) This is accomplished by changing the Volume Serial on the SVDisk. If the program in question is looking for a change in Volume Label or a DOS program is looking for a change line bit in hardware, /c will not work. /e[f] Eject media. This will eject the media in the SVDisk, thereby releasing all memory, including locked memory (see /l and /u below) back to the system. If a program is currently running off the SVDisk, you must specify /ef to force the disk to eject. Further access to the SVDisk drive will cause a drive not ready error. /i[:size] Insert media. If size is not specified, it will insert a media with the exactly same size as the SVDisk device. For example, if the VFloppy is 2.88MB, specifying /i alone will insert a 2.88MB media into the SVDisk drive. The optional size parameter is only applicable for a VFloppy device. This allows different size media to be inserted into the VFloppy drive. If the VFloppy is a 5.25" 360KB device, the possible values are: 160, 180, 320, and 360. If the VFloppy is a 3.5" 1.44MB device, the possible values are: 720 and 1.44. Depending on the type of VFloppy device, the possible values are: 160, 180, 320, 360, 720, 1.2, 1.44 and 2.88. /l:size Lock virtual disk in non-swappable memory. This will cause the virtual memory allocated by SVDisk to be locked in real memory pages, and they will be precluded from swapping out by the system. The starting location of the lock is fixed at the beginning of the disk, at logical sector 0. The size parameter is anywhere from 0 to the maximum size of the media in the SVDisk. It will be rounded up in 4KB in size as OS/2 can only lock memory in page boundary. A size of 0 is equivalent to unlocking all the memory (see /u switch below.) If a lock already exists on the SVDisk, it will be released, and the new lock size will be installed. If there is not enough real memory for the lock, /l will fail, and at the same time, releasing any memory previously locked. The OS/2 kernel will swap out other processes in order to make room for the lock. This may take a while as pages are being swapped out. The system will not be responsive when the kernel is into heavy paging activities. 9 WARNING: Locking memory as non-swappable has the same effect as removing system memory on the hardware level. If you have a 8MB system, locking a few mega bytes of memory will make your system appear as if it has 4MB total system memory or less. If the lock succeeds in locking large amount of memory, and the remaining non- swappable memory is extremely low, the OS/2 virtual memory paging mechanism will thrash. Although the system is not crashed, it will be paging in and out so frequently that the system can no longer respond to the user's input. You will need to press Ctrl-Alt-Del to recover in this case. In general, it is recommended not to lock more that one quarter of total system memory as non-swappable for all SVDisk devices combined. PMSVDC.EXE will limit the maximum of the lock to half of total system memory or the maximum disk size, whichever is less. On the other hand, SVDC.EXE is designed to be flexible, so any lock size is possible. /q Query SVDisk Status. The following is a typical SVDisk report: SVDISK.SYS Version: 1.01 Reconfigurable device size: 2.88MB Current device size: 2.88MB Current media size: 1.44MB Non-swappable memory locked: 128KB /r[:size] Reconfigure VFloppy device capacity. This switch is only applicable to the VFloppy device. It allows dynamic device reconfiguration while the system is running. Before you can reconfigure the VFloppy device, the media must first be ejected via the /i switch. Specifying /r alone will reconfigure the VFloppy device to the maximum capacity as loaded by the device driver. If SVDisk is loaded as a 1.2MB VFloppy device, you cannot reconfigure it to a 1.44MB or 2.88MB VFloppy device. For example, if SVDisk is loaded as a 3.5" 2.88MB VFloppy device, you can reconfigure it to 5.25" 360KB, and 1.2MB VFloppy device. You can also reconfigure it to 3.5" 720KB, 1.44KB and 2.88MB VFloppy device. /u Unlock non-swappable memory used by the SVDisk. This is the same as specifying /l:0. Locked memory is released as being swappable. 10 8.3. PM Super Virtual Disk Control The Presentation Manager version of Super Virtual Disk Control (PMSVDC.EXE) provides identical functions as SVDC.EXE with one exception. The lock function will limit the maximum available memory for the lock as half of total system memory or maximum media size, whichever is less. This means if you have 16MB of memory, and your VDisk device is 16MB, the largest memory size you can lock is 8MB. Many system board reserves up to 384K of memory for shadow ROM and other purposes. This effectively reduces your total system memory. Instead of 16MB (16384KB), you get 16000KB total system under OS/2 and the maximum size for the lock in this case is 8000KB. The lock function also warns you if you are locking more than one quarter of the total system memory. If you have multiple SVDisk devices, PMSVDC will add up all memory locked all SVDisk devices, subtract the existing lock size on the current device, then add the new requested size to see if it exceeds one quarter total memory limit. In general, the total memory locked by all SVDisk devices should be less than one quarter of the total system memory to prevent OS/2 pager from thrashing. 8.4. Diskette boot bypass using VFloppy SVDisk contains a special boot sector which can be used to bypass real floppy boot. You can do this by transferring the image of a VFloppy device with DISKCOPY to a real diskette. If you leave the diskette in drive A:, upon system reboot, you will get the following message on the screen: Transferring system boot from diskette to hard drive... And the boot sequence will be transferred to the hard drive. If you have OS/2 Boot Manager installed, you will see the Boot Manager at this point. 9.0. PROGRAMMING INFORMATION _________________________________________________________________ When SVDisk is used as a VFloppy device, it tries to emulate a real floppy drive as much as possible. However, this emulation is not 100%. If you write a program against the behavior of a real floppy drive, it will almost certainly work with SVDisk. The converse is not always true. This is because SVDisk makes certain assumptions to simplify many of the internal operations which are true for a virtual device. The common pitfall is to assume reading and writing to a floppy device are always slower than other computational threads. If a multithreaded OS/2 application is designed with the above assumption, it will almost certainly fail because the disk read/write operations are much faster than the program has expected. 11 SVDisk supports the following IOCtl Category 8 logical disk commands (in hex): 00 Lock drive 01 Unlock drive 02 Redetermine media 04 Begin format 20 Block removable 21 Query logical map 43 Set device parameters (the changing the BPB of the device is not supported) 44 Read track 64 Write track 65 Verify track 45 Format and verify track 60 Query media sense 63 Query device parameters Please refer to OS/2 2.x SDK (Software Development Kit) on programming the IOCtl interface. 12 10.0. EXAMPLES _________________________________________________________________ The following examples assume you have the following lines installed in CONFIG.SYS: DEVICE=D:\SVDISK\SVDISK.SYS 8192 512 DEVICE=D:\SVDISK\SVDISK.SYS 2880 CALL=D:\SVDISK\SVDC.EXE H: /i CALL=D:\SVDISK\SVDC.EXE I: /i:1.44 The first SVDisk is an 8MB VDisk device with 512 root directory entries, with drive letter 'H' assigned to it by OS/2. The second SVDisk is a 2.88MB VFloppy device, initially loaded with a 1.44MB virtual media, and is assigned as drive 'I'. 10.1. Example 1: Locking non-swappable memory and querying status You would like to lock the first 600K of SVDisk H: in non- swappable memory, and query the status at the same time: SVDC H: /l:600 /q And you get the following report: SVDISK.SYS Version: 1.01 Reconfigurable device size: 8192KB Current device size: 8192KB Current media size: 8192KB Non-swappable memory locked: 600KB 10.2. Example 2: Ejecting virtual media You can eject the virtual media in SVDisk so that all memory used (including locked memory) is returned to the operating system: SVDC I: /e If the SVDisk is in used by a process (ie: a running program, open files, etc.), you'll receive an error message: KWT0131: Drive I: is not ready or in use by another process. You can force eject the virtual media by specifying /ef: SVDC I: /ef 13 10.3. Example 3: Reconfiguring VFloppy device You want to change the VFloppy drive I: into a 1.2MB 5.25" device: SVDC I: /r:1.2 10.4. Example 4: Inserting virtual media You want to insert a 360KB virtual media into drive I:, which has just been reconfigured to a 1.2MB VFloppy drive: SVDC I: /i:360 10.5. Example 5: Multiple operations You can combine example 3 and 4 plus locking and querying all in one step: SVDC I: /r:1.2 /i:360 /l:180 /q And you'll receive this status report: SVDISK.SYS Version: 1.01 Reconfigurable device size: 2.88MB Current device size: 1.2MB Current media size: 360KB Non-swappable memory locked: 180KB 14 11.0. ERROR MESSAGES _________________________________________________________________ 11.1. List of error messages The following is a list of major error messages returned by SVDC.EXE. The error return code is also displayed as part of the prefix in the error message: SVDnnnn: Error message text Where nnnn is the error return code. SVD0016: Drive X: is not a Super Virtual Disk. SVD0017: SVDISK.SYS has a higher revision level. SVD0018: Invalid media size. SVD0020: Unable to eject Super Virtual Disk due to memory deallocation error. SVD0021: Unable to insert Super Virtual Disk due to memory allocation error. SVD0022: No media in drive. SVD0023: You cannot insert two media in the drive. SVD0024: Incorrect size specified. SVD0025: System failed to lock memory as non-swappable. SVD0026: System failed to unlock non-swappable memory. SVD0027: No non-swappable memory locked by the Super Virtual Disk. SVD0028: Cannot reconfigure Super Virtual Disk with a media in the Drive. SVD0029: Only VFloppy type device can be reconfigured. 15