home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 103.lha / IntDevExpl / idev.doc < prev    next >
Text File  |  1986-11-21  |  8KB  |  245 lines
  1.  
  2.  
  3.  
  4.  
  5.         IDEV: An Interactive Device Explorer
  6.              --------------------------
  7.             Ed Puckett     August 26, 1987
  8.  
  9.  
  10.  
  11. INTRODUCTION
  12.  
  13.     IDEV will let you muck around with Amiga Exec devices,
  14.     interactively sending and receiving data through IORequests.
  15.     A data buffer and an extended IORequest are maintained
  16.     internally for your use.  You may read or write the data
  17.     contained in these two structures to or from disk files;
  18.     with the aid of a file zap utility or an invertible dump
  19.     program, you will be able to send almost anything you please
  20.     to a device, and also see what returns.
  21.  
  22.     I wrote IDEV to help me discover how to use the sasi.device
  23.     which came with my Tecmar T-card.  It was my means of
  24.     "hypothesis testing" between rounds of disassembly!
  25.  
  26.     [ Amiga is a trademark of Commodore-Amiga Inc.            ]
  27.     [ Tecmar and T-card are trademarks of Tecmar, Incorporated. ]
  28.  
  29.  
  30. BACKGROUND AND CONVENTIONS
  31.  
  32.     This document assumes some familiarity with Exec devices
  33.     and libraries.
  34.  
  35.     Numbers will be represented in this document as follows:
  36.  
  37.     * If a string begins with `0x', the remaining portion
  38.       is the hexadecimal representation of the intended number.
  39.  
  40.     * If it begins with `0', but not `0x', then it is octal.
  41.  
  42.     * Strings beginning with the digits `1' through `9' are
  43.       decimal representations.
  44.  
  45.     (Unfortunately, IDEV itself only understands numbers input
  46.     in decimal representation, even if they begin with `0'.
  47.     IDEV's output follows the above conventions.)
  48.  
  49.  
  50. USING IDEV
  51.  
  52.     IDEV is invoked with three parameters: the name of the device,
  53.     the unit number, and the flags to be passed to OpenDevice().
  54.     For example,
  55.  
  56.         IDEV sasi.device 1 10
  57.  
  58.     tells IDEV to open unit 1 of the device "sasi.device" with
  59.     flags 0x0A.  (Note that you are forced to give the decimal
  60.     representation of numbers.)
  61.  
  62.     Unless there is a problem opening the device (in which case
  63.     you will be informed and the program will exit), idev will
  64.     print the following:
  65.  
  66.     | Device: "sasi.device"
  67.     | Unit:   1
  68.     | Flags:  0x0000000A
  69.     |
  70.     | Buffer Address = 0x00123456      I/O Request Address = 0x00654321
  71.     | Buffer Size     = 0x00000400      I/O Request Size    = 0x00002000
  72.     |
  73.     | Commands:
  74.     |    ? or h             help
  75.     |    ri filename         read  I/O request from file
  76.     |    wi filename size         write I/O request to file
  77.     |    rb filename         read  buffer from file
  78.     |    wb filename size         write buffer to file
  79.     |    &                 patch buffer address to ioreq->io_Data
  80.     |    !                 send I/O request to device via DoIO
  81.     |    ^ n             send I/O request in reg A1 via vector #n
  82.     |    q                 quit
  83.     |
  84.     | Notes:  I/O request memory is read/written starting from io_Command.
  85.     |      Vectors are numbered starting from 1.
  86.     |      ESC ('\\033') will abort a partially entered command.
  87.  
  88.     Note: the addresses given above are for illustration only.
  89.     They are the addresses of the internal buffers, wherever they
  90.     landed.  The sizes reflect hard-coded constants: the data buffer
  91.     is given 1024 bytes and the I/O request is given 8192 bytes.
  92.     The "Device", "Unit" and "Flags" come from the command line.
  93.  
  94.     The above help screen is produced by typing either `?'
  95.     or `h'.  (All commands are parsed ignoring case, so `H'
  96.     will also produce the help screen.)
  97.  
  98.     Reading Data Into the Internal Structures
  99.  
  100.     To modify either the data buffer or the I/O Request
  101.     structure, you may read them in from a file.  For example,
  102.  
  103.         r i T:iobytes
  104.  
  105.     reads the file "T:iobytes" into the I/O Request.  It stops
  106.     when EOF is reached, or when the end of the buffer is reached,
  107.     whichever comes first.    (If the file is indeed larger than
  108.     the buffer, you will be informed.)
  109.  
  110.     (Note: there is no way to specify file names which contain
  111.     embedded spaces.  Quotes will be parsed as parts of their
  112.     adjoining strings.)
  113.  
  114.     The space between the `r' and the `i' above is optional.
  115.     Commands may be spread across more than one line or,
  116.     opppositely, many commands may be issued on a single line.
  117.     However, the prompt "IDEV-->" will be issued as each
  118.     command is parsed.
  119.  
  120.     If an error is encountered while parsing a command, the
  121.     remaining characters on the line will be discarded and
  122.     the next command will be parsed beginning on the next line.
  123.  
  124.     When the I/O Request is read from or written to a file, its
  125.     first 0x1C bytes are unaffected (i.e., the io_Message,
  126.     io_Device and io_Unit fields are untouched).  The total
  127.     number of bytes transferred does not include these bytes.
  128.  
  129.     Writing Internal Data to a File
  130.  
  131.     Now, let's say you have sent an I/O Request (through
  132.     mechanisms described later), and want to examine the data
  133.     buffer which the device filled for you.  You might type:
  134.  
  135.         w b T:returned_buf 512
  136.  
  137.     This will write a binary image of the first 512 bytes of the
  138.     internal data buffer to the file "T:returned_buf".  Unless
  139.     the buffer contained text, it will probably not be editable.
  140.     Instead, process files written in this manner with a file
  141.     zap program, or use a dump program (preferably an invertible
  142.     one, so you can convert the edited files back to binary).
  143.  
  144.     Notice that if we had written the I/O Request like:
  145.  
  146.         w i T:returned_ioreq 512
  147.  
  148.     we get bytes 0x001C through 0x021B of the I/O request dumped
  149.     to the file because the first 0x1C bytes are protected.
  150.  
  151.     The `&' command patches the buffer address into the
  152.     I/O Request's io_Data field.  A typical setup for a call
  153.     to a device is:
  154.  
  155.         ri T:intended_ioreq  rb T:intended_buf    &
  156.  
  157.     All three commands are entered on one line here.  This reads
  158.     the I/O request and data buffer from their respective files,
  159.     and then links them using the `&' command.
  160.  
  161.     Don't forget to link in the data buffer before sending
  162.     the I/O Request, especially if you want the device to
  163.     write to the buffer.  Leaving garbage there (say 0x000004)
  164.     can evoke Amiga trances!
  165.  
  166.     Sending Data to the Device
  167.  
  168.     Two mechanisms are provided by which you may call the
  169.     device with data you have prepared for it.
  170.  
  171.     `!' sends the current I/O Request to the device via DoIO(),
  172.     and prints the returned error code when (if?) it returns
  173.     (or "no error" if 0 is returned).
  174.  
  175.     `^', in conjunction with a number, calls one of the
  176.     device's library vectors.  For example,
  177.  
  178.         ^ 1
  179.  
  180.     calls the device's Open() vector, and
  181.  
  182.         ^ 3
  183.  
  184.     calls the device's Expunge() vector.  The device is passed
  185.     the pointer to the I/O request in register A1, and the
  186.     value returned is printed in the same fashion as with `!'.
  187.  
  188.     The device's vector table is scanned in an attempt to
  189.     prevent nonexistent vectors from being called.    If a NULL
  190.     or -1 longword is found prior to your requested vector,
  191.     an error will be issued.
  192.  
  193.     If this calling mechanism does not fit the device with which
  194.     you are working, you must modify the program.  Notably, the
  195.     register by which the I/O request is sent cannot be changed
  196.     by any IDEV command.
  197.  
  198.     Additional Notes
  199.  
  200.     Command parsing is case-insensitive.
  201.  
  202.     CTRL-C will abort most operations over which IDEV has control.
  203.     It probably will not break out of a stuck DoIO() call, however.
  204.     CTRL-C stops the cleans up the structures and exits the program.
  205.  
  206.     The <ESC> character will abort partially entered commands,
  207.     like the following:
  208.  
  209.         w b T:junk <ESC>
  210.  
  211.     In addition, the rest of the line on which the <ESC> appears
  212.     is discarded.
  213.  
  214.     Warnings are prefixed by three astersisks followed by the word
  215.     "Warning: " ("*** Warning: ").
  216.  
  217.     Error messages are prefixed by three asterisks ("***") not
  218.     followed by the word "Warning".
  219.  
  220.  
  221. COMPILATION
  222.  
  223.     IDEV is written in C, with one support routine in 68000
  224.     assembly language.  It compiles using Lattice 3.03.
  225.  
  226.     Compile main.c and idev.c to produce main.o and idev.o,
  227.     and assemble vect_intfc.asm to vect_intfc.o.  Then use
  228.     Alink (or BLink) to link the modules together:
  229.  
  230.         Alink FROM    LStartup.obj,main.o,idev.o,vect_intfc.o \
  231.               TO      idev                      \
  232.               LIBRARY amiga.lib lc.lib
  233.  
  234. AUTHOR
  235.  
  236.       +-------------------------------------------\
  237.       | Ed Puckett                   \
  238.       |                         \
  239.       | EMAIL:      ...!ihnp4!mit-eddie!mit-oz!qix     }     (26-Aug-87)
  240.       | US MAIL:  MIT Branch PO, Box 61         /
  241.       |       Cambridge, MA  02139           /
  242.       +-------------------------------------------/
  243.  
  244.  
  245.