.; .; Please use BONNER LAB RUNOFF on this document. .; .PAGE SIZE 58,70,10 .AUTOBREAK "-" .NO AUTOHYPHENATE .AUTOPARAGRAPH .NO AUTOTITLE .NO FLAGS .STYLE HEADERS 6 .TAB STOPS +8,+8,+8,+8,+8,+8,+8 .TITLE DBG Assembly Level Debugger V1.8 .CHAPTER Introduction .SUBTITLE Introduction DBG is a symbolic debugging tool for user mode programs running under RSX-11M-PLUS (it won't work under M until sending the task region by reference is allowed). It was written because DEC failed to include air sickness bags with ODT. DBG has the following general features: .LIST "o" .LIST ELEMENT Symbolic instruction display. .LIST ELEMENT Memory and register display and modification. .LIST ELEMENT Program control via breakpoints, tracepoints, watchpoints and single stepping. .LIST ELEMENT Instruction profiling and history. .LIST ELEMENT Ability to debug I/D space tasks. .LIST ELEMENT Ability to accept commands from a command file, and write commands and output to a log file. .END LIST There are many desirable features which DBG does not provide, including: .LIST .LIST ELEMENT DBG is NOT a source language debugger. .LIST ELEMENT DBG does NOT know the types of data objects. .LIST ELEMENT DBG can NOT differentiate between I space and D space symbols in an I/D space task. .LIST ELEMENT DBG does NOT provide support for debugging overlaid programs. .LIST ELEMENT DBG can NOT debug supervisor mode libraries. .LIST ELEMENT DBG does NOT provide support for dealing with floating point instructions and registers. .LIST ELEMENT DBG does NOT provide a screen-oriented user interface. .LIST ELEMENT DBG does NOT come with a known bug list. I'm sure there are bugs here, but I don't know where they are. .LIST ELEMENT DBG does NOT come with any guarantees, express or implied. I have had good luck in using it, but I refuse any responsibility for the results of any use, misuse, or abuse of this program. .END LIST .HEADER LEVEL 1 What DBG does To debug a program using DBG, the programmer includes an extra module in the task image (DBGAID), and causes the task builder to create a symbol table file. The programmer invokes the task in the normal manner, and then initiates DBG. DBG prompts the programmer for commands and allows the programmer to examine and modify memory and the CPU registers, and to control and profile task execution. Breakpoints may be set in the task. Task execution will stop when a breakpoint is reached; the instruction at that location will not yet have been executed. Tracepoints are a lot like breakpoints, but they do not halt task execution. You will simply be notified each time the task reaches the point in question. Breakpoints and tracepoints are implemented by storing BPT instructions at the specified points, so they can not be used on read only code (e.g. FCSRES). Watchpoints are used to detect erroneous data modifications. The target task will be single stepped, and the watched location(s) will be examined after every instruction. The task will be halted whenever the data changes. Only data word watchpoints are provided (byte data is not supported). Because of the implementation technique execution with watchpoints is very slow. When profiling is enabled a group of counters is created. Each counter represents the execution of one or more instructions. The task is single stepped, and every time an instruction that is represented by a counter is executed that counter is incremented; this allows the measurement of the instruction execution frequency within a task. The data acquired by profiling can be used to aid in the optimization of program performance. A program (PROFANAL.C) is provided to convert the instruction counter data to instructions executed per module (areas separated by global symbols). When instruction history is enabled the task will be single stepped, and the registers will be stored in the history buffer prior to the execution of each instruction. The history buffer may be displayed as a list of instructions, registers, or both. .CHAPTER Expressions .SUBTITLE Expressions DBG allows all addresses and numeric values to be expressions. A valid expression may contain constants, symbols, and operators. .HEADER LEVEL 1 Constants Constants may be numeric values, ASCII characters, or RAD50 characters. .HEADER LEVEL 2 Numeric Constants Numeric constants may be in one of four radices: binary, octal, decimal, and hexadecimal. By default, numeric constants are always processed in the current default radix (initially octal, and controlled by the SET MODE command). In addition, the default radix may be overridden through the use of the temporary radix operators (^B, ^D, ^O, ^X), or by following a decimal value with a period. The first digit of a hexadecimal constant must always be a valid (decimal) digit, even if a temporary radix operator is used. The following examples assume the default radix is octal (default). .LITERAL EXAMPLES: 100 = 100 octal (64 decimal) 100. = 144 octal (100 decimal) ^B100 = 4 octal (4 decimal) ^X0D = 15 octal (13 decimal) ^XAF0 = Invalid (does not begin with 0-9) .END LITERAL .HEADER LEVEL 2 ASCII Constants ASCII constants may be either one or two characters long. Single ASCII characters must be preceded by a single quote. Two characters following a double quote will be packed into a 16-bit word; the first character will be placed in the low byte. .LITERAL EXAMPLES: 'A = 101 octal (65 decimal) "AA = 40501 octal (16705 decimal) "AB = 41101 octal (16961 decimal) .END LITERAL .HEADER LEVEL 2 RAD50 Constants RAD50 constants may be up to three characters long. The characters to be converted to RAD50 must be preceded by a percent sign, or the RAD50 operator (^R). If fewer than three characters are provided, the rightmost positions in the word will be filled with RAD50 spaces (zeroes). .LITERAL EXAMPLES: %ABC = 3223 octal (1683 decimal) ^RDEF = 14716 octal (6606 decimal) %A = 3100 octal (1600 decimal) .END LITERAL .HEADER LEVEL 1 Symbols Symbols are groups of characters which represent numeric values to DBG; they may be created by the DEFINE and LOAD commands. Symbols may be composed of the alphanumeric characters (A-Z and 0-9), the dollar sign ($) and period (.). A symbol which begins with a digit will not be usable in expressions. Only the first six characters in a symbol are significant. It is useful to note that all C implementations (that I know of) for RSX convert an underscore (_) to a period (.) for task building purposes. .LITERAL EXAMPLES: ABC OK $123 OK FILENAME OK (but will be truncated to FILENA) E_ZT Invalid (contains an underscore) 1QZ Not recommended (starts with digit) .END LITERAL In addition, the following PDP-11 registers (and the directive status word) may be referred to by name: R0, R1, R2, R3, R4, R5, SP, PC, PS, $DSW. These special symbols refer to locations in the DBGAID module that contain the register values. .HEADER LEVEL 1 Operators DBG has several classes of operators: character, radix, monadic, and dyadic. In addition, angle brackets (<>) may be used to enclose subexpressions, and control the order of evaluation. .HEADER LEVEL 2 Character Operators Character operators are used to convert characters to numeric values. The single quote (') and double quote (") characters specify ASCII conversion, and the percent sign (%) and RAD50 operator (^R) specify RAD50 conversion. For examples of these operators see the sections on ASCII and RAD50 constants. .HEADER LEVEL 2 Radix Operators Radix operators are used to temporarily control the conversion of digit strings to numeric values. These operators cause the radix to be temporarily set to binary (^B), octal (^O), decimal (^D) or hexadecimal (^X). These operators are handled by the expression parser as monadic operators; they normally apply only to the next digit string. If one of these operators is used on a subexpression (i.e. one that is enclosed in angle brackets), then it becomes the default radix for the subexpression. For examples of the use of these operators, see the section on numeric constants. .HEADER LEVEL 2 Monadic Operators Monadic operators take only a single argument. This argument may be a constant, symbol, or subexpression enclosed in angle brackets. Monadic operators are processed left to right before dyadic operators. The monadic operators are the complementation operator (^C), the indirection operator (@), and the negation operator (-). The complementation operator inverts all of the bits in its argument (it takes the one's complement). The indirection operator fetches the data word specified by its argument taken as an address. The negation operator produces the two's complement of its argument. .LITERAL EXAMPLES: ^C<1> = 177776 octal (65534 decimal) @R0 = contents of the word whose address is in register R0. -1 = 177777 octal (65536 decimal) .END LITERAL .HEADER LEVEL 2 Dyadic Operators Dyadic operators take two arguments, which may be constants, symbols, subexpressions, etc. These operators are evaluated from left to right. The dyadic operators are add (+), subtract (-), multiply (*), divide (/), and (&), and or (!). .LITERAL EXAMPLES: 1+2 = 4 4-3 = 1 5*6 = 36 octal (30 decimal) 9./2 = 4 (note period after 9) 5&6 = 4 101!16 = 117 octal (79 decimal) .END LITERAL .CHAPTER Commands .SUBTITLE Commands DBG has a number of commands, some of which are actually useful. All command keywords and switches may be shortened as much as you like, but the result must not be ambiguous (e.g. "EX" could represent "EXAMINE" or "EXIT"). You may exit DBG by typing control-Z, EXIT, or QUIT. Any command line beginning with a semicolon will be treated as a comment. .HEADER LEVEL 1 CANCEL The CANCEL command is used to eliminate breakpoints, tracepoints, watchpoints, and profile ranges. A keyword specifying the type of object to be eliminated must be included following the command. If more than one object of a type is to be eliminated then their addresses should be separated by commas with no intervening blanks. .LITERAL SYNTAX: CANCEL[/switches] keyword [address expression(s)] SWITCHES: /ALL Specifies that all objects of the specified type are to be eliminated. KEYWORDS: BREAK Eliminate the specified breakpoint. PROFILE Eliminate all profile ranges. TRACE Eliminate the specified tracepoint. WATCH Eliminate the specified watchpoint. EXAMPLES: CANCEL BREAK T$RECV Eliminate the breakpoint at location T$RECV CANCEL/ALL TRACE Eliminate all tracepoints CANCEL PROFILE Eliminate all profile ranges .END LITERAL .HEADER LEVEL 1 DEFINE The DEFINE command is used to define a symbol with a specified value. Both the symbol name and value must be specified. .LITERAL SYNTAX: DEFINE symbol=value EXAMPLES: DEFINE BIT9=512. Define symbol BIT9 and give it the value 1000 octal. DEFINE NEXT=@PC Define symbol NEXT and give it the value in the PC. .END LITERAL .HEADER LEVEL 1 DEPOSIT The DEPOSIT command is used to modify the target task memory and/or registers. This command always defaults to depositing data words; it is not affected by the mode settings. To deposit multiple data bytes or words in sequential memory locations, separate them with commas. To deposit multiple instructions they must be separated by semicolons. In I/D space tasks only instructions are deposited into I space. .LITERAL SYNTAX: DEPOSIT[/switch] address=value[,value...] SWITCHES: /BYTE Deposit data bytes /INSTRUCTION Deposit instructions /WORD Deposit data words (default) EXAMPLES: DEPOSIT SYMLOW=64. Deposits 100 octal in word SYMLOW DEP/BY TXT='H,'I Deposits 'H and 'I in the two bytes at location TXT DEP/I @PC=MOV (R0)+,-(SP);SOB R1,@PC Deposits a loop at @PC .END LITERAL .HEADER LEVEL 1 EVALUATE The EVALUATE command is used to evaluate an expression and display its value in signed decimal, unsigned decimal, binary, octal, hexadecimal, RAD50, and ASCII. .LITERAL SYNTAX: EVALUATE expression EXAMPLE: EVAL 2*<3+6> .END LITERAL .HEADER LEVEL 1 EXAMINE The EXAMINE command is used to display target task memory or registers. This command always remembers the last address range displayed, and will redisplay it by default if no address range is specified. The data type and mode switches are set for the current command only; the defaults are set by the SET MODE and SET TYPE commands. An address range consists of two address expressions separated by a colon; the lower address should be specified first. In I/D space tasks I space can only be displayed as instructions; all other data types refer to D space. .LITERAL SYNTAX: EXAMINE[/switches] range[,range...] SWITCHES: /ADDRESS Displays symbolic addresses /ASCII Displays ASCII text /BINARY Display in binary /BYTE Displays byte data /DECIMAL Display in decimal /HEXADECIMAL Display in hexadecimal /INSTRUCTION Displays instructions /LEADING Display leading zeroes /NOLEADING Don't display leading zeroes /NOSYMBOLIC Don't display symbols /OCTAL Display in octal /RAD50 Displays RAD50 characters /SIGNED Display numbers as signed /SYMBOLIC Display symbols /UNSIGNED Display numbers as unsigned /WORD Displays words EXAMPLES: EXAM/WORD R0:PS Displays all registers EXAM @PC '' next instruction EXAM @PC:@PC+20 '' next few instructions EXAM/ADDR @SP:@SP+100 '' stack symbolically .END LITERAL .HEADER LEVEL 1 EXIT The EXIT command terminates the debugging session. There are no parameters. If a log file is open it will be closed before the command takes effect. .HEADER LEVEL 1 GO The GO command initiates or resumes target task execution. If an address expression is specified then the PC will be set to the specified address before execution begins. .LITERAL SYNTAX: GO [address] EXAMPLES: GO START Resume execution at location START GO Proceed with execution from @PC .END LITERAL .HEADER LEVEL 1 HELP The HELP command displays brief help on a variety of topics. Type HELP without a topic to get a list of topics. HELP does not support subtopics. .HEADER LEVEL 1 LOAD The LOAD command is used to add the symbols in a symbol table file produced by TKB into the symbol table. The file name must be specified. If the device, directory, and file type are not specified then they will default to the current device (SY:), directory, and type .STB. .LITERAL SYNTAX: LOAD filespec EXAMPLES: LOAD LB:[3,54]DBG Load LB0:[3,54]DBG.STB LOAD PROGRAM Load PROGRAM.STB .END LITERAL .HEADER LEVEL 1 QUIT This command is a synonym for the EXIT command. .HEADER LEVEL 1 SET The set command is used to control many DBG parameters affecting program execution and DBG output. The SET command must be followed by one or more keywords indicating the parameters that are to be controlled. .HEADER LEVEL 2 SET BREAK SET BREAK is used to set one or more breakpoints. The addresses of the instructions which are to be breakpointed must be specified. If multiple breakpoints are set then their addresses should be separated by commas. .LITERAL EXAMPLES: SET BREAK T$RECV Breakpoint location T$RECV SET BREAK MAIN+20 Breakpoint location MAIN+20 .END LITERAL .HEADER LEVEL 2 SET HISTORY SET HISTORY is used to control instruction and register traceback. The number of instructions of traceback must be specified. The absolute maximum is 1820 instructions, but prior memory commitments may reduce this. Whenever HISTORY is in effect all instructions will be single-stepped. .LITERAL EXAMPLES: SET HISTORY 1820. Set history to maximum. SET HISTORY 0 Turn off history. .END LITERAL .HEADER LEVEL 2 SET LOG SET LOG is used to set the name of the log file. The name of the log file must be specified. The default filespec, parts of which will be used if the filespec is not complete, is SY:DEBUG.LOG. .LITERAL EXAMPLE: SET LOG EXAMPLE Sets the log file to EXAMPLE.LOG .END LITERAL .HEADER LEVEL 2 SET MODE The SET MODE command allows the user to control the formatting of numeric values and other output, and the simulation of stepped instructions. .HEADER LEVEL 3 SET MODE (NO)LEADING The command controls the display of leading zeroes on numeric values. The initial setting is NOLEADING. .LITERAL EXAMPLES: SET MODE LEADING Display leading zeroes SET MODE NOLEADING Don't display leading zeroes .END LITERAL .HEADER LEVEL 3 SET MODE radix This group of commands controls the default input radix, as well as the output radix. The radix may be set to BINARY, DECIMAL, HEXADECIMAL, or OCTAL. The initial setting is OCTAL. .LITERAL EXAMPLE: SET MODE DECIMAL Set radix to decimal .END LITERAL .HEADER LEVEL 3 SET MODE (NO)SIMULATE Single stepping is important to some of the things that DBG does, but stepping with the trace trap is horrendously slow. For this reason, DBG provides a module that simulates many common instructions at a faster rate than with the trace trap. This module does not operate unless a SET MODE SIMULATE command is issued, because it depends on the MFPS and MTPS instructions which are fully implemented only on some of the newer PDP-11 CPUs (e.g. KDF11 and KDJ11s). Please note that simulation could have strange effects on system behavior if the MCR DEBUG command is used, or if the target task is aborted during simulation. .LITERAL EXAMPLES: SET MODE SIMULATE Turns on simulation SET MODE NOSIMULATE Turns off simulation .END LITERAL .HEADER LEVEL 3 SET MODE (NO)SINGLE This command controls the display of multiple data items on a single line (as in EXAM/WORD). I find that I only use this mode as a switch on the EXAMINE command. The initial setting is NOSINGLE. .LITERAL EXAMPLE: SET MODE SINGLE Display one item per line .END LITERAL .HEADER LEVEL 3 SET MODE (NO)SYMBOLIC This command controls the use of symbols in item addresses and disassembled instruction operands (type ADDRESS is always displayed symbolically). The initial setting is SYMBOLIC. .LITERAL EXAMPLES: SET MODE SYMBOLIC Display symbols SET MODE NOSYMBOLIC Do not display symbols .END LITERAL .HEADER LEVEL 3 SET MODE (UN)SIGNED This command controls the display of values with the high bit set as negative. The initial setting is UNSIGNED. .LITERAL EXAMPLES: SET MODE SIGNED Display values as signed SET MODE UNSIGNED Display values as unsigned .END LITERAL .HEADER LEVEL 2 SET OUTPUT The SET OUTPUT command allows the user to control terminal, log file, and command file handling. .HEADER LEVEL 3 SET OUTPUT (NO)ATTACH This command controls whether or not DBG's TI: will be attached during data output (e.g. EXAMINE, SHOW). The initial setting is ATTACH. .HEADER LEVEL 3 SET OUTPUT (NO)LOG This command controls whether or not commands and responses (except HELP responses) will be sent to the log file. The initial setting is NOLOG. .HEADER LEVEL 3 SET OUTPUT (NO)TERM This command controls whether or not commands and responses (except HELP responses) will be sent to the terminal. The initial setting is TERM. .HEADER LEVEL 3 SET OUTPUT (NO)VERIFY This command controls whether or not commands read from a command file are sent to your terminal and the log file (subject to LOG and TERM). The initial setting is NOVERIFY (i.e. commands read from a command file are executed quietly). .HEADER LEVEL 2 SET PROFILE The SET PROFILE command is used to control instruction profiling; specifically, it is used to create a profile range. A profile range consists of a set of counters which reflect execution within a specific address range. To create a profile range an address range, and a compression factor, must be specified. The address range specifies the minimum and maximum addresses which are to be profiled. The compression factor specifies the number of instruction words to be represented by each 32-bit counter. The default compression factor of one provides the best possible profile resolution, but may consume too much memory. Higher levels of compression reduce resolution, but also reduce memory requirements. .LITERAL EXAMPLES: SET PROF 0:20000 Profiles from 0 to 20000, 1 word per counter SET PR 20002:40000 2 Profiles from 20002 to 40000 2 words per counter .END LITERAL .HEADER LEVEL 2 SET TRACE SET TRACE is used to set one or more tracepoints. The addresses of the instructions which are to be traced must be specified. If multiple tracepoints are set then their addresses should be separated by commas. .LITERAL EXAMPLES: SET TRACE LOOP Trace location LOOP SET TRACE MAIN+20 Trace location MAIN+20 .END LITERAL .HEADER LEVEL 2 SET TYPE SET TYPE controls the default type displayed by the EXAMINE command. The type to be displayed must follow SET TYPE. The initial setting is INSTRUCTION. .LITERAL TYPES: ADDRESS Displays symbolic addresses ASCII Displays ASCII text BYTE Displays byte data INSTRUCTION Displays instructions RAD50 Displays RAD50 characters WORD Displays words EXAMPLE: SET TYPE ADDR Set the default type to ADDRESS .END LITERAL .HEADER LEVEL 2 SET WATCH SET WATCH is used to set one or more watchpoints. The addresses of the data words which are to be watched must be specified. If multiple watchpoints are set then their addresses should be separated by commas. .LITERAL EXAMPLES: SET WATCH ERRCOUNT Watch the word at ERRCOU SET WATCH @SP+4 Watch the third word from the top of the stack SET WATCH R5 Watch R5 .END LITERAL .HEADER LEVEL 1 SHOW The SHOW command is used to display various DBG parameters. .HEADER LEVEL 2 SHOW BREAK SHOW BREAK will display the symbolic address of every breakpoint that is currently set. If no breakpoints are set then nothing will be displayed. .HEADER LEVEL 2 SHOW HISTORY SHOW HISTORY will display the size or contents of the history buffer. If no switches are provided then the size will be displayed. The switches specify what information should be displayed for each history entry. The optional count parameter specifies how many of the most recent history entries should be displayed. .LITERAL SYNTAX: SHOW HISTORY[/switches] [count] SWITCHES: /INSTRUCTIONS Displays instructions /REGISTERS Displays registers EXAMPLES: SHOW HIST Displays history buffer size SH HIST/I/R '' entire history buffer SH HIST/R '' all registers in buffer SH HIST/I 5 '' last 5 instructions .END LITERAL .HEADER LEVEL 2 SHOW MODE SHOW MODE will display the current mode settings. Note that some mode parameters (e.g. LEADING, SIGNED, SIMULATE, SINGLE) are only displayed when they are enabled (i.e. NOLEADING will never show up). .HEADER LEVEL 2 SHOW OUTPUT SHOW OUTPUT will display the current output settings (i.e. those controlled by the SET OUTPUT command). .HEADER LEVEL 2 SHOW PROFILE SHOW PROFILE will display the profile ranges that have been defined. For each range, the low and high addresses, and the compression factor, will be displayed. SHOW PROFILE/COUNTERS will display all of the profile counters. Each line will contain the symbolic address of the lowest word represented by the counter, and the number of instructions executed in the words represented. .HEADER LEVEL 2 SHOW SYMBOL SHOW SYMBOL will display the name and value of every symbol known to DBG. The symbols will be displayed in value order. If no symbols have been defined then nothing will be displayed. .HEADER LEVEL 2 SHOW TRACE SHOW TRACE will display the symbolic address of every tracepoint that is currently set. If no tracepoints are set then nothing will be displayed. .HEADER LEVEL 2 SHOW TYPE SHOW TYPE will display the current default type for the EXAMINE command. .HEADER LEVEL 2 SHOW WATCH SHOW WATCH will display the symbolic address of every watchpoint that is currently set. If no watchpoints are set then nothing will be displayed. .HEADER LEVEL 1 STEP The STEP command executes one or more instructions in the target task. If a numeric value is provided then the number of instructions specified will be executed. The step count is treated as an unsigned 16-bit value. If no count is specified then one instruction will be executed. .LITERAL SYNTAX: STEP [count] EXAMPLES: STEP Execute the next instruction STEP 3 Execute the next 3 instructions .END LITERAL .HEADER LEVEL 1 UNDEFINE The UNDEFINE command is used to delete one or more symbols from the symbol table. The symbol name(s) must be specified. If more than one symbol is to be deleted then the names should be separated with commas (no blanks). .LITERAL SYNTAX: UNDEFINE symbol[,symbol...] EXAMPLE: UNDEF START Remove START from the symbol table .END LITERAL .CHAPTER Installing DBG .SUBTITLE Installing DBG All source code needed for DBG and DBGAID is provided. To assemble all of the modules, install ...MAC and type "MAC @DBGASM". To generate listings, use command file DBGASL instead of DBGASM. If your machine supports I/D space, then you may task build DBG by typing "TKB @DBGBLD". Otherwise, you will have to task build DBG by typing "TKB @DBGOVLY" (overlaid DBG). I/D space DBG is faster and has more space for symbols, breakpoints, profile ranges, etc., so you should use it if possible. If your system does not support fast mapping then you will have to edit out the "/FM" switches in the task build files, and remove the definition of X$FMAP from DBGPRE.MAC. Once you have assembled and task built DBG, you should copy DBGAID.OBJ to LB:[1,1], and copy DBG.TSK to your LIBUIC (LB:[3,54]). If you intend to modify DBG, then DBG.STB will be useful for debugging it. .HEADER LEVEL 1 Conditional Assembly In some cases you may wish to modify DBGPRE.MAC (the source prefix file) to change conditionally assembled support. The following conditional assembly symbols are used: .LITERAL I$FIS - Disassembly of FIS instructions I$FPP - Disassembly of FPP instructions I$MTPS - MFPS/MTPS support for simulation M$PLUS - Execution on RSX-11M-PLUS (default) X$FMAP - Fast mapping support .END LITERAL .HEADER LEVEL 1 Use of FCSRES Using FCSRES or FCSFSL with DBG will reduce the size of the task. If the overlaid version is used, then this will also increase the virtual address space available for symbols, etc. If your system does not support FCSRES then you will have to remove the line specifying it in DBGOVLY.CMD. .CHAPTER Task Building for use with DBG .SUBTITLE Task Building for use with DBG In order for DBG to be used with a program, the DBGAID module must be linked in as a debugging aid when the task is built. This module, which is normally located in LB:[1,1], must always be placed in the root of an overlaid task. .HEADER LEVEL 1 A Simple Example In the following example, DBGAID is linked with a task which consists of a single module, TEST. The symbol table file produced will contain all global symbols defined in TEST. These may be used to aid in debugging after being loaded into the symbol table with a LOAD TEST command. .LITERAL TKB TEST,,TEST=TEST,LB:[1,1]DBGAID/DA .END LITERAL .HEADER LEVEL 1 More About DBGAID The DBGAID module contains several locations which may be of interest to advanced (i.e. desperate) users. Location $DBG$S (instruction space) may be patched to contain an RTI instruction (octal 000002). This will cause DBGAID to begin task execution immediately. If an error SST occurs (the MCR DEBUG command could also be used) then DBGAID will attempt to communicate with the appropriate debugger task. This allows a production task to be debugged if and when a problem is discovered (without re-task building). DBG is built this way (see DBGBLD.CMD). Location $DBG$T (data space) contains the RAD50 name of the task which DBGAID will communicate with. The first word (3 characters) of this value may be patched during task building (or later) so that a name other than "DBGTxx" will be used. This is especially useful for debugging more than one task from a single terminal, or using DBG to debug itself (see DBGBLD.CMD). The second word of this value is determined at startup from the TT: unit number of the target task's TI: (e.g. a task running at TT13: will set this word to RAD50 "T13"). Location $DBG$V (data space) contains the 8-word SST vector table. This table, which is described in the Executive Reference Manual under the SVDB$ directive, is used to vector the SSTs that DBG is interested in. Some language run time systems, particularly DEC's Fortran OTS, use the TRAP instruction. Normally DBGAID would receive this SST, but by changing the TRAP SST vector word ($DBG$V+14) to a zero you can allow Fortan to handle TRAPs in its own way. The other SST vector words may be treated similarly, except that DBG will cease to be useful if you zap the T-bit and BPT trap vector. Please note that your task must never issue an SVDB$ directive (SVTK$ is OK). On RSX-11M-PLUS V3.0, DBGAID requires 562 bytes of instruction space, and 526 bytes of data space (1088 bytes total). .CHAPTER Using DBG .SUBTITLE Using DBG .HEADER LEVEL 1 Getting Started DBG only seems to work right when it is installed as a utility (i.e. ...DBG), so make sure that this is done prior to attempting to use it. After having built your task with DBGAID, run it in the normal manner. Unless you have patched DBGAID location $DBG$S, your program will not do anything much. Now type DBG followed by the name of your task (if you leave off the task name, DBG will prompt for it). If all is well, then DBG will come up with a message that includes DBG's version and the name of the target task, and a prompt. If you created a symbol table file, now is the time to LOAD it. The EXAMINE command will let you look around (try "EXAM @PC" or "EXAM/W R0:PS"), and the GO and STEP commands will let you begin to execute your task. Set a breakpoint with SET BREAK (clear it with CANCEL BREAK). The HELP command just might. .HEADER LEVEL 1 Target Task Priority If you must do a lot of stepping (e.g. profiling or using watchpoints) and cannot use simulate mode then you should make sure that your target task runs at a lower priority than DBG. This will result in much faster execution. This is because of the way DBG and DBGAID use the Wait for Significant Event directive while communicating. Organizing your task priorities in this manner could also improve the speed of other operations. .HEADER LEVEL 1 Directive Status The executive expects the directive status word ($DSW) to be at location 46. DBGAID, however, would modify the target task directive status if it didn't save it. For this reason you should always refer to $DSW by name for both examination and modification. This will cause you to reference the target task directive status that DBGAID has squirreled away, and which will be restored before execution proceeds. If you "EVAL $DSW", you will notice it is not at location 46 (it is stored right after the PS in DBGAID). .HEADER LEVEL 1 MCR DEBUG The MCR DEBUG command is used to force a trace trap in a task which has a debugging aid. DBG recognizes this condition, with the possible exception of when the program is being stepped via the trace trap (try again if DBG doesn't seem to notice). If you are stepping, and simulation mode is enabled, then the MCR DEBUG command will not be recognized until an instruction that is not simulated is encountered. This might take a little while. If this is a real problem for you, then you should reduce the value of MAXSIM in DBGPRE.MAC. .HEADER LEVEL 1 PROFANAL PROFANAL.C is a supplied C program that can help you to use the data from instruction profiling. To use PROFANAL, compile and task build it, and run it with the STDIN redirected to a file containing the output of the SHOW PROFILE/COUNTERS command. You can create a file containing this information by logging this information to a file (see SET OUTPUT LOG) and editing the log file to remove everything but the results of this command. PROFANAL will add up all counters between global symbols and display the sums, as well as a grand total, on STDOUT. For many programs, this list represents the relative time spent in each module, therefore it indicates which modules, if any, could profit from optimization. .HEADER LEVEL 1 SST Vectors As discussed in the section on DBGAID, DBGAID's debugging SST vectors begin at location $DBG$V. If any vectors must be disabled (e.g. TRAP for use with the Fortran OTS) they may be modified at run time. The target task must not issue an SVDB$ directive. .HEADER LEVEL 1 I/D Space Tasks DBG is perfectly happy debugging I/D space tasks. It doesn't know that you may get confused because your data and instruction symbols will overmap the same areas. Even if TKB indicated whether symbols are in I or D space, a lot of DBG would have to change to take advantage of it (symbol storage, expression handling, symbol selection, etc.). .HEADER LEVEL 1 Programs with Overlays It is possible to debug programs with overlays using DBG, but I don't recommend it. Overlays make things nasty because DBG doesn't know where things are anymore. You should make sure that no breakpoints are set in an overlay area if another overlay might be loaded; otherwise DBG may modify your program or data for you. It is useful to know that when you set a breakpoint on a global routine that is actually in an overlay, DBG will set the breakpoint on the autoload vector entry point (assuming you are not loading overlays yourself). From this point you can step your way into the overlay... .HEADER LEVEL 1 Programs with ASTs Debugging a program with ASTs can be complicated because of the multiple execution streams through the task. DBGAID protects itself by disabling AST recognition while it has control. Before DBGAID relinquishes control it enables AST recognition only if it was enabled when DBGAID was entered. You can set a breakpoint within an AST routine and DBG should work as expected. If you are single stepping the program at task level, an AST can occur between the time the trace trap occurs and when DBGAID disables AST recognition. When the AST routine is entered the PSW will not have the trace bit set, so the AST routine will execute unimpeded. It may not be obvious that this has occurred. .HEADER LEVEL 1 Debugging a Task at Another Terminal It is sometimes necessary to run DBG on a different terminal from the target tasks TI: (e.g. the target task attaches the terminal). This is most easily handled by running the target task in the normal manner, and initiating DBG execution via the MCR RUN command on another terminal and specifying the task name as if DBG were running on the same terminal as the target task. This works because DBGAID communicates with the DBG task using RCVD$ and SREF$ calls. .LITERAL EXAMPLE: RUN $DBG/TASK=DBGT13 .END LITERAL .HEADER LEVEL 1 Function Keys DBG is very nice with programmable function keys. Unfortunately, I didn't implement them. I have a terminal which allows the user to program the function keys inside the setup menus. I typically put in things like "STEP", "GO", "EXAM/W R0:PS", etc. When I want to implement something that can't be done in one command, I have the function key invoke a command file. A good example is OVER.CMD (below, invoked as "@OVER"). .TEXT .LITERAL ; ; OVER.CMD "steps over" a subroutine call. ; Note that this is not foolproof, but still useful. ; SET BREAK @PC+4 ! Set break at return point GO ! Execute the subroutine CAN BREAK @PC ! Clear the breakpoint .END LITERAL .END TEXT .HEADER LEVEL 1 Serious Problems Because of the way DBGAID is implemented, it is possible to write a program that is very difficult to debug. A program that modifies DBGAID's code and/or data area(s) could cause you to tear your hair out. Assuming that the damage is accidental, it may help to change the ordering of modules (changing DBGAID's PSECT names could work), or to insert guard areas before and/or after DBGAID's code and data areas, and set watchpoints on the guard areas. Understanding how DBGAID works, along with some creative thinking, should get you through most anything. .CHAPTER Implementation .SUBTITLE Implementation DBG is a non-privileged program, and operates on the target task by mapping an address window to it. The DBGAID module facilitates the process by saving and restoring task registers, and by sending mapping context information, and other task areas, by reference. The DBGAID module is rather large because of its internal data requirements, but it is smaller than ODT. An earlier version of this program operated entirely by send and receive data calls, but I got fed up with it because of the poor performance. DBG requires the extended instruction set (EIS). On KDF11 and KDJ11 processors DBG can simulate instruction execution (the MFPS and MTPS instructions are required); this is faster than stepping with the trace trap. DBG uses CSI, GCML, and FCS. DBGAID disables ASTs while it executes, and does not use any LUNs or event flags. DBG uses fast mapping when it is available. DBG and DBGAID use the following executive directives: .LITERAL ALUN$ GTSK$S CRAW$ MAP$S DSAR$S QIO$ DTRG$ QIOW$ ENAR$S QIOW$S EXIT$S RCVD$ EXST$S RREF$ EXTK$S SREF$S GIN$ (subfunction GI.TSK) SVDB$ GLUN$ SDAT$S GMCR$ WSIG$S GMCX$ .END LITERAL DBG is composed of the following files: .LITERAL ASSEMBLE.MAC Assembles instructions for DEP/INS CANCEL.MAC CANCEL command CONVERT.MAC Numeric/symbolic conversion DBGAID.MAC DBG support module for target task DBGPRE.MAC DBG and DBGAID prefix file DEBUG.MAC DBG main program (many global variables) DEFINE.MAC DEFINE and UNDEFINE commands DEPOSIT.MAC DEPOSIT command DISASM.MAC Instruction disassembler ERROR.MAC Error message display and definition EVALUATE.MAC EVALUATE command EXAMINE.MAC EXAMINE command EXECUTE.MAC GO and STEP commands, associated stuff EXPRESS.MAC Expression parser HELP.MAC HELP command and text INIT.MAC One-time initialization LOAD.MAC LOAD command MEMORY.MAC Target task memory routines MODTBL.MAC Mode keyword table for SET and EXAMINE OPCTBL.MAC Opcode table for ASSEMBLE and DISASM SET.MAC SET command SHOW.MAC SHOW command SIM11.MAC PDP-11 instruction simulator SYMBOL.MAC Symbol handling routines TSKCOM.MAC Routines to talk to DBGAID UTILITY.MAC Utility routines (some bizarre) PROFANAL.C C program to analyze profile data DBGASL.CMD MAC command file to assemble DBG DBGASM.CMD Same as DBGASL but makes no listings DBGBLD.CMD Builds DBG for I/D space DBGMAN.CMD Produces DBG manual (via RUNOFF) DBGOVLY.CMD Builds overlaid DBG DBGOVLY.ODL Overlay description for DBGOVLY.CMD DBGFRONT.RNO Cover sheet for DBG manual (RUNOFF) DBGMAN.RNO DBG manual (RUNOFF) DBG.DOC Human readable DBG manual .END LITERAL .HEADER LEVEL 1 Parsing Parsing takes place at several levels within the debugger. Keywords are parsed by recognizing them in keyword tables. Expressions are parsed by a recursive descent expression parser. The following routines (modules) are useful for parsing command lines. .LITERAL U$DCOD (UTILITY) Looks up a keyword in a keyword table. The keyword table is composed of KEYWRD macro calls, and terminated by a zero. U$FNXT (UTILITY) Finds the next command line element. U$FTRM (UTILITY) Finds a command element terminator. XPRESS (EXPRESS) Evaluates an expression. .END LITERAL .HEADER LEVEL 1 User Output .HEADER LEVEL 2 Output Formatting The following routines (modules) are provided to aid in the formatting of output. .LITERAL C$ASCB (CONVERT) Convert a byte to an ASCII character. C$ASCI (CONVERT) Convert a word to 2 ASCII characters. C$NUMB (CONVERT) Convert a byte to a numeric value. C$NUM (CONVERT) Convert a word to a numeric value. C$R50 (CONVERT) Convert a RAD50 word to ASCII. C$SYMB (CONVERT) Convert a word value symbolically. C$VALU (CONVERT) Converts a word value according to the default format (mode and symbol flags). U$ADDR (UTILITY) Buffer an address to start a data line. U$RMTB (UTILITY) Strip trailing blanks from a string. .END LITERAL .HEADER LEVEL 2 Error Output Routine ERROR (module ERROR) is used to output error messages. All of the errors that can be displayed are in a table in this module. A single text argument can be passed for inclusion at a user-defined point in an error message. .HEADER LEVEL 2 Terminal Output Routine LINOUT (module DEBUG) is used to output a line of text to the terminal, and the log file if logging is enabled. Locating the data to be presented in TRMBUF allows optimal data handling. Routines TRMATT and TRMDET (also module DEBUG) are used to attach and detach the terminal for potentially long output sequences. This allows the use of control O on the output. .HEADER LEVEL 1 List Handling All lists managed by DBG are stored in value order. This simplifies many of the list searching algorithms although it frequently increases search times. The following lists are stored in this manner. .LITERAL BRKLST (DEBUG) Breakpoint list (elements are P.xxxx) PROLST (DEBUG) Profile range list (elements are PR.xxx) REGSYM (DEBUG) Register symbols (elements are S.xxxx) SYMTBL (DEBUG) Symbol table list (elements are S.xxxx) TRCLST (DEBUG) Tracepoint list (elements are P.xxxx) WCHLST (DEBUG) Watchpoint list (elements are P.xxxx) .END LITERAL The following routines are provided for managing symbol tables. .LITERAL S$DEFN (SYMBOL) Define a symbol. S$LNAM (SYMBOL) Locate a symbol by name. S$LVAL (SYMBOL) Locate a symbol by value. .END LITERAL