Gold Fish 3

home *** CD-ROM | disk | FTP | other *** search

/ Gold Fish 3 / goldfish_volume_3.bin / files / dev / debug / serlog / serlog.doc < prev next >

Wrap

Text File | 1995-03-19 | 13.3 KB | 316 lines

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 occur. However, sensible protocols should handle them. Take this as general information, not as warning! Software should never have problems with the device, *very* sensitive hardware *may* however. Also note that version 1.4 comes up with a significant speed-up and some options to get along even with hardware depending on sensitive timing. 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 appropriate 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". PRIORITY -- Priority of serlog's server task. By default this equals 0. This causes trouble with some special applications. (E.g. MultiFax usually doesn't work with TKR's SpeedStar if priority is 0). This is NOT a bug in serlog but a timing problem between the software and the connected device. Try PRIORITY=2 if you're having problems. FILENAME -- Captains log. This is the name of the file the protocol will be written to. YOU SHOULD NEVER use a FILENAME in RAM: It might not actually cause trouble, but it is really, well, silly. If you have enough memory to store the file on a RAM disk you should store it on a harddisk and use a big BUFFERSIZE to buffer the *complete* file during IO operations. There is no need to waste expensive CPU time for filesystems, etc. YOU MUST NEVER use a relative path. Always provide a full path. Again, violance against this recommendation might not actually cause trouble, but if you wish to find the logfile you should keep it in mind, because you don't know the working directory for the server task which opens the file... A good FILENAME is something like "SYS:t/serlog.log", which is the default. BUFFERSIZE -- Size of buffer used for writing to FILENAME. Since version 1.4 the device no longer uses DOS' buffered IO functions but a much more efficient special-purpose buffering technique. The BUFFERSIZE option is used to set the size of the buffer in byte. Actually the device will use *about* BUFFERSIZE byte, i.e. it will adjust BUFFERSIZE to fit its needs. IMPORTANT: This options can by very useful and very dangerous! 1. A bigger buffer generally speeds up the device, thus if you have timing problems with your hardware (e.g. the modem) you may want to increase the BUFFERSIZE. 2. Sooner or later the buffer needs to be written to disk. This will block IO operations, not to mention problems with harddisks which lock interrupts. SO, HOW TO USE IT? If you have enough memory use a real big buffer! Say 2 MB or even more. This will allow to buffer a *COMPLETE* session! The buffer will not be written to disk until the device is closed. You may want to run a test-session first to figure out how big the log-file becomes and then choose BUFFERSIZE a bit bigger than that. If you have not much memory use something between 256 byte and some kB, depending on the application you're debugging. By default serlog will use 256 byte, which is the (internal) minimum and about the same DOS used to use for serlog version <= 1.3. 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. (NO)TIME -- When TIME is on, serlog will supply ever entry in the log-file with the time the IORequest has been sent and the duration of it's completion. NOTE: "TIME" causes serlog using more overhead. E.g it will have to transfer more memory. Therefore it is strongly recommended to a) specify a BUFFERSIZE large enough to buffer a complete session, b) set PRIORITY to, say, 2, c) not to use "TIME" if you don't need it. Also note: Due to multitasking TIME is not able to provide exact values, actually they can be quite inaccurate. The time when an IORequest has been sent ist quite exact, though. @@@ further explanation for public release required 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. HEXDUMP -- When dumping data (e.g. CMD_READ, CMD_WRITE) print it similar as "type <foobar> hex". This option has no effect when BRIEF is on. HEXDUMP and CDUMP cannot be used at the same time. 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. (First reported by Darryl Mcginnis) 1.4 - added support for shared access added configurable PRIORITY of server task speed-up by own memory-management functions speed-up by own buffering functions [bumped revision before public version was finished] 1.5 - added HEXDUMP option (Suggested by Richard Karlsson) added TIME option (Suggested by René Hexel) 1.6 - minor internal changes, recompiled with SAS/C 6.55 TODO ~~~~ - MUI based GUI for slprefs including standard SAVE USE CANCEL buttons which behave equal under OSV37 and OSV39+ - finish a public release before starting a new beta, does anyone know a ftp-server for days with more than 24 hours :-( KNOWN PROBLEMS ~~~~~~~~~~~~~~ No, NOT bugs. I won't document bugs but fix them :) * Some applications depend on very sensitive timing. serlog.device *DOES* use a significant overhead and therefore *IS* slow. Without a major loss of compatibility (serlog claims to be very, say 100%, compatible) there is not much I can do about it :( For example, every (Send|Do|Begin)IO requires multible task-switches. In case you're running into trouble with the speed try to specify a higher priority for the server process, BUT NOT TO HIGH!!! (You need blanance not force.) In most cases PRIORITY=2 should work well. You may want to use this by default. * Q: Although serlog seems to work well, my logfile is always empty. What's going on? A: You're probably using OwnDevUnit.library or for some other reason serlog.device is <closed, opened again, closed again> before the program you want to debug exits. Whenever serlog.device is opened the first time (i.e. the open counter switches from 0 to 1) the logfile is opened and probably deleted. To prevent this from happening just turn on "APPEND" using slprefs. * Q: fmtlog always tells me "LOGFILE contains garbage". A: You've probably rebooted your computer while serlog.device was sill in use. So data buffered by serlog.device has not been written to disk yet. Now fmtlog would tell you "unexpected EOF". Guess what happens if you're starting serlog.device again in APPEND mode... To get out of this you must delete the logfile before you're opening serlog again after an abnormal termination (e.g. reboot). 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: serlog@p13.die-box.in-passau.de 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.