SERLOG.DEVICE Preface ~~~~~~~ Space - the final frontier! These are the vo... oh, sorry :-) "serlog.device" is a special purpose debugging tool which allows you to monitor serial-IO. I wrote this when trying to track down some problems with my FAX-Software and was ask to make it available to other people. Legal stuff ~~~~~~~~~~~ serlog.device is Copyright (c) by the author Stefan Pröls. It is released as FREEWARE meaning that you may distribute and use it in any form without limitations. There is absolutely no warranty on any part of this package. Use it on your own risk. Technical Overview ~~~~~~~~~~~~~~~~~~ serlog.device passes all IOExtSer requests to a "real" serial.device and writes the results to a file. You may configure the amount of information to be stored in the log. The log-file created by serlog.device contains a binary dump which can be formatted (i.e. transferred into a readable version) using the supplied formatter. Note that serlog.device uses *significant* overhead over the underlying serial.device, resulting in very low baud-rates. OS 2.0 or greater is required. Installation ~~~~~~~~~~~~ Just copy "serlog.device" to "DEVS:" and the supplied programs "slprefs" and "fmtlog" to any place you want. If you have a CPU >= 68020 use the binaries from the bin020 directory, otherwise use the ones from bin000. If you have problems with the speed try to reduce mulitasking while serlog.device is in use and try to hold most things in 32 Bit FAST memory. E.g. "CPU FASTROM" will result in a significant speed-up on 68030 CPUs using 16-Bit ROMS (e.g. A2k-30). When using high-speed connections hardware-overflow errors may occure. However, sensible protocols should handle them. Usage ~~~~~ Tell the software you want to debug to use "serlog.device" unit 0 instead of "serial.device". Before you start the program you should tell the device what to monitor. "slprefs" is used for that. "slprefs" is a shell-driven -- sorry ;-) -- preferences utility for the serlog.device. Basically it allows you to turn on and off monitoring of certain commands like "CMD_READ". To do so specify the appropirate commands and append "ADD" or "SUB" to the command line. You may get a list of possible commands by the includes or by typing "slprefs ?". There are some more options: DEVICE -- The underlying device used to execute commands. E.g. "serial.device". UNIT -- The unit of the underlying device. DO NOT MIX THIS UP with the unit of "serlog.device"! serlog.device supports *ONLY* unit *0*. If you have some kind of multi-IO board you may for example specify "DEVICE=multiio.device UNIT=2" which means that "serlog.device" when opened for unit *0* will use unit 2 of "multiio.device". FILENAME -- Captains log. This is the name of the file the protocol will be written to. SHOW -- Shows the current settings. They are always shown but when this option is specified they will *only* be shown, i.e. changes will have no effect. CMD_*, SDCMD_* -- Commands to (or not to) monitor. ALL -- Same as all (SD)CMD_*s. ADD -- Turn on monitoring (SD)CMD_*s SUB -- Turn off monitoring (SD)CMD_*s DEFAULTS -- Reset all preferences to their default values. (NO)APPEND -- When APPEND is on, the log-file will not be deleted when OpenDevice() is called but all new data will be appended. Useful in case you're using "OwnDevUnit.library", for example. Note that any changes to the preferences will not have effect until the device is restarted, i.e. when OpenDevice() (with exclusive access) is called the next time. The log-file created by serlog.device contains a binary dump of information about processed IOExtSer requests. To create a readable output you use the "fmtlog" utility. If you do not specify a name for the log-file "fmtlog" will use the one set with slprefs. "fmtlog" knows a few more or less useful options: GURULAYOUT -- Do not create a "nice" output but a very compact one. Normal human beings are likely to get completely mad when reading that. However, if you're a guru and you want to format a very large file which would produce an even larger output you may try this. BRIEF -- Do not extract all available information but only a brief overview on what happened. Basically there will be no data for CMD_READ and CMD_WRITE. CDUMP -- When dumping binary data use "\x??" notation for writing non-ASCII characters. Otherwise all non-printable characters will shown by ".". When CDUMP is specified some further 'C' like notations will be used, e.g. '\n' for NL or '\\' for "\". Quotes however will not be affected. This option has no effect when BRIEF is on. History ~~~~~~~ 1.0 - works for me and only for me... 1.1 - temporary version 1.2 - complete rework, first public release This is a major update - but as this isn't a SASG product this doesn't matter. 1.3 - fixed a problem which made the preferences utility unusable due to a bug in AmigaOS versions prior V39. Nothing else changed. Target for flames ~~~~~~~~~~~~~~~~~ Ahm, flames? Hey, read the legal stuff above ;-) However, comments are welcome. If you have any suggestions or if you think serlog.device is THE tool you've been searching for for years and want to send me some new Amigas or SUNs, feel free to contact me: Internet: proels@fmi.uni-passau.de Fidonet: Stefan Proels,2:2494/22.13 Snailmail (ever heard about that?): Stefan Pröls Rudolf-Guby-Str. 1 94032 Passau Germany Earth email is preferred.