TOPS-20 DDT Manual | Electronic distribution with Autopatch Tape 16 | August 1987 This manual describes the use of TOPS-20 DDT, the Dynamic Debugging Tool for MACRO-20 programs. | This manual updates the | T_O_P_S_-_2_0_ D_D_T_ M_a_n_u_a_l_ printed for | TOPS-20 6.1. This version of | the manual is not printed and | is not available from DIGITAL | in printed form. It is | distributed on the Autopatch | tape #16 for TOPS-20 in .MEM | file format only. You can | print this file on any | printer; page length has been | set at 58 lines. Change bars | indicate changes and bullets | indicate data deletions since | the previous version of this | manual. OPERATING SYSTEM: TOPS-20 V6.1 | SOFTWARE: DDT V44C(670) digital equipment corporation marlboro, massachusetts First Printing, May 1985 | Autopatch Revision, August 1987 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies. | Copyright (C) 1985, 1987, Digital Equipment Corporation. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: DEC DECnet IAS DECUS DECsystem-10 MASSBUS Digital Logo DECSYSTEM-20 PDT PDP DECwriter RSTS UNIBUS DIBOL RSX VAX EduSystem VMS VT CONTENTS PREFACE CHAPTER 1 INTRODUCTION TO DDT 1.1 SYMBOLIC DEBUGGING . . . . . . . . . . . . . . . . 1-1 1.2 TOPS-20 VARIANTS OF DDT . . . . . . . . . . . . . 1-1 CHAPTER 2 GETTING STARTED WITH DDT 2.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 2-1 2.2 LOADING DDT . . . . . . . . . . . . . . . . . . . 2-1 2.3 BASIC FUNCTIONS . . . . . . . . . . . . . . . . . 2-2 2.3.1 Error Conditions . . . . . . . . . . . . . . . . 2-3 2.3.2 Basic Concepts . . . . . . . . . . . . . . . . . 2-4 2.3.3 Starting and Stopping the Program . . . . . . . 2-5 2.3.4 Examining and Modifying Memory . . . . . . . . . 2-6 2.3.5 Executing Program Instructions . . . . . . . . . 2-9 2.4 A SAMPLE DEBUGGING SESSION USING DDT . . . . . . 2-10 2.5 PROGRAMMING WITH DDT IN MIND . . . . . . . . . . 2-21 CHAPTER 3 DDT COMMAND FORMAT 3.1 COMMAND SYNTAX . . . . . . . . . . . . . . . . . . 3-1 3.2 INPUT TO DDT . . . . . . . . . . . . . . . . . . . 3-2 3.2.1 Values in DDT Expressions . . . . . . . . . . . 3-2 3.2.2 Operators in DDT Expressions . . . . . . . . . . 3-7 CHAPTER 4 DISPLAYING AND MODIFYING MEMORY 4.1 DISPLAY MODES . . . . . . . . . . . . . . . . . . 4-1 4.1.1 Default Display Modes . . . . . . . . . . . . . 4-1 4.1.2 Selecting Display Modes . . . . . . . . . . . . 4-2 4.2 DISPLAYING EXPRESSIONS . . . . . . . . . . . . . . 4-6 4.3 DISPLAYING BYTE POINTERS . . . . . . . . . . . . . 4-6 4.4 DISPLAYING AND DEPOSITING IN MEMORY . . . . . . . 4-7 4.4.1 Commands that Use the Current Location . . . . 4-10 4.4.2 Commands that Use the Location Sequence Stack 4-11 4.4.3 Commands that Use an Address within the Command 4-12 4.5 DISPLAYING ASCIZ STRINGS . . . . . . . . . . . . 4-19 4.6 ZEROING MEMORY . . . . . . . . . . . . . . . . . 4-19 4.7 AUTOMATIC WRITE-ENABLE . . . . . . . . . . . . . 4-20 4.8 AUTOMATIC PAGE CREATION . . . . . . . . . . . . 4-21 4.9 DISPLAYING PAGE ACCESSIBILITY INFORMATION . . . 4-22 4.10 WATCHING A MEMORY LOCATION . . . . . . . . . . . 4-23 4.11 TTY CONTROL MASK . . . . . . . . . . . . . . . . 4-23 iii CHAPTER 5 CONTROLLING PROGRAM EXECUTION 5.1 BEGINNING EXECUTION . . . . . . . . . . . . . . . 5-1 5.2 USING BREAKPOINTS . . . . . . . . . . . . . . . . 5-1 5.2.1 Setting Breakpoints . . . . . . . . . . . . . . 5-3 5.2.2 Proceeding from Breakpoints . . . . . . . . . . 5-6 5.2.3 Conditional Breakpoints . . . . . . . . . . . . 5-9 5.2.4 The "Unsolicited" Breakpoint . . . . . . . . . 5-10 5.3 EXECUTING EXPLICIT INSTRUCTIONS . . . . . . . . 5-11 5.4 SINGLE-STEPPING INSTRUCTIONS . . . . . . . . . . 5-11 5.5 EXECUTING SUBROUTINES AND RANGES OF INSTRUCTIONS 5-13 5.5.1 Single-Stepping "Dangerous" Instructions . . . 5-15 5.6 USER-PROGRAM CONTEXT . . . . . . . . . . . . . 5-16 CHAPTER 6 SEARCHING FOR DATA PATTERNS IN DDT CHAPTER 7 MANIPULATING SYMBOLS IN DDT 7.1 OPENING AND CLOSING SYMBOL TABLES . . . . . . . . 7-1 7.2 DEFINING SYMBOLS . . . . . . . . . . . . . . . . . 7-2 7.3 SUPPRESSING SYMBOL TYPEOUT . . . . . . . . . . . . 7-3 7.4 KILLING SYMBOLS . . . . . . . . . . . . . . . . . 7-3 7.5 CREATING UNDEFINED SYMBOLS . . . . . . . . . . . . 7-4 7.6 FINDING WHERE A SYMBOL IS DEFINED . . . . . . . . 7-4 7.7 SEARCHING FOR SYMBOLS . . . . . . . . . . . . . . 7-5 7.8 LISTING UNDEFINED SYMBOLS . . . . . . . . . . . . 7-5 7.9 LISTING SYMBOLS . . . . . . . . . . . . . . . . . 7-5 7.10 LOCATING SYMBOL TABLES WITH PROGRAM DATA VECTORS . 7-6 CHAPTER 8 INSERTING PATCHES WITH DDT CHAPTER 9 FILDDT 9.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 9-1 9.2 USING FILDDT . . . . . . . . . . . . . . . . . . . 9-1 9.2.1 FILDDT Commands . . . . . . . . . . . . . . . . 9-3 9.2.2 Symbols . . . . . . . . . . . . . . . . . . . . 9-4 9.2.3 Commands to Establish Formats and Parameters . . 9-4 9.2.4 Commands to Access the Target and Enter DDT . . 9-5 9.2.5 Exiting FILDDT . . . . . . . . . . . . . . . . . 9-8 CHAPTER 10 PRIVILEGED MODES OF DDT 10.1 MDDT . . . . . . . . . . . . . . . . . . . . . . 10-2 10.2 KDDT . . . . . . . . . . . . . . . . . . . . . . 10-3 10.3 EDDT . . . . . . . . . . . . . . . . . . . . . . 10-4 iv CHAPTER 11 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS CHAPTER 12 EXTENDED ADDRESSING 12.1 LOADING DDT INTO AN EXTENDED SECTION . . . . . . 12-1 12.2 EXAMINING AND CHANGING MEMORY . . . . . . . . . 12-2 12.3 BREAKPOINTS . . . . . . . . . . . . . . . . . . 12-2 12.3.1 The Breakpoint Block . . . . . . . . . . . . . 12-2 12.3.2 Enabling and Disabling Inter-section Breakpoints . . . . . . . . . . . . . . . . . 12-3 12.4 DISPLAYING SYMBOLS IN NONZERO SECTIONS . . . . . 12-4 12.5 DEFAULT SECTION NUMBERS . . . . . . . . . . . . 12-5 12.5.1 Permanent Default Section . . . . . . . . . . 12-6 12.5.2 Floating Default Section . . . . . . . . . . . 12-6 12.6 EXECUTING SINGLE INSTRUCTIONS . . . . . . . . . 12-8 12.7 ENTERING PATCHES IN EXTENDED SECTIONS . . . . . 12-8 APPENDIX A ERROR MESSAGES GLOSSARY INDEX FIGURES 2-1 Sample Program X.MAC . . . . . . . . . . . . . . 2-11 2-2 Annotated Debugging Session . . . . . . . . . . 2-12 2-3 Terminal Display of Debugging Session . . . . . 2-20 4-1 DDT Session Showing Columnar Output . . . . . . 4-25 8-1 Annotated Patching Session . . . . . . . . . . . . 8-4 8-2 Terminal Display of Patching After an Instruction 8-5 8-3 Terminal Display of Patching Before an Instruction 8-6 TABLES 3-1 Commands that Return Values . . . . . . . . . . . 3-3 3-2 Effects of Operators When Evaluating Expressions . 3-8 4-1 Evaluation of Symbolic Display Mode . . . . . . . 4-1 4-2 DDT Display Modes . . . . . . . . . . . . . . . . 4-4 4-3 Commands to Display Expressions . . . . . . . . . 4-6 4-4 DDT Commands to Display Memory . . . . . . . . . . 4-9 4-5 TTY Control Mask . . . . . . . . . . . . . . . . 4-24 5-1 Breakpoint Locations of Interest . . . . . . . . . 5-2 5-2 User-Program Context Values . . . . . . . . . . 5-16 vi PREFACE MANUAL OBJECTIVES AND AUDIENCE This manual explains and illustrates the features of TOPS-20 DDT, the debugger for MACRO-20 programs. Although TOPS-20 DDT can be used to debug the compiled code of programs written in higher-level languages, this manual illustrates the use of TOPS-20 DDT to debug programs written in MACRO-20 only. This manual is both an introduction to the basic functions of TOPS-20 DDT and a reference guide to all TOPS-20 DDT commands and functions. This manual assumes that the reader is familiar with using TOPS-20, has done some programming in MACRO-20, and is familiar with the format of MACRO-20 instructions. STRUCTURE OF THIS DOCUMENT This manual has 12 chapters, one appendix, and one glossary. o Chapter 1 introduces the concept of symbolic debugging and describes the variants of TOPS-20 DDT. o Chapter 2 describes loading TOPS-20 DDT with your program, discusses basic TOPS-20 DDT commands, and illustrates a sample debugging session. o Chapter 3 explains the syntax of a DDT command. Chapter 3 also describes expressions to enter data and explains how TOPS-20 DDT evaluates expressions. o Chapter 4 discusses how to examine and modify a program using TOPS-20 DDT. o Chapter 5 describes the use of TOPS-20 DDT to control program execution: how to start, stop, and monitor the running of a program. vii o Chapter 6 explains how to perform searches of a program's address space using TOPS-20 DDT. o Chapter 7 discusses the manipulation of program symbols using TOPS-20 DDT. o Chapter 8 describes how to use the TOPS-20 DDT patching function to insert and test a new series of instructions in your program without reassembling the program. o Chapter 9 describes the use of FILDDT. o Chapter 10 describes the use of the privileged DDTs: KDDT and MDDT. o Chapter 11 describes special-use commands that control physical and virtual addressing. These commands are useful primarily when running EDDT and FILDDT. o Chapter 12 describes the use of DDT in non-zero sections (NZS). o Appendix A explains DDT and FILDDT error messages. o The glossary defines important TOPS-20 DDT terms. OTHER DOCUMENTS Other documents to which the reader should have access are: o M_A_C_R_O_ A_s_s_e_m_b_l_e_r_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ o T_O_P_S_-_2_0_ L_I_N_K_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ o T_O_P_S_-_2_0_ C_o_m_m_a_n_d_s_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ o D_E_C_s_y_s_t_e_m_-_1_0_/_D_E_C_S_Y_S_T_E_M_-_2_0_ P_r_o_c_e_s_s_o_r_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ o T_O_P_S_-_1_0_/_T_O_P_S_-_2_0_ R_S_X_-_2_0_F_ S_y_s_t_e_m_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ viii CONVENTIONS The following conventions are used in this manual in the description of DDT commands and concepts. {} Curly brackets (braces) indicate that the enclosed item is optional. . (period) The address contained in DDT's location counter; also called the c_u_r_r_e_n_t_ l_o_c_a_t_i_o_n_. addr A symbolic location within a program, a symbolic or absolute address in memory, an AC, or ".", the current location. c A single ASCII or SIXBIT character. expr Any expression that is legal in DDT. filnam One or more components of a file specification. instr Any instruction in the PDP-10 machine instruction set. location sequence stack A circular stack of memory locations that is used to store the addresses of certain previously referenced locations. n A numeric argument. page A page in memory. A page equals 512 words of memory. symbol A symbol name of up to 6 RADIX50 characters. text Any string of ASCII or SIXBIT characters. word Any 36-bit value occupying one word of memory. Represents pressing the ESCAPE or ALTMODE key once. Represents pressing the ESCAPE or ALTMODE key twice. Represents pressing a key (represented by X) at the same time as you press the key labeled CTRL. represents pressing the BACKSPACE key or . Represents pressing the LINE FEED key. Represents pressing the RETURN key. Represents pressing the TAB key or . ix Numbers are in octal radix unless otherwise specified. Examples of interaction between the user and DDT show user input in lowercase and DDT output in uppercase. The symbols , , , , , and always represent user input. NOTE The descriptions of many DDT commands list the actions and effects of those commands. The actions and effects may not occur in precisely the order specified, but this has no effect on the user. x 1-1 CCHHAAPPTTEERR 11 IINNTTRROODDUUCCTTIIOONN TTOO DDDDTT DDT is a utility program you can use to help you debug your MACRO-20 programs. This manual describes how to use the DDT utility. 11..11 SSYYMMBBOOLLIICC DDEEBBUUGGGGIINNGG It is sometimes difficult to understand precisely the operation of a program by reading the source code. DDT is a tool for interactively examining the operation of a MACRO-20 program while it is running. DDT is useful for finding programming errors (bugs) in programs that do not run correctly. You can also use DDT to analyze the flow of control in a program that is to be revised or rewritten. With DDT, you can interrupt the execution of your program at locations (breakpoints) you choose, and then examine and modify the program's address space as required. You can execute instructions one-by-one to check whether the effect of each instruction is what is intended. You can then set other breakpoints in your program before continuing execution. When you refer to program locations and values, DDT allows you to use the symbols that are defined in the program rather than absolute values and addresses. This makes it much easier to refer to the source listing and to find specific locations in memory. After modifying the program's instructions or data, you can exit DDT and save (with the monitor-level SAVE command) the changed version of the program for further testing. 11..22 TTOOPPSS--2200 VVAARRIIAANNTTSS OOFF DDDDTT There are several variants of DDT, each useful under specific circumstances or for specific tasks. 1-1 IINNTTRROODDUUCCTTIIOONN TTOO DDDDTT The variants of TOPS-20 DDT are: o EDDT o FILDDT o KDDT o MDDT o RDDT o SDDT o UDDT o XDDT EDDT is used to debug programs that run in executive mode (such as BOOT), and is described in Chapter 10. FILDDT is used to examine and patch disk files and structures. You can also use FILDDT to examine the running monitor. FILDDT is described in Chapter 9. KDDT is used to debug and patch monitor .EXE files and the running monitor, and is described in Chapter 10. MDDT is used to debug and patch the running monitor, and is described in Chapter 10. RDDT is a relocatable variant of DDT that can be used to debug programs in user mode. If your program is in memory (and has been loaded with RDDT as below), you invoke RDDT by entering (at TOPS-20 command level): START You load RDDT with your program by running LINK as follows: @LINK *MYPROG,SYS:RDDT.REL/GO where MYPROG is the name of your program. Loading RDDT.REL with your program does not prevent you from using other LINK features. You must load RDDT.REL last, or its start address is lost. RDDT.REL is useful in situations where you do not wish to have DDT loaded at its default location. This example shows only the minimal steps required to load the relocatable DDT with your program. See the L_I_N_K_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ for further information about using LINK. 1-2 IINNTTRROODDUUCCTTIIOONN TTOO DDDDTT SDDT is a "stub" that places XDDT in its own section, with system symbols defined as in MONSYM and MACSYM. SDDT is the DDT variant invoked when, at TOPS-20 command level, you enter: SDDT SDDT exists so that entering SDDT invokes DDT version 44 in the same manner as previous versions. UDDT is a "stub" that resides in your user program's section if the program has a TOPS-10-style entry vector and the program entry vector is in section zero. This is done for compatibility with programs that use locations 770000, 770001 and 770002. If you load a program in section zero and the program has a TOPS-10-style entry vector, when you use the DDT command, the EXEC loads the UDDT stub into your program's section at address 770000. UDDT then loads XDDT into the highest-numbered free (nonexistent) section (if XDDT is not already loaded), and starts XDDT. XDDT is the DDT variant normally used to debug user programs. If you load your program in a nonzero section or the program does not have a TOPS-10-style entry vector, the DDT command causes the EXEC to load XDDT directly into the highest-numbered free section. XDDT is also invoked by the SDDT and UDDT stubs. If you type in XDDT while at TOPS-20 command level, the EXEC loads XDDT into section zero, with system symbols defined. 1-3 1-4 CCHHAAPPTTEERR 22 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT 22..11 IINNTTRROODDUUCCTTIIOONN This chapter is an introduction to using DDT. It describes how to load DDT with your program and shows how to perform basic DDT functions. It then illustrates a sample session debugging a simple MACRO-20 program, using basic DDT functions. You can use DDT to debug programs, using only the commands described in this chapter. Once you are familiar with using these commands, you may wish to learn how to use the commands and functions that are described in the rest of the manual, to perform more sophisticated debugging. The commands used in this chapter are described only in sufficient detail for the debugging task being performed; all commands are thoroughly described in Chapters 3 through 11 of this document. The best way to learn is by d_o_i_n_g_. You will learn the commands and techniques discussed in this manual if you use them as you read about them. If you have a MACRO-20 program that you wish to debug, use it to practice the commands discussed here. If not, type in the program X.MAC listed in Figure 2-1. 22..22 LLOOAADDIINNGG DDDDTT | It is much easier to debug a program when you can use the symbols that | are defined in the program. For you to be able to use program | symbols, DDT must have access to your program's symbol table. One way | to provide this access is to use the TOPS-20 DEBUG command to load DDT | with your program and retain your program symbols. Load an existing | MACRO-20 program with the TOPS-20 DEBUG command as follows: | | DEBUG filnam | 2-1 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT | where f_i_l_n_a_m_ is the name of your MACRO-20 program. The following | appears on your terminal (if your .REL file is older than your .MAC | file, MACRO-20 reassembles your program, otherwise the second line | does not appear): | | @DEBUG PROG | MACRO: filnam | LINK: Loading | [LNKDEB DDT execution] | DDT | | where f_i_l_n_a_m_ is the name of your MACRO-20 program (with default | extension .MAC). The last line (DDT) indicates that DDT is loaded, | and is ready to accept your commands. 22..33 BBAASSIICC FFUUNNCCTTIIOONNSS You must be able to perform certain basic functions to interactively debug a program. Basic DDT functions are: o starting the program o stopping the program at specified locations o examining and modifying memory o executing program instructions one-at-a-time o continuing execution of the program | | o deleting input o exiting DDT You must give DDT commands to tell DDT what functions to perform. DDT does not wait for a line terminator (such as a carriage return) to indicate the end of your command. Instead, DDT reads your commands character-by-character as you enter them. When you enter a DDT command, you almost never have to press the RETURN key. This manual explicitly indicates the occasions when a command requires you to press the RETURN key. NOTE You must press the ESCAPE key as part of entering many DDT commands. This manual uses the symbol to indicate where you press the ESCAPE key. When you press the ESCAPE key, DDT displays a dollar sign ($) on the screen. DDT never displays when you press the ESCAPE key. 2-2 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT NOTE This manual uses the symbols , , , , and to indicate where you press the BACKSPACE, ESCAPE, LINE FEED, RETURN, and TAB keys, respectively. This manual also uses the symbol to indicate where you simultaneously press the CONTROL key and the key indicated by X. These symbols ALWAYS indicate where you press the specific keys noted here. You need NEVER enter the characters <_B_K_S_P_>_, <_E_S_C_>_, <_L_F_>_, <_R_E_T_>_, <_T_A_B_>_, or <_C_T_R_L_/_X_>_, to enter a DDT command. Your commands appear on the screen as you type them. Use the DELETE key to delete partially entered commands character-by-character. If you try to delete more characters than you have entered, DDT displays: XXX You can delete an entire command line with . When you do, DDT displays: XXX To exit DDT, enter: The other basic DDT functions are described in the rest of this chapter. 22..33..11 EErrrroorr CCoonnddiittiioonnss If DDT cannot execute a command, it displays a message to let you know. The message may be only a single character (such as M or U, for M_ultiply-defined symbol or U_ndefined symbol), a question mark (?), or a complete message string. For most errors, DDT also sets a pointer to the error string, so that if DDT did not display it, you can enter a command to display the error string. The error string is available for display until another error occurs, when DDT changes the pointer. To display the error string that describes the last DDT error, enter: ? (press the ESCAPE key, followed by a question mark). o 2-3 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT 22..33..22 BBaassiicc CCoonncceeppttss A very useful DDT concept is that of the c_u_r_r_e_n_t_ l_o_c_a_t_i_o_n_. The current location is a memory location that you have referenced, either implicitly or explicitly, with your last command, and that is the default point of reference of your next command. The current location can be thought of as the location "where you are". The symbol "." (period) refers to the address of the current location, and can be used as an argument in DDT commands. The l_o_c_a_t_i_o_n_ c_o_u_n_t_e_r_ is a DDT pointer that contains the address of the current location. The location counter performs a function similar to that of a bookmark. You can enter a command to display the contents of a specific location but not change the address of the current location, in order to maintain a specific point of reference for your next command. Most DDT commands change the address of the current location, and therefore also change the location counter. The commands that do not change the current location are so indicated. The o_p_e_n_ l_o_c_a_t_i_o_n_ is a memory word that can be modified by your next command. DDT "opens" the location as a result of a command you give to examine or modify memory. There is never more than one location open at any given time. The open location is usually also the current location. T_o_ f_i_n_d_ t_h_e_ s_y_m_b_o_l_i_c_ a_d_d_r_e_s_s_ o_f_ t_h_e_ c_u_r_r_e_n_t_ l_o_c_a_t_i_o_n_, enter: ._ (a period followed by an underscore) This causes DDT to display the following: ADDR1+n where ADDR1 is a label defined in your program, and n is the offset of the current location from that label (if the current location is ADDR1, DDT does not display +_n_). Another useful DDT concept is that of the c_u_r_r_e_n_t_ q_u_a_n_t_i_t_y_. This is a value that is the contents of the last word that DDT displayed, or the value that you last deposited in memory. The current quantity is the most recent of those values. Many DDT commands use arguments that default to the current quantity. The l_o_c_a_t_i_o_n_ s_e_q_u_e_n_c_e_ s_t_a_c_k_ is a DDT storage area used to store the addresses of previous current locations. Certain DDT commands store the address of the current location on the location sequence stack. Other DDT commands change the address of the current location to an address that has already been stored on the location sequence stack. The location sequence stack functions in a fashion similar to inserting place-markers in a source code listing, to be able to "get back" to prior references. 2-4 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT 22..33..33 SSttaarrttiinngg aanndd SSttooppppiinngg tthhee PPrrooggrraamm When your program is loaded and DDT is ready to accept your commands (as indicated by D_D_T_ appearing on the terminal display), you can begin execution of your program at its start address by entering: G Unless you set one or more b_r_e_a_k_p_o_i_n_t_s_ before you start the program, your program runs either to completion or until it commits a fatal error. A breakpoint is a location in a program's executable code that has been modified so that i_f_ the program attempts to execute the instruction at that location, control passes to DDT b_e_f_o_r_e_ the instruction is executed. The command to set a breakpoint is: addrB where a_d_d_r_ is the address at which to stop execution. If the user-program PC reaches addr, DDT interrupts execution of the program before the program executes the instruction at the specified address. When DDT interrupts program execution at a breakpoint, it changes the current location to the breakpoint and opens the current location (the breakpoint). While program execution is stopped at a breakpoint, you can display and change the contents of instruction and data words, remove breakpoints, set new breakpoints, and execute instructions one at a time (single-step). As you examine memory, you may find an instruction that is incorrect, and modify it. You can also examine and modify data words in memory. After modifying incorrect instructions and data in memory, you can immediately execute the instructions to check the effects of the modifications, without having to reassemble the source code. Once you have made your changes, you can continue program execution at the place where execution was interrupted, restart the program at the beginning, or start execution at any other location you choose. The program will run to completion, until it reaches a breakpoint, or until it gets a fatal error. 2-5 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT 22..33..44 EExxaammiinniinngg aanndd MMooddiiffyyiinngg MMeemmoorryy One command to examine memory is: addr/ where a_d_d_r_ is the address of the memory word you wish to examine (display), and can be numeric or symbolic. DDT displays the contents of the word located at addr. If the opcode field (bits 0-8) of the memory word matches a recognized instruction or user-defined OPDEF, DDT displays the contents of addr as an instruction (or OPDEF). If DDT finds (in the symbol table) any of the values to be displayed, DDT displays those symbols rather than the numeric values. For example, either of the following display lines might appear on your terminal (depending on the address and contents of the word): ADDR1/ MOVE 2,SYM1 ADDR1+5/ SYM1,,SYM2 where ADDR1, SYM1, and SYM2 have been defined in the program. If you enter a symbol that DDT does not find in the symbol table, DDT sounds the terminal buzzer or bell, and displays U_ on the screen. If you enter a symbol that is defined as a local symbol in more than one module, DDT sounds the terminal buzzer or bell and displays M_. You can eliminate the multiply-defined symbol problem by "opening" the symbol table of the module in which the correct symbol is defined. See Chapter 7 (Manipulating Symbols in DDT) for more information. When searching for a symbol to display, DDT uses global symbols in preference to local symbols. However, DDT searches the "open" symbol table first, and treats local symbols found in the open symbol table as global symbols. If DDT finds only a local symbol that is not in the open symbol table, DDT displays the symbol with a pound-sign (#) appended to the symbol. For example, DDT might display: ADDR#/ MOVE 2,SYM1# See Chapter 7 (Manipulating Symbols in DDT) for more information on symbols and symbol tables. The command a_d_d_r_/_ changes the current location to a_d_d_r_ and opens the word at a_d_d_r_. If you omit a_d_d_r_ from an examine-memory command, such as a_d_d_r_/_, DDT uses the current quantity to determine the address of the location to display. For example, after DDT displays the contents of ADDR1+5 as above, if you enter "/", DDT displays the contents of the word located at SYM2. The display line then appears: ADDR1+5/ SYM1,,SYM2 / value 2-6 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT where v_a_l_u_e_ is the contents of the word located at SYM2. By default, DDT displays v_a_l_u_e_ symbolically if it can. The command / by itself (without a_d_d_r_) does not change the current location. Both forms of the / command open the location displayed, enabling you to modify the location with your next command. Another very useful command for examining memory is . This | command starts a new display line before displaying the contents of | a_d_d_r_, making the display easier to read. For example, if you enter after DDT displays the address and contents of ADDR1+5 (as above) on your terminal, the terminal display appears: ADDR1+5/ SYM1,,SYM2 SYM2/ value where v_a_l_u_e_ is the contents of the word located at SYM2. does not appear on the screen, but is shown above to indicate where you | press the key. changes the current location to SYM2 and | opens the word at SYM2. In this example, the current quantity becomes | v_a_l_u_e_. also stores the address of the current location (ADDR1+5) on the location sequence stack before changing the current location to the location just displayed (SYM2). DDT uses the location sequence stack to "remember" previous values of the location counter. To "get back" to the previous current location, enter: In the above example, after you press at ADDR1+5, DDT displays the contents of SYM2 and changes the current location to SYM2. When you enter , DDT changes the current location to ADDR1+5, opens the location at ADDR1+5, and again displays the contents of ADDR1+5. o If you use the command a_d_d_r_<_T_A_B_>_, DDT deposits a_d_d_r_ in the open location and closes the location before opening the location at a_d_d_r_ and displaying its contents. by itself does not deposit anything, but does save the current location on the location sequence stack, making more useful than / (slash by itself). You can display and open the word after the current location by entering: 2-7 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT DDT changes the current location to the next word in memory, starts a new line, and displays the address of the (new) current location (as a symbol or a symbol plus an offset, if it can find a corresponding symbol in the symbol table), displays the contents of the current location, and opens the current location. For example, to display the next word in memory after ADDR1+5, enter: DDT changes the current location to ADDR1+6, starts a new line, and displays the address and contents of ADDR1+6. The screen display then appears as follows: ADDR1+5/ SYM1,,SYM2 ADDR1+6/ -1,,SYM3 Note that DDT does not display the characters <_L_F_>_. does not affect the location sequence stack. Entering another causes DDT to display and open the next word. To display and open the word p_r_e_v_i_o_u_s_ to the current location, enter: DDT changes the current location to the previous word, starts a new line, displays the address and contents of the (new) current location, and opens the current location. does not affect the location sequence stack. For example, if you enter to open and display the location before ADDR1+5, the screen appears as follows: ADDR1+5/ SYM1,,SYM2 ADDR1+4/ -3,,SYM2 Note that <_B_K_S_P_>_ does not appear on the screen. To change the contents of the open location, enter: value where v_a_l_u_e_ can be an instruction, a symbol, or a numeric expression. For example, if you enter the command L_A_B_L_2_/_, DDT displays the contents of the memory word at LABL2, and "opens" that word. If the word at LABL2 contains: MOVE 1,SYM1 and you wish to change SYM1 to SYM2, enter: MOVE 1,SYM2 2-8 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT DDT stores the new instruction in the location at LABL2 and "closes" the location. DDT does NOT display . The terminal display appears as follows (your input is in lowercase): labl2/ MOVE 1,SYM1 move 1,sym2 The current location is still LABL2, but there is no open location. To check whether the instruction is now correct, you can enter: ./ to display the contents of the current location. The screen display now appears (your input is in lowercase): labl2/ MOVE 1,SYM1 move 1,sym2 ./ MOVE 1,SYM2 After entering a command to display and open a location, if you enter: value DDT stores the new value, changes the current location to the next location in memory, starts a new display line and opens and displays the new current location. The example above would then appear as follows (your input is in lowercase): labl2/ MOVE 1,SYM1 move 1,sym2 LABL2+1/ CONTENTS where C_O_N_T_E_N_T_S_ is the value stored at LABL2+1. o 22..33..55 EExxeeccuuttiinngg PPrrooggrraamm IInnssttrruuccttiioonnss When you have interrupted program execution at a breakpoint, you can execute the next instruction (the one at the breakpoint), by entering: X DDT executes the instruction, displays the results of executing the instruction, and displays the address and contents of the next instruction to be executed. This command changes the current location to the next instruction to be executed. For example, assume that the next instruction to be executed is located at LABEL1, which contains: MOVE 1,VARIBL 2-9 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT If the word at VARIBL contains SYM1, when you enter X, DDT starts a new line and displays: 1/ SYM1 VARIBL/ SYM1 LABEL1+1/ instr where i_n_s_t_r_ is the contents of LABEL1+1, and is the next instruction to be executed. You can continue to execute instructions one-at-a-time by entering successive X commands. This is known as s_i_n_g_l_e_-_s_t_e_p_p_i_n_g_. To e_x_e_c_u_t_e_ a_ s_u_b_r_o_u_t_i_n_e_, enter: X | DDT executes the subroutine and returns control to you if the | subroutine returns to a location +1, +2, or +3 from the instruction | that calls the subroutine. DDT changes the current location to the | address of the next instruction to be executed. o To c_o_n_t_i_n_u_e_ e_x_e_c_u_t_i_o_n_ o_f_ t_h_e_ p_r_o_g_r_a_m_ until the next breakpoint or until program completion, enter: P DDT starts the program running again, beginning with the next instruction to be executed. If you did not single-step any instructions, the program begins by executing the instruction at the breakpoint. If you have executed any instructions by single-stepping, the program continues where you stopped. The effect is as if the program were running without DDT in control. o 22..44 AA SSAAMMPPLLEE DDEEBBUUGGGGIINNGG SSEESSSSIIOONN UUSSIINNGG DDDDTT This section describes a debugging session using DDT. The program being debugged is X.MAC, shown in Figure 2-1. The program and the sample session are for illustration only. There are many styles of programming and debugging, and these examples are descriptive rather than prescriptive in intent. You will understand this section and learn the commands described more easily if you type in the program listed in Figure 2-1 and use the commands as they are described. 2-10 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--11:: SSaammppllee PPrrooggrraamm XX..MMAACC SEARCH MONSYM TITLE X R0=0 ;AC0 IDX=6 ;INDEX REGISTER P=17 ;STACK COUNTER START:: MOVE P,PWORD ;Set up stack counter MOVEI IDX,TABLE1 ;Address of table with X & Y PUSHJ P,ADDEM ;Do the addition MOVEI IDX,TABLE1 ;Address of table MOVE R0,ANSWER(IDX) ;Answer to R0 JFCL 0 HALTF% ;All done! ADDEM: MOVE R0,X(IDX) ;Load X ADD R0,Y(IDX) ;X + Y MOVE R0,ANSWER(IDX) ;Store answer POPJ P, ;Return TABLE1: BLOCK 3 ;3 words X==0 ;Offset for X Y==1 ;Offset for Y ANSWER==2 ;Offset for answer STKSIZ==10 ;Stack size PWORD: IOWD STKSIZ,STACK ;Stack pointer STACK: BLOCK STKSIZ ;Stack END START Figure 2-2 is an annotated session debugging X.MAC, the program in Figure 2-1. In the annotated session, the DDT terminal display is on the left, user input is in the center in lowercase, and explanatory comments about the session are on the right. This is not always the way it appears on the terminal. Figure 2-3 shows the session as it actually appears on the terminal. The program is designed to pass the address of a table to a subroutine. The table contains three elements. The subroutine is to add the first two elements of the table and store the result in the third element before returning to the main program. There are no input or output routines in the program. The table is initialized using DDT, and the result is checked while in DDT. NOTE DDT does not display , , or . These are shown in the sample session to indicate user input. 2-11 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT NOTE DDT does not display the AC field of an instruction if it is zero. This means that if your program contains the instruction MOVE R0,LABL1, where R0=0, DDT displays the instruction as MOVE LABL1. FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn SCREEN DISPLAY USER INPUT EXPLANATION @ TOPS-20 prompt. debug x Begin the session by entering "debug x", where x is the name of your MACRO program. MACRO: X MACRO reassembles your program LINK: Loading (if needed), and LINK loads [LNKDEB DDT execution] your program with DDT. DDT DDT displays the "DDT" prompt. start/ Begin examining code at label "START". MOVE P,PWORD# DDT displays the instruction at START. Press to display the next instruction. .JBDA+1/ MOVEI IDX,TABLE1# The first symbol in this program happens to coincide with .JBDA, a JOBDAT symbol. When DDT scans the symbol table, it finds .JBDA before it finds START, and displays .JBDA instead. DDT still accepts START as an input symbol. Also note the pound-sign (#) appended to TABLE1 and PWORD. PWORD and TABLE1 are local symbols that are not in the open symbol table. 2-12 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION .jbdak Enter .jbdak to suppress DDT typeout of symbol .JBDA. DDT will display START rather than .JBDA from now on. x: Enter the module name (X) followed by and a colon to open the symbol table associated with X. DDT will not append any more pound-signs. Press to start a new display line, evaluate the current quantity as if it were an instruction, and display the contents of the location addressed by the Y field of the instruction. (Entering / (slash) displays the same word as , but does not start a new line.) also saves your place (like a bookmark) on the location sequence stack, so you can get back here easily. TABLE1/ 0 When you enter the command, DDT displays the address and the contents of the location. The first element of the table contains zero. The command also opens the location. 2 Enter "2" followed by to deposit the value "2" in the first element, and to open and display the second element. TABLE1+1/ 0 The second element contains zero. 2-13 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION 3 Enter "3" followed by to deposit the value "3" in the second element and open and display the third element. The addition to be performed by the program is 2+3. TABLE1+2/ 0 The third element (the answer) contains zero. Press , then press to return to the address you saved on the location sequence stack. START+1/ MOVEI IDX,TABLE1 DDT displays the address and contents of the last location you displayed before you entered . Press to look at the next location. START+2/ PUSHJ P,ADDEM This is the call to the subroutine that does the computation. .b Enter ".", press , and enter "b" to set a breakpoint at the current location. g Enter g to start program execution. $1B>>START+2/ PUSHJ P,ADDEM DDT displays the breakpoint number, the address of the breakpoint, and the instruction at the breakpoint. This instruction has not yet been executed. x Press twice, then enter "x" to let DDT execute the subroutine. 2-14 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION START+3/ MOVEI IDX,TABLE1 DDT returns from the subroutine at the next instruction, and displays the address and contents of the instruction. If there is a "skip return", DDT displays "" if the program skipped one instruction. If the program skips 2 or 3 instructions, DDT displays "", where n is the number of instructions skipped. x Press and enter "x" to execute the instruction. IDX/ TABLE1 TABLE1 DDT displays the address and contents of IDX (the result of executing the instruction), and also displays "TABLE1" (the result of evaluating the Y field of the instruction). START+4/ MOVE 2(IDX) DDT then starts a new line and displays the address and contents of the next instruction. Note that DDT does not display the zero in the AC field of the instruction. Press , then to display the contents of the location addressed by the instruction, using any indexing and indirection. (If you omit , DDT uses only the Y field, without indexing and indirection.) TABLE1+2/ 0 The location addressed by the instruction is TABLE1+2, and its contents is zero. This is the table element that contains the answer, which should be 5. 2-15 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION Press to see the previous element in the table. TABLE1+1/ 3 This element contains 3. That is correct. Press again to check the previous element. TABLE1/ 2 This element contains 2. That is also correct. One way to find the error is to single-step through the program. startb Enter "start", press , and enter "b" to set a breakpoint at the beginning of the program. g Press and enter "g" to start the program again. $2B>>START/ MOVE P,PWORD DDT displays the breakpoint number, and the address and contents of the instruction at the breakpoint. x Press , then enter "x" to execute the instruction. This instruction moves a memory word to a register. P/ -10,,PWORD PWORD/ -10,,PWORD DDT displays the address and new contents of the register, and the address and contents of the memory word. START+1/ MOVEI IDX,TABLE1 DDT then displays the address and contents of the next instruction. 2-16 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION x Press , then enter "x" to execute this instruction, which moves an immediate value to a register. IDX/ TABLE1 TABLE1 DDT displays the address and new contents of the register, and the immediate value. START+2/ PUSHJ P,ADDEM DDT then displays the address and contents of the next instruction. x Press , then enter "x" to execute the instruction. P/ -7,,STACK DDT displays the address and new contents of the stack pointer used by the PUSHJ. DDT displays "" if the change in PC is less than one or greater than 4. ADDEM/ MOVE 0(IDX) DDT displays the address and contents of the next instruction to be executed. x Press and enter "x" to execute the instruction. 0/ 2 TABLE1/ 2 The instruction moved the contents of the word at TABLE1 (which is 2) to AC0. Looks OK so far. ADDEM+1/ ADD 1(IDX) DDT displays the next instruction. x Press and enter "x" to execute the instruction. 0/ 5 TABLE1+1/ 3 The instruction added the contents of the word at TABLE1+1 (which is 3) to AC0, which now contains 5. OK. 2-17 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION ADDEM+2/ MOVE 2(IDX) DDT displays the next instruction. x Press and enter "x" to execute the instruction. 0/ 0 TABLE1+2/ 0 The instruction moved the contents of the word at TABLE1+2 to AC0. The MOVE instruction at ADDEM+2 should be MOVEM. ADDEM+3/ POPJ P,0 DDT displays the next instruction (as a result of the x). Press to display and open the location with the incorrect instruction. ADDEM+2/ MOVE 2(IDX) DDT displays the previous instruction. This is the incorrect instruction. movem r0,answer(idx) Enter the new instruction and press . ./ Check the current location to see what you deposited. MOVEM 2(IDX) Looks OK. .b Set a breakpoint at ".", the current location. g Restart the program at the beginning. $2B>>START/ MOVE P,PWORD DDT displays the breakpoint information. p Press and enter "p" to proceed from breakpoint 2 to the next breakpoint. 2-18 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT FFiigguurree 22--22:: AAnnnnoottaatteedd DDeebbuuggggiinngg SSeessssiioonn ((CCoonntt..)) SCREEN DISPLAY USER INPUT EXPLANATION $1B>>START+2/ PUSHJ P,ADDEM DDT displays the breakpoint information. p Proceed from breakpoint 1. $3B>>ADDEM+2/ MOVEM 2(IDX) DDT displays the breakpoint information. This is the instruction you changed. x Single-step the instruction to watch what it does. 0/ 5 TABLE1+2/ 5 The instruction moves the contents of AC0 to the word at TABLE1+2. OK!! ADDEM+3/ POPJ P,0 DDT also displays the address and contents of the next instruction. start+4b Set a breakpoint at START+4 to check the results. p Proceed from breakpoint 3. $4B>>START+4/ MOVE 2(IDX) DDT displays the breakpoint information. x Single-step the instruction. 0/ 5 TABLE1+2/ 5 The instruction moves the contents of the word at TABLE1+2 to AC0. The new value of AC0 is 5. OK! START+5/ JFCL 0 DDT displays the address and contents of the next instruction. Quit. @ Back at TOPS-20 command level. 2-19 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT Figure 2-3 shows the session as it actually appears on the terminal screen. Again, user input is in lowercase. Comments on the right indicate where you enter characters that do not echo. FFiigguurree 22--33:: TTeerrmmiinnaall DDiissppllaayy ooff DDeebbuuggggiinngg SSeessssiioonn @debug x MACRO: X LINK: Loading [LNKDEB DDT execution] DDT start/ MOVE P,PWORD# Enter . .JBDA+1/ MOVEI IDX,TABLE1# .jbda$k x$: Enter . TABLE1/ 0 2 Enter . TABLE1+1/ 0 3 Enter . TABLE1+2/ 0 $ Enter . START+1/ MOVEI IDX,TABLE1 Enter . START+2/ PUSHJ P,ADDEM .$b $g $1B>>START+2/ PUSHJ P,ADDEM $$x START+3/ MOVEI IDX,TABLE1 $x IDX/ TABLE1 TABLE1 START+4/ MOVE 2(IDX) $ Enter . TABLE1+2/ 0 Enter . TABLE1+1/ 3 Enter . TABLE1/ 2 start$b $g $2B>>START/ MOVE P,PWORD $x P/ -10,,PWORD PWORD/ -10,,PWORD START+1/ MOVEI IDX,TABLE1 $x IDX/ TABLE1 TABLE1 START+2/ PUSHJ P,ADDEM $x P/ -7,,STACK ADDEM/ MOVE 0(IDX) $x 0/ 2 TABLE1/ 2 ADDEM+1/ ADD 1(IDX) $x 0/ 5 TABLE1+1/ 3 ADDEM+2/ MOVE 2(IDX) $x 0/ 0 TABLE1+2/ 0 ADDEM+3/ POPJ P,0 Enter . ADDEM+2/ MOVE 2(IDX) movem r0,answer(idx) Enter . ./ MOVEM 2(IDX) .$b $g $2B>>START/ MOVE P,PWORD $p $1B>>START+2/ PUSHJ P,ADDEM $p $3B>>ADDEM+2/ MOVEM 2(IDX) $x 0/ 5 TABLE1+2/ 5 ADDEM+3/ POPJ P,0 start+4$b $p $4B>>START+4/ MOVE 2(IDX) $x 0/ 5 TABLE1+2/ 5 START+5/ JFCL 0 ^Z @ 2-20 GGEETTTTIINNGG SSTTAARRTTEEDD WWIITTHH DDDDTT 22..55 PPRROOGGRRAAMMMMIINNGG WWIITTHH DDDDTT IINN MMIINNDD There are a few MACRO-20 programming techniques that make debugging with DDT easier. These techniques primarily concern the use of labels and symbols. Labels that meaningfully describe (perhaps mnemonically) the function of the code are more helpful when examining code and setting breakpoints than labels that are alphanumerically coded (such as A0001). When using symbols as offsets into tables, you can prevent DDT from displaying the offset symbol in place of the symbol's numeric value if you define the symbol in this way: symbol==expression S_y_m_b_o_l_ is still entered in the symbol table, and you can use symbol as input to DDT, but DDT does not display s_y_m_b_o_l_ on output. For example, if you have defined: OFFSET==3 DDT displays the contents of a word that contains the value of 3 as: addr/ 3 rather than: addr/ OFFSET where addr is the address of the word. See the M_A_C_R_O_ A_s_s_e_m_b_l_e_r_ R_e_f_e_r_e_n_c_e_ M_a_n_u_a_l_ for more information about defining symbols. 2-21 2-22 CCHHAAPPTTEERR 33 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT 33..11 CCOOMMMMAANNDD SSYYNNTTAAXX The complete syntax of a DDT command is: {arg1<}{arg2>}{arg3}{{}{arg4}}c{arg5} where arg1, arg2, arg3, arg4, and arg5 are arguments to the command c_. Arg1, arg2, and arg3 can be any legal DDT expression. Arg1 must be followed by a left angle bracket (<), and arg2 must be followed by a right angle bracket (>). Arg4 can only be a number. Arg5 is a text argument of the form: /text/ or c where text is a string of characters, the slashes (/) are delimiters that can be any character not contained in text, and c is a single character. DDT commands never use all five arguments. Each argument is optional or required according to the syntax of the specific command. Most DDT commands are not more complicated than: arg3c or arg3arg4c You can enter alphabetic commands and text arguments in uppercase or lowercase. An argument to a command can be the result of executing another command. For example, you can enter a command to evaluate a text string, and then enter another command to deposit in memory the result of evaluating the text string. The entire command line would be: "/abcd/ where /_a_b_c_d_/_ is the argument to the command " (quotation mark). The function of the quotation mark command is to evaluate the string (abcd) within the delimiters (/) as a left-justified ASCII string. 3-1 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT The left-justified ASCII string a_b_c_d_ is then the argument to the command (entered by pressing the RETURN key). The function of the command is to deposit an argument (in this case, the string a_b_c_d_) into the open location. The " command is described in this chapter, and the command is described in Chapter 4 (Displaying and Modifying Memory). Most commands produce results that are immediately visible, such as commands that display the contents of memory locations. However, commands such as those that invoke search functions or those that evaluate text expressions (as above) may not produce immediately visible results. If you enter a question mark (?) while DDT is performing a function invoked by one of these commands, DDT displays a message that tells you what DDT is currently doing. For example, such a message might be: Searching: addr/ value where a_d_d_r_ is the address that DDT is to next test as part of a search, and v_a_l_u_e_ is the contents of the memory location at a_d_d_r_. Still other commands return values that DDT does not display, but can use as arguments to other commands. 33..22 IINNPPUUTT TTOO DDDDTT You enter arguments to DDT as e_x_p_r_e_s_s_i_o_n_s_. An expression can be a single value, or a combination of two or more values with one or more o_p_e_r_a_t_o_r_s_. 33..22..11 VVaalluueess iinn DDDDTT EExxpprreessssiioonnss Values in DDT expressions can be: o octal or decimal integers o floating point numbers o symbols o values that are returned by commands o text To enter an o_c_t_a_l_ i_n_t_e_g_e_r_ v_a_l_u_e_, simply enter the integer in octal digits. For example: 70707065 3-2 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT To enter a d_e_c_i_m_a_l_ i_n_t_e_g_e_r_ v_a_l_u_e_, enter the integer in decimal digits and follow the value with a decimal point. For example: 9876. To enter a f_l_o_a_t_i_n_g_ p_o_i_n_t_ n_u_m_b_e_r_, use regular or scientific notation. For example, you can enter the value .034 as one of the following: .034 3.4E-2 Note that 1. is a decimal integer, while 1.0 is a floating point number. To enter a s_y_m_b_o_l_ as a value in an expression, type in the symbol name as defined in your program. To enter an u_n_d_e_f_i_n_e_d_ s_y_m_b_o_l_ that you can define later, enter: symbol# where s_y_m_b_o_l_ is the symbol that you will later define. See Chapter 7 (Manipulating Symbols in DDT) for more information about using undefined symbols. You can enter a c_o_m_m_a_n_d_ t_h_a_t_ r_e_t_u_r_n_s_ a_ v_a_l_u_e_ as a value in an expression. DDT commands that return values and the values they return are listed in Table 3-1. TTaabbllee 33--11:: CCoommmmaannddss tthhaatt RReettuurrnn VVaalluueess CCOOMMMMAANNDD VVAALLUUEE RREETTUURRNNEEDD VVAALLUUEE AALLSSOO KKNNOOWWNN AASS . The address of the current location. . . The address of the next user program $. instruction to be executed. . The previous value of ".". $$. nB The address of the DDT location that $nB contains the address of breakpoint n. nI The address of the DDT location that contains the saved machine state flags (user-program context). nM The address of DDT "mask" n. Q The current quantity. $Q 3-3 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT TTaabbllee 33--11:: CCoommmmaannddss tthhaatt RReettuurrnn VVaalluueess ((CCoonntt..)) CCOOMMMMAANNDD VVAALLUUEE RREETTUURRNNEEDD VVAALLUUEE AALLSSOO KKNNOOWWNN AASS Q The current quantity, with halves $$Q swapped. nU The address of the DDT location that contains the argument (or default) that was given in the virtual addressing command: exprnU. The commands nB, nI, nM, and nU, return values that are the addresses of locations internal to DDT, which contain information that you can use and modify. For brevity, these commands are said to address those internal DDT locations. For example, the command nB returns (but does not display) the address of the DDT location that contains the address of breakpoint n, and the command addr/ (address followed by slash) displays the contents of the location at addr. To display the address of breakpoint n, enter: nB/ where you enter the command nB as the expression for DDT to evaluate as a_d_d_r_. | You can enter t_e_x_t_ to be interpreted in the following ways: | | o left-justified ASCII strings | | o left-justified SIXBIT strings | | o single right-justified ASCII characters | | o single right-justified SIXBIT characters | | o RADIX50 words | You can enter text expressions in uppercase or lowercase. DDT translates strings to uppercase for SIXBIT or RADIX50 text as required. The term l_o_n_g_ t_e_x_t_ s_t_r_i_n_g_ refers to an expression in a DDT command that is a string of text characters that requires more than one 36-bit expression for full evaluation. You can enter long text strings in SIXBIT and ASCII as DDT expressions. If you use a long text string as an expression, DDT assumes that you will enter a command that deposits the expression in memory. 3-4 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT DDT evaluates the string one 36-bit expression at a time. After evaluating the first 36-bit expression, DDT deposits the expression in the open location, closes the open location, and opens the next location. DDT then evaluates the next 36-bit expression contained in the string, and deposits that expression in the (new) open location. This process continues until you enter c_, the command. If you enter a command that does deposit to memory, DDT deposits the final 36-bit expression in the open location, and updates the location counter according to the rules of that particular command. The current quantity is the last 36-bit expression that DDT evaluated. If you do not enter a command that deposits to memory, DDT uses, as the argument to the command, the 36-bit expression that was last evaluated. All other 36-bit expressions that were evaluated as part of the string have been deposited, and the current and open locations were updated accordingly. The current quantity is then the last 36-bit expression that DDT evaluated. If there is no open location when you begin typing the long text string, DDT evaluates only the first 36-bit expression, ignores the rest of the string, and uses the first 36-bit expression as the argument to the command. The current quantity is then the first 36-bit expression that DDT evaluated in the string. If you enter a command that deposits to memory, it has no effect because there was no open location. o The syntax to enter an A_S_C_I_I_ s_t_r_i_n_g_ is: "/text/ where t_e_x_t_ is the string, and the slashes (/) represent any printing character that is not contained within t_e_x_t_. DDT evaluates the string as a series of 36-bit expressions, each in 7-bit ASCII format (left-justified), with all unused bits reset. For example, if you enter: "+abc/def+ DDT evaluates one 36-bit expression as the 7-bit ASCII string a_b_c_/_d_ in bits 0-34, and bit 35 reset. If there is no open location, DDT uses that expression as the argument to the command, and that expression becomes the current quantity. If there is an open location, DDT deposits a_b_c_/_d_ in the open location, closes it, and opens the next location in memory. DDT then evaluates a second 36-bit expression as the 7-bit ASCII string e_f_ in bits 0-13, and bits 14-35 reset. The last 36-bit expression evaluated becomes the current quantity. 3-5 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT NOTE You cannot use this format to enter an ASCII string that begins with the ESCAPE character, because terminates the command that enters a single right-justified ASCII character (in this case, your intended delimiter). The syntax to enter a S_I_X_B_I_T_ s_t_r_i_n_g_ is: "/text/ where text is the string, and the slashes (/) represent any printing character that is not contained within t_e_x_t_. DDT evaluates the string as a series of 36-bit expressions, each in SIXBIT format (left-justified), with any unused bits in the last 36-bit expression reset. DDT translates lowercase characters to uppercase; all other non-SIXBIT characters cause DDT to sound your terminal buzzer or bell and display a question mark. For example, if you enter: "/qwertyu/ DDT evaluates one 36-bit expression as the SIXBIT string Q_W_E_R_T_Y_ in bits 0-35. If there is no open location, DDT uses that expression as the argument to the command, and that expression becomes the current quantity. If there is an open location, DDT deposits Q_W_E_R_T_Y_ in the open location, closes it, and opens the next location in memory. DDT then evaluates a second 36-bit expression as the SIXBIT character U_ in bits 0-5, with bits 6-35 reset. The last 36-bit expression evaluated becomes the current quantity. The syntax to enter a right-justified A_S_C_I_I_ c_h_a_r_a_c_t_e_r_ is: "c where c is the character. DDT evaluates this as one 36-bit expression with the 7-bit ASCII character c_ in bits 29-35, and bits 0-28 reset. 3-6 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT The syntax to enter a right-justified S_I_X_B_I_T_ c_h_a_r_a_c_t_e_r_ is: "c where c is the character. DDT evaluates one 36-bit expression with the SIXBIT character c_ in bits 30-35, and bits 0-29 reset. DDT translates lowercase characters to uppercase; all other non-SIXBIT characters cause DDT to sound your terminal buzzer or bell and display a question mark. The syntax to enter a R_A_D_I_X_5_0_ w_o_r_d_ is: text5" where t_e_x_t_ is any string of RADIX50 characters up to six characters long. DDT evaluates one 36-bit expression with bits 0-3 reset and the RADIX50 string t_e_x_t_ in bits 4-35. DDT ignores any characters in t_e_x_t_ after the sixth. For example, if you enter: poiuytr5" DDT evaluates one 36-bit expression with bits 0-3 reset and the RADIX50 string P_O_I_U_Y_T_ in bits 4-35. DDT ignores the character r_. DDT translates lowercase characters to uppercase. Characters in t_e_x_t_ not in the RADIX50 character set that are DDT commands use, as an argument to the command, any characters already entered. Characters in t_e_x_t_ not in the RADIX50 character set that are not DDT commands cause DDT to sound your terminal buzzer or bell and display a question mark. 33..22..22 OOppeerraattoorrss iinn DDDDTT EExxpprreessssiioonnss When you enter an expression, DDT evaluates the expression to create a 36-bit quantity but does not necessarily use all 36 bits when it executes the command. For example, you can enter a complete MACRO instruction when giving an argument to a command that requires an address, but DDT uses only the address specified by the instruction (and ignores the rest of the evaluated expression) when it executes the command. Table 3-2 lists DDT's expression operators and the effects those operators produce on the evaluation. The term v_a_l_u_e_ s_o_ f_a_r_ represents the accumulated 36-bit value resulting from evaluation of the expression to that point. 3-7 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT TTaabbllee 33--22:: EEffffeeccttss ooff OOppeerraattoorrss WWhheenn EEvvaalluuaattiinngg EExxpprreessssiioonnss OOPPEERRAATTOORR EEFFFFEECCTT OONN EEVVAALLUUAATTIIOONN + Add the 36-bit value on the left to the 36-bit value on the right, using two's complement addition. - Subtract the 36-bit value on the right from the 36-bit value on the left, using two's complement subtraction. * Multiply the 36-bit value on the left by the 36-bit value on the right, using PDP-10 full-word integer multiplication. DDT uses only the low-order 36 bits of the result. ' (apostrophe) Divide the 36-bit value on the left by the 36-bit value on the right, using PDP-10 full-word integer division. DDT ignores any remainder. NOTE Apostrophe is DDT's division operator. / (slash) is a DDT command to examine memory, and is never used in DDT to indicate division. space Add the previous expression (normally an opcode) to the value so far, and add the low-order 18 bits of the value at the right of the space to the low-order 18 bits of the value so far. DDT ignores carries resulting from the addition, and does not change the left half of the value so far. 3-8 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT TTaabbllee 33--22:: EEffffeeccttss ooff OOppeerraattoorrss WWhheenn EEvvaalluuaattiinngg EExxpprreessssiioonnss ((CCoonntt..)) OOPPEERRAATTOORR EEFFFFEECCTT OONN EEVVAALLUUAATTIIOONN , (comma) If you are entering an I/O instruction, shift the low-order 18 bits of the expression at the left of the comma 26 bits to the left (to the device field of the instruction), otherwise shift the low-order 18 bits of the expression at the left of the comma 23 bits to the left (to the A field of an instruction). Then logically OR the result into the value so far. NOTE DDT does not check whether the value at the left of the comma is a legitimate device or AC address, and may overwrite other parts of the instruction. () Swap the halves of the expression within the parentheses and add the resulting expression to the value so far. This makes it possible to enter an instruction that uses an index register. NOTE DDT does not check whether the value within the parentheses is a legitimate AC address, and may overwrite other parts of the instruction. @ Assume the expression is an instruction and set the indirect bit (bit 13) of the value so far. ,, (two commas) Move the low-order bits of the expression at the left of the commas to bits 0-17 and build a new 18-bit expression in the right half. 3-9 DDDDTT CCOOMMMMAANNDD FFOORRMMAATT The nonarithmetic operators allow you to enter expressions in i_n_s_t_r_u_c_t_i_o_n_ f_o_r_m_a_t_ as well as in d_a_t_a_ f_o_r_m_a_t_. To enter an i_n_s_t_r_u_c_t_i_o_n_, format the instruction as you would in a MACRO-20 program. For example: MOVE R4,@VAR1+OFFSET(R5) NOTE Follow an opcode (such as MOVE) with a space, not a . To enter h_a_l_f_w_o_r_d_s_, enter the values (numbers or symbols) separated by two commas (,,). The halfwords can be symbolic or absolute values. For example: -1,,SYM1 NOTE DDT is not designed to evaluate complicated arithmetic expressions. The nonarithmetic operators are implemented to enable DDT to evaluate expressions you enter as MACRO-20 instructions and halfwords. Using values and operators for other purposes may not produce the results you intend. 3-10 CCHHAAPPTTEERR 44 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..11 DDIISSPPLLAAYY MMOODDEESS A major function of DDT is displaying the contents of memory words, both data and instructions. You can choose whether to display the contents of memory words as symbols or as numeric values. You can also select the radix in which DDT displays numeric values. DDT displays symbols, labels, and most messages in uppercase. 44..11..11 DDeeffaauulltt DDiissppllaayy MMooddeess There is no sure way for DDT to distinguish between instruction and data words, or between data words of different formats. DDT displays memory words in symbolic mode by default. Symbolic mode is described in Table 4-1. DDT tests for the condition on the left, and if the condition is met, displays the word in the format described on the right. DDT performs the tests in descending order. TTaabbllee 44--11:: EEvvaalluuaattiioonn ooff SSyymmbboolliicc DDiissppllaayy MMooddee CCOONNDDIITTIIOONN DDDDTT DDIISSPPLLAAYYSS EEXXAAMMPPLLEE Bits 0-18 are all set. A negative number -45 in the current radix. The 36-bit value is defined The symbol. SYMBL1 in the user program symbol HALT table. The opcode field is zero. Halfwords. 345,,-27 4-1 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY TTaabbllee 44--11:: EEvvaalluuaattiioonn ooff SSyymmbboolliicc DDiissppllaayy MMooddee ((CCoonntt..)) CCOONNDDIITTIIOONN DDDDTT DDIISSPPLLAAYYSS EEXXAAMMPPLLEE The opcode and I, X, and Y The OPDEF. CORE 6, fields, or the opcode and A fields match an OPDEF in the user program symbol table. The opcode matches a The instruction. MOVE 3,SYMBL definition in DDT's internal hardware instruction table. No match. Halfwords. 3445,,-23 By default, DDT displays numeric values in radix 8. Leading zeros are always suppressed. 44..11..22 SSeelleeccttiinngg DDiissppllaayy MMooddeess You can select display modes to control: o the format in which DDT tries to interpret the contents of memory locations; for example, as instructions, or as floating-point numbers. o whether addresses are displayed as symbolic or numeric values. o the radix in which numeric values are displayed. In addition, you can specify these modes on a short-term (temporary mode) or long-term (prevailing mode) basis. A prevailing display mode remains in effect until you select another prevailing mode, but may be overridden by a temporary mode until you enter a command that restores the prevailing display mode. DDT commands that restore the prevailing display mode are: o {expr} (deposit expr and close location) o G (start program execution) o P (proceed from a breakpoint) o W, E, N (perform a search) o Z (zero memory) 4-2 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY o instrX (execute i_n_s_t_r_) o V (watch a location) The syntax of commands that set the prevailing mode is: mode where mode is one of the display modes shown in Table 4-2. The syntax of commands that set a temporary mode is: mode where mode is one of the display modes shown in Table 4-2. The c_u_r_r_e_n_t_ d_i_s_p_l_a_y_ m_o_d_e_ is the mode (prevailing or temporary) in which DDT will display the next word (unless you enter a command to change the display mode). DDT has two "masks" that control the action of two of the display modes. 3M is a command that addresses a DDT location that contains the o_u_t_p_u_t_ b_y_t_e_ s_i_z_e_ m_a_s_k_. When the current display mode is O, each bit that is set in the mask indicates the position of a low order bit of a byte in the word being displayed. In this mode, bit 35 is always assumed to be set. For example, if the output byte size mask contains: 510410100400 (octal) the byte sizes specified are, from left to right, 1, 2, 3, 4, 5, 6, 7, and 8. When displaying a word in O mode that contains 777777,,777777, and the current radix is 8, DDT displays: 1,3,7,17,37,77,177,377 The default value of the output byte size mask is zero, specifying one 36-bit byte. You can set the output byte size mask with the command: expr3M where e_x_p_r_ evaluates to the bit pattern required. You can also examine and change the output byte size mask with the examine and deposit commands described later in this chapter. 4-3 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 2M is a command that addresses a DDT location that contains the m_a_x_i_m_u_m_ s_y_m_b_o_l_i_c_ o_f_f_s_e_t_. When DDT displays an address in R(elative) mode, it displays the address symbolically, that is, as a symbol, or as a symbol + the numeric offset of the address from that symbol. The maximum symbolic offset (minus 1) determines the maximum offset address that DDT displays symbolically, and defaults to 1000 (octal). DDT displays addresses beyond that offset in A(bsolute) mode. For example, assume that the maximum symbolic offset is 2, and that you are examining subroutine ADDEM in program X.MAC (Fig 2-1), using to display instructions in sequence. DDT displays: ADDEM/ MOVE 0(6) ADDEM+1/ ADD 1(6) addr/ MOVE 2(6) where a_d_d_r_ is the absolute address (for example, 14414) of the location. You can set the maximum symbolic offset with the command: expr2M where e_x_p_r_ evaluates to the offset required. You can also examine and change the maximum symbolic offset with the examine and deposit commands described later in this chapter. DDT display modes and the commands that select them are described in Table 4-2. TTaabbllee 44--22:: DDDDTT DDiissppllaayy MMooddeess FFOORRMMAATT MMOODDEESS MODE EFFECT C Display memory word as numbers in the current radix (see Radix Modes). F Display memory word as a floating point decimal number. H Display memory word as two halfword addresses (see Address Modes) separated by two commas (,,). O Display memory word as numeric bytes of sizes that are specified by the 3M mask. n0 Display memory word as n-bit numeric bytes, (with trailing remainder byte, as required). 4-4 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY TTaabbllee 44--22:: DDDDTT DDiissppllaayy MMooddeess ((CCoonntt..)) FFOORRMMAATT MMOODDEESS MODE EFFECT S Display memory word in symbolic mode (default). 1S Search DDT's internal hardware opcode table before searching the user's symbol table, otherwise follow rules for symbolic mode. nT Display memory word as ASCII text, using n-bit bytes. | n=1: Byte Pointer Format n=5: RADIX50 n=6: SIXBIT | n=7 through 36: | | Specifies the number of bits per byte. The | default is 7-bit ASCII. | | n=0: ASCIZ | | (Stop ASCIZ typeout by typing any character.) A Display addresses as absolute values in the current radix. R Display addresses as values relative to symbols (default). DDT displays the offsets in the current radix. The maximum offset is controlled by the value stored in the 2M mask, and defaults to 1000 (octal). RRAADDIIXX MMOODDEESS MODE EFFECT nR Display numeric values in radix n (default=8), where n is a decimal number greater than 1. If n=8, DDT displays the word as octal halfwords, otherwise DDT displays the word as one number. o 4-5 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..22 DDIISSPPLLAAYYIINNGG EEXXPPRREESSSSIIOONNSS DDT has three commands you can use to display expressions in different modes. They are: ; (semicolon) = (equal sign) _ (underscore) The syntax of these commands is: {expr}c where e_x_p_r_ is the expression to display (e_x_p_r_ defaults to the current quantity), and c_ is one of the above commands. These commands are useful for redisplaying the current quantity without affecting the current display mode. Table 4-3 lists the commands to display expressions and their effects. TTaabbllee 44--33:: CCoommmmaannddss ttoo DDiissppllaayy EExxpprreessssiioonnss CCOOMMMMAANNDD EEFFFFEECCTT ; Display the current quantity in the current display mode. expr; Display expr in the current display mode. = Display the current quantity as a number in the current radix. expr= Display expr as a number in the current radix. - Display the current quantity in 1$ mode. expr_ Display expr in 1$ mode. 44..33 DDIISSPPLLAAYYIINNGG BBYYTTEE PPOOIINNTTEERRSS If you set the display mode to 1T, DDT displays the contents of the memory location as a byte pointer. DDT can display one-word local, one-word global, and two-word byte pointers. DDT displays the P and S fields, and the address as determined by the I, X, and Y fields of the byte pointer. In section zero, DDT displays only one-word byte pointers (local and global). 4-6 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY For example, if the contents of the location at ADDR2 is 100702,,addr, where addr is the value of symbol LABL2, the following illustrates one-word local byte pointer display: addr2/ 100702,,addr lT; 10 7 LABL2(2) The following illustrates one-word global byte pointer display, where addr is the value of symbol LABL2: 1,,addr2/ 610002,,LABL2 lT; 44&7 2,,LABL2 The following illustrates two-word global byte pointer display, where addr is the value of symbol LABL2 (DDT echoes as ^H): 1,,addr2/ 440740,,0 1,,addr2+1/ 3,,addr lT^H 1,,addr2/ 44 7 3,,MAIN. <2> 44..44 DDIISSPPLLAAYYIINNGG AANNDD DDEEPPOOSSIITTIINNGG IINN MMEEMMOORRYY DDT allows you to display the contents of memory locations and deposit a new value in the open location. In performing these functions, you must understand the concept of the open location, the current location, the location sequence stack, and the current quantity. The o_p_e_n_ l_o_c_a_t_i_o_n_ is a memory location (or AC) that is "open" for modification by the next command. There is never more than one location open at a time. DDT always closes the open location before opening another. The l_o_c_a_t_i_o_n_ c_o_u_n_t_e_r_ contains the address of a word in memory that has been referenced (implicitly or explicitly) by the previous command, and that is the default point of reference for the next command. That word is known as the c_u_r_r_e_n_t_ l_o_c_a_t_i_o_n_. DDT uses the address of the current location as the default address in most commands. The current location is often, but not always, the open location. Most DDT commands change the current location to a word specified by an address given (explicitly or by default) in the command. Commands that do not are so indicated. "." (period) is a command that returns (but does not display) the address of the current location. When you first enter DDT, the current location is zero. 4-7 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY The l_o_c_a_t_i_o_n_ s_e_q_u_e_n_c_e_ s_t_a_c_k_ is a "ring" of seventeen words, each containing the address of a prior current location, or of a match found during a search. The present value of the current location is not placed in the ring. Entries are made to and retrieved from the location sequence stack in a last-in, first-out manner. Most commands that change the location counter by values other than +1 and -1 cause DDT to place the address of the current location (before the change) on the location sequence stack. Addresses of matching locations found during searches are also placed on the location sequence stack. When DDT enters a new value in the next word on the stack, the new value becomes the c_u_r_r_e_n_t_ l_o_c_a_t_i_o_n_ s_t_a_c_k_ e_n_t_r_y_. This is similar to PUSHing entries on a stack. When the current location stack entry is the last location on the location sequence stack, DDT enters a new value on the stack by "wrapping around" to the beginning of the stack and overwriting the value in the first location on the stack. The first location on the stack then contains the current location stack entry. Certain DDT commands change the address of the current location to the current location stack entry, and then change the current location stack entry to the previous entry. This is similar to POPing entries off a stack, and allows you to "return" to locations that have previously been the current location. When the first location on the location sequence stack contains the current location stack entry and DDT changes the address of the current location to the current location stack entry, DDT "wraps around" to the end of the stack, and the value contained in the last word of the stack becomes the current location stack entry (whether or not the stack was previously "full"). The c_u_r_r_e_n_t_ q_u_a_n_t_i_t_y_ is a value that is the most recent of: o the last 36-bit quantity that DDT displayed (an expression or the contents of a memory location) o the last expression that you entered as an argument to a command that deposits to memory This value is also known as the l_a_s_t_ v_a_l_u_e_ t_y_p_e_d_. Q is a command that returns (but does not display) the current quantity. DDT issues an implicit Q to return this value for use as the default argument for some commands. You can give the current quantity as an argument to a command by entering the command Q as the argument. The command Q returns the current quantity with the right and left halves swapped. This manual uses the term $Q to refer to the value that is returned by the command Q, and the term $$Q to refer to the value that is returned by the command Q. 4-8 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY Some commands calculate the address of the location to be opened from an expression given or defaulted in the command. Other commands use the address of the current location or entries on the location sequence stack. The general syntax of these commands is: {expr}{}c where e_x_p_r_ is any legal DDT expression, and c is the command. NOTE See V_a_l_u_e_s_ i_n_ D_D_T_ E_x_p_r_e_s_s_i_o_n_s_ in Chapter 3 for a discussion of long text strings as values in DDT expressions. Table 4-4 summarizes the commands and their effects. Complete descriptions of the commands follow the table. TTaabbllee 44--44:: DDDDTT CCoommmmaannddss ttoo DDiissppllaayy MMeemmoorryy CCOOMMMMAANNDD DDIISSPPLLAAYY MMOODDEE OOPPEENN CCHHAANNGGEE DDEEPPOOSSIITT CCOONNTTEENNTTSS OOFF TTHHEE CCUURRRREENNTT EEXXPPRR DDIISSPPLLAAYY LLOOCCAATTIIOONN LLOOCCAATTIIOONN / Yes Current Yes Yes(1) No [ Yes Numeric Yes Yes(1) No ] Yes Symbolic Yes Yes(1) No ! No Suppress Yes Yes(1) No \ Yes(2) Current Yes No Yes(1) Yes(2) Current Yes Yes Yes(1) No Restore No No Yes(1) Yes(2) Current Yes Yes(.+1) Yes(1) Yes(2) Current Yes Yes(.-1) Yes(1) or ^ (1) If you enter expr. (2) If not suppressed by !. 4-9 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..44..11 CCoommmmaannddss tthhaatt UUssee tthhee CCuurrrreenntt LLooccaattiioonn The commands , , and use the address of the current location to determine the next address of the current location. These commands do not make entries to the location sequence stack. {expr} does the following: o deposits expr (if given) in the open location o closes the open location o resets the current typeout mode to the prevailing typeout mode o does not change the address of the current location {expr} does the following: o deposits expr (if given) in the open location o closes the open location o increments the location counter o opens the current location o o displays the open location (unless display has been suppressed by !) {expr} and {expr}^ do the following: o deposits expr (if given) in the open location o closes the open location o decrements the location counter o opens the current location o o displays the open location (unless display has been suppressed by !) 4-10 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..44..22 CCoommmmaannddss tthhaatt UUssee tthhee LLooccaattiioonn SSeeqquueennccee SSttaacckk The commands , , and use the current location stack entry to determine the next address of the current location. Repetitions of these commands refer to successively earlier entries on the stack, until you again address the most recent entry. These commands do not make entries to the location sequence stack. {expr} does the following: o deposits expr (if given) in the open location o closes the open location o changes the value contained in the location counter to the current location stack entry o opens the current location o starts a new line and displays the address and contents of the open location in the current display mode o causes the previous entry on the location sequence stack to become the current location stack entry NOTE If display is suppressed as a result of using the ! command, the command {expr} restores the current display mode, which can be either a temporary or prevailing display mode. {expr} does the following: o deposits expr (if given) in the open location o closes the open location o changes the value contained in the location counter to the current location stack entry o increments the location counter o opens the current location o starts a new line and displays the address of the open location 4-11 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY o displays the contents of the open location (unless display has been suppressed by !) o causes the previous entry on the location sequence stack to become the current location stack entry {expr} and {expr}^ do the following: o deposits expr (if given) in the open location o closes the open location o changes the value contained in the location counter to the current location stack entry o decrements the location counter o opens the current location o displays the address of the open location o o displays the contents of the open location (unless display has been suppressed by !) o causes the previous entry on the location sequence stack to become the current location stack entry 44..44..33 CCoommmmaannddss tthhaatt UUssee aann AAddddrreessss wwiitthhiinn tthhee CCoommmmaanndd The commands: / (slash) [ (left square bracket) ] (right square bracket) ! (exclamation point) \ (backslash) use an expression given in the command (either explicitly or by default) to determine the addresses of the current location and the open location. 4-12 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY The complete syntax of these commands is: {expr}{{}}c where expr may be an address, ".", a symbol, or any expression that is legal in DDT, and c is the command. When you use the commands /, [, ], !, \, and : o If you omit e_x_p_r_ > DDT uses the current quantity as a default. > enters the address of the current location on the location sequence stack and changes the current location to the address determined from the current quantity. o If you enter e_x_p_r_, DDT enters the address of the current location on the location sequence stack (except \). o DDT treats e_x_p_r_ (whether given or defaulted) as if it were in instruction format and performs the effective address calculation as follows: > If you omit , DDT does not perform indexing or indirection. > If you include one , DDT treats expr as an IFIW (instruction format indirect word), and uses the I and Y fields of expr to perform indexing and indirection when appropriate. > If you use , DDT utilizes EFIWs (extended format indirect words), as appropriate, when performing effective address calculations, and can thereby calculate 30-bit addresses. > In section zero, when you include , it is treated as one . These commands always do the following: o close the open location o open the location at the address indicated by expr o change the current quantity to the value displayed (all commands except !) 4-13 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY The following is a list that gives a complete description of the effects of each command. COMMAND EFFECTS / o closes the open location o opens the location at the address calculated from the current quantity o displays the contents of the open location in the current display mode o sets the current quantity to the value displayed expr/ o closes the open location o opens the location at the address calculated from expr o enters the address of the current location on the location sequence stack o changes the current location to the location at the address calculated from expr o displays the contents of the open location in the current display mode o sets the current quantity to the value displayed [ o closes the open location o opens the location at the address calculated from the current quantity o displays the contents of the open location in numeric mode in the current radix o o sets the current quantity to the value displayed 4-14 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY expr[ o closes the open location o opens the location at the address calculated from expr o enters the address of the current location on the location sequence stack o changes the current location to the location at the address calculated from expr o displays the contents of the open location in numeric mode in the current radix o sets the current display mode to numeric mode in the current radix o sets the current quantity to the value displayed ] o closes the open location o opens the location at the address calculated from the current quantity o displays the contents of the open location in symbolic mode o sets the current display mode to symbolic mode o sets the current quantity to the value displayed expr] o closes the open location o opens the location at the address calculated from expr o enters the address of the current location on the location sequence stack o changes the current location to the location at the address calculated from expr o displays the contents of the open location in symbolic mode o sets the current display mode to symbolic mode o sets the current quantity to the value displayed 4-15 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY ! o closes the open location o opens the location at the address calculated from the current quantity o does not display the contents of the open location o suppresses display of the open location by the \, , , and commands (any other display command restores the current display mode) o does not change the current quantity expr! o closes the open location o opens the location at the address calculated from expr o enters the address of the current location on the location sequence stack o changes the current location to the location at the address calculated from expr o does not display the contents of the open location o suppresses display of the open location by the \, , , and commands (any other display command restores the current display mode) o does not change the current quantity \ o closes the open location o opens the location at the address calculated from the current quantity o displays the contents of the open location in the current display mode (unless display has been suppressed by !) o sets the current quantity to the value displayed 4-16 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY expr\ o deposits expr in the open location o closes the open location o opens the location at the address calculated from expr o does not change the address of the current location (and does not enter the address of the current location on the location sequence stack) o displays the contents of the open location in the current display mode (unless display has been suppressed by !) o sets the current quantity to the value displayed o closes the open location o opens the location at the address calculated from the current quantity o enters the address of the current location on the location sequence stack o changes the current location to the location at the address calculated from the current quantity o starts a new line and displays the address of the open location (which is also the current location) o displays the contents of the open location in the current display mode (unless display has been suppressed by !) o sets the current quantity to the value displayed expr o deposits expr in the open location o closes the open location o opens the location at the address calculated from expr o enters the address of the current location on the location sequence stack o changes the current location to the location at the address calculated from expr 4-17 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY o starts a new line and displays the address of the open location (which is also the current location) o displays the contents of the open location in the current display mode (unless display has been suppressed by !) o sets the current quantity to the value displayed You can treat e_x_p_r_ as an IFIW (instruction format indirect word), and use any indexing and indirection specified by e_x_p_r_ to compute the effective address of the location to be opened. Use the command form: {expr}c where c is /, [, ], !, \, or . For example, assume the following conditions as indicated by the display commands: COMMAND DISPLAY EXPLANATION LABL1/ SYM1 Display contents of LABL1. LABL1+1/ SYM2 Display contents of LABL1+1. SYM2/ SYM3 Display contents of SYM2. 2/ 1 Display contents of AC 2. @LABL1(2)/ SYM1 DDT uses Y field only. @LABL1(2)/ SYM3 causes indexing and indirection. Note that DDT does not start a new line unless you enter , , or , or until the display wraps around the end of the line. DDT also displays three spaces (or a tab, depending on the TTY control mask) before and after its output. Thus, an actual DDT terminal display might be the following (user input is lowercase; and do not appear on the screen, but are shown to indicate where you pressed the corresponding keys): 2/ 1 labl1/ SYM1 LABL1+1/ SYM2 SYM2/ SYM3 sym4/ MOVE 1,@LABL1(2) SYM2/ SYM3 You can treat e_x_p_r_ as an EFIW (extended format indirect word) and use any indexing and indirection specified by e_x_p_r_ to compute the (global) effective address of the location to be opened. Use the command form: {expr}c where c is /, [, ], !, \, or . 4-18 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..55 DDIISSPPLLAAYYIINNGG AASSCCIIZZ SSTTRRIINNGGSS You can display memory as an ASCIZ string. The command addr0T where addr defaults to the open location (if there is one, otherwise addr defaults to the current location), displays memory, beginning with addr, as an ASCIZ string. The display stops when DDT finds a zero byte, or when you type in any character, which DDT displays, but otherwise ignores. The current location remains unchanged. 44..66 ZZEERROOIINNGG MMEEMMOORRYY To deposit the same value in each of a string of memory words (useful for initializing memory to zero), enter: addr1{expr}Z where expr is any legal DDT expression, addr1 is the first word to receive expr, and addr2 is the last. Follow addr1 with a left angle bracket (<) and addr2 with a right angle bracket (>). Both addr1 and addr2 are required. If you omit expr, it defaults to zero. Prior to execution, DDT enters the address of the current location on the location sequence stack and closes the open location. When DDT has | completed execution of the command, the current location is the word | at addr2 + 1. There is no open location. This command restores the prevailing display mode. If you enter: ? while DDT is executing the Z command, DDT displays: Depositing: addr/ value where a_d_d_r_ is the location where DDT will make the next deposit, and v_a_l_u_e_ is the contents of a_d_d_r_ before the deposit. If you enter any other character, DDT stops executing the Z | command, and waits for your next command. The character that you | enter to terminate the Z command is otherwise ignored. 4-19 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..77 AAUUTTOOMMAATTIICC WWRRIITTEE--EENNAABBLLEE If you attempt to deposit a value in a location that is write-protected, DDT returns the message ?NOT WRITABLE This is the TOPS-20 default condition. To allow DDT to modify write-protected memory, type in {0}W If you now attempt to deposit a value in a location that is write-protected, DDT removes the protection, deposits the value, and then reinvokes the protection. Note that you cannot use this command to enable patching in FILDDT. To prevent DDT from modifying write-protected memory, type in {0}W The zero in the above commands is optional and has no effect on the operation of the commands. DDT allows the zero for compatibility with prior versions of DDT. 4-20 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..88 AAUUTTOOMMAATTIICC PPAAGGEE CCRREEAATTIIOONN If you attempt to deposit a value in a location within a nonexistent page, DDT creates the page and deposits the value. If you attempt to deposit a value within a nonexistent section, DDT creates the section as well as the page. This is the default condition. To prevent DDT from creating a page when you attempt to deposit a value within a nonexistent page, type in 1W If you now attempt to deposit a value in a location within a nonexistent page, DDT returns the error message CAN'T CREATE PAGE To allow DDT to create the page (and the section, as required) when you attempt to deposit a value within a nonexistent page, type in 1W 4-21 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY | 44..99 DDIISSPPLLAAYYIINNGG PPAAGGEE AACCCCEESSSSIIBBIILLIITTYY IINNFFOORRMMAATTIIOONN | | You can get information about the access requirements of the pages and | sections in the program you are debugging, using the $L and $$L | commands. The complete format for this command is: {{arg1<}arg2}{}L where arg1 and arg2 are section numbers. Using one causes DDT to display access information about the section and about individual pages. Using twice causes DDT to display access information only about the section(s). If you include both arg1 and arg2, DDT displays the information for all sections that your program and DDT are using, in the range arg1 to arg2, inclusive. If you include only arg2, DDT displays access information for that section only. If you omit both arguments, DDT displays access information for all sections that your program and DDT are using. The page and section accessibility bits and their meanings are: Read Page can be read. Write Page can be written. Copy-on-write Page is copy-on-write Execute page can be executed Private page is private Zero Page is allocated but zero.(FILDDT only) For example, the command L might produce the following display: | Section 0 Read, Write, Execute, Private | 000 Read, Write, Execute, Private | 770 Read, Execute | 771 Read, Write, Execute, Private | Section 37 Read, Write, Execute, Private | 700-701 Read, Copy-on-write, Execute | 703-730 Read, Copy-on-write, Execute | 735-736 Read, Write, Execute, Private | 740-753 Read, Execute And the command L might produce a display like the following: Section 0 Read, Write, Execute, Private Section 37 Read, Write, Execute, Private 4-22 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY 44..1100 WWAATTCCHHIINNGG AA MMEEMMOORRYY LLOOCCAATTIIOONN If you wish to have DDT monitor or "watch" a memory location while your program is running, and display the location whenever its contents change, enter: addrV where a_d_d_r_ is the address of the location to be watched, and defaults to the current location. When you enter the command, DDT starts a new line and displays: addr/ value where a_d_d_r_ is the address of the location being watched, and v_a_l_u_e_ is the contents of the location. This command also restores the prevailing display mode. DDT checks a_d_d_r_ every "jiffy" (about 20 milliseconds), and displays the address and contents of a_d_d_r_ whenever those contents change. (Executive mode EDDT watches a_d_d_r_ continuously.) If you enter a question mark (?) while DDT is watching, DDT displays: Watching: addr/ value where a_d_d_r_ is the address of the location being watched, and v_a_l_u_e_ is the contents of a_d_d_r_. To terminate the watch, enter any other character. DDT stops monitoring the word, starts a new display line, echoes the character you enter, starts another line, and waits for more input. The character that you enter to terminate the watch is otherwise ignored. Because any input character terminates the watch, you cannot continue execution and watch your own user program. The V command is useful to watch activity in a separate process (such as the running monitor or other job, for which you must be using EDDT or FILDDT). The page that contains the word you wish to watch must be mapped into your own process (the one that contains DDT and your program). 44..1111 TTTTYY CCOONNTTRROOLL MMAASSKK You can control certain aspects of DDT's display by setting DDT's T_T_Y_ c_o_n_t_r_o_l_ m_a_s_k_. The command 1M returns a value that is the address of the DDT location that contains this mask. Table 4-5 summarizes the features controlled by the bits in the TTY control mask. 4-23 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY TTaabbllee 44--55:: TTTTYY CCoonnttrrooll MMaasskk BBIITT VVAALLUUEE EEXXPPLLAANNAATTIIOONN 15 0 Display the commands (and results) from the file executed by the Y command (default). 1 Do not display the commands (or results) from the file executed by the Y command. 16 0 When interrupting program execution at a breakpoint, display the address and contents of the breakpoint (default). 1 When interrupting program execution at a breakpoint, display only the address of the breakpoint. 17 0 Display 3 spaces when spacing DDT output (1). 1 Display DDT output fields at tab stops (1). 34 0 The terminal does not have a tab mechanism (2). 1 The terminal has a tab mechanism (2). 35 0 Echo deleted characters (3). 1 Backspace over deleted characters (3). (1) If bit 17 is reset (default), DDT displays 3 spaces between output fields (such as between the address of a location and the contents of the location), and at the end of display lines. If bit 17 is set, DDT lines up the output fields in columns beginning at tab stops (see bit 34). Figure 4-1 illustrates the two different modes. (2) If bit 34 is set, DDT displays a tab character () between fields. If bit 34 is reset, DDT displays enough spaces to start the field at the next tab stop. When starting up, DDT checks whether your terminal can handle TAB characters (), and sets this bit accordingly. (3) When starting up, DDT checks whether your terminal can backspace to delete characters, and sets this bit accordingly. 4-24 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY To change the settings of the TTY control mask, use the command: expr1M where expr evaluates to the required bit pattern. You can also open the location addressed by 1M with one of the DDT display commands, and deposit an expression that contains the new bit settings. Figure 4-1 is an illustration of the effects of bit 17 in the TTY control mask. The code being examined is the first few lines of X.MAC, listed in Figure 2-1. The example is not a complete debugging session; only enough is shown to illustrate the effects of bit 17 of the TTY control mask. The numbers at the left of the DDT display lines are to assist you in following the commentary that follows the display. User input is in lowercase. | | | FFiigguurree 44--11:: DDDDTT SSeessssiioonn SShhoowwiinngg CCoolluummnnaarr OOuuttppuutt | | SCREEN DISPLAY 1. DDT 2. start/ MOVE P,PWORD x$: .$b $g 3. $1B>>START/ MOVE P,PWORD $x 4. P/ -10,,STACK PWORD/ -10,,STACK 5. START+1/ MOVEI IDX,TABLE1 $x 6. IDX/ TABLE1 TABLE1 $1m/ 2 1,,2 7. start$g 8. $1B>>START/ MOVE P,PWORD $x 9. P/ -10,,STACK PWORD/ -10,,STACK 10. START+1/ MOVEI IDX,TABLE1 $x 11. IDX/ TABLE1 TABLE1 COMMENTARY Line 1: o DDT is loaded and waiting for a command. Line 2: o Enter s_t_a_r_t_/_ to examine location start. o Enter x_<_E_S_C_>_:_ to open the symbol table for module X. o Enter ._<_E_S_C_>_b_ to set breakpoint at location S_T_A_R_T_. o Enter <_E_S_C_>_g_ to begin execution. 4-25 DDIISSPPLLAAYYIINNGG AANNDD MMOODDIIFFYYIINNGG MMEEMMOORRYY Line 3: o DDT displays breakpoint information. o Enter <_E_S_C_>_x_ to execute the next instruction. Line 4: o DDT displays results of executing the instruction. Line 5: o DDT displays the next instruction. o Enter <_E_S_C_>_x_ to execute the instruction. Line 6: o DDT displays the results of executing the instruction. o Enter <_E_S_C_>_1_m_/_ to display and open the TTY control mask. o DDT displays the mask. Bit 34 is set. o Enter 1_,_,_2_<_R_E_T_>_ to set bits 17 and 34. Line 7: o Enter s_t_a_r_t_<_E_S_C_>_g_ to restart the program. Line 8: o DDT displays the breakpoint information. o Enter <_E_S_C_>_x_ to execute the instruction. Line 9: o DDT displays the results of executing the instruction. Line 10: o DDT displays the next instruction. o Enter <_E_S_C_>_x_ to execute the next instruction. Line 11: o DDT displays the results of executing the instruction. 4-26 CCHHAAPPTTEERR 55 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN 55..11 BBEEGGIINNNNIINNGG EEXXEECCUUTTIIOONN To begin execution of your program, enter: G Your program will run, beginning at its start address. If you have not set any breakpoints, your program runs to completion, or until it makes a fatal error. At TOPS-20 command level, you can then use the D_D_T_ command to reenter DDT and examine your program. You can start or continue program execution at any address with the command: addrG 55..22 UUSSIINNGG BBRREEAAKKPPOOIINNTTSS A b_r_e_a_k_p_o_i_n_t_ is a program location that has been altered such that if your program PC reaches the address of the breakpoint, your program transfers control to DDT. When you set a breakpoint with DDT, DDT stores the address of the breakpoint in an internal table. When you command DDT to begin or continue program execution, DDT stores the instructions from all breakpoints in the table, and replaces them with JSRs into a DDT entry table. While program execution is suspended at a breakpoint, you can examine and modify memory, remove breakpoints, insert new breakpoints, execute individual instructions, and continue program execution. 5-1 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN During this time, the command "." returns the value that is the address of the next instruction to be executed. The command "." returns a value that is the previous value returned by ".". When you first receive control at the breakpoint, "." returns the address of the breakpoint and "." returns zero. Before you start execution with G, "." and "." are illegal commands (if you try to execute them, DDT sounds the terminal buzzer or bell and displays a question mark). NOTE This manual uses the term "$." to represent the value returned by the command ".", and the term "$$." to represent the value returned by the command ".". You can set up to 12 breakpoints at a time (this is a DDT assembly parameter) in your program. These breakpoints are numbered 1 through 12. There is also one breakpoint (the u_n_s_o_l_i_c_i_t_e_d_ b_r_e_a_k_p_o_i_n_t_, numbered zero) that can be used by your MACRO program to "call" DDT. Each breakpoint has several internal DDT locations associated with it, which contain information to control DDT action with respect to the breakpoint. You can examine and modify these DDT locations with the same DDT commands that you use to examine and modify locations in your user program. nB is a command that returns the value that is the address of the first DDT word associated with breakpoint n. The symbol $nB is used here to represent that address. Table 5-1 contains a list of the breakpoint locations of interest to the user, and their contents. TTaabbllee 55--11:: BBrreeaakkppooiinntt LLooccaattiioonnss ooff IInntteerreesstt LLOOCCAATTIIOONN CCOONNTTEENNTTSS $nB Address of breakpoint n. $nB+1 Instruction for conditional breakpoint n. $nB+2 Proceed count for conditional breakpoint n. $nB+3 Address of a location to be opened and displayed when the breakpoint is reached. | $nB+4 Address of an ASCIZ DDT command string to be executed | when the breakpoint is reached. 5-2 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN When your user-program PC reaches a breakpoint, your program executes the JSR into DDT. When this occurs, DDT does the following: o saves your user-program context o replaces the JSR instructions at all breakpoints with the original program instructions o displays the breakpoint number, breakpoint address, and the contents of the breakpoint (depending on bit 16 of the TTY control mask) o sets "$." to the breakpoint address o sets "$$." to zero o enters the address of the current location (set before you started the program or proceeded from a breakpoint) on the location sequence stack o changes the current location to the breakpoint o waits for you to give a DDT command When you command DDT to restart or continue program execution, DDT does the following: o saves the program instructions from all breakpoints o replaces the program instructions at all breakpoints with JSR instructions to DDT o if you have not executed the instruction at the breakpoint with X, DDT simulates execution of the instruction at the breakpoint o restores your user-program context o DDT performs a JRSTF (if in section zero, otherwise XJRSTF) to the next instruction to be executed 55..22..11 SSeettttiinngg BBrreeaakkppooiinnttss To s_e_t_ a_ b_r_e_a_k_p_o_i_n_t_, enter: addr{n}B where addr is the address where you want to suspend execution (addr can be ".", the command that returns the address of the current location), and n is the number of the breakpoint (and defaults to the lowest unused breakpoint number). 5-3 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN If you do not specify n, it defaults to the lowest available (unset) breakpoint. If you have already set twelve breakpoints, DDT displays "?" and sounds the terminal buzzer or bell. If you specify n, it must be greater than zero and less than 13. DDT restores the original contents of any (previously set) breakpoint designated as breakpoint n before setting new breakpoint n. You cannot set more than one breakpoint at the same address. DDT simply sets the same breakpoint again, even if you explicitly specify a breakpoint number the second time. You cannot set a breakpoint at AC zero. Assume the following conditions: o location LABL1+3 contains the instruction MOVE 1,LABL2 o breakpoint 2 is set at LABL1+3 If your program reaches LABL1+3 it executes the JSR to DDT, and DDT does the following: o saves your user-program context o restores the original program instructions to the breakpoints o sets "$." to LABL1+3 o sets "$$." to zero o enters the address of the current location on the location sequence stack o changes the current location to LABL1+3 (the breakpoint) o opens location LABL1+3 o displays: $2B>>LABL1+3/ MOVE 1,LABL2 To s_e_t_ a_ b_r_e_a_k_p_o_i_n_t_ a_n_d_ h_a_v_e_ D_D_T_ d_i_s_p_l_a_y_ a_n_ a_d_d_i_t_i_o_n_a_l_ l_o_c_a_t_i_o_n_ when your program reaches the breakpoint, enter: addr1{n}B where addr1 is the location to be displayed, and addr2 is the location of the breakpoint. Follow addr1 with a left angle bracket (<). 5-4 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN Assume the following conditions: o location LABL1+3 contains the instruction MOVE 1,LABL2 o location LABL3 contains value SYMBL1 o breakpoint 2 was set by the command: LABL3B If your program reaches LABL1+3 it executes the JSR to DDT, and DDT does the following: o saves your user-program context o restores the original program instructions to the breakpoints o sets "$." to LABL1+3 o sets "$$." to zero o enters the address of the current location on the location sequence stack o changes the current location to LABL1+3 (the breakpoint) o enters the address of the current location (the breakpoint) on the location sequence stack o changes the current location to LABL3 o opens location LABL3 o displays: $2B>>LABL1+3/ MOVE 1,LABL2 LABL3/ SYMBL1 Note that, because DDT placed the breakpoint address on the location sequence stack, you can enter to change the current location back to the breakpoint. 5-5 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN To d_i_s_p_l_a_y_ t_h_e_ a_d_d_r_e_s_s_ of any breakpoint, enter: nB/ where n is the address of the breakpoint. DDT displays the address of breakpoint n, and you can use the examine commands to open and display the instruction at breakpoint n. If breakpoint n is not set, DDT displays zero. To r_e_m_o_v_e_ b_r_e_a_k_p_o_i_n_t_ n, enter: 0nB To remove all breakpoints, enter: B 55..22..22 PPrroocceeeeddiinngg ffrroomm BBrreeaakkppooiinnttss After your program has reached a breakpoint, you can continue execution at "$." by entering: P DDT saves the program instructions from all breakpoints, replaces the program instructions with JSRs to DDT, restores your user-program context, and if you have not executed any program instructions with the X command, simulates execution of the instruction at the breakpoint. DDT then executes a JRSTF (in section zero, otherwise DDT executes an XJRSTF) to the next instruction to be executed. You can cause the program to start execution at a different location with the {addr}G command, where a_d_d_r_ defaults to the program's start address. 5-6 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN Once your program has reached a breakpoint and DDT has interrupted execution, you can cause DDT to continue execution but NOT stop at that breakpoint until your program has reached that breakpoint a specified number of times. To do this, enter: exprP where e_x_p_r_ is the proceed count. DDT places expr at location $nB+2, where n is the number of the breakpoint at which your program has stopped. DDT resumes execution of your program. Each time your program reaches breakpoint n, DDT decrements the proceed count stored at $nB+2. Your program continues execution until: o it reaches a different breakpoint o it terminates normally o it commits a fatal error o the proceed count reaches zero Each breakpoint has an associated a_u_t_o_m_a_t_i_c_ p_r_o_c_e_e_d_ f_l_a_g_. If this flag is set and the program reaches the breakpoint, DDT decrements the proceed count at $nB+2 (where n is the number of the breakpoint) and displays the breakpoint information if the proceed count is less than one. DDT then automatically continues program execution. The P command r_e_s_e_t_s_ (clears) the automatic proceed flag associated with the breakpoint at which DDT has suspended program execution. To s_e_t_ a_ b_r_e_a_k_p_o_i_n_t_ a_n_d_ s_e_t_ t_h_e_ a_s_s_o_c_i_a_t_e_d_ a_u_t_o_m_a_t_i_c_ p_r_o_c_e_e_d_ f_l_a_g_, enter: {addr1<}addr2{n}B where addr2 is the address of the breakpoint and may be ".", addr1 is an (optional) additional location to be displayed, and n is optional and defaults to the lowest unused breakpoint. Each time your program reaches breakpoint n, DDT decrements the associated proceed count, and if the result is less than one, displays: $nB>>addr2/ instr where n is the breakpoint number, addr2 is the address of the breakpoint, and instr is the contents of the word at addr2. 5-7 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN If you entered a_d_d_r_1_<_ when you gave the command, DDT displays: $nB>>addr2/ instr addr1/ contents where n is the breakpoint number, addr2 is the address of the breakpoint, instr is the contents of the word at addr2, addr1 is the additional location to be displayed, and c_o_n_t_e_n_t_s_ is the contents of the word at addr1. DDT then automatically continues program execution until: o your program reaches a different breakpoint o your program terminates normally o your program commits a fatal error o you enter any character while your program is at breakpoint n You can interrupt the automatic proceed function if you enter a character while your program is at breakpoint n. DDT then resets the automatic proceed flag and suspends program execution at the breakpoint. DDT echoes the character that you entered, which is otherwise ignored. To p_r_o_c_e_e_d_ f_r_o_m_ a_ b_r_e_a_k_p_o_i_n_t_ a_n_d_ s_e_t_ t_h_e_ a_s_s_o_c_i_a_t_e_d_ a_u_t_o_m_a_t_i_c_ p_r_o_c_e_e_d_ f_l_a_g_, give the command: {expr}P where expr is the proceed count. DDT stores the proceed count at $nB+2. 5-8 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN 55..22..33 CCoonnddiittiioonnaall BBrreeaakkppooiinnttss To cause DDT to interrupt program execution at a breakpoint only if a specific condition is satisfied, you must store a single test instruction or a call to a test routine in DDT's breakpoint table. You can use a test routine in your program, or one that you enter in DDT's patching area. See Chapter 8 (Inserting Patches with DDT) for more information about the patching area. To enter the test instruction (or the call to the test routine), open the DDT location addressed by the command nB+1 by entering: nB+1/ where n is the number of the breakpoint. You must enter n, or DDT interprets the command as B, and removes all breakpoints. | Deposit the test instruction or the call to the test subroutine. If | your program reaches breakpoint n, DDT executes the instruction at $nB+1. DDT then proceeds as follows: o If the instruction does not cause a program counter skip, DDT decrements the proceed count at $nB+2. If the result is zero or less, DDT interrupts execution at breakpoint n. o If a program counter skip of 1 does occur, DDT interrupts execution at breakpoint n. o If the conditional instruction is a call to a subroutine that returns by skipping over two or more instructions, DDT does not interrupt program execution. If DDT interrupts execution because the test instruction resulted in a program counter skip, DDT displays only one angle bracket after the breakpoint identification, as: $3B>LABL1/ MOVE 1,LABL2 5-9 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN 55..22..44 TThhee ""UUnnssoolliicciitteedd"" BBrreeaakkppooiinntt You can cause your MACRO program to "call" DDT by inserting the following instruction in your program: JSR $0BPT## The two pound-signs (##) appended to $0BPT in your MACRO program declare the symbol as EXTERNAL. NOTE "$" represents the dollar sign character, which is part of the symbol, and is not the DDT echo of the ESCAPE key. You must load RDDT.REL with your program or you will get a LINK error (?LNKUGS undefined global symbol) when you load your program. Load RDDT.REL with your program as follows (your input is in lowercase; the last line indicates that DDT is loaded and ready to accept your commands): | @link | */debug filnam/go | DDT | | where f_i_l_n_a_m_ is the name of your MACRO-20 program. You can start your | program running with the G command. If your program executes the | JSR instruction, DDT interrupts program execution and displays: $0B>>addr+1/ instr where a_d_d_r_+_1_ is the first location a_f_t_e_r_ the J_S_R_ $_0_B_P_T_ instruction, and i_n_s_t_r_ is the contents of that location. 5-10 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN 55..33 EEXXEECCUUTTIINNGG EEXXPPLLIICCIITT IINNSSTTRRUUCCTTIIOONNSS To execute a specific instruction, enter the instruction followed by X: instrX For example: MOVE 1,@LABL1(3)X After executing the instruction, DDT starts a new line and displays: o <> if in-line execution of instr would result in skipping no instructions. o if in-line execution of instr would result in skipping 1 instruction. o if in-line execution of instr would result in skipping 2 instructions. o if in-line execution of instr would result in skipping 3 instructions. NOTE "In-line execution" means execution of the instruction as part of normal program flow. The execution of instructions with this command has no effect on your user-program PC. This command restores the prevailing display mode. 55..44 SSIINNGGLLEE--SSTTEEPPPPIINNGG IINNSSTTRRUUCCTTIIOONNSS After your program has transferred control to DDT from a breakpoint, you can execute program instructions one at a time. This is called "single-stepping." "." is a command that returns the address of the next instruction to be executed. To execute the instruction whose address is returned by ".", enter: X 5-11 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN For example, breakpoint 3 is set at LABL1+3. If your program PC reaches LABL1+3, control passes to DDT, which displays: $3B>>LABL1+3/ ADD 1,LABL2(2) Examining the environment, you learn the following: o AC 1 contains 1 o AC 2 contains 3 o LABL1+4 contains MOVEM 1,@LABL2(3) o LABL2+3 contains SYM3 as shown by the following terminal display (DDT does not display or ): $3B>>LABL1+3/ ADD 1,LABL2(2) \ SYM3 LABL1+4/ MOVEM 1,@LABL2(3) 1/ 1 2/ 3 If you now enter the command X, DDT does the following: o changes "$$." to LABL1+3 o executes the instruction at LABL1+3 o changes "$." to LABL1+4 o changes the current location to LABL1+4 o opens LABL1+4 o displays: 1/ SYM3+1 LABL2+3/ SYM3 LABL1+4/ MOVEM 1,@LABL2(3) If single-stepping an instruction results in a value of ($. minus $$.) not equal to 1, DDT also begins a new line and displays: o if ($. minus $$.) = 2 o if ($. minus $$.) = 3 o if ($. minus $$.) = 4 o if ($. minus $$.) is greater than 4 or less than 1 5-12 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN before displaying the address and contents of the next instruction to be executed. For example, the following shows a typical terminal display where you enter X to single-step the first instruction at a breakpoint (DDT echoes as $): $4B>>LABL1+5/ AOSN 3 / 0 x 3/ 1 LABL1+7/ MOVEM 1,LABL2 o 55..55 EEXXEECCUUTTIINNGG SSUUBBRROOUUTTIINNEESS AANNDD RRAANNGGEESS OOFF IINNSSTTRRUUCCTTIIOONNSS To execute a series of n instructions beginning with the instruction whose address is returned by the command ".", enter: nX where n is the number of instructions to execute. DDT then does the following for each instruction: o starts a new display line o executes the instruction o displays the address of any register or memory location referenced by the execution of the instruction, and the contents of those locations after execution of the instruction o changes the current location to the next instruction to be executed o opens the current location o displays the address and contents of the next instruction to be executed o changes "$." to the address of the next instruction to be executed o changes "$$." to the address of the instruction just executed 5-13 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN To suppress typeout of all but the last instruction executed, use the command: nX where n is the number of instructions to execute. To continue program execution until the PC (program counter) enters a range of instructions, enter: {addr1<}{addr2>}X where addr1 is the lower end of the range, and addr2 is the upper end. Addr1 defaults to 1 + "$." and addr2 defaults to addr1 + 3. Follow addr1 with a left angle bracket (<) and addr2 with a right angle bracket (>). This command also indicates skips and jumps. This command is useful for executing a loop or a subroutine call quickly and without typeout. For example, breakpoint 3 is at location LABL1. $3B>>LABL1/ PUSHJ 17,SUBRTN X ;Enter X ;SUBRTN returns + 2 LABL1+2/ ADD 1,2 If you enter a question mark (?) while DDT is executing an X command, DDT displays: Executing: addr/ instr where a_d_d_r_ is the address of the next instruction to be executed, and i_n_s_t_r_ is the instruction. To t_e_r_m_i_n_a_t_e_ t_h_e_ e_x_e_c_u_t_i_o_n_ o_f_ t_h_e_ s_e_r_i_e_s_ o_f_ i_n_s_t_r_u_c_t_i_o_n_s_, enter any character other than ? (question mark). DDT does the following: o echoes the character o displays , , , or , as appropriate o starts a new display line o changes the current location to the address of the next instruction to be executed o displays the address and contents of the current location 5-14 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN o opens the current location o waits for your next command 55..55..11 SSiinnggllee--SStteeppppiinngg ""DDaannggeerroouuss"" IInnssttrruuccttiioonnss DDT classifies the following as "dangerous" instructions: o instructions that can modify memory o instructions that can cause an arithmetic trap o instructions that can cause a stack overflow o a monitor call or I/O instruction Before single-stepping one of these instructions, DDT saves and replaces the original instructions at the breakpoints with JSRs to DDT, and restores the full user-program context (including interrupt system and terminal characteristics) before executing the instruction. After executing the instruction, DDT replaces the JSRs at the breakpoints with the original program instructions, and saves the full user-program context. DDT does not check whether the instruction actually results in one of these conditions, only whether the opcode is in the class of instructions that can cause these effects. This can make executing subroutines and ranges of instructions under DDT control extremely time-consuming. | To execute a subroutine or series of instructions without checking for | dangerous instructions, use the command: {addr1<}{addr2>}1X where addr1 is the lower end of the range, and addr2 is the upper end. Addr1 defaults to 1 + "$." and addr2 defaults to 3 + addr1. Follow addr1 with a left angle bracket (<), and addr2 with a right angle bracket (>). CAUTION This command executes much faster than X, but if the execution of an instruction causes a software interrupt, the error and trap handling mechanism may not function correctly. In addition, program instructions that change or rely on terminal or job characteristics that are also used by DDT can cause unpredictable results. 5-15 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN 55..66 UUSSEERR--PPRROOGGRRAAMM CCOONNTTEEXXTT When DDT interrupts your program's execution at a breakpoint, and after it has executed a dangerous instruction during an X or X command, it saves the user-program context. The command nI, where 0<=n<=8 (decimal), returns the address of the word that contains the information for "function" n. You can use this address to display and modify these values. Most of these values are useful only in executive mode. DDT displays the address of the word containing the information for function n as: $I+n where 1<=n<=10 (octal). If n = 0, DDT displays only $I. | Table 5-2 lists the functions. TTaabbllee 55--22:: UUsseerr--PPrrooggrraamm CCoonntteexxtt VVaalluueess FFUUNNCCTTIIOONN VVAALLUUEE 0 Executive mode CONI PI. 1 Executive mode PI channels turned off. 2 Executive mode CONI APR. 3 User PC flags. 4 User PC address. 5 EPT page address. 6 UPT page address. 7 CST base virtual address. 10 SPT base virtual address. DDT restores the user-program context whenever you execute G, P, and when you execute X, or X of dangerous instructions. 5-16 CCOONNTTRROOLLLLIINNGG PPRROOGGRRAAMM EEXXEECCUUTTIIOONN Functions 5 through 10 (octal) affect DDT's interpretation of your program's virtual address space. You can alter DDT's interpretation of your program's virtual address space with the physical and virtual addressing (nU) commands described in Chapter 11 (Physical and Virtual Addressing Commands). However, any alterations that you make do not become part of your user-program context, and do not affect TOPS-20's interpretation of your program's virtual address space. DDT also saves and restores the user-program ACs as part of the user-program context. DDT stores the contents of the ACs in an internal "register" block. Any references you make to addresses 0-17 refer to the relative locations in DDT's internal register block. These actions are totally transparent to you. 5-17 5-18 CCHHAAPPTTEERR 66 SSEEAARRCCHHIINNGG FFOORR DDAATTAA PPAATTTTEERRNNSS IINN DDDDTT With DDT you can search for memory locations that contain a specific value, and conversely, for words that do not contain a specific value. You can also set a mask to indicate to DDT that only specified bits are to be considered when performing the search. In addition, you can search for words that reference a specific address. You can specify a range within which to perform the search, or default the range to all of your program's address space. In either case, DDT compares the contents of each location within the range with the specified value. To s_e_a_r_c_h_ f_o_r_ w_o_r_d_s_ t_h_a_t_ m_a_t_c_h_ a_ s_p_e_c_i_f_i_c_ v_a_l_u_e_, enter: {addr1<}{addr2>}exprW where expr is the value for which DDT is to search, and addr1 and addr2 delimit the range in which the search is to be conducted. Follow addr1 with a left angle bracket (<) and addr2 with a right angle bracket (>). Addr1 defaults to zero and addr2 defaults to 777777 in the current section. Expr can be any legal DDT expression. DDT does the following: o compares each location (after ANDing it with the search mask) within the search range with the 36-bit value resulting from evaluating expr o starts the search by comparing the contents of addr1 with e_x_p_r_ o stops the search after comparing the contents of addr2 with e_x_p_r_ o displays (on a new line) the address and contents of each location that matches expr o enters the address of each matching location on the location sequence stack 6-1 SSEEAARRCCHHIINNGG FFOORR DDAATTAA PPAATTTTEERRNNSS IINN DDDDTT o sets the current location to addr2 o displays a blank line to indicate the search is over o restores the prevailing display mode NOTE If DDT finds more matching locations than there are words on the location sequence stack, the earlier entries are overwritten. o To s_e_a_r_c_h_ f_o_r_ w_o_r_d_s_ t_h_a_t_ d_o_ N_O_T_ m_a_t_c_h_ a_ s_p_e_c_i_f_i_e_d_ v_a_l_u_e_, enter: {addr1<}{addr2>}exprN where expr is the value which is not to be matched, and addr1 and addr2 delimit the range within which DDT is to search. Follow addr1 with a left angle bracket (<) and addr2 with a right angle bracket (>). Addr1 defaults to zero and addr2 defaults to 777777 in the current section. Expr is any legal DDT expression. NOTE When you use the DDT search functions while running FILDDT, addr2 defaults to 777777 (in the current section) unless: | | o the target is the running monitor job and you are | using physical addressing o the target is an .EXE file and you are using normal virtual addressing o the target is a disk structure or data file In these cases, addr2 defaults to the last word of the target. See Chapter 9 (FILDDT), and Chapter 11 (Physical and Virtual Addressing Commands), for more information. 6-2 SSEEAARRCCHHIINNGG FFOORR DDAATTAA PPAATTTTEERRNNSS IINN DDDDTT DDT functions as for the W command, except: o DDT searches for and displays the address and contents of any word within the address range that does NOT match the 36-bit value resulting from evaluating expr. o DDT enters the locations of non-matching words on the location sequence stack. o To s_e_a_r_c_h_ f_o_r_ r_e_f_e_r_e_n_c_e_s_ t_o_ a_n_ a_d_d_r_e_s_s_, enter: {addr1<}{addr2>}exprE where addr1 and addr2 delimit the range of the search, and expr contains the address for which DDT is to search. Follow addr1 with a left angle bracket (<) and addr2 with a right angle bracket (>). Addr1 defaults to zero and addr2 defaults to 777777 in the current section. Expr is any legal DDT expression. DDT performs an IFIW effective address calculation on the expression contained in each word within the range, and uses the 18-bit result to determine whether there is a match. Thus, if bits 14-17 (the X field of an instruction) or bit 13 (the I field of an instruction) are nonzero, indexing or indirection may result in DDT finding different search results at different times. DDT does not check whether the expression is actually an instruction before performing the effective address calculation. o If you enter a question mark (?) while DDT is performing any of the above searches, DDT displays: Searching: addr/ value where a_d_d_r_ is the address of the location that will next compare, and v_a_l_u_e_ is the contents of a_d_d_r_. To a_b_o_r_t_ t_h_e_ s_e_a_r_c_h_, enter any character other than question mark (?). DDT stops searching, and waits for more input. The character that you enter to terminate the search is otherwise ignored. | Each of the above search commands restores the prevailing display | mode. 6-3 SSEEAARRCCHHIINNGG FFOORR DDAATTAA PPAATTTTEERRNNSS IINN DDDDTT M is a command that addresses a DDT location that contains a s_e_a_r_c_h_ m_a_s_k_ used to prevent specified bits in the memory word from being considered during the search. This mask is used only by W and N, not by E. DDT logically ANDs the search mask with the memory word before making the comparison, but does not change the memory word. If DDT finds a match, it displays the entire word. DDT sets the search mask to 777777,,777777 (compare all 36 bits) by default. To set the search mask, enter: exprM where e_x_p_r_ evaluates to the required bit pattern. For example, to search for all of the RADIX50 references to MAIN. (user input is in lowercase): 5t ;Set typeout mode to RADIX50. 37777,,777777m ;Ignore the left 4 bits. main.5"w ;Enter RADIX50 symbol, start search. 4112/ 4 MAIN. ;DDT displays match found. 4775/ 0 MAIN. ;DDT displays match found. ;Search over, DDT displays blank line. You can also examine and modify the search mask with the examine and deposit commands described in Chapter 4 (Displaying and Modifying Memory). 6-4 CCHHAAPPTTEERR 77 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT 77..11 OOPPEENNIINNGG AANNDD CCLLOOSSIINNGG SSYYMMBBOOLL TTAABBLLEESS Each separate program module has its own symbol table. When displaying a value symbolically, if more than one symbol is defined with that value, DDT displays the first global symbol found. When searching for a symbol, DDT searches the "open" symbol table first. For display purposes, DDT treats local symbols found in the open symbol table as global symbols. DDT appends a pound-sign (#) to local symbol names that it finds in a symbol table that is not open. For example: SYMBL1# where SYMBL1 is a local symbol that DDT found in a symbol table that is not open. If you enter an expression that contains a symbol that is defined in more than one of your program modules, DDT uses the value of the symbol that is contained in the open symbol table. If the symbol is not defined in the open symbol table, or if there is no open module and there is not a global definition of the symbol, DDT displays: M To o_p_e_n_ t_h_e_ s_y_m_b_o_l_ t_a_b_l_e_ of a program module, enter: name: where n_a_m_e_ is the name of the program module as specified by the TITLE pseudo-op in your MACRO-10 program (or the equivalent mechanism in a higher-level language program). DDT closes any currently open symbol table and opens the symbol table associated with module n_a_m_e_. 7-1 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT To f_i_n_d_ t_h_e_ n_a_m_e_ o_f_ t_h_e_ m_o_d_u_l_e_ a_s_s_o_c_i_a_t_e_d_ w_i_t_h_ t_h_e_ o_p_e_n_ s_y_m_b_o_l_ t_a_b_l_e_, enter: 1: If there is an open symbol table, DDT displays the name of the module associated with the open symbol table. For example, if the symbol table for module X is open, the screen display is as follows (DDT echoes as $, and does not display any spaces between the command and the module name): $1:/X If there is no open symbol table, DDT displays three spaces (or a tab, depending on the TTY control mask), and waits for your next command. To c_l_o_s_e_ t_h_e_ o_p_e_n_ s_y_m_b_o_l_ t_a_b_l_e_, enter: : 77..22 DDEEFFIINNIINNGG SSYYMMBBOOLLSS To redefine a symbol or to create a new symbol in the current symbol table, enter: exprK where s_y_m_b_o_l_ is the symbol to be suppressed. DDT still accepts s_y_m_b_o_l_ as input, but no longer displays s_y_m_b_o_l_ as output. To suppress the last symbol that DDT displayed (in an address, in the contents of a memory word, or in the evaluation of an expression), enter: D DDT suppresses the last symbol displayed, and then redisplays the current quantity. DDT does not display its usual three spaces between the command and the displayed value. In the following example, assume that symbol SIZE is defined as 3. User typein is lowercase ( does not appear on the terminal screen). start/ JFCL 0 LOOP/ AOS 1 LOOP+1/ MOVE 2,1 dMOVE 2,1 START+3/ MULI 2,SIZE dMULI 2,3 To r_e_a_c_t_i_v_a_t_e_ a_ s_y_m_b_o_l_ f_o_r_ t_y_p_e_o_u_t_, redefine the symbol. For example, to reactivate the display of symbol SIZE, above, enter: sizeK DDT removes s_y_m_b_o_l_ from the symbol table, and no longer displays s_y_m_b_o_l_ or accepts s_y_m_b_o_l_ as input. 7-3 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT 77..55 CCRREEAATTIINNGG UUNNDDEEFFIINNEEDD SSYYMMBBOOLLSS It is sometimes convenient to use symbols that have not yet been defined. To create an undefined symbol, enter: symbol# where s_y_m_b_o_l_ is the undefined symbol name. DDT enters s_y_m_b_o_l_ in the undefined symbol table. When you later define the symbol, DDT enters it into the defined symbol table, removes it from the undefined symbol table, and enters the correct value in all locations where you referenced the symbol. You can use undefined symbols only as parts of expressions that you are depositing to memory. Undefined symbols can be either fullword or right-halfword values; they cannot be used as the A or X fields of an instruction, or as the left-halfword of an expression. | | | | 77..66 FFIINNDDIINNGG WWHHEERREE AA SSYYMMBBOOLL IISS DDEEFFIINNEEDD | To determine the modules in which a symbol is defined, enter: symbol? where s_y_m_b_o_l_ is the name of the symbol. DDT displays the name of each program module in which s_y_m_b_o_l_ is defined. If the symbol is a global symbol, DDT displays a "G", as: sym? MAIN. G DDT does not display G following a local symbol found in the open symbol table. When DDT has searched the entire symbol table, it displays a blank line. 7-4 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT 77..77 SSEEAARRCCHHIINNGG FFOORR SSYYMMBBOOLLSS To search for all the symbols that begin with a specific character pattern, use the command sym? where sym is the character pattern for which you are searching, and may be one to six characters long. DDT searches your symbol tables and displays all symbols that begin with that pattern. DDT also displays all modules in which the symbol is found, whether the symbol is global, and the value of the symbol. In addition, if the symbol represents a value in which only one bit is set, DDT displays the number of the bit. For example, the command fdb? might cause the following display: FDBIN INOUT G 3 FDBOUT INOUT G 2 (1B34) FDB MOD1 7 77..88 LLIISSTTIINNGG UUNNDDEEFFIINNEEDD SSYYMMBBOOLLSS To get a list of all currently undefined symbols, enter: ? DDT displays a list containing each undefined symbol. | | | | 77..99 LLIISSTTIINNGG SSYYMMBBOOLLSS | | To get a list of all symbols starting with a certain character or set | of characters, enter: | | {val1<{val2>}}{sym}{n}? | | where v_a_l_1_ and v_a_l_2_ restrict the values of symbols which DDT displays. | If only v_a_l_1_ is present, only symbols having that value are displayed. | If both v_a_l_1_ and v_a_l_2_ are present, symbols with (signed) values | between v_a_l_1_ and v_a_l_2_ inclusive are displayed. The n_ argument is an | octal mask of flags. | | If bit 35 is on, only symbols defined in the open module are | displayed. If any of bits 33-30 are on, the corresponding bit from | 0-3 must be present in the symbol's definition. Any other bits are in | error. 7-5 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT | For example, entering "4?" displays all global symbols, "1?" | displays all symbols defined in the open module, and "5<100>T5?" | displays all global symbols defined in the open module, starting with | "T", whose values are in the range of 5-100. 77..1100 LLOOCCAATTIINNGG SSYYMMBBOOLL TTAABBLLEESS WWIITTHH PPRROOGGRRAAMM DDAATTAA VVEECCTTOORRSS DDT Version 44 can access symbol tables pointed to by JOBDAT, by PDVs (program data vectors) and by values you store in DDT. The command 5M returns the address of a DDT location that contains information to direct DDT to the current symbol table. The symbol $5M refers to the memory location at the address returned by the 5M command. If the value contained in $5M is negative (bit 0 is set), the right-halfword contains the number of the section that contains the JOBDAT area. If the value contained in $5M is positive (bit zero is clear, and the value in $5M is nonzero), $5M contains the 30-bit address of the PDV currently in use by DDT. If $5M contains zero, DDT uses values (which can be stored by the user) pointed to by locations 770001 and 770002 of UDDT, to determine which symbol table(s) to use. The algorithm that DDT uses is described below. To set $5M to a PDV address, type in addr5M where addr is the the PDV address. If you know the PDV name, you can type in :/name/ where n_a_m_e_ is the name of the PDV, and the slashes (/) represent any characters that do not appear in n_a_m_e_. If n_a_m_e_ is a null string, DDT searches for a PDV with no name or a null name. DDT ignores any characters in n_a_m_e_ beyond a length of 39. DDT searches for a PDV named n_a_m_e_, and places its address in $5M. If DDT does not find the PDV, it displays ? and sounds the terminal buzzer or bell. 7-6 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT You can learn the names of the PDVs associated with your program by using the following sequence of TOPS-20 commands: @GET program-name @INFORMATION VERSION To display the name of the PDV addressed by $5M, type in 1: If $5M contains the address of a PDV, DDT displays the name of the PDV; otherwise, it does nothing. Whenever DDT is entered from its start address or from a breakpoint, if $5M is zero, DDT initializes $5M according to the following rules: o If XDDT was started by the UDDT stub, AND the location addressed by location 770001 in the stub has bit zero set: > DDT uses the location addressed by location 770001 (in the stub) as an IOWD pointer to a symbol table in the section that contains the stub. > DDT uses the location addressed by location 770002 (in the stub) as as IOWD pointer to the undefined symbol table in the section that contains the stub. o If XDDT was not started by the UDDT stub, OR the location addressed by location 770001 in the stub has bit zero clear: > If no PDVs exist, DDT sets $5M to -1,,n, where n is: * the section that contains the UDDT stub (if the stub exists) OR * the section that contains the entry vector (if an entry vector exists) OR * section zero. > If there is one (only) PDV, DDT sets $5M to the address of the PDV. 7-7 MMAANNIIPPUULLAATTIINNGG SSYYMMBBOOLLSS IINN DDDDTT > If there is more than one PDV, DDT examines word .PVSYM of each PDV in ascending memory order (DDT first looks at the PDV closest to 0,,0). DDT then sets $5M to: * the address of the first (lowest in memory) PDV that contains a .PVSYM word that contains a global address (if there is one). * the address of the first (lowest in memory) PDV that exists in or above the section containing the entry vector (if there is one). * the address of the first (lowest in memory) PDV. NOTE DDT ignores its own PDV when setting $5M. 7-8 CCHHAAPPTTEERR 88 IINNSSEERRTTIINNGG PPAATTCCHHEESS WWIITTHH DDDDTT To replace the instruction at the open location with a series of instructions and test the new instructions without reassembling your program, you can use the DDT patch function. DDT deposits (in a patching area) the replaced instruction, the new series of instructions, and one or more JUMPA instructions back to the main line of your program. DDT also deposits (in the location that contains the replaced instruction) a JUMPA instruction to the first word of the patch. To i_n_s_e_r_t_ a_ p_a_t_c_h_ t_h_a_t_ w_i_l_l_ b_e_ e_x_e_c_u_t_e_d_ b_e_f_o_r_e_ t_h_e_ i_n_s_t_r_u_c_t_i_o_n_ at the open location, enter: {expr}< where e_x_p_r_ is the start of the patching location, and defaults first to PAT.., then to PATCH. KDDT and MDDT default to FFF (an area created during the monitor build), PAT.., and PATCH, in that order. If you do not enter e_x_p_r_, and DDT finds none of the default symbols, DDT uses the value contained in JOBDAT location .JBFF as the address to begin the patch. If e_x_p_r_ is a symbol (or the default), DDT updates the symbol table when you terminate the patch, so that the symbol identifies the first word after the patch that you just terminated. o If there is no open location when you initiate the patch, DDT displays "?" and sounds the terminal buzzer or bell. NOTE If e_x_p_r_ is an AC address, or resolves to a value less than 0,,140, DDT displays "?" and sounds the terminal buzzer or bell. 8-1 IINNSSEERRTTIINNGG PPAATTCCHHEESS WWIITTHH DDDDTT When you issue a command to start a patch, DDT saves the address of the open location, closes the open location, changes the current location to the first word in the patching area, and opens that word. DDT also displays the address and contents of the first word of the patching area. For example: < PAT../ 0 You can now enter the patch, using deposit instructions (the expr format is probably most useful). DDT updates the current and open locations according to the rules for the command that you use. To t_e_r_m_i_n_a_t_e_ t_h_e_ p_a_t_c_h_, enter: {expr}{n}> where e_x_p_r_ is the last word of the patch you are entering, and n_ is the number of returns possible from execution of the patch. The default for n is 2, allowing for a return to 1 + the address of the instruction being replaced, and for a "skip return" to 2 + the address of the instruction being replaced. When you terminate the patch, DDT deposits the instruction being replaced into the first location following the current location, unless: o display is not suppressed by ! AND o the current location is zero AND o the current location is closed OR you omitted e_x_p_r_ in which case DDT deposits the instruction being replaced into the current location. This prevents the patch from containing unintended null words. DDT deposits n JUMPA instructions in the locations immediately following the one in which it deposited the original program instruction. The first JUMPA instruction has 1 in its A field, and jumps to 1 + the address of the replaced instruction, the second JUMPA instruction has 2 in its A field and jumps to 2 + the address of the replaced instruction, and so on. The AC numbers are used for identification purposes only. Any JUMPA instruction beyond the sixteenth contains 17 in its A field. DDT then changes the current location to the location that was open when you initiated the patch, deposits in the current location a JUMPA instruction to the first word of the patch that you entered, and displays the address, original contents, and new contents of the current location. The current location is "open", and can be modified by your next command. 8-2 IINNSSEERRTTIINNGG PPAATTCCHHEESS WWIITTHH DDDDTT If you default e_x_p_r_, or enter a symbol in the {expr}< command, when you terminate the patch, DDT redefines the symbol that identifies the start of the patch. If DDT used the value contained in JOBDAT location .JBFF as the address of the patching area, DDT changes the values contained in .JBFF and the left half of JOBDAT location .JBSA. In all cases, the new value is the address of the memory location after the last word of the patch. By default, there are 100 (octal) words in the patching area. DDT does not check whether your patch overflows the patching area. You can control the size of the patching area with the /PATCHSIZE switch in LINK. NOTE DDT allows you to use other DDT commands while you are in the process of entering a patch. DDT does not check whether the current and open locations are in the patching area, or whether you are entering patch instructions in sequence. When you terminate the patch, DDT deposits the instruction being replaced in the current location regardless of whether the current location is in the patching area. To i_n_s_e_r_t_ a_ p_a_t_c_h_ t_h_a_t_ w_i_l_l_ b_e_ e_x_e_c_u_t_e_d_ a_f_t_e_r_ t_h_e_ i_n_s_t_r_u_c_t_i_o_n_ at the open location, enter: {expr}< where e_x_p_r_ is the address of the patching location (PAT.. is the default). The results are the same as inserting the patch before the instruction as above, except: o When you open the patch DDT deposits the replaced instruction in the first word of the patch. o When you terminate the patch, DDT deposits the first JUMPA instruction (rather than the instruction being replaced) in the first location following the current location unless: > display is not suppressed by ! AND > the current location is zero AND > the current location is closed OR you omitted e_x_p_r_ in which case DDT deposits the first JUMPA instruction in the current location. This is to prevent the patch from containing unintended null words. 8-3 IINNSSEERRTTIINNGG PPAATTCCHHEESS WWIITTHH DDDDTT NOTE If e_x_p_r_ is an AC address, or resolves to a value less than 0,,140, DDT displays "?" and sounds the terminal buzzer or bell. Figure 8-1 illustrates the patching function. The program being patched is X.MAC (see Figure 2-1). The patch inserts a SKIPN instruction that is to be executed after the instruction at START+4. FFiigguurree 88--11:: AAnnnnoottaatteedd PPaattcchhiinngg SSeessssiioonn DDT OUTPUT USER INPUT EXPLANATION START+4/ MOVE 2(IDX) As a result of your last command, DDT displays the contents of START+4. | < Enter < to start | the patch. | | PAT../ 0 MOVE 2(IDX) DDT displays the address | and contents of the first | word of the patch area, and | deposits the instruction from | START+4 in the first word of | the patch. | | PAT..+1/ 0 DDT displays the address | and contents of the next word | of the patch area. | | pat..= Check the address of PAT.." | (the first word of the patch | area). 14432 DDT displays the current address of "PAT..". | skipn 1,02> Enter the new instruction, | and terminate the patch with | a normal return and one skip | return by entering 2>. | | PAT..+2/ 0 JUMPA 1,START+5 DDT displays the next word | of the patch area, then | deposits a JUMPA instruction | to 1 + the address of the | replaced instruction. 8-4 IINNSSEERRTTIINNGG PPAATTCCHHEESS WWIITTHH DDDDTT | FFiigguurree 88--11:: AAnnnnoottaatteedd PPaattcchhiinngg SSeessssiioonn ((CCoonntt..)) | | | DDT OUTPUT USER INPUT EXPLANATION | | PAT..+3/ 0 JUMPA 2,START+6 DDT displays the address | and contents of the next word | of the patch area, then | deposits a JUMPA instruction | to 2 + the address of the | replaced instruction. START+4/ MOVE 2(IDX) JUMPA STACK+10 DDT displays the address and original contents of the replaced instruction, then deposits and displays a JUMPA instruction to the first word of the patch. START+4 is the current location, and is "open". pat..= Check the address of the patch area. 14436 DDT updated "PAT..". Figure 8-2 shows the terminal display as it actually appears when you insert the patch described above. Your input is in lowercase. FFiigguurree 88--22:: TTeerrmmiinnaall DDiissppllaayy ooff PPaattcchhiinngg AAfftteerr aann IInnssttrruuccttiioonn | START+4/ MOVE 2(IDX) $$< | PAT../ 0 MOVE 2(IDX) | PAT..+1/ 0 pat..=14432 skipn 1,0$2> | PAT..+2/ 0 JUMPA 1,START+5 | PAT..+3/ 0 JUMPA 2,START+6 | START+4/ MOVE 2(IDX) JUMPA STACK+10 pat..=14436 | Figure 8-3 shows the terminal display when inserting the same patch | b_e_f_o_r_e_ the instruction at START+4. You enter the instruction in the | form e_x_p_r_<_L_F_>_ (user input is lowercase). Note the use of the patch termination command without e_x_p_r_ and without n_. 8-5 IINNSSEERRTTIINNGG PPAATTCCHHEESS WWIITTHH DDDDTT FFiigguurree 88--33:: TTeerrmmiinnaall DDiissppllaayy ooff PPaattcchhiinngg BBeeffoorree aann IInnssttrruuccttiioonn | START+4/ MOVE 2(IDX) $< | PAT../ 0 .=14432 skipn 1,0 | PAT..+1/ 0 $> | PAT..+1/ 0 MOVE 2(IDX) | PAT..+2/ 0 JUMPA 1,START+5 | PAT..+3/ 0 JUMPA 2,START+6 | START+4/ MOVE 2(IDX) JUMPA STACK+10 pat..=14436 To a_b_o_r_t_ t_h_e_ p_a_t_c_h_ y_o_u_ a_r_e_ e_n_t_e_r_i_n_g_, enter: 0< DDT displays 3 spaces (or a tab, depending on the TTY control mask) and changes the current location to the location that was open when you initiated the patch. The symbol that denotes the start of the patching area is unchanged. Any deposits that you made as part of the patch remain in the patching area. This allows you to restart the same patch, or to write over the patch with a new one. 8-6 CCHHAAPPTTEERR 99 FFIILLDDDDTT 99..11 IINNTTRROODDUUCCTTIIOONN FILDDT is a utility used to examine and change disk files and physical disk blocks. You can also use FILDDT to examine monitor crash dumps, and to examine the running monitor. With FILDDT, you can look at .EXE files as if they had been loaded with the monitor GET command, or as if they were binary data files. In selecting a disk file, a disk, or the monitor with FILDDT, you are really establishing the v_i_r_t_u_a_l_ a_d_d_r_e_s_s_ s_p_a_c_e_ that FILDDT accesses. When discussing the contents of that virtual address space, where the contents can be any of the above objects, this chapter uses the term t_a_r_g_e_t_. Once you have accessed a target, you can examine and modify it with the DDT examine and modify commands (you cannot modify the running monitor with FILDDT), and then save it with your modifications. You can use all of DDT's commands for examining and modifying memory, but you cannot use any commands that cause the execution of program instructions, such as X, G, and so on. If you attempt to execute a program instruction, FILDDT sounds the terminal buzzer or bell. 99..22 UUSSIINNGG FFIILLDDDDTT There are two command levels in FILDDT. This document refers to these two levels as F_I_L_D_D_T_ c_o_m_m_a_n_d_ l_e_v_e_l_ and D_D_T_ c_o_m_m_a_n_d_ l_e_v_e_l_. FILDDT command level accepts FILDDT commands to control session parameters and to select the target. FILDDT command level employs TOPS-20 command recognition and help. When at FILDDT command level, FILDDT displays the prompt: FILDDT> 9-1 FFIILLDDDDTT Once you access a target, FILDDT enters DDT command level. At DDT command level, use DDT commands to examine and modify the target. The syntax of a FILDDT command-level command is: command {file-spec{/switch...}} where c_o_m_m_a_n_d_ is a FILDDT command-level command, f_i_l_e_-_s_p_e_c_ is a TOPS-20 file specification, and s_w_i_t_c_h_ invokes a specific function or parameter about the function that you can perform (enable patching, for example). You can use FILDDT commands to invoke functions and parameters that are invoked by analogous FILDDT switches. With a FILDDT command you can: o request HELP on FILDDT o specify the target to be examined o invoke FILDDT functions o establish certain parameters about the functions that you can perform o enter DDT command level o exit FILDDT A FILDDT command can have more than one of the above effects. The commands and switches are described in detail in the rest of this chapter. To start FILDDT, enter the TOPS-20 command: FILDDT FILDDT enters FILDDT command level and prompts: FILDDT> You can now use the FILDDT commands described on the following pages. 9-2 FFIILLDDDDTT 99..22..11 FFIILLDDDDTT CCoommmmaannddss There are two classes of FILDDT-level commands; those that select the target that FILDDT is to access and those that establish what function FILDDT is to perform for the target (enable patching, extract symbols, and treat an .EXE file as data). The following are the targets (virtual address spaces) that FILDDT can access, and the commands that select them: TARGET COMMANDS Disk files GET Disk structures DRIVE, STRUCTURE The running monitor PEEK To examine and patch disk structures, you must have WHEEL, OPERATOR, or MAINTENANCE privileges enabled. To examine the running monitor, you must have WHEEL or OPERATOR privileges enabled. Following are the parameters you can invoke for the target and the commands and switches that select them: FUNCTION COMMAND SWITCH Treat file as pure binary data ENABLE DATA-FILE /DATA Enable patching ENABLE PATCHING /PATCH Enable thawed access ENABLE THAWED /THAWED Load symbol table only from file LOAD /SYMBOL To get HELP, enter: HELP FILDDT displays a very brief description of the FILDDT commands and redisplays the FILDDT> prompt. To return to TOPS-20 command level from FILDDT command level, enter: EXIT 9-3 FFIILLDDDDTT 99..22..22 SSyymmbboollss To enhance performance, FILDDT uses a symbol table that it builds in its own address space, rather than one which exists in the target address space. FILDDT automatically extracts symbols to build its internal symbol table from the first .EXE file it loads during a session. Once FILDDT has an internal symbol table, it ignores any symbols in subsequently loaded .EXE files unless you use the LOAD command or the GET command with the SYMBOL switch. 99..22..33 CCoommmmaannddss ttoo EEssttaabblliisshh FFoorrmmaattss aanndd PPaarraammeetteerrss EENNAABBLLEE DDAATTAA--FFIILLEE If you specify an .EXE file, DDT (by default) loads the file in virtual memory as if it were to be executed. You can use the ENABLE DATA-FILE command to look at an .EXE file as if it were a data file. FILDDT then loads the entire file (including the .EXE directory block) as a binary file, starting at virtual location zero. You can accomplish the same thing by appending the /DATA switch to the file-spec when you use the GET command. EENNAABBLLEE PPAATTCCHHIINNGG The ENABLE PATCHING lets you modify the target. You can also enable patching by appending the /PATCH switch to the file-spec when you use the GET command. If you do not enable patching, you can only examine the target. If you attempt to modify the target but have not enabled patching, FILDDT displays: ? Patching is not enabled Note that you cannot enable patching in FILDDT with the W command. EENNAABBLLEE TTHHAAWWEEDD The ENABLE THAWED command lets you examine and modify (if you enable patching) files that require thawed access. You can also use the /THAWED switch when loading the file with the GET command. 9-4 FFIILLDDDDTT LLOOAADD The LOAD command tells FILDDT to copy the symbol table from the file named by file-spec. Once FILDDT has built its internal symbol table, FILDDT displays: [Extracting symbols from file file-spec] [n symbols loaded from file] where n is the number of symbols that FILDDT extracted from the file. FILDDT then again prompts you with FILDDT>. You can also load symbols from the file you specify in the GET command by appending the /SYMBOL switch to the file-spec. If the file you specify is not an .EXE file, FILDDT displays: % Not in .EXE format -- Data file assumed. [Extracting symbols from file file-spec] ? Symbols cannot be extracted from a data file FILDDT then redisplays its prompt. 99..22..44 CCoommmmaannddss ttoo AAcccceessss tthhee TTaarrggeett aanndd EEnntteerr DDDDTT DDRRIIVVEE The DRIVE command allows you to access a physical structure directly. This may be useful if the home block has been damaged. To access disk structures with FILDDT, you must have WHEEL, OPERATOR, or MAINTENANCE privileges enabled. If you wish to be able to patch the disk structure, you must give the ENABLE PATCHING command before using the DRIVE command. To access the disk structure, enter: DRIVE c k u where c is the channel, k is the controller, and u is the unit, in decimal. 9-5 FFIILLDDDDTT If the unit is part of a mounted structure, FILDDT displays: [Unit is part of structure name] where n_a_m_e_ is the logical name of the disk structure. If FILDDT successfully access the unit, FILDDT enters DDT command level and displays: [Looking at unit u on controller k on channel c] where c is the channel, k is the controller, and u is the unit, in decimal. GGEETT The GET command tells FILDDT to load the file you name, invoke any parameters for which you specify switches, and enter DDT command level. Legal switches are /DATA, /PATCH, /SYMBOL, and /THAWED, and correspond to the ENABLE DATA-FILE, ENABLE PATCHING, LOAD, and ENABLE THAWED commands, respectively. If FILDDT extracts symbols and builds an internal symbol table, it displays: [Extracting symbols from file file-spec] [n symbols loaded from file] where n is the number of symbols loaded. When FILDDT has loaded the file, it displays: [Looking at file file-spec] where file-spec is the TOPS-20 file specification of the file. If FILDDT does not find the file, it displays: ? Invalid file specification, message where message is a TOPS-20 error string. 9-6 FFIILLDDDDTT PPEEEEKK Use the PEEK command to examine the running monitor. To use FILDDT to examine the running monitor, you must have WHEEL or OPERATOR privileges enabled. Once you have invoked FILDDT, if you wish to be able to use monitor symbols when looking at the running monitor, you must use the LOAD command first, as: LOAD SYSTEM:MONITR.EXE You cannot patch the running monitor with FILDDT. To examine the running monitor, enter: PEEK FILDDT displays: [Looking at running monitor] and enters DDT command level. NOTE You cannot use FILDDT to PEEK at the running monitor unless you are using normal virtual addressing. If you are PEEKing the monitor and change memory mapping to a mode other than normal virtual addressing with the n0U, n1U, n2U, or $$U commands, FILDDT does not give an error. However, every page in the monitor then appears to DDT to be non-existent. In this case, most attempts to reference memory causes DDT to display ?, sound the terminal buzzer or bell, and set the error string to "CAN'T PEEK PHYSICAL". Searches do not cause errors, but never discover matches. 9-7 FFIILLDDDDTT SSTTRRUUCCTTUURREE The STRUCTURE command allows you to access a disk structure by its logical name. To access disk structures with FILDDT, you must have WHEEL, OPERATOR, or MAINTENANCE privileges enabled. If you wish to be able to patch the disk structure, you must give the ENABLE PATCHING command before using the STRUCTURE command. To examine a disk structure, enter: STRUCTURE name where name is the logical name of the structure. If the structure contains more than one physical disk, you can access the entire logical structure. If FILDDT successfully accesses the structure, it enters DDT command level and displays: [Looking at file structure name] where n_a_m_e_ is the logical name of the structure. 99..22..55 EExxiittiinngg FFIILLDDDDTT When you are through examining and modifying the target, save the modified file by entering: FILDDT closes the file, saving any changes that you have made, and returns to FILDDT command level. Any symbol table that you have loaded (explicitly or by default) remains loaded until you specify another with the LOAD command or the /SYMBOL switch. If you have modified symbols, FILDDT also modifies the symbol table of the disk file, if one of the following occurred: o FILDDT automatically loaded the symbol table. o you loaded the symbol table and entered DDT command level by entering: GET file-spec/SYMBOL 9-8 FFIILLDDDDTT | FILDDT sometimes runs out of memory when you use the | command to save files without exiting FILDDT. If FILDDT runs out | of memory while loading a file, it displays the message: | | ? Not enough memory for file pages | | If FILDDT runs out of space while building a symbol table, it | displays the message: | | ? Not enough memory for symbols | | To reclaim all of your available memory, exit FILDDT with the | command, and then restart FILDDT with the TOPS-20 | command FILDDT. Note that this technique restores standard | virtual addressing conditions, as if you had used the U | command. See Chapter 11 (Physical and Virtual Addressing | Commands) for more information about virtual addressing | conditions. To close the file, save all modifications (as with , above) and exit from FILDDT, enter: | If you exit FILDDT by entering , changes that you make to | a disk file can still be in FILDDT's output buffer; if so, they | will NOT be saved. When you exit FILDDT, you can save FILDDT with its internal symbol table. This saves time if you often use FILDDT to debug a specific file (such as the monitor) that has a very large symbol table. Start FILDDT, load the symbol table, then exit. Use the TOPS-20 SAVE command to create a copy of FILDDT to be used with that specific file. For example (your input is in lowercase): @filddt FILDDT>load system:monitr.exe [34472 symbols loaded from file] FILDDT>exit @save FILDDT.EXE.1 Saved 9-9 10-1 CCHHAAPPTTEERR 1100 PPRRIIVVIILLEEGGEEDD MMOODDEESS OOFF DDDDTT NOTE This chapter makes no attempt to explain internal monitor mechanisms. This chapter assumes that you are aware of various monitor contexts. Certain monitor contexts may interfere with or be interfered with by DDT context switching. It is up to you to be aware of these. Note also that internal monitor locations that are used in examples in this chapter are subject to change in subsequent monitor releases. 10-1 PPRRIIVVIILLEEGGEEDD MMOODDEESS OOFF DDDDTT 1100..11 MMDDDDTT MDDT is used to debug and patch the running monitor during timesharing, and is an integral part of the swappable monitor. To run MDDT, you must have WHEEL or OPERATOR privileges enabled. To invoke MDDT, start DDT and then execute the MDDT% JSYS. For example (user input is lowercase): @enable $ddt DDT mddt%x MDDT You can also invoke MDDT by running a MACRO-20 program that executes the MDDT% JSYS. MDDT runs in the executive virtual address space of the process that executed the MDDT% JSYS. While in MDDT, you are still running in user context, you are running under timesharing, and your process is subject to being swapped out, as is any other user process. If for some reason you cannot access system files, you can enter MDDT through the MEXEC, as follows: @enable $QUIT MX>/ where the / (slash) command to MEXEC enters MDDT. To exit MDDT, enter: mretng or enter: . 10-2 PPRRIIVVIILLEEGGEEDD MMOODDEESS OOFF DDDDTT 1100..22 KKDDDDTT You can run KDDT in executive mode or in user mode. KDDT in executive mode is used to debug parts of the monitor which can not be debugged interactively such as those modules that deal with physical memory or paging. KDDT in user mode is used to debug and patch the monitor .EXE file, which you can then save for BOOTing at a later time. KDDT is part of the resident monitor. When running KDDT in executive mode, you can exercise any normal DDT functions, such as changing memory and setting breakpoints. When you stop at a breakpoint and control passes to KDDT, timesharing (if in effect) ceases. To run KDDT in executive mode use the /E command when BOOTing the monitor. For example (user input is in lowercase): BOOT>/e ;Type in /e [BOOT: LOADING] [OK] EDDT ;EDDT is loaded and waiting for your command Your debugging may be easier if you lock the swappable monitor in core. You can do this by executing the instruction that calls monitor routine SWPMLK. For example: CALL SWPMLKX To run KDDT in user mode: @get system:monitr.exe @start 140 DDT You can use KDDT in user mode to patch the monitor (.EXE file) which will be booted the next time the system is BOOTed up. After you have started KDDT as above, use the DDT patching commands to insert your patch. When your patch is complete, exit KDDT with and use the TOPS-20 SAVE command to save the patched version of the monitor. For example: < ;ESCAPE key followed by a left angle ;bracket. .... .... ;Type in the patch. > ;ESCAPE key followed by right angle ;bracket. ;Exit KDDT @save system:monitr.exe ;Save the new version. 10-3 PPRRIIVVIILLEEGGEEDD MMOODDEESS OOFF DDDDTT 1100..33 EEDDDDTT You can use EDDT to debug user programs that run in executive mode. You must load EDDT.REL with your program, as follows: @LINK SSYS:EDDT.REL,PROG/GO @SAVE PROG where PROG is the name of your MACRO-20 program. 10-4 10-5 11-1 CCHHAAPPTTEERR 1111 PPHHYYSSIICCAALL AANNDD VVIIRRTTUUAALL AADDDDRREESSSSIINNGG CCOOMMMMAANNDDSS | All TOPS-20 DDTs (including FILDDT) can do their own page mapping. | The commands described in this chapter allow you to set parameters to govern the interpretation of the address space which you are examining. You can control the mapping of the address space you are examining by choosing to use or bypass the user process table (UPT) or the executive process table (EPT). You can choose which special pages table (SPT) to use, and which hardware register block to use. Other commands allow you to emulate either KI-paging or KL-paging, control address relocation, and set memory protection limits. In each of the following commands, the argument (page, addr, n) defaults to zero. NOTE The DDT commands G, P, and X have side effects that affect your control over physical and virtual addressing. In addition to their normal functions, these commands also do the following: o restore normal virtual addressing as if U had been given (X does NOT do this) o set the FAKEAC flag (as if U had been given) o clear the relocation factor (as if 08U had been given) o reset the address-protection address to infinity (377777,,777777) o restore the active hardware register block to the one in use before any 4U command was given 11-1 PPHHYYSSIICCAALL AANNDD VVIIRRTTUUAALL AADDDDRREESSSSIINNGG CCOOMMMMAANNDDSS COMMAND EXPLANATION U This command enables memory mapping by standard TOPS-20 virtual addressing. When you give this command, DDT restores the virtual addressing conditions that were in effect before any {}nU (where 0<=n<=2) commands were given, and sets DDT's FAKEAC flag, thereby forcing DDT to interpret memory addresses 0-17 as DDT's own internal "registers", in which the user's registers were saved. U This command enables DDT to use actual physical addresses when accessing memory, and clears DDT's FAKEAC flag, causing DDT to interpret memory addresses 0-17 as the hardware registers 0-17. This command is meaningful only when using KDDT in executive mode, or when using FILDDT to look at the running monitor. Although DDT accepts U at other times, this command then produces the same effect as U. The general syntax of the following virtual addressing commands is: argnU where n is the function number of the command, and a_r_g_ is dependent on the function (see the function descriptions below). Functions 0, 1, and 2 enable you to control memory mapping by selecting the executive process table (EPT), user process table (UPT), or the section map through which mapping occurs. Setting a mapping condition with any one of these functions (0, 1, and 2) also has the effect of clearing the effects of any prior use of one of these functions (0, 1, and 2). You can also specify the offset into the special pages table (SPT) with functions 0, 1, and 2 by using the following command: argnU where arg is the SPT offset, and 0<=n<=2. This form is legal only if KL-paging is in effect. NOTE All forms of B and X are illegal if you have used the page mapping functions (0, 1, or 2) and have not restored standard mapping with the U command. 11-2 PPHHYYSSIICCAALL AANNDD VVIIRRTTUUAALL AADDDDRREESSSSIINNGG CCOOMMMMAANNDDSS COMMAND EXPLANATION page0U This command causes memory mapping to occur through the executive process table (EPT) that is located at physical page p_a_g_e_. offset0U This command produces the same effect as page0U (above), except that o_f_f_s_e_t_ is an offset (in words) into the SPT. page10U This command is an exception to the general syntax, and is legal only under KI-paging. You can select both the user page table (UPT) and the executive page table (EPT) with this command, where p_a_g_e_1_ is the page number of the UPT, and p_a_g_e_2_ is the page number of the EPT. Follow page1 with a left angle bracket (<). page1U This command causes memory mapping to occur through the user process table (UPT) that is located at physical page p_a_g_e_. With this command, you can bypass the EPT. offset1U This command produces the same effect as page1U (above), except that o_f_f_s_e_t_ is an offset (in words) into the SPT. page2U This command causes mapping to occur through the section map at physical page p_a_g_e_. This command is legal only if KL-paging is in effect. offset2U This command produces the same effect as page2U (above), except that o_f_f_s_e_t_ is an offset (in words) into the SPT. This command is legal only if KL-paging is in effect. 11-3 PPHHYYSSIICCAALL AANNDD VVIIRRTTUUAALL AADDDDRREESSSSIINNGG CCOOMMMMAANNDDSS COMMAND EXPLANATION n3U This command determines whether DDT interprets references to memory locations 0-17 as references to hardware registers, or to DDT's own internal "registers" (which normally contain the user-program ACs), by setting or resetting DDT's FAKEAC flag. If n=0, reset FAKEAC flag (use the hardware registers 0-17). If n is nonzero, set FAKEAC flag (use DDT's internal registers 0-17). If you enter a nonzero value for n, DDT stores the value -1. n4U This command tells DDT to copy hardware register block n (0<=n<=7) to its own internal register block, set the FAKEAC flag, and use hardware register block n as its own registers. If the FAKEAC flag is set when you give this command, DDT first restores the contents of its internal register block to the hardware register block from which they were copied. This command is legal in executive mode EDDT and KDDT only. Note that the microcode uses register block 7, and any attempt to use this block produces an almost immediate system crash. addr5U This command copies the 20 (octal) word block located at a_d_d_r_ to DDT's internal "registers" and sets the FAKEAC flag. addr6U This command sets the special pages table (SPT) to addr. addr7U This command sets the core status table address (CST) to addr. addr8U This command sets the address relocation factor to a_d_d_r_. DDT adds addr to all user addresses that you enter. addr9U This command read-and-write-protects all addresses above a_d_d_r_ (before adding relocation factor). 11-4 PPHHYYSSIICCAALL AANNDD VVIIRRTTUUAALL AADDDDRREESSSSIINNGG CCOOMMMMAANNDDSS COMMAND EXPLANATION n10U This command controls whether KI paging is enabled or cleared. If n is nonzero, KI paging is enabled. If n=0, KI paging is cleared. If you enter a nonzero value for n, DDT stores the value -1. | This command is illegal in executive mode EDDT. n11U This command controls whether KL paging is enabled or cleared. If n is nonzero, KL paging is enabled. If n=0, KL paging is cleared. If you enter a nonzero value for n, DDT stores the value -1. | This command is illegal in executive mode EDDT. | 22U | 23U | | These commands specify the type of CPU on which the program is | being debugged. 22U refers to a KL processor. 23U | refers to a KS processor. | | For DDT, this command is meaningless, because DDT uses the | current CPU type. However, these commands may be useful for | FILDDT. You can interrogate DDT to determine the last virtual addressing command that was given for a specific function. The command: nU where 0<=n<=11, returns the address of a DDT location that contains the argument that was given i_f_ t_h_e_ c_o_m_m_a_n_d_ f_o_r_ t_h_a_t_ f_u_n_c_t_i_o_n_ w_a_s_ u_s_e_d_, and returns the default value if that function was not used. If you entered a nonzero argument to a command that requires zero or nonzero values (or if the default is nonzero), this location contains -1. You can use DDT commands to examine this location. 11-5 PPHHYYSSIICCAALL AANNDD VVIIRRTTUUAALL AADDDDRREESSSSIINNGG CCOOMMMMAANNDDSS The command: nU where 0<=n<=2, returns the address of a DDT location that contains information that indicates which function you used, and whether you set a page address or an offset. You can use DDT commands to examine this location. This command is illegal for all functions where n>2. If you did not enter any commands affecting functions 0-2 since the last U command, the right half of this DDT location word contains zero. Otherwise, the right half contains n+1, where n is the number of the command function you used. If you set a page address (with argnU), bit 1 of this word is reset. If you set an offset (with argnU), bit 1 of the word is set. 11-6 CCHHAAPPTTEERR 1122 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG 1122..11 LLOOAADDIINNGG DDDDTT IINNTTOO AANN EEXXTTEENNDDEEDD SSEECCTTIIOONN If your program is loaded in a nonzero section, merge DDT with your program with the TOPS-20 command: @DDT DDT is loaded into the highest-numbered free (nonexistent) section. If your program has a TOPS-10-style entry vector in section zero, the EXEC merges the UDDT stub into the section that contains the entry vector, and places that section's JOBDAT symbol table pointers (.JBSYM and .JBUSY) into the DDT locations pointed to by UDDT locations 770001 and 770002. UDDT then loads XDDT into the highest-numbered free section. You can load DDT into a specific section with the EXEC's /USE-SECTION switch, as: @DDT/USE-SECTION:n where n is the (octal) section number of a section that does not already exist. You can load DDT into an existing section with the /USE-SECTION and /OVERLAY switches. You must be careful, however, that your program does not use any pages that DDT uses. See the T_O_P_S_-_2_0_ C_O_M_M_A_N_D_S_ R_E_F_E_R_E_N_C_E_ M_A_N_U_A_L_ for more information about the use of these switches. 12-1 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG 1122..22 EEXXAAMMIINNIINNGG AANNDD CCHHAANNGGIINNGG MMEEMMOORRYY The commands /, [ (left square bracket), ] (right square bracket), !, \ and (see Section 4.4.3) open a memory location at an address calculated from an expression typed in or defaulted in the command. The syntax of the command is {expr}{{}}c where c is the command, and expr is any legal DDT expression (expr defaults to $Q, the current quantity). In nonzero sections, you can cause DDT to utilize all indirection and indexing indicated by EFIWs (extended format indirect words) to calculate 30-bit global addresses by using the format {expr}c This format also recognizes and utilizes instruction format indirect words (IFIW). These commands are thoroughly described in Chapter 4 (Displaying and Modifying Memory). 1122..33 BBRREEAAKKPPOOIINNTTSS If DDT is running in a nonzero section, breakpoints can be set in any section. 1122..33..11 TThhee BBrreeaakkppooiinntt BBlloocckk To set breakpoints in a section external to the one containing DDT, DDT requires an area of contiguous storage in the section containing the breakpoint. This area is known as the "breakpoint block". The extra storage is required for saving global addresses for transfer of control between your program and DDT, and also for the execution of single-stepped instructions that reference memory locations that are not in their section. Each section within your program space that contains a breakpoint must have one breakpoint block. Breakpoint blocks are located at the same relative local address within each section (the default is 777700), and are 100 (octal) words in size. Each breakpoint block is always contiguous within one section. Breakpoint blocks never extend across section boundaries and never "wrap around" the end of a section to the beginning of the section. 12-2 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG DDT creates a breakpoint block in each section as required, if inter-section breakpoints are enabled (see below). You (or your program) can reference memory within a breakpoint block, but any information stored there can be overwritten by DDT. 1122..33..22 EEnnaabblliinngg aanndd DDiissaabblliinngg IInntteerr--sseeccttiioonn BBrreeaakkppooiinnttss The section-relative (18-bit) address of the breakpoint block(s) is stored in an internal DDT location. The command 4M returns the address of that DDT location. The symbol $4M refers to the DDT location at the address returned by 4M. Inter-section breakpoints are enabled as long as $4M contains the address of the breakpoint block. At startup, DDT enables inter-section breakpoints by default. To change the address of the breakpoint block, enter: n4M where n is the address of the breakpoint block, and can be any legal DDT expression (20<=n<=777700). DDT uses only the right half of n, and changes only the right half of the DDT location at $4M. By default, the section-relative breakpoint block address is 777700, placing the breakpoint block at the top of the section. To display the address of the breakpoint block, enter: 4M/ Inter-section breakpoints are disabled when $4M contains zero. NOTE In MDDT, $4M defaults to MDDBLK. In KDDT, $4M defaults to EDDBLK. Each symbol denotes the start of a 100-word (octal) block contained in page zero of the monitor. Page zero of the monitor is mapped into every section that contains monitor code. To d_i_s_a_b_l_e_ i_n_t_e_r_-_s_e_c_t_i_o_n_ b_r_e_a_k_p_o_i_n_t_s_, enter: 04M 12-3 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG While inter-section breakpoints are disabled, you cannot set a breakpoint in a section external to DDT, and any breakpoints already set in such a section are lost when you begin program execution with G, or continue program execution with P. For each breakpoint lost, DDT displays: % CAN'T INSERT $nB - IN NON-DDT SECTION where n is the breakpoint number. While inter-section breakpoints are disabled, DDT cannot execute the X command when: o you try to execute the instrX command, and the default section is not the section that contains DDT. o you try to single-step a dangerous instruction and the user-program PC is not in the section that contains DDT. | In these cases, when you try to use X, DDT rings the terminal | bell or buzzer and sets its error message text to: | | Intersection reference and no $4M global breakpoint/execute block 1122..44 DDIISSPPLLAAYYIINNGG SSYYMMBBOOLLSS IINN NNOONNZZEERROO SSEECCTTIIOONNSS DDT normally uses right-halfword values when searching symbol tables for symbols to display. However, code linked in a nonzero section has symbols defined with the section number in the left-halfword. DDT uses a 30-bit value when searching for a symbol in the following circumstances: o when displaying the address of a location o when displaying the contents of a location as an address o when displaying the Y field of an instruction When displaying an address, DDT searches for a symbol defined with the 30-bit value of the address. If such a symbol is not found, DDT displays the address in halfword format. When displaying the Y field of an instruction, DDT searches for a symbol defined with a 30-bit value consisting of: o the section number of the address of the word being displayed o the section-relative address contained in the Y field of the instruction 12-4 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG If DDT does not find a symbol defined with that 30-bit value, it looks for a symbol defined with the 18-bit value contained in the Y field of the instruction. Assume a program with the following conditions: Symbol LABL1 is defined as 0,,300 Symbol LABL2 is defined as 3,,300 Location 1,,300 contains 3,,300 Location 1,,301 contains 2,,300 Location 3,,400 contains 200040,,300 (MOVE contents of location 300 to AC 1) When displaying the contents of location 1,,300, DDT displays: 1,,LABL1/ LABL2 When displaying the contents of location 1,,301, DDT displays: 1,,LABL1+1/ 2,,LABL1 When displaying the contents of location 3,,400, DDT displays: LABL2+100/ MOVE 1,LABL2 1122..55 DDEEFFAAUULLTT SSEECCTTIIOONN NNUUMMBBEERRSS To reduce the need to type in the section number as part of the address when you specify a location, DDT uses a default section number when you do not specify one. DDT has two section defaulting options: o permanent default section o floating default section The command 6M returns the address of an internal DDT location that contains section default information. The symbol $6M refers to the DDT location at the address returned by the command 6M. When DDT is in section zero, the default section number is always zero, regardless of the contents of $6M. NOTE When you use KDDT in user-mode, $6M defaults to 0,,0. In all other cases, $6M defaults to 1,,0. 12-5 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG 1122..55..11 PPeerrmmaanneenntt DDeeffaauulltt SSeeccttiioonn | If the value contained in $6M is non-negative (bit zero is reset), the permanent default section option is in effect. DDT then takes the left half of $6M as the section number of any address that you type in without a section number. Set the permanent default section by entering: n,,06M where n is the section number, and can be any legal DDT expression. 1122..55..22 FFllooaattiinngg DDeeffaauulltt SSeeccttiioonn If the value contained in $6M is negative (bit zero is set), the floating default section option is in effect. This is the default option (at start-up, DDT initializes $6M to -1). DDT selects the floating default section as follows: o If you enter DDT from its normal start address, DDT sets the default section to: > the section that contains the program entry vector (if there is one) OR > section zero. o If you enter DDT from a breakpoint, DDT sets the default section to the section that contains the breakpoint. o If you open a local address between 20 and 777777, DDT sets the default section to the section that contains the open address. o If you type in an address that contains a section number (including a symbol that is defined with a section number), DDT sets the default section to the one in the address you entered. If you exit DDT with or , and then reenter DDT, the current location does not change. If you give a command that takes the current location as its default address argument, DDT sets the floating default section to the section of the current location. In the following example, the DDT screen display is on the left, and explanatory comments are on the right. The entry vector is in section 1. Symbol START is not defined with a section number. User input is in lowercase. 12-6 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG SSCCRREEEENN DDIISSPPLLAAYY UUSSEERR IINNPPUUTT EEXXPPLLAANNAATTIIOONN 3,,place/ Examine location 3,,PLACE. LABL1 DDT displays the contents. Type in to examine the next location. 3,,PLACE+1/ LABL1+2 DDT displays the next location. The floating default section = 3. Exit with . The current location is 3,,PLACE+1. @ TOPS-20 prompts you. @ddt Reenter DDT. DDT DDT is loaded and ready for your command. The floating default section is 1, because the entry vector is in section 1. Type in to examine the next location. 3,,START+2/ LABL1+4 DDT displays the address and contents of the next location. DDT doesn't use the floating default section, because your command defaults addr to the current location, and uses its section number (3). start/ Examine location START. DDT uses the floating default section number because symbol START is defined with no section number. JFCL 0 DDT displays the contents. Type in to examine the next location. 1,,START+1/ MOVE 1,LABL1 DDT displays the address and contents of the location. 12-7 EEXXTTEENNDDEEDD AADDDDRREESSSSIINNGG 1122..66 EEXXEECCUUTTIINNGG SSIINNGGLLEE IINNSSTTRRUUCCTTIIOONNSS Instructions that are executed by means of the command instrX where instr is the instruction for DDT to execute, are executed within the current default section. If that section is not the one that contains DDT, DDT uses the breakpoint block in that section to execute instr. If the floating default section option is in effect and you are unsure of the current default section, use the addr/ command to open a location in the section in which you wish DDT to execute instr. This sets the default section to the section specified by addr. If DDT is to execute the instruction in a section other than the one that contains DDT, inter-section breakpoints must be enabled. If you try to execute instr outside DDT's section while intersection breakpoints are disabled, DDT sounds the terminal buzzer or bell, displays "?" and sets its error string to: | Intersection reference and no $4M global breakpoint/execute block 1122..77 EENNTTEERRIINNGG PPAATTCCHHEESS IINN EEXXTTEENNDDEEDD SSEECCTTIIOONNSS You cannot enter a patch if a patching area does not exist in the section that contains the word to be replaced. To ensure that there is a patching area for each section that contains user-program code, do one of the following: o reserve the same part of each section for patches, and define the patch symbol as 0,,addr, where addr is the local address of the patching area o use only one patching area and map it into all the sections that contain user-program code. Define the patch symbol as 0,,addr, where addr is the local address of the patching area. o define a different symbol for each section's patching area, and use the symbol appropriate to the section being patched If the left half of expr is zero, DDT defaults the section to the section that contains the open location. If the left half of expr is a value that is not the section that contains the open location, DDT displays: ?CAN'T PATCH ACROSS SECTIONS 12-8 AAPPPPEENNDDIIXX AA EERRRROORR MMEESSSSAAGGEESS DDT and FILDDT display error messages to indicate the results of your commands. DDT sometimes (and FILDDT usually) displays these messages on the screen, and at other times displays only a question mark. When only a question mark is displayed, a location internal to DDT usually points to a text string that is the error message. To display the error message, enter the command: ? o Following is a list of DDT messages together with explanations of what the messages indicate. ? ABOVE PROTECTION REGISTER LIMIT The address of the location you tried to display or modify is above the protection register limit, which is set by n9U. ? ACTUAL REFERENCE FAILED A memory reference failed unexpectedly (the page exists and is readable, but the reference failed anyway). ? ADDRESS GREATER THAN 777777 An address to be mapped through a section table has a nonzero section number. This can occur only if you specified a section table with the n{}2U command. A-1 EERRRROORR MMEESSSSAAGGEESS | ? ADDRESS BEYOND END OF PHYSICAL MEM | | You attempted to examine a physical memory location beyond the | end of physical memory. This error occurs only if you have used | the U command to enable physical addressing. ? Bad format for .EXE file You specified a file that appears to have an .EXE directory, but the directory is badly formatted or DDT cannot read it because of some other reason. ? BAD $4M VALUE You used the n4M command where 777700{}nU command, where 0<=n<=2. ? CAN'T BE WRITE ENABLED Even though you have automatic write-enable turned on, DDT is unable to write-enable a page that exists and is write-protected. ? CAN'T CREATE PAGE DDT attempted to create a page and failed, or else cannot attempt to create the page (see the 1W command). ? CAN'T DEPOSIT INTO SYMBOL TABLE BECAUSE ..... You tried to define or kill a symbol, but DDT was unable to modify the symbol table. Look up the second part of the error message in this appendix. ? CAN'T DEPOSIT INTO SYMBOL TABLE BECAUSE DEPOSIT FAILED You tried to define or kill a symbol, but DDT was unable to modify the symbol table, and cannot identify the specific reason. A-2 EERRRROORR MMEESSSSAAGGEESS % CAN'T INSERT $nB BECAUSE ..... DDT is not able to access the location where you inserted your breakpoint. Look up the second part of the error message in this appendix. This situation occurs before DDT tries to execute G, P, X, or X. % CAN'T INSERT $nB BECAUSE BREAKPOINT IS IN DIFFERENT SECTION DDT is not able to access the location where you inserted your breakpoint because inter-section breakpoints are not enabled (4M contains zero). This error occurs before DDT tries to execute G, P, X, or X. To enable inter-section breakpoints, deposit the breakpoint block address in the location addressed by the command 4M. % CAN'T INSERT $nB BECAUSE MEM REF FAILED DDT is not able to access the location where you inserted your breakpoint. DDT is not able to identify the reason. This occurs before DDT tries to execute G, P, X, or X. A typical occurrence is when you have a breakpoint set in the swappable monitor (set in KDDT in executive mode), but the swappable monitor is not locked in memory. ? CAN'T PATCH ACROSS SECTIONS You tried to insert a patch in a section other than the one that contains the patching area. ? CAN'T PEEK PHYSICAL You attempted to PEEK at the monitor but have specified other than normal virtual addressing (FILDDT only). % CAN'T REMOVE $nB BECAUSE ..... DDT is not able to access the location where you inserted your breakpoint. Look up the second part of the error message in this appendix. This error occurs when your program enters DDT from a breakpoint. A-3 EERRRROORR MMEESSSSAAGGEESS % CAN'T REMOVE $nB BECAUSE BREAKPOINT IS IN DIFFERENT SECTION DDT is not able to access the location where you inserted your breakpoint. because inter-section breakpoints are not enabled (4M contains zero). This error occurs when your program enters DDT from a breakpoint. To enable inter-section breakpoints, deposit the breakpoint block address in the location addressed by the command 4M. % CAN'T REMOVE $nB BECAUSE MEM REF FAILED DDT is not able to access the location where you inserted your breakpoint. DDT is not able to identify the reason. This error occurs when your program enters DDT from a breakpoint. A typical occurrence is when you have a breakpoint set in the swappable monitor (set in KDDT in executive mode), but the swappable monitor is not locked in memory. % CAN'T SET BREAKPOINT, $4M NOT SET You attempted to set a breakpoint in a section other than the one containing DDT while inter-section breakpoints were not enabled. | ? FAILURE ON SWITCHING ADDRESS SPACE | | EDDT (Executive mode EDDT only) encountered an error while trying | to access the virtual address space where monitor symbols are | kept. ? Garbage at end-of-command FILDDT encountered extra text at a place in the command where there should have been only . | | | Intersection reference and no $4M global breakpoint/execute block | | Inter-section breakpoints are not enabled, and one of the | following is true: | | o you tried to execute the command instrX but the default | section is not the section that contains DDT. | | o you tried to single-step a dangerous instruction but the | user-program PC is not in the section that contains DDT. A-4 EERRRROORR MMEESSSSAAGGEESS ? I/O error Some kind of I/O error occurred when FILDDT attempted to read or write to the unit specified in a DRIVE or STRUCTURE command. ? Illegal channel number You entered a DRIVE command that contained an illegal channel number. ? Illegal controller number You entered a DRIVE command that contained an illegal controller number. ? Illegal unit number You entered a DRIVE command that contained an illegal unit number. ? Incorrect symbol table pointer FILDDT is unable to read the symbol table specified by the symbol table pointer in the file. ? Input device must be a disk The device you specified is not a disk. ? Insufficient memory to read EXE file directory FILDDT does not have enough free memory to read in the directory section of the .EXE file that you specified. A-5 EERRRROORR MMEESSSSAAGGEESS ? Insufficient memory to read PDV list FILDDT does not have enough free memory to read in the list of PDVs in the .EXE file that you specified. NOTE FILDDT sometimes runs out of memory when you use the command to save files without exiting FILDDT. If this is the case, exit with the command, and then restart FILDDT with the TOPS-20 FILDDT command. ? INVALID DDT INTERNAL ADDRESS You addressed an internal location that is not defined. This is most likely to occur after you use a command that returns a value (such as M) to examine a DDT location and then use or to look at nearby memory. ? Invalid file specification, message where message is a TOPS-20 error string. FILDDT could not parse a filespec given to a LOAD or GET command. ? Invalid guide phrase input where input is a guide (or noise) phrase that you typed in, and does not match FILDDT's guide phrase. M You entered a symbol that is defined in more than one module. You can select the correct symbol by opening the symbol table associated with that module, using the command m_o_d_u_l_e_<_E_S_C_>_:_. ? MDDT BREAKPOINT BLOCK ALREADY IN USE Only one fork may have breakpoints set in MDDT at one time. You attempted to set a breakpoint in MDDT while another fork had already set an MDDT breakpoint. A-6 EERRRROORR MMEESSSSAAGGEESS ? Missing or extra units in structure The number of units with the name supplied in a STRUCTURE command does not agree with the number of units in the first structure with that name returned by MSTR%. ? No keyword input where input is a word that you typed in. You entered ENABLE without the DATA, PATCHING, or THAWED qualifier. ? NO READ ACCESS You tried to display a word in a page to which you do not have read access. ? No such command as input where input is a word that you typed in. You entered a command that FILDDT does not recognize. ? No such file structure COMND% and DEVST% think you supplied a disk name in a STRUCTURE command, but no unit with that name was returned by MSTR%. ? Not enough memory for file pages FILDDT does not have enough free memory for its file page buffers. NOTE FILDDT sometimes runs out of memory when you use the command to save files without exiting FILDDT. If this is the case, exit with the command, and then restart FILDDT with the TOPS-20 FILDDT command. ? Not enough memory for symbols FILDDT does not have enough free memory to read in the symbol table from the specified .EXE file. See the note above. A-7 EERRRROORR MMEESSSSAAGGEESS ? NOT IN CORE You tried to map through a page map pointer (in a UPT, SPT, or section table) that addresses a page that is swapped out. This can occur only if you are trying to do your own virtual address mapping, and used the expr{}nU command, where 0<=n<=2. % Not in .EXE format -- Data file assumed. A GET command without a /DATA switch or a previous ENABLE DATA-FILE command specified a file which is not in .EXE file format. FILDDT assumes it is a data file. ? NOT WRITABLE You tried to modify a word in a write-protected page. To enable writing on protected pages, use the 0W command. | | | ? Null filename illegal | | You did not enter a file specification to a command that requires | one. ? PAGE DOES NOT EXIST You tried to display a word in a nonexistent page. ? Patching is not enabled You attempted to modify (with FILDDT) a file, a disk, or the monitor, but did not use the /PATCH switch or the ENABLE PATCHING command. % Patching the running monitor is illegal You entered an ENABLE PATCHING command and then gave a PEEK command. ? PEEK FAILED You tried to PEEK at the monitor, but do not have WHEEL or OPERATOR privileges enabled. A-8 EERRRROORR MMEESSSSAAGGEESS % Symbols cannot be extracted from a data file You used the command G_E_T_ f_i_l_n_a_m_/_S_Y_M_B_O_L_. Either the file specified by filnam is not an .EXE file, or you previously used the command E_N_A_B_L_E_ D_A_T_A_-_F_I_L_E_. ? Symbols cannot be extracted from a data file You used the command L_O_A_D_ f_i_l_n_a_m_, and the file specified by filnam is not an .EXE file. U You entered a symbol that DDT cannot locate in any symbol table. Cure this by entering the correct symbol, or by defining the symbol with the command {_e_x_p_r_<_}_s_y_m_b_o_l_:_. ? UNEXPECTED MOVEM FAILURE DDT could not deposit to memory even though the page exists exists and is write-enabled. NOTE In the following messages, u_n_i_t_ is one of the following: o "Unit" (if you used the DRIVE command) o "Unit u on controller k on channel c" (if you used the STRUCTURE command, where u, k, and c are the arguments you entered) % U_n_i_t_ has a bad BAT block The unit that you specified in a DRIVE or STRUCTURE command has a bad BAT block. % U_n_i_t_ has a bad HOME block The unit that you specified in a DRIVE or STRUCTURE command has a bad HOME block. A-9 EERRRROORR MMEESSSSAAGGEESS ? U_n_i_t_ is off line The unit that you specified in a DRIVE or STRUCTURE command is off line. % U_n_i_t_ is write locked You used an ENABLE PATCHING command and then specified a write-locked unit in a DRIVE or STRUCTURE command. % Update of file's symbol table failed FILDDT was unable to write the modified symbol table back to the file after you gave a or command. This may also occur when you use the n5M command. A-10 GGLLOOSSSSAARRYY bit Bit is a contraction of "binary digit". A bit is the smallest unit of information in a binary system of notation. It is the choice between two possible states, usually designated as zero and one. Bits of data are often used as flags to indicate on/off or yes/no conditions. breakpoint A breakpoint is a location in a program's executable code that has been modified so that if the program attempts to execute the instruction at that location, control passes to DDT before the instruction is executed. current display mode The current display mode is the mode in which DDT displays the next word (unless there is an intervening command that changes the current display mode). Also known as the current typeout mode. current quantity The current quantity is the most recent of: o the last 36-bit quantity that DDT displayed o the 36-bit evaluation of the last expression that you entered as an argument to a command that deposits to memory This value is often used as the default argument for the next command. Also known as the last value typed. Gloss-1 GGLLOOSSSSAARRYY current location The current location is a memory word that has been referenced by an earlier DDT command. The address of the current location is the default address for most DDT commands. current location stack entry The location that will become the current location as a result of the next command. current radix The current radix is the radix in which DDT displays numeric values. current typeout mode See current display mode. debugging Debugging is the process of finding and removing programming errors from programs. EDDT EDDT is the DDT variant that is used to debug executive-mode programs. FILDDT FILDDT is the DDT variant that is used to examine and modify disk files and disk structures. FILDDT is also used to examine (but not modify) the running monitor. jiffy A jiffy is a unit of time defined as one AC (alternating current) cycle. If your line power has a frequency of 60 Hz., a jiffy is one sixtieth of a second (about 16 milliseconds). If your line power has a frequency of 50 Hz., a jiffy is one fiftieth of a second (20 milliseconds). KDDT KDDT is the DDT variant used to debug the monitor. You can set breakpoints, single-step instructions, and perform any other DDT function. Gloss-2 GGLLOOSSSSAARRYY last value typed See current quantity. location A location is a numbered or named place in storage or memory where a unit of data or an instruction can be stored. This manual also uses the terms w_o_r_d_ and m_e_m_o_r_y_ w_o_r_d_. location counter The location counter is a memory word that contains the address of the current location. location sequence stack The location sequence stack is a stack in which DDT stores the addresses of locations used earlier. DDT uses the stack to access these locations again without having you explicitly enter the address of each of the locations. DDT references these addresses in a last-in, first-out manner. MDDT MDDT is the DDT mode used to examine and patch the running monitor. open location The open location is a memory word that you can modify with your next DDT command. prevailing display mode The prevailing display mode is a user-defined default display mode. DDT displays memory words in the prevailing mode unless you specify a temporary display mode. You can restore the prevailing mode with the command. See Chapter 4 (Displaying and Modifying Memory) for a list of other commands that restore the prevailing display mode. reset Reset refers to the zero condition of a bit or flag. A bit that is zero is said to be reset. T_o_ r_e_s_e_t_ is the verb that refers to the act of turning the bit off, "clearing" the bit, or making it zero. Gloss-3 GGLLOOSSSSAARRYY set Set refers to the nonzero condition of a bit or flag. A bit that is nonzero is said to be set. T_o_ s_e_t_ is the verb that refers to the act of turning the bit on, or making it nonzero. single-stepping Single-stepping is the process of executing program instructions one at a time using DDT, to verify the result of each instruction. target Target refers to the contents of the virtual address space that FILDDT is accessing. The virtual address space may contain a disk structure, a disk file, or the running monitor. temporary display mode The temporary display mode is a short-term, user-selected display mode which overrides the prevailing display mode. Temporary display mode remains in effect until you enter or . Also known as the temporary typeout mode. temporary typeout mode See temporary display mode. Gloss-4 INDEX $, 2-2 ], 4-9, 4-12, 4-13, 4-15, $$., 5-2, 5-3 12-2 $., 5-2, 5-3 ^, 4-9 Backslash, 4-9, 4-12, 4-13, ASCIZ strings, 4-19 4-16, 12-2 Automatic page-creation, 4-21 , 2-3, 4-9 Automatic proceed , 2-3 terminating, 5-8 , 2-3 Automatic proceed flag, 5-7 deleting, 2-3 Automatic write-enable, 4-20 Equal sign, 4-6 , 2-3, 4-12 BACKSPACE key, 2-3 ", 3-6 , 2-3 "5, 3-7 $0BPT, 5-10 "c, 3-7 Breakpoint block, 12-2 ., 5-2 Breakpoints, 2-5, 5-1 0<, 8-6 conditional, 5-9 0T, 4-5 DDT action at, 5-3 1:, 7-2 display additional location at, 1M, 4-23, 4-25 5-4 1S, 4-5 display address of, 5-6 1W, 4-21 executing command strings at, 2M, 4-3 5-5 3M, 4-3 executing instructions at, 5-11 4M, 12-3 executing subroutines at, 5-13 5M, 7-6 inter-section, 12-3 5T, 4-5 proceeding from, 5-3, 5-6 6M, 12-5 removing, 5-6 6T, 4-5 setting, 5-3 7T, 4-5 single-stepping at, 5-11 :, 7-1, 7-2 unsolicited, 5-10 <, 8-1 Byte pointers, 4-6 , 4-11, 4-12 ., 5-2 1:, 7-7 Commands 1W, 4-21 DDT 1X, 5-15 , 4-6 :, 7-6 !, 4-9, 4-12, 4-13, 4-16, <, 8-3 4-17, 4-18, 12-2 K, 7-3 ", 3-5 nU, 11-2 ""<""">, 3-6 P, 5-8 ., 4-7 Q, 4-8 /, 4-9, 4-12, 4-13, 4-14, U, 11-2 12-2 W, 4-20 ;, 4-6 X, 5-14, 5-16 =, 4-6 , 4-11 ?, 4-19, 4-23, 5-14, 6-3, 7-5 , 4-11 [, 4-9, 4-12, 4-13, 4-14, >, 8-2 12-2 ?, 2-3 \, 4-9, 4-12, 4-13, 4-16, B, 5-6, 11-2 12-2 C, 4-5 Index-1 D, 7-3 DDT variants, 1-2 E, 6-3 Default section F, 4-5 floating, 12-6 G, 5-1, 5-6, 5-16, 11-1 permanent, 12-6 H, 4-5 Display mode I, 5-16 C, 4-5 K, 7-3 current, 4-3 M, 6-4 F, 4-5 N, 6-2 H, 4-5 0nB, 5-6 O, 4-5 nB, 3-4, 5-3, 5-4, 5-6 prevailing, 4-2 nI, 3-4 1S, 4-5 nM, 3-4 S, 4-5 nT, 4-5 symbolic, 4-1 nU, 3-4, 11-2 0T, 4-5 O, 4-5 5T, 4-5 P, 5-6, 5-7, 5-16, 11-1 6T, 4-5 Q, 4-8 temporary, 4-2 S, 4-5 U, 5-17, 11-2 EFIW, 4-13, 4-18 V, 4-23 , 2-2, 2-3 W (search), 6-1 ESCAPE key, 2-2, 2-3 W (write-protect), 4-20 Expression operators, 3-7 X, 5-11, 5-13, 5-16, Expressions, 3-2 11-1, 11-2 Extended format indirect word, Z, 4-19 4-13 Exclamation point, 4-9, 4-12, 4-13, 4-16, 4-17, 4-18, IFIW, 4-13, 4-18 12-2 Initializing memory, 4-19 Left square bracket, 4-9, Input 4-12, 4-13, 4-14, 12-2 ASCII character, 3-6 , 2-3, 4-9 ASCII string, 3-5 Period, 4-7 decimal integer, 3-3 , 2-3, 4-9, 4-10 floating point, 3-3 Reverse slash, 4-9, 4-12, halfwords, 3-10 4-13, 4-16, 12-2 instructions, 3-10 Right square bracket, 4-9, long text string, 3-4 4-12, 4-13, 4-15, 12-2 octal integer, 3-2 Semicolon, 4-6 RADIX50 word, 3-7 Slash, 4-9, 4-12, 4-13, 4-14, SIXBIT character, 3-7 12-2 SIXBIT string, 3-6 , 2-3, 4-9, 4-12, 4-13, text, 3-4 4-17, 12-2 value returned by a command, Underscore, 4-6 3-3 L (page access), 4-22 Input to DDT, 3-2 FILDDT Instruction format indirect word, , 9-9 4-13 CONTROL key, 2-3 CPU type for FILDDT, 11-5 Last quantity typed, 4-8 Current display mode, 4-3 , 2-3 Current location, 2-4, 4-7 LINE FEED key, 2-3 Current location stack entry, 4-8 Location counter, 2-4, 4-7 Current quantity, 2-4, 4-8 Location sequence stack, 2-4, 4-8 Dangerous instructions, 5-15 $4M, 12-3 Index-2 $5M, 7-6 for address, 6-3 $6M, 12-5 for matching value, 6-1 Mask for non-matching value, 6-2 output byte size, 4-3 terminate, 6-3 search, 6-4 Search mask, 6-4 TTY control, 4-23 Single-stepping, 5-11 Maximum symbolic offset, 4-4 Symbol table Memory protection, 4-20 closing, 7-2 Memory watch, 4-23 finding name of, 7-2 opening, 7-1 $nB, 5-2 Symbolic debugging, 1-1 Symbols Open location, 2-4, 4-7 creating undefined, 7-4 Operators defining new, 7-2 in expressions, 3-7 deleting, 7-3 Output byte size mask, 4-3 listing specific, 7-5 listing undefined, 7-5 Page accessibility, 4-22 locating, 7-4 Patch multiply-defined, 7-1 abort, 8-6 reactivating typeout of, 7-3 before instruction, 8-1 redefining old, 7-2 following instruction, 8-3 suppressing typeout of, 7-3 terminate, 8-2, 8-3 TAB key, 2-3 Prevailing display mode, 4-2 , 2-3 Proceed count, 5-7 Temporary display mode, 4-2 TTY control mask, 4-23 $$Q, 4-8 $Q, 4-8 Unsolicited breakpoint, 5-10 User-program context, 5-16 , 2-3 RETURN key, 2-2, 2-3 Watching memory, 4-23 Search Zeroing memory, 4-19 Index-3