SPRU053 TMS320C30 TMS320C31 SPRU031 TMS320 SPRU035 SPRU024 SPRA021 SPRU069 - Datasheet Archive

 

C Source Debugger User's Guide SPRU053 November 1993 Printed on Recycled Paper TMS320C3x C Source Debugger User's Guide Reader

 

TMS320C3x C Source Debugger User's Guide SPRU053 SPRU053 November 1993 Printed on Recycled Paper TMS320C3x C Source Debugger User's Guide Reader Response Card Texas Instruments wants to provide you with the best documentation possible-please help us by answering these questions and returning this card. How have you used this manual? To look up specific information or procedures when needed (as a reference). To read chapters about subjects of specific interest. To read from front to back before using the product. Did you use the Tutorial (Chapter 2)? Yes No Which additional subjects should be included in future versions of the Tutorial? Please describe any mistakes or misleading information that you found (include page numbers). Which topics should this document describe in greater detail? Please list information that was difficult to find and why (not in index, not in a logical location, etc.). Please provide any specific suggestions that you have for improving the content of this document. Are there specific, useful features of this user's guide that should be retained in future versions of this document? Additional comments: Thank you for taking the time to fill out this card. Name Title Company Address City State Zip/Country May we call you to discuss your comments? If so, please include phone number November 1993 TMS320C3x C Source Debugger Reference Card Phone Number DSP Hotline: (713) 274­2320 Invoking the Debugger Emulator: EVM: Simulator: emu3x evm30 sim3x [filename] [­options] [filename] [­options] [filename] [­options] Debugger Options Option Description ­b[b] Select the screen size. Option Characters. none 80 × 25 (default) ­b 80 × 43 (EGA or VGA) ­bb 80 × 50 (VGA only) ­i pathname Identify additional directories. Identifies directories that contain source files. ­mm0 ­mm1 Select the mode. (simulator only) Tells debugger to operate in microprocessor (0) or microcomputer (1) mode (0 is the default). ­mv30 ­mv31 Select the device version. (simulator only) Identifies 'C30 or 'C31 memory map ('C30 is the default). ­p port address Identify the port address. (emulator and EVM) Identifies the I/O port address that the debugger uses for communicating with the device. ­profile Enter the profiling environment. (emulator and simulator) Brings up the debugger in a profiling environment. ­s Load symbol table only. Tells the debugger to load filename's symbol table only. ­t filename Identify new initialization file. Allows you to specify an initialization file. ­v Load without symbol table. Loads only global symbols; later, local symbols are loaded as needed. Affects all loads. ­x Ignore D_OPTIONS. Ignores options supplied with D_OPTIONS. 1 Summary of Debugger Commands ? expression [, display format] d addr address addr function name d alias [alias name [, "command string"] ] b asm d ba address d bd address d bl d border [active ] [, [ inactive ] [,resize ] ] d br d c d calls d cd [directory name] chdir [directory name] b cls b cnext [expression] d color area, attr1 [,attr2 [,attr3 [,attr4 ] ] ] d cstep [expression] d dasm address dasm function name b dir [directory] b disp expression [, display format] d dlog filename [, {a|w}] d echo string b else d endif d endloop d eval expression e expression b file filename b fill address , length, data d func function name func address b go [address] d halt d if Boolean expression debugger command list [else debugger command list] endif b load object filename b loop expression debugger command list endloop b ma address, length, type b map {on | off} b mc port address, filename, {READ | WRITE} b p = profiler only b = both profiler and basic debugger 2 d = basic debugger only simulator only Summary of Debugger Commands md address b mem expression [, display format] d mi port address, {READ|WRITE} b mix d ml b move [X, Y [, width, length ] ] b mr b ms address, length, filename b next [expression] d patch address, assembly language instruction d pf starting point [, update rate] p pinc pinname filename d pind pinname d pinl d pq starting point [, update rate] p pr [clear data [, update rate] ] p prompt new prompt b quit b reload object filename b reset b restart rest b return ret d run [expression] d runb d runf d sa address p scolor area, attr1 [, attr2 [, attr3 [, attr4 ] ] ] d sconfig [filename] b sd address p setf [data type, display format ] d size [width, length ] b sl p sload object filename b sound on | off d sr p ssave [filename] d step [expression] d system [operating-system command [, flag ] ] b take batch filename [, suppress echo flag] b unalias alias name b use directory name b vaa filename p vac filename p p = profiler only b = both profiler and basic debugger 3 d = basic debugger only simulator only Summary of Debugger Commands version b vr p wa expression [, [ label], display format ] d wd index number d whatis symbol d win WINDOW NAME b wr d b zoom p = profiler only b = both profiler and basic debugger d = basic debugger only simulator only Border Styles (BORDER Command) Index Style 0 1 2 3 4 5 6 7 8 Double-lined box Single-lined box Solid 1/2-tone top, double-lined sides/bottom Solid 1/4-tone top, double-lined sides/bottom Solid box, thin border Solid box, heavy sides, thin top/bottom Solid box, heavy borders Solid 1/2-tone box Solid 1/4-tone box Colors and Attributes (COLOR/SCOLOR Commands) black red bright blue magenta green yellow blink cyan white Area Names (COLOR/SCOLOR Commands) menu_bar menu_border menu_entry menu_cmd menu_hilite menu_hicmd win_border win_hiborder win_resize field_text field_hilite field_edit field_label field_error cmd_prompt cmd_input cmd_cursor cmd_echo asm_data asm_cdata asm_label asm_clabel background blanks error_msg file_line file_eof file_text file_brk file_pc file_pc_brk 4 Memory Types To identify this kind of memory Use this keyword as the type parameter read-only memory R, ROM, or READONLY write-only memory W, WOM, or WRITEONLY read/write memory R|W or RAM no-access memory PROTECT input port IPORT or IN PORT output port OPORT or OUT PORT input/output port IOPORT Display Formats (?, DISP, MEM, SETF, and WA Commands) Para- Result meter Para- Result meter * Default for the data type o Octal c ASCII character (bytes) p Valid address d Decimal s ASCII string e Exponential floating point u Unsigned decimal f Decimal floating point x Hexadecimal ?, DISP, SETF, and WA commands only Switching Modes Use this function key To do this Switch debugging modes in this order: auto assembly mixed Running Code Use these function keys To do this Run code from the current PC Single-step from the current PC Single-step code from the current PC; step over function calls 5 Selecting or Closing a Window Use these function keys To do this Select the active window Close the CALLS or DISP window Editing Text on the Command Line Use these function keys To do this Enter the current command Move back over text without erasing characters or Move forward through text without erasing characters Move back over text while erasing characters Move forward through text while erasing characters Insert text into the characters that are already on the command line Using the Command History Use these function keys To do this Repeat the last command that you entered Move backward, one command at a time, through the command history Move forward, one command at a time, through the command history Editing Data or Selecting the Active Field Use this function key To do this FILE or DISASSEMBLY window: Set or clear a breakpoint CALLS window: Display the source to a listed function Any data-display window: Edit the contents of the current field DISP window: Open an additional DISP window 6 Halting or Escaping From an Action Use this function key To do this Halt program execution Close a pulldown menu Undo an edit of the active field in a data-display window Halt the display of a long list of data Displaying Pulldown Menus Use these function keys To do this Display the Load menu Display the Break menu Display the Watch menu Display the Memory menu Display the Color menu Display the MoDe menu Display the Pin menu P Display an adjacent menu or Execute any of the choices from a displayed pulldown menu Press the highlighted letter cor sponding to you choice Moving or Sizing a Window Enter the MOVE or SIZE command without parameters, then use the arrow keys: Use these function keys To do this Move the window down one line Make the window one line longer Move the window up one line Make the window one line shorter Move the window left one character position Make the window one character narrower Move the window right one character position Make the window one character wider 7 Scrolling the Active Window's Contents Use these function keys To do this Scroll up through the window contents, one window length at a time Scroll down through the window contents, one window length at a time Move the field cursor up one line at a time Move the field cursor down one line at a time FILE window only: Scroll left 8 characters at a time Other windows: Move the field cursor left 1 field; at the first field on a line, wrap back to the last fully displayed field on the previous line FILE window only: Scroll right 8 characters at a time Other windows: Move the field cursor right 1 field; at the last field on a line, wrap around to the first field on the next line FILE window only: Adjust the window's contents so that the first line of the text file is at the top of the window FILE window only: Adjust the window's contents so that the last line of the text file is at the bottom of the window DISP windows only: Scroll up through an array of structures DISP windows only: Scroll down through an array of structures 8 Phone Number DSP Hotline: (713) 274­2320 TMS320C3x C Source Debugger Profiler Reference Card Entering the Profiling Environment The profiling evironment is supported under all platforms except DOS. Basic Profiling Commands Emulator: EVM: Simulator: Running a Profiling Session Command Description pf starting point [, update rate] emu3x ­profile evm30 ­profile sim3x ­profile Run a full profiling session pq starting point [, update rate] Run a quick profiling session pr [clear data [, update rate] ] Resume a profilng session that has halted Debugger Commands That Can Be Used in the Profiling Environment SLOAD ALIAS MA PROMPT SYSTEM CD MAP QUIT TAKE MC RELOAD UNALIAS MD RESET USE DIR Defining Stopping Points MR DASM Resume a profilng session that has halted LOAD CLS pr [clear data [, update rate] ] ? MI RESTART VERSION Command Description EVAL ML SCONFIG WIN sa address Add a stopping point FILE MOVE SIZE ZOOM sd address Delete a stopping point sr Delete all the stopping points sl View a list of all current stopping points FUNC Debugger Commands That Can't Be Used in the Profiling Environment vac filename Save the contents of the PROFILE window to a system file vaa filename Save all data for the current view RUNF COLOR NEXT SCOLOR CSTEP PINC SSAVE BD Description MS BA Command CNEXT ASM Saving Profile Data to a File ADDR DISP PIND STEP BL FILL PINL WA BORDER GO RETURN WD BR HALT RUN WHATIS C MEM RUNB WR CALLS MIX Marking Areas To mark this area C only Disassembly only Lines By line number, address All lines in a function MCLE filename, line number MALE address MCLF function MALF function MCRE filename, line number, line number MARE address, address MCFE function not applicable Ranges By line numbers Functions By function name All functions in a module All functions everyhwhere MCFM filename MCFG Disabling Marked Areas To disable this area Lines By line number, address All lines in a function All lines in a module All lines everywhere Ranges By line numbers, addresses All ranges in a function All ranges in a module All ranges everywhere Functions By function name All functions in a module All functions everyhwhere All areas All areas in a function All areas in a module All areas everyhwhere C only Disassembly only C and Disassembly DCLE filename, line number DALE address not applicable DCLF function DALF function DBLF function DCLM filename DALM filename DBLM filename DCLG DALG DBLG DCRE filename, line number DARE address not applicable DCRF function DARF function DBRF function DCRM filename DARM filename DBRM filename DCRG DARG DBRG DCFE function not applicable not applicable DCFM filename DBFM filename DCFG DBFG DCAF function DAAF function DBAF function DCAM filename DAAM filename DBAM filename DCAG DAAG DBAG Enabling Disabled Areas To disable this area Lines By line number, address All lines in a function All lines in a module All lines everywhere Ranges By line numbers, addresses All ranges in a function All ranges in a module All ranges everywhere Functions By function name All functions in a module All functions everyhwhere All areas All areas in a function All areas in a module All areas everyhwhere C only Disassembly only C and Disassembly ECLE filename, line number EALE address not applicable ECLF function EALF function EBLF function ECLM filename EALM filename EBLM filename ECLG EALG EBLG ECRE filename, line number EARE address not applicable ECRF function EARF function EBRF function ECRM filename EARM filename EBRM filename ECRG EARG EBRG ECFE function not applicable not applicable ECFM filename EBFM filename ECFG EBFG ECAF function EAAF function EBAF function ECAM filename EAAM filename EBAM filename ECAG EAAG EBAG C only Disassembly only C and Disassembly UCLE filename, line number UALE address not applicable UCLF function UALF function UBLF function UCLM filename UALM filename UBLM filename UCLG UALG UBLG UCRE filename, line number UARE address not applicable UCRF function UARF function UBRF function UCRM filename UARM filename UBRM filename UCRG UARG UBRG UCFE function not applicable Unmarking Areas To disable this area Lines By line number, address All lines in a function All lines in a module All lines everywhere Ranges By line numbers, addresses All ranges in a function All ranges in a module All ranges everywhere Functions By function name All functions in a module All functions everyhwhere All areas All areas in a function All areas in a module All areas everyhwhere not applicable UCFM filename UBFM filename UCFG UBFG UCAF function UAAF function UBAF function UCAM filename UAAM filename UBAM filename UCAG UAAG UBAG Changing the PROFILE Window Display Viewing specific areas To disable this area Lines By line number, address All lines in a function All lines in a module All lines everywhere Ranges By line numbers, addresses All ranges in a function All ranges in a module All ranges everywhere Functions By function name All functions in a module All functions everyhwhere All areas All areas in a function All areas in a module All areas everyhwhere C only Disassembly only C and Disassembly VFCLE filename, line number VFALE address not applicable VFCLF function VFALF function VFBLF function VFCLM filename VFALM filename VFBLM filename VFCLG VFALG VFBLG VFCRE filename, line number VFARE address not applicable VFCRF function VFARF function VFBRF function VFCRM filename VFARM filename VFBRM filename VFCRG VFARG VFBRG VFCFE function not applicable not applicable VFCFM filename VFBFM filename VFCFG VFBFG VFCAF function VFAAF function VFBAF function VFCAM filename VFAAM filename VFBAM filename VFCAG VFAAG VFBAG Viewing different data Sorting the data To view this information Use this command To sort on this data Use this command Count VDC Count VSC Inclusive VDI Inclusive VSI Inclusive, maximum VDN Inclusive, maximum VSN Exclusive VDE Exclusive VSE Exclusive, maximum VDX Exclusive, maximum VSX Address VDA Address VSA All VDL Data VSD IMPORTANT NOTICE Texas Instruments Incorporated (TI) reserves the right to make changes to its products or to discontinue any semiconductor product or service without notice, and advises its customers to obtain the latest version of relevant information to verify, before placing orders, that the information being relied on is current. TI warrants performance of its semiconductor products and related software to current specifications in accordance with TI's standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements. Please be aware that TI products are not intended for use in life-support appliances, devices, or systems. Use of TI product in such applications requires the written approval of the appropriate TI officer. Certain applications using semiconductor devices may involve potential risks of personal injury, property damage, or loss of life. In order to minimize these risks, adequate design and operating safeguards should be provided by the customer to minimize inherent or procedural hazards. Inclusion of TI products in such applications is understood to be fully at the risk of the customer using TI devices or systems. TI assumes no liability for applications assistance, customer product design, software performance, or infringement of patents or services described herein. Nor does TI warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such semiconductor products or services might be or are used. WARNING This equipment is intended for use in a laboratory test environment only. It generates, uses, and can radiate radio frequency energy and has not been tested for compliance with the limits of computing devices pursuant to subpart J of part 15 of FCC rules, which are designed to provide reasonable protection against radio frequency interference. Operation of this equipment in other environments may cause interference with radio communications, in which case the user at his own expense will be required to take whatever measures may be required to correct this interference. Copyright © 1993, Texas Instruments Incorporated Preface Read This First What Is This Book About? This book tells you how to use the TMS320C3x C source debugger with these debugging tools: - Emulator Evaluation module (EVM) Simulator All three tools support code development for both the TMS320C30 TMS320C30 and the TMS320C31 TMS320C31. Each tool has its own version of the debugger. These versions operate almost identically; however, the executable files that invoke them are very different. For example, the EVM version won't work with the emulator or simulator, and vice versa. Separate commands are provided for invoking each version of the debugger. There are two debugger environments: the basic debugger environment and the profiling environment. The basic debugger environment is a general-purpose debugging environment. The profiling environment is a special environment for collecting statistics about code execution. Both environments have the same easy-to-use interface. Before you use this book, you should read the appropriate installation guide to install the C source debugger and any necessary hardware. How to Use This Manual The goal of this book is to help you learn to use the Texas Instruments advanced programmer's interface for debugging. This book is divided into three distinct parts: - Part I: Hands-On Information is presented first so that you can start using your debugger the same day you receive it. J J Chapter 1 lists the key features of the debugger, describes additional 'C3x software tools, tells you how to prepare a 'C3x program for debugging, and provides instructions and options for invoking the debugger. Chapter 2 is a tutorial that introduces you to many of the debugger features. iii How to Use This Manual - - Part II: Debugger Description contains detailed information about using the debugger. The chapters in Part II detail the individual topics that are introduced in the tutorial. For example, Chapter 3 describes all of the debugger's windows and tells you how to move them and size them; Chapter 4 describes everything you need to know about entering commands. Part III: Reference Material provides supplementary information. J J J Chapter 11 provides a complete reference to all the tasks introduced in Parts I and II. This includes a functional and an alphabetical reference of the debugger commands and a topical reference of function key actions. Chapter 12 provides information about C expressions. The debugger commands are powerful because they accept C expressions as parameters; however, the debugger can also be used to debug assembly language programs. The information about C expressions will aid assembly language programmers who are unfamiliar with C. Part III also includes a glossary and an index. The way you use this book should depend on your experience with similar products. As with any book, it would be best for you to begin on page 1 and read to the end. Because most people don't read technical manuals from cover to cover, here are some suggestions about what you should read. - If you have used TI development tools or other debuggers before, then you may want to: J J J - If this is the first time that you have used a debugger or similar tool, then you may want to: J J J iv Read the introductory material in Chapter 1. Complete the tutorial in Chapter 2. Read through the alphabetical command reference in Chapter 11. Read the introductory material in Chapter 1. Complete the tutorial in Chapter 2. Read all of the chapters in Part II. Notational Conventions Notational Conventions This document uses the following conventions. - The TMS320C30 TMS320C30 and TMS320C31 TMS320C31 processors are referred to collectively as the 'C3x. The C source debugger has a very flexible command-entry system; there are a variety of ways to perform any specific action. For example, you may be able to perform the same action by typing in a command, using the mouse, or pressing function keys. There are three symbols to identify the methods that you can use to perform an action: Symbol Description Identifies an action that you perform by using the mouse. Identifies an action that you perform by using function keys. Identifies an action that you perform by typing in a command. - The following symbols identify mouse actions. For simplicity, these symbols represent a mouse with two buttons. However, you can use a mouse with only one button or a mouse with more than two buttons. Symbol Action Point. Without pressing a mouse button, move the mouse to point the cursor at a window or field on the display. (Note that the mouse cursor displayed on the screen is not shaped like an arrow; it's shaped like a block.) Press and hold. Press a mouse button. If your mouse has only one button, press it. If your mouse has more than one button, press the left button. Release. Release the mouse button that you pressed. Click. Press a mouse button and, without moving the mouse, release the button. Drag. While pressing the left mouse button, move the mouse. Read This First v Notational Conventions - Debugger commands are not case sensitive; you can enter them in lowercase, uppercase, or a combination. To emphasize this fact, commands are shown throughout this user's guide in both uppercase and lowercase. Program listings and examples, interactive displays, and window contents are shown in a special font. Some examples use a bold version to identify code, commands, or portions of an example that you enter. Here is an example: Command Result displayed in the COMMAND window whatis giant struct zzz giant[100]; whatis xxx struct xxx { int a; int b; int c; int f1 : 2; int f2 : 4; struct xxx *f3; int f4[10]; } In this example, the left column identifies debugger commands that you type in. The right column identifies the result that the debugger displays in the COMMAND window display area. - In syntax descriptions, the instruction or command is in a bold face font, and parameters are in italics. Portions of a syntax that are in bold face should be entered as shown; portions of a syntax that are in italics describe the kind of information that should be entered. Here is an example of a command syntax: mem expression [, display format ] mem is the command. This command has two parameters, indicated by expression and display format. The first parameter must be an actual C expression; the second parameter, which identifies a specific display format, is optional. - Square brackets ( [ and ] ) identify an optional parameter. If you use an optional parameter, you specify the information within the brackets; you don't enter the brackets themselves. Here's an example of a command that has an optional parameter: run [expression] The RUN command has one parameter, expression, which is optional. vi Notational Conventions / Information About Cautions / Related Documentation From Texas Instruments - Braces ( { and } ) indicate a list. The symbol | (read as or) separates items within the list. Here's an example of a list: sound {on | off} This provides two choices: sound on or sound off. Unless the list is enclosed in square brackets, you must choose one item from the list. Information About Cautions This is an example of a caution statement. A caution statement describes a situation that could potentially damage your software or equipment. Please read each caution statement carefully. Related Documentation From Texas Instruments The following books describe the TMS320C3x DSPs and related support tools. To obtain a copy of any of these TI documents, call the Texas Instruments Literature Response Center at (800) 477­8924. When ordering, please identify the book by its title and literature number. TMS320C3x User's Guide (literature number SPRU031 SPRU031) describes the 'C3x 32-bit floating-point microprocessor (developed for digital signal processing as well as general applications), its architecture, internal register structure, instruction set, pipeline, specifications, and DMA and serial port operation. Software and hardware applications are included. TMS320 TMS320 Floating-Point DSP Assembly Language Tools User's Guide (literature number SPRU035 SPRU035) describes the assembly language tools (assembler, linker, and other tools used to develop assembly language code), assembler directives, macros, common object file format, and symbolic debugging directives for the 'C3x and 'C4x generations of devices. TMS320 TMS320 Floating-Point DSP Optimizing C Compiler User's Guide (literature number SPRU024 SPRU024) describes the TMS320 TMS320 floating-point C compiler. This C compiler accepts ANSI standard C source code and produces TMS320 TMS320 assembly language source code for the 'C3x and 'C4x generations of devices. Read This First vii If You Need Assistance / Trademarks Digital Signal Processing Applications With the TMS320C30 TMS320C30 Evaluation Module Selected Application Notes (literature number SPRA021 SPRA021) contains useful information for people who are preparing and debugging code. The book gives additional information about the TMS320C30 TMS320C30 EVM, as well as C coding tips. TMS320C30 TMS320C30 Evaluation Module Technical Reference (literature number SPRU069 SPRU069) describes board-level operation of the TMS320C30 TMS320C30 EVM. If you are an assembly language programmer and would like more information about C or C expressions, you may find this book useful: The C Programming Language (second edition, 1988), by Brian W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New Jersey. If You Need Assistance. . . If you want to. . . Do this. . . Request more information about Texas Instruments Digital Signal Processing (DSP) products Write to: Texas Instruments Incorporated Market Communications Manager, MS 736 P.O. Box 1443 Houston, Texas 77251­1443 Order Texas Instruments documentation Call the TI Literature Response Center: (800) 477­8924 Ask questions about product operation or report suspected problems Call the DSP hotline: (713) 274­2320 FAX: (713) 274­2324 Report mistakes in this document or any other TI documentation Fill out and return the reader response card at the end of this book, or send your comments to: Texas Instruments Incorporated Technical Publications Manager, MS 702 P.O. Box 1443 Houston, Texas 77251­1443 Trademarks PC-DOS and OS/2 are trademarks of International Business Machines Corp. MS-DOS and MS-Windows are registered trademarks of Microsoft Corp. Motorola-S is a trademark of Motorola, Inc. SunOS, Sun-3, Sun-4, and OpenWindows are trademarks of Sun Microsystems, Inc. Tektronix is a trademark of Tektronix, Inc. UNIX is a registered trademark of Unix System Laboratories, Inc. viii Contents Contents Part I: Hands-On Information 1 Overview of a Code Development and Debugging System . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Discusses features of the debugger, describes additional software tools, and tells you how to invoke the debugger. 1.1 1.2 1.3 1.4 1.5 1.6 1.7 2 Description of the 'C3x C Source Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Key features of the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Description of the Profiling Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Key features of the profiling environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Developing Code for the 'C3x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Preparing Your Program for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Selecting the screen size (­b option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Identifying additional directories (­i option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Selecting the operating mode (­mm option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Selecting the device version (­mv option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Identifying the port address (­p option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Entering the profiling environment (­profile option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Loading the symbol table only (­s option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Identifying a new initialization file (­t option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Loading without the symbol table (­v option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Ignoring D_OPTIONS (­x option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Exiting the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 Debugging 'C3x Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16 An Introductory Tutorial to the C Source Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 This chapter provides a step-by-step introduction to the debugger and its features. How to use this tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A note about entering commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . An escape route (just in case) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoke the debugger and load the sample program's object code . . . . . . . . . . . . . . . . . . . . . . . Take a look at the display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What's in the DISASSEMBLY window? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents 2-2 2-2 2-3 2-3 2-4 2-5 ix Contents Select the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Size the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Zoom the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Move the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 Scroll through a window's contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Display the C source version of the sample file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Execute some code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Become familiar with the three debugging modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Open another text file, then redisplay a C source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 Use the basic RUN command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 Set some breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 Watch some values and single-step through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Run code conditionally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 WHATIS that? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19 Clear the COMMAND window display area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20 Display the contents of an aggregate data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20 Display data in another format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 Change some values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 Define a memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26 Define your own command string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 Close the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 Part II: Debugger Description 3 The Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Describes the default displays, tells you how to switch between assembly language and C debugging, describes the various types of windows on the display, and tells you how to move and size the windows. 3.1 3.2 x Debugging Modes and Default Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Auto mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Assembly mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Mixed mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Restrictions associated with debugging modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Descriptions of the Different Kinds of Windows and Their Contents . . . . . . . . . . . . . . . . 3-5 COMMAND window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 DISASSEMBLY window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 FILE window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 CALLS window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 PROFILE window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 MEMORY windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 CPU window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 DISP windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16 WATCH window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17 Contents 3.3 3.4 3.5 3.6 3.7 4 Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Active Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manipulating Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resizing a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Zooming a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manipulating a Window's Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scrolling through a window's contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the data displayed in windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Closing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 3-19 3-19 3-20 3-21 3-21 3-23 3-24 3-26 3-26 3-28 3-29 Entering and Using Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Describes the rules for entering commands from the command line, tells you how to use the pulldown menus and dialog boxes (for entering parameter values), describes general information about entering commands from batch files, and describes the use of DOS-like system commands. 4.1 4.2 4.3 4.4 4.5 4.6 Entering Commands From the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 How to type in and enter commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Sometimes, you can't type a command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 Using the command history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Clearing the display area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Recording information from the display area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Using the Menu Bar and the Pulldown Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Pulldown menus in the profiling environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 Using the pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 Escaping from the pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 Using menu bar selections that don't have pulldown menus . . . . . . . . . . . . . . . . . . . . . 4-10 Using Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 Entering text in a dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 Entering Commands From a Batch File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Echoing strings in a batch file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Controlling command execution in a batch file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Defining Your Own Command Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17 Entering Operating-System Commands (DOS Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19 Entering a single command from the debugger command line . . . . . . . . . . . . . . . . . . . 4-19 Entering several commands from a system shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20 Additional system commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20 Contents xi Contents 5 Defining a Memory Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Contains instructions for setting up a memory map that will enable the debugger to correctly access target memory, includes hints about using batch files, and tells you how to simulate I/O ports for use with the simulator version of the debugger. 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 6 Loading, Displaying, and Running Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 Tells you how to use the three debugger modes to view the type of source files that you'd like to see, how to load source files and object files, how to run your programs, and how to halt program execution. 6.1 6.2 6.3 6.4 xii The Memory Map: What It Is and Why You Must Define It . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Defining the memory map in a batch file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Potential memory map problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Sample Memory Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Identifying Usable Memory Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 Memory mapping with the simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 Enabling Memory Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 Checking the Memory Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10 Modifying the Memory Map During a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . 5-11 Returning to the original memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12 Using Multiple Memory Maps for Multiple Target Systems . . . . . . . . . . . . . . . . . . . . . . . 5-12 Simulating Serial Ports (Simulator Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 Simulating I/O Space (Simulator Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 Connecting an I/O port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 Configuring memory to use serial port simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15 Disconnecting an I/O port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15 Simulating External Interrupts (SImulator Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 Setting up your input file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 Programming the simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18 Code-Display Windows: Viewing Assembly Language Code, C Code, or Both . . . . . . 6-2 Selecting a debugging mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Displaying Your Source Programs (or Other Text Files) . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Displaying assembly language code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Modifying assembly language code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Additional information about modifying assembly language code . . . . . . . . . . . . . . . . . . 6-7 Displaying C code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 Displaying other text files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Loading Object Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 Loading code while invoking the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 Loading code after invoking the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 Where the Debugger Looks for Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 Contents 6.5 6.6 6.7 7 6-12 6-12 6-13 6-14 6-16 6-17 6-18 6-19 Managing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 Describes the data-display windows and tells you how to edit data (memory contents, register contents, and individual variables). 7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8 7.9 8 Running Your Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining the starting point for program execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single-stepping through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running code while disconnected from the target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running code conditionally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Halting Program Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Benchmarking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where Data Is Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Basic Commands for Managing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Basic Methods for Changing Data Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Editing data displayed in a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Advanced "editing"-using expressions with side effects . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 Managing Data in Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Displaying memory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Displaying memory contents while you're debugging C . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8 Saving memory values to a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9 Filling a block of memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9 Managing Register Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 Displaying register contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 Accessing extended-precision registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11 Managing Data in a DISP (Display) Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12 Displaying data in a DISP window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12 Closing a DISP window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 Managing Data in a WATCH Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 Displaying data in the WATCH window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15 Deleting watched values and closing the WATCH window . . . . . . . . . . . . . . . . . . . . . . . 7-16 Monitoring the Pipeline (Simulator Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17 Displaying Data in Alternative Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18 Changing the default format for specific data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18 Changing the default format with ?, MEM, DISP, and WA . . . . . . . . . . . . . . . . . . . . . . . 7-20 Using Software Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 Describes the use of software breakpoints to halt code execution. 8.1 8.2 8.3 Setting a Software Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 Clearing a Software Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Finding the Software Breakpoints That Are Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 Contents xiii Contents 9 Customizing the Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Contains information about the commands that you can use for customizing the display and identifies the display areas that you can modify. 9.1 9.2 9.3 9.4 Changing the Colors of the Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 Area names: common display areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 Area names: window borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Area names: COMMAND window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Area names: DISASSEMBLY and FILE windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5 Area names: data-display windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Area names: menu bar and pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7 Changing the Border Styles of the Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8 Saving and Using Custom Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9 Changing the default display for monochrome monitors . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9 Saving a custom display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9 Loading a custom display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10 Invoking the debugger with a custom display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 Returning to the default display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 Changing the Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 10 Profiling Code Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 Describes the profiling environment and tells you how to collect statistics about code execution. 10.1 10.2 10.3 10.4 10.5 10.6 10.7 xiv An Overview of the Profiling Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 A profiling strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 Entering the Profiling Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Restrictions of the profiling environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Using pulldown menus in the profiling environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4 Defining Areas for Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5 Marking an area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5 Disabling an area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7 Re-enabling a disabled area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10 Unmarking an area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11 Restrictions on profiling areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12 Defining a Stopping Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13 Running a Profiling Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15 Viewing Profile Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17 Viewing different profile data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17 Data accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19 Sorting profile data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19 Viewing different profile areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19 Interpreting session data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20 Viewing code associated with a profile area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21 Saving Profile Data to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22 Contents Part III: Reference Material 11 Summary of Commands and Special Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 Provides a functional summary of the debugger commands, profiling commands, and function keys; also provides a complete alphabetical summary of all debugger commands. 11.1 11.2 11.3 11.4 11.5 Functional Summary of Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 Changing modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 Managing windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 Displaying and changing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 Performing system tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4 Displaying files and loading programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 Managing breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 Customizing the screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5 Memory mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 Running programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7 Profiling commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8 How the Menu Selections Correspond to Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8 Program-execution commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9 File/load commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9 Breakpoint commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9 Watch commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9 Memory commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10 Screen-configuration commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10 Mode commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10 Interrupt-simulation commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10 Alphabetical Summary of Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11 Summary of Profiling Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-48 Summary of Special Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-52 Editing text on the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-52 Using the command history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-52 Switching modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-53 Halting or escaping from an action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-53 Displaying pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-53 Running code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-54 Selecting or closing a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-54 Moving or sizing a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-54 Scrolling a window's contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-55 Editing data or selecting the active field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-55 Contents xv Contents 12 Basic Information About C Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1 Many of the debugger commands accept C expressions as parameters. This chapter provides general information about the rules governing C expressions and describes specific implementation features related to using C expressions as command parameters. 12.1 12.2 A 12-2 12-4 12-4 12-4 Specifications for Your Target System's Connection to the Emulator . . . . . . . . . . . . . . . . A-1 Contains information about constructing a 12-pin connector on your target system and information about connecting the target system to the emulator. A.1 A.2 A.3 A.4 B C Expressions for Assembly Language Programmers . . . . . . . . . . . . . . . . . . . . . . . . . . Using Expression Analysis in the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Designing Your Target System's Emulator Connector (12-Pin Header) . . . . . . . . . . . . . Buffering Signals Between the Emulator and the Target System . . . . . . . . . . . . . . . . . . Buffer Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mechanical Dimensions for the 12-Pin Emulator Connector . . . . . . . . . . . . . . . . . . . . . . A-2 A-3 A-4 A-6 Constraints When Using the Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Covers cache control and command constraints when using the debugger with the emulator. B.1 B.2 B.3 Cache Interaction With Software Breakpoint Commands . . . . . . . . . . . . . . . . . . . . . . . . . Cache Control for Memory Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Software breakpoint constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single-step constraints with repeated instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constraints imposed when emulator is reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 B-3 B-4 B-4 B-5 B-5 C Troubleshooting When Using the Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1 Contains information that is helpful when using the debugger with the emulator. D What the Debugger Does During Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1 In some circumstances, you may find it helpful to know the steps that the debugger goes through during the invocation process; this appendix lists these steps. E Debugger Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1 Describes progress and error messages that the debugger may display. E.1 E.2 E.3 E.4 F xvi Associating Sound With Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2 Alphabetical Summary of Debugger Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2 Additional Instructions for Expression Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-20 Additional Instructions for Hardware Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-20 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1 Defines acronyms and key terms used in this book. Running Title-Attribute Reference Figures 1­1 1­2 1­3 1­4 3­1 3­2 3­3 3­4 3­5 4­1 4­2 4­3 5­1 5­2 5­3 10­1 A­1 A­2 A­3 A­4 A­5 The Basic Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 The Profiling-Environment Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 'C3x Software Development Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Steps You Go Through to Prepare a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Typical Assembly Display (for Auto Mode and Assembly Mode) . . . . . . . . . . . . . . . . . . . . . 3-2 Typical C Display (for Auto Mode Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Typical Mixed Display (for Mixed Mode Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 The Default and Additional MEMORY Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13 Default Appearance of an Active and an Inactive Window . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 The COMMAND Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 The Menu Bar in the Basic Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 All of the Pulldown Menus (Basic Debugger Display) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Sample Memory Map for Use With a 'C3x Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Sample Memory Map for Use With a 'C3x Application Board / Emulator . . . . . . . . . . . . . . 5-5 Sample Memory Map for Use With a 'C3x EVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 An Example of the PROFILE Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17 12-Pin Header Signals and Header Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 H3 Buffer Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4 Emulator Pod Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5 Pod/Connector Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6 12-Pin Connector Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7 Contents xvii Running Title-Attribute Reference Tables 1­1 1­2 4­1 7­1 7­2 7­3 9­1 9­2 10­1 10­2 10­3 10­4 10­5 10­6 10­7 11­1 11­2 11­3 11­4 11­5 A­1 A­2 xviii Summary of Debugger Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Screen Size Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Predefined Constants for Use With Conditional Commands . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Pipeline Pseudoregisters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17 Display Formats for Debugger Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18 Data Types for Displaying Debugger Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19 Colors and Other Attributes for the COLOR and SCOLOR Commands . . . . . . . . . . . . . . . 9-2 Summary of Area Names for the COLOR and SCOLOR Commands . . . . . . . . . . . . . . . . . 9-3 Debugger Commands That Can/Can't Be Used in the Profiling Environment . . . . . . . . . 10-3 Menu Selections for Marking Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7 Menu Selections for Disabling Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9 Menu Selections for Enabling Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10 Menu Selections for Unmarking Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12 Types of Data Shown in the PROFILE Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18 Menu Selections for Displaying Areas in the PROFILE Window . . . . . . . . . . . . . . . . . . . 10-20 Marking Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-48 Disabling Marked Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-48 Enabling Disabled Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-49 Unmarking Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-50 Changing the PROFILE Window Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-51 12-Pin Header Signal Description and Pin Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Maximum Buffer Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4 Running Title-Attribute Reference Chapter 1 Overview of a Code Development and Debugging System The TMS320C3x C source debugger is an advanced programmer's interface that helps you to develop, test, and refine 'C3x C programs (compiled with the 'C3x optimizing ANSI C compiler) and assembly language programs. The debugger is the interface to the 'C3x simulator, EVM, and unique scan-based, realtime emulator. This chapter gives an overview of the programmer's interface, describes the 'C3x code development environment, and provides instructions and options for invoking the debugger. Topic Page 1.1 Description of the 'C3x C Source Debugger Key features of the debugger 1-2 1-3 1.2 Description of the Profiling Environment Key features of the profiling environment 1-5 1-5 1.3 Developing Code for the 'C3x 1-7 1.4 Preparing Your Program for Debugging 1-10 1.5 Invoking the Debugger Selecting the screen size (­b option) Identifying additional directories (­i option) Selecting the operating mode (­mm option) Selecting the device version (­mv option) Identifying the port address (­p option) Entering the profiling environment (­profile option) Loading the symbol table only (­s option) Identifying a new initialization file (­t option) Loading without the symbol table (­v option) Ignoring D_OPTIONS (­x option) 1-12 1-13 1-13 1-13 1-14 1-14 1-14 1-14 1-15 1-15 1-15 1.6 Exiting the Debugger 1-15 1.7 Debugging 'C3x Programs 1-16 Chapter Title-Attribute Reference 1-1 Description of the 'C3x C Source Debugger 1.1 Description of the 'C3x C Source Debugger The 'C3x C source debugger interface improves productivity by allowing you to debug a program in the language it was written in. You can choose to debug your programs in C, assembly language, or both. And, unlike many other debuggers, the 'C3x debugger's higher level features are available even when you're debugging assembly language code. The Texas Instruments advanced programmer's interface is easy to learn and use. Its friendly window-, mouse-, and menu-oriented interface reduces learning time and eliminates the need to memorize complex commands. The debugger's customizable displays and flexible command entry let you develop a debugging environment that suits your needs-you won't be locked into a rigid environment. A shortened learning curve and increased productivity reduce the software development cycle, so you'll get to market faster. Figure 1­1 identifies several features of the debugger display. Figure 1­1. The Basic Debugger Display pulldown menus disassembly display C source display interactive command entry and history window 1-2 Load Break Watch Memory Color MoDe Pin Run=F5 Step=F8 Next=F10 DISASSEMBLY CPU CALLS PC 00f00035 00002d 62f00042 CALL xcall 2: call() SP 00f0207c 00002e 19840001 SUBI 1,SP 1: main() R0 00000001 00002f 6a00000c BU call+30 90xf0003c) R1 00f00009 000030 08510b02 LDI *_AR3(2),IR0 R2 00000007 WATCH 000031 02f10003 AND 3,IR0 R3 00000003 1: str.a 0 000032 08282051 LDI @02051H 02051H,AR0 2: F0 1.000000e R4 00000003 000033 04f10003 CMPI 3,IR0 R5 00000000 3: color GREEN 000034 51f10004 LDIHI 4,IR0 R6 00000000 000035 08484011 LDI *+AR0(IR0),AR0 R7 00000000 000036 FILE: sample.c BU 68000008 AR) AR0 00f00037 000037 00052 } 00f00021 ABSI 33,DP AR1 00000008 000038 00053 00f00024 ABSI 36,DP AR2 00000000 000039 00054 call(newvalue) 00f0 AR3 00f0207c 00003a 00055 int newvalue; 00f0 AR4 00000000 00003b 00056 { 00f0 static int value = 0; AR5 00000000 00003c 00057 0840 AR6 00000000 00003d 00058 1520 00059 switch (newvalue & 3) AR7 00000000 00060 { IR0 00000003 00061 case 0 : str.a = newvalue ; break; IR1 MEMORY 00000000 00062 case 1 : str.b = newvalue + 1; return DISP: astr[7] ST 00000024 f0207c 00f02076 00063 case 2 : str.c = 123 newvalue * 2; a RC 00000000 f0207d 00000002 00064 case 3 : xcall(newvalue); break; b 555 RS 00f00064 f0207e 00f0002e 00065 } c 75435 DISP: astr[7].f4 RE 00f00064 f0207f 00f0207c 00066 f1 3 [0] 0 DP 000000f0 f02080 d363ae8a f2 6 [1] 9 BK 00000000 f02081 379d0aaa f3 0x00f000a [2] 7 IE 00000000 f02082 fe3567bb f4 [.] [3] 54 IF 00000000 f02083 9bfa3b3a [4] 3 IOF 00000088 f02084 fb6a2e2a COMMAND [5] 3 f02085 32bababa whatis str [6] 4 f02086 9cb5a158 [7] 123 f02087 fabe82a8 struct xxx str; [8] 4 f02088 8ea99a24 step [9] 789 f02089 8644d8a1 f0208a 8ab705b5 >>> f0208b 52b9188c function call traceback natural-format data displays scrolling data displays with on-screen, interactive editing Description of the 'C3x C Source Debugger Key features of the debugger - Multilevel debugging. The debugger allows you to debug both C and assembly language code. If you're debugging a C program, you can choose to view just the C source, the disassembly of the object code created from the C source, or both. You can also use the debugger as an assembly language debugger. Fully configurable, state-of-the-art, window-oriented interface. The C source debugger separates code, data, and commands into manageable portions. Use any of the default displays. Or, select the windows you want to display, size them, and move them where you want them. Comprehensive data displays. You can easily create windows for displaying and editing the values of variables, arrays, structures, pointers- any kind of data-in their natural format (float, int, char, enum, or pointer ). You can even display entire linked lists. WATCH DISP: str 1: str.a 0 a 123 2: F0 1.000000e b 0 3: color GREEN c 75435 DISP: *str.f3 f1 3 a 8327 f2 6 b 666 f3 0x00f000a 87213 DISP: *str.f3­>f3 c a 75 f4 [.] f1 45 b 3212 f2 27 c f3 0x00f000a 782 f4 [.] f1 7 f2 9 f3 0x00f000a f4 [.] - On-screen editing. Change any data value displayed in any window- just point the mouse, click, and type. Continuous update. The debugger continuously updates information on the screen, highlighting changed values. Powerful command set. Unlike many other debugging systems, this debugger doesn't force you to learn a large, intricate command set. The 'C3x C source debugger supports a small but powerful command set that makes full use of C expressions. One debugger command performs actions that would take several commands in another system. Overview of a Code Development and Debugging System 1-3 Description of the 'C3x C Source Debugger - - Flexible command entry. There are a variety of ways to enter commands. You can type commands or use a mouse, function keys, or the pulldown menus; choose the method that you like best. Want to re-enter a command? No need to retype it-simply use the command history. Create your own debugger. The debugger display is completely configurable, allowing you to create the interface that is best suited for your use. J J J If you're using a color display, you can change the colors of any area on the screen. You can change the physical appearance of display features such as window borders. You can interactively set the size and position of windows in the display. Create and save as many custom configurations as you like, or use the defaults. Use the debugger with a color display or a black-and-white display. A color display is preferable; the various types of information on the display are easier to distinguish when they are highlighted with color. - - 1-4 Variety of screen sizes. The debugger's default configuration is set up for a typical PC display, with 25 lines by 80 characters. If you use a sophisticated graphics card, you can take advantage of the debugger's additional screen sizes. A larger screen size allows you to display more information and provides you with more screen space for organizing the display- bringing the benefits of workstation displays to your PC. All the standard features you expect in a world-class debugger. The debugger provides you with complete control over program execution with features like conditional execution and single-stepping (including singlestepping into or over function calls). You can set or clear a breakpoint with a click of the mouse or by typing commands. You can define a memory map that identifies the portions of target memory that the debugger can access. You can choose to load only the symbol table portion of an object file to work with systems that have code in ROM. The debugger can execute commands from a batch file, providing you with an easy method for entering often-used command sequences. Description of the Profiling Environment 1.2 Description of the Profiling Environment In addition to the basic debugging environment, a second environment-the profiling environment-is available. The profiling environment provides a method for collecting execution statistics about specific areas in your code. This gives you immediate feedback on your application's performance. The profiler is not available when you're running the debugger under DOS. Figure 1­2 identifies several features of the debugger display within the profiling environment. Figure 1­2. The Profiling-Environment Display profiling areas are clearly marked PROFILE window displays execution statistics mAp Enable Disable Unmark View Stop­points Load Mark DISASSEMBLY f00001 080b0014 RE> LDI SP,AR3 f00002 02750002 ADDI 2,SP f00003 0f240000 PUSH R4 f00004 08640000 LDI 0,R4 f00005 15440301 STI R4,*+AR3(1) f00006 15440302 STI R4,*+AR3(2) f00007 62f00057 CALL meminit f00008 08640000 LDI 0,R4 f00009 0f240000 meminit(); 00059 RE> for (i = 0; i < 0x50000; 00060 { 00061 call(i); 00062 if (i & j) j += i; 00063 aai[k][k] = j; 00064 >> pulldown menu provides access to often-used basic debugger commands plus special profiling commands profiling areas are clearly marked Key features of the profiling environment The profiling environment builds on the same easy-to-use interface available in the basic debugging environment and provides these additional features: - More efficient code. Within the profiling environment, you can quickly identify busy sections in your programs. This helps you to direct valuable development time toward streamlining the sections of code that most dramatically affect program performance. Overview of a Code Development and Debugging System 1-5 Description of the Profiling Environment - Statistics on multiple areas. You can collect statistics about individual statements in disassembly or C, about ranges in disassembly or C, and about C functions. When you are collecting statistics on many areas, you can choose to view the statistics for all the areas or a subset of the areas. Comprehensive display of statistics. The profiler provides all the information you need for identifying bottlenecks in your code: J J J - 1-6 The number of times each area was entered during the profiling session. The total execution time of an area, including or excluding the execution time of any subroutines called from within the area. The maximum time for one iteration of an area, including or excluding the execution time of any subroutines called from within the area. Statistics may be updated continuously during the profiling session or at selected intervals. Configurable display of statistics. Display the entire set of data, or display one type of data at a time. Display all the areas you're profiling, or display a selected subset of the areas. Visual representation of statistics. When you choose to display one type of data at a time, the statistics will be accompanied by histograms for each area, showing the relationship of each area's statistics to those of the other profiled areas. Disabled areas. In addition to identifying areas that you can collect statistics on, you can also identify areas that you don't want to affect the statistics. This removes the timing impact from code such as a standard library function or a fully optimized portion of code. Special profiling commands. The profiling environment supports a rich set of commands to help you select areas and display information. Some of the basic debugger commands-such as the memory map commands-may be necessary during profiling and are available within the profiling environment. Other commands-such as breakpoint commands and run commands-are not necessary and are therefore not available within the profiling environment. Developing Code for the 'C3x 1.3 Developing Code for the 'C3x The 'C3x is well supported by a complete set of hardware and software development tools, including a C compiler, assembler, and linker. Figure 1­3 illustrates the 'C3x code development flow. The most common paths of software development are highlighted in grey; the other portions are optional. Figure 1­3. 'C3x Software Development Flow C source files C compiler assembler source macro library assembler COFF object files library of object files linker hex conversion utility runtime support library executable COFF file debugging tools hexadecimal object file EPROM programmer 'C3x target system Overview of a Code Development and Debugging System 1-7 Developing Code for the 'C3x These tools use common object file format (COFF), which encourages modular programming. COFF allows you to divide your code into logical blocks, define your system's memory map, and then link code into specific memory areas. COFF also provides rich support for source-level debugging. The following list describes the tools shown in Figure 1­3. C compiler The 'C3x optimizing ANSI C compiler is a full-featured optimizing compiler that translates standard ANSI C programs into 'C3x assembly language source. Key characteristics include: - - - 1-8 Standard ANSI C. The ANSI standard is a precise definition of the C language, agreed upon by the C community. The standard encompasses most of the recent extensions to C. To an increasing degree, ANSI conformance is a requirement for C compilers in the DSP community. Optimization. The compiler uses several advanced techniques for generating efficient, compact code from C source. Assembly language output. The compiler generates assembly language source that you can inspect (and modify, if desired). ANSI standard runtime support. The compiler package comes with a complete runtime library that conforms to the ANSI C library standard. The library includes functions for string manipulation, dynamic memory allocation, data conversion, timekeeping, trigonometry, exponential operations, and hyperbolic functions. Functions for I/O and signal handling are not included, because they are application specific. Flexible assembly language interface. The compiler has straightforward calling conventions, allowing you to easily write assembly and C functions that call each other. Shell program. The compiler package includes a shell program that enables you to compile, assemble, and link programs in a single step. Source interlist utility. The compiler package includes a utility that interlists your original C source statements into the assembly language output of the compiler. This utility provides you with an easy method for inspecting the assembly code generated for each C statement. Developing Code for the 'C3x assembler linker debugging tools The assembler translates 'C3x assembly language source files into machine language object files. The linker combines object files into a single, executable object module. As the linker creates the executable module, it performs relocation and resolves external references. The linker is a tool that allows you to define your system's memory map and to associate blocks of code with defined memory areas. The main purpose of the development process is to produce a module that can be executed in a 'C3x target system. You can use one of several debugging tools to refine and correct your code. Available products include: hex conversion utility A realtime in-circuit emulator, An evaluation module (EVM), and A software simulator. A hex conversion utility is also available; it converts a COFF object file into an ASCII-Hex, Intel, Motorola-S, Tektronix, or TI-tagged object-format file that can be downloaded to an EPROM programmer. Overview of a Code Development and Debugging System 1-9 Preparing Your Program for Debugging 1.4 Preparing Your Program for Debugging Figure 1­4 illustrates the steps you must go through to prepare a program for debugging. Figure 1­4. Steps You Go Through to Prepare a Program If you're working with a C program, start here C source C Compiler If you're working with an assembly language program, start here assembly language code Assembler object code Linker This is the file that you load when you invoke the debugger If you're preparing to debug a C program. . . executable object code 1) Compile the program; use the ­g option. If you plan to use the profiler, compile the program with the ­as option. 2) Assemble the resulting assembly language program. 3) Link the resulting object file. This produces an object file that you can load into the debugger. If you're preparing to debug an assembly language program. . . 1) Assemble the assembly language source file. 2) Link the resulting object file. This produces an object file that you can load into the debugger. You can compile, assemble, and link a program by invoking the compiler, assembler, and linker in separate steps, or you can perform all three actions in a single step by using the cl30 shell program. The TMS320 TMS320 Floating-Point DSP Assembly Language Tools User's Guide and TMS320 TMS320 Floating-Point DSP Optimizing C Compiler User's Guide contain complete instructions for invoking the tools individually and for using the shell program. 1-10 Preparing Your Program for Debugging For your convenience, here's the command for invoking the shell program when preparing a program for debugging: cl30 [­options] ­g [filenames] [­z [link options]] cl30 is the command that invokes the compiler and assembler. options affect the way the shell processes input files. If you plan to use the debugger's profiling environment, include the ­as option. filenames are one or more C source files, assembly language source files, or object files. Filenames are not case sensitive. ­g is an option that tells the C compiler to produce symbolic debugging information. When preparing a C program for debugging, you must use the ­g option. ­z is an option that invokes the linker. After compiling/assembling your programs, you can invoke the linker in a separate step. If you want the shell to automatically invoke the linker, however, use ­z. link options affect the way the linker processes input files; use these options only when you use ­z. Options and filenames can be specified in any order on the command line, but if you use ­z, it must follow all C/assembly language source filenames and compiler options. The shell identifies a file's type by the filename's extension. Extension File Type File Description .c C source compiled, assembled, and linked .asm assembly language source assembled and linked .s* (any extension that begins with s) assembly language source assembled and linked .o* (extension begins with o) object file linked none (.c assumed) C source compiled, assembled, and linked Overview of a Code Development and Debugging System 1-11 Invoking the Debugger 1.5 Invoking the Debugger Here's the basic format for the commands that invoke the debugger: emulator: emu3x [filename] [­options] EVM: evm30 [filename] [­options] simulator: sim3x [filename] [­options] emu3x, evm30 sim3x are the commands that invoke the debugger. filename is an optional parameter that names an object file that the debugger will load into memory during invocation. The debugger looks for the file in the current directory; if the file isn't in the current directory, you must supply the entire pathname. If you don't supply an extension for the filename, the debugger assumes that the extension is .out, unless you're using multiple extensions; you must specify the entire filename if the filename has more than one extension. ­options supply the debugger with additional information (Table 1­1 summarizes the available options). You can also specify filename and option information with the D_OPTIONS environment variable (see Setting up the environment variables in the appropriate installation guide). Table 1­1 lists the debugger options and specifies which debugger tools use the options; the subsections following the table describe the options. Table 1­1. Summary of Debugger Options Option Debugger Tools ­b[b] Select the screen size All ­i pathname Identify additional directories All ­mmmode Select the operating mode Simulator ­mvversion Select the device version Simulator ­p port address Identify the port address EVM and emulator ­profile Enter the profiling environment All, except when running under DOS ­s Load the symbol table only All ­t filename Identify a new initialization file All ­v Load without the symbol table All ­x 1-12 Brief description Ignore D_OPTIONS All Invoking the Debugger Selecting the screen size (­b option) By default, the debugger uses an 80-character-by-25-line screen. You can use one of the options in Table 1­2 to specify a different screen size. On Sun systems, you can resize the screen at runtime also. Table 1­2. Screen Size Options Option Description Display none 80 characters by 25 lines Default display ­b 80 characters by 43 lines Any EGA or VGA display ­bb 80 characters by 50 lines VGA only Note: On Sun systems, the maximum size of the debugger screen is 132 characters by 60 lines. Identifying additional directories (­i option) The ­i option identifies additional directories that contain your source files. Replace pathname with an appropriate directory name. You can specify several pathnames; use the ­i option as many times as necessary. For example: emu3x ­i pathname1 ­i pathname2 ­i pathname3 . . . Using ­i is similar to using the D_SRC environment variable (see Setting up the environment variables in the appropriate installation guide). If you name directories with both ­i and D_SRC, the debugger first searches through directories named with ­i. The debugger can track a cumulative total of 20 paths (including paths specified with ­i, D_SRC, and the debugger USE command). Selecting the operating mode (­mm option) The ­mm option is valid only when you are using the simulator. The ­mm option tells the simulator to operate in either the microprocessor or microcomputer mode: ­mm0 tells the simulator to operate in the microprocessor mode. ­mm1 tells the simulator to operate in the microcomputer mode (default). If you don't use the ­mm option, the simulator operates in the microcomputer mode. Overview of a Code Development and Debugging System 1-13 Invoking the Debugger Selecting the device version (­mv option) The ­mv option is valid only when you are using the simulator. The ­mv option tells the simulator to simulate the 'C30 or the 'C31 memory map: ­mv30 tells the simulator to simulate the 'C30 memory map (default). ­mv31 tells the simulator to simulate the 'C31 memory map. If you don't use the ­mv option, the simulator simulates the 'C30 memory map. Identifying the port address (­p option) The ­p option is valid only when you are using the EVM or emulator. The ­p option identifies the I/O port address that the debugger uses for communicating with the emulator or EVM. If you used the default switch settings, you don't need to use the ­p option. If you used nondefault switch settings, you must use ­p. Refer to your entries in the Your Settings table in the appropriate installation guide; depending on your switch settings, replace port address with one of these values: Switch 1 Switch 2 Option on on ­p 240 (optional) on off ­p 280 off on ­p 320 off off ­p 340 If you didn't note the I/O switch settings, you can use a trial-and-error approach to find the correct ­p setting. If you use the wrong setting, you will see an error message when you invoke the debugger. (See the appropriate installation guide for more information.) Entering the profiling environment (­profile option) This optio