home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / fish / disks / d1015.lha / Programs / SerLog / Readme < prev   
Encoding:
Text File  |  1994-09-10  |  6.1 KB  |  170 lines
  1.  
  2.  
  3.  
  4.                               SERLOG.DEVICE
  5.  
  6.  
  7. Preface
  8. ~~~~~~~
  9.   Space - the final frontier! These are the vo... oh, sorry :-)
  10.   "serlog.device" is a special purpose debugging tool which allows you to
  11.   monitor serial-IO.
  12.   I wrote this when trying to track down some problems with my FAX-Software
  13.   and was ask to make it available to other people.
  14.  
  15.  
  16. Legal stuff
  17. ~~~~~~~~~~~
  18.   serlog.device is Copyright (c) by the author Stefan Pröls.
  19.   It is released as FREEWARE meaning that you may distribute and use it in
  20.   any form without limitations.
  21.   There is absolutely no warranty on any part of this package.
  22.   Use it on your own risk.
  23.  
  24.  
  25. Technical Overview
  26. ~~~~~~~~~~~~~~~~~~
  27.   serlog.device passes all IOExtSer requests to a "real" serial.device
  28.   and writes the results to a file.
  29.   You may configure the amount of information to be stored in the log.
  30.   The log-file created by serlog.device contains a binary dump which can
  31.   be formatted (i.e. transferred into a readable version) using the supplied
  32.   formatter.
  33.  
  34.   Note that serlog.device uses *significant* overhead over the underlying
  35.   serial.device, resulting in very low baud-rates.
  36.  
  37.   OS 2.0 or greater is required.
  38.  
  39.  
  40. Installation
  41. ~~~~~~~~~~~~
  42.   Just copy "serlog.device" to "DEVS:" and the supplied programs "slprefs"
  43.   and "fmtlog" to any place you want.
  44.   If you have a CPU >= 68020 use the binaries from the bin020 directory,
  45.   otherwise use the ones from bin000.
  46.  
  47.   If you have problems with the speed try to reduce mulitasking while
  48.   serlog.device is in use and try to hold most things in 32 Bit FAST
  49.   memory. E.g. "CPU FASTROM" will result in a significant speed-up on
  50.   68030 CPUs using 16-Bit ROMS (e.g. A2k-30).
  51.  
  52.   When using high-speed connections hardware-overflow errors may occure.
  53.   However, sensible protocols should handle them.
  54.  
  55.  
  56. Usage
  57. ~~~~~
  58.   Tell the software you want to debug to use "serlog.device" unit 0 instead
  59.   of "serial.device".
  60.  
  61.   Before you start the program you should tell the device what to monitor.
  62.   "slprefs" is used for that.
  63.  
  64.   "slprefs" is a shell-driven -- sorry ;-) -- preferences utility for the
  65.   serlog.device. Basically it allows you to turn on and off monitoring of
  66.   certain commands like "CMD_READ". To do so specify the appropirate commands
  67.   and append "ADD" or "SUB" to the command line. You may get a list of possible
  68.   commands by the includes or by typing "slprefs ?".
  69.   There are some more options:
  70.  
  71.     DEVICE      -- The underlying device used to execute commands.
  72.                    E.g. "serial.device".
  73.  
  74.     UNIT        -- The unit of the underlying device.
  75.                    DO NOT MIX THIS UP with the unit of "serlog.device"!
  76.                    serlog.device supports *ONLY* unit *0*.
  77.                    If you have some kind of multi-IO board you may for example
  78.                    specify "DEVICE=multiio.device UNIT=2" which means that
  79.                    "serlog.device" when opened for unit *0* will use unit 2
  80.                    of "multiio.device".
  81.  
  82.     FILENAME    -- Captains log. This is the name of the file the protocol
  83.                    will be written to.
  84.  
  85.     SHOW        -- Shows the current settings. They are always shown but when
  86.                    this option is specified they will *only* be shown, i.e.
  87.                    changes will have no effect.
  88.  
  89.     CMD_*,
  90.     SDCMD_*     -- Commands to (or not to) monitor.
  91.  
  92.     ALL         -- Same as all (SD)CMD_*s.
  93.  
  94.     ADD         -- Turn on monitoring (SD)CMD_*s
  95.  
  96.     SUB         -- Turn off monitoring (SD)CMD_*s
  97.  
  98.     DEFAULTS    -- Reset all preferences to their default values.
  99.  
  100.     (NO)APPEND  -- When APPEND is on, the log-file will not be deleted when
  101.                    OpenDevice() is called but all new data will be appended.
  102.                    Useful in case you're using "OwnDevUnit.library",
  103.                    for example.
  104.  
  105.   Note that any changes to the preferences will not have effect until the
  106.   device is restarted, i.e. when OpenDevice() (with exclusive access) is
  107.   called the next time.
  108.  
  109.  
  110.   The log-file created by serlog.device contains a binary dump of information
  111.   about processed IOExtSer requests. To create a readable output you use the
  112.   "fmtlog" utility.
  113.  
  114.   If you do not specify a name for the log-file "fmtlog" will use the one set
  115.   with slprefs. "fmtlog" knows a few more or less useful options:
  116.  
  117.     GURULAYOUT  -- Do not create a "nice" output but a very compact one.
  118.                    Normal human beings are likely to get completely mad
  119.                    when reading that. However, if you're a guru and you
  120.                    want to format a very large file which would produce
  121.                    an even larger output you may try this.
  122.  
  123.     BRIEF       -- Do not extract all available information but only a
  124.                    brief overview on what happened. Basically there will
  125.                    be no data for CMD_READ and CMD_WRITE.
  126.  
  127.     CDUMP       -- When dumping binary data use "\x??" notation for writing
  128.                    non-ASCII characters. Otherwise all non-printable
  129.                    characters will shown by ".".
  130.                    When CDUMP is specified some further 'C' like notations
  131.                    will be used, e.g. '\n' for NL or '\\' for "\". Quotes
  132.                    however will not be affected.
  133.                    This option has no effect when BRIEF is on.
  134.  
  135.  
  136. History
  137. ~~~~~~~
  138.   1.0   - works for me and only for me...
  139.   1.1   - temporary version
  140.   1.2   - complete rework, first public release
  141.           This is a major update - but as this isn't a SASG product this
  142.           doesn't matter.
  143.   1.3   - fixed a problem which made the preferences utility unusable
  144.           due to a bug in AmigaOS versions prior V39.
  145.           Nothing else changed.
  146.  
  147.  
  148. Target for flames
  149. ~~~~~~~~~~~~~~~~~
  150.   Ahm, flames? Hey, read the legal stuff above ;-) However, comments are
  151.   welcome. If you have any suggestions or if you think serlog.device is
  152.   THE tool you've been searching for for years and want to send me some
  153.   new Amigas or SUNs, feel free to contact me:
  154.  
  155.       Internet: proels@fmi.uni-passau.de
  156.       Fidonet:  Stefan Proels,2:2494/22.13
  157.  
  158.       Snailmail (ever heard about that?):
  159.  
  160.           Stefan Pröls
  161.           Rudolf-Guby-Str. 1
  162.           94032 Passau
  163.           Germany
  164.  
  165.           Earth
  166.  
  167.  
  168.       email is preferred.
  169.  
  170.