home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / disks / tools / vdisk / vdisk.doc < prev    next >
Text File  |  1997-06-22  |  15KB  |  331 lines
  1. $VER: vdisk.doc 2.7 (22.6.97)   (C) 1994-1997 by Etienne Vogt
  2.  
  3.  
  4. INTRODUCTION
  5.  
  6.  vdisk.device is a driver for a recoverable RAM disk. It started 2 years ago as
  7. a hack of ASDG-RAM (written by Perry S. Kivolowitz). These hacked versions 
  8. (1.3 -> 1.12) were not distributed.
  9.  As of version 2.0, it has been entirely rewritten, with many new features added :
  10.  
  11.  - Up to 16 units with virtually unlimited size (512 MB)
  12.  - Dynamic memory allocation and (optionnaly) deallocation
  13.  - Full support of all AmigaDOS Filesystems.
  14.  - Will survive the heaviest system crashes as long as its own data is not 
  15.    corrupted.
  16.  - In case of a recovery failure, the cause can be reported by a support command.
  17.  
  18.  VDisk requires AmigaDOS 2.04 or higher (V37). It has been heavily tested on
  19. the following configurations :
  20.  
  21.  - A500 68000 ECS , 1 Mb Chip 2 Mb Fast 1.5 Mb False Fast , WB 3.1
  22.    20 Mb IDE-XT + 170 Mb SCSI HDs
  23.  - A3000 68030 ECS, 2 Mb Chip 8 Mb Fast , WB 2.04 -> 3.1
  24.    100 Mb + 1 Gb SCSI HDs
  25.  - A500 68040(PP&S) ECS , 1 Mb Chip 2 Mb Fast16 8 Mb Fast32 , WB 2.04
  26.    50 Mb SCSI HD
  27.  - A4000 68040 AGA, 2 Mb Chip 8 Mb Fast , WB 3.0
  28.    120 Mb + 500 Mb IDE HDs
  29.  - A4000 68040 AGA, 2 Mb Chip 8 Mb Fast , WB 3.0
  30.    250 Mb IDE HD + 1Gb SCSI-II HDs
  31.  - A1200 68EC020 AGA, 2 Mb Chip 5 Mb Fast , WB 3.0
  32.    60 Mb IDE HD + 100 Mb SCSI HDs
  33.  - A4000T 68060(Phase5) AGA, 2 Mb Chip 8 Mb Fast , WB 3.1
  34.    1Gb SCSI-II HD
  35.  
  36.  VDisk has been developed independently from StatRam (Another ASDG-RAM based
  37. ram drive written by Richard Waspe and Nicola Salmoria)
  38.  
  39.  
  40. DISTRIBUTION
  41.  
  42.  VDisk is Freely Distributable Copyrighted Software (FreeWare).
  43.  Some restrictions from the original ASDG-RAM package remains :
  44.  
  45.  This package :
  46.  
  47.  - Must be copied only in the form of the original lha archive, as uploaded
  48.    to aminet by the author.
  49.  - May not be distributed by any commercial software or hardware vendor.
  50.  - May not be sold under any guise.
  51.  - Must contain the following copyright information.
  52.  
  53.    vdisk.device, Copyright 1994 by Etienne Vogt.
  54.    Inspired from asdg.vdisk.device, Copyright 1987 by Perry S. Kivolowitz
  55.     (ASDG Incorporated)
  56.  
  57.  Specifically :
  58.  
  59.   No maker or seller of Amiga expansion hardware or software may distribute
  60.  this software in any way. No reseller of public domain software may
  61.  distribute this software either (as this in NOT in the public domain).
  62.   The only acceptable means of distribution is by networks, bbs's and by
  63.  non-profit user groups. Distribution MUST BE FREE (except for media
  64.  costs plus a token amount covering only shipping and handling).
  65.  
  66.   This software may no longer be included on any aminet CD, as long as the
  67.  freebie policy for contributing authors is not reestablished.
  68.  
  69.  
  70. DISCLAIMER
  71.  
  72.  This software is provided "as is" without any warranty, either expressed or
  73. implied. By using this software, you accept the entire risk as to its quality
  74. and performance.
  75.  
  76.  
  77. INSTALLATION
  78.  
  79.  - Copy the file 'vdisk.device' to your DEVS: directory .
  80.    NEVER CHANGE THE NAME OF THIS FILE !!!
  81.  
  82.  - Copy the support commands CleanRamDisk, DeleteRamDisk, VDStat to your
  83.    C: directory or whatever you like. You may also copy the .info files.
  84.  
  85.  - If you have OS 2.1 or higher, copy the file VD0 to your DEVS:DOSDrivers
  86.    directory. You may change the name of this file to whatever you want.
  87.    You may edit this file to change some parameters of the recoverable RAM
  88.    disk, such as its maximum size. (see below)
  89.  
  90.  - If you have OS 2.0 , join the file VD0.mountlist to your DEVS:MountList
  91.    file. You may change the name of the mountlist entry to whatever you want.
  92.    You may also edit the mountlist record to change some parameters of the
  93.    recoverable RAM disk (see below). Make sure you do not have another
  94.    entry with the same name in your mountlist (especially if you use the
  95.    old asdg-ram).
  96.    Add a 'Mount VD0:' command to your S:User-Startup. If you have 1 Mb or
  97.    less memory, it may be wise to put this command at the beginning of your
  98.    Startup-Sequence to minimize the risk of recovery failures.
  99.  
  100.  - If you still have OS 1.x, well... It's time to upgrade !
  101.  
  102.  - After that, reboot your Amiga. If all is OK, you should see an icon named
  103.    VD-RAM-00 on your Workbench.
  104.  
  105.    NOTE : If you are upgrading from an earlier version of vdisk.device, you
  106.           *MUST* issue a 'DeleteRamDisk' command on all active units before
  107.           rebooting the system, or unexpected things may happen.
  108.           See the support commands below.
  109.  
  110.  
  111. CHANGING MOUNTFILE PARAMETERS
  112.  
  113.   WARNING : Changing any other MountFile parameter than those listed below will
  114.             cause the vdisk.device to cease to function and to wake up the
  115.             GURU with recoverable alert number $50000005 !
  116.             After changing ANY parameter of an already active unit, you MUST
  117.             issue a 'DeleteRamDisk' command on it before rebooting the system,
  118.             or unexpected things may happen.
  119.  
  120.  - DOS device name : Unlike the original asdg.vdisk.device, you can give any
  121.    name you want to the recoverable RAM disk. Just change the name of the
  122.    mountfile (OS 2.1+) or the mountlist entry (OS 2.0). The default name is
  123.    VD0 . It is recommended that the last character be a digit equal to the 
  124.    unit number.
  125.  
  126.  - Unit : This is the device unit number. You can have several recoverable
  127.    RAM disks by having different mountfiles with different values for this
  128.    keyword. Valid numbers are 0 to 15, giving a possible total of 16 units.
  129.  
  130.  - Flags : Different options may be selected here. You combine them by adding
  131.    their respective value (ex. to enable autocleaning and allocretry, use
  132.    Flags = 3).
  133.     A Flags value of 1 (bit 0 set) will enable autocleaning on the corresponding
  134.    unit. This means that the memory used by the ram disk will automatically
  135.    decrease when you delete files in it. This also implies that you cannot use
  136.    tools like DiskSalv to recover the deleted files. If autocleaning is not
  137.    set, you must use the CleanRamDisk support command to free memory after
  138.    deleting files. Cleaning may still happen if the system runs low on memory.
  139.    It is recommended that you keep AutoCleaning enabled.
  140.     A flags value of 2 (bit 1 set) will enable allocretry. This causes the
  141.    vdisk unit to retry failed memory allocations with less restrictive
  142.    conditions than those specified in the BufMemType parameter. The allocation
  143.    retry will use any public memory available. This is only useful if you have
  144.    set specific memory requirements in the BufMemType parameter (to force use
  145.    of 16 bit fast ram for ex.) and don't want an error to be returned if this
  146.    specific memory type is exhausted.
  147.  
  148.  - HighCyl : This is used to specify the maximum size the recoverable RAM disk
  149.    is allowed to use. When this size is reached, you will get a 'Volume is full'
  150.    requester. Note that unlike RAD, vdisk.device does only allocate memory when
  151.    you write files into it.
  152.    Do not set this too high ! If you run out of memory before reaching the
  153.    maximum size of the RAM disk, you will get a 'write error' requester and
  154.    the files in the RAM disk might become corrupt !!!
  155.    The recommended maximum size is one fourth of your total FAST RAM.
  156.    The HighCyl parameter must be set to an ODD VALUE. HighCyl + 1 is the total
  157.    number of 'virtual tracks' usable by the RAM disk. One virtual track has
  158.    a size of 8 Kb (16 sectors of 512 bytes).
  159.    The default HighCyl value of 63 thus corresponds to a maximum size of
  160.    (63 + 1) * 8 = 512 Kb. For a 2 Mb RAM disk, you will set HighCyl to 255.
  161.    The maximum allowed value is 65533. This corresponds to 512 Mb.
  162.    Remember this value *MUST* be odd !
  163.  
  164.  - Buffers : This is the number of buffers used by the File System to speed up
  165.    disk accesses. With a RAM disk, it may actually slow it down, so you'd
  166.    better not change this.
  167.  
  168.  - BufMemType : Strictly speaking, this is the type of memory used by the
  169.    File System for its internal buffers. For vdisk.device, is also affects
  170.    the type of memory allocated to store data you write into it.
  171.    You can combine different attributes by adding their respective values.
  172.    A value of 1 (MEMF_PUBLIC) means public memory (shared and non virtual)
  173.    and is always used.
  174.    2 (MEMF_CHIP) is chip memory (not recommended).
  175.    4 (MEMF_FAST) is fast memory.
  176.    256 (MEMF_LOCAL) is motherboard memory that should survive a reset. You
  177.    can try to set this flag if vdisk loses its content after reboot.
  178.    512 (MEMF_24BITDMA) is memory accessible via 24 bit addresses. This
  179.    can be 16 or 32 bit RAM though.
  180.    1024 (MEMF_KICK) is memory that can be used at boot time. This is only
  181.    defined in KickStart 3.0+.
  182.     The default value is 5 which means public fast memory.
  183.  
  184.  - DosType : The type of File System used. Possible values are :
  185.     0x444f5300 : Old File System. Slow and not really needed since vdisk.device
  186.                  has its own checksums.
  187.     0x444f5301 : Fast File System. The default.
  188.     0x444f5302 : International Old File System. OS 2.1 + only.
  189.     0x444f5303 : International Fast File System. OS 2.1 +
  190.     0x444f5304 : Directory Caching Old File System. OS 3.0 +
  191.     0x444f5305 : Directory Caching Fast File System. OS 3.0 +
  192.    International mode may be used if you run OS 2.1 or higher. Directory Caching
  193.    is not a good idea since it will slow down the RAM disk.
  194.  
  195.  - Activate : Instructs the mount command to start the device immediately when
  196.    set to 1. If you set it to 0, you must add some command in your Startup
  197.    that accesses VD0 to start it really.
  198.  
  199.  
  200. SUPPORT COMMANDS
  201.  
  202.  CleanRamDisk :
  203.  
  204.    This command is used to force a vdisk unit to free deleted file space. It
  205.   is generally not needed with autocleaning units.
  206.    This command may be used from Workbench (but you can't use the switches).
  207.   Select the virtual disk icon, then double-click on the CleanRamDisk icon.
  208.  
  209.   Usage : CleanRamDisk DEVICE,UNIT/K/N,NOFREECHIP/S,REBUILD/S,FREEBOOT/S
  210.  
  211.   DEVICE : This is the AmigaDOS device name (ex. VD0: )
  212.   UNIT : Alternatively to the AmigaDOS name, you may specify the unit number
  213.          (ex. UNIT 0)
  214.   NOFREECHIP : When BufMemType is set to 1, CleanRamDisk normally attempts to
  215.                free some CHIP memory by relocating virtual tracks located in
  216.                CHIP RAM to FAST RAM. This switch inhibits this behaviour.
  217.   REBUILD : When a vdisk unit has read errors on it (generally caused by some
  218.             bad software that writes over someone else's memory), it will be
  219.             lost at the next reboot (which in this case may come soon).
  220.             This switch forces a rebuild of all internal checksums so that
  221.             the unit will be kept alive after reset. Some data will still be
  222.             bad, but you should be able to save most of it.
  223.   FREEBOOT : If something has been written in the RAM disk's boot blocks
  224.              (unused at this time), virtual track 0 will be locked in memory.
  225.              This switch will mark the boot blocks as free, thus enabling the
  226.              Cleaning routine to flush track 0 out.
  227.  
  228.  DeleteRamDisk :
  229.  
  230.    This command deletes a virtual disk unit entirely (as RemRAD for RAD). All
  231.   memory used is freed and the File System is inhibited. (VD0:BUSY)
  232.    This command may be used from Workbench. Select the virtual disk icon, then
  233.   double-click on the DeleteRamDisk icon. A requester will ask you for confir-
  234.   mation.
  235.    You *MUST* use this command when you change the mountfile parameters of
  236.   an active unit. You must also delete all active units when you upgrade to
  237.   a newer version of vdisk.device. 
  238.  
  239.   Usage : DeleteRamDisk DEVICE,UNIT/K/N
  240.  
  241.   DEVICE : This is the AmigaDOS device name (ex. VD0: )
  242.   UNIT : Alternatively to the AmigaDOS name, you may specify the unit number
  243.          (ex. UNIT 0)
  244.  
  245.  VDStat :
  246.  
  247.    This command is used to get information about a virtual disk unit that
  248.   failed to recover its data after reboot. It is mainly intended for beta
  249.   testers, so it cannot be used from Workbench.
  250.    Recovery error 2 (Root Structure not found) will always show at power-up.
  251.  
  252.   Usage : VDStat DEVICE,UNIT/K/N,FULL/S
  253.  
  254.   DEVICE : This is the AmigaDOS device name (ex. VD0: )
  255.   UNIT : Alternatively to the AmigaDOS name, you may specify the unit number
  256.          (ex. UNIT 0)
  257.   FULL : This switch causes more information to be displayed. It is mainly
  258.          used for debugging purposes.
  259.  
  260.   Recovery error codes :
  261.  
  262.   1 (Deleted Unit) : This will show after reboot when a unit is deleted by
  263.     the DeleteRamDisk command.
  264.   2 (Root structure not found) : This will always show up at power-up. It may
  265.     also happen if something else (like RAD) allocates memory in reverse order
  266.     before vdisk.device starts. To avoid this, always mount a vdisk unit before
  267.     any ramdrive units. Other possibilities are a bad program trashing memory
  268.     or the presence of non reset proof memory in the system (see the known
  269.     problems section).
  270.     This error indicates that all units were lost.
  271.   3 (Bad Root Structure Checksum) : The Root Structure has been corrupted.
  272.     Bad program or memory around ! All units were lost.
  273.   4 (Bad Sector CheckSum) : Either a bad program has trashed your data, or
  274.     you have a memory problem.
  275.   5 (Track not found) : Bad virtual track. This may happen if the unit maximum
  276.     size is set too big, your memory is heavily fragmented or a bad program
  277.     trashed some memory.
  278.   6 (Reallocation Failure) : Everything seems OK, but memory couldn't be
  279.     reallocated with AllocAbs(). This is a bad one that will also wake up
  280.     the guru with recoverable alert number $50010003. If you have access
  281.     to E-Mail, please send a bug report to me (address below).
  282.   7 (Unit Structure not found) : Unit structure got trashed. Bad program or
  283.     memory.
  284.   8 (Bad Unit Structure Checksum) : Corrupted unit structure. Bad Program or
  285.     memory.
  286.   9 (Unknown Error) : How did you get this one ?
  287.  
  288.  
  289. CHANGES
  290.  
  291.  V 2.4 :    First released version.
  292.  
  293.  V 2.5 :      - vdisk now retries failed memory allocations with MEMF_PUBLIC
  294.         when BufMemType was set to allocate a specific type of
  295.         memory. This should cause less write errors.
  296.           - French doc included after numerous requests.
  297.  
  298.  V 2.6 :      - The kludge for safely using $C00000 memory has been entirely
  299.         rewritten. It does no longer cause fragmentation of this
  300.         memory.
  301.           - The Root structure is now allocated in MEMF_KICK memory
  302.         (MEMF_LOCAL for OS 2). This should help vdisk to survive
  303.         reboot on systems with non autoconfig 32bit memory.
  304.           - Added the allocretry Flags option.
  305.           - vdisk will now allow memory flushing to occur when it
  306.         tries to allocate more memory.
  307.  
  308.  V 2.7 :      -    Fixed a stupid bug that caused crashes when odd unit numbers 
  309.         were used on a 68000 system.
  310.  
  311.  
  312. KNOWN PROBLEMS
  313.  
  314.  It seems that certain accelerator boards have 32 bit memory that does
  315. not keep its content after a reset. This will cause vdisk to lose its
  316. files.
  317.  If this happens to you, try to set the BufMemType parameter to 1024
  318. (if you have OS 3+) or 256 (for OS 2) to prevent vdisk from using this
  319. 32 bit memory. Also don't set the allocretry bit in Flags.
  320.  
  321.  
  322. CONTACTING THE AUTHOR
  323.  
  324.  I can be reached by E-Mail at the following address : Etienne.Vogt@obspm.fr
  325.  
  326.   Bug reports must include the complete hardware and software configuration,
  327.  including any third party software that was running in the background.
  328.  
  329.  
  330.                                          Etienne Vogt, 22/7/1997
  331.