home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Exec 3 / CD_Magazyn_EXEC_nr_3.iso / Recent / util / sys / dev-handler.readme < prev    next >
Text File  |  2000-07-13  |  9KB  |  234 lines
  1. Short:    Un*x like raw device access handler
  2. Author:   thor@math.tu-berlin.de (Thomas Richter)
  3. Uploader: thor@math.tu-berlin.de (Thomas Richter)
  4. Version:  40.2
  5. Type:     util/sys
  6. Requires: OS 2.04
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. Purpose of this program:
  11.  
  12. The DEV-Handler allows easy access to raw sectors of an exec type device under
  13. the dos.library environment. A typical application would be to use the "copy"
  14. command to make a full backup of a floppy to a file, or to use "copy" to make
  15. a backup of the RDB of your HD.
  16.  
  17. The DEV-Handler is very powerful, but also very dangerous in the wrong hands
  18. because it modifies the device structure going down to the exec handler
  19. directly without using any kind of filing system access.
  20.  
  21. This DEV-Handler replaces various other DEV-Handlers and improves and fixes
  22. many problems of these earlier releases. Note that no original code of these
  23. versions have been used, this handler is a complete rewrite.
  24.  
  25. ------------------------------------------------------------------------------
  26.  
  27. Usage:
  28.  
  29. A file name for the DEV-Handler is either a "DOS" device name like "df0" or
  30. "DH0" in which case this "file" indicates the full partition addressed by this
  31. name. For example, "DEV:df0" is the raw, unmapped first internal floppy drive,
  32. "DEV:dh0" the first harddisk partition. The start of the file using this syntax
  33. is always the start of the partition, the length of the file the full length of
  34. the partition. Especially, this does NOT include the RDB, if there is one.
  35.  
  36. The alternative syntax addresses an exec device directly and completely,
  37. ignoring partitions. A file name using this syntax looks as follows:
  38.  
  39. DEV:device/unit/flags/bufmemtype/mask/maxtransfer
  40.  
  41. where    
  42.  
  43. device            is an exec device name, i.e. "scsi.device". This is
  44.             mandatory.
  45. unit            is the exec unit number, typically the SCSI ID. This
  46.             is mandatory. If only one argument is given, the
  47.             DEV-Handler reads the device as DOS partition name and
  48.             not as an exec name. This is a numeral.
  49. flags            exec flags for opening the device. Optionally and
  50.             defaults to zero. This is a numeral.
  51. bufmemtype        the memory type for the buffer to allocate for device
  52.             I/O. Optionally and defaults to 
  53.             MEMF_24BITDMA|MEMF_PUBLIC.
  54.             This is a numeral, or one of the following hard-coded
  55.             identifiers:
  56.  
  57.             MEMF_ANY, ANY        whatever is available, this is
  58.                         identical to MEMF_PUBLIC for
  59.                         the purpose of this handler.
  60.             MEMF_PUBLIC, PUBLIC    public (non-virtual) memory.
  61.             MEMF_CHIP, CHIP        chip memory.
  62.             MEMF_FAST, FAST        non-chip, i.e. FAST memory.
  63.             MEMF_LOCAL, LOCAL    native motherboard memory that
  64.                         does not go away on reset.
  65.             MEMF_24BITDMA, 24BITDMA    memory in the 24 bit address
  66.                         space reachable for Zorro-II
  67.                         DMA.
  68.             MEMF_ZORROII, ZORROII    a synonym for the above.
  69.  
  70.             All other values are read as numerals, hex identifiers
  71.             using the "$" or "0x" notation are allowed here as
  72.             well.
  73.             
  74.             This field fulfills the same purpose than the
  75.             BUFMEMTYPE in the mount lists.
  76.  
  77. mask            A mask used for checking whether the supplied buffer is
  78.             "proper". If "memory and not mask" is non-zero, the 
  79.             handler will fall back to single block-I/O like the FFS.
  80.  
  81.             This field has the same purpose and works in the same
  82.             way as the "MASK" entry in mountlists. 
  83.  
  84.             It is optional, the handler will compute a reasonable
  85.             mask for you using the supplied or non-supplied 
  86.             bufmemtype.
  87.  
  88.             This entry is a numeral, hex notation is accepted.
  89.  
  90. maxtransfer        The maximal amount of bytes the exec device is able to
  91.             transfer at once. Larger chunks are split into smaller
  92.             pieces at most as big as the "maxtransfer".
  93.  
  94.             This field works as the "MAXTRANSFER" entry in mount-
  95.             lists. It defaults to 32767, i.e. 32K-1. 
  96.  
  97.             This entry is a numeral, hex notation is accepted.
  98.  
  99. ------------------------------------------------------------------------------
  100.  
  101. Examples:        Note that the DEV-Handler is clearly an expert-tool,
  102.             unsophisticated playing with the DEV-Handler may easely
  103.             destroy the data-integrity of your HD!
  104.  
  105. Make a byte for byte backup of a floppy in drive 0 - known as ".adf" file:
  106.  
  107.     copy dev:df0 to Backup.adf
  108.  
  109. No need to run or use any kind of "ADF" conversion utility. 
  110.  
  111.  
  112. Restore a backup to the floppy:
  113.  
  114.     copy Backup.adf to dev:df0
  115.  
  116. Yes, it is really that simple. (-:
  117.  
  118.  
  119. Make a byte copy of the ZIP partition for future use:
  120.  
  121.     copy DEV:ZIP to Backup
  122.  
  123.  
  124. View the "RDB" block of your boot volume, connected to the scsi.device, unit 0:
  125.  
  126.     type DEV:scsi.device/0 hex
  127.  
  128. ------------------------------------------------------------------------------
  129.  
  130. Installation:
  131.  
  132. - Copy "Device-Handler" to L:
  133.  
  134. - Copy "DEV" and "DEV.info" to "Storage/DOSDrivers".
  135.  
  136. I *do not* recommend to mount DEV: automatically on startup since accidental
  137. playing with DEV: may really yield to major damage!
  138.  
  139. ------------------------------------------------------------------------------
  140.  
  141. Improvements over the 37.xx releases (note that this is a re-design):
  142.  
  143. - Keeps care about popular device bugs including the standard-workarounds the
  144.   FFS offers as well, including a MASK, MAXTRANSFER and BUFMEMTYPE.
  145. - Allows concurrent reading and writing to the same stream.
  146. - Implements ACTION_SEEK, i.e. seeking in device streams is possible.
  147. - Automatically turns off the drive motors after a fixed delay like the FFS.
  148. - Handles large devices correctly using the TD64 and/or the TD64 standard.
  149. - Handles errors on Read/Write correctly, unlike the V37 edition.
  150.  
  151. ------------------------------------------------------------------------------
  152.  
  153.                          The THOR-Software Licence (v2, 24th June 1998)
  154.  
  155.  
  156. This License applies to the computer programs known as "Device-Handler".
  157. The "Program", below, refers to such program. The "Archive" refers to the 
  158. the original and unmodified package of distribution, as prepared by the 
  159. author of the Program. Each licensee is addressed as "you".
  160.  
  161.  
  162.  
  163. The Program and the data in the archive are freely distributable
  164. under the restrictions stated below, but are also Copyright (c)
  165. Thomas Richter.
  166.  
  167. Distribution of the Program, the Archive and the data in the Archive by a
  168. commercial organization without written permission from the author to any
  169. third party is prohibited if any payment is made in connection with such
  170. distribution, whether directly (as in payment for a copy of the Program) or
  171. indirectly (as in payment for some service related to the Program, or
  172. payment for some product or service that includes a copy of the Program
  173. "without charge"; these are only examples, and not an exhaustive enumeration
  174. of prohibited activities).
  175.  
  176.  
  177. However, the following methods of distribution
  178. involving payment shall not in and of themselves be a violation of this
  179. restriction:
  180.  
  181.  
  182. (i) Posting the Program on a public access information storage and
  183. retrieval service for which a fee is received for retrieving information
  184. (such as an on-line service), provided that the fee is not
  185. content-dependent (i.e., the fee would be the same for retrieving the same
  186. volume of information consisting of random data).
  187.  
  188.  
  189. (ii) Distributing the Program on a CD-ROM, provided that
  190.  
  191. a) the Archive is reproduced entirely and verbatim on such CD-ROM, including
  192. especially this licence agreement;
  193.  
  194. b) the CD-ROM is made available to the public for a nominal fee only,
  195.  
  196. c) a copy of the CD is made available to the author for free except for
  197. shipment costs, and
  198.  
  199. d) provided further that all information on such CD-ROM is redistributable
  200. for non-commercial purposes without charge.
  201.  
  202.  
  203. Redistribution of a modified version of the Archive, the Program or the
  204. contents of the Archive is prohibited in any way, by any organization,
  205. regardless whether commercial or non-commercial. Everything must be kept
  206. together, in original and unmodified form.
  207.  
  208.  
  209.  
  210.  
  211. Limitations.
  212.  
  213.  
  214. THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO
  215. WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  216. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  217. PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
  218. RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
  219. THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  220. SERVICING, REPAIR OR CORRECTION.
  221.  
  222.  
  223. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE
  224. AND ALL DATA OF THIS ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS
  225. LICENCE BY USING OR REDISTRIBUTING THE PROGRAM.
  226.  
  227.  
  228.                                                         Thomas Richter
  229.  
  230. ------------------------------------------------------------------------------
  231.  
  232. Thomas Richter,
  233.         July 2000
  234.