04/29/86 debug_fnp, db_fnp Syntax as a command: db_fnp {request} Function: is a debugging aid intended to be used by FNP software developers and in FNP dump analysis. You can use it to patch or dump memory in a running FNP, to examine a dump from a crashed FNP or a core image segment before it is loaded, to set breakpoints in a running FNP, and to display symbolically FNP control blocks, buffers, etc. Arguments: request is the first request(s) to be executed. Once the initial request(s) is completed, debug_fnp reads request lines from user_input. Each line can contain multiple requests, separated by semicolons. If an error occurs in any request, the remaining requests on that line are not be executed. You can abort any request by typing "quit" followed by a "pi" (program_interrupt). Notes on debug_fnp mode selection: This command can operate on a running FNP, a dump segment, or a core image segment; with few exceptions, most requests work the same regardless of the selection. When first invoked, the command is set up to examine the first configured FNP. You can switch between dumps, core images, and running FNPs at any time. List of mode selection requests: fnp Usage: fnp tag selects a running FNP, where tag can be "a", "b", "c", "d", "e", "f", "g", or "h". image Usage: image path selects a core image, where path is the Multics pathname of a segment containing the core image. Core image segments and dump segments have a different format, so the image and dump requests are not interchangeable. The pathname on this request can also be a starname, provided it matches only one entry in the directory specified. dump Usage: dump path selects a dump, where path is the Multics pathname of a segment containing the dump. Core image segments and dump segments have a different format, so the image and dump requests are not interchangeable. The pathname on this request can also be a starname, provided it matches only one entry in the directory specified. In most cases, it is not necessary to know the pathname of the dump to be examined, as special requests are provided for selecting dumps. dumps Usage: dumps lists all the dumps currently in the dump directory. The default dump directory is >dumps. dump_dir Usage: dump_dir {path} changes the default dump directory, where path is the pathname of the new dump directory. If you omit "path," the name of the current dump directory is printed. last_dump Usage: last_dump selects the latest dump. prev_dump Usage: prev_dump selects the next earliest dump. You can use this request to peruse any or all the dumps in the dump directory, going in either direction. You can use it repeatedly as long as there are more dumps. next_dump Usage: next_dump selects the next latest dump. You can use this request to peruse any or all the dumps in the dump directory, going in either direction. select_fnp Usage: select_fnp tag selects which FNP in the dump is examined, when dealing with a dump that contains multiple FNPs, such a BOS fdump; tag can be "a", "b", "c", "d", "e", "f", "g", or "h". what Usage: what prints the fnp tag or the pathname, to find out what FNP, dump, or core image is selected. Notes on expressions: Many of the following requests take numeric arguments such as addresses, lengths, etc. Expressions can contain "(", ")", "+", "-", "*", and "/" with their normal meanings and precedence. The symbol "|" is synonymous with "+", as in module|offset. You can specify indirection by ",*", following the address to indirect through. Numeric constants are interpreted as octal unless they are followed by a ".", in which case they are decimal. You can use "*" for the current location counter, which is generally the last address used in a display or patch request. You can also use many common FNP symbols, including all fields in the system comm region, the hardware comm region, the software comm region, and the TIB. (Before you can use TIB, hwcm, and sfcm addresses, establish the addresses of these control blocks. See the line and set requests.) A symbol can also be any opblock mnemmonic, the name of any FNP object module, or a machine instruction (enclosed within apostrophes). In addition, you can define user symbols. For example, hsla|500 t.icp,* *+30 tib|14,*+10 goto 'lda 0,2,b.0' cax3 (apostrophe not needed if there is no operand) List of fnp memory-display requests: display, d Usage: display address {length} {mode} d address {length} {mode} displays the contents of FNP words, where address is the starting address, length is the number of words, and mode is the display mode. The symbol "*" is set to the address specified. You can use the following display modes: octal, oct character, ch address, addr (in form module|offset) clock, ck (4 FNP words as a Multics clock) instruction, inst (355 instruction format) opblock, op (pseudo-opblock format) decimal, dec bit ebcdic, ebc If you omit length, it defaults to 1 unless address is a predefined FNP symbol, in which case the appropriate length for that symbol is used. Similarly, if you omit mode, octal is used unless address is a predefined FNP symbol, in which case the mode appropriate for that symbol is used. buffer, buf Usage: buffer {address} {mode} {-brief, -bf} buf {address} {mode} {-brief, -bf} displays a buffer, where address is the address of the buffer, mode is the mode to display it in (see the display request), and -brief means display only the first two words of the buffer. If you omit address, the next buffer pointer from the previous buffer displayed is used. If you omit mode, character mode is assumed. If you omit -brief, the entire buffer is displayed. The length is determined automatically by reading the buffer header. buffer_chain, bufc Usage: buffer_chain {address} {mode} {-brief, -bf} bufc {address} {mode} {-brief, -bf} displays a buffer chain. block, blk Usage: block {address} {-offset, -o offset} {-length, -l length} blk {address} {-offset, -o offset} {-length, -l length} displays a control block at the address specified. Use this request if the data being displayed is in the form of threaded control blocks. The default offset to the forward pointer in the block is 0. The default block length is eight words. If you specify no address, the next block in the chain is displayed (using the forward pointer from the previous block). block_chain, blkc Usage: block_chain {address} {-offset, -o offset} {-length, -l length} blkc {address} {-offset, -o offset} {-length, -l length} displays the entire chain of control blocks until one with a zero forward pointer is encountered. Use this request if the data being displayed is in the form of threaded control blocks. The request follows the threads in the buffer chain, displaying each buffer. The default offset to the forward pointer in the block is 0. The default block length is eight words. If you specify no address, the next block in the chain is displayed (using the forward pointer from the previous block). flags Usage: flags address {type} shows the setting of individual bits. Use this request if the data being displayed is a word of flags. The argument address is the the address of the word containing flags; type can be: t.stat tib status word t.flg first tib flag word t.flg2 second tib flag word t.flg3 third tib flag word sf.flg hsla sfcm flags istat interpreter status word hs.1 first word of hsla hardware status hs.2 second word of hsla hardware status If you omit type, it is assumed to be the same as "address," which then must be one of the items in the above list. The flags are listed by name, as they appear in the macros.map355 source file. You can use the explain request for help on unfamiliar names. Occasionally, the value of a flag word is known (from a trace, for example), without knowing an address of it. In this case, you can use the following form: flags =expression type where expression is any valid expression and type is one of the types shown above. List of fnp memory-patching requests: patch Usage: patch address arg1...{argn} patches the contents of FNP memory, where address is the starting address to patch and argi represent patch data. Each argi can be an expression representing the value to be stored in one FNP word or a character string in quotes (which can contain more that one word of data). The total number of words patched cannot exceed 32. Before the patch is applied, the effects of the patch are displayed (old and new contents of every word) and you are asked to verify that the patch is correct. The symbol "*" is set to the address specified. Examples of patch requests are-- patch 43102 203456 -1 2 patch .crver "3.1x" patch ctrl|1400 goto ctrl|1600 patch hsla|1541 'tze 13' cax3 'lda 0,2,b.1' A shorthand form of this request is =arg1...{argn} which is equivalent to patch * arg1...{argn} set_flag Usage: set_flag flag_symbol sets the bit associated with the flag_symbol specified in the appropriate word. Use this request to manipulate individual flag bits in words of flags. clear_flag Usage: clear_flag flag_symbol clears an individual bit. Use this request to manipulate individual flag bits in words of flags. This request is not an indivisible operation; this means if other flag bits in the word are dynamically changing, this request may change their value if they happen to have been changed between the time the word was read and when it was rewritten. List of dump analysis requests: The following requests are valid only when using debug_fnp on a dump. why Usage: why finds out the cause of a dump. It prints the type of fault that caused the crash and, if the crash was caused by a "die" opcode in the FNP, interprets the reason for the crash. regs Usage: regs prints the contents of all machine registers at the time of the fault. call_trace Usage: call_trace address {-long, -lg} starts at the address specified and perform a backward trace of all subroutine calls. The subroutine must be as defined by the map355 "subr" macro. If you give -lg, the registers saved at each subroutine level are also printed. You can also use this request on a running FNP, but the information is probably changing too fast for the request to be useful. List of fnp trace table requests: A running FNP or a dump contains a trace table of the most recent events occurring in the FNP. print_trace Usage: print_trace {start} {count} displays the trace table, where start indicates the starting trace message and count is the number of messages to display. If you supply no arguments, the entire trace table is printed. If you give no count, the trace table is displayed from the starting point specified to the end. If the start number is positive, it is counted from the oldest message; if negative, it is counted from the most recent. For example, print_trace 200. skips the 199 oldest entries and print the rest. print_trace -50. prints the 50 most recent messages. Note that the start and count, like all other numeric values, are octal unless followed by a decimal point. Printing the trace table of a running FNP is only meaningful if tracing has been suspended; otherwise the table is changing too fast to be interpreted. stop_trace Usage: stop_trace suspends tracing in a running FNP. start_trace Usage: start_trace restarts tracing in a running FNP. Tracing can also be stopped and started with some of the breakpoint requests explained below. Which modules in the FNP are traced is determined by the trace mask, kept in FNP memory. trace_mask Usage: trace_mask {modules} examines or updates the trace mask. If you give no modules, trace_mask displays and interprets the current trace mask. If you give modules, they represent modules to be added to, or deleted from, the current mask. Specify the module as "name" or "+name" to set the tracing bit for the module and as "-name" or "^name" to turn off the corresponding bit. In addition, you can specify all and none. For example, trace_mask hsla ^dia -util turns on tracing for hsla_man and turn off tracing for dia_man and utilities. Turning tracing on for a module for which tracing was not enabled when the core image was bound has no efect. Notes on fnp breakpoint facility: The control table interpreter in the FNP allows breakpoints to be set in the interpreted control tables. A breakpoint causes the line encountering it to stop execution in the interpreter until you give a request to restart it. You can use breakpoints only if the module breakpoint_man is included in the core image. Breakpoints are often a useful tool, but be careful in their use. The following points are important: 1. Breakpoints can only be set in interpreted opblocks. They cannot be set at machine instructions. 2. While at a break, the line is executing an opblock equivalent to wait 0,0,0 followed by no status blocks. This means that timers can run out unnoticed, status can be ignored, hangups can be missed, etc. For this reason it may be difficult to restart a channel after a breakpoint. 3. Breakpoints cannot be set at subroutine levels where waits would be illegal. 4. Breakpoints cannot be set when a restart may execute a wait opblock. 5. Breakpoints cannot be set at a status opblock. 6. If a breakpoint is set at a wait opblock, it must be reset before the line is restarted. In addition, a breakpoint cannot be set at a wait if any channels are currently waiting at that block. 7. Control tables that use local internal variables (as opposed to variables in the TIB extension) cannot depend on these variables being preserved during the break unless other channels that may use the same control tables are not running. 8. No notice is given when a channel encounters a breakpoint. The list_break request lists all breakpoints and shows what channels are stopped at each one. List of fnp breakpoint facility request: set_break, sb Usage: set_break address -line- {-stop_trace} sb address -line- {-stop_trace} sets a breakpoint at the address specified. If you give a tty channel, the breakpoint applies to that line only, and any other channel encountering the breakpoint continues execution; otherwise, the breakpoint applies to any channel that encounters it. If you supply -stop_trace, the FNP automatically suspends tracing if any channel stops at that breakpoint. reset_break, rb Usage: reset_break address, rb address reset_break -all, rb -all resets a break at the address specified. Any lines stopped at the break are not automatically restarted. If you give -all, all breaks are reset. start, sr Usage: start line {address} {-reset} {-start_trace} sr line {address} {-reset} {-start_trace} start -all, sr -all restarts the line specified. If you supply an address, the line restarts at the address given, instead of where it was stopped. If you supply -reset, the break is reset before the line is started. If you supply -start_trace, tracing resumes as the line is restarted. If you supply -all, all lines at breakpoints at the time you issue the request are restarted. list_break, lb Usage: list_break lb lists all FNP breakpoints and the channels stopped at each. List of performance analysis requests: The FNP software periodically samples the instruction counter to determine whether the FNP is running or idling. idle_time Usage: idle_time {-reset, -rs} prints the percentage of time the FNP has been idling since bootload or the last time you invoked the request with -rs. sample_time Usage: sample_time {new_time} prints or sets the sampling interval used by the FNP for metering data, where new_time is the new sampling interval in milliseconds (between 1 and 1000). If you supply no argument, the current sampling interval is printed. (Default when the FNP is booted: 50 milliseconds) You can collect more detailed information on FNP usage by configuring the module "ic_sampler" in the FNP core image. This module periodically samples the instruction counter (at the rate set by sample_time) and adds 1 to a bucket, which represents a small range (typically 16) of FNP addresses. With this data you can determine with some precision where the FNP is spending its time when it is running. ic_sample This request is only accepted if the ic_sampler module is configured in the FNP. It has the following options: Usage: ic_sample start starts the ic sampling feature. Sampling is normally disabled when the FNP is booted. Usage: ic_sample stop stops ic_sampling. Usage: ic_sample reset zeroes all the sampling buckets. Usage: ic_sample module prints a table showing each module in the core image and what percentage of samples collected occur in that module. Usage: ic_sample histogram, hist {fraction} prints a histogram showing each bucket address that has data and the percentage of nonidle time that bucket represents. The fraction must be a floating point number between 0.0 and 1.0. With this option, the histogram only contains the most frequently used buckets. Enough buckets are printed so that the fraction specified of the total data collected is printed. For example, if the fraction is .9, 10% of the data collected is not displayed by discarding infrequently referenced buckets. This option is useful in deleting "noise" from the histogram. List of miscellaneous requests: line Usage: line {line} locates the TIB, software comm region, and hardware comm region of the line specified. Once these addresses are set, you can reference fields in these control blocks by name in any expression in other requests. You can specify the line either in Multics form (a.h012) or as an FNP line number (1014). If you give no line, the name of the current line is printed. If the line selected is not on the current FNP, the proper FNP is selected automatically. You can specify the line as -login_channel, in which case your login channel is selected. buffer_status, bstat Usage: buffer_status {-brief, -bf} bstat {-brief, -bf} prints a table showing each line and how much buffer space in the FNP it is using. If you use -bf, only summary information is printed. set Usage: set symbol value sets a symbol, where symbol is "*", "tib", "hwcm", "sfcm", or any user-defined symbol. Setting control block addresses (tib, hwcm, sfcm) is more easily done with the line request, but can be manually done with this request in case internal FNP tables have been damaged. Note that setting any of these control block addresses has no effect on the current value of other control blocks. Setting "*" is also done by any dump or patch request. Once set, a symbol can be used in any expression in any other request. map Usage: map displays a list of modules, their addresses in the core image, and their dates of compilation. convert_address, cva Usage: convert_address {address1}...{addressn} cva {address1}...{addressn} displays the address in any other meaningful forms that can be derived. For example, octal values are converted to module|offset, and vice versa. explain Usage: explain sym1 {sym2}...{symn} finds the explanation of any FNP symbol (usally the output of a flags or convert_address request), where symi are symbols to be explained. It prints the comment from the line in macros.map355 that defined the symbol. e Usage: e command_line executes any Multics command by passing "command_line" to the command processor. quit, q Usage: q exits from debug_fnp. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved