1 04/29/86 debug_fnp, db_fnp
2
3 Syntax as a command: db_fnp request
4
5
6 Function: is a debugging aid intended to be used by FNP software
7 developers and in FNP dump analysis. You can use it to patch or dump
8 memory in a running FNP, to examine a dump from a crashed FNP or a core
9 image segment before it is loaded, to set breakpoints in a running FNP,
10 and to display symbolically FNP control blocks, buffers, etc.
11
12
13 Arguments:
14 request
15 is the first requests to be executed. Once the initial requests
16 is completed, debug_fnp reads request lines from user_input. Each
17 line can contain multiple requests, separated by semicolons. If an
18 error occurs in any request, the remaining requests on that line are
19 not be executed. You can abort any request by typing "quit"
20 followed by a "pi" program_interrupt.
21
22
23 Notes on debug_fnp mode selection: This command can operate on a
24 running FNP, a dump segment, or a core image segment; with few
25 exceptions, most requests work the same regardless of the selection.
26 When first invoked, the command is set up to examine the first
27 configured FNP. You can switch between dumps, core images, and running
28 FNPs at any time.
29
30
31 List of mode selection requests:
32 fnp
33 Usage: fnp tag
34 selects a running FNP, where tag can be "a", "b", "c", "d", "e",
35 "f", "g", or "h".
36 image
37 Usage: image path
38 selects a core image, where path is the Multics pathname of a
39 segment containing the core image. Core image segments and dump
40 segments have a different format, so the image and dump requests are
41 not interchangeable. The pathname on this request can also be a
42 starname, provided it matches only one entry in the directory
43 specified.
44
45
46 dump
47 Usage: dump path
48 selects a dump, where path is the Multics pathname of a segment
49 containing the dump. Core image segments and dump segments have a
50 different format, so the image and dump requests are not
51 interchangeable. The pathname on this request can also be a
52 starname, provided it matches only one entry in the directory
53 specified.
54 In most cases, it is not necessary to know the pathname of the dump
55 to be examined, as special requests are provided for selecting
56 dumps.
57 dumps
58 Usage: dumps
59 lists all the dumps currently in the dump directory. The default
60 dump directory is >dumps.
61
62
63 dump_dir
64 Usage: dump_dir path
65 changes the default dump directory, where path is the pathname of
66 the new dump directory. If you omit "path," the name of the current
67 dump directory is printed.
68 last_dump
69 Usage: last_dump
70 selects the latest dump.
71 prev_dump
72 Usage: prev_dump
73 selects the next earliest dump. You can use this request to peruse
74 any or all the dumps in the dump directory, going in either
75 direction. You can use it repeatedly as long as there are more
76 dumps.
77
78
79 next_dump
80 Usage: next_dump
81 selects the next latest dump. You can use this request to peruse
82 any or all the dumps in the dump directory, going in either
83 direction.
84 select_fnp
85 Usage: select_fnp tag
86 selects which FNP in the dump is examined, when dealing with a dump
87 that contains multiple FNPs, such a BOS fdump; tag can be "a", "b",
88 "c", "d", "e", "f", "g", or "h".
89 what
90 Usage: what
91 prints the fnp tag or the pathname, to find out what FNP, dump, or
92 core image is selected.
93
94
95 Notes on expressions: Many of the following requests take numeric
96 arguments such as addresses, lengths, etc. Expressions can contain
97 "" "", "+", "-", "*", and "/" with their normal meanings and
98 precedence. The symbol "|" is synonymous with "+", as in
99 module|offset. You can specify indirection by ",*", following the
100 address to indirect through. Numeric constants are interpreted as
101 octal unless they are followed by a ".", in which case they are
102 decimal. You can use "*" for the current location counter, which is
103 generally the last address used in a display or patch request. You
104 can also use many common FNP symbols, including all fields in the
105 system comm region, the hardware comm region, the software comm
106 region, and the TIB. Before you can use TIB hwcm and sfcm
107 addresses establish the addresses of these control blocks. See the
108 line and set requests.
109
110
111 A symbol can also be any opblock mnemmonic, the name of any FNP object
112 module, or a machine instruction enclosed within apostrophes. In
113 addition, you can define user symbols. For example,
114 hsla|500
115 t.icp,*
116 *+30
117 tib|14,*+10
118 goto
119 'lda 0,2,b.0'
120 cax3 apostrophe not needed if there is no operand
121
122
123 List of fnp memory-display requests:
124 display, d
125 Usage: display address length mode
126 d address length mode
127 displays the contents of FNP words, where address is the starting
128 address, length is the number of words, and mode is the display
129 mode. The symbol "*" is set to the address specified. You can use
130 the following display modes:
131
132
133 octal, oct
134 character, ch
135 address, addr in form module|offset
136 clock, ck 4 FNP words as a Multics clock
137 instruction, inst 355 instruction format
138 opblock, op pseudo-opblock format
139 decimal, dec
140 bit
141 ebcdic, ebc
142 If you omit length, it defaults to 1 unless address is a predefined
143 FNP symbol, in which case the appropriate length for that symbol is
144 used. Similarly, if you omit mode, octal is used unless address is
145 a predefined FNP symbol, in which case the mode appropriate for that
146 symbol is used.
147
148
149 buffer, buf
150 Usage: buffer address mode -brief -bf
151 buf address mode -brief -bf
152 displays a buffer, where address is the address of the buffer, mode
153 is the mode to display it in see the display request, and -brief
154 means display only the first two words of the buffer. If you omit
155 address, the next buffer pointer from the previous buffer displayed
156 is used. If you omit mode, character mode is assumed. If you omit
157 -brief, the entire buffer is displayed. The length is determined
158 automatically by reading the buffer header.
159 buffer_chain, bufc
160 Usage: buffer_chain address mode -brief -bf
161 bufc address mode -brief -bf
162 displays a buffer chain.
163
164
165 block, blk
166 Usage: block address -offset -o offset
167 -length -l length
168 blk address -offset -o offset -length -l length
169 displays a control block at the address specified. Use this request
170 if the data being displayed is in the form of threaded control
171 blocks. The default offset to the forward pointer in the block is
172 0. The default block length is eight words. If you specify no
173 address, the next block in the chain is displayed using the forward
174 pointer from the previous block.
175
176
177 block_chain, blkc
178 Usage: block_chain address -offset -o offset
179 -length -l length
180 blkc address -offset -o offset
181 -length -l length
182 displays the entire chain of control blocks until one with a zero
183 forward pointer is encountered. Use this request if the data being
184 displayed is in the form of threaded control blocks. The request
185 follows the threads in the buffer chain, displaying each buffer.
186 The default offset to the forward pointer in the block is 0. The
187 default block length is eight words. If you specify no address, the
188 next block in the chain is displayed using the forward pointer from
189 the previous block.
190
191
192 flags
193 Usage: flags address type
194 shows the setting of individual bits. Use this request if the data
195 being displayed is a word of flags. The argument address is the the
196 address of the word containing flags; type can be:
197 t.stat tib status word
198 t.flg first tib flag word
199 t.flg2 second tib flag word
200 t.flg3 third tib flag word
201 sf.flg hsla sfcm flags
202 istat interpreter status word
203 hs.1 first word of hsla hardware status
204 hs.2 second word of hsla hardware status
205
206
207 If you omit type, it is assumed to be the same as "address," which
208 then must be one of the items in the above list. The flags are
209 listed by name, as they appear in the macros.map355 source file.
210 You can use the explain request for help on unfamiliar names.
211 Occasionally, the value of a flag word is known from a trace for
212 example, without knowing an address of it. In this case, you can
213 use the following form:
214 flags =expression type
215 where expression is any valid expression and type is one of the
216 types shown above.
217
218
219 List of fnp memory-patching requests:
220 patch
221 Usage: patch address arg1...argn
222 patches the contents of FNP memory, where address is the starting
223 address to patch and argi represent patch data. Each argi can be an
224 expression representing the value to be stored in one FNP word or a
225 character string in quotes which can contain more that one word of
226 data. The total number of words patched cannot exceed 32. Before
227 the patch is applied, the effects of the patch are displayed old
228 and new contents of every word and you are asked to verify that the
229 patch is correct. The symbol "*" is set to the address specified.
230
231
232 Examples of patch requests are--
233 patch 43102 203456 -1 2
234 patch .crver "3.1x"
235 patch ctrl|1400 goto ctrl|1600
236 patch hsla|1541 'tze 13' cax3 'lda 0,2,b.1'
237 A shorthand form of this request is
238 =arg1...argn
239 which is equivalent to
240 patch * arg1...argn
241 set_flag
242 Usage: set_flag flag_symbol
243 sets the bit associated with the flag_symbol specified in the
244 appropriate word. Use this request to manipulate individual flag
245 bits in words of flags.
246
247
248 clear_flag
249 Usage: clear_flag flag_symbol
250 clears an individual bit. Use this request to manipulate individual
251 flag bits in words of flags. This request is not an indivisible
252 operation; this means if other flag bits in the word are dynamically
253 changing, this request may change their value if they happen to have
254 been changed between the time the word was read and when it was
255 rewritten.
256
257
258 List of dump analysis requests: The following requests are valid only
259 when using debug_fnp on a dump.
260 why
261 Usage: why
262 finds out the cause of a dump. It prints the type of fault that
263 caused the crash and, if the crash was caused by a "die" opcode in
264 the FNP, interprets the reason for the crash.
265 regs
266 Usage: regs
267 prints the contents of all machine registers at the time of the
268 fault.
269
270
271 call_trace
272 Usage: call_trace address -long -lg
273 starts at the address specified and perform a backward trace of all
274 subroutine calls. The subroutine must be as defined by the map355
275 "subr" macro. If you give -lg, the registers saved at each
276 subroutine level are also printed. You can also use this request on
277 a running FNP, but the information is probably changing too fast for
278 the request to be useful.
279
280
281 List of fnp trace table requests: A running FNP or a dump contains a
282 trace table of the most recent events occurring in the FNP.
283 print_trace
284 Usage: print_trace start count
285 displays the trace table, where start indicates the starting trace
286 message and count is the number of messages to display. If you
287 supply no arguments, the entire trace table is printed. If you give
288 no count, the trace table is displayed from the starting point
289 specified to the end. If the start number is positive, it is
290 counted from the oldest message; if negative, it is counted from the
291 most recent. For example,
292 print_trace 200.
293 skips the 199 oldest entries and print the rest.
294 print_trace -50.
295 prints the 50 most recent messages.
296
297
298 Note that the start and count, like all other numeric values, are
299 octal unless followed by a decimal point. Printing the trace table
300 of a running FNP is only meaningful if tracing has been suspended;
301 otherwise the table is changing too fast to be interpreted.
302 stop_trace
303 Usage: stop_trace
304 suspends tracing in a running FNP.
305 start_trace
306 Usage: start_trace
307 restarts tracing in a running FNP.
308
309 Tracing can also be stopped and started with some of the breakpoint
310 requests explained below.
311
312
313 Which modules in the FNP are traced is determined by the trace mask,
314 kept in FNP memory.
315 trace_mask
316 Usage: trace_mask modules
317 examines or updates the trace mask. If you give no modules,
318 trace_mask displays and interprets the current trace mask. If you
319 give modules, they represent modules to be added to, or deleted
320 from, the current mask. Specify the module as "name" or "+name" to
321 set the tracing bit for the module and as "-name" or "^name" to turn
322 off the corresponding bit. In addition, you can specify all and
323 none. For example,
324
325
326 trace_mask hsla ^dia -util
327 turns on tracing for hsla_man and turn off tracing for dia_man and
328 utilities.
329 Turning tracing on for a module for which tracing was not enabled
330 when the core image was bound has no efect.
331
332
333 Notes on fnp breakpoint facility: The control table interpreter in the
334 FNP allows breakpoints to be set in the interpreted control tables. A
335 breakpoint causes the line encountering it to stop execution in the
336 interpreter until you give a request to restart it.
337
338 You can use breakpoints only if the module breakpoint_man is included
339 in the core image.
340
341 Breakpoints are often a useful tool, but be careful in their use. The
342 following points are important:
343 1. Breakpoints can only be set in interpreted opblocks. They cannot be
344 set at machine instructions.
345
346
347 2. While at a break, the line is executing an opblock equivalent to
348 wait 0,0,0
349 followed by no status blocks. This means that timers can run out
350 unnoticed, status can be ignored, hangups can be missed, etc. For
351 this reason it may be difficult to restart a channel after a
352 breakpoint.
353 3. Breakpoints cannot be set at subroutine levels where waits would be
354 illegal.
355 4. Breakpoints cannot be set when a restart may execute a wait opblock.
356 5. Breakpoints cannot be set at a status opblock.
357 6. If a breakpoint is set at a wait opblock, it must be reset before
358 the line is restarted. In addition, a breakpoint cannot be set at a
359 wait if any channels are currently waiting at that block.
360
361
362 7. Control tables that use local internal variables as opposed to
363 variables in the TIB extension cannot depend on these variables
364 being preserved during the break unless other channels that may use
365 the same control tables are not running.
366 8. No notice is given when a channel encounters a breakpoint. The
367 list_break request lists all breakpoints and shows what channels are
368 stopped at each one.
369
370
371 List of fnp breakpoint facility request:
372 set_break, sb
373 Usage: set_break address -line- -stop_trace
374 sb address -line- -stop_trace
375 sets a breakpoint at the address specified. If you give a tty
376 channel, the breakpoint applies to that line only, and any other
377 channel encountering the breakpoint continues execution; otherwise,
378 the breakpoint applies to any channel that encounters it. If you
379 supply -stop_trace, the FNP automatically suspends tracing if any
380 channel stops at that breakpoint.
381
382
383 reset_break, rb
384 Usage: reset_break address, rb address
385 reset_break -all, rb -all
386 resets a break at the address specified. Any lines stopped at the
387 break are not automatically restarted. If you give -all, all breaks
388 are reset.
389
390
391 start, sr
392 Usage: start line address -reset -start_trace
393 sr line address -reset -start_trace
394 start -all, sr -all
395 restarts the line specified. If you supply an address, the line
396 restarts at the address given, instead of where it was stopped. If
397 you supply -reset, the break is reset before the line is started.
398 If you supply -start_trace, tracing resumes as the line is
399 restarted. If you supply -all, all lines at breakpoints at the time
400 you issue the request are restarted.
401 list_break, lb
402 Usage: list_break
403 lb
404 lists all FNP breakpoints and the channels stopped at each.
405
406
407 List of performance analysis requests: The FNP software periodically
408 samples the instruction counter to determine whether the FNP is
409 running or idling.
410 idle_time
411 Usage: idle_time -reset -rs
412 prints the percentage of time the FNP has been idling since bootload
413 or the last time you invoked the request with -rs.
414 sample_time
415 Usage: sample_time new_time
416 prints or sets the sampling interval used by the FNP for metering
417 data, where new_time is the new sampling interval in milliseconds
418 between 1 and 1000. If you supply no argument, the current
419 sampling interval is printed. Default when the FNP is booted: 50
420 milliseconds
421
422
423 You can collect more detailed information on FNP usage by
424 configuring the module "ic_sampler" in the FNP core image. This
425 module periodically samples the instruction counter at the rate set
426 by sample_time and adds 1 to a bucket, which represents a small
427 range typically 16 of FNP addresses. With this data you can
428 determine with some precision where the FNP is spending its time
429 when it is running.
430 ic_sample
431 This request is only accepted if the ic_sampler module is configured
432 in the FNP. It has the following options:
433 Usage: ic_sample start
434 starts the ic sampling feature. Sampling is normally disabled when
435 the FNP is booted.
436 Usage: ic_sample stop
437 stops ic_sampling.
438
439
440 Usage: ic_sample reset
441 zeroes all the sampling buckets.
442 Usage: ic_sample module
443 prints a table showing each module in the core image and what
444 percentage of samples collected occur in that module.
445 Usage: ic_sample histogram, hist fraction
446 prints a histogram showing each bucket address that has data and the
447 percentage of nonidle time that bucket represents. The fraction
448 must be a floating point number between 0.0 and 1.0. With this
449 option, the histogram only contains the most frequently used
450 buckets. Enough buckets are printed so that the fraction specified
451 of the total data collected is printed. For example, if the
452 fraction is .9, 10% of the data collected is not displayed by
453 discarding infrequently referenced buckets. This option is useful
454 in deleting "noise" from the histogram.
455
456
457 List of miscellaneous requests:
458 line
459 Usage: line line
460 locates the TIB, software comm region, and hardware comm region of
461 the line specified. Once these addresses are set, you can reference
462 fields in these control blocks by name in any expression in other
463 requests. You can specify the line either in Multics form a.h012
464 or as an FNP line number 1014. If you give no line, the name of
465 the current line is printed. If the line selected is not on the
466 current FNP, the proper FNP is selected automatically. You can
467 specify the line as -login_channel, in which case your login channel
468 is selected.
469
470
471 buffer_status, bstat
472 Usage: buffer_status -brief -bf
473 bstat -brief -bf
474 prints a table showing each line and how much buffer space in the
475 FNP it is using. If you use -bf, only summary information is
476 printed.
477
478
479 set
480 Usage: set symbol value
481 sets a symbol, where symbol is "*", "tib", "hwcm", "sfcm", or any
482 user-defined symbol. Setting control block addresses tib hwcm
483 sfcm is more easily done with the line request, but can be manually
484 done with this request in case internal FNP tables have been
485 damaged. Note that setting any of these control block addresses has
486 no effect on the current value of other control blocks. Setting "*"
487 is also done by any dump or patch request. Once set, a symbol can
488 be used in any expression in any other request.
489 map
490 Usage: map
491 displays a list of modules, their addresses in the core image, and
492 their dates of compilation.
493
494
495 convert_address, cva
496 Usage: convert_address address1...addressn
497 cva address1...addressn
498 displays the address in any other meaningful forms that can be
499 derived. For example, octal values are converted to module|offset,
500 and vice versa.
501 explain
502 Usage: explain sym1 sym2...symn
503 finds the explanation of any FNP symbol usally the output of a
504 flags or convert_address request, where symi are symbols to be
505 explained. It prints the comment from the line in macros.map355
506 that defined the symbol.
507
508
509 e
510 Usage: e command_line
511 executes any Multics command by passing "command_line" to the
512 command processor.
513 quit, q
514 Usage: q
515 exits from debug_fnp.