workbench/tools/debug/sashimi/sashimi.doc

   1 Sashimi v1.6
   2
   3 Written by Olaf `Olsen' Barthel <olsen@sourcery.han.de>
   4 Public Domain
   5
   6
   7 Sashimi intercepts raw serial debugging output on your own machine; command
   8 line options are:
   9
  10 Startup: [RECOVER=name]
  11          [ON] [BUFK=n (n must be a power of 2)] [BUFFERSIZE=n] [NOPROMPT]
  12          [QUIET] [ASKEXIT] [ASKSAVE] [TIMERON] [CONSOLE] [WINDOW=name]
  13
  14 Runtime: [OFF] [SAVE] [SAVEAS=name] [EMPTY]
  15
  16
  17 Sashimi is a tool to intercept the raw serial output of Enforcer, Mungwall,
  18 and all tool and application debugging output that uses kprintf(). This
  19 makes it possible to use serial debugging on a single Amiga, without
  20 interfering with attached serial hardware such as modems and serial
  21 printers.
  22
  23 This is a drop-in replacement for the "Sushi" tool, as written by Carolyn
  24 Scheppner. Well, not exactly. Sashimi has a few different/new features and
  25 does not support the complete feature set of the "Sushi" tool. Sashimi only
  26 runs from Shell and requires Kickstart 2.04 or higher. Sashimi cannot patch
  27 the older Enforcer at run time which means that you have to use Enforcer
  28 V37 or an equivalent like CyberGuard.
  29
  30
  31 Quick usage
  32 ===========
  33 Here's what's in my "S:User-Startup" file:
  34
  35 Run >NIL: MungWall NAMETAG
  36 Run >NIL: Enforcer RAWIO
  37 Run >NIL: Sashimi CONSOLE BUFK=64 NOPROMPT ASKEXIT ASKSAVE
  38
  39 All standard serial debugging functions are intercepted. Currently, the
  40 patch to the serial debugging input function just returns a `y'. Standard
  41 serial debugging output and Enforcer output go into Sashimi's circular buffer
  42 (the size is user-definable, with a default size of 32K), where it is
  43 noticed by the Sashimi process and written to the output window. The
  44 Sashimi process is signalled whenever a carriage return or linefeed comes
  45 through kprintf().
  46
  47 Sashimi has several startup options, and several runtime options:
  48
  49 Startup: [RECOVER=name]
  50          [ON] [BUFK=n (n must be a power of 2)] [BUFFERSIZE=n] [NOPROMPT]
  51          [QUIET] [ASKEXIT] [ASKSAVE] [TIMERON] [CONSOLE] [WINDOW=name]
  52
  53 Runtime: [OFF] [SAVE] [SAVEAS=name] [EMPTY]
  54
  55
  56 Startup options
  57 ===============
  58 RECOVER=name    Sashimi will search the Amiga memory for the buffer created
  59                 and maintained by a previous invocation of Sashimi. This is
  60                 useful if the system crashed before you had any chance to
  61                 save the Sashimi buffer to disk. While the search is in
  62                 progress the system will be frozen. There is no guarantee
  63                 that Sashimi will find any older buffer or that the contents
  64                 of the buffer found will still be intact. Once the data is
  65                 found, it will be saved to the file with the given name.
  66
  67                 Sashimi will exit immediately after processing the recovery
  68                 command. No further action will be taken. Depending on whether
  69                 it was successful in recovering the data, Sashimi's return
  70                 code will be either 0 (= success) or 5 (= failure).
  71
  72 ON              Default (not required)
  73
  74 BUFK=n          Changes the circular buffer size from default 32K to specified
  75                 power-of-2 K from 4K to whatever you like, i.e. BUFK=8 will
  76                 allocate a buffer of 8192 bytes.
  77
  78 BUFFERSIZE=n    Changes the circular buffer size from default 32K to specified
  79                 buffer size, i.e. BUFFERSIZE=8000 will allocate a buffer
  80                 of 8000 bytes.
  81
  82 NOPROMPT        Turns off the "Sashimi installed" prompt. This is useful if
  83                 the Sashimi output is redirected to an AUTO CON window such
  84                 as in conjunction with the CONSOLE option.
  85
  86 QUIET           Causes Sashimi to just buffer all debugging output.
  87                 This effectively silences serial debugging output.
  88
  89 ASKSAVE         Cause Sashimi to ask you if you want to save the buffer
  90                 when you exit Sashimi.  If there's nothing in the buffer,
  91                 it won't ask.
  92
  93 ASKEXIT         Cause Sashimi to ask you if you *really* want to exit if
  94                 a [Ctrl]+C signal is received.  This is good for people like
  95                 me who might accidentally [Ctrl]+C in a Sashimi window when
  96                 they meant to do it somewhere else. This option should
  97                 only be used if Sashimi has an input stream - i.e. if Sashimi
  98                 is not run/redirected, or if Sashimi has in/out redirection
  99                 in a CONSOLE window.
 100
 101 TIMERON         Cause Sashimi to wake up every 1/10 second to check for
 102                 output. Without this option, Sashimi will just wake up every
 103                 time a carriage return or linefeed is output.
 104
 105 CONSOLE         This will make Sashimi open a console output window for itself
 106                 which all input and output will go into. Unless you provide a
 107                 console window specifier (see WINDOW option), Sashimi will use:
 108
 109                 CON:0/20/640/100/Sashimi  [Ctrl]+E=Empty  [Ctrl]+F=File  [Ctrl]+D=Reset console/AUTO/CLOSE/WAIT/INACTIVE
 110
 111 WINDOW=name     This option works in conjunction with the CONSOLE option and
 112                 allows you to override the default console window specifier.
 113
 114
 115 Runtime options
 116 ===============
 117 OFF             Signals the active running copy of Sashimi to exit.
 118
 119 EMPTY           Finds the active running copy of Sashimi and empties its
 120                 buffer.
 121
 122 SAVE            Finds the active running copy of Sashimi and saves its buffer
 123                 as "T:sashimi.out".
 124
 125 SAVEAS=name     Finds the active running copy of Sashimi and saves its buffer
 126                 as the specified file name.
 127
 128
 129 Example startup usage
 130 =====================
 131
 132 Sashimi ASKSAVE (in its own shell window)
 133
 134 Run >NIL: Sashimi >"CON:0/20/640/120/Sashimi/AUTO/CLOSE/WAIT/INACTIVE" ON NOPROMPT
 135
 136 Run Sashimi >ram:hits (all output redirected to a file)
 137
 138
 139 Keyboard and Break signals
 140 ==========================
 141 [Ctrl]+C: To quit Sashimi, [Ctrl]+C it (if it has its own window), send it
 142           a [Ctrl]+C signal with the Break command, or run Sashimi a second
 143           time with the OFF keyword.
 144
 145 [Ctrl]+D: This sends a control sequence to the output console to reset it.
 146           Very handy in case garbage data has changed the character set
 147           or the text rendering colours.
 148
 149 [Ctrl]+E: Tells Sashimi to empty (clear) its buffer.
 150
 151 [Ctrl]+F: Tells Sashimi to save its own buffer to the file "T:sashimi.out"
 152
 153
 154 Other runtime usage
 155 ===================
 156 Sashimi OFF                     ; tell active running Sashimi to try to exit
 157 Sashimi SAVE                    ; save buffer of active Sashimi
 158 Sashimi SAVEAS ram:myhits EMPTY ; save buffer as ram:myhits and clear buffer
 159
 160 Usually, I just hit [Ctrl]+F in the Sashimi window, and it saves its buffer
 161 as "T:sashimi.out".
 162
 163
 164 Programmer interface
 165 ====================
 166 Sorry, no programmer interface. "Sushi" had one, but I did not see much
 167 sense in replicating this functionality.
 168
 169
 170 Why "Sashimi"?
 171 ==============
 172 I got bitten by bugs in "Sushi", and not just once. Whenever the Sushi
 173 circular buffer would wrap around, there was a good chance part of the buffer
 174 would still be filled with random data when getting saved to disk. If a large
 175 amount of data would be sent through the kprintf() interface, Sushi would
 176 occasionally "hickup" and regurgitate stale data from its buffer. I took
 177 this as indications that the Sushi buffer management code was none too
 178 robust. Another thing that struck me as odd was the fact that sometimes
 179 Sushi would stop reporting incoming kprintf() output and effectively behave
 180 as if it had been stopped with [Ctrl]+C. Sushi also had a tendency to block
 181 screen output when printing its buffer; it would output the buffer in a
 182 single Write() operation, causing the console window to lock the display.
 183 And while that operation was in progress, you could not suspend window output
 184 or stop it.
 185
 186 Sashimi tries to do better in these situations. The algorithms for
 187 maintaining the circular buffer (or FIFO) are different. And just in case
 188 there is a bug in the code, I have provided the complete tool source code.
 189
 190
 191 Author
 192 ======
 193 Sashimi was written by Olaf `Olsen' Barthel, with "Sushi" by Carolyn
 194 Scheppner as a reference. Sushi was in turn influenced by the "Reporter"
 195 and "Detective" tools written by Steve Tibbett and Christian E. Hopps.
 196
 197 My postal address:
 198
 199    Olaf Barthel
 200    Brabeckstrasse 35
 201    D-30559 Hannover
 202    Federal Republic of Germany
 203
 204 My e-mail address:
 205
 206    olsen@sourcery.han.de
 207
 208
 209 History
 210 =======
 211
 212 Sashimi 1.6 (20.6.99)
 213
 214         - Sashimi could cause the entire system to hang due to an
 215           unmatched Disable() in the RawPutChar wedge [David Gerber].
 216
 217         - If Sashimi is not already running "Sashimi OFF" will no
 218           longer restart it.
 219
 220 Sashimi 1.5 (8.2.99)
 221
 222         - Made the FIFO access routines into atomic operations. This
 223           reduces the risk of two programs trying to modify the
 224           FIFO bookkeeping variables at the same time.
 225
 226         - Fixed a bug in the FIFO management code which would cause
 227           Sashimi to regurgitate stale data after a buffer overrun.
 228           Strangely, this was one of the bugs in Sushi I wanted to
 229           avoid...
 230
 231         - Added the new RECOVER functionality.
 232
 233 Sashimi 1.4 (11.9.98)
 234
 235         - The Sashimi RawPutChar() patch now saves and restores
 236           the contents of A0 and A1. This is necessary since
 237           the KPutStr() code relies upon A0 to remain unchanged
 238           after each call to RawPutChar() [Stuart Kyzer Caie].
 239
 240 Sashimi 1.3 (07.04.98)
 241
 242         - Updated the console window title text
 243
 244 Sashimi 1.2 (05.04.98)
 245
 246         - Added the [Ctrl]+D console reset command.