home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d113 / dosdev.lha / DosDev / DOSDEV.DOC < prev    next >
Text File  |  1987-11-21  |  8KB  |  194 lines
  1.  
  2.                 DOS DEVICE DRIVER
  3.  
  4.           DOS DEVICE DRIVER EXAMPLE FOR AZTEC C
  5.  
  6.                    A RAM DISK,
  7.  
  8.                 by Matthew Dillon
  9.  
  10.                   V1.10 (Works with the workbench!)
  11.  
  12.     Dedicated to all those people out there (including me!) who have been
  13.     struggling with DOS devices.  Placed in PUBLIC DOMAIN.  I would like to
  14.     give special thanks to Steve Beats for helping me get it to work with
  15.     the workbench.  He saved me at least 24 manhours plus a couple of white
  16.     hairs.
  17.  
  18.     Documentation is sorely lacking... even the RKM examples are sorely
  19.     lacking.  What programmers need is a working example ... as full an
  20.     implementation as possible to figure out all the little DOS quirks that
  21.     the manuals don't tell you about... Little things like when the driver
  22.     stores a string in a structure it must be in BCPL 'length first'
  23.     format.  There are literally hundreds of these babies!
  24.  
  25. REQUIREMENTS:
  26.  
  27.     -Aztec C compiler
  28.  
  29.     -A precompiled symbol table of all sub-directory include's (*/*.H). i.e.
  30.      one which does NOT include top level stuff like <stdio.h>.  Remember to
  31.      compile with the +L option when generating the symbol table.
  32.  
  33.     -A tiny bit of background with BPTR's and how dos works in general.
  34.  
  35.      The LARGE data and code model will be used... It makes life *much*
  36.      easier.  This will NOT effect performance as there are very few global
  37.      elements anyway.
  38.  
  39.     *Alternately, no requirements if you just want to look at the source.
  40.  
  41.  
  42. MOUNTLIST:
  43.  
  44.     You will want to change this to a more permanent file path, obviously,
  45.     though to run the example you might as well leave the driver in RAM:
  46.  
  47.  
  48. THE EXAMPLE:
  49.  
  50.     How 'bout a RAM disk?  RAM disks use most DOS packet types...  Since my
  51.     RAM disk is not meant for normal usage, There will be a lot of minor
  52.     items I will leave unimplimented:
  53.  
  54.     -I don't check out-of-memory conditions (remember! This is ONLY an
  55.      example!)
  56.  
  57.     -The ARCHIVE protection bit is not supported
  58.  
  59.     All packet types normally associated with a RAM disk are supported,
  60.     Most especially LOCKS, which *many* people have not been able to figure
  61.     out in the past.  There are also a number of compatibility issues,
  62.     discussed below.
  63.  
  64. DEBUGGING:
  65.  
  66.     Since this is an example, FULL Debugging has been implemented.  Since
  67.     the DOS device driver cannot make DOS library calls itself (confusion
  68.     on the message port), CreatProc() is used to create a secondary process
  69.     which will do the actual printing of the debug messages.  The messages
  70.     are sent to the debug process via a dedicated message port.
  71.  
  72.     Since Debugging causes a huge efficiency decrease, and since you are
  73.     going to want to fool around with the device, you can turn off debug
  74.     error message output by:
  75.  
  76.     CD test:
  77.     type debugoff    (will get an error, but debugging will be turned
  78.             off)
  79.  
  80.     alternately, 'type debugon' will turn it back on.
  81.  
  82.     The debugging code itself is a good example.
  83.  
  84.     ---------------------------------------------------------------------
  85.  
  86. RESTRICTIONS:
  87.  
  88.     The Workbench assumes that locks are always sizeof(struct FileLock).
  89.     Although DOS allows you to extend the structure however you like, if
  90.     you want your driver to work with the workbench it MUST be a normal
  91.     FileLock.  This isn't a big problem... simply use the fl_Link and
  92.     fl_Key fields to point to other things.
  93.  
  94.     The Workbench checks the DOS Device List every second or so.  To make
  95.     a disk icon appear (see the source), you must construct a VOLUME node.
  96.     This is in addition to the DEVICE node that DOS already constructed
  97.     for our device driver.
  98.  
  99.     If you do not intend to support the Workbench, you do not need to
  100.     make a volume node, and can extend the FileLock structure however you
  101.     want (beyond the required fields, that is).
  102.  
  103.  
  104. DOS IN GENERAL:
  105.     DOS is the only part of the Amiga that was written in (ugghh) BCPL.
  106.     BCPL has many strange notions.  Pointers in BCPL are always longword
  107.     aligned and shifted right by 2 (divided by 4), so 0x0 would mean
  108.     address 0, 0x1 would mean address 4, etc...
  109.  
  110.     To convert BPTR's to C pointers (CPTR's), simply shift left by 2. To
  111.     convert the otherway, simply shift right by 2, but remembering that the
  112.     original C pointer must be longword aligned.
  113.  
  114.     BCPL strings (BSTR's) are quite different.  Most commonly you have
  115.     "BPTR's to BSTR's", which means you both have to convert the pointer
  116.     to a C pointer, and then interpret it differently.    The first character
  117.     in a BSTR is the length of the string (unsigned 0 to 255).    The
  118.     actual string starts at ptr+1 (CPTR+1), and has NO TERMINATION
  119.     CHARACTER.    See the BTOS() routine in DEVICE.C
  120.  
  121.     Most DOS structures which have string arrays are in BCPL format.  For
  122.     example, the Name and Comment fields in FileInfoBlock are in BCPL
  123.     format.  The DOS library from C converts these fields to normal C
  124.     strings for you when you make Examine()/ExNext() calls, but are BCPL
  125.     strings inside any device driver.
  126.  
  127. FILESYSTEMS:
  128.     Beware that it is perfectly acceptable to CurrentDir(lock) a lock which
  129.     is a file rather than a directory, then open "" to access that file.
  130.     The workbench does this quite a bit.
  131.  
  132.     One major point not addressed well in my device driver is handling
  133.     multiple writer's to the same file (or a reader and a writer).  It is
  134.     also acceptable to open a file ACCESS_OLD (1005) and write to it.
  135.  
  136.     Another common problem is an incorrectly implemented Examine()/ExNext()
  137.     function.    Keep in mind that *any* entry in the directory being
  138.     scanned can be removed or moved out of that directory at anytime,
  139.     including between ExNext() calls.  My RAM: disk accomplishes this by
  140.     rescanning the directory at every ExNext() call (an admittedly
  141.     inefficient method).
  142.  
  143.     Finally, you must properly implement shared access to files.  Remember
  144.     that it *is* possible to have a reader AND a writer, or two writers, or
  145.     N readers and N writers each with separate filehandles going to a
  146.     single file.  I do not properly implement some of these cases in my
  147.     example, but note the bug at the beginning of the source.o
  148.  
  149.     ACTION_INHIBIT is not addressed well in the device driver.    This has
  150.     one argument, a Bool TRUE or FALSE.  If TRUE, it 'inhibits' access to
  151.     the low level hardware handling the device.  This isn't very
  152.     useful for a RAM disk.
  153.  
  154.     My example device does not handle small block sizes well in that they
  155.     cause a large amount of overhead.  A really serious RAM disk would
  156.     combine small blocks into larger ones (in terms of memory storage).
  157.     This was actually a bug in the 1.1 RAM: disk.  I'm not sure how well
  158.     the 1.2 RAM: disk fixes it.  Workbench has a nasty habit of writing 1
  159.     and 2 byte blocks (somebody should really fix that!).
  160.  
  161.  
  162. OTHER DOS PECULARITIES:
  163.  
  164.     NON FILE SYSTEMS:    Specifically, control terminals like CON: ..
  165.     The CLI and other programs get a duplicate filehandle of the control
  166.     terminal by openning the file '*'.  This is how the CLI is able to open
  167.     two filehandles (Input()/Output()) to the same CON: device that would
  168.     otherwise cause two invocations of a CON: device.
  169.  
  170.     This isn't to say you can simply Open("*",1005), you CAN'T!  You must
  171.     open CON:blah, then extract the handler process ID from that
  172.     filehandle, then manually send an OPEN_OLD packet with filename "*" to
  173.     the handler.
  174.  
  175.     ACTION_DISK_INFO, when sent to a CONSOLE device, will return the window
  176.     associated with the console as follows:
  177.  
  178.         id_VolumeNode   =    console window
  179.         id_InUse        =    console IO blvock
  180.  
  181.     There are probably many more.
  182.  
  183.  
  184.  
  185.                     Matthew Dillon
  186.  
  187.                     ARPA: dillon@ucbvax.berkeley.edu
  188.                     UUCP: ..!ihnp4!ucbvax!dillon
  189.                     SNAIL:    Matthew Dillon
  190.                         891 Regal Rd.
  191.                         Berkeley, Ca. 94708
  192.  
  193.  
  194.