home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 171.lha / SupLib / dio.doc < prev    next >
Text File  |  1988-04-28  |  7KB  |  182 lines
  1.  
  2.                     DIO
  3.  
  4.     EXEC device driver IO support routines... makes everything easy.
  5.  
  6.     dfd = dio_open(name, unit, flags, req/NULL)
  7.  
  8.       open an IO device.  Note: in some cases you might have to provide a
  9.       request structure with some fields initialized (example, the console
  10.       device requires certain fields to be initialized).  For instance, if
  11.       openning the SERIAL.DEVICE, you would want to give an IOExtSer
  12.       structure which is completely blank execept for the io_SerFlags
  13.       field.
  14.  
  15.       The request structure's message and reply ports need not be
  16.       initialized.  The request structure is no longer needed after
  17.       the dio_open().
  18.  
  19.       returns NULL = error, else DIO descriptor (a pointer) returned.
  20.  
  21.  
  22.   dio_close(dfd)
  23.  
  24.       close an IO device.  Any pending asyncronous requests are
  25.       AbortIO()'d and then Wait'ed on for completion.
  26.  
  27.  
  28.   dio_closegrp(dfd)
  29.  
  30.       close EVERY DIO DESCRIPTOR ASSOCIATED WITH THE dio_open() call
  31.       that was the parent for this descriptor.    That is, you can get
  32.       a descriptor using dio_open(), dio_dup() it a couple of times,
  33.       then use dio_closegrp() on any ONE of the resulting descriptors
  34.       to close ALL of them.
  35.  
  36.  
  37.   dio_cact(dfd,bool)
  38.  
  39.       If an error occurs (io_Error field), the io_Actual field is usually
  40.       not modified by the device driver, and thus contains garbage.  To
  41.       provide a cleaner interface, you can have the DIO_CTL() and
  42.       DIO_CTL_TO() calls automatically pre-clear this field so if an
  43.       io_Error does occur, the field is a definate 0 instead of garbage.
  44.  
  45.       In most cases you will want to do this.  An exception is the
  46.       TIMER.DEVICE, which uses the io_Actual field for part of the timeout
  47.       structure.
  48.  
  49.       This flags the particular dio descriptor to do the pre-clear, and any
  50.       new descriptors obtained by DIO_DUP()ing this one will also have the
  51.       pre-clear flag set.
  52.  
  53.  
  54.   dio_dup(dfd)
  55.  
  56.       Returns a new channel descriptor referencing the same device. The new
  57.       descriptor has it's own signal and IO request structure. For
  58.       instance, if you openned the serial device, you might want to dup the
  59.       descriptor so you can use one channel to pend an asyncronous read,
  60.       and the other channel to write out to the device and do other things
  61.       without disturbing the asyncronous read.
  62.  
  63.  
  64.   sig = dio_signal(dfd)
  65.  
  66.       get the signal number (0..31) used for a DIO descriptor. This allows
  67.       you to Wait() for asyncronous requests.  Note that if your Wait()
  68.       returns, you should double check using dio_isdone()
  69.  
  70.  
  71.   req = dio_ctl_to(dfd, command, buf, len, to)
  72.  
  73.       Same as DIO_CTL() below, but (A) is always syncronous, and (B) will
  74.       attempt to AbortIO()+WaitIO() the request if the timeout occurs
  75.       before the IO completes.
  76.  
  77.       the 'to' argument is in microseconds.
  78.  
  79.       If timeout occurs before request completes, and DIO aborts the
  80.       request, some devices, such as the SERIAL.DEVICE do not have the
  81.       io_Actual field set properly.  Always check the io_Error field for
  82.       an abort before using io_Actual.
  83.  
  84.  
  85.   req = dio_ctl(dfd, command, buf, len)
  86.  
  87.       DIO_CTL() is the basis for the entire library.  It works as follows:
  88.  
  89.       (1) If the channel isn't clear (there is an asyncronous IO request
  90.       still pending), DIO_CTL() waits for it to complete
  91.  
  92.       (2) If the command is 0, simply return a pointer to the io
  93.       request structure.
  94.  
  95.       (3) If the DIO_CACT() flag is TRUE, the io_Actual field of the
  96.       request is cleared.
  97.  
  98.       (4) Set the io_Data field to 'buf', and io_Length field to 'len'
  99.       If the command is positive, use DoIO().  If the command
  100.       negative, take it's absolute value and then do a SendIO().
  101.       (The command is placed in the io_Command field, of course).
  102.  
  103.       (5) return the IO request structure
  104.  
  105.  
  106.   bool= dio_isdone(dfd)
  107.  
  108.       return 1 if current channel is clear (done processing), else 0. e.g.
  109.       if you did, say, an asyncronous read, and dio_isdone() returns true,
  110.       you can now use the data buffer returned and look at the io_Actual
  111.       field.
  112.  
  113.       You need not do a dio_wait() after dio_isdone() returns 1.
  114.  
  115.  
  116.   req = dio_wait(dfd)
  117.  
  118.       Wait on the current channel for the request to complete and then
  119.       return the request structure. (nop if channel is clear)
  120.  
  121.  
  122.   req = dio_abort(dfd)
  123.  
  124.       Abort the request on the current channel (nop if channel is
  125.       clear).  Sends an AbortIO() if the channel is active and then
  126.       WaitIO()'s the request.
  127.  
  128.     ------ MACROS ------
  129.  
  130.     dio_simple() and related macros return the !io_Error field. That
  131.     is, 0=ERROR, 1=OK
  132.  
  133.     dio_actual() returns the io_Actual field instead of !io_Error.
  134.  
  135.     NOTE: the io_Actual field may not be set by the device if an
  136.     error condition exists.  To make the io_ctl() and io_ctl_to()
  137.     call automatically clear the io_Actual field before doing the
  138.     io operation, use the DIO_CACT() call.  The reason this isn't
  139.     done automatically by default is that some devices require
  140.     parameters to be passed in the io_Actual field (like the
  141.     timer.device).
  142.  
  143.     Remember, Asyncronous IO is done by sending -com instead of com.
  144.     (that is, negative command).
  145.  
  146.       CALL              Syncronous IO   Asyncronous IO
  147.  
  148.   dio_simple(dfd,com)             0=ERROR, 1=OK   undefined
  149.   dio_actual(dfd,com)             io_Actual       undefined
  150.   dio_reset(dfd)                  0=ERROR, 1=OK   n/a
  151.   dio_update(dfd)                 0=ERROR, 1=OK   n/a
  152.   dio_clear(dfd)                  0=ERROR, 1=OK   n/a
  153.   dio_stop(dfd)                   0=ERROR, 1=OK   n/a
  154.   dio_start(dfd)                  0=ERROR, 1=OK   n/a
  155.   dio_flush(dfd)                  0=ERROR, 1=OK   n/a
  156.   dio_getreq(dfd)                 returns a ptr to the IO
  157.                   request structure
  158.  
  159.       NOTE: If you use the following, you probably want to have the device
  160.       library automatically clear the io_Actual field before sending the
  161.       request so you get 0 if an error occurs.    That is: dio_cact(dfd,1):
  162.  
  163.   dio_read(dfd,buf,len)           returns actual bytes read
  164.   dio_write(dfd,buf,len)          returns actual bytes written
  165.  
  166.     The timeout argument for dio_readto() and dio_writeto()
  167.     is in MICROSECONDS, up to 2^31uS.
  168.  
  169.   dio_readto(dfd,buf,len,to)      returns actual bytes read
  170.   dio_writeto(dfd,buf,len,to)     returns actual bytes written
  171.  
  172.     The asyncronous dio_reada() and dio_writea() do not
  173.     return anything.
  174.  
  175.   dio_reada(dfd,buf,len)          begin asyncronous read
  176.   dio_writea(dfd,buf,len)         begin asyncronous write
  177.  
  178.  
  179.  
  180.  
  181.  
  182.