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 _______ ___ ______ | TOPS-20 DDT Manual 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 MACRO Assembler Reference Manual _______ ____ _________ ______ o TOPS-20 LINK Reference Manual _______ ________ _________ ______ o TOPS-20 Commands Reference Manual _________________________ _________ _________ ______ o DECsystem-10/DECSYSTEM-20 Processor Reference Manual _______________ _______ ______ _________ ______ o TOPS-10/TOPS-20 RSX-20F System Reference Manual 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 current location. 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 CHAPTER 1 CHAPTER 1 INTRODUCTION TO DDT INTRODUCTION TO DDT 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. 1.1 SYMBOLIC DEBUGGING 1.1 SYMBOLIC DEBUGGING 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. 1.2 TOPS-20 VARIANTS OF DDT 1.2 TOPS-20 VARIANTS OF DDT There are several variants of DDT, each useful under specific circumstances or for specific tasks. 1-1 INTRODUCTION TO DDT INTRODUCTION TO DDT 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 LINK Reference Manual for further information about using LINK. 1-2 INTRODUCTION TO DDT INTRODUCTION TO DDT 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 CHAPTER 2 CHAPTER 2 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 2.1 INTRODUCTION 2.1 INTRODUCTION 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 doing. 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. 2.2 LOADING DDT 2.2 LOADING DDT | 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT ______ | where filnam 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 filnam 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. 2.3 BASIC FUNCTIONS 2.3 BASIC FUNCTIONS 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 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 ______ _____ ____ _____ _____ ________ , , , , , or , 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. 2.3.1 Error Conditions 2.3.1 Error Conditions 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 _ _ Multiply-defined symbol or Undefined 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 2.3.2 Basic Concepts 2.3.2 Basic Concepts _______ ________ A very useful DDT concept is that of the current location. 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 location counter 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 open location 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. __ ____ ___ ________ _______ __ ___ _______ ________ To find the symbolic address of the current location, 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 current quantity. 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 location sequence stack 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 2.3.3 Starting and Stopping the Program 2.3.3 Starting and Stopping the Program When your program is loaded and DDT is ready to accept your commands ___ (as indicated by DDT 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 breakpoints 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 if the program attempts to execute the ______ instruction at that location, control passes to DDT before the instruction is executed. The command to set a breakpoint is: addrB ____ where addr 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 2.3.4 Examining and Modifying Memory 2.3.4 Examining and Modifying Memory One command to examine memory is: addr/ ____ where addr 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 addr/ changes the current location to addr and opens the ____ word at addr. ____ _____ If you omit addr from an examine-memory command, such as addr/, 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT _____ where value is the contents of the word located at SYM2. By default, _____ DDT displays value symbolically if it can. ____ The command / by itself (without addr) 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 ____ | addr, 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 value 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 _____ | value. 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 addr, DDT deposits addr in the open ____ location and closes the location before opening the location at addr 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 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 . does not affect the location sequence stack. Entering another causes DDT to display and open the next word. ________ To display and open the word previous 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 does not appear on the screen. To change the contents of the open location, enter: value _____ where value can be an instruction, a symbol, or a numeric expression. ______ For example, if you enter the command LABL2/, 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 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 CONTENTS is the value stored at LABL2+1. o 2.3.5 Executing Program Instructions 2.3.5 Executing Program Instructions 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 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 instr 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 single-stepping. _______ _ __________ To execute a subroutine, 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 continue execution of the program 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 2.4 A SAMPLE DEBUGGING SESSION USING DDT 2.4 A SAMPLE DEBUGGING SESSION USING DDT 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-1: Sample Program X.MAC Figure 2-1: Sample Program X.MAC 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 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. Figure 2-2: Annotated Debugging Session Figure 2-2: Annotated Debugging Session 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT Figure 2-2: Annotated Debugging Session (Cont.) Figure 2-2: Annotated Debugging Session (Cont.) 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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 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. Figure 2-3: Terminal Display of Debugging Session Figure 2-3: Terminal Display of Debugging Session @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 GETTING STARTED WITH DDT GETTING STARTED WITH DDT 2.5 PROGRAMMING WITH DDT IN MIND 2.5 PROGRAMMING WITH DDT IN MIND 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 ______ Symbol is still entered in the symbol table, and you can use symbol as ______ input to DDT, but DDT does not display symbol 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 MACRO Assembler _________ ______ Reference Manual for more information about defining symbols. 2-21 2-22 CHAPTER 3 CHAPTER 3 DDT COMMAND FORMAT DDT COMMAND FORMAT 3.1 COMMAND SYNTAX 3.1 COMMAND SYNTAX 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 /abcd/ 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 DDT COMMAND FORMAT DDT COMMAND FORMAT ____ The left-justified ASCII string abcd 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 ____ abcd) 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 addr is the address that DDT is to next test as part of a _____ ____ search, and value is the contents of the memory location at addr. Still other commands return values that DDT does not display, but can use as arguments to other commands. 3.2 INPUT TO DDT 3.2 INPUT TO DDT ___________ You enter arguments to DDT as expressions. An expression can be a single value, or a combination of two or more values with one or more _________ operators. 3.2.1 Values in DDT Expressions 3.2.1 Values in DDT Expressions 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 octal integer value, simply enter the integer in octal digits. For example: 70707065 3-2 DDT COMMAND FORMAT DDT COMMAND FORMAT _______ _______ _____ To enter a decimal integer value, enter the integer in decimal digits and follow the value with a decimal point. For example: 9876. ________ _____ ______ To enter a floating point number, 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 symbol as a value in an expression, type in the symbol name _________ ______ as defined in your program. To enter an undefined symbol that you can define later, enter: symbol# ______ where symbol 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 command that returns a value as a value in an expression. DDT commands that return values and the values they return are listed in Table 3-1. Table 3-1: Commands that Return Values Table 3-1: Commands that Return Values COMMAND VALUE RETURNED VALUE ALSO COMMAND VALUE RETURNED VALUE ALSO KNOWN AS KNOWN AS . 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 DDT COMMAND FORMAT DDT COMMAND FORMAT Table 3-1: Commands that Return Values (Cont.) Table 3-1: Commands that Return Values (Cont.) COMMAND VALUE RETURNED VALUE ALSO COMMAND VALUE RETURNED VALUE ALSO KNOWN AS KNOWN AS 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 addr. ____ | You can enter text 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 long text string 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 DDT COMMAND FORMAT DDT COMMAND FORMAT 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 ASCII string is: "/text/ ____ where text is the string, and the slashes (/) represent any printing ____ character that is not contained within text. 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 abc/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 abc/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 ef in bits 0-13, and bits 14-35 reset. The last 36-bit expression evaluated becomes the current quantity. 3-5 DDT COMMAND FORMAT DDT COMMAND FORMAT 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 SIXBIT string is: "/text/ where text is the string, and the slashes (/) represent any printing ____ character that is not contained within text. 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 QWERTY 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 QWERTY 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 ASCII character 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 DDT COMMAND FORMAT DDT COMMAND FORMAT ______ _________ The syntax to enter a right-justified SIXBIT character 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 RADIX50 word is: text5" ____ where text 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 text in bits 4-35. DDT ignores any characters in text after the sixth. For example, if you enter: poiuytr5" DDT evaluates one 36-bit expression with bits 0-3 reset and the RADIX50 ______ _ string POIUYT in bits 4-35. DDT ignores the character r. DDT ____ translates lowercase characters to uppercase. Characters in text not in the RADIX50 character set that are DDT commands use, as an argument to ____ the command, any characters already entered. Characters in text 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. 3.2.2 Operators in DDT Expressions 3.2.2 Operators in DDT Expressions 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 value so far represents the accumulated 36-bit value resulting from evaluation of the expression to that point. 3-7 DDT COMMAND FORMAT DDT COMMAND FORMAT Table 3-2: Effects of Operators When Evaluating Expressions Table 3-2: Effects of Operators When Evaluating Expressions OPERATOR EFFECT ON EVALUATION OPERATOR EFFECT ON EVALUATION + 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 DDT COMMAND FORMAT DDT COMMAND FORMAT Table 3-2: Effects of Operators When Evaluating Expressions (Cont.) Table 3-2: Effects of Operators When Evaluating Expressions (Cont.) OPERATOR EFFECT ON EVALUATION OPERATOR EFFECT ON EVALUATION , (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 DDT COMMAND FORMAT DDT COMMAND FORMAT The nonarithmetic operators allow you to enter expressions in ___________ ______ ____ ______ instruction format as well as in data format. ___________ To enter an instruction, 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 halfwords, 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 CHAPTER 4 CHAPTER 4 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.1 DISPLAY MODES 4.1 DISPLAY MODES 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. 4.1.1 Default Display Modes 4.1.1 Default Display Modes 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. Table 4-1: Evaluation of Symbolic Display Mode Table 4-1: Evaluation of Symbolic Display Mode CONDITION DDT DISPLAYS EXAMPLE CONDITION DDT DISPLAYS EXAMPLE 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY Table 4-1: Evaluation of Symbolic Display Mode (Cont.) Table 4-1: Evaluation of Symbolic Display Mode (Cont.) CONDITION DDT DISPLAYS EXAMPLE CONDITION DDT DISPLAYS EXAMPLE 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. 4.1.2 Selecting Display Modes 4.1.2 Selecting Display Modes 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY _____ o instrX (execute instr) 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 current display mode 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 ______ ____ ____ ____ output byte size mask. 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 expr 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 2M is a command that addresses a DDT location that contains the _______ ________ ______ maximum symbolic offset. 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 addr is the absolute address (for example, 14414) of the location. You can set the maximum symbolic offset with the command: expr2M ____ where expr 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. Table 4-2: DDT Display Modes Table 4-2: DDT Display Modes FORMAT MODES FORMAT MODES 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY Table 4-2: DDT Display Modes (Cont.) Table 4-2: DDT Display Modes (Cont.) FORMAT MODES FORMAT MODES 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). RADIX MODES RADIX MODES 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.2 DISPLAYING EXPRESSIONS 4.2 DISPLAYING EXPRESSIONS 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 expr is the expression to display (expr 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. Table 4-3: Commands to Display Expressions Table 4-3: Commands to Display Expressions COMMAND EFFECT COMMAND EFFECT ; 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. 4.3 DISPLAYING BYTE POINTERS 4.3 DISPLAYING BYTE POINTERS 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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> 4.4 DISPLAYING AND DEPOSITING IN MEMORY 4.4 DISPLAYING AND DEPOSITING IN MEMORY 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 open location 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 location counter 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 current location. 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY ________ ________ _____ The location sequence stack 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 current location _____ _____ stack entry. 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 current quantity 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 last value typed. 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 expr is any legal DDT expression, and c is the command. NOTE ______ __ ___ ___________ See Values in DDT Expressions 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. Table 4-4: DDT Commands to Display Memory Table 4-4: DDT Commands to Display Memory COMMAND DISPLAY MODE OPEN CHANGE DEPOSIT COMMAND DISPLAY MODE OPEN CHANGE DEPOSIT CONTENTS OF THE CURRENT EXPR CONTENTS OF THE CURRENT EXPR DISPLAY LOCATION LOCATION DISPLAY LOCATION LOCATION / 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.4.1 Commands that Use the Current Location 4.4.1 Commands that Use the Current Location 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.4.2 Commands that Use the Location Sequence Stack 4.4.2 Commands that Use the Location Sequence Stack 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 4.4.3 Commands that Use an Address within the Command 4.4.3 Commands that Use an Address within the Command 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 expr > 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 expr, DDT enters the address of the current location on the location sequence stack (except \). ____ o DDT treats expr (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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY ! 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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 expr as an IFIW (instruction format indirect word), and ____ use any indexing and indirection specified by expr 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 expr as an EFIW (extended format indirect word) and use ____ any indexing and indirection specified by expr to compute the (global) effective address of the location to be opened. Use the command form: {expr}c where c is /, [, ], !, \, or . 4-18 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.5 DISPLAYING ASCIZ STRINGS 4.5 DISPLAYING ASCIZ STRINGS 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. 4.6 ZEROING MEMORY 4.6 ZEROING MEMORY 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 addr is the location where DDT will make the next deposit, and _____ ____ value is the contents of addr 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.7 AUTOMATIC WRITE-ENABLE 4.7 AUTOMATIC WRITE-ENABLE 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.8 AUTOMATIC PAGE CREATION 4.8 AUTOMATIC PAGE CREATION 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.9 DISPLAYING PAGE ACCESSIBILITY INFORMATION | 4.9 DISPLAYING PAGE ACCESSIBILITY INFORMATION | | 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 4.10 WATCHING A MEMORY LOCATION 4.10 WATCHING A MEMORY LOCATION 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 addr 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 addr is the address of the location being watched, and value is the contents of the location. This command also restores the prevailing display mode. ____ DDT checks addr every "jiffy" (about 20 milliseconds), and displays ____ the address and contents of addr whenever those contents change. ____ (Executive mode EDDT watches addr continuously.) If you enter a question mark (?) while DDT is watching, DDT displays: Watching: addr/ value ____ _____ where addr is the address of the location being watched, and value is ____ the contents of addr. 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). 4.11 TTY CONTROL MASK 4.11 TTY CONTROL MASK ___ You can control certain aspects of DDT's display by setting DDT's TTY _______ ____ control mask. 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY Table 4-5: TTY Control Mask Table 4-5: TTY Control Mask BIT VALUE EXPLANATION BIT VALUE EXPLANATION 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 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY 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. | | Figure 4-1: DDT Session Showing Columnar Output | Figure 4-1: DDT Session Showing Columnar Output | | 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 start/ to examine location start. _______ o Enter x: to open the symbol table for module X. _______ _____ o Enter .b to set breakpoint at location START. ______ o Enter g to begin execution. 4-25 DISPLAYING AND MODIFYING MEMORY DISPLAYING AND MODIFYING MEMORY Line 3: o DDT displays breakpoint information. ______ o Enter 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 x to execute the instruction. Line 6: o DDT displays the results of executing the instruction. ________ o Enter 1m/ to display and open the TTY control mask. o DDT displays the mask. Bit 34 is set. _________ o Enter 1,,2 to set bits 17 and 34. Line 7: ___________ o Enter startg to restart the program. Line 8: o DDT displays the breakpoint information. ______ o Enter 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 x to execute the next instruction. Line 11: o DDT displays the results of executing the instruction. 4-26 CHAPTER 5 CHAPTER 5 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 5.1 BEGINNING EXECUTION 5.1 BEGINNING EXECUTION 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 ___ DDT command to reenter DDT and examine your program. You can start or continue program execution at any address with the command: addrG 5.2 USING BREAKPOINTS 5.2 USING BREAKPOINTS __________ A breakpoint 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 unsolicited breakpoint, 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. Table 5-1: Breakpoint Locations of Interest Table 5-1: Breakpoint Locations of Interest LOCATION CONTENTS LOCATION CONTENTS $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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 5.2.1 Setting Breakpoints 5.2.1 Setting Breakpoints ___ _ __________ To set a breakpoint, 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 set a breakpoint and have DDT display an additional location 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION _______ ___ _______ To display the address 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 remove breakpoint n, enter: 0nB To remove all breakpoints, enter: B 5.2.2 Proceeding from Breakpoints 5.2.2 Proceeding from Breakpoints 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 addr defaults to the program's start address. 5-6 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 expr 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 automatic proceed flag. 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 resets (clears) the automatic proceed flag associated with the breakpoint at which DDT has suspended program execution. ___ _ __________ ___ ___ ___ __________ _________ _______ ____ To set a breakpoint and set the associated automatic proceed flag, 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION ______ If you entered addr1< 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 contents 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 proceed from a breakpoint and set the associated automatic proceed ____ flag, give the command: {expr}P where expr is the proceed count. DDT stores the proceed count at $nB+2. 5-8 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 5.2.3 Conditional Breakpoints 5.2.3 Conditional Breakpoints 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 5.2.4 The "Unsolicited" Breakpoint 5.2.4 The "Unsolicited" Breakpoint 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 filnam 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 addr+1 is the first location after the JSR $0BPT instruction, _____ and instr is the contents of that location. 5-10 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 5.3 EXECUTING EXPLICIT INSTRUCTIONS 5.3 EXECUTING EXPLICIT INSTRUCTIONS 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. 5.4 SINGLE-STEPPING INSTRUCTIONS 5.4 SINGLE-STEPPING INSTRUCTIONS 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 5.5 EXECUTING SUBROUTINES AND RANGES OF INSTRUCTIONS 5.5 EXECUTING SUBROUTINES AND RANGES OF INSTRUCTIONS 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 addr is the address of the next instruction to be executed, and _____ instr is the instruction. _________ ___ _________ __ ___ ______ __ ____________ To terminate the execution of the series of instructions, 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION o opens the current location o waits for your next command 5.5.1 Single-Stepping "Dangerous" Instructions 5.5.1 Single-Stepping "Dangerous" Instructions 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 5.6 USER-PROGRAM CONTEXT 5.6 USER-PROGRAM CONTEXT 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. Table 5-2: User-Program Context Values Table 5-2: User-Program Context Values FUNCTION VALUE FUNCTION VALUE 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 CONTROLLING PROGRAM EXECUTION CONTROLLING PROGRAM EXECUTION 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 CHAPTER 6 CHAPTER 6 SEARCHING FOR DATA PATTERNS IN DDT SEARCHING FOR DATA PATTERNS IN DDT 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 search for words that match a specific value, 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 ____ expr o stops the search after comparing the contents of addr2 with ____ expr 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 SEARCHING FOR DATA PATTERNS IN DDT SEARCHING FOR DATA PATTERNS IN DDT 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 search for words that do NOT match a specified value, 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 SEARCHING FOR DATA PATTERNS IN DDT SEARCHING FOR DATA PATTERNS IN DDT 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 search for references to an address, 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 addr is the address of the location that will next compare, and _____ ____ value is the contents of addr. _____ ___ ______ To abort the search, 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 SEARCHING FOR DATA PATTERNS IN DDT SEARCHING FOR DATA PATTERNS IN DDT M is a command that addresses a DDT location that contains a ______ ____ search mask 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 expr 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 CHAPTER 7 CHAPTER 7 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT 7.1 OPENING AND CLOSING SYMBOL TABLES 7.1 OPENING AND CLOSING SYMBOL TABLES 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 open the symbol table of a program module, enter: name: ____ where name 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 name. 7-1 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT ____ ___ ____ __ ___ ______ __________ ____ ___ ____ ______ _____ To find the name of the module associated with the open symbol table, 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 close the open symbol table, enter: : 7.2 DEFINING SYMBOLS 7.2 DEFINING SYMBOLS To redefine a symbol or to create a new symbol in the current symbol table, enter: exprK ______ ______ where symbol is the symbol to be suppressed. DDT still accepts symbol ______ as input, but no longer displays symbol 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 reactivate a symbol for typeout, redefine the symbol. For example, to reactivate the display of symbol SIZE, above, enter: sizeK ______ DDT removes symbol from the symbol table, and no longer displays ______ ______ symbol or accepts symbol as input. 7-3 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT 7.5 CREATING UNDEFINED SYMBOLS 7.5 CREATING UNDEFINED SYMBOLS It is sometimes convenient to use symbols that have not yet been defined. To create an undefined symbol, enter: symbol# ______ ______ where symbol is the undefined symbol name. DDT enters symbol 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. | | | 7.6 FINDING WHERE A SYMBOL IS DEFINED | 7.6 FINDING WHERE A SYMBOL IS DEFINED | To determine the modules in which a symbol is defined, enter: symbol? ______ where symbol is the name of the symbol. DDT displays the name of each ______ program module in which symbol 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 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT 7.7 SEARCHING FOR SYMBOLS 7.7 SEARCHING FOR SYMBOLS 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 7.8 LISTING UNDEFINED SYMBOLS 7.8 LISTING UNDEFINED SYMBOLS To get a list of all currently undefined symbols, enter: ? DDT displays a list containing each undefined symbol. | | | 7.9 LISTING SYMBOLS | 7.9 LISTING SYMBOLS | | To get a list of all symbols starting with a certain character or set | of characters, enter: | | {val1<{val2>}}{sym}{n}? | ____ ____ | where val1 and val2 restrict the values of symbols which DDT displays. ____ | If only val1 is present, only symbols having that value are displayed. ____ ____ | If both val1 and val2 are present, symbols with (signed) values ____ ____ _ | between val1 and val2 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 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT | 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. 7.10 LOCATING SYMBOL TABLES WITH PROGRAM DATA VECTORS 7.10 LOCATING SYMBOL TABLES WITH PROGRAM DATA VECTORS 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 name is the name of the PDV, and the slashes (/) represent any ____ ____ characters that do not appear in name. If name is a null string, DDT searches for a PDV with no name or a null name. DDT ignores any ____ characters in name beyond a length of 39. ____ DDT searches for a PDV named name, and places its address in $5M. If DDT does not find the PDV, it displays ? and sounds the terminal buzzer or bell. 7-6 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT 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 MANIPULATING SYMBOLS IN DDT MANIPULATING SYMBOLS IN DDT > 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 CHAPTER 8 CHAPTER 8 INSERTING PATCHES WITH DDT INSERTING PATCHES WITH DDT 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 insert a patch that will be executed before the instruction at the open location, enter: {expr}< ____ where expr 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 expr, 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 expr 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 expr is an AC address, or resolves to a value less than 0,,140, DDT displays "?" and sounds the terminal buzzer or bell. 8-1 INSERTING PATCHES WITH DDT INSERTING PATCHES WITH DDT 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 terminate the patch, enter: {expr}{n}> ____ _ where expr 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 expr 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 INSERTING PATCHES WITH DDT INSERTING PATCHES WITH DDT ____ If you default expr, 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 insert a patch that will be executed after the instruction at the open location, enter: {expr}< ____ where expr 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 expr 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 INSERTING PATCHES WITH DDT INSERTING PATCHES WITH DDT NOTE ____ If expr 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. Figure 8-1: Annotated Patching Session Figure 8-1: Annotated Patching Session 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 INSERTING PATCHES WITH DDT INSERTING PATCHES WITH DDT Figure 8-1: Annotated Patching Session (Cont.) | Figure 8-1: Annotated Patching Session (Cont.) | | | 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. Figure 8-2: Terminal Display of Patching After an Instruction Figure 8-2: Terminal Display of Patching After an Instruction | 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 ______ | before the instruction at START+4. You enter the instruction in the ________ | form expr (user input is lowercase). Note the use of the patch ____ _ termination command without expr and without n. 8-5 INSERTING PATCHES WITH DDT INSERTING PATCHES WITH DDT Figure 8-3: Terminal Display of Patching Before an Instruction Figure 8-3: Terminal Display of Patching Before an Instruction | 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 abort the patch you are entering, 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 CHAPTER 9 CHAPTER 9 FILDDT FILDDT 9.1 INTRODUCTION 9.1 INTRODUCTION 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 virtual address space 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 ______ target. 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. 9.2 USING FILDDT 9.2 USING FILDDT There are two command levels in FILDDT. This document refers to these ______ _______ _____ ___ _______ _____ two levels as FILDDT command level and DDT command level. 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 FILDDT FILDDT 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 command is a FILDDT command-level command, file-spec is a ______ TOPS-20 file specification, and switch 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 FILDDT FILDDT 9.2.1 FILDDT Commands 9.2.1 FILDDT Commands 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 FILDDT FILDDT 9.2.2 Symbols 9.2.2 Symbols 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. 9.2.3 Commands to Establish Formats and Parameters 9.2.3 Commands to Establish Formats and Parameters ENABLE DATA-FILE ENABLE DATA-FILE 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. ENABLE PATCHING ENABLE PATCHING 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. ENABLE THAWED ENABLE THAWED 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 FILDDT FILDDT LOAD LOAD 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. 9.2.4 Commands to Access the Target and Enter DDT 9.2.4 Commands to Access the Target and Enter DDT DRIVE DRIVE 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 FILDDT FILDDT If the unit is part of a mounted structure, FILDDT displays: [Unit is part of structure name] ____ where name 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. GET GET 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 FILDDT FILDDT PEEK PEEK 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 FILDDT FILDDT STRUCTURE STRUCTURE 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 name is the logical name of the structure. 9.2.5 Exiting FILDDT 9.2.5 Exiting FILDDT 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 FILDDT FILDDT | 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 CHAPTER 10 CHAPTER 10 PRIVILEGED MODES OF DDT PRIVILEGED MODES OF DDT 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 PRIVILEGED MODES OF DDT PRIVILEGED MODES OF DDT 10.1 MDDT 10.1 MDDT 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 PRIVILEGED MODES OF DDT PRIVILEGED MODES OF DDT 10.2 KDDT 10.2 KDDT 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 PRIVILEGED MODES OF DDT PRIVILEGED MODES OF DDT 10.3 EDDT 10.3 EDDT You can use EDDT to debug user programs that run in executive mode. You must load EDDT.REL with your program, as follows: @LINK S SYS:EDDT.REL,PROG/GO @SAVE PROG where PROG is the name of your MACRO-20 program. 10-4 10-5 11-1 CHAPTER 11 CHAPTER 11 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS PHYSICAL AND VIRTUAL ADDRESSING COMMANDS | 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 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS PHYSICAL AND VIRTUAL ADDRESSING COMMANDS 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 arg 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 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS PHYSICAL AND VIRTUAL ADDRESSING COMMANDS COMMAND EXPLANATION page0U This command causes memory mapping to occur through the executive ____ process table (EPT) that is located at physical page page. offset0U This command produces the same effect as page0U (above), ______ except that offset 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 _____ _____ page1 is the page number of the UPT, and page2 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 page. With this command, you can bypass the EPT. offset1U This command produces the same effect as page1U (above), ______ except that offset is an offset (in words) into the SPT. page2U This command causes mapping to occur through the section map at ____ physical page page. This command is legal only if KL-paging is in effect. offset2U This command produces the same effect as page2U (above), ______ except that offset is an offset (in words) into the SPT. This command is legal only if KL-paging is in effect. 11-3 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS PHYSICAL AND VIRTUAL ADDRESSING COMMANDS 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 addr 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 addr. DDT adds addr to all user addresses that you enter. addr9U ____ This command read-and-write-protects all addresses above addr (before adding relocation factor). 11-4 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS PHYSICAL AND VIRTUAL ADDRESSING COMMANDS 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 if the command for that function was used, 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 PHYSICAL AND VIRTUAL ADDRESSING COMMANDS PHYSICAL AND VIRTUAL ADDRESSING COMMANDS 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 CHAPTER 12 CHAPTER 12 EXTENDED ADDRESSING EXTENDED ADDRESSING 12.1 LOADING DDT INTO AN EXTENDED SECTION 12.1 LOADING DDT INTO AN EXTENDED SECTION 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 TOPS-20 COMMANDS _________ ______ REFERENCE MANUAL for more information about the use of these switches. 12-1 EXTENDED ADDRESSING EXTENDED ADDRESSING 12.2 EXAMINING AND CHANGING MEMORY 12.2 EXAMINING AND CHANGING MEMORY 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). 12.3 BREAKPOINTS 12.3 BREAKPOINTS If DDT is running in a nonzero section, breakpoints can be set in any section. 12.3.1 The Breakpoint Block 12.3.1 The Breakpoint Block 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 EXTENDED ADDRESSING EXTENDED ADDRESSING 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. 12.3.2 Enabling and Disabling Inter-section Breakpoints 12.3.2 Enabling and Disabling Inter-section Breakpoints 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 disable inter-section breakpoints, enter: 04M 12-3 EXTENDED ADDRESSING EXTENDED ADDRESSING 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 12.4 DISPLAYING SYMBOLS IN NONZERO SECTIONS 12.4 DISPLAYING SYMBOLS IN NONZERO SECTIONS 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 EXTENDED ADDRESSING EXTENDED ADDRESSING 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 12.5 DEFAULT SECTION NUMBERS 12.5 DEFAULT SECTION NUMBERS 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 EXTENDED ADDRESSING EXTENDED ADDRESSING 12.5.1 Permanent Default Section 12.5.1 Permanent Default Section | 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. 12.5.2 Floating Default Section 12.5.2 Floating Default Section 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 EXTENDED ADDRESSING EXTENDED ADDRESSING SCREEN DISPLAY USER INPUT EXPLANATION SCREEN DISPLAY USER INPUT EXPLANATION 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 EXTENDED ADDRESSING EXTENDED ADDRESSING 12.6 EXECUTING SINGLE INSTRUCTIONS 12.6 EXECUTING SINGLE INSTRUCTIONS 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 12.7 ENTERING PATCHES IN EXTENDED SECTIONS 12.7 ENTERING PATCHES IN EXTENDED SECTIONS 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 APPENDIX A APPENDIX A ERROR MESSAGES ERROR MESSAGES 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 ERROR MESSAGES ERROR MESSAGES | ? 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 ERROR MESSAGES ERROR MESSAGES % 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 ERROR MESSAGES ERROR MESSAGES % 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 ERROR MESSAGES ERROR MESSAGES ? 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 ERROR MESSAGES ERROR MESSAGES ? 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 module:. ? 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 ERROR MESSAGES ERROR MESSAGES ? 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 ERROR MESSAGES ERROR MESSAGES ? 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 ERROR MESSAGES ERROR MESSAGES % Symbols cannot be extracted from a data file ___ _____________ You used the command GET filnam/SYMBOL. Either the file specified by filnam is not an .EXE file, or you previously used ______ _________ the command ENABLE DATA-FILE. ? Symbols cannot be extracted from a data file ____ ______ You used the command LOAD filnam, 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 {expr<}symbol:. ? UNEXPECTED MOVEM FAILURE DDT could not deposit to memory even though the page exists exists and is write-enabled. NOTE ____ In the following messages, unit 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) ____ % Unit has a bad BAT block The unit that you specified in a DRIVE or STRUCTURE command has a bad BAT block. ____ % Unit has a bad HOME block The unit that you specified in a DRIVE or STRUCTURE command has a bad HOME block. A-9 ERROR MESSAGES ERROR MESSAGES ____ ? Unit is off line The unit that you specified in a DRIVE or STRUCTURE command is off line. ____ % Unit 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 GLOSSARY GLOSSARY 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 GLOSSARY GLOSSARY 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 GLOSSARY GLOSSARY 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 word and memory word. 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. To reset is the verb that refers to the act of turning the bit off, "clearing" the bit, or making it zero. Gloss-3 GLOSSARY GLOSSARY set Set refers to the nonzero condition of a bit or flag. A bit __ ___ that is nonzero is said to be set. To set 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