ON-LINE DEUGGING TECHNIQUE "VERSION 9" (ODTV09) PAGE 1 D.R. HANSON (714) 988-2427 DESIGN SPECIALIST DEPT 1-321 LOCKHEED AIRCRAFT SERVICE CO. P.0. BOX 33 ONTARIO, CA 91761 1.0 FOREWORD ODTV09 contains the basic "DEC ODT", modified to gain entry points (hooks) to subsequent routines. All features of the original version are maintained with one exception. Breakpoint 7 is used in this version as a breakpoint which can be installed in line with the users application code. It will not be honored by ODT until the user types "CTRL/B" on the terminal keyboard. This allows the application program to run unhindered by break- points while retaining the ability of the user to halt the program and gain access to ODT functions when desired. All other functions of ODT remain as outlined by (DEC) system manuals. Application programs which require use of the console device in their operation will not be able to use ODTV09 as assembled. The source program is conditionalized to allow assembly using an auxilary terminal for I/O. ODTV09 was written for use as an enhanced debugging tool for an RT- 11 single user environment. It's basic mode allows the user to display application program symbols and their values on the system terminal. At normal "ODT" breakpoints, the displayed values are updated and the contents of the general purpose registers R0 thru R5 are displayed. The user has the option of encoding displayed values in hex, decimal or octal. With only breakpoint 7 installed in inline code, the dynamic mode allows the applicat- ion program to run in real time. The user may alter symbol values/conditions of the application program "on the fly", via keyboard commands, to directly observe program effects. ODTV09 provides a display capability of 35 user selectable symbols. To simplify user entry tasks, the program searches the "linkmap" generated during the linking process, for global symbol addresses. Data at these add- resses are encoded and displayed in three forms. The "WORD" display may be octal, hex or decimal at the users option. This value is then followed by "HIBYTE" and "LOBYTE" values displayed in octal or decimal form. Each of the 35 symbols may be replaced or changed via keyboard commands. Locations which are not global and not in the link map may be monitored by entering the correct address in response to a command prompt. Update period is a result of baud rate, number of symbols displayed and number of data values changed since the last update. An approximation is 1 second at 9600 baud. The program uses direct cursor addressing to write screen data , flicker is evident on the VT52, a flying cursor is in the background on the VT100. VT52 cursor addressing sequences are used in the program, user must switch a VT100 to VT52 compatible mode. -ODTV09- PAGE 2 In addition to the data window into the application program, ODTV09, provides a menu of console commands which allow the user to CLR or SET=1 any of the displayed symbols, change data values in a accumulator and transfer them to the symbols or via a deferred mode of operation, to any location in the user program. This is accomplished during application "run state". A "BLINK" option causes "CLR/SET" flag changes to alternately display the for- mer condition for a presetable period to alert the operator. At each program breakpoint, all data are updated including values of the general purpose registers and is displayed in the selected mode (hex/octal/decimal), a very useful tool during single step mode. ODTV09 uses approximately 4.6K words when linked in low memory. This includes stack area and the reserved vector space. It has been linked with programs in excess of 23K words by using overlays. To effectively use this program, the user should anticipate desired monitoring points of the appli- cation program and assign them global symbols. When linking the run image a linkmap should be generated on the desired storage device per the following example: PROGRM,DEV:PROGRM.MAP/W/A=ODTV09,PROGRM -ODTV09- PAGE 3 2.0 GENERAL OPERATION Using standard (ODT) procedures for program startup, assign reloca- tion registers and breakpoints. ODTV09 uses the line clock vector for update activity. If the application program uses the LTC vector, initial breakpoint must be set after the program loads this vector with its service address. ODTV09, in the dynamic display mode, uses this interrupt to update a screen data list and then jumps to the "application" service routine to complete its task. No other precautions are required. Failure to observe this rule will result in the loss of the "dynamic" mode of operation. ODTV09, upon encountering the initial program breakpoint, will dis- play a menu of services and a request for the file name of the application program linkmap. The default extension is "MAP" and does not have to be en- tered. It then determines the size of the map and reads it to free memory space between the program and the USR. If there is insufficient space to store the entire map, it is sized to be read in sections that will fit (minimum 1 block). If the user normally uses free memory space for patching, he should reserve an area at the end of the application program for this purpose. i.e. "LABEL: .BLKW XX." ODTV09 also searches the system directory for "ODTV09.FIL". If it exists, it reads it to memory, if it does not, it creates it. This file is used to save application program symbols specified by the user. It negates reentering the symbols each time the program is started. Addresses of the symbols are then updated. Each subsequent program breakpoint will report the data values of the selected symbols on the terminal, including the values of the general purpose registers R0 thru R5. To access the menu services, the memory locations must be SET=1 at any breakpoint. The next break encountered will initiate the desired request. To use the dynamic mode, set breakpoint 7 "in line" with program code to insure that it will be accessed each iteration. Remove all other breakpoints and type ";P" followed by "D" on the keyboard. A full report of AP symbols will be written once to clear the screen, thereafter, only the data values are updated. All menu options are then accessible via the keyboard using the command keys depicted in the menu. -ODTV09- PAGE 4 2.1 STARTUP VT52 COMPATIBLE MODE Set the relocation registers using the procedures as depicted in DEC system manuals. Using the program listing, set the first breakpoint beyond your program initialization code. The "LTC" must be on for ODTV09 to enable the dynamic display mode of operation. It will reassign the bus event vector to an internal service routine at the first occurence of this interrupt. The application program therefore must have loaded this vector with its service routine address prior to the first break.If the application program(AP) does not use the vector, then no precaution is required. If it requires that the bus event remain off, no dynamic display is possible, ODTV09 will function in basic mode only. At the initial breakpoint, the menu of service requests will be dis- played. If the program has been linked with ODT in low memory, the addresses displayed are valid, otherwise use the linkmap printout to determine their locations. ODT will have created a storage file named ODTV09.FIL on the sys- tem device if this is the first time startup, otherwise it will read that file to memory. It then requests that the file specification be entered for the linkmap. System device "DK:" and file extension ".MAP" are defaults and do not have to be entered if valid. It then sizes the linkmap file, reads it to memory above the program and searches for the addresses of the symbol labels stored previously. If the linkmap does not reside in its entirety in memory, it reads each section to memory until it finds all that are listed. No indication is given whether it found all the symbols, however, by read- ing the byte "SYMF.D" the user can determine this. It should be the same as all symbols that are declared global in ODTV09.FIL. The program then halts at the initial breakpoint, the user now has access to all standard features of ODT plus the options of ODTV09. Setting the option to "OPTION=1" will initiate the requested service or services, at the next breakpoint. In single step mode, this occurs at the next instruction. In dynamic mode it occurs when breakpoint 7 is encoun- tered or when the next screen update is initiated depending on the request (see discription of individual requests). If this is a first time start up, "MODF.G" should be set by the user to request modification of the display file. The program will request the position number of the symbol to be ent- ered. When the user responds, the present symbol is displayed. Character entry of the desired symbol will overwrite the undesired symbol. A carriage return or 6 characters entered will automatically invoke the address search for the symbol and insert it in the file. Symbols may be entered in any pos- ition, grouped for convenient reference and repeated if desired. To exit the modify mode, type "N". -ODTV09- PAGE 5 The data display will be written to the screen of the system console only upon encountering the second breakpoint. This allows the user to digest the menu before proceeding (pun not intended). ODTV09 will request/interact with the user to insert "AP" symbolic labels in the display file in the pos- itions desired. At the termination of the session, the modified file will be stored on DK:, for subsequent recall. Data contained therein will be encoded to ASCII in the preselected mode and written to the screen, along with the data values of the general purpose registers (R0 thru R5). Each breakpoint thereafter will update the display with the new values. -ODTV09- PAGE 6 2.2 SYMBOLIC DISPLAY The symbolic display consists of 36 displayed labels, each followed by the word data, the hi and lo byte data presentation. Data are presented in the option format selected, octal, decimal or hexadecimal. Symbol "36" is "ODT" reserved and cannot be altered. It consists of "ACUM.L", 6 data positions followed by "option" indicators in the byte data area. Those ind- icators are as follows: SYMBOL *DATA* HBT LBT ACUM.L XXXXXX WBA @DD A=ACCUMULATOR (A)OPEN,( )CLOSED B=BYTE PRESENTATION (O)CTAL,(D)ECIMAL W=WORD " (O)CTAL,(D)ECIMAL,(H)EXADECIMAL D=DIGIT (0-9) TOTAL = 01 THRU 35 @=DEFERRED FUNCTION (@)DEFERRED,( )DIRECT The symbols displayed are 3 columns of 12 labels each. The columns contain 3 groups of 4 labels seperated by a blank line. The labels are ass- igned a position reference for the purpose of user/odt interaction in order to simplify modification of the display. When the user requires an action to them he must address them via their assigned number. They are numbered vert- ically as follows: Column 1 Column 2 Column 3 01 to 12 13 to 24 25 to 36 During entry of user symbols to the display file, it is permissible to specify a position with single digits, i.e., 1 ... 35. The dynamic mode requires they be addressed 01 .. 35, since a single digit 0-9 will address the function flags. In addition to the 36 labels, the display, at a breakpoint, includes 2 lines containing the data present in the general purpose registers R0 to R5. The presentation is in the same format as previously depicted for the 36 labels. The general purpose register display is erased in the dynamic mode since data present in the gpr's is meaningless "on the fly". The data sample is initiated by the first occurence of a bus event interrupt following the completion of the display update and thus would occur at random throughout the application program iteration. -ODTV09- PAGE 7 3.0 ODTV09 OPTIONS (BASIC MODE) 3.1 RPTF.G RPTF.G is initially set and controls the updating of the screen at each breakpoint. If cleared, no update will occur and the screen will not be written at program breakpoints. No other functions are effected. 3.2 MENF.G MENF.G is cleared after the initial display. Setting this flag will recall the menu at the next breakpoint. 3.3 MODF.G The MODF.G allows the user to modify the display file, either to add "AP" symbol labels or change ones which exist. It enables various service routines which interact with the user, to determine the position, the name, and the address of the specified symbol to be displayed. Also, it enables a write of the updated version of the display file to the system storage device at the conclusion of the modification session. User is promp- ted for desired position of the symbol to be entered, the symbol (may be 1-6 characters) and address if not found in the link map. Symbols of less than 6 characters require a carriage return to terminate their entry. A "CR" ent- ered prior to any character will not modify the symbol but will cause an address search. This enables the user to reenter the address of a non global symbol, or to validate that the symbol address was found by the search alg- orithm. It may also be used in reverse to determine the address of a global symbol by entering a non global symbol. The address of the global symbol will be displayed. Use normal procedure to enter the desired symbol again. This feature is useful when an updated hardcopy of the linkmap is unavail- able. 3.4 TMPF.G This flag performs the same functions as the MODF.G except it does not write the updated version of the display file to the system storage dev- ice. It is used when it is desired to temporarily monitor symbol locations without having to reenter the former selections again. 3.5 RDFF.G SET=1 to input the stored display file from the system storage device. Used to return the display file to its original state prior to the "TMPF.G" function. -ODTV09- PAGE 8 3.6 WRDF.G Initially 0, this flag controls the "word" display presentation. All data is displayed in octal when this flag contains an even value. To change the presentation to decimal, set to any odd value. 3.7 BYTF.G BYTF.G controls the "byte" presentation in the same manner as the WRDF.G. The initial presentation will be octal. 3.8 HEXF.G The HEXF.G is included for a reference convenience only, it is only active on the "word" display. Set, the presentation is in hexadecimal. If cleared the presentation reverts to the option selected by the "WRDF.G". 3.9 FFLG.0 thru FFLG.9 Provided within ODTV09, these global flags may be used in the "AP" by the user, either insuring that selected sections of code be executed or not as desired by setting the flag to obtain the desired result. Their use is expanded in the dynamic mode. 3.10 BRKF.G If breakpoint 7 has been installed, it will be ignored unless this flag has been set. Other breakpoints are not effected by it's condition. 3.11 DYNF.G This flag initiates the dynamic mode of operation. It is cleared at the occurrence of a valid breakpoint. It may be manually SET at a breakpoint and the AP started with ";P". The simpler method is to type "D" after the program has started. 3.12 BLNK.F This flag is initially 0. It controls the iteration cycle of the data blinking option. In normal mode of operation it has no purpose, it may how- ever prevent the "byte" presentation from appearing on a changed flag if it had been previously used in the dynamic mode. The "word" presentation will still contain the current condition. Blinking may be cancelled at any time by clearing this flag. 3.13 RETURN TO MONITOR At any breakpoint (ODT level), typing a single "^C" will abort the application program and restore vector assignments to their startup con- ditions before exiting to the monitor. If running in the dynamic mode, "^B" will return to ODT when breakpoint 7 is encountered. "^C" will then return to the monitor. -ODTV09- PAGE 9 4.0 ODTV09 OPTIONS (DYNAMIC MODE) All the foregoing options (services) are applicable in the dynamic mode of operation as they are in normal mode. Additionally, they are only a keystroke away. The dynamic mode can only function if it is not interrupted by a breakpoint. It uses breakpoint 7 to "look see" if any user request is pending. If not, it resets the break count so that the program will not halt. Otherwise it services the request and allows the break to occur. Breakpoints may be hidden behind program conditions, i.e. FFLG.X, and only allow entry to them when the user desires, which is one of the reasons for their existance. To use the dynamic mode, remove (or hide) inline breakpoints except XXXXXX;7B. Initiate start at the desired address, "XXXXXX;G" or if at the desired start point already, type ";P" followed by "D". The entire screen will be rewritten too clean up the display, and the general purpose register data will be erased. The display will now be updated with data only. As each cycle of screen update is complete, data in each symbolic label is compared with the previous value. Changes are encoded to the format re- quested by the user and the screen is updated again. Delays between data changes and screen update is mainly a function of the console baud rate. 654 characters must be written to the screen. Program iteration time is not materially effected since the writing is done via interrupts. A delay may occur which is more than one iteration period since an entire screen update may be starting when a change is commanded from the keyboard. In that event, the result will not be evident until the subsequent update. 4.1 RPTF.G,MENF.G Not effected by dynamic mode, if they are not displayed on the screen they can be set and cleared thru a deferred action to enable/disable the option at the next breakpoint. 4.2 MODF.G KEYSTROKE "M" TMPF.G " "T" RDFF.G " "R" BRKF.G " "^B" Each of the flags function as previously depicted. M,T,R cause break 7 to be honored after their function is complete. ^B returns control to ODT for whatever action desired by the user. The program can be resumed with ";P" and "D". 4.3 WRDF.G KEYSTROKE "W" BYTF.G " "^W" Both of these command functions are alternate action. Depressing the key(s) shown will change the display from octal to decimal or inverse. -ODTV09- PAGE 10 4.4 HEXF.G KEYSTROKE "H" An alternate action key/flag. When off, the display reverts to the selection commanded by the WRDF.G. If "ACUM.L" is open and a digit keystroke made, it is cancelled. No entry can be made in hexadecimal, it conflicts with command keys. 4.5 BLNK.F KEYSTROKE "B" Initially 0, it provides a user defined blink cycle to draw atten- tion to a monitored memory location that has changed. Each keystroke increments the number of on/off blink cycles which will occur. It may be cleared thru the deferred function or at a breakpoint to cease blinking entirely. Only locations which are "CLR" or "SET" will blink, a location which previously contained data, will exhibit the past condition alternately in the "byte" display until the cycle is complete. An additional symbol that incurs a change during the blink cycle will not cause the cycle to restart but will blink until the end of the current cycle. The "word" display always denotes the true condition of the symbol. 4.6 ACUM.L KEYSTROKE "A" The accumulator provides the means to alter program parameters dur- ing debugging "on the fly". An alternate action function, an "A" is dis- played on the screen when it is open. Any digit keystroke will be entered to the accumulator in the format selected by the WRDF.G, either octal or dec- imal. Digit entries which cause overflow are treated as any other digit. Overflow may be corrected by depressing "C" and reenter the desired number. Any non-command keystroke will clear and close the ACCM.L if it is open. The ACUM.L may be used as a octal/decimal reference table by entering a num- ber in one format and then switch formats to view its equivilant. The ACUM.L may be viewed in hex but will revert to oct/dec if a digit is depressed while it is open. To transfer the value in the ACUM.L, a location must be previously selected, or the ACUM.L closed while one is selected. The ACUM.L can then be opened with "A" and depressing "S" will transfer the contents of the ACUM.L to the intended location. The value in the ACUM.L is not changed. Data can be directed to any of the 35 displayed symbolic labels. A symbol from 01 thru 35 is selected by two successive digits. Other numbers greater or less will be ignored. A 3rd digit entered will cancell the 2nd and replace the 1st. Labels 01 thru 09 must be addressed using 2 digits when in the dynamic mode of operation. Data can be entered to FFLG.0 thru FFLG.9 by depressing a single corresponding digit. -ODTV09- PAGE 11 4.7 DYNF.G KEYSTROKE "D" Enables the dynamic display of the symbolics. This command must be invoked each time a program is restarted following a program halt at break 7. It allows the user the option of running the program in real time with only minor interruption ... i.e A. Data routines are not executed B. Screen output is disabled C. ODT executes minimum code at break 7 before returning to "AP" 4.8 FFLG.0 thru FFLG.9 During the course of debugging an application program, it may be ex- pedient for the user to isolate sections of code dependent upon proper oper- ation of related functions. The function flags are global and can be utilized in the application program for this purpose. Select "0" to "9", "S" or "C" to SET or CLR them. Used as data variables, their content can be altered on the fly using the following sequence: KEY: "0" ; Select FFLG.0 "A" ; Open ACUM.L "XXXXXX" ; Enter integer value to ACUM.L "S" ; Transfer ACUM.L to FFLG.0 and close it The following examples illustrate use as control flags: TST FFLG.0 ; If .EQ., don't execute BEQ 1$ . ; "0","S" will enable . ; execution of this section . ; of code when desired . 1$: ASR FFLG.1 ; EXECUTE FOLLOWING ONE TIME! BCC 2$ ; "1","S" . ; bypass until flg is set . ; do it again sam! any time . 2$: -ODTV09- PAGE 12 4.9 DEFE.R KEYSTROKE "@" A deferred mode option is available to enable transfer of data/bit patterns with the "ACUM.L" open, or SET/CLR of any location in addressable memory. This option is fraught with dangers for two reasons. The user should be absolutely sure of his address assignment before using this option. A program abort will be the result. A. A bus error will occur if the addressed location is not valid i.e. ... device address space B. An illegal instruction error can occur if the cpu attempts to execute a "garbage" instruction that has been placed in "in- line" code. FFLG.0 thru FFLG.9 are provided for the deferred mode. An address may be placed in them via the "ACUM.L", the "@" key depressed, a (S)ET or (C)LR function performed. If the "ACUM.L" is open, data in the accumulator will be transferred to the address within the flag selected if the (S)ET key is depressed. Deferred transfers to the labels of the symbolic display are forbidden and will result in a "direct" transfer only. Each deferred action will cancel all selections. A subsequent transfer will require a new setup (reselect the flag, depress the "@" key, initiate the desired function). The function may be aborted previous to the (S)/(C) key by depressing any "non- command" key. Frequently used locations may be saved for future use by inserting them in the function flags, depress "M" which initiates the modify option, depress "N", which then saves them on the system storage device. The program may be then resumed using ";P","D". -ODTV09- PAGE 13 5.0 PRELOADING ODT REGISTERS Most programs require multiple debug sessions to resolve errors, pro- bably because computers execute our instructions but not our intent. If the programs are large, there usually are several modules consisting of discrete subroutines grouped in psects. Each edit cycle the program is linked and the program is restarted. The programmer is required to set inital breakpoints and relocation registers, consulting a printed link map. Although not a cat- astrophic situation, there is an easier way which will not require a link map hardcopy for every program change cycle. Additionally, restart is a single command "XXXXXX;G" (address of the program initialization location). ASSUME: A. Initialization code section preceeds other sections more likely to change (it's address remains constant) B. Each psect declares a unique global label at it's beginning i.e. PSECT1:: ; or a subroutine name WE CAN UTILIZE THE INITIALIZATION CODE TO PRELOAD REGISTERS. INIT:: . ; Program initialization processes . . ; PRELOAD THE RELOCATION REGISTERS MOV #PSECT0,RREG.0 ; .. as many as req'd MOV #PSECT1,RREG.1 ; OVERLAY REGIONS MOV #PSECT2,RREG.2 ; need only one global label . . ; PRELOAD BREAKPOINT 0 THRU 6 (AS DESIRED) MOV #BREAK,BKPT.0 ; Load the "break" address MOV BREAK,INST.0 ; The instruction MOV #3,BREAK ; The trap . . ; PRELOAD BREAKPOINT 7 MOV #STOP,BKPT.7 ; BREAK 7 must be executed MOV STOP,INST.7 ; Each iteration if dynamic MOV #3,STOP ; mode is to be used BREAK: NOP ; Brkpnt "0" will display the menu & ; input the link map specification! ; Subsequent "breaks" if not loaded ; are set per checkout requirements START: . . . STOP: . ; BREAK 7 is ignored if BRKF.G=0 . ; "^B" sets the flag in dynamic mode . ; the break ... clears it ; APPLICATION CODE OR SUBROUTINE CALLS . . JMP START -ODTV09- PAGE 14 6.0 COMMENTS/RESTRICTIONS/PROBLEMS This program was born of necessity, the author's programming efforts have been directed to a real time hardware interactive environment involving small service modules to complete programs with several overlay regions. Resolving bugs in functional modules using ODT is cumbersome to say at best. When interrelationships of independent subroutines are spread over large programs in real time operations, it's frustrating and time consuming. Searching thru linkmaps for addresses, examining memory locations and keeping track of conditions/flags/values taxes your memory as to nature of the ori- ginal problem. A visual display seemed to be the optimum solution. The ver- sions of this program came thru natural evolution, adding functions, optional modes (oct/dec), auto search, etc. ODTV07/8 has been used by many programmers on over a hundred programs. ODTV09 added global declaration of breakpoint and relocation registers plus reset of "system" vectors when aborting. Using this program will shorten the debugging phase of any large program, however one will soon learn the requirement to "declare global" just about anything used, to make monitoring more convenient. The program has been utilized with V3, V4 & V5.0 monitors. It has not been assembled as "VDT" and used with the XM monitor, since the need has not existed in the past. It has been used with LSI-11, LSI-11/2, LSI-11/23 and LSI-11/73 processors (with/without EIS). Use in environments other than the aforementioned may reveal problems not encountered. I would appreciate comments or feedback. The source file is commented and should be easily alte- red if need arises. Screen writing to a VT52 produces flicker since direct cursor addres- sing is used. A VT100 will exhibit a flashing cursor in the background, less noticable in underline mode. Neither effect is particularly irritating and soon is ignored. The search algorithm is not perfect, it has failed to find 4 "known" globals in as many years. The user will know because it queries for the address of the known global when modifying the display file. The inputted link map is sized so that a split of the symbol label occurs therefore it cannot be found in either section. This can only occur in a large program and a very large link map. END