View SPVU021A_1004317.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

TMS340 Family C Source Debugger User's Guide
SPVU021A 2564010-9721 Rev. A September 1991
Printed on Recycled Paper
Running Title
1-2
Chapter Title
TMS340 Family C Source Debugger Reference Card
Phone Numbers
TI Customer Response Center (CRC) Hotline: (800) 336-5236 Graphics Hotline: (713) 274-2340
Debugging TIGA Applications
Before invoking the debugger, install the TIGA communication driver:
Development Board: TIGACD / D2 Execute TIGACOM on the target system. Execute DEBUGCOM on the host system. Emulator: TIGACD / D1
Invoking the Debugger
Development Board: Emulator: db340 [filename] [-options] db340emu [filename] [-options]
Debugger Options
Option -b[bbbb] Description Screen size options. Option Chars./Lines Notes none 80 X 25 Default display -b 80 X 43 Use any EGA 80 X 50 or VGA card -bb 120 X 43 Supported on a -bbb 132 X 43 Video Seven -bbbb 80 X 60 VEGA Deluxe -bbbbb 100 X 60 card Identifies additional directories that contain source files. Tells the debugger to provide '34082 support. Tells the debugger to expect IEEE floating-point format. Tells the debugger not to initialize the program counter (PC) or the stack pointer (SP).
-i pathname -mc -mf -mi
EGA card VGA card Development Board Version only
1
Debugger Options
Option
-p port address
Description
Emulator only. If you used nondefault switch settings, you must use -p. Switch 1 Switch 2 Option on on -p 220 none needed on off off on -p 300 off off -p 3E0 Tells the debugger to load filename's symbol table only. Specifies an initialization command file to be used instead of init.cmd. Loads only global symbols; later, local symbols are loaded as needed. Affects all loads. Ignores options supplied with D_OPTIONS.
-s -t filename -v
-x
Summary of Debugger Commands
Command ? expression addr address addr function name alais [aliasname ["command string"]] asm ba address bd address bl border [active] [ ,inactive] [,resize] br c calls cd directory name chdir directory name cls cnext [expression] color area, attr1 [,attr2 [,attr3 [,attr4 ] ] ] cstep [expression] dasm address dasm function name dir [directory] disp expression Description Evaluate expression Display code at address or function name Associates one or more debugger commands with a single alias name. Switch to assembly mode Set breakpoint at address Delete breakpoint at address List all breakpoints Change window border style Clear all breakpoints Switch to C/auto mode Open the CALLS window Change current directory Clear COMMAND display Single-step C code, step over functions Change screen colors, delayed update Single-step C code Display disassembly at address or function name Show contents of directory Open DISPlay window
Summary of Debugger Commands
2
Command eval expression e expression file filename fill address, length, data fpuregs func function name func address go [address] halt ioregs load object filename ma address, length, type map {on | off} md address mem expression mix ml mod [module identifier ] move [X, Y [, width, length ] ] mr ms addresslength, filename
Description Evaluate expression Display text file Fill memory Opens the FPU window to display the '34082 registers. Display function Run to address Halt target system Opens the I/O window to display the registers. Load object file Add block to memory map Enable / disable memory mapping Delete block from memory map Display memory at expression Switch to mixed mode List blocks in memory map TIGA module identifier Move active window Reset memory map Saves the parameter values in a block of memory to a system file. Single-step disassembly, step over functions Change the prompt Exit the debugger Load object file without symbol table Reset target system (emulator) or reload gspmon (development boards) Reset PC to program entry point Return to function's caller Run program Benchmark code Run free from target Change screen colors, immediate update Load saved screen configuration Changes the display format for a specific datatype.
next [expression] prompt new prompt quit reload object filename reset
restart, rest return, ret run [expression] runb runf scolor area, attr1 [, attr2 [, attr3 [, attr4 ] ] ] sconfig [filename] setf [datatype, display format] Emulator only
Summary of Debugger Commands
3
Command size [width, length ] sload object filename sound on | off ssave [filename] step [expression] system [operating-system command [arg ] ] take filename [, flag] tba function name tbd breakpoint index unalias aliasname use directory name wa expression [, label] wd index number whatis symbol win WINDOW NAME wr zoom Emulator only
Description Size active window Load object file's symbol table Beeps every time an error message is displayed. Save current screen configuration Single-step disassembly Allows you to enter operating-system commands without exiting the debugger. Execute batch file Set a tentative breakpoint on a TIGA module Clear a tentative breakpoint Deletes an alias and its definition. Use an additional directory Add item to WATCH window Delete item from WATCH window Query type of symbol Make WINDOW active Reset WATCH window Makes the active window as large as possible.
Border Styles (BORDER Command)
Index 0 1 2 3 4 5 6 7 8 Style 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 4 cyan white
Area Names (COLOR/SCOLOR Commands)
menu_bar menu_hilite win_resize field_label cmd_cursor asm_label error_msg file_brk menu_border menu_hicmd field_text field_error cmd_echo asm_clabel file_line file_pc menu_entry win_border field_hilite cmd_prompt asm_data background file_eof file_pc_brk menu_cmd win_hiborder field_edit cmd_input asm_cdata blanks file_text
Window Size and Position Limits (SIZE and MOVE Commands)
Screen size 80 X 25 80 X43 80X 50 120X43 132X43 80X60 100X60 Option none -b -bb -bbb -bbbb -bbbbb Valid widths 4-80 4-80 4-120 4-132 4-80 4-100 Valid lengths 3-24 3-42 3-49 3-42 3-42 3-59 3-59 Valid X pos. 0-76 0-76 0-116 0-128 0-76 0-106 Valid Y pos. 1-22 1-40 1-47 1-40 1-40 1-57 1-57
EGA card VGA card
Memory Types (MA Command)
To identify this kind of memory read-only memory write-only memory read/write memory no-access memory Use this keyword as the type parameter R, ROM, or READONLY W, WOM, or WRITEONLY RW or RAM
PROTECT
Switching Modes
To do this Switch debugging modes in this order: auto assembly mixed Use this function key
5
Editing Text on the Command Line
To do this Enter the current command (if you press the return key in the middle of text, the debugger truncates the input text at the point where you press this key) Move back over text without erasing characters Use these function keys
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
To do this Move backward, one command at a time, through the command history Move forward, one command at a time, through the command history Use these function keys
Halting or Escaping From an Action
To do this Halt program execution Close a pulldown menu Undo an edit of the active field in a data-display window (pressing this key leaves the field unchanged) Halt the display of a long list of data in the COMMAND window display area Use this function key
6
Displaying Pulldown Menus
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 an adjacent menu Execute any of the choices from a displayed pulldown menu Use these function keys
or
Press the highlighted letter corresponding to your choice
Running Code
To do this Run code from the current PC (equivalent to the RUN command without an expression parameter) Single-step code from the current PC (equivalent to the STEP command without an expression parameter) Single-step code from the current PC; step over function calls (equivalent to the NEXT command without an expression parameter) Use these function keys
Selecting or Closing a Window
To do this Select the active window (pressing this key makes each window active in turn; stop pressing the key when the desired window becomes active) Close the CALLS or DISP window (the window must be active before you can close it) Repeat the last command Use these function keys
Editing Data or Selecting the Active Field
To do this Use this function key
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 to display a member that is an array, structure, or pointer
7
Moving or Sizing a Window
Enter the MOVE or SIZE command without parameters, then use the arrow 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 Use these function keys
Scrolling the Active Window's Contents
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 Use these function keys
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
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 (c) 1991, Texas Instruments Incorporated
How to Use This Manual
Preface
Read This First
What Is This Book About?
This book tells you how to use the the '340 family C source debugger with these debugging tools:
-
The '34020 emulator '34010- and '34020-based development boards that use TIGA communication software (version 2.05 or later). This includes the Texas Instruments '34010 TIGA development board, '34020 software development board, and a number of third-party '340 development boards.
How to Use This Book
The goal of this book is to help you install the C source debugger and learn how to use it. 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 that you receive it.
J J
There are two versions of the debugger--one for development boards and one for the emulator--and two sets of installation instructions (Chapters 2 and 3). It is very important to use the correct installation--Chapter 1 will help you to select the appropriate installation chapter. Chapter 4 is a tutorial that introduces you to many of the debugger features.
-
Part II: Debugger Description contains detailed information about using the debugger.
J J
Chapter 5 is analogous to a traditional manual introduction. It lists the key features of the debugger, describes additional '340 software tools, and tells you how to prepare a '340 program for debugging. The remaining chapters in Part II detail the individual topics that are introduced in the tutorial. For example, Chapter 6 describes all of the debugger's windows and tells you how to move them and size them; Chapter 7 describes everything you need to know about entering commands.
Chapter Title--Attribute Reference
iii
How to Use This Manual
-
Part III: Reference Material provides supplementary information.
J J J
Chapter 13 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 14 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 J J J J J
Read Chapter 1 to determine which version of the debugger you should install. Use the appropriate installation chapter, as directed in Chapter 1. Complete the tutorial in Chapter 4. Read the alphabetical command reference in Chapter 13.
If this is the first time that you have used a debugger or similar tool, then you may want to: Read Chapter 1 to determine which version of the debugger you should install. Use the appropriate installation chapter, as directed in Chapter 1. Complete the tutorial in Chapter 4. Read all of the chapters in Part II.
iv
Notational Conventions
Notational Conventions
This document uses the following conventions:
-
The C source debugger has a very flexible command-entry system; there are usually 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 using a function key. This document uses 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. Press, hold, and move. While pressing the left mouse button, move the mouse.
Debugger commands are not case sensitive; you can enter them in lowercase, uppercase, or a combination. To emphasize this fact,
Chapter Title--Attribute Reference
v
-
Notational Conventions
-
commands are shown throughout this user's guide in both uppercase and lowercase. The debugger recognizes standard C numeric formats. Hexadecimal numbers must be prefixed with 0x. Octal numbers must be prefixed with 0. Decimal numbers are not prefixed. 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:
Enter whatis giant whatis xxx Result displayed in the COMMAND window struct zzz giant[100]; 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 most 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: wa expression [, label ] wa is the command. This command has two parameters, indicated by expression and label. The first parameter must be an actual C expression; the second parameter, which can be any string of characters, 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
Related Documentation From Texas Instruments
Related Documentation From Texas Instruments
The following books describe the TMS34010, TMS34020, and related support tools. To obtain a copy of any of these TI documents, call the Texas Instruments Customer Response Center (CRC) at (800) 336-5236. When ordering, please identify the book by its title and literature number.
TMS34010 TIGA Development Board User's Guide (literature number SPVU031) provides an in-depth description of TIGA development board operation. TMS34020 Software Development Board User's Guide (literature number SPVU034) provides an in-depth description of the software development board operation. TMS34020 Emulator Installation Guide (literature number SPVU032) provides an in-depth description of emulator board operation. TMS34010 User's Guide (literature number SPVU001) discusses hardware aspects of the '34010, such as pin functions, architecture, stack operation, interfaces, and instruction set. TMS340 Graphics Library User's Guide (literature number SPVU027) describes the graphics operations library that is available for a '340-based graphics system. TIGA Interface User's Guide (literature number SPVU015) describes the architecture of the TIGA (Texas Instruments Graphics Architecture) software interface between a host processor and a '340 graphics processor, which includes the applications interface, communications driver, and graphics manager. TMS34020 User's Guide (literature number SPVU019) describes hardware aspects of the '34020, such as pin functions, architecture, stack operation, interfaces, and instruction set. TMS340 Family Assembler Support for the TMS34082 (literature number SPVU029) summarizes the '34082 instruction set. TMS340 Family Code-Generation Tools User's Guide (literature number SPVU020) describes the '340 C compiler, assembler, linker, archiver, and auxiliary tools that are available for developing '34010 or '34020 code. Pixel Perspectives is a quarterly newsletter, published by the Computer Video Products group of Texas Instruments Incorporated. This newsletter describes new products, discusses support for existing products, and identifies new documentation releases.
Chapter Title--Attribute Reference
vii
Related Documentation / Assistance / Trademarks
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. . .
Request more information about Texas Instruments computer video products Do this. . . Call the CRC hotline: (800) 336-5236 Or write to Texas Instruments Incorporated Market Communications Manager, MS 736 P.O. Box 1443 Houston, Texas 77251-1443 Call the CRC hotline: (800) 336-5236 Call the graphics hotline: (713) 274-2340 Send your comments to Texas Instruments Incorporated Technical Publications, MS 702 P.O. Box 1443 Houston, Texas 77251-1443
Order Texas Instruments documentation Ask questions about product operation or report suspected problems Report mistakes in this document or any other TI documentation
Texas Instruments Customer Response Center; the number is toll free in the U.S. and Canada.
Trademarks
TIGA is a trademark of Texas Instruments Incorporated. PC-DOS is a trademark of International Business Machines. MS-DOS and Windows are trademarks of Microsoft Corporation. VEGA Deluxe is a trademark of Video Seven Incorporated.
viii
Contents
Part I: Hands-On Information
1 Identifying the Correct Installation for Your Development System . . . . . . . . . . . . . . . . . . . 1-1
Illustrates key items necessary for both versions of the debugger, directs you to the appropriate installation instructions, and describes the three general categories of '340 debugging strategies.
1.1 1.2 1.3
1.4
Using the Development Board Version of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . Where are the installation instructions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Emulator Version of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where are the installation instructions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Strategies for Debugging Your '340 Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standalone applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIGA applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-TIGA host applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using an Emulator and a Development Board in the Same System . . . . . . . . . . . . . . . .
1-2 1-3 1-4 1-5 1-6 1-6 1-6 1-7 1-8
2
Installing the Debugger for Use With '340-Based Development Boards
. . . . . . . . . . . . . 2-1
Lists the hardware and software you'll need to install and run the development board version of the debugger, guides you through a 2-step installation process, and tells you how to invoke the development board version of the debugger.
2.1
2.2 2.3
2.4 2.5 2.6
What You'll Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Hardware checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Software checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Installing the Debugger Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Setting Up the Debugger Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Invoking the new or modified batch file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Modifying the PATH statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Setting up the environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Installing the TIGA communication driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Setting Up for TIGA Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Pinout for serial cable connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Exiting the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Chapter Title--Attribute Reference
ix
Running Title--Attribute Reference
3
Installing the Debugger for Use With the '34020 Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Lists the hardware and software you'll need to install and run the emulator version of the debugger, guides you through a 2-step installation process, and tells you how to invoke the emulator version of the debugger.
3.1
3.2 3.3
3.4 3.5 3.6
What You'll Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Hardware checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Software checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Installing the Debugger Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Setting Up the Debugger Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Invoking the new or modified batch file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Modifying the PATH statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Setting up the environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Identifying the correct I/O switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Resetting the emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Setting Up for TIGA Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Exiting the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
4
An Introductory Tutorial to the C Source Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 How to use this tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 A note about entering commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 An escape route (just in case) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Invoke the debugger and load the sample program's object code . . . . . . . . . . . . . . . . . . . . . . . 4-4 Now what should I see? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 What's in the DISASSEMBLY window? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Select the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Resize the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8 Zoom the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 Move the active window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 Scroll through a window's contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 Display the C source version of the sample file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Execute some code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Become familiar with the three debugging modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Open another text file, then redisplay a C source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Use the basic RUN command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 Set some breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 Benchmark a section of code (emulator only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18 Watch some values and single-step through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19 Run code conditionally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21 WHATIS that? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22 Clear the COMMAND window display area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Provides a step-by-step introduction to the debugger and its features.
x
Running Title--Attribute Reference
Display the contents of an aggregate data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display data in another format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Change some values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Define a memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Define your own command string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Close the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-23 4-26 4-28 4-29 4-30 4-30
Part II: Debugger Description
5 Overview of a Code Development and Debugging System . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 5.1 5.2 5.3 Description of the '340 C Source Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Key features of the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Developing Code for the '340 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 Preparing Your Program for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 Assembling and/or compiling your program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 Program constraints for development board applications . . . . . . . . . . . . . . . . . . . . . . . . 5-10 Debugging '340 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Discusses features of the debugger, additional tools.
5.4
6
The Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-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.
6.1
6.2
6.3
Debugging Modes and Default Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Auto mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Assembly mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Mixed mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Restrictions associated with debugging modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Descriptions of the Different Kinds of Windows and Their Contents . . . . . . . . . . . . . . . . 6-5 COMMAND window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 DISASSEMBLY window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 FILE window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 CALLS window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 MEMORY window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 CPU window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12 I/O window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13 FPU window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14 DISP windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15 WATCH window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16 Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Chapter Title--Attribute Reference
xi
Running Title--Attribute Reference
6.4
6.5
6.6
6.7
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-18 6-18 6-19 6-21 6-21 6-23 6-24 6-27 6-27 6-29 6-30
7
Entering and Using Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-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.
7.1
7.2
7.3 7.4 7.5
Entering Commands From the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 How to type in and enter commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 Sometimes, you can't type a command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Using the command history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Clearing the display area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 Using the Menu Bar and the Pulldown Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Using the pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7 Escaping from the pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8 Entering parameters in a dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8 Using menu bar selections that don't have pulldown menus . . . . . . . . . . . . . . . . . . . . . 7-10 How the menu selections correspond to commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 Entering Commands From a Batch File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12 Defining Your Own Command Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14 Entering Operating-System Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16 Entering a single command from the debugger command line . . . . . . . . . . . . . . . . . . . 7-16 Entering several commands from a system shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17 Additional system commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18
8
Defining a Memory Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Contains instructions for setting up a memory map that will enable the debugger to correctly access target memory. Also includes hints about using batch files.
8.1 8.2 8.3
xii
The Memory Map: What It Is and Why You Should Define It . . . . . . . . . . . . . . . . . . . . . . 8-2 Sample Memory Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 Identifying Usable Memory Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Running Title--Attribute Reference
8.4 8.5 8.6 8.7 9
Enabling Memory Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking the Memory Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the Memory Map During a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . Returning to the original memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple Memory Maps for Multiple Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-6 8-6 8-7 8-8 8-9
Loading, Displaying, and Running Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-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.
9.1 9.2
9.3
9.4 9.5
9.6 9.7
Code-Display Windows: Viewing Assembly Language Code, C Code, or Both . . . . . . 9-2 Selecting a debugging mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 Displaying Your Source Programs (or Other Text Files) . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Displaying assembly language code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Displaying C code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Displaying other text files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7 Loading Object Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8 Loading code while invoking the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8 Loading code after invoking the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8 Where the Debugger Looks for Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9 Running Your Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10 Defining the starting point for program execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10 Running code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 Single-stepping through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Running code while disconnected from the target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14 Running code conditionally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15 Halting Program Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Benchmarking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
10 Loading TIGA Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Describes special processes that are necessary for debugging TIGA applications.
10.1 10.2
10.3 10.4
Overview of the Dynamic-Load Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging with Microsoft Windows (version 3.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Tentative Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clearing a tentative Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using regular breakpoint commands while debugging TIGA modules . . . . . . . . . . . . . Reloading TIGA Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using LOAD, RELOAD, SLOAD, and RESTART while debugging TIGA modules . . . Identifying Symbols Used in TIGA Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10-2 10-3 10-4 10-4 10-5 10-6 10-6 10-7
11 Managing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Describes the data-display windows and tells you how to edit data (memory contents, register contents, and individual variables).
11.1
Where Data Is Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Chapter Title--Attribute Reference
xiii
Running Title--Attribute Reference
11.2 11.3
11.4
11.5
11.6
11.7
11.8
Basic Commands for Managing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 Basic Methods for Changing Data Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4 Editing data displayed in a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4 Advanced "editing" --using expressions with side effects . . . . . . . . . . . . . . . . . . . . . . . 11-5 Managing Data in Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 Displaying memory contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6 Displaying memory contents while you're debugging C . . . . . . . . . . . . . . . . . . . . . . . . . 11-8 Saving memory values to a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9 Filling a block of memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10 Managing Register Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11 Displaying register contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11 Displaying and changing the contents of I/O registers . . . . . . . . . . . . . . . . . . . . . . . . . 11-12 Displaying and changing the contents of status bits . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13 Displaying and changing the contents of '34082 registers . . . . . . . . . . . . . . . . . . . . . . 11-14 Managing Data in a DISP (Display) Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15 Displaying data in a DISP window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15 Closing a DISP window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17 Managing Data in a WATCH Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18 Displaying data in the WATCH window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18 Deleting watched values and closing the WATCH window . . . . . . . . . . . . . . . . . . . . . . 11-19 Displaying Data in Alternative Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20 Changing the default format for specific data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20 Changing the default format with ?, MEM, DISP, and WA . . . . . . . . . . . . . . . . . . . . . . 11-22
12 Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Describes the use of software breakpoints to halt code execution.
12.1 12.2 12.3
Setting a Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Clearing a Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4 Finding the Breakpoints That Are Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
13 Customizing the Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Contains information about the commands that you can use for customizing the display, and identifies the display areas that you can modify.
13.1
13.2 13.3
Changing the Colors of the Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . area names: common display areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . area names: window borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . area names: COMMAND window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . area names: DISASSEMBLY and FILE windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . area names: data-display windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . area names: menu bar and pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Border Styles of the Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving and Using Custom Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the default display for monochrome monitors . . . . . . . . . . . . . . . . . . . . . . . . .
13-2 13-3 13-4 13-4 13-5 13-6 13-7 13-8 13-9 13-9
xiv
Running Title--Attribute Reference
13.4
Saving a custom display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading a custom display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking the debugger with a custom display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returning to the default display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13-10 13-10 13-11 13-11 13-12
Part III: Reference Material
14 Summary of Commands and Special Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Provides a functional summary of the debugger commands and function keys; also provides a complete alphabetical summary of all debugger commands.
14.1
14.2 14.3
Functional Summary of Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2 Changing modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 Managing windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 Performing system tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3 Displaying and changing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 Displaying files and loading programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4 Managing breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5 Loading TIGA applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5 Customizing the screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5 Memory mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6 Running programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6 Alphabetical Summary of Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7 Summary of Special Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-38 Editing text on the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-38 Using the command history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-38 Switching modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-39 Halting or escaping from an action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-39 Displaying pulldown menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-39 Running code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-40 Selecting or closing a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-40 Moving or sizing a window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-40 Scrolling a window's contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-41 Editing data or selecting the active field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-41
15 Basic Information About C Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-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.
15.1
C Expressions for Assembly Language Programmers . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2
Chapter Title--Attribute Reference
xv
Running Title--Attribute Reference
15.2
Restrictions and Features Associated With Expression Analysis in the Debugger . . 15-4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 Additional features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
xvi
Running Title--Attribute Reference
A
Troubleshooting and Technical Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Provides troubleshooting information for installation problems; gives additional board- and system-level technical information.
A.1 A.2
A.3 A.4 A.5 A.6
Troubleshooting an Emulator Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Troubleshooting a Development Board Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Common serial link problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4 Running the gspsetup utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5 What the Debugger Does During Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6 Using the Emulator With Target Systems That Hold HCS Inactive During Power-Up . A-7 Debugger and Monitor Communications (Development Boards Only) . . . . . . . . . . . . . . A-8 Using a TIGA Communication Driver (Development Boards Only) . . . . . . . . . . . . . . . . A-10
B
Debugger Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 B.1 B.2 B.3 B.4 Associating Sound With Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Alphabetical Summary of Debugger Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Additional Instructions for Expression Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19 Additional Instructions for Hardware Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19
Describes progress and error message that the debugger may display.
C
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Defines acronyms and key terms used in this book.
Chapter Title--Attribute Reference
xvii
Running Title--Attribute Reference
Figures
1-1 1-2 2-1 2-2 2-3 3-1 3-2 5-1 5-2 5-3 6-1 6-2 6-3 6-4 7-1 7-2 7-3 8-1 8-2 Key Items in a '340-Based Development System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Key Items in an Emulator System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 DOS-Command Set Up for the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Components Required for Debugging a TIGA Application . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Serial Cable Pinout Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 DOS-Command Set Up for the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Components Required for Debugging a TIGA Application . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 The Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 '340 Software Development Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 Steps You Go Through to Prepare a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 Typical Assembly Display (for Auto Mode and Assembly Mode) . . . . . . . . . . . . . . . . . . . . . 6-2 Typical C Display (for Auto Mode Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Typical Mixed Display (for Mixed Mode Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Default Appearance of an Active and an Inactive Window . . . . . . . . . . . . . . . . . . . . . . . . . 6-18 The COMMAND Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 The Menu Bar in the Debugger Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 All of the Pulldown Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Sample Memory Map for Use With a '34010 Development Board . . . . . . . . . . . . . . . . . . . . 8-3 Sample Memory Map for Use With the '34020 Emulator or a '34020 Development Board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
xviii
Running Title--Attribute Reference
Tables
2-1 3-1 3-2 3-3 6-1 6-2 2-1 2-2 4-1 4-2 A-1 Debugger Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Using D_OPTIONS to Identify Nondefault I/O Address Space . . . . . . . . . . . . . . . . . . . . . . . 3-7 -x Options for the emurst Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Debugger Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Width and Length Limits for Window Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22 Minimum and Maximum Limits for Window Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25 Display Formats for Debugger Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20 Data Types for Displaying Debugger Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20 Colors and Other Attributes for the COLOR and SCOLOR Commands . . . . . . . . . . . . . . 13-2 Summary of Area Names for the COLOR and SCOLOR Commands . . . . . . . . . . . . . . . . 13-3 gspsetup Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Chapter Title--Attribute Reference
xix
Chapter 1
Identifying the Correct Installation for Your Development System
The '340 C source debugger is a software interface for '340 debugging systems. There are two versions of the debugger: The development board version of the C source debugger works with '340-based PC development boards such as the '34010 TIGA development board or the '34020 software development board. It also works with third-party boards that use a TIGA communication driver. The emulator version of the C source debugger works with the '34020 emulator. Both versions of the debugger operate almost identically. However, the executable files that invoke them are very different. The development board version will not work with the emulator, and vice versa. Be sure to install the correct version of the debugger for your environment. This chapter describes how these two versions of the debugger can be used in various environments. It also tells you which installation chapter to use to make sure that you install the correct version of the debugger for your environment.
Synopsis Page
This section shows the key items in a development board system and points you to the appropriate installation instructions. This section shows the key items in an emulator system and points you to the appropriate installation instructions This section describes three '340 application environments and describes the debugger's role in each environment.
1.1 Using the Development Board Version of the Debugger Where are the installation instructions?
Topic
iii iv
1.2
Using the Emulator Version of the Debugger Where are the installation instructions?
v vi
1.3
Strategies for Debugging Your '340 Application Standalone applications TIGA applications Non-TIGA host applications
vii vii vii viii
Chapter Title--Attribute Reference
i
Running Title--Attribute Reference
An emulator and development board are not usually used in the same system. However, when they are, here's some extra information that you'll need.
1.4
Using an Emulator and a Development Board in the Same System
ix
ii
Using the Development Board Version of the Debugger
1.1 Using the Development Board Version of the Debugger
Figure 1-1 shows the key hardware and software items that you'll need for using the development board version of the C source debugger.
Figure 1-1. Key Items in a '340-Based Development System
IBM PC/AT
Hardware
'34010 or '34020 development board
Software TIGA C source debugger A C or assembly language program that you developed
Chapter Title--Attribute Reference
iii
Using the Development Board Version of the Debugger
The development board version of the debugger can be used with the following boards:
-
'34010 TIGA development board (TDB). This board is a standard video display adapter for ISA- and EISA-based PCs. The TDB provides an environment for debugging '34010 application software. '34020 software development board (SDB). This board is a standalone, high-performance, graphics-development board, compatible with the IBM PC-AT bus (ISA compatible). The SDB provides an environment for debugging '34020 application software. Third-party '34010- or '34020-based boards that use version 2.05 (or later) of the TIGA software interface.
Where are the installation instructions?
To install the development board version of the debugger, read Chapter 2, Installing the Debugger for Use With '340 Development Boards.
Chapter 2 assumes that you have already installed your board and that you have also installed TIGA:
-
-
Installing the '34010 TDB: Refer to the TMS34010 TIGA Development Board User's Guide, which accompanies the TDB. Installing the '34020 SDB: Refer to the TMS34020 Software Development Board User's Guide, which accompanies the SDB. Installing third-party boards: Refer to the manufacturer's instructions accompanying your board. Installing TIGA: The documentation for installing TIGA usually accompanies your development board. If this is not available, refer to the TIGATM Interface User's Guide.
iv
Using the Emulator Version of the Debugger
1.2 Using the Emulator Version of the Debugger
Figure 1-2 shows the key hardware and software items that you'll need for using the emulator version of the C source debugger.
Figure 1-2. Key Items in an Emulator System
IBM PC/AT
Hardware '34020 emulator board target system target cable
Software C source debugger A C or assembly language program that you developed
Chapter Title--Attribute Reference
v
Using the Emulator Version of the Debugger
You can use this version of the debugger with the Texas Instruments '34020 emulator only. The emulator uses unique, scan-based TI emulation technology and provides an environment for debugging code on a '34020 board. The emulator does not contain a '34020 processor, so it must be connected to a target system that has a '34020. Usually, the target system is a board of your own design; for testing purposes, however, you can use the '34020 SDB as a target system.
Where are the installation instructions?
To install the emulator version of the debugger, read Chapter 3, Installing the Debugger for Use With the '34020 Emulator.
Chapter 3 assumes that you have already installed the emulator board and your target system. For emulator installation instructions, refer to the TMS34020 Emulator Board Installation Guide, which accompanies the emulator version of the debugger.
vi
Strategies for Debugging Your '340 Application
1.3 Strategies for Debugging Your '340 Application
'340 applications fall into three general categories:
-
Standalone applications TIGA applications Non-TIGA host applications
The '340 C source debugger cannot be used with all three types of applications. The following paragraphs describe these application categories and tell you whether or not the debugger can be used.
Standalone applications
Standalone applications execute entirely on the '340 processor. The program you are debugging is composed of a single COFF object module. Only the debugger loads and executes your program; there is no interaction between your program and the PC. Both versions of the C source debugger can be used without restriction in standalone environments:
-
Because your program does not interact with the PC, the development board debugger is free to use the '340 processor's host interface (via the TIGA communication driver routines). The emulator version of the debugger does not use or need the '340 processor's host interface. The emulator's scan-based interface allows it to control the '340 system.
TIGA applications
For the purposes of debugging, a TIGA application is an application in which you have written your own TIGA modules to supplement the standard functions in the TIGA applications interface library. You can use the debugger to refine your custom modules. In a TIGA application, the debugging environment is split into two parts.
-
The TIGA application resides on a target PC, with TIGA; TIGA relocates code and loads it into '340 memory. The debugger software resides on a host PC.
Chapter Title--Attribute Reference
vii
Strategies for Debugging Your '340 Application
These two parts must communicate with each other during program execution. If you are using the emulator, the two parts communicate via the emulation cable. If you are using a development system, the two parts must communicate over a serial cable. Both the emulator and development board versions of the debugger allow you to debug TIGA applications. For more information about debugging TIGA applications, refer to Chapter 10, Loading TIGA Applications.
Non-TIGA host applications
Non-TIGA host applications are similar to TIGA applications because they are split into two parts:
-
One part, like a standalone application, executes entirely on the '340 processor. Another part executes on the PC.
These two parts must communicate with each other during program execution. The emulator version of the C source debugger can be used with non-TIGA host applications as long as the debugger runs on a different PC or runs as a separate task under a multitasking DOS extension. The debugger controls the '340 processor through the emulator interface, leaving the host port free for controlling communications between the two parts of the application software. If the host system, rather than the emulator, loads the program that you plan to debug, the debugger must load the symbols for the '340 program (with the SLOAD debugger command or the debugger -s option). The development board version of the C source debugger is not compatible with non-TIGA host applications, because the debugger requires exclusive use of the host interface.
viii
Using an Emulator and a Development Board in the Same System
1.4 Using an Emulator and a Development Board in the Same System
An emulator and a development board are not often used in the same system--usually, you will want to use one or the other for debugging your '340 application. However, it's possible that you may want to use both an emulator and a development board. For example, you may be using the '34020 SDB as a target system for the emulator. If you use an emulator and a development board in the same system, it's important to note that:
-
The debugger provides nearly identical functionality for the development boards and for the emulator. Remember, though, that there are two different versions of the debugger, and they are invoked with different commands: db340 db340emu Is the command that invokes the development board version of the debugger. Is the command that invokes the emulator version of the debugger.
-
If you are using the SDB as a target system for the emulator, you should use the emulator version of the debugger. If you use a development board separately from the emulator, you must be sure that the emulator is running free while you are using the development board version of the debugger. To do this, invoke the emulator debugger, enter the RUNF command, then quit. Now you will be able to invoke the development board debugger without interference from the emulator. If the emulator is not running free while you are using the development board debugger, the development board's '340 processor could be halted by the emulator. This prevents the development board software from gaining control of the '340.
Chapter Title--Attribute Reference
ix
Chapter 2
Installing the Debugger for Use With '340-Based Development Boards
STOP If you are using the debugger with the '34020 emulator, do not follow the installation instructions in this chapter--turn to Chapter 3. If you are not sure which version of the debugger you should install, read Chapter 1.
This chapter will help you install the development board version of the '340 C source debugger. This version of the debugger works with '34010- and '34020-based PC boards that use TIGA (version 2.05 or later). For example, it works with the '34010 TDB and the '34020 SDB. In most cases, if you install the debugger as instructed in this chapter, it will operate properly. However, if your debugger doesn't seem to work properly, or if you are developing a nonstandard or advanced application, refer to Appendix A, Technical Notes, for troubleshooting and supplementary information. When you finish installing the debugger, turn to Chapter 4, An Introductory Tutorial to the C Source Debugger.
Topic
The chapter begins with checklists of the hardware and software you'll need for installing the debugger and using it with a '340 development board. Installing the debugger is a 2-step process. After you install the debugger software, you must modify the DOS environment and invoke several utilities. This enables the debugger to operate properly. If you plan to debug TIGA applications, you must also follow the steps in Section 2.4; otherwise, skip this section. After you install the debugger, you will need to know how to invoke and exit the debugger.
2.1 What You'll Need Hardware checklist Software checklist
Page
ii ii ii
2.2 2.3
Installing the Debugger Software Setting Up the Debugger Environment Invoking the new or modified batch file Modifying the PATH statement Setting up the environment variables Installing the TIGA communication driver Setting Up for TIGA Applications Pinout for serial cable connector
iv iv v vi vi vii viii xi
2.4
2.5 2.6
Invoking the Debugger Exiting the Debugger
xii xiii
Chapter Title--Attribute Reference
i
What You'll Need
2.1 What You'll Need
In addition to the items shipped with the C source debugger, you'll need the following items.
Hardware checklist
host target memory display development board optional hardware An IBM PC/AT or 100% compatible ISA/EISA-bus PC with a harddisk system and a 1.2M floppy-disk drive If you plan to debug TIGA applications, you will also need a target PC to run TIGA and the TIGA application Minimum of 640K (debugger occupies approximately 400K) Monochrome or color (color recommended) A '340-based PC board Mouse (must be compatible with a Microsoft mouse) An EGA- or VGA-compatible graphics display card A 17" or 19" monitor. The C source debugger has several modes that allow you to display varying amounts of information on your PC monitor. If you have an EGA- or VGA-compatible graphics card and a large monitor (17" or 19"), you can take advantage of some of the debugger's larger screen modes. (To use larger screen sizes, you must invoke the debugger with the appropriate options; Table 2-1, page xii, explains this in detail.) A second monitor. Most development boards allow you to connect the board to both your PC's monitor and to a second display monitor. The debugger display is shown on your PC's display monitor. If you want to display any graphics routines drawn by your '340 code, you must connect the development board to a second display monitor. miscellaneous materials A blank, formatted disk
Software checklist
operating system software tools MS-DOS or PC-DOS (version 3.0 or later) '340 family C compiler, assembler, and linker (version 5.0 or later)
ii
What You'll Need
required files

gspmon.out contains '340 routines that the debugger uses for controlling the '340 processor. tigacom.exe and debugcom.exe are two communication drivers required for serial communication in TIGA applications. tigacd loads the TIGA communication driver.
If you plan to debug TIGA applications, you'll need tigagm.out (the TIGA graphics manager). If you are debugging extended primitives, you also need extprims.rlm. dbinit.cmd is a general-purpose batch file that contains debugger commands. When you invoke the debugger, it will execute the commands in dbinit.cmd. Initially, dbinit.cmd disables memory mapping; if dbinit.cmd isn't present when you invoke the debugger, then all memory is invalid at first. Two additional files, sdbmap.cmd and tdbmap.cmd, define sample memory maps. When you first start to use the debugger, it is usually not necessary to enable memory mapping. Later, you may want to define your own memory map. For information about these files and about setting up your own memory map, refer to Chapter 8, Defining a Memory Map.
optional files
init.clr is a general-purpose screen configuration file. If init.clr isn't present when you invoke the debugger, the debugger uses the default screen configuration.
The default configuration is for color monitors; an additional file, mono.clr, can be used for monochrome monitors. When you first start to use the debugger, the default screen configuration should be sufficient for your needs. Later, you may want to define your own custom configuration. For information about these files and about setting up your own screen configuration, refer to Chapter 13, Customizing the Display.
Included as part of the debugger package Included as part of the TIGA software package
Note that the debugger operates correctly in a Windows 3.0 environment; however, the mouse may not function properly. You must use the TIGA software interface (version 2.05 or later). The installation instructions in this chapter assume that you have already installed TIGA according to the instructions provided with your third-party development board or in the TIGATM Interface User's Guide.
Chapter Title--Attribute Reference
iii
Installing the Debugger Software / Setting Up the Debugger Environment
2.2 Installing the Debugger Software
This section explains the simple process of installing the debugger software on a hard disk system. The debugger package includes a single disk that contains multiple directories. To install the debugger, you must copy the db directory from the product disk. Step 1: Make a backup copy of the product disk. (If necessary, refer to the DOS manual that came with your computer.)
Step 2: On your hard disk or system disk, create a directory named db. This directory will contain the '340 C source debugger software.
MD C:\db
Step 3: Insert the product disk into drive A. Copy the contents of the db directory:
COPY A:\db\*.* C:\db\*.* /V
2.3 Setting Up the Debugger Environment
To ensure that your debugger works correctly, you must perform several steps: 1) Modify the PATH statement to identify the db directory. 2) Define environment variables so that the debugger can find the files it needs. 3) Install the TIGA communication driver. Not only must you do these things before you invoke the debugger for the first time, you must do them any time you power up or reboot your PC. You can accomplish these tasks by entering individual DOS commands, but it's simpler to put the commands in a batch file. You can edit your system's autoexec.bat file; in some cases, modifying the autoexec may interfere with other applications running on your PC. So, if you prefer, you can create a separate batch file that performs these tasks. Figure 2-1 (a) shows an example of an autoexec.bat file that contains the suggested modifications (highlighted in bold type). Figure 2-1 (b) shows a sample batch file that you could create instead of editing the autoexec.bat file. (For the purpose of discussion, assume that this sample file is named initdb.bat.)
iv
Setting Up the Debugger Environment
Figure 2-1. DOS-Command Set Up for the Debugger
(a) Sample autoexec.bat file to use with the debugger
Modifications: DATE TIME ECHO OFF PATH=C:\DOS;C:\340TOOLS;C:tiga;C:\db SET D_DIR=C:\db SET D_SRC=;C:\340code SET D_OPTIONS=-b SET C_DIR=C:\340TOOLS CLS tigacd
PATH statement Environment variables
Install TIGA driver
(b) Sample initdb.bat file to use with the debugger PATH statement Environment variables Install TIGA driver
PATH=C:\db;%path% SET D_DIR=C:\db SET D_SRC=C:\340code SET D_OPTIONS=-b tigacd
Invoking the new or modified batch file
-
If you modify the autoexec.bat file, be sure to invoke it before invoking the debugger for the first time. To invoke this file, enter:
autoexec
If you create an initdb.bat file, you must invoke it before invoking the debugger for the first time. After that, you'll need to invoke initdb.bat any time that you power up or reboot your PC. To invoke this file, enter:
initdb
Chapter Title--Attribute Reference
v
Setting Up the Debugger Environment
Modifying the PATH statement
Step 1: Define a path to the debugger directory. The general format for doing this is:
PATH=C:\db
This allows you to invoke the debugger without specifying the name of the directory that contains the debugger executable file.
-
If you are modifying an autoexec that already contains a PATH statement, simply include ;C:\db at the end of the statement as shown in Figure 2-1 (a). If you are using the initdb.bat file, use a different format for the PATH statement: PATH=C:\db;%path% The addition of ;%path% ensures that this PATH statement won't undo PATH statements in any other batch files (including the autoexec.bat file).
Setting up the environment variables
An environment variable is a special system symbol that the debugger uses for finding or obtaining certain types of information. The debugger uses three environment variables, named D_DIR, D_SRC, and D_OPTIONS. The next three steps tell you how to set up these environment variables. The format for doing this is the same for both the autoexec.bat file and initdb.bat files. Step 2: Set up the D_DIR environment variable to identify the db directory:
SET D_DIR=C:\db
(Be careful not to precede the equal sign with a space.) This directory contains auxiliary files (such as dbinit.cmd) that the debugger needs. Step 3: Set up the D_SRC environment variable to identify any directories that contain program source files that you'll want to look at while you're debugging code. The general format for this is: SET D_SRC=C:\pathname1 ;pathname2 ... (Be careful not to precede the equal sign with a space.) For example, if your '340 programs were in a directory named 340code, the D_SRC set up would be:
SET D_SRC=C:\340code
vi
Setting Up the Debugger Environment
Step 4: You can use several options when you invoke the debugger. If you use the same options over and over, it's convenient to specify them with D_OPTIONS. The general format for doing this is: SET D_OPTIONS= [object filename] [debugger options] (Be careful not to precede the equal sign with a space.) This tells the debugger to load the specified object file and use the specified options each time you invoke the debugger. These are the options that you can identify with D_OPTIONS: -b[bbbb] -i pathname -v
-s
For more information about debugger options, see Section 2.5 (page xii). Note that you can override D_OPTIONS by invoking the debugger with the -x option.
Installing the TIGA communication driver
Step 5: Install the TIGA communication driver by entering:
TIGACD
Note: TIGA Applications If you will be debugging a TIGA application, you may want to wait to install the TIGA communication driver until you have read the information in Section 2.4, Setting Up Serial Communications for TIGA Applications.
Chapter Title--Attribute Reference
vii
Setting Up for TIGA Applications
2.4 Setting Up for TIGA Applications
If you plan to debug your own custom TIGA modules, you will need to run your application and the debugger on separate PCs. If you do not plan to debug your own custom TIGA modules, skip this section; turn to Section 2.5, Invoking the Debugger, on page xii. Figure 2-2 shows the various components that are needed on the TIGA (target) side and the debugger (host) side.
Figure 2-2. Components Required for Debugging a TIGA Application
Target PC '340 development board tigacd driver (TIGA version 2.05) tigacom driver Object code and target RLMs tigagm.out extprims.rlm Host PC '340 debugger debugcom driver gspmon.out dbinit.cmd gspsetup.exe Object code and target RLMs Source files tigagm.out extprims.rlm
RS-232 serial cable
This system requires two serial communication drivers, tigacom and debugcom: debugcom emulates portions of the TIGA communication driver (enabling the debugger to operate normally) and communicates with tigacom over the serial port. receives commands from debugcom and relays them to TIGA. Any return values from TIGA are sent back across the serial link to debugcom, which, in turn, relays these values to the debugger.
tigacom
Figure 2-3 (page xi) illustrates pinout connections for the host and target serial-cable connections.
viii
Setting Up for TIGA Applications
Follow these steps to set up the serial link between your TIGA application and the debugger: Step 1: Connect the target and host PCs with an RS-232 serial cable. Step 2: Copy tigacom.exe from the product diskette to the target PC; put tigacom.exe in the directory where the TIGA communication driver resides. Step 3: On the target PC, reinstall the TIGA communication driver:
TIGACD /D2
This enables the development-board version of the communication driver's debug mode. Later, if you need to disable this mode, enter:
TIGACD /D0
Step 4: On the target PC, install the tigacom driver by entering: tigacom [Ccommunication port] [Bbaud rate] where communication port and baud rate are single digits. The communication port parameter can have any of these values:
Parameter value 1 2 3 4 Represents this baud rate COM1 (3F8h)--default COM2 (2F8h) COM3 (3E8h) COM4 (2E8h)
The baud rate parameter can have any of these settings:
Parameter value 1 2 3 4 Represents this baud rate 1200 2400 4800 9600 Parameter value 5 6 7 8 Represents this baud rate 19200--default 38400 57600 115200
Note: TIGA Communication Driver If you ever uninstall the TIGA communication driver (by entering tigacd /u) and then reinstall it, you must also reinstall tigacom. The tigacom driver will uninstall itself whenever it detects that the TIGA communication driver has been unloaded.
Chapter Title--Attribute Reference
ix
Setting Up for TIGA Applications
Step 5: On the host PC, install the debugcom driver by entering: debugcom [Ccommunication port] [Bbaud rate] where communication port and baud rate can have the same values as those listed for debugcom. You can use different COM port settings for the two PCs, but the baud rates must be the same. Step 6: For each module that you plan to debug, copy the source and object code to the host PC. The source code can go in any directory, but the object code must reside in the same directory as db340.exe (the db directory). Step 7: Be sure that you have copied tigagm.out and, if you are using TIGA extended primitives, extprims.rlm to the directory on the target PC that contains tigacd. Also copy them to the db directory on the host PC. Step 8: On the host PC, execute the gspsetup utility to verify that the serial link is operating properly. Enter:
gspsetup -D
This will print the status of several tests. If no errors are reported, you are ready to invoke the debugger. If gspsetup does not execute properly, refer to Common serial link problems on page A-4. Step 9: On the host PC, invoke the debugger:
db340
The debugger should come up in a state where the '340 processor is in an endless loop. Use the RUN command (or press F5 ) to start the processor running. Step 10: Verify that the debugger is working properly by reloading the TIGA graphics manager. On the target PC, enter:
tigalnk /lx
The debugger should display a message indicating that it has successfully loaded the TIGA graphics manager. If "File Not Found" types of errors show up on the host PC, check your setup against the illustration in Figure 2-2 (page viii). Be sure that all of the files have been copied to the correct directories and that the serial cable is set up correctly. If the tigalnk utility produces other types of errors, you will need to reboot the target PC and begin again with Step 4, using lower baud rate settings for tigacom and debugcom. You may have to try several baud rates until you determine which is the highest baud rate you can use for reliable operation. In most
x
Setting Up for TIGA Applications
systems, the baud rate can be set as high as 115200 baud, but in some 386 protected mode systems, mode switching restrictions result in a maximum baud rate of 37400 to 57600 baud. The best method for determining the optimum baud rate is to start at 115200 baud and work down until serial communications are stable.
Like the information in Section 2.3, you have to install tigacd, tigacom, and debugcom whenever you power up or reboot the PC. Once you have determined the correct baud rates for tigacom and debugcom, you may want to enter the tigacd and tigacom commands into the target PC's autoexec and enter the debugcom command into the host PC's autoexec (or whatever initialization file you choose to use).
Pinout for serial cable connector
Figure 2-3 illustrates the pinout configuration for the RS-232 serial cable used for communications between the host and target PCs. Note that pinouts are shown for both a 9-pin and a 25-pin connector.,
Figure 2-3. Serial Cable Pinout Connections
(a) Connections for a 9-pin connector
Host PC Connector pin 2 pin 3 pin 5 Target PC Connector pin 3 pin 2 pin 5 pins 7-8 pins 1-4-6
(a) Connections for a 25-pin connector
Host P2 Connector pin 3 pin 2 pin 7 Target PC Connector pin 2 pin 3 pin 7 pins 4-5 pins 6-8-20
Notes:
1) 9-pin connector: On the target end, pins 7 and 8 are tied together and pins 1, 4, and 6 are tied together. 2) 25-pin connector: On the target end, pins 4 and 5 are tied together and pins 6, 8 and 20 are tied together.
Chapter Title--Attribute Reference
xi
Invoking the Debugger
2.5 Invoking the Debugger
Here's the basic format for the command that invokes the debugger: db340 [filename] [-options] db340 is the command that invokes the development board version of the debugger. 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. supply the debugger with additional information (see Table 2-1).
filename
-options
You can also specify filename and option information with the D_OPTIONS environment variable (see Setting up the environment variables, page vi).
Table 2-1. Debugger Options
Option -b[bbbb] Description Screen-size options. By default, the debugger uses an 80-character-by-25-line screen. If you have a special graphics card, however, you can choose one of several larger screen sizes. Option none -b -bb -bbb -bbbb -bbbbb -i pathname Characters/Lines 80 by 25 80 by 43 (EGA) 80 by 50 (VGA) 120 by 43 132 by 43 80 by 60 100 by 60 Notes This is the default display Use any EGA or VGA card Currently, the debugger supports these modes on a Video Seven VEGA Deluxe card.
Additional directories. Replace pathname with an appropriate directory name. You can specify several pathnames; use the -i option as many times as necessary: db340 -i path1 -i path2 -i path3 . . .
Using -i is similar to using the D_SRC environment variable (described on page vi). 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 D_SRC and the debugger USE command). -mc '34082 support. -mc tells the debugger to provide '34082 support. This allows you to access '34082 register values and tells the debugger to disassemble '34082 coprocessor instructions.
xii
Invoking the Debugger / Exiting the Debugger
Table 2-1. Debugger Options (Continued)
Option -mi Description Don't initialize PC or SP. By default, the debugger automatically initializes the '340 processor's program counter (PC) and stack pointer (SP-- register A15/B15) to a section of memory assigned to these registers by the TIGA memory manager. The -mi option allows you to leave the PC and SP uninitialized. However, if the PC and SP are not pointing to valid RAM, you will not be able to invoke the debugger. Floating-point format. By default, the debugger expects source code to use '340 floating-point format. The -mf option tells the debugger to expect IEEE floating-point format (IEEE std 754-1985) instead. If you are already using -mc, you don't need to use -mf. -s Load symbol table only. If you supply a filename when you invoke the debugger, you can use the -s option to tell the debugger to load only the file's symbol table (without the file's object code). This is similar to the debugger's SLOAD command. Load without symbol table. This option prevents the debugger from loading the entire symbol table when you load an object file. The debugger loads only the global symbols and later loads local symbols as it needs them. This speeds up the loading time and consumes less memory space. The -v option affects all loads, including loading when you invoke the debugger and loading with the LOAD command within the debugger environment. -x -t filename Ignore D_OPTIONS. -x tells the debugger to ignore any information supplied with D_OPTIONS. New initialization file. The -t option allows you to specify an initialization command file that will be used instead of dbinit.cmd.
-mf
-v
2.6 Exiting the Debugger
To exit the debugger and return to the operating system, enter this command: quit You don't need to worry about where the cursor is or which window is active--just type. If a program is running, press ESC to halt program execution before you quit the debugger.
Chapter Title--Attribute Reference
xiii
xiv
Chapter 3
Installing the Debugger for Use With the '34020 Emulator
STOP If you aren't using the debugger with the '34020 emulator, do not follow the installation instructions in this chapter--turn to Chapter 2. If you are not sure which version of the debugger you should install, read Chapter 1.
This chapter will help you install the emulator version of the '340 C source debugger. This version of the debugger works only with the '34020 emulator. In most cases, if you install the debugger as instructed in this chapter, it will operate properly. However, if your debugger doesn't seem to work properly, refer to Appendix A, Technical Notes. Also, if you are developing a nonstandard or advanced application, refer to Appendix A for supplementary information. When you finish installing the debugger, turn to Chapter 4, An Introductory Tutorial to the C Source Debugger.
Synopsis Page
The chapter begins with checklists of the hardware and software you'll need for installing the debugger and using it with the '34020 emulator. Installing the debugger is a 2-step process. After you install the debugger software, you must modify the DOS environment and reset the emulator. This enables the debugger to operate properly.
3.1 What You'll Need Hardware checklist Software checklist
Topic
ii ii iii
3.2 3.3
Installing the Debugger Software Setting Up the Debugger Environment Invoking the new or modified batch file Modifying the PATH statement Setting up the environment variables Identifying the correct I/O switches Resetting the emulator Setting Up for TIGA Applications Invoking the Debugger Exiting the Debugger
iv iv v vi vi vii viii x xii xiii
3.4
After you install the debugger, you will need to know how to invoke and exit the debugger.
3.5 3.6
Chapter Title--Attribute Reference
i
What You'll Need
3.1 What You'll Need
In addition to the items that are shipped with the '340 C source debugger, you'll need the following.
Hardware checklist
host target memory display emulator system optional hardware An IBM PC/AT or 100% compatible ISA/EISA-bus PC with a harddisk system and a 1.2M floppy-disk drive If you plan to debug TIGA applications, you will also need a target PC to run TIGA and the TIGA application Minimum of 640K (debugger occupies approximately 400K) Monochrome or color (color recommended) The '34020 emulator board and a '34020 target system Mouse (must be compatible with a Microsoft mouse) An EGA- or VGA-compatible graphics display card A 17" or 19" monitor. The C source debugger has several modes that allow you to display varying amounts of information on your PC monitor. If you have an EGA- or VGA-compatible graphics card and a large monitor (17" or 19"), you can take advantage of some of the debugger's larger screen modes. (To use larger screen sizes, you must invoke the debugger with the appropriate options; Table 3-3, page xii, explains this in detail.) miscellaneous materials A blank, formatted disk
ii
What You'll Need
Software checklist
operating system software tools required files

MS-DOS or PC-DOS (version 3.0 or later) '340 family C compiler, assembler, and linker (version 5.0 or later)
emurst resets the '34020 emulator
If you plan to debug TIGA applications, you'll need tigagm.out (the TIGA graphics manager). If you are debugging extended primitives, you also need extprims.rlm.
optional files
emuinit.cmd is a file that a contains debugger commands.When you invoke the debugger, it will execute the commands in emuinit.cmd. Initially, emuinit.cmd disables memory mapping; if emuinit.cmd isn't present when you invoke the debugger, then all memory is invalid at first. When you first start to use the debugger, it is usually not necessary to enable memory mapping. Later, you may want to define your own memory map. For information about setting up your own memory map, refer to Chapter 8, Defining a Memory Map. init.clr is a general-purpose screen configuration file. If this file isn't present when you invoke the debugger, the debugger uses the default screen configuration.
The default configuration is for color monitors; an additional file, mono.clr, can be used for monochrome monitors.When you first start to use the debugger, the default screen configuration should be sufficient for your needs. Later, you may want to define your own custom configuration. For information about these files and about setting up your own screen configuration, refer to Chapter 13, Customizing the Display.
Included as part of the debugger package Included as part of the TIGA software package
The debugger operates correctly in a Windows 3.0 environment; however, the mouse may not function properly.
Chapter Title--Attribute Reference
iii
Installing the Debugger Software / Setting Up the Debugger Environment
3.2 Installing the Debugger Software
This section explains the simple process of installing the debugger software on a hard disk system. The debugger package includes a single disk that contains multiple directories. To install the debugger, you must copy the emu34020 directory from the product disk.
Step 1: Make a backup copy of the product disk. (If necessary, refer to the DOS manual that came with your computer.)
Step 2: On your hard disk or system disk, create a directory named emu34020. This directory will contain the '34020 debugger software.
MD C:\emu34020
Step 3: Insert the product disk into drive A. Copy the contents of the emu34020 directory:
COPY A:\emu34020\*.* C:\emu34020\*.* /V
3.3
Setting Up the Debugger Environment
To ensure that your debugger works correctly, you must: 1) Modify the PATH statement to identify the emu34020 directory. 2) Define environment variables so that the debugger can find the files it needs. 3) Identify any nondefault I/O space used by the emulator. 4) Reset the emulator. Not only must you do these things before you invoke the debugger for the first time, you must do them any time you power up or reboot your PC. You can accomplish these tasks by entering individual DOS commands, but it's simpler to put the commands in a batch file. You can edit your system's autoexec.bat file; in some cases, however, modifying the autoexec may interfere with other applications running on your PC. So, if you prefer, you can create a separate batch file that performs these tasks.
iv
Setting Up the Debugger Environment
Figure 3-1 (a) shows an example of an autoexec.bat file that contains the suggested modifications (highlighted in bold type). Figure 3-1 (b) shows a sample batch file that you could create instead of editing the autoexec.bat file. (For the purpose of discussion, assume that this sample file is named initdb.bat.) The subsections following the figure describe these commands.
Figure 3-1. DOS-Command Set Up for the Debugger
(a) Sample autoexec.bat file to use with the debugger
Modifications: DATE TIME ECHO OFF PATH=C:\DOS;C:\340TOOLS;C:\emu34020 SET D_DIR=C:\emu34020;C:\cmdfiles SET D_SRC=C:\340source SET D_OPTIONS= -b SET C_DIR=C:\340tools CLS emurst
PATH statement Environment variables Identify I/O space
Reset the emulator
(b) Sample initdb.bat file to use with the debugger PATH statement Environment variables Identify I/O space Reset the emulator
PATH=C:\emu34020;%path% SET D_DIR=C:\emu34020 SET D_SRC=C:\340source SET D_OPTIONS= -b emurst
Invoking the new or modified batch file
-
If you modify the autoexec.bat file, you must invoke the file before invoking the debugger for the first time. To invoke this file, enter:
autoexec
If you create an initdb.bat file, you must invoke the file before invoking the debugger for the first time. After that, you must invoke initdb.bat any time that you power up or reboot your PC. To invoke this file, enter:
initdb
Chapter Title--Attribute Reference
v
Setting Up the Debugger Environment
Modifying the PATH statement
Step 1: Define a path to the debugger directory. The general format for doing this is:
PATH=C:\emu34020
This allows you to invoke the debugger without specifying the name of the directory that contains the debugger executable file.
-
If you are modifying an autoexec that already contains a PATH statement, simply include ;C:\emu34020 at the end of the statement as shown in Figure 3-1 (a). If you are using the initdb.bat file, use a different format for the PATH statement: PATH=C:\emu34020;%path% The addition of ;%path% ensures that this PATH statement won't undo PATH statements in any other batch files (including the autoexec.bat file).
Setting up the environment variables
An environment variable is a special system symbol that the debugger uses for finding or obtaining certain types of information. The debugger uses three environment variables, named D_DIR, D_SRC, and D_OPTIONS. The next three steps tell you how to set up these environment variables. The format for doing this is the same for both the autoexec.bat and initdb.bat files. Step 2: Set up the D_DIR environment variable to identify the emu34020 directory:
SET D_DIR=C:\emu34020
(Be careful not to precede the equal sign with a space.) This directory contains auxiliary files (such as emuinit.cmd) that the debugger needs. Step 3: Set up the D_SRC environment variable to identify any directories that contain program source files that you'll want to look at while you're debugging code. The general format for this is: SET D_SRC=C:\pathname1 ;pathname2 ... (Be careful not to precede the equal sign with a space.) For example, if you keep all of your C source files in a directory named CSOURCE, the line will look like this:
SET D_SRC=C:\CSOURCE
vi
Setting Up the Debugger Environment
Step 4: You can use several options when you invoke the debugger. If you use the same options over and over, it's convenient to specify them with D_OPTIONS. The general format for doing this is: SET D_OPTIONS= [object filename] [debugger options] (Be careful not to precede the equal sign with a space.) This tells the debugger to load the specified object file and use the specified options each time you invoke the debugger. These are the options that you can identify with D_OPTIONS: -b[bbbb] -p port address -i pathname -v
-s
For more information about debugger options, see Section 3.5 (page xii). Note that you can override D_OPTIONS by invoking the debugger with the -x option. If you specify a -p option, it will be used by both the debugger and the emurst utility.
Identifying the correct I/O switches
Step 5: If you didn't modify the emulator's I/O switches when you installed the emulator board, skip this step. If you modified the I/O switch settings, you must use the debugger's -p option to identify the I/O space that the emulator is using. You can do this each time you invoke the debugger, or you can specify this information by using the D_OPTIONS environment variable as shown in Table 3-1.
Table 3-1. Using D_OPTIONS to Identify Nondefault I/O Address Space
switch # 1 0x0220-0x023F 0x0300-0x031F 0x03E0-0x03FF on off off 2 on on off Add this line to the autoexec.bat or initdb.bat file SET D_OPTIONS=-P 220 SET D_OPTIONS=-P 300 SET D_OPTIONS=-P 3E0
Chapter Title--Attribute Reference
vii
Setting Up the Debugger Environment
Resetting the emulator
Step 6: To reset the emulator, invoke the emurst utility that comes with the debugger package. The general format for doing this is: emurst [ -x] [-p port address] You can include the emurst command in the autoexec.bat or initdb.bat file; the command format is the same for either type of file. If you didn't modify the I/O switches, it is not necessary to use either of emurst's parameters. If you modified the I/O switches, you can use the -p option as shown in Table 3-2. If you already specified -p with the D_OPTIONS environment variable, it is not necessary to use -p with the emurst utility.
Table 3-2. -x Options for the emurst Utility
switch # 1 0x0220-0x023F 0x0300-0x031F 0x03E0-0x03FF on off off 2 on on off Invoke emurst with this option emurst -p 220 emurst -p 300 emurst -p 3E0
If you set emurst's -p option with D_OPTIONS and need to override it, invoke emurst from the DOS prompt by using both -x and -p:
emurst -x -p new port address
This tells emurst to ignore the port address supplied by D_OPTIONS and to use the new one that was specified on the command line. A port address specified with emurst must not differ from the D_OPTIONS port address unless you also use emurst's -x option. Note that running emurst places the emulator board and the target cable buffer pod in a disconnected state: the '34020 does not perform emulation functions and executes as if the emulator is not installed. Every time the target's power is cycled, the buffer pod automatically switches to the disconnect state. However, if the debugger is not running when target power is cycled, a mismatch state can occur between the pod and the controller. To avoid this problem, always execute emurst after powering up the target system. Also, after powering up the target system, you must reset the '34020 before you can use the debugger. If the debugger is running and you need to cycle the target power, enter a RUNF command first. These situations also apply to
viii
Running Title--Attribute Reference
applications where the target system and the emulator board are in different PCs.
Chapter Title--Attribute Reference
ix
Setting Up for TIGA Applications
3.4 Setting Up for TIGA Applications
If you plan to debug your own custom TIGA modules, you will need to run your application and the debugger on separate PCs. If you do not plan to debug your own custom TIGA modules, skip this section; turn to Section 3.5, Invoking the Debugger, on page xii. Figure 3-2 shows the various components that are needed on the TIGA (target) side and the debugger (host) side.
Figure 3-2. Components Required for Debugging a TIGA Application
Target PC '340 board tigacd driver (TIGA version 2.05) Object code and target RLMs tigagm.out extprims.rlm Host PC '340 debugger init.cmd Object code and target RLMs Source files tigagm.out extprims.rlm
emulator serial cable
This system requires no special communication drivers. However, there are a few additional installation steps that you must follow: Step 1: Install the TIGA communications driver (tigacd) on the target PC. On the target PC, enter:
TIGACD /D1
This enables the emulator version of the communication driver's debug mode. Later, if you need to disable this mode, enter:
TIGACD /D0
Step 2: For each module that you plan to debug, copy the source and object code to the host PC. The source code can go in any directory, but the object code must reside in the same directory as db340emu.exe (the emu34020 directory).
x
Setting Up for TIGA Applications
Step 3: Be sure that you have copied tigagm.out and, if you are using TIGA extended primitives, extprims.rlm to the directory on the target PC that contains tigacd. Also copy them to the emu34020 directory on the host PC. Step 4: On the host PC, invoke the debugger:
db340emu
The debugger should come up in a state where the '340 processor is in an endless loop. Use the RUN command (or press F5 ) to start the processor running. Step 5: Verify that the debugger is working properly by reloading the TIGA graphics manager. On the target PC, enter:
tigalnk /lx
The debugger should display a message indicating that it has successfully loaded the TIGA graphics manager. If "File Not Found" types of errors show up on the host PC, check your setup against the illustration in Figure 3-2 (page x). Be sure that all of the files have been copied to the correct directories and that the serial cable is set up correctly.
Chapter Title--Attribute Reference
xi
Invoking the Debugger
3.5 Invoking the Debugger
Here's the basic format for the command that invokes the debugger: db340emu [filename] [-options] db340emu is the command that invokes the emulator version of the debugger. 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. supply the debugger with additional information (see Table 3-3).
filename
-options
You can also specify filename and option information with the D_OPTIONS environment variable (see Setting up the environment variables, page vi).
Table 3-3. Debugger Options
Option -b[bbbb] Description Screen-size options. By default, the debugger uses an 80-character-by-25-line screen. If you have a special graphics card, however, you can choose one of several larger screen sizes. Option none -b -bb -bbb -bbbb -bbbbb -p port address Characters/Lines 80 by 25 80 by 43 (EGA) 80 by 50 (VGA) 120 by 43 132 by 43 80 by 60 100 by 60 Notes This is the default display Use any EGA or VGA card Currently, the debugger supports these modes on a Video Seven VEGA Deluxe card.
Port address. -p identifies the I/O port address that the debugger uses for communicating with the emulator. If you used the emulator's default switch settings, you don't need to use the -p option. If you used nondefault switch settings, you must use -p. Depending on your switch settings, replace port address with one of these values: Switch 1 on on off off Switch 2 on off on off Option -p 220 none needed (default setting) -p 300 -p 3E0
-s
Load symbol table only. If you supply a filename when you invoke the debugger, you can use the -s option to tell the debugger to load only the file's symbol table (without the file's object code). This is similar to the debugger's SLOAD command.
xii
Invoking the Debugger / Exiting the Debugger
Table 3-3. Debugger Options (Continued)
Option -i pathname Description Additional directories. -i 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: db340emu -i path1 -i path2 -i path3 . . .
Using -i is similar to using the D_SRC environment variable (described on page vi). 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 D_SRC and the debugger USE command). -mc '34082 support. -mc tells the debugger to provide '34082 support. This allows you to access '34082 register values and tells the debugger to disassemble '34082 coprocessor instructions. Floating-point format. By default, the debugger expects source code to use '340 floating-point format. The -mf option tells the debugger to expect IEEE floating-point format (IEEE std 754-1985) instead. If you are already using -mc, it is not necessary to use -mf. -v Load without symbol table. This option prevents the debugger from loading the entire symbol table when you load an object file. The debugger loads only the global symbols and later loads local symbols as it needs them. This speeds up the loading time and consumes less memory space. The -v option affects all loads, including loading when you invoke the debugger and loading with the LOAD command within the debugger environment. -x -t filename Ignore D_OPTIONS. -x tells the debugger to ignore any information supplied with D_OPTIONS. New initialization file. The -t option allows you to specify an initialization command file that will be used instead of emuinit.cmd.
-mf
3.6 Exiting the Debugger
To exit the debugger and return to the operating system, enter this command: quit You don't need to worry about where the cursor is or which window is active--just type. If a program is running, press ESC to halt program execution before you quit the debugger.
Chapter Title--Attribute Reference
xiii
Chapter 4
An Introductory Tutorial to the C Source Debugger
This chapter provides a step-by-step, hands-on demonstration of the '340 C source debugger's basic features. This is not the kind of tutorial that you can take home to read --this tutorial is effective only if you're sitting at your PC, performing the lessons in the order they're presented. This tutorial contains two sets of lessons (11 in the first, 14 in the second) and takes about one hour to complete.
Chapter Title--Attribute Reference
i
How to Use This Tutorial
Synopsis Page
Reading these sections will help you get the most out of the tutorial.
How to use this tutorial A note about entering commands An escape route (just in case)
Topic
ii iii iv
The first set of lessons introduces you to basic debugger operation. You'll learn how to invoke the debugger and load object code, and you'll become acquainted with the main features of the debugger display. You'll also learn how to view a C source file and how to select one of the three debugging modes.
Invoke the debugger and load the sample program's object code Now what should I see? What's in the DISASSEMBLY window? Select the active window Resize the active window Zoom the active window Move the active window Scroll through a window's contents Display the C source version of the sample file Execute some code Become familiar with the three debugging modes
v vi vii vii ix x xi xii xiii xiii xiv
The second set of lessons shows you how to execute your programs and concentrates on the debugger's advanced features: setting breakpoints, benchmarking code, and observing the effects of program execution on selected variables, memory locations, and registers.
Open another text file, then redisplay a C source file Use the basic RUN command Set some breakpoints Benchmark a section of code (emulator only) Watch some values and single-step through code Run code conditionally WHATIS that? Clear the COMMAND window display area Display the contents of an aggregate data type Display data in another format Change some values Define a memory map Close the debugger Define your own command string
xvi xvii xvii xix xx xxii xxiii xxiv xxiv xxviii xxx xxxi xxxii xxxii
How to use this tutorial
This tutorial contains three basic types of information: Primary actions Primary actions identify the main lessons in the tutorial; they're boxed so you can find them easily. A primary action looks like this:
ii
A Note About Entering Commands / An Escape Route
Make the CPU window the active window: win CPU
Important information
In addition to primary actions, important information ensures that the tutorial works correctly. Important information is marked like this:
Important! The CPU window should still be active from the previous step.
Alternative actions
Alternative actions show additional methods for performing the primary actions. Alternative actions are marked like this:
Another way to display the current code in MEMORY is to show memory beginning from the current PC. . . Try This:
As you go through this tutorial, perform the primary actions and pay close attention to the important information. To learn even more about using the debugger, perform the alternative actions, too.
Important!
This tutorial assumes that you have correctly and completely installed your development board or emulator (including invoking any files or DOS commands as instructed in the installation chapters).
A note about entering commands
Whenever this tutorial tells you to type a debugger command, just type --the debugger automatically places the text on the command line. You don't have to worry about moving the cursor to the command line; the debugger takes care of this for you. (There are a few instances when this isn't true --for example, when you're editing data in the CPU or MEMORY window --but this is explained later in the tutorial.) Also, you don't have to worry about typing commands in uppercase or lowercase--either is fine. There are a few instances when a command's parameters must be entered in uppercase, and the tutorial points this out.
Chapter Title--Attribute Reference
iii
Running Title--Attribute Reference
An escape route (just in case)
The steps in this tutorial create a path for you to follow. The tutorial won't purposely lead you off the path. But sometimes when people use new products, they accidently press the wrong key, push the wrong mouse button, or mistype a command. Suddenly, they're off the path without any idea of where they are or how they got there. This probably won't happen to you. But, if it does, you can almost always get back to familiar ground by pressing ESC . If you were running a program when you pressed ESC , you should also type RESTART . Then go back to the beginning of whatever lesson you were in and try again.
iv
Invoke the Debugger and Load the Sample Program's Object Code
Invoke the debugger and load the sample program's object code
Included with the debugger is a demonstration program named sample. This lesson shows you how to invoke the debugger and load the sample program. You will use the -b option so that the debugger uses a larger display.
If you are using the emulator, this step assumes that you are using the default I/O switches or that you have identified the I/O switches with the D_OPTIONS environment variable (as described in the installation instructions in Chapter 3).
Important!
Invoke the debugger and load the sample program: For a development board, enter: db340 -b c:\db\sample For the emulator, enter: db340emu -b c:\emu34020\sample
Chapter Title--Attribute Reference
v
Now What Should I See?
Now what should I see?
Now you should see a display similar to this (it may not be exactly the same display, but it should be close).
menu bar with pulldown menus current PC (highlighted) reverse assembly of memory contents register contents
Load
Brea
Watch c_int00:
Memory SETF MOVI MOVE MOVE MOVI MOVE MOVI CMPI JRZ MOVE MOVE CALLA CALLA MOVE MOVK
Color
MoDe
Run=F5
Step=F8
Next=F10 CPU PC ST A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13 A14 A15 ffc00850 00000010 00000000 00000000 00000000 c0000010 00000000 00000000 00000000 00000040 00000000 ffc45da0 ffffffff 00001795 00000000 ffc363e0 ffc363e0 ffffa000 4006 400d 4014 401b 4022 4029
k DISASSEMBLY ffc00850 0740 ffc00860 09e9 ffc00890 4d2d ffc008a0 4d2e ffc008b0 09e9 ffc008e0 4d2f ffc008f0 09ea ffc00920 0b4a ffc00940 ca05 ffc00950 a3cf ffc00960 934e ffc00970 0d5f ffc009a0 0d5f ffc009d0 a3cf ffc009e0 182b
32,0,0 -3972128,A9 A9,A13 A9,A14 -3908192,A9 A9,SP -1,A10 -1,A10 0ffc009a0h A14,*-SP,1 A10,*A14+,1 var_init main A14,*-SP,1 1,A11 MEMORY 00000000 4000 00000070 4007 000000e0 400e 00000150 4015 000001c0 401c 00000230 4023
COMMAND window display area memory contents command line
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instrume TMS340x0 Development Board
4001 4008 400f 4016 401d 4024
4002 4009 4010 4017 401e 4025
4003 400a 4011 4018 401f 4026
40004 4005 400b 4012 4019 4020 4027 400c 4013 401a 4021 4028
>>>
-
If you don't see a display, then your development board or emulator may not be installed properly. Go back through the board installation instructions and be sure that you followed each step correctly; then reinvoke the debugger. If you still don't see a display, use the troubleshooting information in Appendix A. If you do see a display, check the first few lines of the DISASSEMBLY window. If these lines aren't the same--if, for example, they show ADD instructions--then enter the following commands on the debugger command line. (Just type; you don't have to worry about where the cursor is.) 1) Reset the '340 processor:
reset
2) Load the sample program again:
Development board: Emulator:
vi
load c:\db\sample load c:\emu34020\sample
What's in the DISASSEMBLY Window? / Select the Active Window
What's in the DISASSEMBLY window?
The DISASSEMBLY window always shows the reverse assembly of memory contents; in this case, it shows an assembly language version of sample.out. The MEMORY window displays the current contents of memory. Because you loaded the object file sample.out when you invoked the debugger, memory contains the object code version of the sample file. This tutorial step demonstrates that the code shown in the DISASSEMBLY window corresponds to memory contents. Initially, memory is displayed starting at address 0; if you look at the first line of the DISASSEMBLY window, you'll see that its display starts at address 0xFFC0 0850.
Modify the MEMORY display to show the same object code that is displayed in the DISASSEMBLY window: mem 0xffc00850
Notice that the first column in the DISASSEMBLY window corresponds to the addresses in the MEMORY window; the second column in the DISASSEMBLY window corresponds to the memory contents displayed in the MEMORY window.
Try This: Another way to display the current code in MEMORY is to show
memory beginning from the current PC:
mem pc
Select the active window
This lesson shows you how to make a window into the active window. You can move and resize any window; you can close some windows. Whenever you type a command or press a function key to move, resize, or close a window, the debugger must have some method of understanding which window you want to affect. The debugger does this by designating one window at a time to be the active window. Any window can be the active window, but only one window can be active at a time.
Chapter Title--Attribute Reference
vii
Select the Active Window
Make the CPU window the active window: win CPU
Important! If this didn't work, look at the way you entered the command. Did
you enter CPU in uppercase letters? For this command, it's important that you enter the parameter in uppercase as shown. Notice the appearance of the CPU window (especially its borders) in contrast to the other, inactive windows. This is how you can tell which window is active.
Important!
key "hops" through the windows in the display, making each one active in turn. Press F6 as many times as necessary until the CPU window becomes the active window again.
F6
Try This: Pressing the
Try This: You can also use the mouse to make a window active:
1) Point to any location on the window's border. 2) Click the left mouse button.
Be careful! If you point inside the window, the window becomes active when you press the mouse button, but something else may happen as well:
-
If you're pointing inside the CPU window, then the register you're pointing at becomes active. The debugger then treats any text you type as a new value for that register. Similarly, if you're pointing inside the MEMORY window, the address you're pointing at becomes active.
Press
ESC
to get out of this.
If you're pointing inside the DISASSEMBLY or FILE window, you'll set a breakpoint on the statement that you were pointing to.
Point to the same statement; press the button again to delete the breakpoint.
viii
Resize the Active Window
Resize the active window
This lesson shows you how to resize the active window.
Important! The CPU window should still be active from the previous step.
Make the CPU window as small as possible: size 4,3 This tells the debugger to make the window 4 characters by 3 lines, which is the smallest a window can be. (If it were any smaller, the debugger wouldn't be able to display all four corners of the window.) If you try to enter smaller values, the debugger will warn you that you've entered an Invalid window size. The maximum width and length depend on which -b option you used when you invoked the debugger. (If you'd like a complete list of the limits, see Table 6-1 on page 6-22.)
Make the CPU window larger: size
Enter the SIZE command without parameters Make the window 3 lines longer Make the window 4 characters wider Press this key when you finish sizing the window
You can also use narrower.
to make the window shorter and
to make the window
Try This: You can also use the mouse to resize the window (note that this
automatically causes the selected window to become the active window). 1) If you examine any window, you'll see a highlighted, backwards "L" in the lower right corner. Point to the lower right corner of the CPU window. 2) Press the left mouse button but don't release it; move the mouse while you're holding in the button. This resizes the window. 3) Release the mouse button when the window reaches the desired size.
Chapter Title--Attribute Reference
ix
Zooming the Active Window
Zoom the active window
Another way to resize the active window is to zoom it. Zooming the window makes it as large as possible.
Important! The CPU window should still be active from the previous steps.
Make the active window as large as possible: zoom
The window should now be as large as possible, taking up the entire display (except for the menu bar) and hiding all the other windows. You can "unzoom" the window by entering the ZOOM command again. Return the window to its previous size. (Even though the COMMAND window is hidden by the CPU window, the ZOOM command will be recognized.) zoom
The window should now be back to the size it was before zooming.
Try This: You can also use the mouse to zoom the window.
Zoom the active window: 1) Point to the upper left corner of the active window. 2) Click the left mouse button. Return the window to its previous size by repeating these steps.
x
Move the Active Window
Move the active window
This lesson shows you how to move the active window.
Important! The CPU window should still be active from the previous steps.
Move the CPU window to the upper left portion of the screen: move 0,1
The debugger doesn't let you move the window to the very top--that would hide the menu bar
The MOVE command's first parameter identifies the window's new X position on the screen. The second parameter identifies the window's new Y position on the screen. The maximum X and Y positions depend on which -b option you used when you invoked the debugger. (For a complete list of the limits, see Table 6-2 on page 6-25.)
Try This: You can use the MOVE command with no parameters and then use
arrow keys to move the window:
move

ESC
Press until the CPU window is back where it was (it may seem like only the border is moving--this is normal) Press ESC when you finish moving the window
You can also use to move the window up, and to move the window left.
to move the window down,
Try This: You can also use the mouse to move the window (note that this
automatically causes the selected window to become the active window). 1) Point to the top edge or left edge of the window border. 2) Press the left mouse button but don't release the button; move the mouse while you're holding in the button. 3) Release the mouse button when the window reaches the desired position.
Chapter Title--Attribute Reference
xi
Scroll Through a Window's Contents
Scroll through a window's contents
Many of the windows contain more information than can possibly be displayed at one time. You can view hidden information by moving through a window's contents. The easiest way to do this is to use the mouse to scroll the display up or down.
If you examine most windows, you'll see an up arrow near the top of the right border and a down arrow near the bottom of the right border. These are scroll arrows. Scroll through the contents of the DISASSEMBLY window: 1) Point to either of the scroll arrows. 2) Press the left mouse button; continue pressing it until the display has scrolled several lines. 3) Release the button.
Try This: You can also use several of the keys to modify the display in the
active window. Make the MEMORY window the active window:
win MEMORY
Now try pressing these keys; observe their effects on the window's contents.
PAGE DOWN PAGE UP
These keys don't work the same for all windows; Section 14.3 (page 14-38) summarizes the functions of all the special keys, key sequences, and how their effects vary for the different windows.
xii
Display the C Source Version of the Sample File / Execute Some Code
Display the C source version of the sample file
Now that you can find your way around the debugger interface, you can get familiar with some of the debugger's more significant features. It's time to load some C code. Display the contents of a C source file: file sample.c
This opens a FILE window that displays the contents of the file sample.c (sample.c was one of the files that contributed to making the sample object file). You can always tell which file you're displaying by the label in the FILE window. Right now, the label should say FILE: sample.c.
Execute some code
Let's run some code --not the whole program, just a portion of it. Execute a portion of the sample program: go main
You've just executed your program up to the point where main() is declared. Notice how the display has changed:
-
The current PC is highlighted in both the DISASSEMBLY and FILE windows. The addresses and object code of the first four statements in the DISASSEMBLY window are highlighted; this is because all four statements are associated with the current C statement (line 53 in the FILE window). The CALLS window, which tracks functions as they're called, now shows that the current function is main(). The values of the program counter (PC), the stack pointer (SP), and possibly some additional registers are highlighted in the CPU window because they were changed by program execution.
Note: If you're using the emulator and the program doesn't stop after several seconds, press ESC and refer to Section A.4 (page A-7).
Chapter Title--Attribute Reference
xiii
Become Familiar With the Three Debugging Modes
Become familiar with the three debugging modes
The debugger has three basic debugging modes:
-
Mixed mode shows both disassembly and C code at the same time. Auto mode shows disassembly or C code, depending on what part of your program happens to be running. Assembly mode shows only the disassembly, no C code, even if you're executing C code.
When you opened the FILE window in a previous step, the debugger switched to mixed mode; you should be in mixed mode now. (You can tell that you're in mixed mode if both the FILE and DISASSEMBLY windows are displayed.) The following steps show you how to switch debugging modes.
Use the MoDe menu to select assembly mode: 1) Look at the top of the display: the first line shows a row of pulldown menu selections. 2) Point to the word MoDe on the menu bar. 3) Press the left mouse button, but don't release it; drag the mouse downward until Asm (the second entry) is highlighted. 4) Release the button. This switches to assembly mode. You should see the DISASSEMBLY window, but not the FILE window. Switch to auto mode: 1) Type . This displays and freezes the MoDe menu.
2) Now select C(auto). Choose one of these methods for doing this: Press the arrow keys to move up/down through the menu; when C(auto) is highlighted, press . Type C .
Point the mouse cursor at C(auto), then press and release the left mouse button.
lesson continues on the next page
xiv
Become Familiar With the Three Debugging Modes / Halfway Point
You should be in auto mode now, and you should see the FILE window but not the DISASSEMBLY window (because your program is in C code). Auto mode automatically switches between an assembly or a C display, depending on where you are in your program. Here's a demonstration of that: Run to a point in your program that executes assembly language code: go meminit
You're still in auto mode, but you should now see the DISASSEMBLY window. The current PC should be at the statement that defines the meminit label.
Try This: You can also switch modes by typing one of these commands:
asm c mix
switches to assembly-only mode switches to auto mode switches to mixed mode
Switch back to mixed mode.
You've finished the first half of the tutorial and the first set of lessons. If you're lucky enough to be going to lunch or going home at this point, you may want to close the debugger down. To do this, just type QUIT . When you come back, reinvoke the debugger and load the sample program (page v). Then turn to page xvi and continue with the second set of lessons. Still here? Turn the page.
Chapter Title--Attribute Reference
xv
Open Another Text File, Then Redisplay a C Source File
Open another text file, then redisplay a C source file
In addition to what you already know about the FILE window and the FILE command, you should also know that:
-
You can display any text file in the FILE window. If you enter any command that requires the debugger to display a C source file, it automatically displays that code in the FILE window (regardless of whether the window is open or not and regardless of what is already displayed in the FILE window).
Display a file that isn't a C source file: file init.cmd This replaces sample.c in the FILE window with the init.cmd file (init.cmd is a batch file that comes with the debugger).
Remember, you can tell which file you're displaying by the label in the FILE window. Right now, the label should say FILE: init.cmd.
Redisplay another C source file (sample1.c): func call
Now the FILE window label should say FILE: sample1.c because the call() function is in sample1.c.
xvi
Use the Basic RUN Command / Set Some Breakpoints
Use the basic RUN command
The debugger provides you with several ways of running code, but it has one basic run command.
Run your entire program: run
Entered this way, the command basically means "run forever". You may not have that much time!
This isn't very exciting: halt program execution:
Set some breakpoints
When you halted execution in the previous step, you should have seen changes in the display similar to the changes you saw when you entered go main earlier in the tutorial. When you pressed ESC , you had little control over where the program stopped. Knowing that information changed was nice, but what part of the program affected the information? This information would be much more useful if you picked an explicit stopping point before running the program. Then, when the information changed, you'd have a better understanding of what caused the changes. You can stop program execution in this way by setting breakpoints. This lesson assumes that you're displaying the contents of sample.c in the FILE window. If you aren't, enter:
file sample.c
Chapter Title--Attribute Reference
xvii Important!
Set Some Breakpoints
Set a breakpoint and run your program: 1) Scroll to line 58 in the FILE window (the meminit() statement) and set a breakpoint at that line: a) Point the mouse cursor at the statement on line 58. b) Click the left mouse button. Notice how the line is highlighted; this identifies a breakpointed statement. 2) Reset the program entry point: restart 3) Enter the run command: run
Program execution halts at the breakpoint
Once again, you should see that some statements are highlighted in the CPU window, showing that they were changed by program execution. But this time, you know that the changes were caused by code from the beginning of the program to line 58 in the FILE window.
Clear the breakpoint: 1) Point the mouse cursor at the statement on line 58. (It should still be highlighted from setting the breakpoint.) 2) Click the left mouse button. The line is no longer highlighted.
xviii
Benchmark a Section of Code (Emulator Only)
Benchmark a section of code (emulator only)
If you're using the '34020 emulator, you can use breakpoints to help you benchmark a section of code. This means that you'll ask the debugger to count the number of CPU clock cycles that are consumed by a certain portion of code.
Benchmark some code: 1) In sample.c (displayed in the FILE window), set two breakpoints: one at line 58 (the meminit() statement) and one at line 66 (the for(;;); statement). 2) Reset the program entry point: restart 3) Enter the run command: run 4) Enter the runb command: runb emulator only
This runs to the first breakpoint
This runs to the second breakpoint (this may take several seconds)
5) Now use the ? command to examine the contents of the CLK pseudoregister: ? clk
The debugger now shows a number in the display area; this is the number of CPU clock cycles consumed by the portion of code between the two breakpointed C statements.
The value in the CLK pseudoregister is valid only when you execute the RUNB command and when that execution is halted on breakpointed statements.
Important!
Delete both breakpoints: br
The BR (breakpoint reset) command deletes all breakpoints that were set
Chapter Title--Attribute Reference
xix
Watch Some Values and Single-Step Through Code
Watch some values and single-step through code
Now you know how to update the display without running your entire program; you can set breakpoints to obtain information at specific points in your program. But what if you want to update the display after each statement? No, you don't have to set a breakpoint at every statement --you can use single-step execution. For this lesson, you have to be at a specific point in the program --let's go there before we do anything else.
Set up for single-step example: restart go main
The debugger has another type of window called a WATCH window that's very useful in combination with single-step execution. What's a WATCH window for? Suppose you are interested in only a few specific register values, not all of the registers shown in the CPU window. Or suppose you are interested in a particular memory location or in the value of some variable. You can observe these data items in a WATCH window. Set up the WATCH window before you start the single-step execution.
Open a WATCH window: wa wa wa wa a15, Stack Pointer pc *0xffc36440, Call: i
You may have noticed that the WA (watch add) command can have one or two parameters. The first parameter is the item that you're watching. The second parameter is an optional label. If the WATCH window isn't wide enough to display the PC value, resize the window. lesson continues on the next page
xx
Watch Some Values and Single-Step Through Code
Now try out the single-step commands. Hint: Watch the PC in the FILE and DISASSEMBLY windows; watch the value of i in the WATCH window. Single-step through the sample program: step 50
Notice that the step command single-stepped each assembly language statement (in fact, you single-stepped through 50 assembly language statements). Did you also notice that the FILE window displayed the source for the call() function when it was called? The debugger supports more single-step commands that have a slightly different flavor.
Try This:
-
For example, if you enter:
cstep 50
you'll single-step 50 C statements, not assembly language statements (notice how the PC "jumps" in the DISASSEMBLY window). Reset the program entry point and run to main().
restart go main
Now enter the NEXT command, as shown below. You'll be single-stepping 50 assembly language statements, but the FILE window doesn't display the source for the call() function when call() is executed.
next 50
(There's also a CNEXT command that "nexts" in terms of C statements.)
Chapter Title--Attribute Reference
xxi
Run Code Conditionally
Run code conditionally
Take a look at the code following the meminit() statement; this code is doing a lot of work with a variable named i. You may want to check the value of i at specific points instead of after each statement. To do this, you set breakpoints at the statements you're interested in and then initiate a conditional run. First, clear out the WATCH window so that you won't be distracted by any superfluous data items.
Delete the first three data items from the WATCH window (don't watch them anymore): wd 3 wd 1 wd 1
i was the fourth item added to the WATCH window in the previous tutorial step, and it should now be the only remaining item in the window.
Set up for the conditional run examples 1) Set breakpoints at lines 59 and 61. 2) Reset the program entry point: restart 3) Run the first part of the program go main 4) Reset the value of i: ?i=0
Now initiate the conditional run: run i<100
lesson continues on the next page
xxii
Run Code Conditionally / WHATIS That?
This causes the debugger to run through the for loop as long as the value of i is less than 100. Each time the debugger encounters the breakpoints in the loop, it updates the value of i in the WATCH window. When the conditional run completes, close the WATCH window. Close the WATCH window: wr
WHATIS that?
At some point, you might like to obtain some information about the types of data in your C program. Maybe things won't be working quite the way you'd planned, and you'll find yourself saying something like "... but isn't that supposed to point to an integer?" Here's how you can check on this kind of information--be sure to watch the COMMAND window display area as you enter these commands.
Chapter Title--Attribute Reference
xxiii
Clear the COMMAND Window Display Area / Display the Contents of an Aggregate Data Type
Use the WHATIS command to find the types of some of the variables declared in the sample program: whatis genum enum yyy genum; whatis tiny6 struct { int u; int v; int x; int y; int z; } tiny6; whatis call int call(); whatis s short s; whatis bbb struct bbb { int a; int b; Press to halt long listings
genum is an enumerated type tiny6 is a structure
call is a function that returns an integer s is a short unsigned integer bbb is a very long structure
Clear the COMMAND window display area
After displaying all of these types, you may want to clean out the display area. This is easy to do. Clear the COMMAND window display area: cls
Try This: Here are examples of two more DOS-like commands that you can
use in the debugger environment:
cd .. dir
Change back to the main directory Show a listing of the current directory
Display the contents of an aggregate data type
The WATCH window is convenient for watching single, or scalar, values. When you're debugging a C program, though, you may need to observe values that
xxiv
Running Title--Attribute Reference
aren't scalar; for example, you might need to observe the effects of program execution on an array. The debugger provides another type of window called a DISP window where you can display the individual members of an array or structure. Show another structure in a DISP window: disp big1
Now you should see a display like the one below. The newly opened DISP window becomes the active window. Like the FILE window, you can always tell what's being displayed because of the way the DISP window is labeled. Right now, it should say DISP: big1.
DISP: big 1 b1 1450748877 b2 1450748877 b3 1450748877 b4 1450748877 b5 1450748877 q1 [...] q2 {...} q3 0x2af3559e
-
lesson continues on the next page
Members b1, b2, b3, b4, and b5 are ints; you can tell because they're displayed as integers (shown as plain numbers without prefixes). Member q1 is an array; you can tell because q1 shows [. . .] instead of a value. Member q2 is another structure; you can tell because q2 shows {. . .} instead of a value. Member q3 is a pointer; you can tell because it is displayed as a hexadecimal address (indicated by a 0x prefix) instead of an integer value.
Chapter Title--Attribute Reference
xxv
Display the Contents of an Aggregate Data Type
If a member of a structure or an array is itself a structure or an array, or even a pointer, you can display its members (or the data it points to) in additional DISP windows (referred to as the original DISP window's children). Display what q3 is pointing to: 1) Point at the address displayed next to the q3 label in big1's display. 2) Click the left mouse button. This opens a second DISP window, labeled DISP: big1.q3, that shows what q3 is pointing to (it's pointing to another structure). Close this DISP window by pressing F4 .
Display array q1 in another DISP window: 1) Point at the [. . .] displayed next to the q1 label in big1's display. 2) Click the left mouse button. This opens another DISP window labeled DISP: big1.q1. q1 is actually a 2-member array of structures. To view the two different structures, use CONTROL PAGE DOWN and CONTROL PAGE UP . (Look at the name of this DISP window when you're switching.)
lesson continues on the next page
Important!
Try This: Display structure q2 in another DISP window.
1) Close the additional DISP windows or move them out of the way so that you can clearly see the original DISP window that you opened to display big1. 2) Make big1's DISP window the active window.

3) Use these arrow keys to move the field cursor ( _ ) through the list of big1's members until the cursor points to q2. 4) Now press
F9
F9
.
xxvi
Running Title--Attribute Reference
This opens a window named DISP: big1.q2.
Close all of the DISP windows: 1) Make DISP: big1 the active window. 2) Press .
When you close the main DISP window, the debugger closes all of its children as well.
Chapter Title--Attribute Reference
xxvii
Display Data in Another Format
Display data in another format
Usually, when you add an item to the WATCH window or open a DISP window, the data is shown in its natural format. This means that ints are shown as integers, floats are shown as floating-point values, etc. Occasionally, you may wish to view data in a different format. This can be especially important if you want to show memory or register contents in another format. One way to display data in another format is through casting (which is part of the C language). In the expression below, the *(float *) portion of the expression tells the debugger to treat address 0x1000 as type float (exponential floating-point format). Display memory contents in floating-point format: disp *(float *)0x1000
This opens a DISP window to show memory contents in an array format. The "array" member identifiers don't necessarily correspond to actual addresses--they're relative to the first address you request with the DISP command. In this case, the item displayed as item [0] is the contents of address 0x1000--it isn't memory location 0. Note that you can scroll through the memory displayed in the DISP window; item [1] is at 0x1010, item [-1] is at 0x0FE0. You can also change display formats according to data type. This affects all data of a specific C data type. Change display formats according to data types by using the SETF (set format) command: 1) For comparison, watch the following variables. Their C data types are listed on the right. wa wa wa wa str.f1 longstr.A d ac[1]
Type int Type float Type double Type char
2) You can list all the data types and their current display formats: setf
xxviii
Display Data in Another Format
3) Now display the following data types with new formats: setf setf setf setf int, c float, o double, x char, d
Ints as characters Floats as octal integers Doubles as hex integers Chars as decimal integers
4) List the data types to display formats again; note the changes in the display: setf 5) Add the variables to the WATCH window again; use labels to identify the additions: wa wa wa wa str.f1, NEWstr.f1 longstr.A, NEWlongstr.A d, NEWd ac[1], NEWac[1]
Notice the differences in the display formats between the first versions you added and these new versions. 6) Now reset all data types back to their defaults: setf *
A third way to display data in another format is to use the DISP, ?, MEM, or WA command with an optional parameter that identifies the new display format. The following examples are for ? and WA--DISP and MEM work similarly. Use display formats with the ? and WA commands: 1) Evaluate a variable and display it as a character: ? small.ra[1],c 2) Add a variable to the watch window and display it as an octal integer: wa longstr.a,,o (Notice that because no label was used with WA, an extra comma was inserted--otherwise, the o parameter would have been interpreted as a label.)
To get ready for the next step, close the DISP and WATCH windows.
Chapter Title--Attribute Reference
xxix
Change Some Values
Change some values
You can edit the values displayed in the MEMORY, CPU, WATCH, and DISP windows.
Change a value in memory: 1) Move or close the WATCH window if it's obscuring the MEMORY window; then, display memory beginning with address 0x1000: mem 0x1000 2) Point to the contents of memory location 0x1000. 3) Click the left mouse button. This highlights the field to identify it as the field that will be edited. 4) Type 0000. 5) Press 6) Press to enter the new value. to conclude editing.
Try This: Here's another method for editing data. This method lets you edit
a few more values at once. 1) Make the CPU window the active window:
win CPU

2) Press the arrow keys until the field cursor ( _ ) points to the PC contents. 3) Press
F9
F9
.
4) Type ffc000000.
5) Press
twice. You should now be pointing at the contents of register A2.
6) Type ffff. 7) Press
ESC
to enter the new value.
ESC
8) Press
to conclude editing.
xxx
Define a Memory Map
Define a memory map
You can set up a memory map to tell the debugger which areas of memory it can and can't access. This is called memory mapping. By default, memory mapping is disabled, which means that the debugger assumes that all of memory is available for its use. For the purposes of the sample program, that's fine (which is why this lesson was saved for next-to-last). Memory mapping is a simple process of identifying the memory space in your application and identifying whether the spaces are read/write, protected, etc. Here's an example. Enable memory mapping: map on
Look at the DISASSEMBLY and MEMORY windows. Mapping is enabled, but the actual memory map hasn't been defined yet. So, all of the address values in the MEMORY are highlighted as invalid (on color monitors, the default method for indicating invalid memory contents is to show them in red). Because memory contents is now invalid, the disassembly of memory in the DISASSEMBLY window no longer shows assembly language code --each line says Invalid address. Define a memory map: 1) Use the MA (memory add) command to map a block of program memory: ma 0xffc00000,0x0010000,RAM Program memory is now valid -- the DISASSEMBLY window displays assembly language code again. 2) Add in a block of memory for '340 I/O registers: ma 0xc0000000,0x10000000,RAM
Try This: The debugger supports a memory list command that tells you how
memory is currently mapped:
ml
Look in the COMMAND window display area -- you'll see a listing of the two areas that you defined.
Chapter Title--Attribute Reference
xxxi
Define Your Own Command String / Close the Debugger
Define your own command string
If you find that you often enter a command with the same parameters, or often enter the same commands in sequence, you will find it helpful to have a shorthand method for entering these commands. The debugger provides an aliasing feature that allows you to do this. This lesson shows you how you can define an alias to set up a memory map, defining the same map that was defined in the previous lesson. Define an alias for setting up the memory map: 1) Use the ALIAS command to associate a nickname with the commands used for defining a memory map: alias mymap,"mr;ma 0xffc00000,0x0010000,RAM; ma0xc0000000,0x10000000,RAM;ml" (Note: Because of space constraints, the command is shown on two lines.) 2) Now, to use this memory map, just enter the alias name: mymap This is equivalent to entering the following four commands: mr ma 0xffc00000,0x0010000,RAM ma 0xc0000000,0x10000000,RAM ml
Close the debugger
This is the end of the tutorial -- close the debugger. Close the debugger and return to DOS: quit
xxxii
Chapter 5
Overview of a Code Development and Debugging System
The '340 C source debugger is an advanced software interface that helps you to develop, test, and refine '340 C programs (compiled with the '340 optimizing ANSI C compiler) and assembly language programs. This chapter provides an overview of the C source debugger and describes the '340 code development environment.
Synopsis Page
The chapter provides an overview of the debugger and the debugging process and describes how the debugging process fits in with the overall code development process.
5.1 5.2 5.3 Description of the '340 C Source Debugger Key features of the debugger Developing Code for the '340 Preparing Your Program for Debugging Assembling and/or compiling your program Program constraints for development board applications Debugging '340 Programs
Topic
ii iii v viii viii x xi
5.4
Chapter Title--Attribute Reference
i
Description of the '340 C Source Debugger
5.1 Description of the '340 C Source Debugger
The '340 C source debugger 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 '340 debugger's higher level features are available even when you're debugging assembly language code. The debugger 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 5-1 identifies several features of the debugger display.
Figure 5-1. The Debugger Display
pulldown menus disassembly display
Load Brea Watch Memory Color MoDe Run=F5 Step=F8 Next=F10
C source display
interactive command entry and history window
k DISASSEMBLY ffc00350 098f call: MMTM SP,A11,FP ffc00370 4dcd MOVE STK,FP ffc00380 93ee MOVE SP,*STK+,1 ffc00390 c10a JRUC call+496(0ffc00540h) ffc003a0 b7ab MOVE @newvalue,A11,1 ffc003c0 078b MOVE A11,@str,1 ffc003f0 c01f JRUC call+672(0ffc005f0h) FILE: sample.c 00008 }; MOVE @newvalue,A11,1 ffc00400 b7ab 00009 ffc00420 102b INC A11 00010 extern struct xxx str; ffc0 00011 ffc0 00012 call(newvalue) 00013 int newvalue; ffc0 00014 { static int value = 0; ffc0 00015 00016 ffc0 00017 switch (newvalue & 3) ffc0 00018 { DISP: astr[7] 00019 case 0 : str.a = newvalue ; a 123 ffc0 00020 case 1 : str.b = newvalue + 1; b 555 ffc0 00021 case 2 : str.c = newvalue * 2; c 75435 DISP: 00022 case 3 : xcall(newvalue); [0] f1 3 f2 6 [1] f3 0x00f000a [2] f4 [...] [3] [4] COMMAND [5] whatis str [6] [7] struct xxx str; [8] step [9] >>>
CPU PC ffc00350 ST 20000010 1: main() A0 00000000 A1 00000080 A2 00000000 WATCH A3 c0000010 1: str.a 0 2: F0 1.000000e A4 00000000 A5 00000000 3: color GREEN A6 00000000 A7 00000040 A8 00000000 A9 00000000 A10 ffffffff A11 00001795 A12 00000000 A13 ffc363e0 A14 ffc36460 A15 ffc45cc0 B0 ffffffff MEMORY [PROG] 0107 bf08 09f5 break; 0109 bf09 09f5 return 010b bf00 be47 astr[7].f4 010d bf80 017c break; 0 010f b801 e388 9 0111 0114 7a89 7 0113 0118 7a89 54 0115 0040 8a89 3 0017 0163 7802 3 0019 bf80 017c 4 001b 8b88 a6a0 123 001d b801 a680 4 001f 0290 038b 789 0121 7b9a 0126 0123 8b89 7c02 0125 ef00 b801 CALLS 2: call()
function call traceback natural-format data displays
scrolling data displays with on-screen, interactive editing
ii
Description of the '340 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 '340 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.
Chapter Title--Attribute Reference
iii
Description of the '340 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.
-
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. Plus, 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 single-stepping 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.
-
iv
Developing Code for the '340
5.2 Developing Code for the '340
The '340 is supported by a complete set of hardware and software development tools, including a C compiler, assembler, and linker. Figure 5-2 illustrates the '340 code development flow. The figure highlights the most common paths of software development; the other portions are optional.
Figure 5-2. '340 Software Development Flow
C source files
C compiler
assembler source
macro libraries
assembler
COFF object files
software libraries
linker
executable COFF file
object format converter '340 target system
debugging tools
EPROM programmer
Chapter Title--Attribute Reference
v
Developing Code for the '340
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 5-2. The '340 optimizing ANSI C compiler is a full-featured optimizing compiler that translates standard ANSI C programs into '340 assembly language source. Key characteristics include:
C compiler
-
-
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. 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, 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.
-
vi
Developing Code for the '340
assembler
The assembler translates '340 assembly language source files into machine language object files. The archiver allows you to collect a group of files into a library. It also allows you to modify a library by deleting, replacing, extracting, or adding members. One of the most useful applications of the archiver is to build a library of object modules. Several object libraries and a source library are included with the C compiler. 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 '340 target system. You can use one of a variety of debugging tools to refine and correct your code. Each uses the '340 debugger as a software interface:
archiver
linker
debugging tools
-
The emulator version of the debugger supports the TI realtime emulator for the '34020. The development board version of the debugger supports an entire class of '340-based PC development boards that use TIGA and a TIGA communication driver. TI has two such boards: the '34010 TIGA development board and the '34020 software development board.
object format converter
An object format converter is also available; it converts a COFF object file into an Intel, Tektronix, or TI-tagged object-format file that can be downloaded to an EPROM programmer.
Chapter Title--Attribute Reference
vii
Preparing Your Program for Debugging
5.3 Preparing Your Program for Debugging
This section describes the steps that you must go through when preparing a '340 program and discusses constraints that apply to development board programs.
Assembling and/or compiling your program
Figure 5-3 illustrates the steps you must go through to prepare a program for debugging.
Figure 5-3. 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
executable object code
If you're preparing to debug a C program. . .
1) Compile the program; use the -g option. Use the -mc option for '34082 support. Use the -mf option for IEEE floating-point support without the '34082 support. 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.
viii
Preparing Your Program for Debugging
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 GSPCL shell program. The TMS340 Code Generation Tools User's Guide contains complete instructions for invoking the tools individually and for using the shell program. For your convenience, here's the basic command for invoking the shell program when preparing a program for debugging:
gspcl [-options] -g [filenames] [-vnn] [-mc | -mf] [-z [link options]]
gspcl
is the command that invokes the compiler and assembler. affect the way the shell processes input files. are one or more C source files, assembly language source files, or object files. Filenames are not case sensitive. 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. provides '34082 support. If you plan to use the debugger's -mc option, then you must also use the -mc option when compiling your code. provides IEEE support (without '34082 support). If you plan to use the debugger's -mf option, then you must also use the -mf option when compiling your code. is an option that tells the tools to produce code for either the '34010 or '34020; the nn is a number that identifies the correct device: -v10 creates object code for the '34010 -v20 creates object code for the '34020 By default, the tools expect '34020 source and create '34020 object. So, if you are debugging a '34020 program, it's not necessary to use the -v option. However, if you are debugging a '34010 program, you must use the -v option. 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.
options filenames
-g
-mc
-mf
-v
-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.
Chapter Title--Attribute Reference
ix
Preparing Your Program for Debugging
The shell identifies a file's type by the filename's extension.
Extension .c .asm .s* (any extension that begins with s) .o* (extension begins with o) none (.c assumed) File Type C source assembly language source assembly language source object file C source File Description compiled, assembled, and linked assembled and linked assembled and linked linked compiled, assembled, and linked
Program constraints for development board applications
When preparing a '340 program for debugging on a development board, observe the following constraints:
-
Your program should not modify these vectors or TRAP instructions:
Vector address 0xFFFF FC40 0xFFFF FBE0 TRAP instruction TRAP 29 Used for debugger breakpoints TRAP 32 ('34020 only) Used for debugger single stepping
-
Your program should not rely on accessing previous stack contents that were popped off the stack. 34020 only:
J J
Your program should not use the single-step interrupt. When an interrupt is serviced, the program counter and status register values are pushed onto the stack. If a RUN command is executing when the interrupt occurs, the single-step bit may be set in the status register value that is pushed on the stack. The interrupt service routine should not modify this bit.
x
Debugging '340 Programs
5.4 Debugging '340 Programs
Debugging a program is a multiple-step process. These steps are described below, with references to parts of this book that will help you accomplish each step. Step 1 Prepare a C program or assembly language program for debugging. Step 2 Ensure that the debugger has a valid memory map. Step 3 Load the program's object file.
See Section 9.3, Loading Object Code, page 9-8. See Chapter 8, Defining a Memory Map See Section 5.3, Preparing a Program for Debugging, page viii.
Step 4 Run the loaded file. You can run the entire program, run parts of the program, or singlestep through the program. Step 5 Stop the program at critical points and examine important information. Step 6 If you find a mistake in your source code, exit the debugger, edit your source file, and return to step 1.
See Chapter 12, Using Breakpoints, and Chapter 11, Managing Data. See Running Your Programs on page 9-10.
Chapter Title--Attribute Reference
xi
page
xii
Chapter 6
The Debugger Display
The '340 C source debugger has a window-oriented display. This chapter shows what windows can look like and describes the basic types of windows that you'll use.
Chapter Title--Attribute Reference
i
Running Title--Attribute Reference
Synopsis Page
The debugger's three modes use a set of three default displays. These modes control the types of information that you can display and the types of actions that you can perform. The debugger can display eight different types of windows. Each has a unique purpose.
6.1 Debugging Modes and Default Displays Auto mode Assembly mode Mixed mode Restrictions associated with debugging modes
Topic
iii iii v vi vi
6.2
Descriptions of the Different Kinds of Windows and Their Contents COMMAND window DISASSEMBLY window FILE window CALLS window MEMORY window CPU window I/O window FPU window DISP windows WATCH window
vii viii viii x xi xiii xiv xv xvi xvii xviii
The windows in the debugger display aren't fixed in position or size. You can resize, move, and, in some cases, close windows. The window that you're going to move, resize, or close must be the active window.
6.3 6.4
Cursors The Active Window Identifying the active window Selecting the active window Manipulating Windows Resizing a window Zooming the active window Moving a window Manipulating a Window's Contents Scrolling through a window's contents Editing the data displayed in windows Closing a Window
xix xx xx xxi xxiii xxiii xxv xxvi xxix xxix xxx xxxii
6.5
6.6
6.7
ii
Debugging Modes and Default Displays
6.1 Debugging Modes and Default Displays
The debugger has three debugging modes:
-
Auto mode Assembly mode Mixed mode
Each mode changes the debugger display by adding or hiding specific windows. Some windows, such as the COMMAND window, may be present in all modes. The following figures show the default displays for these modes and show the windows that the debugger automatically displays for these modes. In addition to the default windows shown in these illustrations, you can also display DISP windows and the WATCH window (see Section 6.2, page vii).
Auto mode
In auto mode, the debugger automatically displays whatever type of code is currently running -- assembly language or C. This is the default mode; when you first invoke the debugger, you'll see a display similar to Figure 6-1. Auto mode has two types of displays:
-
When the debugger is running assembly language code, you'll see an assembly display similar to the one in Figure 6-1. The DISASSEMBLY window displays the reverse assembly of memory contents.
Chapter Title--Attribute Reference
iii
Debugging Modes and Default Displays
Figure 6-1. Typical Assembly Display (for Auto Mode and Assembly Mode)
Load Brea Watch c_int00: Memory SETF MOVI MOVE MOVE MOVI MOVE MOVI CMPI JRZ MOVE MOVE CALLA CALLA MOVE MOVK Color MoDe Run=F5 Step=F8 Next=F10 CPU PC ST A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13 A14 A15 4001 4008 400f 4016 401d 4024 4002 4009 4010 4017 401e 4025 4003 400a 4011 4018 401f 4026 ffc00850 00000010 00000000 00000000 00000000 c0000010 00000000 00000000 00000000 00000040 00000000 ffc45da0 ffffffff 00001795 00000000 ffc363e0 ffc363e0 ffffa000 4006 400d 4014 401b 4022 4029 k DISASSEMBLY ffc00850 0740 ffc00860 09e9 ffc00890 4d2d ffc008a0 4d2e ffc008b0 09e9 ffc008e0 4d2f ffc008f0 09ea ffc00920 0b4a ffc00940 ca05 ffc00950 a3cf ffc00960 934e ffc00970 0d5f ffc009a0 0d5f ffc009d0 a3cf ffc009e0 182b
32,0,0 -3972128,A9 A9,A13 A9,A14 -3908192,A9 A9,SP -1,A10 -1,A10 0ffc009a0h A14,*-SP,1 A10,*A14+,1 var_init main A14,*-SP,1 1,A11 MEMORY 00000000 00000070 000000e0 00000150 000001c0 00000230
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instrume TMS340x0 Development Board
4000 4007 400e 4015 401c 4023
40004 4005 400b 4012 4019 4020 4027 400c 4013 401a 4021 4028
>>>
-
When the debugger is running C code, you'll see a C display similar to the one in Figure 6-2. (This assumes that the debugger can find your C source file to display in the FILE window. If the debugger can't find your source, then it switches to mixed mode.)
iv
Debugging Modes and Default Displays
Figure 6-2. Typical C Display (for Auto Mode Only)
Load FILE: 00044 00045 00046 00047 00048 00049 00050 00051 00052 00053 00054 00055 00056 00057 0058 Brea Watch Memory Color MoDe Run=F5 Step=F8 Next=F10 k sample.c short aaas[10][5][2]; char ac[10]; int *pi; char *xpc; struct zzz giant[100]; extern call(); exter meminit(); main() { register int i = 0; int j = 0; k = 0; meminit(); CALLS 1: main()
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instruments Incorporated TMS340x0 Development Board go main
>>>
When you're running assembly language code, the debugger automatically displays windows as described for assembly mode. When you're running C code, the debugger automatically displays the COMMAND, CALLS, and FILE windows. If you like, you can also open a WATCH, DISP, I/O, or FPU window.
Assembly mode
Assembly mode is for viewing assembly language programs only. In this mode, you'll see a display similar to the one shown in Figure 6-1. When you're in assembly mode, you'll always see the assembly display, regardless of whether C or assembly language is currently running. Windows that are automatically displayed in assembly mode include the MEMORY window, the DISASSEMBLY of memory contents, the CPU register window, and the COMMAND window. If you like, you can also open a WATCH, DISP, I/O, or FPU window.
Chapter Title--Attribute Reference
v
Debugging Modes and Default Displays
Mixed mode
Mixed mode is for viewing assembly language and C code at the same time. Figure 6-3 shows the default display for mixed mode.
Figure 6-3. Typical Mixed Display (for Mixed Mode Only)
Load Brea Watch main: Memory MMTM MOVE ADDI MOVE SUB MOVE MOVE CALLA MOVE Color MoDe Run=F5 Step=F8 Next=F10 CPU PC ST A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 fffc0000 00000010 00000000 00000000 00000000 c0000010 00000000 00000000 00000000 00000040 00000000 ffc45da0 ffffffff k DISASSEMBLY fffc0000 098f ffc00020 4dcd ffc00030 0b0e ffc00050 93ee ffc00060 4529 ffc00070 832d ffc00080 b32d ffc000a0 0d5f ffc000d0 a3cf
SP,A7,A9,A11,FP STK,FP 64,STK SP,*STK+,1 A9,A9 A9,@j,1 A9,@k,1 meminit STK,*-SP,1
FILE: sample.c 00047 char *xpc; 0048 struct zzz giant[100]; 00049 00050 extern call(); 00051 exter meminit(); 00052 00053 main() COMMAND file sample.c go main mix >>> MEMORY 00000000 00000070 000000e0 00000150 000001c0 4000 4007 400e 4015 401c 4001 4008 400f 4016 401d 4002 4009 4010 4017 401e 4003 400a 4011 4018 401f
CALLS 1: main()
40004 4005 400b 4012 4019 4020 400c 4013 401a 4021
4006 400d 4014 401b 4022
In mixed mode, the debugger displays all windows that can be displayed in auto and assembly modes --regardless of whether you're currently running assembly language or C code. This is useful for finding bugs in C programs that exploit specific architectural features of the '340.
Restrictions associated with debugging modes
The assembly language code that the debugger shows you is the disassembly (reverse assembly) of memory's contents. If you load object code into memory, then the assembly language code is the disassembly of that object code. If you don't load an object file, then the disassembly won't be very useful. Some commands are valid only in certain modes, especially if a command applies to a window that is visible only in certain modes. In this case, entering the command causes the debugger to switch to the mode that is appropriate for the command. This applies to these commands: dasm calls
vi
func file
mem disp
Descriptions of the Different Kinds of Windows and Their Contents
6.2 Descriptions of the Different Kinds of Windows and Their Contents
The debugger can show several types of windows. This section lists the various types of windows and describes their characteristics. Every window is identified by a name in its upper left corner. Each type of window serves a specific purpose and has unique characteristics. There are eight different windows, divided into three general categories:
-
The COMMAND window provides an area for typing in commands and for displaying various types of information such as progress messages, error messages, or command output. Code-display windows are for displaying assembly language or C code. There are three code-display windows:
J J J J J J J J J
The DISASSEMBLY window displays the disassembly (assembly language version) of memory contents. The FILE window displays any text file that you want to display; its main purpose, however, is to display C source code. The CALLS window identifies the current function traceback (when C code is running).
Data-display windows are for observing and modifying various types of data. There are six data-display windows: The MEMORY window displays the contents of a range of memory. The CPU window displays the contents of '340 registers. The I/O window displays the contents of '340 I/O registers. The FPU window displays the contents of '34082 registers. A DISP window displays the contents of an aggregate type such as an array or structure, showing the values of the individual members. You can display up to 120 DISP windows at one time. A WATCH window displays selected data such as variables, specific registers, or memory locations.
You can move or resize any of these windows; you can also edit any value in a data-display window. Before you can perform any of these actions, however, you must select the window you want to move, resize, or edit, and make it the active window. For more information about making a window active, see Section 6.4, The Active Window, on page xx. The remainder of this section describes the individual windows.
Chapter Title--Attribute Reference
vii
Descriptions of the Different Kinds of Windows and Their Contents
COMMAND window
display area
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instruments Incorporated TMS34010 Rev 1 Loading sample.out
command line
>>>
go main
command line cursor
Purpose
Provides an area for entering commands Provides an area for echoing commands and displaying command output, errors, and messages
Editable? Modes Created Affected by
Command line is editable; command output isn't All modes Automatically Any command entered on the command line Any command displaying output in the display area Any input that creates an error
The COMMAND window has two parts:
-
Command line. This is where you enter commands. When you want to enter a command, just type -- no matter which window is active. The debugger keeps a list of the last 100 commands that you entered. You can select and re-enter commands from the list without retyping them. Display area. This area of the COMMAND window echoes the command that you entered, shows any output from the command, and displays debugger messages.
For more information about the COMMAND window and entering commands, refer to Chapter 7, Entering and Using Commands.
DISASSEMBLY window
viii
Running Title--Attribute Reference
memory address
object code
disassembly (assembly language constructed from object code)
DISASSEMBLY ffc00820 09af ffc00850 ffc00860 ffc00890 ffc008a0 ffc008b0 ffc008eo ffc008f0 ffc00920 0740 09e9 4d2d 4d2e 09e9 4d2f 09ea 0b4a c_int00:
RETS SETF MOVI MOVE MOVE MOVI MOVE MOVI CMPI
0 32,0,0 -3972128,A9 A9,A13 A9,A14 -3908192,A9 A9,SP -1,A10 -1,A10
current PC
Purpose Editable? Modes Created Affected by
Displays the disassembly (or reverse assembly) of memory contents No; pressing the edit key ( F9 ) or the left mouse button sets a breakpoint on an assembly language statement Auto (assembly display only), assembly, and mixed Automatically DASM and ADDR commands Breakpoint and run commands
Within the DISASSEMBLY window, the debugger highlights:
-
The statement that the PC is pointing to (if that line is in the current display) Any breakpointed statements The address and object code fields for all statements associated with the current C statement, as shown below
DISASSEMBLY ffc00000 098f ffc00020 4dcd ffc00030 0b0e ffc00050 93ee
main:
These assembly language statements are associated with this C statement
MMTM MOVE ADDI MOVE
SP,A7,A0,A11,FP STK,FP 64,STK SP,*STK+,1
FILE: t1.c 00049 extern call(); 00059 exter meminit(); 00060 00061 main()
current PC
Chapter Title--Attribute Reference
ix
Descriptions of the Different Kinds of Windows and Their Contents
FILE window
FILE: sample.c 00001 struct xxx 00002 00003 union uuu 00004 struct zzz 00005 00006 struct 00007 enum yyy
text file
{ int a,b,c; int f1 : 2; int f2 : 4; struct xx str, astr[10], aastr[ { int u1, u2, u3, u4, u5[6]; struct xxx u6; } { int b1,b2,be,b4,b5; struct xxx q1[2],q2; str big1, *big2, big3[6]; { int x,y,z,; int **ptr; float *fptr; char ra[5 { RED, GREEN, BLUE } genum, *penum, aenum[5][4]
Purpose Editable?
Shows any text file you want to display No; if the FILE window displays C code, pressing the edit key ( F9 ) or the left mouse button sets a breakpoint on a C statement Auto (C display only) and mixed With the FILE command Automatically when you're in auto or mixed mode and your program begins executing C code FILE, FUNC, and ADDR commands Breakpoint and run commands
Modes Created
Affected by
You can use the FILE command to display the contents of any file within the FILE window, but this window is especially useful for viewing C source files. Whenever you single-step a program or run a program and halt execution, the FILE window automatically displays the C source associated with the current point in your program. This overwrites any other file that may have been displayed in the window. Within the FILE window, the debugger highlights:
-
The statement that the PC is pointing to (if that line is in the current display) Any statements where you've set a breakpoint
x
Descriptions of the Different Kinds of Windows and Their Contents
CALLS window
order of functions called
CALLS 3: subx() 2: call() 1: main()
current function is at top of list
names of functions called
Purpose Editable?
Lists the function you're in, its caller, and its caller, etc., as long as each function is a C function No; pressing the edit key ( F9 ) or the left mouse button changes the FILE display to show the source associated with the called function Auto (C display only) and mixed Automatically when you're displaying C code With the CALLS command if you closed the window Run and single-step commands
Modes Created Affected by
The display in the CALLS window changes automatically to reflect the latest function call.
If you haven't run any code, then no functions have been called yet. You'll also see this if you're running code but are not currently running a C function.
CALLS 1: **UNKNOWN
CALLS 1: main()
In C programs, the first C function is main.
CALLS 2: xcall() 1: main()
As your program runs, the contents of the CALLS window change to reflect the current routine that you're in and where the routine was called from. When you exit a routine, its name is popped from the CALLS list.
CALLS 1: main()
Chapter Title--Attribute Reference
xi
Descriptions of the Different Kinds of Windows and Their Contents
If a function name is listed in the CALLS window, you can easily display the function in the FILE window:
1) Point the mouse cursor at the appropriate function name that is listed in the CALLS window. 2) Click the left mouse button. This displays the selected function in the FILE window.
1) Make the CALLS window the active window (see Section 6.4, The Active Window, page xx).

2) Use the arrow keys to move up/down through the list of function names until the appropriate function is indicated. 3) Press
F9
F9
. This displays the selected function in the FILE window.
You can close and reopen the CALLS window.
-
Closing the window is a two-step process: 1) Make the CALLS window the active window.
-
2) Press
F4
To reopen the CALLS window after you've closed it, enter the CALLS command. The format for this command is: calls
xii
Descriptions of the Different Kinds of Windows and Their Contents
MEMORY window
MEMORY 00000000 00000010 4000 4001 4002 4003 4004 4005
addresses
00000020 00000030 00000040 00000050
data
MEMORY 00000000 00000060 000000c0
4000 4006 400c 4012 4018 401e
4001 4007 400d 4013 4019 401f
4002 4008 400e 4014 401a 4020
4003 4009 400f 4015 401b 4021
4004 400a 4010 4016 401c 4022
4005 400b 4011 4017 401d 4023
The display changes when you resize the window
00000120 00000180 000001e0
Purpose Editable? Modes Created Affected by
Displays the contents of memory Yes --you can edit the data (but not the addresses) Auto (assembly display only), assembly, and mixed Automatically The MEM command
-
The MEMORY window has two parts: Addresses. The first column of numbers identifies the addresses of the first column of displayed data. No matter how many columns of data you display, only one address column is displayed. Each address in this column identifies the address of the data immediately to its right. Data. The remaining columns display the values at the listed addresses. You can display more data by making the window wider and/or longer. The first MEMORY window above has one column of data, so each new address is incremented by 1016. Although the second window shows six columns of data, there is still only one column of addresses; the first value is at address 0x0000 0000, the second at address 0x0000 0010, etc.; the seventh value (first value in the second row) is at address 0x0000 0060, the eighth at address 0x0000 0070, etc.
As you run programs, some memory values change as the result of program execution. The debugger highlights changed values. Depending on how you configure memory for your application, some locations may be invalid/unconfigured. The debugger also highlights these locations (by default, it shows these locations in red).
Chapter Title--Attribute Reference
xiii
Descriptions of the Different Kinds of Windows and Their Contents
If you want to view different memory locations, use the MEM command to display a different block of memory. The basic syntax for this command is: mem address When you enter this command, the debugger changes the memory display so that address becomes the first displayed location (it's displayed in row 1, column 1).
CPU window
register name
register contents
CPU PC ST A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A12 A13 A14 A15 B0
ffc00000 20000010 00000000 00000080 00000000 c0000010 00000000 00000000 00000000 00000040 00000000 ffc45da0 ffffffff 00001795 ffc363e0 ffc363e0 ffc45d80 ffffffff CPU PC ffc00000
ST A2 A5 A8
20000010 00000000 00000000 00000000
A0 A3 A6 A9
00000000 00000010 00000000 ffc45da0
The display changes when you resize the window
A1 A4 A7
00000080 00000000 00000040
Purpose Editable? Modes Created Affected by
Shows the contents of the '340 registers Yes --you can edit the value of any displayed register Auto (assembly display only), assembly, and mixed Automatically Data-management commands
As you run programs, some values displayed in the CPU window change as the result of program execution. The debugger highlights changed values.
xiv
Descriptions of the Different Kinds of Windows and Their Contents
I/O window
register name
I/O VESYNC VEBLNK VSBLNK VCOUNT VTOTAL DPYCTL DPYINT DPYADR CONTROL INTENB CONVSP HESERR CONVMP SETVCNT HSTCTLL HSTDATA HSTADR PMASK DPYNX DPYMSK 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 00000000 00000000 00000000 0000 HESYNC HEBLNK HSBLNK HCOUNT HTOTAL DPYSTRT DPYTAP REFADR PSIZE INTPEND CONVDP SCOUNT CONFIG SETHCNT HSTCTLH BSFLTST BSFLTD DINC DPYST 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 00000000 00000000 00000000
register contents
Purpose Editable? Modes Created Affected by
Shows the contents of the '340 I/O registers Yes --you can edit the value of any displayed register Auto (assembly display only), assembly, and mixed With the IOREGS command Data-management commands
As you run programs, some values displayed in this window may change as the result of program execution. The debugger highlights changed values.
Chapter Title--Attribute Reference
xv
Descriptions of the Different Kinds of Windows and Their Contents
FPU window
FPU RA0 0.000000E+000 RA1 0.000000E+000 RA2 0.000000E+000 RA3 0.000000E+000 RA4 0.000000E+000 RA5 0.000000E+000 RA6 0.000000E+000 RA7 0.000000E+000 RA8 0.000000E+000 RA9 0.000000E+000 CSTATIS 00001000
register name
register contents
RB0 0.000000E+000 RB1 0.000000E+000 RB2 0.000000E+000 RB3 0.000000E+000 RB4 0.000000E+000 RB5 0.000000E+000 RB6 0.000000E+000 RB7 0.000000E+000 RB8 0.000000E+000 RB9 0.000000E+000 CCPMFOG ffe00420
Purpose Editable? Modes Created Affected by
Shows the contents of the '34082 registers Yes--you can edit the value of any displayed register Auto (assembly display only), assembly, and mixed With the FPUREGS command Data-management commands
The FPU window shows the '34082 A- and B-file registers in double-precision scientific notation. It also shows the '34082 status and configuration registers as hexadecimal values. As you run programs, some values displayed in this window may change as the result of program execution. The debugger highlights changed values. Note: The FPU window can be displayed only if you've invoked the debugger with the -mc option.
xvi
Descriptions of the Different Kinds of Windows and Their Contents
DISP windows
DISP: str a 84
structure members member values
b c f1 f2 f3 f4
86 172 1 7 0x18740001 [...] DISP: str.f4 [0] 44276127 [1] 1778712578 [2] 555492660 [3] 356713217 [4] 138412802 [5] 182452229 [6] 35659888
This member is an array, and you can display its contents in a second DISP window
[7] 37749506 [8] 134742016 [9] 138412801
Purpose Editable? Modes Created Affected by
Displays the members of a selected structure, array or pointer, and the value of each member Yes --you can edit individual values Auto (C display only) and mixed With the DISP command DISP command
A DISP window is similar to a WATCH window, but it shows the values of an entire array or structure instead of a single value. Use the DISP command to open a DISP window; the basic syntax is: disp expression Data is displayed in its natural format: :
-
Integer values are displayed as decimal numbers. Floating-point values are displayed in floating-point format. Pointers are displayed as hexadecimal addresses (with a 0x prefix). Enumerated types are displayed symbolically.
If any of the displayed members are arrays, structures, or pointers, you can bring up additional DISP windows to display their contents--up to 120 DISP windows can be open at once.
Chapter Title--Attribute Reference
xvii
Descriptions of the Different Kinds of Windows and Their Contents
WATCH window
WATCH 1: A0 2: 3: X+X PC
watch index
-1 4 0x00400064
label
current value
Purpose Editable?
Displays the values of selected expressions Yes --you can edit the value of any expression whose value specifies a storage location (in registers or memory). In the window above, for example, you could edit the value of PC but couldn't edit the value of X+X. Auto, assembly, and mixed With the WA command WA, WD, and WR commands
Modes Created Affected by
The WATCH window helps you to track the values of arbitrary expressions, variables, and registers. Use the WA command for this; the syntax is: wa expression [, label] WA adds expression to the WATCH window. (If there's no WATCH window, then WA also opens a WATCH window). To delete individual entries from the WATCH window, use the WD command. To delete all entries at once and close the WATCH window, use the WR command. Although the CPU window displays register contents, you may not be interested in the values of all these registers. In this situation, it is convenient to use the WATCH window to track the values of the specific registers you're interested in.
xviii
Cursors
6.3 Cursors
The debugger display has three types of cursors:
-
The command-line cursor is a block-shaped cursor that identifies the current character position on the command line. Arrow keys do not affect the position of this cursor.
COMMAND file sample.c go meminit go call go c_int00 restart >>> go main
command line cursor
-
The mouse cursor is a block-shaped cursor that tracks mouse movements over the entire display. This cursor is controlled by the mouse driver installed on your system; if you haven't installed a mouse, you won't see a mouse cursor on the debugger display.
-
The current-field cursor identifies the current field in the active window. This is the hardware cursor that is associated with your EGA or VGA card. Arrow keys do affect this cursor's movement.
CPU B0 00f0007 6 B3 5 B6 0 B9 0 0000000 0000000 0000000
B1 5 B4 7 B7 0 2
0000075 0000000 0000000
B2 3 B5 0 B8 0 0
0000000 0000000 0000000
current field B11 0000000 cursor B10 0000180
Chapter Title--Attribute Reference
xix
The Active Window
6.4 The Active Window
The windows in the debugger display aren't fixed in their position or in their size. You can resize them, move them around, and, in some cases, close them. The window that you're going to move, resize, or close must be active. You can move, resize, or close only one window at a time; thus, only one window at a time can be the active window. Whether or not a window is active doesn't affect the debugger's ability to update information in a window -- it affects only your ability to manipulate a window.
Identifying the active window
The debugger highlights the active window. When windows overlap on your display, the debugger pops the active window to be on top of other windows. You can alter the active window's border style and colors if you wish; Figure 6-4 illustrates the default appearance of an active window and an inactive window.
Figure 6-4. Default Appearance of an Active and an Inactive Window
An active window (default appearance)
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instrume
This window is highlighted to show that it is active
Loading sample.out go main >>>
An inactive window (default appearance)
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instruments Incorporated
This window is not highlighted and is not active
Note:
Loading sample.out go main >>>
On monochrome monitors, the border and selection corner are highlighted as shown in the illustration. On color monitors, the border and selection corner are highlighted as shown in the illustration, but they also change color (by default, they change from white to yellow).
xx
The Active Window
Selecting the active window
You can use one of several methods for selecting the active window:
1) Point to any location within the boundaries or on any border of the desired window. 2) Click the left mouse button. Note that if you point within the window, you might also select the current field. For example:
-
If you point inside the CPU window, then the register you're pointing at becomes active, and the debugger treats any text that you type as a new register value. If you point inside the MEMORY window, then the address value you're pointing at becomes active, and the debugger treats any text that you type as a new memory value.
-
Press
ESC
to get out of this.
If you point inside the DISASSEMBLY or FILE window, you'll set a breakpoint on the statement you're pointing to.
Press the button again to clear the breakpoint.
F6
This key hops through the windows on your display, making each one active in turn and making the previously active window inactive. Pressing this key highlights one of the windows, showing you that the window is active. Pressing F6 again makes a different window active. Press F6 as many times as necessary until the desired window becomes the active window.
Chapter Title--Attribute Reference
xxi
The Active Window
win
The WIN command allows you to select the active window by name. The format of this command is: win WINDOW NAME Note that the WINDOW NAME is in uppercase (matching the name exactly as displayed). You can spell out the entire window name, but you really need specify only enough letters to identify the window. For example, to select the DISASSEMBLY window as the active window, you could enter either of these two commands:
win DISASSEMBLY
or
win
DISA
If several windows of the same type are visible on the screen, don't use the WIN command to select one of them. If you supply an ambiguous name (such as C, which could stand for CPU or CALLS), the debugger selects the first window it finds whose name matches the name you supplied. If the debugger doesn't find the window you asked for (because you closed the window or misspelled the name), then the WIN command has no effect.
xxii
Manipulating Windows
6.5 Manipulating Windows
Windows don't have a fixed size or position -- you can change their sizes and you can move them around. This section tells you how to do this. Note: You can resize or move any window, but first the window must be active. For information about selecting the active window, refer to Section 6.4 (page xx).
Resizing a window
The minimum window size is three lines by four characters. The maximum window size varies, depending on which screen size you're using, but you can't make a window larger than the screen. There are two basic ways to resize a window:
-
You can resize a window by using the mouse. You can resize a window by using the SIZE command.
1) Point to the lower right corner of the window. This corner is highlighted --here's what it looks like:
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instr Loading sample.out go main >>>
lower right corner (highlighted)
2) Grab the highlighted corner by pressing one of the mouse buttons; while pressing the button, move the mouse in any direction. This resizes the window. 3) Release the mouse button when the window reaches the desired size.
Chapter Title--Attribute Reference
xxiii
Manipulating Windows
size
The SIZE command allows you to size the active window. The format of this command is: size [width, length ] You can use the SIZE command in one of two ways: Method 1 Method 2 Supply a specific width and length Omit the width and length parameters and use arrow keys to interactively resize the window.
SIZE, method 1: Use width and length parameters. Valid values for the width and length depend on the screen size and the window position on the screen. Table 6-1 lists the minimum and maximum window sizes.
Table 6-1. Width and Length Limits for Window Sizes
Debugger Valid widths option none -b -bb -bbb -bbbb -bbbbb 4 through 80 4 through 80 4 through 120 4 through 132 4 through 80 4 through 100
Screen size 80 characters by 25 lines 80 characters by 43 lines (EGA) 80 characters by 50 lines (VGA) 120 characters by 43 lines 132 characters by 43 lines 80 characters by 60 lines 100 characters by 60 lines
Note:
Valid lengths 3 through 24 3 through 42 3 through 49 3 through 42 3 through 42 3 through 59 3 through 59
To use a larger screen size, you must invoke the debugger with one of the -b options.
The maximum sizes assume that the window is in the upper left corner (beneath the menu bar). If a window is in the middle of the display, for example, you can't size it to the maximum height and width --you can size it only to the right and bottom screen borders.The easiest way to make a window as large as possible is to zoom it, as described on page xxv. If you want to use commands to make the CALLS window 8 characters wide by 20 lines long, you could enter:
win CALLS size 8, 20
xxiv
Manipulating Windows
SIZE, method 2: Use arrow keys to interactively resize the window. If you enter the SIZE command without width and length parameters, you can use arrow keys to size the window:

Makes the active window one line longer. Makes the active window one line shorter. Makes the active window one character narrower. Makes the active window one character wider. or .
When you're finished using the cursor keys, you must press
For example, if you want to make the CPU window three lines longer and two characters narrower, you can enter:
win CPU size
ESC
Zooming a window
Another way to resize the active window is to zoom it. Zooming a window makes it as large as possible, so that it takes up the entire display (except for the menu bar) and hides all the other windows. Unlike the SIZE command, zooming is not affected by the window's position in the display. To "unzoom" a window, repeat the same steps you used to zoom it. This will return the window to its prezoom size and position. There are two basic ways to zoom a window:
-
You can zoom a window by using the mouse. You can zoom a window by using the ZOOM command.
Chapter Title--Attribute Reference
xxv
Manipulating Windows
1) Point to the upper left corner of the window. This corner is highlighted--here's what it looks like:
COMMAND TMS340 Debugger Version 5.00
upper left corner (highlighted)
Copyright (c) 1990, Texas Instr Loading sample.out go main >>>
2) Click the left mouse button.
zoom You can also use the ZOOM command to zoom/unzoom the window. The format for this command is: zoom
Moving a window
The windows in the debugger display don't have fixed positions --you can move them around. There are two ways to move a window:
-
You can move a window by using the mouse. You can move a window by using the MOVE command.
1) Point to the left or top edge of the window.
Point to the top edge or the left edge
COMMAND TMS340 Debugger Version 5.00 Copyright (c) 1990, Texas Instr Loading sample.out go main >>>
xxvi
Manipulating Windows
2) Grab the window by pressing the left mouse button, but don't release the button; now move the mouse in any direction. 3) Release the mouse button when the window is in the desired position.
move The MOVE command allows you to move the active window. The format of this command is: move [X position, Y position [, width, length ] ] You can use the MOVE command in one of two ways: Method 1 Method 2 Supply a specific X position and Y position Omit the X position and Y position parameters and use arrow keys to interactively resize the window
MOVE, method 1: Use the X position and Y position parameters. You can move a window by defining a new XY position for the window's upper left corner. Valid X and Y positions depend on the screen size and the window size. Table 6-2 lists the minimum and maximum XY positions.
Table 6-2. Minimum and Maximum Limits for Window Positions
Screen size 80 characters by 25 lines 80 characters by 43 lines (EGA) 80 characters by 50 lines (VGA) 120 characters by 43 lines 132 characters by 43 lines 80 characters by 60 lines 100 characters by 60 lines
Note:
Debugger Valid X option positions none -b -bb -bbb -bbbb -bbbbb 0 through 76 0 through 76 0 through 116 0 through 128 0 through 76 0 through 106
Valid Y positions 1 through 22 1 through 40 1 through 47 1 through 40 1 through 40 1 through 57 1 through 57
To use a larger screen size, you must invoke the debugger with one of the -b options.
The maximum values assume that the window is as small as possible; for example, if a window is half as tall as the screen, you won't be able to move its upper left corner to an X position on the bottom half of the screen. If you want to use commands to move the DISASSEMBLY position to a place in the upper left area of the display, you might enter:
win DISASSEMBLY move 5, 6
Chapter Title--Attribute Reference
xxvii
Manipulating Windows
MOVE, method 2: Use arrow keys to interactively move the window. If you enter the MOVE command without X position and Y position parameters, you can use arrow keys to move the window:

Moves the active window down one line. Moves the active window up one line. Moves the active window left one character position. Moves the active window right one character position. or .
When you're finished using the cursor keys, you must press
For example, if you want to move the COMMAND window up two lines and right five characters, you can enter:
win COM move
ESC
Note: If you choose, you can resize a window at the same time you move it. To do this, use the width and length parameters in the same way that they are used for the SIZE command.
xxviii
Manipulating a Window's Contents
6.6 Manipulating a Window's Contents
Although you may be concerned with changing the way windows appear in the display -- where they are and how big/small they are -- you'll usually be interested in something much more important: what's in the windows. Some windows contain more information than can be displayed on a screen; others contain information that you'd like to change. This section tells you how to view the hidden portions of data within a window and which data can be edited. Note: You can scroll and edit only the active window. For information about selecting the active window, refer to Section 6.4 (page xx).
Scrolling through a window's contents
If you resize a window to make it smaller, you may hide information. Sometimes, a window may contain more information than can be displayed on a screen. In these cases, the debugger allows you to scroll information up and down within the window. There are two ways to view hidden portions of a window's contents:
-
You can use the mouse to scroll the contents of the window. You can use function keys and arrow keys.
You can use the mouse to point to the scroll arrows on the righthand side of the active window. This is what the scroll arrows look like:
FILE: sample.c 00038 extern call(); 00039 extern meminit(); 00040 main() 00041 { 00042 register int i = 0; 00043 int j = 0, k = 0; 00044 00045 meminit(); 00046 for (i = 0, i , 0x50000; i++) 00047 { 00048 call(i); 00049 if (i & 1) j += i; 00050 aai[k][k] = j; 00051 if (!(i & 0xFFFF)) k++; 00052 }
scroll up
scroll down
Chapter Title--Attribute Reference
xxix
Manipulating a Window's Contents
To scroll window contents up or down: 1) Point to the appropriate scroll arrow. 2) Press the left mouse button; continue to press it until the information you're interested in is displayed within the window. 3) Release the mouse button when you're finished scrolling. You can scroll up/down one line at a time by pressing the mouse button and releasing it immediately.
In addition to scrolling, the debugger supports the following methods for moving through a window's contents.
PAGE UP
The page-up key scrolls up through the window contents, one window length at a time. You can use CONTROL PAGE UP to scroll up through an array of structures displayed in a DISP window.
PAGE DOWN
The page-down key scrolls down through the window contents, one window length at a time. You can use CONTROL PAGE DOWN to scroll down through an array of structures displayed in a DISP window.
HOME
When the FILE window is active, pressing HOME adjusts the window's contents so that the first line of the text file is at the top of the window. You can't use HOME outside of the FILE window. When the FILE window is active, pressing END adjusts the window's contents so that the last line of the file is at the bottom of the window. You can't use END outside of the FILE window. Moves the field cursor up one line at a time. Moves the field cursor down one line at a time. In the FILE window, scrolls the display left eight characters at a time. In other windows, moves the field cursor left one field; at the first field on a line, wraps back to the last fully displayed field on the previous line. In the FILE window, scrolls the display right eight characters at a time. In other windows, moves the field cursor right one field; at the last field on a line, wraps around to the first field on the next line.
END

Editing the data displayed in windows
You can edit the data displayed in the MEMORY, CPU, DISP, and WATCH windows by using an overwrite "click and type" method or by using commands
xxx
Manipulating a Window's Contents
that change the values. (This is described in detail in Section 11.3, Basic Methods for Changing Data Values, page 11-4.)
Note: In these windows, the "click and type" method of selecting data for editing --pointing at a line and pressing F9 or clicking a mouse button -- does not allow you to modify data. In the FILE and DISASSEMBLY windows, pressing F9 or a mouse button sets or clears a breakpoint on any line of code that you select. You can't modify text in a FILE or DISASSEMBLY window. In the CALLS window, pressing F9 or a mouse button shows the source for the function named on the selected line.
Chapter Title--Attribute Reference
xxxi
Closing a Window
6.7 Closing a Window
The debugger opens various windows on the display according to the debugging mode you select. When you switch modes, the debugger may close some windows and open others. Additionally, you may choose to open DISP and WATCH windows. Most of the windows remain open -- you can't close them. However, you can close the CALLS, DISP, and WATCH windows.
-
To close the CALLS window: 1) Make the CALLS window the active window. 2) Press .
To close a DISP window: 1) Make the appropriate DISP window the active window. 2) Press .
-
If the DISP window that you close has any children, they are closed also. To close the WATCH window, enter:
wr
xxxii
Chapter 7
Entering and Using Commands
The debugger provides you with several methods for entering commands and accomplishing other tasks within the debugger environment. There are several ways to enter commands: from the command line, from pulldown menus, with a mouse, and with function keys. Mouse and function key use differs from situation to situation, and is described throughout this book whenever applicable. Certain specific rules apply to entering commands and using pulldown menus, however, and this chapter includes this information.
Synopsis Page
Some of the alternative methods for entering commands don't apply to all commands--however, entering the command from the command line is a method that works for all commands. The pulldown menus and dialog boxes provide you with another easy method for entering commands. You can use this method even if you don't have a mouse.
7.1 Entering Commands From the Command Line How to type in and enter commands Sometimes, you can't type a command Using the command history Clearing the display area
Topic
iii iv v v vi
7.2
Using the Menu Bar and the Pulldown Menus Using the pulldown menus Escaping from the pulldown menus Entering parameters in a dialog box Using menu bar selections that don't have pulldown menus How the menu selections correspond to commands
vii viii ix ix xi xi
The debugger allows you to execute often-needed command sequences by keeping the commands in a batch file. The debugger also allows you to perform some simple system commands from within the debugger environment.
7.3 7.4 7.5
Entering Commands From a Batch File Defining Your Own Command Strings
xiii xv
Entering Operating-System Commands xvii Entering a single command from the debugger command line xvii Entering several command from a system shell xviii Additional system commands xix
Chapter Title--Attribute Reference
i
Running Title--Attribute Reference
ii
Entering Commands From the Command Line
7.1 Entering Commands From the Command Line
The debugger supports a complete set of commands that help you to control and monitor program execution, customize the display, and perform other tasks. These commands are discussed in the various sections throughout this book, as they apply to the current topic. Chapter 14 summarizes all of the debugger commands with an alphabetic reference. Although there are a variety of methods for entering most of the commands, all of the commands can be entered by typing them on the command line in the COMMAND window. Figure 7-1 shows the COMMAND window.
Figure 7-1. The COMMAND Window
COMMAND
display area
TMS340 Debugger Version 4.95 Copyright (C) 1990, Texas Instruments Incorporated Loading sample.out file sample.c
command line
>>>
go main
The COMMAND window serves two purposes:
-
The command line portion of the window provides you with an area for entering commands. For example, the command line in Figure 7-1 shows that a GO command was typed in (but not yet entered). The display area provides the debugger with an area for echoing commands, displaying command output, or displaying errors and messages for you to read. For example, the command output in Figure 7-1 shows the messages that are displayed when you first bring up the debugger and also shows that a FILE command was entered. If you enter a command by using an alternate method (using the mouse, a pulldown menu, or function keys), the COMMAND window doesn't echo the entered command.
Chapter Title--Attribute Reference
iii
Entering Commands From the Command Line
How to type in and enter commands
You can type a command at almost any time; the debugger automatically places the text on the command line when you type. When you want to enter a command, just type --no matter which window is active. You don't have to worry about making the COMMAND window active or moving the field cursor to the command line. When you start to type, the debugger usually assumes that you're typing a command and puts the text on the command line (except under certain circumstances, which are explained on the next page). Commands themselves are not case sensitive, although some parameters (such as window names) are. To execute a command that you've typed, just press . The debugger then:
1) Echoes the command to the display area, 2) Executes the command and displays any resulting output, and 3) Clears the command line when command execution completes. Once you've typed a command, you can edit the text on the command line with these keystrokes:
To... Move back over text without erasing characters 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 Press... or
Note:
-
You cannot use the arrow keys to move through or edit text on the command line. Typing a command doesn't make the COMMAND window the active window. If you press when the cursor is in the middle of text, the debugger truncates the input text at the point where you press .
iv
Entering Commands From the Command Line
Sometimes, you can't type a command
At most times, you can press any alphanumeric or punctuation key on your keyboard (any printable character); the debugger interprets this as part of a command and displays the character on the command line. In a few instances, however, pressing an alphanumeric key is not interpreted as information for the command line.
-
When you're pressing the ALT key, typing certain letters causes the debugger to display a pulldown menu. When a pulldown menu is displayed, typing a letter causes the debugger to execute a selection from the menu. When you're pressing the CONTROL key, pressing H or L moves the command-line cursor backward or forward through the text on the command line. When you're editing a field, typing enters a new value in the field. When you're using the MOVE or SIZE command interactively, pressing keys affects the size or position of the active window. Before you can enter any more commands, you must press ESC to terminate the interactive moving or sizing. When you've brought up a dialog box, typing enters a parameter value for the current field in the box.
Using the command history
The debugger keeps an internal list, or command history, of the commands that you enter. It remembers the last 100 commands that you entered. If you want to re-enter a command, you can move through this list, select a command that you've already executed, and re-execute it. Use these keystrokes to move through the command history.
To... Repeat the last command that you entered Move forward through the list of executed commands, one by one Move backward through the list of executed commands, one by one Press...
Chapter Title--Attribute Reference
v
Entering Commands From the Command Line
As you move through the command history, the debugger displays the commands, one by one, on the command line. When you see a command that to execute the command. You can also you want to execute, simply press edit these displayed commands in the same manner that you can edit new commands.
Clearing the display area
Occasionally, you may want to completely blank out the display area of the COMMAND window; the debugger provides a command for this:
cls
Use the CLS command to clear all displayed information from the display area. The format for this command is: cls
vi
Using the Menu Bar and the Pulldown Menus
7.2 Using the Menu Bar and the Pulldown Menus
In all three of the debugger displays, you'll see a menu bar at the top of the screen. The menu selections offer you an alternative method for entering many of the debugger commands. Figure 7-2 points out the menu bar in a mixed-mode display. There are several ways to use the selections on the menu bar, depending on whether the selection has a pulldown menu or not.
Figure 7-2. The Menu Bar in the Debugger Display
Load Brea Watch main: Memory MMTM MOVE ADDI MOVE SUB MOVE MOVE CALLA MOVE Color MoDe Run=F5 Step=F8 Next=F10 CPU PC ST A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 fffc0000 00000010 00000000 00000000 00000000 c0000010 00000000 00000000 00000000 00000040 00000000 ffc45da0 ffffffff
menu bar
k DISASSEMBLY fffc0000 098f ffc00020 4dcd ffc00030 0b0e ffc00050 93ee ffc00060 4529 ffc00070 832d ffc00080 b32d ffc000a0 0d5f ffc000d0 a3cf
SP,A7,A9,A11,FP STK,FP 64,STK SP,*STK+,1 A9,A9 A9,@j,1 A9,@k,1 meminit STK,*-SP,1
FILE: sample.c 00047 char *xpc; 0048 struct zzz giant[100]; 00049 00050 extern call(); 00051 exter meminit(); 00052 00053 main() COMMAND file sample.c go main mix >>> MEMORY 00000000 4000 00000070 4007 000000e0 400e 00000150 4015 000001c0 401c 4001 4008 400f 4016 401d 4002 4009 4010 4017 401e 4003 400a 4011 4018 401f
CALLS 1: main()
40004 4005 400b 4012 4019 4020 400c 4013 401a 4021
4006 400d 4014 401b 4022
Several of the selections on the menu bar have pulldown menus; if they could all be pulled down at once, they'd look like Figure 7-3.
Figure 7-3. All of the Pulldown Menus
Load Load Reload Symbols REstart ReseT File Break Add Delete Reset List Watch Add Delete Reset Memory Add Delete Reset List Enable Fill Save Color Load Save Config Border Prompt Mode C (auto) Asm Mixed
Note that the menu bar and associated pulldown menus occupy fixed positions on the display. Unlike windows, you can't move, resize, or cover the menu bar or pulldown menus.
Chapter Title--Attribute Reference
vii
Using the Menu Bar and the Pulldown Menus
Using the pulldown menus
There are several ways to display the pulldown menus and then execute your selections from them. Executing a command from a menu is similar to executing a command by typing it in.
-
If you select a command that has no parameters, then the debugger executes the command as soon as you select it. If you select a command that has one or more parameters, the debugger displays a dialog box when you make your selection. A dialog box offers you the chance to type in the parameter values for the command.
The following paragraphs describe several methods for selecting commands from the pulldown menus.
Mouse method 1 1) Point the mouse cursor at one of the appropriate selections in the menu bar. 2) Press the left mouse button, but don't release the button. 3) While pressing the mouse button, move the mouse downward until your selection is highlighted on the menu. 4) When your selection is highlighted, release the mouse button.
Mouse method 2 1) Point the cursor at one of the appropriate selections in the menu bar. 2) Click the left mouse button. This displays the menu until you are ready to make a selection. 3) Point the mouse cursor at your selection on the pulldown menu. 4) When your selection is highlighted, click the left mouse button.
viii
Using the Menu Bar and the Pulldown Menus
Keyboard method 1
ALT
1) Press the
ALT
key; don't release it.
X
2) Press the key that corresponds to the highlighted letter in the selection name; release both keys. This displays the menu and freezes it. 3) Press and release the key that corresponds to the highlighted letter of your selection in the menu. Keyboard method 2
X
ALT
1) Press the
ALT
key; don't release it.
X
2) Press the key that corresponds to the highlighted letter in the selection name; release both keys. This displays the menu and freezes it.
3) Use the arrow keys to move up and down through the menu. 4) When your selection is highlighted, press .
Escaping from the pulldown menus
-
If you display a menu and then decide that you don't want to make a selection from this menu, you can:
J J -
Press or
ESC
.
Point the mouse outside of the menu; press and then release the left mouse button.
If you pull down a menu and see that it is not the menu you wanted, you can point the mouse at another entry and press the left mouse button, or you can use the and keys to display adjacent menus.
Entering parameters in a dialog box
Many of the debugger commands have parameters. When you execute these commands from menus, you must have some way of providing parameter values. The debugger allows you to do this by displaying a dialog box that asks for these values. Entering parameter values in a dialog box is much like entering commands on the command line:
Chapter Title--Attribute Reference
ix
Using the Menu Bar and the Pulldown Menus
-
If you press in the middle of a string of text, the debugger truncates the string at that point. When you display a dialog box for the first time during a debugging session, the parameter fields are empty. When you bring up the same dialog box again, though, the box displays the last values that you entered. (This is similar to having a command history.) If you want to use the same value, just press .
You can edit what you type (or values that remain from previous entry) in the same way that you can edit text on the command line.
When the dialog box displays more than one parameter, you can use the arrow keys to move from parameter to parameter. You can omit entries for optional parameters, but the debugger won't allow you to skip required parameters. For example, the Add entry on the Watch menu is equivalent to the WA command. This command has three parameters: wa expression [, label] [, display format] When you select Add from the menu, the debugger displays a dialog box that asks you for this parameter information. The dialog box looks like this:
Watch add Expression Label Format
You can enter an expression just as you would if you were typing the WA command, and then press . The cursor moves down to the next parameter:
Watch add Expression Label Format A0+10
In this case, the next two parameters (label and format) are optional. If you want to enter a parameter, you may do so; if you don't want to use these . When you've parameters, don't type anything in their fields --just press entered for the final parameter, the debugger closes the dialog box and executes the command with the parameter values you supplied.
x
Using the Menu Bar and the Pulldown Menus
Using menu bar selections that don't have pulldown menus
These three menu bar selections are single-level entries without pulldown menus:
Run=F5 Step=F8 Next=F10
There are two ways to execute these choices.
1) Point the cursor at one of these selections in the menu bar. 2) Click the left mouse button. This executes your choice in the same manner as typing in the associated command without its optional expression parameter. Pressing this key is equivalent to typing in the RUN command without an expression parameter. Pressing this key is equivalent to typing in the STEP command without an expression parameter. Pressing this key is equivalent to typing in the NEXT command without an expression parameter.
F5
F8
F10
How the menu selections correspond to commands
The following sample screens illustrate the relationship of the debugger commands to the menu bar and pulldown menus. program execution commands
Run=F5 Step=F8 Next=F10
RUN command (without a parameter) STEP command (without a parameter) NEXT command (without a parameter)
breakpoint commands
Break Add Delete Reset List
BA command BD command BR command BL command
Chapter Title--Attribute Reference
xi
Using the Menu Bar and the Pulldown Menus
file/load commands
Load Load Reload Symbols REstart ReseT File
LOAD command RELOAD command SLOAD command RESTART command RESET command FILE command
breakpoint commands
Break Add Delete Reset List
BA command BD command BR command BL command
watch commands
Watch Add Delete Reset
WA command WD command WR command
memory commands
Memory Add Delete Reset List Enable Fill Save
MA command MD command MR command ML command MAP command FILL command MS command
screen-configuration commands
Color Load Save Config Border Prompt
SCONFIG command SSAVE command SCOLOR command BORDER command PROMPT command
mode commands
Mode C (auto) Asm Mixed
C command ASM command MIX command
xii
Entering Commands From a Batch File
7.3 Entering Commands From a Batch File
You can place debugger commands in a batch file and execute the file from within the debugger environment. This is useful, for example, for setting up a memory map that contains several MA commands followed by a MAP command that enables memory mapping.
take
Use the TAKE command to tell the debugger to read and execute commands from a batch file. A batch file can call another batch file; they can be nested in this manner up to 10 deep. To halt the debugger's execution of a batch file, press ESC . The format for the TAKE command is: take batch filename [, suppress echo flag]
-
The batch filename parameter identifies the file that contains commands.
J J J J
If you don't supply an extension, .cmd is used. If you supply path information with the filename, the debugger looks for the file only in the specified directory. If you don't supply path information with the filename, the debugger looks for the file in the current directory. If the debugger can't find the file in the current directory, it looks in any directories that you identified with the D_DIR environment variable. You can set D_DIR within the DOS environment; the command for doing this is SET D_DIR=C:\pathname;C:\pathname This allows you to name several directories that the debugger can search. Remember that if you use D_DIR, you must set it before you invoke the debugger--the debugger doesn't recognize the DOS SET command. If you often use the same directories, it may be convenient to set D_DIR in your autoexec.bat file.
Chapter Title--Attribute Reference
xiii
Entering Commands From a Batch File
-
By default, the debugger echoes the commands in the COMMAND window display area and updates the display as it reads commands from the batch file.
J
J
If you don't use the suppress echo flag parameter, or if you use it but supply a nonzero value, then the debugger behaves in the default manner. If you would like to suppress the echoing and updating, use the value 0 for the suppress echo flag parameter.
xiv
Defining Your Own Command Strings
7.4 Defining Your Own Command Strings
The debugger provides a shorthand method of entering often-used commands or command sequences. This processing is called aliasing. Aliasing enables you to define an alias name for the command(s) and then enter the alias name as if it were a debugger command. To do this, use the ALIAS command. The syntax for this command is: alias [alias name [, "command string"] ] The primary purpose of the ALIAS command is to associate the alias name with the debugger command you've supplied as the command string. However, the ALIAS command is versatile and can be used in several ways:
-
Aliasing several commands. The command string can contain more than one debugger command -- just separate the commands with semicolons. For example, suppose you always began a debugging session by loading the same object file, displaying the same C source file, and running to a certain point in the code. You could define an alias to do all these tasks at once:
alias init,"load test.out;file source.c;go main"
Now you could enter init instead of the three commands listed within the quote marks.
-
Supplying parameters to the command string. The command string can define parameters that you'll supply later. To do this, use a percent sign and a number (%1) to represent the parameter that will be filled in later. The numbers should be consecutive (%1, %2, %3) unless you plan to reuse the same parameter value for multiple commands. For example, suppose that every time you filled an area of memory you also wanted to display that block in the MEMORY window:
alias mfil,"fill %1, %2, %3;mem %1"
Then you could enter:
mfil 0xff8000000,0x18,0x11112222
The first value (0xFF800 0000) would be substituted for the first FILL parameter and the MEM parameter (%1). The second and third values would be substituted for the second and third FILL parameters (%2 and %3).
Chapter Title--Attribute Reference
xv
Defining Your Own Command Strings
-
Listing all aliases. To display a list of all the defined aliases, enter the ALIAS command with no parameters. The debugger will list the aliases and their definitions in the COMMAND window. For example, assume that the init and mfil aliases had been defined as shown in the previous two examples. If you entered:
alias
you'd see:
Alias Command ----------------------------------------- INIT --> load test.out;file source.c;go main MFIL --> fill %1,%2,%3;mem %1
-
Finding the definition of an alias. If you know an alias name but are not sure of its current definition, enter the ALIAS command with just an alias name. The debugger will display the definition in the COMMAND window. For example, if you had defined the init alias as shown in the first example above, you could enter:
alias init
Then you'd see:
"INIT" aliased as "load test.out; file source.c;go main"
Notes:
Nesting alias definitions. You can include a defined alias name in the command string of another alias definition. This is especially useful when the command string would be longer than the debugger command line.
Individual commands within a command string are limited to an expanded length of 132 characters. The expanded length of the command includes the length of any substituted parameter values. To redefine an alias, re-enter the ALIAS command with the same alias name and a new command string. To get rid of an alias, use the UNALIAS command: unalias alias name Alias definitions are lost when you exit the debugger. If you want to reuse aliases, define them in a batch file.
xvi
Entering Operating-System Commands
7.5 Entering Operating-System Commands
The debugger provides a simple method for entering operating-system commands without explicitly exiting the debugger environment. To do this, use the SYSTEM command. The format for this command is: system ["operating-system command" [, flag] ] The SYSTEM command behaves in one of two ways, depending on whether or not you supply an operating-system command as a parameter:
-
If you enter the command with an operating-system parameter, then you stay within the debugger environment. If you enter the command without parameters, the debugger opens a system shell. This means that the debugger will blank the debugger display and temporarily exit to the operating-system prompt.
Use the first method when you have only one command to enter; use the second method when you have several commands to enter.
Entering a single command from the debugger command line
If you need to enter only a single operating-system command, supply it as a parameter to the SYSTEM command. For example, in MS-DOS, if you want to copy a file from another directory into the current directory, you might enter:
system "copy a:\backup\sample.c sample.c"
If the operating-system command produces a display of some sort (such as a message), the debugger will blank the upper portion of the debugger display to show the information. In this situation, you can use the flag parameter to tell the debugger whether or not it should hesitate after displaying the results of the operating-system command. Flag may be a 0 or a 1: 0 The debugger immediately returns to the debugger environment after the last item of information is displayed. The debugger does not return to the debugger environment until you press . (This is the default.)
Chapter Title--Attribute Reference
xvii
1
Entering Operating-System Commands
In the example above, the debugger would open a system shell to display the following message:
1 File(s) copied Type Carriage Return To Return To Debugger
The message would be displayed until you pressed
.
If you wanted the debugger to display the message and then return immediately to the debugger environment, you could enter the command in this way:
system "copy a:\backup\sample.c sample.c",0
Entering several commands from a system shell
If you need to enter several commands, enter the SYSTEM command without parameters. The debugger will open a system shell and display the operating-system prompt. At this point, you can enter any operating-system command. When you are finished entering commands and are ready to return to the debugger environment, enter the appropriate information:
MS-DOS exit
exit
UNIX or
CONTROL
D
Note: On PC systems, available memory may limit the operating-system commands that you can enter from a system shell. For example, you would not be able to invoke another version of the debugger.
xviii
Entering Operating-System Commands
Additional system commands
The debugger also provides separate commands for changing directories and for listing the contents of a directory.
cd
Use the CHDIR (CD) command to change the current working directory. The format for this command is: chdir directory name cd directory name This changes the current directory to the specified directory name. You can use relative pathnames as part of the directory name. Note that this command can affect any command whose parameter is a filename (such as the FILE, LOAD, and TAKE commands).
or
dir
Use the DIR command to list the contents of a directory. The format for this command is: dir [directory name] This command displays a directory listing in the display area of the COMMAND window. If you use the optional directory name parameter, the debugger displays a list of the specified directory's contents. If you don't use this parameter, the debugger lists the contents of the current directory. You can use wildcards as part of the directory name.
Chapter Title--Attribute Reference
xix
Chapter 8
Defining a Memory Map
Before you begin a debugging session, you must supply the debugger with a memory map. The memory map tells the debugger which areas of memory it can and can't access. Note that the commands described in this chapter can also be entered using the Memory pulldown menu.
Synopsis Page
This chapter shows you how to set up a memory map for your system.
8.1 8.2 8.3 8.4 8.5 8.6 The Memory Map: What It Is and Why You Should Define It Sample Memory Maps Identifying Usable Memory Ranges Enabling Memory Mapping Checking the Memory Map Modifying the Memory Map During a Debugging Session Returning to the original memory map Using Multiple Memory Maps for Multiple Systems
Topic
ii iii v vi vi vii viii ix
8.7
Chapter Title--Attribute Reference
i
The Memory Map: What It Is and Why You Should Define It
8.1 The Memory Map: What It Is and Why You Should Define It
A memory map tells the debugger which areas of memory it can and can't access. Memory maps vary, depending on the application; in general, the memory map should identify '340 local memory space plus additional memory space on your board. For the emulator, the memory map may correspond to the memory configuration of your target system. Typically, the map matches the MEMORY definition in your linker command file. When memory mapping is enabled, the debugger checks each of its memory accesses against the provided memory map. If you attempt to access an undefined or protected area, the debugger displays an error message. Note: When the debugger compares memory accesses against the memory map, it performs this checking in software, not hardware. The debugger cannot prevent your program from attempting to access nonexistent memory. The debugger provides a complete set of memory-mapping commands. You can define the memory map interactively by entering these commands while you're using the debugger. This can be inconvenient because, in most cases, you'll set up one memory map before you begin debugging and will use this map for all of your debugging sessions. The easiest method for doing this is to put the memory-mapping commands in a batch file. Whenever you invoke the debugger, it looks for a special initialization batch file. The batch file name differs for the two versions of the debugger. For the emulator, this file is named emuinit.cmd. For the development boards, this file is named dbinit.cmd. If the debugger finds the file, the debugger automatically reads and executes the commands in the file. If you plan to use the same memory map many times, it may be convenient for you to define your memory map in this batch file. However, you aren't required to use the default initialization batch file. You can use the -t debugger option to identify your own batch file. The batch file shipped with the debugger disables memory mapping. This means that the debugger doesn't check to see if it is accessing valid memory; in effect, the entire memory range is treated as valid. Before beginning the debugging process in earnest, you will probably want to supply the debugger with a memory map and enable mapping. If memory mapping is enabled but you have not defined a memory map, the debugger is initially unable to access memory. Invalid memory addresses and their contents are highlighted in the data-display windows. (On color monitors, invalid memory locations, by default, are displayed in red.)
ii
Sample Memory Maps
8.2 Sample Memory Maps
This section contains sample memory maps for development boards and for the emulator. You can use the sample maps if you wish, but that is not necessary; the main purpose of showing them is to provide you with examples to use as a starting point. These samples correspond to two files that are shipped with the debugger, tdbmap.cmd and sdbmap.cmd:
-
Figure 8-1 (a) shows the contents of tdbmap.cmd; Figure 8-1 (a) shows the memory map defined by the commands in tdbmap.cmd. This memory map can be used with a '34010 development board such as the '34010 TIGA development board. Figure 8-2 (a) shows the contents of sdbmap.cmd; Figure 8-2 (a) shows the memory map defined by the commands in sdbmap.cmd. This memory map can be used with the '34020 emulator or with a '34020 development board such as the '34020 software development board.
If you are using a third-party development board, you should refer to the board documentation for additional memory map information. If you don't find any information to help you set up a memory map, then you may want to leave memory mapping disabled.
Figure 8-1. Sample Memory Map for Use With a '34010 Development Board
(a) Memory map commands (tdbmap.cmd) (a) Memory map for '34010 local memory
0x0000 0000 to 0x0000 1FFF 0x0000 2000 to 0x0000 202F 0x0000 2030 to 0x0000 2FFF 0x0000 3000 to 0x0000 303F 0x0000 3040 to 0x0FFF FFFF 0x1000 0000 to 0x107F FFFF 0x1080 0000 to 0xBFFF FFFF 0xC000 0000 to 0xC000 01FF 0xC000 0200 to 0xFF7F FFFF 0xFF80 0000 to 0xFFFF FFFF
map on ma 0x00002000,0x30,RW ma 0x00003000,0x40,WRITEONLY ma 0x10000000,0x00800000,RAM ma 0xc0000000,0x200,RAM ma 0xff800000,0x00800000,RAM
Chapter Title--Attribute Reference
EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE EEEEEEEEE
reserved control registers reserved palette registers reserved display memory reserved I/O registers reserved program/data memory iii
Sample Memory Maps
Figure 8-2.
Sample Memory Map for Use With the '34020 Emulator or a '34020 Development Board
(a) Memory map for '34020 local memory
0x0000 0000 to 0x007F FFFF 0x0080 0000 to 0x00FF FFFF 0x0100 0000 to 0xBFFF FFFF 0xC000 0000 to 0xCFFF FFFF 0xD000 0000 to 0xD000 001F 0xD000 0020 to 0xD000 003F 0xD000 0040 to 0xD000 005F 0xD000 0060 to 0xD000 007F 0xD000 0080 to 0xD000 000F 0xD000 00A0 to 0xD000 00BF 0xD000 00C0 to 0xD000 00DF 0xD000 00E0 to 0xD000 00FF 0xD000 0100 to 0xDFFF FFFF 0xE000 0000 to 0xEFFF FFFF 0xE000 0020 to 0xEFFF FFFF 0xF000 0000 to 0xFFFF FFFF VRAM space DRAM space aliased VRAM/DRAM addresses I/O registers palette address register (RAM write mode) color palette RAM pixel read mask register palette address (write mode) palette address (read only) overlay registers
(a) Memory map commands (sdbmap.cmd)
map on ma 0x00000000,0x00800000,RAM ma 0x00800000,0x00800000,RAM ma 0x01000000,0xbf000000,RAM ma 0xc0000000,0x10000000,RAM ma 0xd0000000,0x20,RAM ma 0xd0000020,0x20,RAM ma 0xd0000040,0x20,RAM ma 0xd0000060,0x20,WRITEONLY ma 0xd0000080,0x20,READONLY ma 0xd00000a0,0x20,RAM ma 0xd00000c0,0x20,PROTECT ma 0xd00000e0,0x20,READONLY ma 0xd0000100,0x0fffff00,RAM ma 0xe00000000,0x20,RAM ma 0xe0000020,0x0fffffe0,RAM ma 0xf0000000,0x10000000,RAM
iv
EEEEEEEE EEEEEEEE EEEEEEEE
reserved palette address (register overlay read) aliased palette register addresses hardware space register aliased hardware space register addresses interrupt and TRAP vectors
Identifying Usable Memory Ranges
8.3 Identifying Usable Memory Ranges
ma The debugger's MA (memory add) command identifies valid ranges of target memory. The syntax for this command is:
-
ma address, length, type The address parameter defines the starting address of a memory range. This parameter can be an absolute address, any C expression, the name of a C function, or an assembly language label. The length parameter defines the length, in bits, of the range. This parameter can be any C expression. The type parameter identifies the read/write characteristics of the memory range. The type must be one of these keywords:
To identify this kind of memory read-only memory write-only memory read/write memory no-access memory Use this keyword as a type parameter R, ROM, or READONLY W, WOM, or WRITEONLY RW or RAM PROTECT
A new memory map must not overlap an existing entry. If you define a range that overlaps an existing range, the debugger ignores the new range and displays this error message in the COMMAND window display area:
Conflicting map range
Note: When memory mapping is enabled, you cannot:
-
Access memory locations that are not defined by an MA command Modify memory areas that are defined as read only or protected
If you attempt to access memory in these situations, the debugger displays this message in the COMMAND window display area:
Error in expression
Chapter Title--Attribute Reference
v
Enabling Memory Mapping / Checking the Memory Map
8.4 Enabling Memory Mapping
map By default, mapping is not enabled when you invoke the debugger. In order to use memory mapping, you must explicitly enable the memory mapping capability. Use the MAP command to do this; the syntax is: map on map off Note that disabling memory mapping can cause bus fault problems in the target because the debugger may attempt to access nonexistent memory.
or
8.5 Checking the Memory Map
ml If you want to see which memory ranges are defined, use the ML command. The syntax for this command is: ml The ML command lists the starting address, ending address, and read/write characteristics of each defined memory range. For example, if you're using the sample TDB memory map and you enter the ML command, the debugger displays this:
Memory range 00002000 - 0000202f 00003000 - 0000303f 10000000 - 107fffff ff800000 - ffffffff
starting address ending address
Attributes READ WRITE WRITE READ WRITE READ WRITE
vi
Modifying the Memory Map During a Debugging Session
8.6 Modifying the Memory Map During a Debugging Session
If you need to modify the memory map during a debugging session, use these commands. md To delete a range of memory from the memory map, use the MD (memory delete) command. The syntax for this command is: md address The address parameter identifies the starting address of the range of memory. If you supply an address that is not the starting address of a range, the debugger displays this error message in the COMMAND window display area:
Specified map not found
mr
If you want to delete all defined memory ranges from the memory map, use the MR (memory reset) command. The syntax for this command is: mr This resets the debugger memory map.
ma
If you want to add a memory range to the memory map, use the MA (memory add) command. The syntax for this command is: ma address, length, type The MA command is described in detail on page v.
Chapter Title--Attribute Reference
vii
Modifying the Memory Map During a Debugging Session
Returning to the original memory map
If you modify the memory map, you may want to go back to the original memory map without quitting and reinvoking the debugger. You can do this by resetting the memory map and then using the TAKE command to read in your original memory map from a batch file. Suppose, for example, that you had set up your memory map in a batch file named mem.map. You could enter these commands to go back to this map:
mr take mem.map
Reset the memory map Reread the default memory map
The MR command resets the memory map. (Note that you could put the MR command in the batch file, preceding the commands that define the memory map.) The TAKE command tells the debugger to execute commands from the specified batch file.
viii
Using Multiple Memory Maps for Multiple Target Systems
8.7 Using Multiple Memory Maps for Multiple Systems
If you're debugging multiple applications, you may need a memory map for each target system. Here's the simplest method for handling this situation. Step 1: Let the dbinit.cmd or emuinit.cmd file define the memory map for one of your applications. Step 2: Create a separate batch file that defines the memory map for the additional system. The filename is unimportant, but for the purposes of this example, assume that the file is named filename.x. The general format of this file's contents should be
mr MA commands map on
Reset the memory map Define the new memory map Enable mapping
(Of course, you can include any other appropriate commands in this batch file.) Step 3: Invoke the debugger as usual. Step 4: The debugger reads init.cmd during invocation. Before you begin debugging, read in the commands from the new batch file:
take filename.x
This redefines the memory map for the current debugging session.
Chapter Title--Attribute Reference
ix
page
x
Chapter 9
Loading, Displaying, and Running Code
The main purpose of a debugging system is to allow you to load and run your programs in a test environment. This chapter tells you how to load your programs into the debugging environment, run them on the target system, and view the associated source code. Note that many of the commands described in this chapter can also be executed from the Load pulldown menu.
Synopsis Page
Depending on the debugging mode you choose, the debugger shows you assembly language only, C code only, or both at the same time. To debug a program, you must load the program's object code into memory. You'll also need to see the associated source code.
9.1 Code-Display Windows: Viewing Assembly Language Code, C Code, or Both Selecting a debugging mode
Topic
ii iii
9.2
Displaying Your Source Programs (or Other Text Files) Displaying assembly language code Displaying C code Displaying other text files Loading Object Code Loading code while invoking the debugger Loading code after invoking the debugger Where the Debugger Looks for Source Files
iv iv vi vii viii viii viii ix
9.3
9.4
Once you've loaded an object file, there are several ways of running the program during a debugging session.
9.5
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
x x xi xii xiv xv xvi xvii
9.6 9.7
Chapter Title--Attribute Reference
i
Code-Display Windows: Viewing Assembly Language Code, C Code, or Both
9.1 Code-Display Windows: Viewing Assembly Language Code, C Code, or Both
The debugger has three code-display windows:
-
The DISASSEMBLY window displays the reverse assembly of program memory contents. The FILE window displays any text file; its main purpose is to display C source files. The CALLS window identifies the current function (when C code is running).
You can view code in several different ways. The debugger has three different code displays that are associated with the three debugging modes. The debugger selects the appropriate display based on two factors:
-
The mode you select and Whether your program is currently executing assembly language code or C code.
Here's a summary of the modes and displays; for a complete description of the three debugging modes, refer to Section 6.1, Debugging Modes and Default Displays (page iii).
The debugger uses these code-display windows DISASSEMBLY
Use this mode assembly mode
To view
assembly language code only (even if your program is executing C code) assembly language code (when that's what your program is running) C code only (when that's what your program is running) both assembly language and C code
auto mode
DISASSEMBLY
auto mode
FILE CALLS DISASSEMBLY FILE CALLS
mixed mode
You can switch freely between the modes. If you choose auto mode, then the debugger displays C code or assembly language code, depending on the type of code that is currently executing.
ii
Code-Display Windows: Viewing Assembly Language Code, C Code, or Both
Selecting a debugging mode
When you first invoke the debugger, it automatically comes up in auto mode. You can then choose assembly or mixed mode. There are several ways to do this.
The Mode pulldown menu provides an easy method for switching modes. There are several ways to use the pulldown menus; here's one method: 1) Point to the menu name.
Mode C (auto) A sm Mixed
2) Press the left mouse button; do not release the button. Move the mouse down the menu until your choice is highlighted. 3) Release the mouse button. For more information about the pulldown menus, refer to Section 7.2, Using the Pulldown Menus, on page vii.
F3
Pressing this key causes the debugger to switch modes in this order:
auto assembly mixed
Enter any of these commands to switch to the desired debugging mode: c asm mix Changes from the current mode to auto mode. Changes from the current mode to assembly mode. Changes from the current mode to mixed mode. If you are already in the desired mode when you enter a mode command, then the command has no effect.
Chapter Title--Attribute Reference
iii
Displaying Your Source Programs (or Other Text Files)
9.2 Displaying Your Source Programs (or Other Text Files)
The debugger displays two types of code:
-
It displays assembly language code in the DISASSEMBLY window in auto, assembly, or mixed mode. It displays C code in the FILE window in auto and mixed modes.
The DISASSEMBLY and FILE windows are primarily intended for displaying code that the PC points to. By default, the FILE window displays the C source for the current function (if any), and the DISASSEMBLY window shows the current disassembly. Sometimes it's useful to display other files or different parts of the same file; for example, you may want to set a breakpoint at an undisplayed line. The DISASSEMBLY and FILE windows are not large enough to show the entire contents of most assembly language and C files. You can scroll through the windows. You can also tell the debugger to display specific portions of the disassembly or C source.
Displaying assembly language code
The assembly language code in the DISASSEMBLY window is the reverse assembly of program-memory contents. (This code doesn't come from any of your text files or from the intermediate assembly files produced by the compiler.)
MEMORY ffc001c0 ffc001d0 ffc00200 ffc00220 ffc00230 ffc00240
403b 0b2b b7a7 24a7 40eb 8bab
addresses
contents of program memory (object code)
DISASSEMBLY ffc001c0 40eb ffc001d0 0bsb ffc00200 b7a7 ffc00220 24a7 ffc00230 40eb ffc00240 8bab
disassembly of object code in memory
ADD ADDI MOVE SLL ADD MOVE
A7,A11 -4151872,A11 @k,A7,1 5,A& A7,A11 @j,*A11,1
iv
Displaying Your Source Programs (or Other Text Files)
When you invoke the debugger, it comes up in auto mode. If you load an object file when you invoke the debugger, then the DISASSEMBLY window displays the reverse assembly of the object file that's loaded into memory. If you don't load an object file, the DISASSEMBLY window shows the reverse assembly of whatever happens to be in memory.
In assembly and mixed modes, you can use these commands to display a different portion of code in the DISASSEMBLY window. dasm Use the DASM command to display code beginning at a specific point. The syntax for this command is: dasm address dasm function name This command modifies the display so that address or function name is displayed within the DISASSEMBLY window. The debugger continues to display this portion of the code until you run a program and halt it. addr Use the ADDR command to display assembly language code beginning at a specific point. The syntax for this command is: addr address addr function name In assembly mode, ADDR works like the DASM command, positioning the code starting at address or at function name as the first line of code in the DISASSEMBLY window. In mixed mode, ADDR affects both the DISASSEMBLY and FILE windows.
or
or
Chapter Title--Attribute Reference
v
Displaying Your Source Programs (or Other Text Files)
Displaying C code
Unlike assembly language code, C code isn't reconstructed from memory contents--the C code that you view is your original C source. You can display C code explicitly or implicitly:
-
You can force the debugger to show C source by entering a FILE, FUNC, or ADDR command. In auto and mixed modes, the debugger automatically opens a FILE window if you're currently running C code.
These commands are valid in C and mixed modes: file Use the FILE command to display the contents of any text file. The syntax for this command is: file filename This command uses the FILE window to display the contents of filename. The debugger continues to display this file until you run a program and halt in a C function. Although this command is most useful for viewing C code, you can use the FILE command for displaying any text file. You can view only one text file at a time.You can also access this command from the Load pulldown menu. (Displaying a file doesn't load that file's object code. If you want to be able to run the program, you must load the file's associated object code as described in Section 9.3 on page viii.) func Use the FUNC command to display a specific C function. The syntax for this command is: func func
or
function name address
FUNC modifies the display so that function name or address is displayed within the window. If you supply an address instead of a function name, the FILE window displays the function containing address and places the cursor at that line. Note that FUNC works similarly to FILE, but you don't need to identify the name of the file that contains the function.
vi
Displaying Your Source Programs (or Other Text Files)
addr
Use the ADDR command to display C code beginning at a specific point. The syntax for this command is: addr address addr function name In a C display, ADDR works like the FUNC command, positioning the code starting at address or at function name as the first line of code in the FILE window. In mixed mode, ADDR affects both the FILE and DISASSEMBLY windows.
or
Whenever the CALLS window is open, you can use the mouse or function keys to display a specific C function. This is similar to the FUNC or ADDR command but applies only to the functions listed in the CALLS window. 1) In the CALLS window, point to the name of C function. 2) Click the left mouse button. (If the CALLS window is active, you can also use the arrow keys and F9 to display the function; see the CALLS window discussion on page xi for details.)
Displaying other text files
The DISASSEMBLY window always displays the reverse assembly of memory contents, no matter what is in memory. The FILE window is primarily for displaying C code, but you can use the FILE command to display any text file within the FILE window. You may, for example, wish to examine system files such as autoexec.bat or init.cmd. You can also view your original assembly language source files in the FILE window. You are restricted to displaying files that are 65,518 bytes long or less.
Chapter Title--Attribute Reference
vii
Loading Object Code
9.3 Loading Object Code
In order to debug a program, you must load the program's object code into memory. You can do this as you're invoking the debugger, or you can do it after you've invoked the debugger. (Note that you create an object file by compiling, assembling, and linking your source files; see Section 5.3, Preparing Your Program for Debugging, on page viii.)
Loading code while invoking the debugger
You can load an object file when you invoke the debugger (this has the same effect as using the debugger's LOAD command). To do this, enter: development board: db340 object filename emulator: db340emu object filename
If you want to load a file's symbol table only, use the -s option (this has the same effect as using the debugger's SLOAD command). To do this, enter: development board: db340 -s object filename emulator: db340emu -s object filename
Loading code after invoking the debugger
After you invoke the debugger, you can use one of three commands to load object code and/or the symbol table associated with an object file. Use these commands as described below, or use them from the Load pulldown menu. load Use the LOAD command to load both an object file and its associated symbol table. In effect, the LOAD command performs both a RELOAD and an SLOAD. The format for this command is: load object filename reload Use the RELOAD command to load only an object file without loading its associated symbol table. This is useful for reloading a program when memory has been corrupted. The format for this command is: reload object filename sload Use the SLOAD command to load only a symbol table. The format for this command is: sload object filename SLOAD is useful in a debugging environment in which the debugger cannot, or need not, load the object code (for example, if the code is in ROM). SLOAD clears the existing symbol table before loading the new one but does not modify memory or set the program entry point.
viii
Where the Debugger Looks for Source Files
9.4 Where the Debugger Looks for Source Files
Some commands (FILE, LOAD, RELOAD, and SLOAD) expect a filename as a parameter. If the filename includes path information, the debugger uses the file from the specified directory and does not search for the file in any other directory. If you don't supply path information, though, the debugger must search for the file. The debugger first looks for these files in the current directory. You may, however, have your files in several different directories.
cd
If you're using LOAD, RELOAD, or SLOAD, you have only two choices for supplying the path information:
J -
Specify the path as part of the filename. Alternatively, you can use the CD command to change the current directory from within the debugger. The format for this command is: cd directory name
If you're using the FILE command, you have several options:
J
Within the DOS environment, you can name additional directories with the D_SRC environment variable. The format for doing this is: SET D_SRC=C:\pathname;C:\pathname This allows you to name several directories that the debugger can search. If you use the same directories often, it may be convenient to set the D_SRC environment variable in your autoexec.bat file. If you do this, then the list of directories is always available when you're using the debugger. When you invoke the debugger, you can use the - i option to name additional source directories for the debugger to search. The format for this is: development board: db340 -i pathname emulator: db340emu -i pathname
J
You can specify multiple pathnames by using several -i options (one pathname per option). The list of source directories that you create with -i options is valid until you quit the debugger. use Within the debugger environment, you can use the USE command to name additional source directories. The format for this command is: use directory name You can specify only one directory at a time. In all cases, you can use relative pathnames such as ..\csource or ..\..\code. The debugger can recognize a cumulative total of 20 paths specified with D_SRC, -i, and USE.
Chapter Title--Attribute Reference
ix
Running Your Programs
9.5 Running Your Programs
To debug your programs, you must execute them on a '340 device. The debugger provides two basic types of commands to help you run your code:
-
Basic run commands run your code without updating the display until you explicitly halt execution. There are several ways to halt execution:
-
J J J
Before you issue a run command, define a specific stopping point (for example, set a breakpoint). Press ESC . Click the left mouse button.
Single-step commands execute assembly language or C code, one statement at time, and update the display after each execution.
Defining the starting point for program execution
All run and single-step commands begin executing from the current PC (program counter). When you load an object file, the PC is automatically set to the starting point for program execution. You can easily identify the current PC by:
or
Finding its entry in the CPU window or Finding the appropriately highlighted line in the FILE or DISASSEMBLY window. You can do this by executing one of these commands: dasm addr PC PC
Sometimes you may want to modify the PC to point to a different position in your program. There are two ways to do this: rest If you executed some code and would like to rerun the program from the original program entry point, use the RESTART (REST) command. The format for this command is: restart rest Note that you can also access this command from the Load pulldown menu.
x
or
Running Your Programs
?/eval
or
You can directly modify the PC's contents with one of these commands: ?PC=new value eval pc = new value
After halting execution, you can continue from the current PC by reissuing any of the run or single-step commands.
Running code
The debugger supports several run commands.
run
The RUN command is the basic command for running an entire program. The format for this command is: run [expression] The command's behavior depends on the type of parameter you supply:
F5
-
If you don't supply an expression, the program executes until it encounters a breakpoint or until you press ESC or the left mouse button. If you supply a logical or relational expression, this becomes a conditional run (see page xv). If you supply any other type of expression, the debugger treats the expression as a count parameter. The debugger executes count instructions, halts, then updates the display.
Pressing this key runs code from the current PC. This is similar to entering a RUN command without an expression parameter.
go
Use the GO command to execute code up to a specific point in your program. The format for this command is: go [address]
If you don't supply an address parameter, then GO acts like a RUN command without an expression parameter. ret The RETURN (RET) command executes the code in the current C function and halts when execution returns to its caller. The format for this command is:
Chapter Title--Attribute Reference
xi
Running Your Programs
or
return ret Breakpoints do not affect this command, but you can halt execution by pressing ESC or the left mouse button.
runb
Use the RUNB (run benchmark) command to execute a specific section of code and count the number of clock cycles consumed by the execution. The format for this command is: runb Using the RUNB command to benchmark code is a multistep process, described later in this chapter (Section 9.7, Benchmarking, on page xvii).
emulator only
Single-stepping through code
Single-step execution is similar to running a program that has a breakpoint set on each line. The debugger executes one statement, updates the display, and halts execution. (You can supply a parameter that tells the debugger to single-step more than one statement; the debugger updates the display after each statement.) You can single-step through assembly language code or C code. The debugger supports several commands for single-stepping through a program. Command execution may vary, depending on whether you're single-stepping through C code or assembly language code. Note that the debugger ignores interrupts when you use the STEP command to single-step through assembly language code. Each of the single-step commands has an optional expression parameter that works like this:
-
step
If you don't supply an expression, the program executes a single statement, then halts. If you supply a logical or relational expression, this becomes a conditional single-step execution (see page xv). If you supply any other type of expression, the debugger treats the expression as a count parameter. The debugger single-steps count C or assembly language statements (depending on the type of code you're in).
Use the STEP command to single-step through assembly language or C code. The format for this command is: step [expression]
xii
Running Your Programs
If you're in C code, the debugger executes one C statement at a time. In assembly or mixed mode, the debugger executes one assembly language statement at a time. If you're single-stepping through C code and encounter a function call, the STEP command shows you the single-step execution of the called function (assuming that the function was compiled with the compiler's -g debug option). When function execution completes, single-step execution returns to the caller. If the function wasn't compiled with the debug option, the debugger executes the function but doesn't show single-step execution of the function. cstep The CSTEP command is similar to STEP, but CSTEP always single-steps in terms of a C statement. If you're in C code, STEP and CSTEP behave identically. In assembly language code, however, CSTEP executes all assembly language statements associated with one C statement before updating the display. The format for this command is: cstep [expression] next The NEXT and CNEXT commands are similar to the STEP and CSTEP cnext commands. The only difference is that NEXT/CNEXT never show single-step execution of called functions--they always step to the next consecutive statement. The formats for these commands are: next [expression] cnext [expression] You can also single-step through programs by using function keys:
F8 F10
Acts as a STEP command. Acts as a NEXT command.
The debugger allows you to execute several single-step commands from the selections on the menu bar. To execute a STEP: 1) Point to Step=F8 in the menu bar. 2) Click the left mouse button. To execute a NEXT: 1) Point to Next=F10 in the menu bar. 2) Click the left mouse button.
Chapter Title--Attribute Reference
xiii
Running Your Programs
Running code while disconnected from the target
runf Use the RUNF command to disconnect the emulator from the target system while code is executing. The format for this command is: runf When you enter RUNF, the debugger clears all breakpoints, disconnects the emulator from the target system, and causes the processor to begin execution at the current PC. You can quit the debugger, or you can continue to enter commands. However, any command that causes the debugger to access the target at this time will produce an error. RUNF is useful in a multiprocessor system. It's also useful in a system in which several target systems share an emulator; RUNF enables you to disconnect the emulator from one system and connect it to another.
emulator only
halt
Use the HALT command to halt the target system after you've entered a RUNF command. The format for this command is: halt When you invoke the debugger, it automatically executes a HALT command. Thus, if you enter a RUNF, quit the debugger, and later reinvoke the debugger, you will effectively reconnect the emulator to the target system and run the debugger in its normal mode of operation. When you invoke the debugger, use the -s option to preserve the current PC and memory contents.
reset
The RESET command behaves differently for the two versions of the debugger:
-
For the development board version of the debugger, RESET reloads the monitor (gspmon) but does not reset the '340 processor. For the emulator version of the debugger, RESET resets the target system. This is a software reset.
The format for this command is: reset
xiv
Running Your Programs
Running code conditionally
The RUN, GO, and single-step commands have an optional expression parameter that can be a relational or logical expression. This type of expression has one of the following operators as the highest precedence operator in the expression: > <= && >= == || < != !
When you use this type of expression with these commands, the command becomes a conditional run. The debugger executes the command repeatedly for as long as the expression evaluates to true. You must use breakpoints with conditional runs; the expression is evaluated each time the debugger encounters a breakpoint. Each time the debugger evaluates the conditional expression, it updates the screen. The debugger applies this algorithm: top: if (expression = = 0) go to end; run or single-step (until breakpoint, ESC , or mouse button halts execution) if (halted by breakpoint, not by ESC or mouse button) go to top end: Generally, you should set the breakpoints on statements that are related in some way to the expression. For example, if you're watching a particular variable in a WATCH window, you may want to set breakpoints on statements that affect that variable and use that variable in the expression.
Chapter Title--Attribute Reference
xv
Halting Program Execution
9.6 Halting Program Execution
Whenever you're running or single-stepping code, program execution halts automatically if the debugger encounters a breakpoint or if it reaches a particular point where you told it to stop (by supplying a count or an address). If you'd like to explicitly halt program execution, there are two ways to accomplish this:
Click the left mouse button.
ESC
Press the escape key.
After halting execution, you can continue program execution from the current PC by reissuing any of the run or single-step commands.
xvi
Benchmarking
9.7 Benchmarking
The debugger allows you to keep track of the number of CPU clock cycles consumed by a particular section of code. The debugger maintains the count in a pseudoregister named CLK. Note: The value in CLK is valid only after using a RUNB command that is terminated by a breakpoint. Benchmarking code is a multiple-step process: emulator only Step 1: Set a breakpoint at the statement that marks the beginning of the section of code you'd like to benchmark. Step 2: Set a breakpoint at the statement that marks the end of the section of code you'd like to benchmark. Step 3: Enter any RUN command to execute code up to the first breakpoint. Step 4: Now enter the RUNB command:
runb
When the processor halts at the second breakpoint, the value of CLK is valid. To display it, use the ? command or enter it into the WATCH window with the WA command. This value is valid until you enter another RUN command.
Chapter Title--Attribute Reference
xvii
page
xviii
Chapter 10
Loading TIGA Applications
If you are working with a TIGA application containing modules you have written yourself, you may want to use the debugger to refine these modules. Conventional debugging strategies are not adequate for this situation. Since TIGA downloads and locates modules at runtime, under usual circumstances, the modules would not be available to the debugger. However, TIGA and the debugger support a special feature which informs the debugger when a module has been downloaded. Thus, allowing you to set a breakpoint at the entry of your module. Therefore, when TIGA downloads your module, the TIGA application halts and you have control of the module for debugging purposes. This feature is called dynamic loading. Once a module has been dynamically loaded, you can use all of the basic debugger features to debug your module.
Topic
This chapter discusses the process of setting and clearing tentative breakpoints in TIGA applications.
10.1 Overview of the Dynamic-Load Process Debugging with Microsoft Windows (version 3.0) 10.2 Setting a Tentative Breakpoint Clearing a tentative breakpoint Using regular breakpoint commands while debugging TIGA modules 10.3 Reloading TIGA Modulesvi Using LOAD, RELOAD, and SLOAD while debugging TIGA modules 10.4 Identifying Symbols Used in TIGA Modules
Page
ii iii iv iv v
vi vii
Chapter Title--Attribute Reference
i
Overview of the Dynamic-Load Process
10.1 Overview of the Dynamic-Load Process
Below are the procedures you should follow to use dynamic loading: Step 1: Be sure you have followed the installation procedures in the Setting Up for TIGA Applications section in the appropriate installation chapter:
-
Be sure that you have installed the TIGA communications driver (tigacd) on the target PC.
emulator: development boards:
tigacd /d1 tigacd /d2
-
Remember, you must install tigacd whenever you power up or reboot the target PC. Be sure you have copied the RLMs to the host PC (so that they're on both PCs). In addition, you may want to copy the C source files to the host PC so that you'll be able to view them during debugging. Be sure you have copied tigagm.out and, if you are using TIGA extended primitives, copy extprims.rlm to the directory on the target PC containing tigacd. Also copy these files to the directory on the host PC containing the debugger executable file.
Development boards only: Be sure you have installed the serial communication drivers--debugcom on the host PC and tigacom on the target PC: debugcom: tigacom:
debugcom [Ccommunication port] [Bbaud rate] tigacom [Ccommunication port] [Bbaud rate]
Remember, you must install these drivers whenever you power up or reboot the host or target PC. Be sure that the serial cable pinouts are correct. Step 2: Start the debugger on the host system. Step 3: Set tentative breakpoints on the TIGA module functions you wish to debug. (Tentative breakpoints are a special type of breakpoint used only for identifying TIGA module functions that will be dynamically loaded. For more information, see page iv.) Step 4: Start the TIGA application on the target system.
ii
Overview of the Dynamic-Load Process
Step 5: As the TIGA application executes, TIGA will load code into the '340 board. When a module is loaded into '340 memory, the module will automatically be loaded into the debugger ("dynamically loaded"). When the breakpoint is reached, the TIGA application will halt. Step 6: Now you can debug the module just as if it were any other type of code. Step 7: When you have finished done debugging the module, run past the end of the module; this will restart the TIGA application.
Debugging with Microsoft Windows (version 3.0)
The dynamic-load capability is also useful for debugging the TIGA graphics manager (tigagm.out) and the Windows driver engine (win30.rlm or tigawin.rlm) while running Microsoft Windows. You can also debug TIGA extensions that are downloaded by a Windows application. However, there are a few restrictions and potential problems:
-
-
The debugger and serial link driver will work only when Windows is run in real (win /r) or standard (win /s) modes. Be sure the Windows driver engine (win30.rlm or tigawin.rlm) is copied into the directory where the debugger executable file is located (on the host PC). Also, if you plan to debug downloaded extensions, the corresponding .rlm files must reside in the same directory as the debugger executable file. You may need to set Windows to use the keyboard rather than a mouse. If windows is set up for use with a mouse, it will poll the available serial ports, looking for a mouse. This may corrupt the serial port settings used by DEBUGCOM.
Chapter Title--Attribute Reference
iii
Setting a Tentative Breakpoint
10.2 Setting a Tentative Breakpoint
Tentative breakpoints are a special type of breakpoint used only for identifying TIGA modules that will be dynamically loaded. In this case, the debugger identifies the breakpoints as unresolved symbols. Unresolved symbols are treated as empty variables within the current symbol table.
tba
The TBA command tells the debugger to look for your custom functions and set tentative breakpoints at their entry points. The basic syntax for this command is: tba
function name
The tentative breakpoint command adds the function name to a list of tentative breakpoints and then evaluates the address. If a valid address is found, a breakpoint is set immediately. Otherwise, when a TIGA module is loaded into the debugger, the debugger processes the tentative breakpoint list by attempting to find the function name in the new symbol table. Breakpoints will be set at the addresses of the new modules.
Clearing a tentative breakpoint
tbd
Once set, you may delete tentative breakpoints from functions that have not yet been loaded by using the TBD command. The basic syntax for this command is:
tbd
breakpoint index
The breakpoint index parameter corresponds to index numbers displayed next to the tentative breakpoints listed with the BL debugger command (refer to page v for more details). Note: If a tentative breakpoint is resolved and active, it cannot be deleted with this command. You must use the BD or BR command as explained on page v.
iv
Setting a Tentative Breakpoint
Using regular breakpoint commands while debugging TIGA modules
The debugger treats the dynamic-load feature and its tentative breakpoints separately from other debugger features. However, you can use regular breakpoint commands while debugging a dynamically loaded TIGA module. Effects of using regular debugger commands with the TBA command are listed below:
-
The BL command lists both regular breakpoints and tentative breakpoints.The tentative breakpoint list consists of any unresolved symbols entered with the TBA command. Breakpoints are identified by index numbers so that you can delete them with the TBD command if you want. The BD command deletes only active breakpoints. Therefore, any breakpoint that is unresolved at execution of the BD command and was originally set through the TBA command will be left on the tentative breakpoint list. The BR command deletes all regular and tentative breakpoints (unresolved as well as resolved). If you are using RUNB (benchmarking) and you load a TIGA module, you will receive inaccurate benchmark results.
-
Chapter Title--Attribute Reference
v
Setting a Tentative Breakpoint
10.3 Reloading TIGA Modules
The debugger maintains a list of the TIGA modules that have been dynamically loaded. The last module loaded is the default module. Any of the modules in this list can be selected again.
mod
The MOD command allows you to select a TIGA module that has been dynamically loaded. The basic syntax for this command is: mod [TIGA module name] The module you select becomes the default module. This insures that the default module is searched first and thereby helps prevent misinterpretation of identical variable names in multiple applications. To obtain a list of all the modules that have been dynamically selected, enter the MOD command with no parameter. This will also tell you which module is the default module and identify any code that has been loaded with the LOAD command.
Using LOAD, RELOAD, SLOAD, and RESTART while debugging TIGA modules
Do not use the LOAD, RELOAD, and RESTART commands. Doing so will interfere with the TIGA application and you will have to restart your application. You can, however, use the SLOAD command to load a module's symbol table.
vi
Identifying Symbols Used in TIGA Modules
10.4 Identifying Symbols Used in TIGA Modules
Multiple TIGA modules may use symbols with the same names. The debugger provides a naming system to help you identify these symbols. The basic syntax for identifying symbols is:
[{module name}] function[.variable]
For example, assume you have a TIGA module named draw containing a function circle. In circle, you have a variable named radius that you want to watch. To do so, enter:
wa {draw} circle.radius
If you choose not to specify a module name, all applications are checked, beginning with the default (current) module. The first function found with the specified name is used. Note that module names are case sensitive. Note: Variables contained in your TIGA application will replace duplicate variable names in your current symbol table.
Chapter Title--Attribute Reference
vii
viii
Chapter 11
Managing Data
The debugger allows you to examine and modify many different types of data related to the target system and to your program. You can display and modify the values of: Individual memory locations or a range of memory '340 registers Variables, including scalar types (ints, chars, etc.) and aggregate types (arrays, structures, etc.) This chapter tells you how to display and change data.
Chapter Title--Attribute Reference
i
Running Title--Attribute Reference
Synopsis Page
The chapter begins by describing basic commands and editing methods that apply to managing all forms of data.
11.1 Where Data Is Displayed 11.2 Basic Commands for Managing Data 11.3 Basic Methods for Changing Data Values Editing data displayed in a window Advanced "editing"--using expressions with side effects
Topic
iii iii vi vi vii
These sections discuss unique details about displaying and changing specific types of data.
11.4 Managing Data in Memory Displaying memory contents Displaying memory contents while you're debugging C Saving memory values to a file Filling a block of memory 11.5 Managing Register Data Displaying register contents Displaying and changing the contents of I/O registers Displaying and changing the contents of '34082 registers Displaying and changing the contents of status bits 11.6 Managing Data in a DISP (Display) Window Displaying data in a DISP window Closing a DISP window 11.7 Managing Data in a WATCH Window Displaying data in the WATCH window Deleting watched values and closing the WATCH window
viii viii x xi xii xiii xiii xiv xvi xv xvii xvii xix xx xx xxi
The debugger allows you to display data in a variety of formats.
11.8 Displaying Data in Alternative Formats Changing the default format for specific data types Changing the default format with ?, MEM, DISP, and WA
xxii xxii xxiv
ii
Where Data Is Displayed / Basic Commands for Managing Data
11.1 Where Data Is Displayed
Four windows are dedicated to displaying the various types of data.
Type of data memory locations Window name and purpose MEMORY window Displays the contents of a range of data memory or program memory CPU window Displays the contents of '340 registers DISP windows Display the contents of aggregate types and show the values of individual members WATCH window Displays selected data
register values pointer data or selected variables of an aggregate type
selected variables (scalar types or individual members of aggregate types) and specific memory locations or registers
This group of windows is referred to as data-display windows.
11.2 Basic Commands for Managing Data
The debugger provides special-purpose commands for displaying and modifying data in dedicated windows. The debugger also supports several general-purpose commands that you can use to display or modify any type of data.
whatis If you want to know the type of a variable, use the WHATIS command. The syntax for this command is: whatis symbol This lists symbol's data type in the COMMAND window display area. The symbol can be any variable (local, global, or static), a function name, structure tag, typedef name, or enumeration constant.
Chapter Title--Attribute Reference
iii
Running Title--Attribute Reference
Command whatis giant whatis xxx
Result displayed in the COMMAND window struct zzz giant[100]; struct xxx { int a; int b; int c; int f1 : 2; int f2 : 4; struct xxx *f3; int f4[10]; }
?
The ? (evaluate expression) command evaluates an expression and shows the result in the COMMAND window display area. The basic syntax for this command is: ? expression The expression can be any C expression, including an expression with side effects. However, you cannot use a string constant or function call in the expression. If the result of expression is scalar, then the debugger displays the result as a decimal value in the COMMAND window. If expression is a structure or array, ? displays the entire contents of the structure or array; you can halt long listings by pressing ESC . Here are some examples that use the ? command.
Command ? giant Result displayed in the COMMAND window giant[0].b1 giant[0].b2 giant[0].b3 giant[0].b4 etc. 4194425 90 436547877 -791051538 1952557575 -1555212096
?j ? j=0x5a
iv
Basic Commands for Managing Data
Note that the DISP command (described in detail on page xvii) behaves like the ? command when its expression parameter does not identify an aggregate type. eval The EVAL (evaluate expression) command behaves like the ? command but does not show the result in the COMMAND window display area. The syntax for this command is: eval expression e expression EVAL is useful for assigning values to registers or memory locations in a batch file (where it's not necessary to display the result).
or
Chapter Title--Attribute Reference
v
Basic Methods for Changing Data Values
11.3 Basic Methods for Changing Data Values
The debugger provides you with a great deal of flexibility in modifying various types of data. You can use the debugger's overwrite editing capability, which allows you to change a value simply by typing over its displayed value. You can also use the data-management commands for more complex editing.
Editing data displayed in a window
Use overwrite editing to modify data in a data-display window; you can edit:
-
Registers displayed in the CPU window Memory contents displayed in the MEMORY window Elements displayed in a DISP window Values displayed in the WATCH window
There are two similar methods for overwriting displayed data:
This method is sometimes referred to as the "click and type" method. 1) Point to the data item that you want to modify. 2) Click the left button. The debugger highlights the selected field. (Note that the window containing this field becomes active when you press the mouse button.)
ESC
3) Type the new information. If you make a mistake or change your mind, press ESC or move the mouse outside the field and press/release the left button; this resets the field to its original value. 4) When you finish typing the new information, press This replaces the original value with the new value. or any arrow key.
1) Select the window that contains the field you'd like to modify; make this the active window. (Use the mouse, the WIN command, or F6 . For more detail, see Section 6.4, The Active Window, on page xx.) 2) Use arrow keys to move the cursor to the field you'd like to edit.

Moves up 1 field at a time. Moves down 1 field at a time. Moves left 1 field at a time. Moves right 1 field at a time.
vi
Basic Methods for Changing Data Values
F9
3) When the field you'd like to edit is highlighted, press highlights the field that the cursor is pointing to.
F9
. The debugger
ESC
4) Type the new information. If you make a mistake or change your mind, press ESC ; this resets the field to its original value. 5) When you finish typing the new information, press This replaces the original value with the new value. or any arrow key.
Advanced "editing"--using expressions with side effects
Using the overwrite editing feature to modify data is straightforward. However, there are other methods that take advantage of the fact that most debugger commands accept C expressions as parameters, and that C expressions can have side effects. When an expression has a side effect, it means that the value of some variable in the expression changes as the result of evaluating the expression. This means that you can coerce many commands into changing values for you. Specifically, it's most helpful to use ? and EVAL to change data as well as display it. For example, if you want see what's in register A3, you can enter:
? A3
You can also use this type of command to modify A3's contents. Here are some examples of how you might do this:
? A3++ eval --A3 ? A3 = 8 eval A3/=2
Side effect: increments the contents of A3 by 1 Side effect: decrements the contents of A3 by 1 Side effect: sets A3 to 8 Side effect: divides contents of A3 by 2
Note that not all expressions have side effects. For example, if you enter ? A3+4, the debugger displays the result of adding 4 to the contents of A3 but does not modify A3's contents. Expressions that have side effects must contain an assignment operator or an operator that implies an assignment. Operators that can cause a side effect are: = %= += &= >>= -= ^= ++ *= |= -- /= <<=
Chapter Title--Attribute Reference
vii
Managing Data in Memory
11.4 Managing Data in Memory
In mixed and assembly modes, the debugger maintains a MEMORY window that displays the contents of memory. For details concerning the MEMORY window, see the MEMORY window discussion (page xiii).
MEMORY ffc45a80 ffc45ae0
ffff ffff 0000 0010 0000 0010
ffff ffff 0000 c000 0000 c000
ffff b460 b460 0000 0010 0000
ffff ffff ffff 0000 2000 0000
ffff 0010 0010 0080 b080 0080
ffff c000 c000 0000 ffff 0000
addresses
ffc45b40 ffc45ba0 ffc45c00 ffc45cc0
data
The debugger has commands that show the value at a specific location or display a different range. The debugger allows you to change the values at individual locations; refer to Section 11.3, Basic Methods for Changing Data Values (page vi), for more information. Note that by default, the memory window shows 16-bit values beginning at even 16-bit boundaries. Because the '340 devices are bit addressable, you can display 16-bit values beginning at any bit boundary.
Displaying memory contents
The main way to observe memory contents is to view the display in the MEMORY window. The amount of memory that you can display is limited by the size of the MEMORY window (which is limited only by the screen size). During a debugging session, you may need to display different areas of memory within the window. The debugger provides two methods for doing this.
mem
If you want to display a different memory range in the MEMORY window, use the MEM command. The basic syntax for this command is: mem expression This makes expression the first entry in the MEMORY window. The end of the range is defined by the size of the window: to show more memory locations, make the window larger (see Resizing a window, page xxiii, for more information).
viii
Managing Data in Memory
The expression can be an absolute address, a symbolic address, or any C expression. Here are several examples:
-
Absolute address. Suppose that you want to display memory beginning from the very first address. You might enter this command:
mem 0x00
Hint: MEMORY window addresses are shown in hexadecimal format. If you want to specify a hex address, be sure to prefix the address number with 0x.
-
Symbolic address. You can use any defined C symbol as an expression parameter. For example, if your program defined a symbol named SYM, you could enter this command:
mem &SYM
Hint: Prefix the symbol with the & operator to use the address of the symbol.
-
C expression. If you use a C expression as a parameter, the debugger evaluates the expression and uses the result as a memory address:
mem SP - A0 + label
You can also change the display of any data-display window--including the MEMORY window--by scrolling through the window's contents. See the Scrolling through a window's contents discussion (page xxix) for more details.
Chapter Title--Attribute Reference
ix
Managing Data in Memory
Displaying memory contents while you're debugging C
If you're debugging C code in auto mode, you won't see a MEMORY window--the debugger doesn't show the MEMORY window in the C-only display. However, there are several ways to display memory in this situation. Hint: If you want to use the contents of an address as a parameter, be sure to prefix the address with the C indirection operator (*). If you have only a temporary interest in the contents of a specific memory location, you can use the ? command to display the value at this address. For example, if you want to know the contents of memory location 20 (hex), you could enter:
? *0x20
-
-
The debugger displays the memory value in the COMMAND window display area. If you want the opportunity to observe a specific memory location over a longer period of time, you can display it in a WATCH window. Use the WA command to do this:
wa *0x20
You can also use the DISP command to display memory contents. The DISP window shows memory in an array format with the specified address as "member" [0]. In this situation, you can also use casting to display memory contents in a different numeric format:
disp *(float *)0x20
x
Managing Data in Memory
Saving memory values to a file
ms
Sometimes it's useful to save a block of memory values to a file. You can use the MS (memory save) command to do this; the files are saved in COFF format. (For more information about COFF, refer to the TMS340 Family Code-Generation Tools User's Guide.) The syntax for the MS command is:
-
ms address, length, filename The address parameter identifies the first address in the block. The length parameter defines the length, in words, of the block. This parameter can be any C expression. The filename is a system file.
For example, to save the values in data memory locations 0x0-0x10 to a file named memsave, you could enter:
ms 0x0,0x10,memsave
To reload memory values that were saved in a file, use the LOAD command. For example, to reload the values that were stored in memsave, enter:
load memsave
Chapter Title--Attribute Reference
xi
Managing Data in Memory
Filling a block of memory
fill
Sometimes it's useful to be able to fill an entire block of memory at once. You can do this by using the FILL command. The syntax for this command is:
-
fill address, length, data The address parameter identifies the first address in the block. The length parameter defines the number of 32-bit words to fill. The data parameter is the value that is placed in each word in the block.
For example, to fill locations 0xFF80 0000 to 0xFF80 0300 with the value 0x1234 ABCD, you would enter:
fill 0xff800000,0x18,0x1234abcd
If you want to check to see that memory has been filled as you have asked, you can enter:
mem 0xff800000
This changes the MEMORY window display to show the block of memory beginning at address 0xFF80 0000. Note that the FILL command can also be executed from the Memory pulldown menu.
xii
Managing Register Data
11.5 Managing Register Data
In mixed and assembly modes, the debugger maintains a CPU window that displays the contents of the PC, the ST, and the A and B registers. For details concerning the CPU window, see the CPU window discussion (page xiv).
CPU PC A1 A4 A7 A10 A13 B0 B3 B6 B9 B12
register name
register contents
ffc00000 00000080 00000000 00000040 ffffffff ffc363e0 ffffffff 00000000 00000000 00000000 00000000
ST A2 A5 A8 A11 A14 B1 B4 B7 B10 B13
20000010 00000000 00000000 00000000 00001795 ffc363e0 00000000 00000000 00000000 00000000 00000000
A0 A3 A6 A9 A12 A15 B2 B5 B8 B11 B14
00000000 c0000010 00000000 ffc45da0 00000000 ffc45d80 00000000 00000000 00000000 00000000 00000000
In addition to the registers listed in the CPU window, you can display and modify the contents of I/O registers, selected status bits. and '34082 registers. You can also access register A15/B15 as SP. Note that the B-file registers cannot be accessed by name unless your program defines them as symbols. The debugger provides commands that allow you to display and modify the contents of registers. You can use the debugger's overwrite editing capability to modify the contents of any register or bit displayed in the CPU, I/O, FPU, or WATCH window. You can use the data-management commands to modify the CPU registers as well as registers that are not displayed in the CPU window. Refer to Section 11.3, Basic Methods for Changing Data Values (page vi), for more information.
Displaying register contents
The main way to observe register contents is to view the display in the CPU window. However, you may not be interested in all of the registers; if you're interested in only a few registers, you might want to make the CPU window small and use the extra screen space for the DISASSEMBLY or FILE display. In this type of situation, there are several ways to observe the contents of the selected registers.
-
If you have only a temporary interest in the contents of a register, you can use the ? command to display the register's contents. For example, if you want to know the contents of the SP, you could enter:
? SP
The debugger displays the SP's current contents in the COMMAND window display area.
Chapter Title--Attribute Reference
xiii
Managing Register Data
-
If you want to observe a register over a longer period of time, you can use the WA command to display the register in a WATCH window. For example, if you want to observe the status register, you could enter:
WA ST,Status Reg
This adds the ST to the WATCH window and labels it as Status Reg. The register's contents are continuously updated, just as if you were observing the register in the CPU window. These methods are also useful when you're debugging C in auto mode, because the debugger doesn't show the CPU window in the C-only display.
Displaying and changing the contents of I/O registers
The simplest way to observe I/O register contents is to open the I/O window. To do this, use the IOREGS command:
ioregs
You can also access individual I/O registers by name (names are not case sensitive). All registers are 16 bits except BSFLTD, DPYNX, DPYST, HSTADR, and PMASK. (Note that PMASK is a 16-bit register for the '34010 and a 32-bit register for the '34020.) You can access the 16 LSBs of a 32-bit register by appending an L suffix to the register name; you can access the 16 MSBs by appending an H suffix to the register name. Note: Some of the registers displayed in the I/O window may be available only for the '34020. Additionally, for the '34010, you can access the REFCNT register as REFADR. You can display or modify the contents of the I/O registers by using the ?, EVAL, and WA commands.
-
The simplest way to display the contents of one of these registers is to use the ? command. For example, to display the contents of the PSIZE register, enter:
? PSIZE
To change the contents of a register, use ? or EVAL. For example, if you want to set the pixel size to 4, enter:
? PSIZE = 4
If you want to observe a register value on a regular basis but don't want to open the I/O window, you can use the WA command to add the register value to the WATCH window. For example,
WA PSIZE,Pixel Size
xiv
Managing Register Data
Displaying and changing the contents of status bits
You can display or modify the following register bits:
Bit name CD (cache disable) HLT (halt) V (overflow) C (carry) FS0 (field size 0) FS1 (field size 1) Access as CD HLT STV STC FS0 FS1 Bit name CF (cache flush) IE (global interrupt enable) Z (zero) N (negative) FE0 (field extension 0) FE1 (field extension 1) Access as CF IE STZ STN FE0 FE1
Note:
-
Bit names are not case sensitive. Some bits can be accessed by name; others must be prefixed with ST. Refer to the Access as column (above). For the '34020, you can also access the RST bit of the HSTCTLH register. (If you're using a development board, don't modify RST.)
When you are debugging assembly language routines, you may find it helpful to add the status bits to the WATCH window. This enables you to observe the processor state while running code.
Chapter Title--Attribute Reference
xv
Managing Register Data
Displaying and changing the contents of '34082 registers
If you invoked the debugger with the -mc option, you can access '34082 registers by opening the FPU window. To do this, use the FPUREGS command:
fpuregs
You can also access these registers by name (for example, RA0, RA1, etc.); they will be represented as double-precision scientific notation. You can display integer and float representations of these registers by replacing the R in the register name with I or F, respectively. For example:
-
To display the integer value of RA0, enter:
? IA0
To watch the float version of RB3, enter:
wa FB3
You can also use the register values in expressions:
eval RA0 + FB5
In this case, the addition is done in double precision; the debugger converts the float value in RB5 to a double.
xvi
Managing Data in a DISP Window
11.6 Managing Data in a DISP (Display) Window
The main purpose of the DISP window is to display members of complex, aggregate data types such as arrays and structures. The debugger shows DISP windows only when you specifically request to see DISP windows with the DISP command (described below). Note that you can have up to 120 DISP windows open at once. For additional details about DISP windows, see the DISP window discussion (page xvii).
DISP: str a 84
structure members member values
b c f1 f2 f3 f4
86 172 1 7 0x18740001 [...] DISP: str.f4 [0] 44276127 [1] 1778712578 [2] 555492660 [3] 356713217 [4] 138412802 [5] 182452229 [6] 35659888
This member is an array, and you can display its contents in a second DISP window
[7] 37749506 [8] 134742016 [9] 138412801
Remember, you can use the data-management commands or the debugger's overwrite editing capability to modify the contents of any value displayed in a DISP window. Refer to Section 11.3, Basic Methods for Changing Data Values (page vi), for more information.
Displaying data in a DISP window
disp To open a DISP window, use the DISP command. The basic syntax for this command is: disp expression If the expression is not an array, structure, or pointer (of the form *pointer name), the DISP command behaves like the ? command. However, if expression is one of these types, the debugger opens a DISP window to display the values of the members. If a DISP window contains a long list of members, you can use PAGE DOWN , PAGE UP , or arrow keys to scroll through the window. If the window contains an array of structures, you can use CONTROL PAGE DOWN and CONTROL PAGE UP to scroll through the array.
Chapter Title--Attribute Reference
xvii
Managing Data in a DISP Window
Once you open a DISP window, you may find that a displayed member is another one of these types. This is how you identify the members that are arrays, structures, or pointers: A member that is an array looks like this A member that is a structure looks like this A member that is a pointer looks like an address [. . .] {. . .} 0x00000000
You can display the additional data (the data pointed to or the members of the array or structure) in additional DISP windows (these are referred to as children). There are three ways to do this.
Use the DISP command again; this time, expression must identify the member that has additional data. For example, if the first expression identifies a structure named str and one of str's members is an array named f4, you can display the contents of the array by entering this command:
disp str.f4
This opens a new DISP window that shows the contents of the array. If str has a member named f3 that is a pointer, you could enter:
disp *str.f3
This opens a window to display what str.f3 points to.
Here's another method of displaying the additional data: 1) Point to the member in the DISP window. 2) Now click the left button.
Here's the third method:
F9
1) Use the arrow keys to move the cursor up and down in the list of members. 2) When the cursor is on the desired field, press
F9
.
When the debugger opens a second DISP window, the new window may at first be displayed on top of the original DISP window--if so, you can move the windows so that you can see both at once. If the new windows also have members that are pointers or aggregate types, you can continue to open new DISP windows.
xviii
Managing Data in a DISP Window
Closing a DISP window
Closing a DISP window is a simple, two-step process. Step 1: Make the DISP window that you want to close active (see Section 6.4, The Active Window, on page xx). Step 2: Press
F4
.
Note that you can close a window and all of its children by closing the original window. Note: The debugger automatically closes any DISP windows when you execute a LOAD or SLOAD command.
Chapter Title--Attribute Reference
xix
Managing Data in a WATCH Window
11.7 Managing Data in a WATCH Window
The debugger doesn't maintain a dedicated window that tells you about the status of all the symbols defined in your program. Such a window might be so large that it wouldn't be useful. Instead, the debugger allows you to create a WATCH window that shows you how program execution affects specific expressions, variables, registers, or memory locations.
watch index
WATCH 1: A0 2: 3: X+X PC
6 4 0x00400064
label
current value
The debugger displays a WATCH window only when you specifically request a WATCH window with the WA command (described below). Note that there is only one WATCH window. For additional details concerning the WATCH window, see the WATCH window discussion (page xviii). Remember, you can use the data-management commands or the debugger's overwrite editing capability to modify the contents of any value displayed in the WATCH window. Refer to Section 11.3, Basic Methods for Changing Data Values (page vi), for more information. Note: All of the watch commands described here can also be accessed from the Watch pulldown menu. For more information about using the the pulldown menus, refer to Section 7.2, Using the Menu Bar and the Pulldown Menus (page vii).
Watch Add Delete Reset
Displaying data in the WATCH window
The debugger has one command for adding items to the WATCH window.
wa
To open the WATCH window, use the WA (watch add) command. The basic syntax is: wa expression [, label]
xx
Managing Data in a WATCH Window
When you first execute WA, the debugger opens the WATCH window. After that, executing WA adds additional values to the WATCH window. The expression parameter can be any C expression, including an expression that has side effects. It's most useful to watch an expression whose value will change over time; constant expressions provide no useful function in the watch window. The label parameter is optional. When used, it provides a label for the watched entry. If you don't use a label, the debugger displays the expression in the label field.
Deleting watched values and closing the WATCH window
The debugger supports two commands for deleting items from the WATCH window.
wr
If you'd like to close the WATCH window and delete all of the items in a single step, use the WR (watch reset) command. The syntax is: wr
wd
If you'd like to delete a specific item from the WATCH window, use the WD (watch delete) command. The syntax is: wd index number Whenever you add an item to the WATCH window, the debugger assigns it an index number. (The illustration of the WATCH window on page xx points to these watch indexes.) The WD command's index number parameter must correspond to one of the watch indexes in the WATCH window. Note that deleting an item (depending on where it is in the list) causes the remaining index numbers to be reassigned. Deleting the last remaining item in the WATCH window closes the WATCH window.
Note: The debugger automatically closes the WATCH window when you execute a LOAD or SLOAD command.
Chapter Title--Attribute Reference
xxi
Displaying Data in Alternative Formats
11.8 Displaying Data in Alternative Formats
By default, all data is displayed in its natural format. This means that:
-
Integer values are displayed as decimal numbers. Floating-point values are displayed in floating-point format. Pointers are displayed as hexadecimal addresses (with a 0x prefix). Enumerated types are displayed symbolically.
However, any data displayed in the COMMAND, MEMORY, WATCH, or DISP window can be displayed in a variety of formats.
Changing the default format for specific data types
To display specific types of data in a different format, use the SETF command. The syntax for this command is: setf [data type, display format ] The display format parameter identifies the new display format for any data of type data type. Table 2-1 lists the available formats and the corresponding characters that can be used as the display format parameter. Table 2-2 lists the C data types that can be used for the data type parameter. Only a subset of the display formats applies to each data type, so Table 2-2 also shows valid combinations of data types and display formats.
Table 2-1. Display Formats for Debugger Data
Display Format Default for the data type ASCII character (bytes) Decimal Exponential floating point Decimal floating point Parameter * c d e f Display Format Hexadecimal Octal Valid address ASCII string Unsigned decimal Parameter x o p s u
Table 2-2. Data Types for Displaying Debugger Data
Valid Display Formats Data Type char uchar short int uint c

d

o

x

e
f
p
s
u

Default Display Format ASCII (c) Decimal (d) Decimal (d) Decimal (d) Decimal (d)
xxii
Displaying Data in Alternative Formats
Table 2-2. Data Types for Displaying Debugger Data (Continued)
Valid Display Formats Data Type long ulong float double ptr c

d

o

x

e
f
p
s
u

Default Display Format Decimal (d) Decimal (d) Exponential floating point (e) Exponential floating point (e)

Address (p)
Here are some examples:
-
To display all data of type short as an unsigned decimal, enter:
setf short, u
To return all data of type short to its default display format, enter:
setf short, *
To list the current display formats for each data type, enter the SETF command with no parameters:
setf
You'll see a display that looks something like this:
Display Format Defaults char: ASCII unsigned char: Decimal int: Decimal unsigned int: Decimal short: Decimal unsigned short: Decimal long: Decimal unsigned long: Decimal float: Exponential floating point double: Exponential floating point pointer: Address
Type Type Type Type Type Type Type Type Type Type Type
-
To reset all data types back to their default display formats, enter :
setf *
Chapter Title--Attribute Reference
xxiii
Displaying Data in Alternative Formats
Changing the default format with ?, MEM, DISP, and WA
You can also use the ?, MEM, DISP, and WA commands to show data in alternative display formats. (The ? and DISP commands can use alternative formats only for scalar types, arrays of scalar types, and individual members of aggregate types.) Each of these commands has an optional display format parameter that works in the same way as the display format parameter of the SETF command. When you don't use a display format parameter, data is shown in its natural format (unless you have changed the format for the data type with SETF). Here are some examples:
-
To watch the PC in decimal, enter:
wa pc,,d
-
To display memory contents in octal, enter:
mem 0x0,o
To display an array of integers as characters, enter:
disp ai,c
The valid combinations of data types and display formats listed for SETF also apply to the data displayed with DISP, ?, WA, and MEM. For example, if you want to use display format e or f, the data that you are displaying must be of type float or type double. Additionally, you cannot use the s display format parameter with the MEM command.
xxiv
Chapter 12
Using Breakpoints
During the debugging process, you may want to halt execution temporarily so that you can examine the contents of selected variables, registers, and memory locations before continuing with program execution. You can do this by setting breakpoints at critical points in your code. You can set breakpoints in assembly language code and in C code. A breakpoint halts any program execution, whether you're running or single-stepping through code. Breakpoints are especially useful in combination with conditional execution (described on page xv) and benchmarking (emulator only; described on page xvii). Note that the commands described in this chapter can also be executed from the Break pulldown menu.
Synopsis Page
This chapter describes the simple processes of setting and clearing software breakpoints and of obtaining a listing of all the breakpoints that are set.
12.1 Setting a Breakpoint 12.2 Clearing a Breakpoint 12.3 Finding the Breakpoints That Are Set
Topic
ii iv v
Chapter Title--Attribute Reference
i
Setting a Breakpoint
12.1 Setting a Breakpoint
When you set a breakpoint, the debugger highlights the breakpointed line in two ways:
-
It prefixes the statement with the characters BP>. It shows the line in a bolder or brighter font. (You can use screen-customization commands to change this highlighting method.)
If you set a breakpoint in the disassembly, the debugger also highlights the associated C statement. If you set a breakpoint in the C source, the debugger also highlights the associated statement in the disassembly. (If more than one assembly language statement is associated with a C statement, the debugger highlights the first of the associated assembly language statements.)
FILE: sample.c A breakpoint is set at this C statement; notice how the line is highlighted. A breakpoint is also set at the associated assembly language statement (it's highlighted, too). DISASSEMBLY
00057 00058 BP> 00059 i++) 00060 00061
meminit(); for (i=0; i < 0x50000; { call(i);
ffc000a0 0d5f BP> ffc000d0 a3cf ffc000e0 932e ffc000f0 0d5f
CALLA MOVE MOVE CALLA
meminit STK,*-SP,1 A9,*STK+,1 call
Notes:
ii
You cannot set breakpoints in ROM. After execution is halted by a breakpoint, you can continue program execution by reissuing any of the run or single-step commands. Up to 200 breakpoints can be set.
Setting a Breakpoint
There are three ways to set a breakpoint.
1) Point to the line of assembly language code or C code where you'd like to set a breakpoint. 2) Click the left button.
Repeating this action clears the breakpoint.
1) Make the FILE or DISASSEMBLY window the active window.

2) Use the arrow keys to move the cursor to the line of code where you'd like to set a breakpoint. 3) Press the
F9
F9
key.
Repeating this action clears the breakpoint.
ba
If you know the address where you'd like to set a breakpoint, you can use the BA (breakpoint add) command. This command is useful because it doesn't require you to search through code to find the desired line. The syntax for the BA command is: ba address This command sets a breakpoint at address. This parameter can be an absolute address, any C expression, the name of a C function, or the name of an assembly language label. You cannot set multiple breakpoints at the same statement.
Chapter Title--Attribute Reference
iii
Clearing a Breakpoint
12.2 Clearing a Breakpoint
There are several ways to clear a breakpoint. If you clear a breakpoint from an assembly language statement, the breakpoint is cleared from any associated C statement as well; similiarly, if you clear a breakpoint from a C statement, the breakpoint is cleared from the associated statement in the disassembly.
1) Point to a breakpointed assembly language or C statement. 2) Click the left button.
1) Use the arrow keys or the DASM command to move the cursor to a breakpointed assembly language or C statement. 2) Press the
F9
F9
key.
br
If you want to clear all the breakpoints that are set, use the BR (breakpoint reset) command. The syntax for the BR command is: br This command is useful because it doesn't require you to search through code to find the desired line.
bd
If you'd like to clear one specific breakpoint and you know the address of this breakpoint, you can use the BD (breakpoint delete) command. The syntax for the BD command is: bd
address
This command clears the breakpoint at address. This parameter can be an absolute address, any C expression, the name of a C function, or the name of an assembly language label. If no breakpoint is set at address, the debugger ignores the command.
iv
Finding the Breakpoints That Are Set
12.3 Finding the Breakpoints That Are Set
bl Sometimes you may need to know where breakpoints are set. For example, the BD command's address parameter must correspond to the address of a breakpoint that is set. The BL (breakpoint list) command provides an easy way to get a complete listing of all the breakpoints that are currently set in your program. The syntax for this command is: bl The BL command displays a table of breakpoints in the COMMAND window display area. BL lists all the breakpoints that are set, in the order in which you set them. Here's an example of this type of list:
Address ffc000a0 Symbolic Information in main, at line 58, "c:\sdb\sample.c"
The address is the memory address of the breakpoint. The symbolic information identifies the function, line number, and filename of the breakpointed C statement:
-
If the breakpoint was set in assembly language code, you'll see only an address unless the statement defines a symbol. If the breakpoint was set in C code, you'll see the address together with symbolic information.
Chapter Title--Attribute Reference
v
para
vi
Chapter 13
Customizing the Debugger Display
The debugger display is completely configurable; you can create the interface that is best suited for your use. Besides being able to size and position individual windows, you can change the appearance of many of the display features, such as window borders, how the current statement is highlighted, etc. In addition, if you're using a color display, you can change the colors of any area on the screen. Once you've customized the display to your liking, you can save the custom configuration for use in future debugging sessions.
Synopsis Page
The commands described in this section are most useful if you have a color display. If you are using a monochrome display, these commands change the shades of gray on your display.
13.1 Changing the Colors of the Debugger Display area names: common display areas area names: window borders area names: COMMAND window area names: DISASSEMBLY and FILE windows area names: data-display windows area names: menu bar and pulldown menus
Topic
ii iii iv iv v vi vii
These sections are useful with both color and monochrome displays. They tell you how to change the window border styles, save and restore custom display configurations, and customize the command-line prompt.
13.2 Changing the Border Styles of the Windows 13.3 Saving and Using Custom Displays Changing the default display for monochrome monitors Saving a custom display Loading a custom display Invoking the debugger with a custom display Returning to the default display 13.4 Changing the Prompt
viii ix ix x x xi xi xii
Chapter Title--Attribute Reference
i
Changing the Colors of the Debugger Display
13.1 Changing the Colors of the Debugger Display
You can use the debugger with a color or a monochrome display; the commands described in this section are most useful if you have a color display. If you are using a monochrome display, these commands change the shades on your display. For example, if you are using a black-and-white display, these commands change the shades of gray that are used.
color scolor
You can use the COLOR or SCOLOR command to change the colors of areas in the debugger display. The format for these commands is: color area name, attribute1 [, attribute2 [, attribute3 [, attribute4 ] ] ] scolor area name, attribute1 [, attribute2 [, attribute3 [, attribute4 ] ] ] These commands are similar. However, SCOLOR updates the screen immediately, and COLOR doesn't update the screen (the new colors/attributes take effect as soon as the debugger executes another command that updates the screen). Typically, you might use the COLOR command several times and follow that with an SCOLOR command to put all of the changes into effect at once. The area name parameter identifies the areas of the display that are affected. The attributes identify how the areas are affected. Table 4-1 lists the valid values for the attribute parameters.
Table 4-1. Colors and Other Attributes for the COLOR and SCOLOR Commands
(a) Colors
black red blue magenta green yellow cyan white
(b) Other attributes
bright blink
The first two attribute parameters usually specify the foreground and background colors for the area. If you do not supply a background color, the debugger uses black as the background. Table 4-2 lists valid values for the area name parameters. This is a long list; the subsections following the table further identify these areas.
ii
Changing the Colors of the Debugger Display
Table 4-2. Summary of Area Names for the COLOR and SCOLOR Commands
menu_bar menu_hilite win_resize field_label cmd_cursor asm_label error_msg file_brk
Note:
menu_border menu_hicmd field_text field_error cmd_echo asm_clabel file_line file_pc
menu_entry win_border field_hilite cmd_prompt asm_data background file_eof file_pc_brk
menu_cmd win_hiborder field_edit cmd_input asm_cdata blanks file_text
Listing order is left to right, top to bottom.
You don't have to type an entire attribute or area name; you need to type only enough letters to uniquely identify either parameter. If you supply ambiguous attribute names, the debugger interprets the names in this order: black, blue, bright, blink. If you supply ambiguous area names, the debugger interprets them in the order that they're listed in Table 4-2 (left to right, top to bottom). The remainder of this section identifies these areas.
area names: common display areas
background
blanks
CPU PC ffc00000 A1 A4 A7 00000080 00000000 00000040 ST A2 A5 A8 20000010 00000000 00000000 00000000 A0 A3 A6 A9 00000000 00000010 00000000 ffc45da0
Area identification Screen background (behind all windows) Window background (inside windows)
Parameter name background blanks
Chapter Title--Attribute Reference
iii
Changing the Colors of the Debugger Display
area names: window borders
an inactive window
WATCH 1: A14 2: 3: X+X PC
0x00001802 4 0x00400064
win_border win_resize
an active window
COMMAND (C) Copyright 1990, Texas Instr Loading sample.out 70 symbols loaded file sample.c go main >>>
win_hiborder
Area identification Window border for any window that isn't active The reversed "L" in the lower right corner of a resizable window Window border of the active window
Parameter name win_border win_resize win_hiborder
area names: COMMAND window
cmd_echo error_msg
COMMAND Done file sample.c wa eee Name "eee" not found >>> go main
cmd_prompt
cmd_input
cmd_cursor
Area identification Echoed commands in display area Errors shown in display area Command-line prompt Text that you enter on the command line Command-line cursor
Parameter name cmd_echo error_msg cmd_prompt cmd_input cmd_cursor
iv
Changing the Colors of the Debugger Display
area names: DISASSEMBLY and FILE windows
asm_cdata
DISASSEMBLY ffc00000 098f P main: MMTM MOVE ADDI MOVE SUB SP,A7,A9,A11,F STK,FP 64,STK SP,*STK+,1 A9,A9
file_pc
asm_clabel asm_label
ffc00020 ffc00030 ffc00050 ffc00060
4dcd 0b0e 93ee 4529
file_brk
asm_data file_text file_line
FILE: t1.c 00053 extern 00054 extern 00055 main() 00056 { *eof call(); meminit():
file_pc_brk
file_eof
Area identification Object code in DISASSEMBLY window that is associated with current C statement Object code in DISASSEMBLY window Addresses in DISASSEMBLY window Addresses in DISASSEMBLY window that are associated with current C statement Line numbers in FILE window End-of-file marker in FILE window Text in FILE or DISASSEMBLY window Breakpointed text in FILE or DISASSEMBLY window Current PC in FILE or DISASSEMBLY window Breakpoint at current PC in FILE or DISASSEMBLY window
Parameter name asm_cdata asm_data asm_label asm_clabel file_line file_eof file_text file_brk file_pc file_pc_brk
Chapter Title--Attribute Reference
v
Changing the Colors of the Debugger Display
area names: data-display windows
field_label
MEMORY ffc00000 ffc00060 ffc000c0 ffc00120 ffc00180 ffc00130
field_text field_hilite
098f 4529 132d 0040 0154 0000 0154 832d b32d 93ee 4dcd 0020 4dcd b32d 0020 0000 0b0e 0d5f 0b0e 0020 0000 0020 b32d 0000 0040 0d5f 098f 0d5f 0020 0154 93ee 0800 0154 0000 4000 4dcd
field_edit
field_error
Area identification Label of a window field (includes register names in CPU window, addresses in MEMORY window, index numbers and labels in WATCH window, member names in DISP window) Text of a window field (includes data values for all data-display windows) and of most command output messages in command window Text of a highlighted field Text of a field that has an error (such as an invalid memory location) Text of a field being edited (includes data values for all data-display windows)
Parameter name field_label
field_text
field_hilite field_error field_edit
vi
Changing the Colors of the Debugger Display
area names: menu bar and pulldown menus
menu_bar
Load
Break
menu_hicmd menu_cmd
Watch Add Delete Reset
Memory
Color
Mode
menu_hilite
menu_entry menu_border
Area identification Top line of display screen; background to main menu choices Border of any pulldown menu Text of a menu entry Invocation key for a menu or menu entry Text for current (selected) menu entry Invocation key for current (selected) menu entry
Parameter name menu_bar menu_border menu_entry menu_cmd menu_hilite menu_hicmd
Chapter Title--Attribute Reference
vii
Changing the Border Styles of the Windows
13.2 Changing the Border Styles of the Windows
In addition to changing the colors of areas in the display, the debugger allows you to modify the border styles of the windows.
border Use the BORDER command to change window border styles. The format for
this command is: border [active window style] [, inactive window style] [, resize style] This command can change the border styles of the active window, the inactive windows, and any window that is being resized. The debugger supports nine border styles. Each parameter for the BORDER command must be one of the numbers that identifies these styles:
Index 0 1 2 3 4 5 6 7 8 Style Double-lined box Single-lined box Solid 1/2-tone top, double-lined sides and bottom Solid 1/4-tone top, double-lined sides and bottom Solid box, thin border Solid box, heavy sides, thin top and bottom Solid box, heavy borders Solid 1/2-tone box Solid 1/4-tone box
Here are some examples of the BORDER command. If desired, you can skip parameters as shown in the examples.
border 6,7,8 border 1,,2 border ,3
Change style of active, inactive, and resize windows Change style of active and resize windows Change style of inactive window
You can execute the BORDER command as the Border selection on the Color pulldown menu. The debugger displays a dialog box so that you can enter the parameter values; in the dialog box, active window style is called foreground, and inactive window style is called background.
viii
Saving and Using Custom Displays
13.3 Saving and Using Custom Displays
The debugger allows you to save and use as many custom configurations as you like. When you invoke the debugger, it looks for a screen configuration file named init.clr. This file defines how various areas of the display will appear. If the debugger doesn't find init.clr, it uses a default screen configuration. Initially, init.clr defines a screen configuration that exactly matches the default configuration. The debugger supports two commands for saving and restoring custom screen configurations into files. The filenames that you use for restoring configurations must correspond to the filenames that you used for saving configurations. Note that these are binary files, not text files, so you can't edit the files with a text editor.
Changing the default display for monochrome monitors
The default display is most useful with color monitors. The debugger highlights changed values, messages, and other information with color; this may not be particularly helpful if you are using a monochrome monitor. The debugger package includes another screen configuration file named mono.clr that defines a screen configuration that can be used with monochrome monitors. The best way to use this configuration is to rename the file: 1) Rename the original init.clr file--you might want to call it color.clr. 2) Now rename the mono.clr file. Call it init.clr. Now, whenever you invoke the debugger, it will automatically come up with a customized screen configuration for monochrome files. If you aren't happy with the way that this file defines the screen configuration, you can customize it.
Chapter Title--Attribute Reference
ix
Saving and Using Custom Displays
Saving a custom display
ssave
Once you've customized the debugger display to your liking, you can use the SSAVE command to save the current screen configuration to a file. The format for this command is: ssave [filename] This saves the screen colors, window positions, window sizes, and border styles for all debugging modes. The filename parameter names the new screen configuration file. You can include path information (including relative pathnames); if you don't supply path information, the debugger places the file in the current directory. If you don't supply a filename, then the debugger saves the current configuration into a file named init.clr in the current directory. You can execute this command as the Save selection on the Color pulldown menu.
Loading a custom display
sconfig You can use the SCONFIG command to restore the display to a particular
configuration. The format for this command is: sconfig [filename]
This restores the screen colors, window positions, window sizes, and border styles that were saved with the SSAVE command into filename. If you don't supply a filename, the debugger looks for the init.clr file. The debugger searches for the specified file (or for init.clr) in the current directory and then in directories named with the D_DIR environment variable. You can execute this command as the Load selection on the Color pulldown menu.
x
Saving and Using Custom Displays
Invoking the debugger with a custom display
If you set up the screen in a way that you like and always want to invoke the debugger with this screen configuration, you have two choices for accomplishing this:
-
Save the configuration in init.clr. Add a line to the init.cmd file (the batch file that the debugger executes at invocation time); this line should use the SCONFIG command to load the custom configuration.
Returning to the default display
If you saved a custom configuration into init.clr but don't want the debugger to come up in that configuration, then rename the file or delete it. If you are in the debugger, have changed the configuration, and would like to revert to the default, just execute the SCONFIG command without a filename.
Chapter Title--Attribute Reference
xi
Changing the Prompt
13.4 Changing the Prompt
prompt The debugger enables you to change the command-line prompt by using the
PROMPT command. The format of this command is: prompt new prompt The new prompt can be any string of characters, excluding semicolons and commas. (If you type a semicolon or a comma, it terminates the prompt string.) The SSAVE command doesn't save the command-line prompt as part of a custom configuration. The SCONFIG command doesn't change the command-line prompt. If you change the prompt, it stays changed until you change it again, even if you use SCONFIG to load a different screen configuration. If you always want to use a different prompt, you can add a PROMPT statement to the init.cmd file (the batch file that the debugger executes at invocation time). You can also execute this command as the Prompt selection on the Color pulldown menu.
xii
Chapter 14
Summary of Commands and Special Keys
This chapter summarizes the debugger's commands and special key sequences.
Synopsis Page
The chapter begins with a description of the various categories of debugger commands and then lists the various commands that fall under these categories.
14.1 Functional Summary of Debugger Commands Changing modes Managing windows Performing system tasks Displaying and changing data Displaying files and loading programs Managing breakpoints Loading TIGA applications Customizing the screen Memory mapping Running programs
Topic
ii iii iii iii iv iv v v v vi vi
The main portion of this chapter is the alphabetical command reference. Each debugger command is listed with its syntax, applicable modes, its correspondence to a pulldown menu (if any), and a short description. The chapter ends with a summary of special keys and their functions in the debugger environment.
14.2 Alphabetical Summary of Debugger Commands
vii
14.3 Summary of Special Keys Editing text on the command line Using the command history Switching modes Halting or escaping from an action Displaying the pulldown menus Running code Selecting or closing a window Moving or sizing a window Scrolling through a window's contents Editing data or selecting the active field
xxxviii xxxviii xxxviii xxxix xxxix xxxix xl xl xl xli xli
Chapter Title--Attribute Reference
i
Functional Summary of Debugger Commands
14.1 Functional Summary of Debugger Commands
This section summarizes the debugger commands according to these categories:
-
Changing modes. These commands enable you to switch freely between the three debugging modes (auto, mixed, and assembly). You can select these commands from the Mode pulldown menu, also. Managing windows. These commands enable you to select the active window and move or resize the active window. You can perform these functions with the mouse, also. Performing system tasks. These commands enable you to perform several DOS-like functions and provide you with some control over the target system. Displaying and changing data. These commands enable you to display and evaluate a variety of data items. Some of these commands are available on the Watch pulldown menu, also. Displaying files and loading programs. These commands enable you to change the displays in the FILE and DISASSEMBLY windows and to load object files into memory. Several of these commands are available on the Load pulldown menu. Managing breakpoints. These commands provide you with a command-line method for controlling software breakpoints. These commands are available through the Break pulldown menu. You can also set/clear breakpoints interactively. Customizing the screen. These commands allow you to customize the debugger display, then save and later reuse the customized displays. These commands are available from the Color pulldown menu, also. Memory mapping. These commands enable you to define the areas of target memory that the debugger can access or to fill a memory range with an initial value. These commands are available on the Memory pulldown menu, also. Running programs. These commands provide you with a variety of methods for running your programs in the debugger environment. The basic run and single-step commands are available on the menu bar, also.
ii
Functional Summary of Debugger Commands
Changing modes
To do this Put the debugger in assembly mode Put the debugger in auto mode for debugging C code Put the debugger in mixed mode Use this command asm c mix See page ix xi xxi
Managing windows
To do this Make the active window as large as possible Select the active window Reposition the active window Resize the active window Use this command zoom win move size See page xxxvii xxxvi xxii xxx
Performing system tasks
To do this Define your own command string Associate a beeping sound with the display of error messages Enter any operating-system command or exit to a system shell Delete an alias definition Clear all displayed information from the COMMAND window display area Change the current working directory from within the debugger environment List the contents of the current directory or any other directory Name additional directories that can be searched when you load source files Execute commands from a batch file Reset the target system (emulator only) or reload gspmon.out (development boards only) Exit the debugger Use this command alias sound system unalias cls cd/chdir dir use take reset quit See page viii xxxi xxxii xxxiv xii xii xv xxxv xxxiii xxv xxiv
Chapter Title--Attribute Reference
iii
Functional Summary of Debugger Commands
Displaying and changing data
Use this command setf whatis ? eval disp mem fpuregs ioregs wa wd wr
To do this Change the default format for displaying data values Show the type of a data item Evaluate and display the result of a C expression Evaluate a C expression without displaying the results Display the values in an array or structure or display the value that a pointer is pointing to Display a different range of memory in the MEMORY window Open the FPU window Open the I/O window Continuously display the value of a variable, register, or memory location within the WATCH window Delete a data item from the WATCH window Delete all data items from the WATCH window and close the WATCH window
See page xxix xxxvi vii xvi xv xx xvii xviii xxxv xxxvi xxxvii
Displaying files and loading programs
Use this command file addr dasm func calls load reload sload
To do this Display a text file in the FILE window Display C and/or assembly language code at a specific point Display assembly language code at a specific address Display a specific C function Reopen the CALLS window Load an object file Load only the object-code portion of an object file Load only the symbol-table portion of an object file
See page xvi viii xiv xvii xi xix xxiv xxxi
iv
Functional Summary of Debugger Commands
Managing breakpoints
Use this command ba bd bl br
To do this Add a breakpoint Delete a breakpoint Display a list of all the breakpoints that are set Reset (delete) all breakpoints
See page ix ix x xi
Loading TIGA applications
Use this command
To do this
See page xxi xxxiv xxxiv
Load a previously loaded TIGA module or list the mod modules that were dynamically loaded Set a tentative breakpoint Clear a tentative breakpoint tba tbd
Customizing the screen
Use this command scolor color border prompt ssave sconfig
To do this Change the screen colors and update the screen immediately Change the screen colors, but don't update the screen immediately Change the border style of any window Change the command-line prompt Save a custom screen configuration Load and use a previously saved custom screen configuration
See page xxvii xiii x xxiv xxxi xxviii
Chapter Title--Attribute Reference
v
Functional Summary of Debugger Commands
Memory mapping
Use this command fill ms map ma md mr ml
To do this Initialize a block of memory Save a block of memory to a system file Enable or disable memory mapping Add an address range to the memory map Delete an address range from the memory map Reset (delete all ranges) the memory map Display a list of the current memory map settings
See page xvii xxiii xx xix xx xxiii xxi
Running programs
Use this command run go step cstep next cnext runb
To do this Run a program Run a program up to a certain point Single-step through assembly language or C code Single-step through assembly language or C code, one C statement at a time Single-step through assembly language or C code; step over function calls Single-step through assembly language or C code one C statement at a time; step over function calls Run a program with benchmarking--count the number of CPU clock cycles consumed by the executing portion of code (emulator only) Execute code in a function and return to the function's caller Reset the program entry point Disconnect the emulator from the target system and run free (emulator only) Halt the target system after executing a RUNF command (emulator only) Execute commands from a batch file Reset the target system (emulator only) or reload gspmon.out (development boards only)
See page xxvi xviii xxxii xiv xxiii xii xxvi
return restart runf halt take reset
xxv xxv xxvii xviii xxxiii xxv
vi
Alphabetical Summary of Debugger Commands
14.2 Alphabetical Summary of Debugger Commands
Commands are not case sensitive; to emphasize this, command names are shown in both uppercase and lowercase throughout this book.
?
Syntax Menu selection Description
Evaluate Expression
? expression [, display format] none The ? (evaluate expression) command evaluates an expression and shows the result in the COMMAND window display area. The expression can be any C expression, including an expression with side effects; however, you cannot use a string constant or function call in the expression. If the result of expression is not an array or structure, then the debugger displays the results in the COMMAND window. If expression is a structure or array, ? displays the entire contents of the structure or array; you can halt long listings by pressing ESC . When you use the optional display format parameter, data will be displayed in one of the following formats:
Parameter * c d e f Result Default for the data type ASCII character (bytes) Decimal Exponential floating point Decimal floating point Parameter x o p s u Result Hexadecimal Octal Valid address ASCII string Unsigned decimal
Chapter Title--Attribute Reference
vii
Running Title--Attribute Reference
addr
Syntax Menu selection Description
Display Code at Selected Address
addr address addr function name none Use the ADDR command to display C code or the disassembly at a specific point. ADDR's behavior changes, depending on the current debugging mode:
Note:
In assembly mode, ADDR works like the DASM command, positioning the code starting at address or at function name as the first line of code in the DISASSEMBLY window. In a C display, ADDR works like the FUNC command, displaying the code starting at address or at function name in the FILE window. In mixed mode, ADDR affects both the DISASSEMBLY and FILE windows.
The address parameter is treated as a program-memory address.
ADDR affects the FILE window only if the specified address is in a C function.
alias
Syntax Menu selection Description
Define Custom Command String
alias [alias name [, "command string" ] ] none The ALIAS command allows you to associate one or more debugger commands with a single alias name. You can include as many debugger commands in the command string as you like, as long you separate them with semicolons and enclose the entire string of commands in quotation marks. You can also identify debugger-command parameters by a percent sign followed by a number (%1, %2, etc.). The total number of characters for an individual command (expanded to include parameter values) is limited to 132. Previously defined alias names can be included as part of the definition for a new alias. To find the current definition of an alias, enter the ALIAS command with the alias name only. To see a list of all defined aliases, enter the ALIAS command with no parameters.
viii
Alphabetical Summary of Debugger Commands
asm
Syntax Menu selection Description
Enter Assembly-Only Debugging Mode
asm MoDeAsm The ASM command changes from the current debugging mode to assembly mode. If you're already in assembly mode, the ASM command has no effect.
ba
Syntax Menu selection Description
Breakpoint Add
ba address BreakAdd The BA command sets a breakpoint at a specific address. This command is useful because it doesn't require you to search through code to find the desired line. The address can be an absolute address, any C expression, the name of a C function, or the name of an assembly language label.
bd
Syntax Menu selection Description
Breakpoint Delete
bd
address
Break Delete The BD command clears a breakpoint at a specific address. The address can be an absolute address, any C expression, the name of a C function, or the name of an assembly language label.
Chapter Title--Attribute Reference
ix
Alphabetical Summary of Debugger Commands
bl
Syntax Menu selection Description
Breakpoint List
bl BreakList The BL command provides an easy way to get a complete listing of all the breakpoints that are currently set in your program. It displays a table of breakpoints in the COMMAND window display area. BL lists all the breakpoints that are set, in the order in which you set them.
border
Syntax Menu selection Description
Change Style of Window Border
border [active window style] [ [ ,inactive window style] [,resize window style] ColorBorder The BORDER command changes the border style of the active window, the inactive windows, and any window that you're resizing. The debugger supports nine border styles. Each parameter for the BORDER command must be one of the numbers that identifies these styles:
Index 0 1 2 3 4 5 6 7 8 Style 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
Note that you can execute the BORDER command as the Border selection on the Color pulldown menu. The debugger displays a dialog box so that you can enter the parameter values; in the dialog box, active window style is called foreground, and inactive window style is called background.
x
Alphabetical Summary of Debugger Commands
br
Syntax Menu selection Description
Breakpoint Reset
br BreakReset The BR command clears all breakpoints that are set.
c
Syntax Menu selection Description
Enter Auto Debugging Mode
c MoDeC (auto) The C command changes from the current debugging mode to auto mode. If you're already in auto mode, then the C command has no effect.
calls
Syntax Menu selection Description
Open CALLS Window
calls none The CALLS command displays the CALLS window. The debugger displays this window automatically when you are in auto/C or mixed mode. However, you can close the CALLS window; the CALLS command opens the window up again.
Chapter Title--Attribute Reference
xi
Alphabetical Summary of Debugger Commands
cd, chdir
Syntax Menu selection Description
Change Directory
cd [directory name] chdir [directory name] none The CD or CHDIR command changes the current working directory from within the debugger. You can use relative pathnames as part of the directory name. If you you don't use a pathname, the CD command displays the name of the current directory. Note that this command can affect any other command whose parameter is a filename, such as the FILE, LOAD, and TAKE commands. You can also use the CD command to change the current drive. For example:
cd a: cd d:\csource cd c:\emu34020
cls
Syntax Menu selection Description
Clear Screen
cls none The CLS command clears all displayed information from the COMMAND window display area.
cnext
Syntax Menu selection Description
Single-Step C, Next Statement
cnext [expression] Next=F10 (in C code) The CNEXT command is similar to the CSTEP command. It runs a program one C statement at a time, updating the display after executing each statement. If you're using CNEXT to step through assembly language code, the debugger won't update the display until it has executed all assembly language statements associated with a single C statement. Unlike CSTEP, CNEXT steps over function calls rather than stepping into them--you don't see the single-step execution of the function call. The expression parameter specifies the number statements that you want to single-step. You can also use a conditional expression for conditional single-step execution (Running code conditionally, page xv, discusses this in detail).
xii
Alphabetical Summary of Debugger Commands
color
Syntax Menu selection Description
Change Screen Colors
color area name, attribute1 [,attribute2 [,attribute3 [,attribute4 ] ] ] none The COLOR command changes the color of specified areas of the debugger display. COLOR doesn't update the display; the changes take effect when another command, such as SCOLOR, updates the display. The area name parameter identifies the area of the display that is affected. The attributes identify how the area is affected. The first two attribute parameters usually specify the foreground and background colors for the area. If you do not supply a background color, the debugger uses black as the background. Valid values for the attribute parameters include:
black red bright blue magenta green yellow blink cyan white
Valid values for the area name parameters include:
menu_bar menu_hilite win_resize field_label cmd_cursor asm_label error_msg file_brk menu_border menu_hicmd field_text field_error cmd_echo asm_clabel file_line file_pc menu_entry win_border field_hilite cmd_prompt asm_data background file_eof file_pc_brk menu_cmd win_hiborder field_edit cmd_input asm_cdata blanks file_text
You don't have to type an entire attribute or area name; you need to type only enough letters to uniquely identify the attribute. If you supply ambiguous attribute names, the debugger interprets the names in this order: black, blue, bright, blink. If you supply ambiguous area names, the debugger interprets them in the order that they're listed above (left to right, top to bottom).
Chapter Title--Attribute Reference
xiii
Alphabetical Summary of Debugger Commands
cstep
Syntax Menu selection Description
Single-Step C
cstep [expression] Step=F8 (in C code) The CSTEP single-steps through a program, one C statement at a time, updating the display after executing each statement. If you're using CSTEP to step through assembly language code, the debugger won't update the display until it has executed all assembly language statements associated with a single C statement. If you're single-stepping through C code and encounter a function call, the STEP command shows you the single-step execution of the called function (assuming that the function was compiled with the compiler's -g debug option). When function execution completes, single-step execution returns to the caller. If the function wasn't compiled with the debug option, the debugger executes the function but doesn't show single-step execution of the function. The expression parameter specifies the number statements that you want to single-step. You can also use a conditional expression for conditional single-step execution (Running code conditionally, page xv, discusses this in detail).
dasm
Syntax
Display Selected Disassembly
dasm address dasm function name none The DASM command displays code beginning at a specific point within the DISASSEMBLY window. The address parameter is treated as a programmemory address.
Menu selection Description
xiv
Alphabetical Summary of Debugger Commands
dir
Syntax Menu selection Description
Show Directory Contents
dir [directory name] none The DIR command displays a directory listing in the display area of the COMMAND window. If you use the optional directory name parameter, the debugger displays a list of the specified directory's contents. If you don't use the parameter, the debugger lists the contents of the current directory.
disp
Syntax Menu selection Description
Open DISPlay Window
disp expression [, display format] none The DISP command opens a DISP window to display the contents of an array, structure, or pointer expressions to a scalar type (of the form *pointer). If the expression is not one of these types, then DISP acts like a ? command. You can have up to 120 DISP windows open at the same time. Once you open a DISP window, you may find that a displayed member is itself an array, structure, or pointer: A member that is an array looks like this A member that is a structure looks like this A member that is a pointer looks like an address [. . .] {. . .} 0x00000000
You can display the additional data (the data pointed to or the members of the array or structure) in another DISP window by using the DISP command again, using the arrow keys to select the field and then pressing F9 , or pointing the mouse cursor to the field and pressing the left mouse button. When you use the optional display format parameter, data will be displayed in one of the following formats:
Parameter * c d e f Result Default for the data type ASCII character (bytes) Decimal Exponential floating point Decimal floating point Parameter x o p s u Result Hexadecimal Octal Valid address ASCII string Unsigned decimal
Chapter Title--Attribute Reference
xv
Alphabetical Summary of Debugger Commands
The display format parameter can be used only when you are displaying a scalar type, an array of scalar type, or a individual member of an aggregate type. You can also use the DISP command with a typecast expression to display memory contents in any format. Here are some examples:
disp *0 disp *(float *)123 disp *(char *)0x111
This shows memory in the DISP window as an array of locations; the location that you specify with the expression parameter is member [0], and all other locations are offset from that location.
eval
Syntax
Evaluate Expression
eval expression e expression none The EVAL command evaluates an expression like the ? command does but does not show the result in the COMMAND window display area. EVAL is useful for assigning values to registers or memory locations in a batch file (where it's not necessary to display the result).
Menu selection Description
file
Syntax Menu selection Description
Display Text File
file filename LoadFile The FILE command displays the contents of any text file in the FILE window. The debugger continues to display this file until you run a program and halt in a C function. This command is intended primarily for displaying C source code. You can view only one text file at a time. You are restricted to displaying files that are 65,518 bytes long or less.
xvi
Alphabetical Summary of Debugger Commands
fill
Syntax Menu selection Description
Fill Memory
fill address, length,data MemoryFill The FILL command fills a block of memory with a specified value. This command has three parameters: The address parameter identifies the beginning of the block. The length parameter defines the number of 32-bit words that will be filled. The data is the value that the memory block will be filled with.
fpuregs
Syntax Menu selection Environments Description
Display '34082 Registers
fpuregs none basic debugger profiler
The FPUREGS command opens the FPU window to display '34082 registers. The window shows '34082 A- and B-file registers in double-precision scientific notation and status/configuration registers as hexadecimal values. Note: The FPU window can be displayed only if you've invoked the debugger with the -mc option.
func
Syntax Menu selection Description
Display Function
func func none The FUNC command displays a specified C function in the FILE window. You can identify the function by its name or its address; an address parameter is treated as a program-memory address. FUNC works similarly to FILE, but when you use FUNC, you don't need to identify the name of the file that contains the function.
Chapter Title--Attribute Reference
xvii
function name address
Alphabetical Summary of Debugger Commands
go
Syntax Menu selection Description
Run to Specified Address
go [address]
none The GO command executes code up to a specific point in your program. The address parameter is treated as program-memory address. If you don't supply an address, then GO acts like a RUN command without an expression parameter.
halt
Syntax Menu selection Description
Halt Target System
halt none The HALT command halts the target system after you've entered a RUNF command. When you invoke the debugger, it automatically executes a HALT command. Thus, if you enter a RUNF, quit the debugger, and later reinvoke the debugger, you will effectively reconnect the emulator to the target system and run the debugger in its normal mode of operation. Note: This command is for the emulator only; it does not work with the development board version of the debugger. If you attempt to use the HALT command with a development board, the debugger displays this error message: --- Execution error
ioregs
Syntax Menu selection Environments Description
xviii
Display I/O registers
ioregs none basic debugger profiler
The IOREGS command opens the I/O window to display the '340 I/O registers.
Running Title--Attribute Reference
load
Syntax Menu selection Description
Load Object File
load object filename Load Load The LOAD command loads both an object file and its associated symbol table into memory. In effect, the LOAD command performs both a RELOAD and an SLOAD. Note that the LOAD command clears the old symbol table and closes the WATCH and DISP windows.
Do not use the LOAD command while debugging TIGA applications.
ma
Syntax Menu selection Description
Memory Map Add
ma address, length, type MemoryAdd The MA command identifies valid ranges of target memory. This command has three parameters:
-
The address parameter defines the starting address of a range of memory. This parameter can be an absolute address, any C expression, the name of a C function, or an assembly language label. The length parameter defines the length of the range. This parameter can be any C expression. The type parameter identifies the read/write characteristics of the memory range. The type must be one of these keywords:
Use this keyword as the type parameter R, ROM, or READONLY W, WOM, or WRITEONLY RW or RAM PROTECT
To identify this kind of memory read-only memory write-only memory read/write memory no-access memory
A new memory map must not overlap an existing entry. If you define a range that overlaps an existing range, the debugger ignores the new range.
Chapter Title--Attribute Reference
xix
Alphabetical Summary of Debugger Commands
map
Syntax Menu selection Description
Enable Memory Mapping
map {on | off} MemoryEnable The MAP command enables or disables memory mapping. In some instances, you may want to explicitly enable or disable memory. Note that disabling memory mapping can cause bus fault problems in the target because the debugger may attempt to access nonexistent memory.
md
Syntax Menu selection Description
Memory Map Delete
md address MemoryDelete The MD command deletes a range of memory from the debugger's memory map. The address parameter identifies the starting address of a range of memory.
mem
Syntax Menu selection Description
Modify MEMORY Window Display
mem expression [, display format] none The MEM command identifies a new starting address for the block of memory displayed in the MEMORY window. The debugger displays the contents of memory at expression in the first data position in the MEMORY window. The end of the range is defined by the size of the window. The expression can be an absolute address, a symbolic address, or any C expression. When you use the optional display format parameter, memory will be displayed in one of the following formats:
xx
Alphabetical Summary of Debugger Commands
Parameter * c d e f
Result Default for the data type ASCII character (bytes) Decimal Exponential floating point Decimal floating point
Parameter x o p u
Result Hexadecimal Octal Valid address Unsigned decimal
mix
Syntax Menu selection Description
Enter Mixed Debugger Mode
mix MoDeMixed The MIX command changes from the current debugging mode to mixed mode. If you're already in mixed mode, the MIX command has no effect.
ml
Syntax Menu selection Description
Memory Map List
ml MemoryList The ML command lists the memory ranges that are defined for the debugger's memory map. The ML command lists the starting address, ending address, and read/write characteristics of each defined memory range.
mod
Syntax Menu selection Description
TIGA Module Identifier
mod [TIGA module name] none Once a module has been selected and dynamically loaded, it can be selected with the MOD command. The newly selected module becomes the default module, which helps avoid misinterpretation of variable names used in multiple modules. If you would like a list of the modules that have been dynamically loaded, enter the MOD command with no parameters.
Chapter Title--Attribute Reference
xxi
Alphabetical Summary of Debugger Commands
move
Syntax Menu selection Description
Move Active Window
move [X position, Y position [, width, length ] ] none The MOVE command moves the upper left corner of the active window to the specified XY position. If you choose, you can resize the window while you move it (see the SIZE command for valid width and length values). You can use the MOVE command in one of two ways: By supplying a specific X position and Y position or By omitting the X position and Y position parameters and using function keys to interactively move the window.
-
Valid X and Y positions depend on the screen size and the window size. These are the minimum and maximum XY positions. The maximum values assume that the window is as small as possible; for example, if a window was half as tall as the screen, you wouldn't be able to move its upper left corner to an X position on the bottom half of the screen.
Debugger Valid X options positions none -b -bb -bbb -bbbb -bbbbb 0 through 76 0 through 76 0 through 116 0 through 128 0 through 76 0 through 106 Valid Y positions 1 through 22 1 through 40 1 through 47 1 through 40 1 through 40 1 through 57 1 through 57
Screen size 80 characters by 25 lines 80 characters by 43 lines (EGA) 80 characters by 50 lines (VGA) 120 characters by 43 lines 132 characters by 43 lines 80 characters by 60 lines 100 characters by 60 lines
Note:
To use larger screen sizes, you must invoke the debugger with the appropriate -b option.
If you enter the MOVE command without X position and Y position parameters, you can use arrow keys to move the window:

Moves the active window down one line. Moves the active window up one line. Moves the active window left one character position. Moves the active window right one character position. or .
When you're finished using the arrow keys, you must press
xxii
Alphabetical Summary of Debugger Commands
mr
Syntax Menu selection Description
Memory Map Reset
mr MemoryReset The MR command resets the debugger's memory map by deleting all defined memory ranges from the map.
ms
Syntax Menu selection Description
Save a Block of Memory to a File
ms address, length,filename MemorySave The MS command saves the values in a block of memory to a system file. The command has three parameters: The address parameter identifies the beginning of the block. The length parameter defines the length, in words, of the block. The filename is a system file. Files are saved in COFF format.
next
Syntax Menu selection Description
Single-Step, Next Statement
next [expression] Next=F10 (in disassembly) The NEXT command is similar to the STEP command. If you're in C code, the debugger executes one C statement at a time. In assembly or mixed mode, the debugger executes one assembly language statement at a time. Unlike STEP, NEXT never updates the display when executing called functions; NEXT always steps to the next consecutive statement. Unlike STEP, NEXT steps over function calls rather than stepping into them--you don't see the single-step execution of the function call. The expression parameter specifies the number statements that you want to single-step. You can also use a conditional expression for conditional single-step execution (Running code conditionally, page xv, discusses this in detail).
Chapter Title--Attribute Reference
xxiii
Alphabetical Summary of Debugger Commands
prompt
Syntax Menu selection Description
Change Command-Line Prompt
prompt new prompt ColorPrompt The PROMPT command changes the command-line prompt. The new prompt can be any string of characters (note that a semicolon or comma ends the string).
quit
Syntax Menu selection Description
Exit Debugger
quit none The QUIT command exits the debugger and returns to the DOS environment.
reload
Syntax Menu selection Description
Reload Object Code
reload object filename LoadReload The RELOAD command loads only an object file without loading its associated symbol table. This is useful for reloading a program when target memory has been corrupted.
Do not use the RELOAD command while debugging TIGA applications.
xxiv
Alphabetical Summary of Debugger Commands
reset
Syntax Menu selection Description
Reset Target System
reset LoadReseT The RESET command works differently for the various '340 debugging systems:
-
For the emulator, RESET resets the target system. This is a software reset. For development boards, RESET reloads the monitor (gspmon) but does not reset the '340 device.
restart
Syntax Menu selection Description
Reset PC to Program Entry Point
restart rest LoadREstart The RESTART or REST command resets the program to its entry point. (This assumes that you have already used one of the load commands to load a program into memory.)
return
Syntax Menu selection Description
Return to Function's Caller
return ret none The RETURN or RET command executes the code in the current C function and halts when execution reaches the caller. Breakpoints do not affect this command, but you can halt execution by pressing the left mouse button or pressing ESC .
Chapter Title--Attribute Reference
xxv
Alphabetical Summary of Debugger Commands
run
Syntax Menu selection Description
Run Code
run [expression] Run=F5 The RUN command is the basic command for running an entire program. The command's behavior depends on the type of parameter you supply:
-
If you don't supply an expression, the program executes until it encounters a breakpoint or until you press the left mouse button or press ESC . If you supply a logical or relational expression, this becomes a conditional run (described in detail on page xv). If you supply any other type of expression, the debugger treats the expression as a count parameter. The debugger executes count instructions, halts, and updates the display.
runb
Syntax Menu selection Description
Run Benchmark
runb none The RUNB command executes a specific section of code and counts the number of CPU clock cycles consumed by the execution. In order to operate correctly, execution must be halted by a breakpoint. After RUNB execution halts, the debugger stores the number of cycles into the CLK pseudoregister. For a complete explanation of the RUNB command and the benchmarking process, read Section 9.7, Benchmarking, on page xvii. Note: Emulator Only This command is for the emulator only; it does not work with the development board version of the debugger. If you attempt to use the RUNB command with a development board, the debugger displays this error message: --- Execution error
xxvi
Alphabetical Summary of Debugger Commands
runf
Syntax Menu selection Description
Run Free
runf none The RUNF command disconnects the emulator from the target system while code is executing. When you enter RUNF, the debugger clears all breakpoints, disconnects the emulator from the target system, and causes the processor to begin execution at the current PC. You can quit the debugger, or you can continue to enter commands. However, any command that causes the debugger to access the target at this time produces an error. The HALT command stops a RUNF; the debugger automatically executes a HALT when the debugger is invoked. Note: Emulator Only This command is for the emulator only; it does not work with the development board version of the debugger. If you attempt to use the RUNF command with a development board, the debugger displays this error message: --- Execution error
scolor
Syntax Menu selection Description
Change Screen Colors
scolor area name, attribute1 [, attribute2 [, attribute3 [, attribute4 ] ] ] ColorConfig The SCOLOR command changes the color of specified areas of the debugger display and updates the display immediately. The area name parameter identifies the area of the display that is affected. The attributes identify how the area is affected. The first two attribute parameters usually specify the foreground and background colors for the area. If you do not supply a background color, the debugger uses black as the background. Valid values for the attribute parameters include:
black red bright blue magenta green yellow blink cyan white
Chapter Title--Attribute Reference
xxvii
Alphabetical Summary of Debugger Commands
Valid values for the area name parameters include:
menu_bar menu_hilite win_resize field_label cmd_cursor asm_label error_msg file_brk menu_border menu_hicmd field_text field_error cmd_echo asm_clabel file_line file_pc menu_entry win_border field_hilite cmd_prompt asm_data background file_eof file_pc_brk menu_cmd win_hiborder field_edit cmd_input asm_cdata blanks file_text
You don't have to type an entire attribute or area name; you need to type only enough letters to uniquely identify the attribute. If you supply ambiguous attribute names, the debugger interprets the names in this order: black, blue, bright, blink. If you supply ambiguous area names, the debugger interprets them in the order that they're listed above (left to right, top to bottom).
sconfig
Syntax Menu selection Description
Load Screen Configuration
sconfig [filename]
ColorLoad The SCONFIG command restores the display to a specified configuration. This restores the screen colors, window positions, window sizes, and border styles that were saved with the SSAVE command into filename. If you don't supply a filename, the debugger looks for the init.clr file. The debugger searches for the specified file in the current directory and then in directories named with the D_DIR environment variable.
xxviii
Running Title--Attribute Reference
setf
Syntax Menu selection Description
Set Default Data-Display Format
setf [data type, display format ] none The SETF command changes the display format for a specific data type. If you enter SETF with no parameters, the debugger lists the current display format for each data type.
-
The data type parameter can be any of the following C data types:
char uchar short int uint long ulong float double ptr
The display format parameter can be any of the following characters:
Parameter Result * c d e f Default for the data type ASCII character (bytes) Decimal Exponential floating point Decimal floating point Parameter x o p s u Result Hexadecimal Octal Valid address ASCII string Unsigned decimal
Only a subset of the display formats can be used for each data type. Listed below are the valid combinations of data types and display formats.
Data Type char (c) uchar (d) short (d) int (d) uint (d)

Valid Display Formats cdoxe

Data long (d) ulong (d) float (e) double (e) ptr (p)

Valid Display Formats cdoxe

f p s u Type
fpsu

To return all data types to their default display format, enter:
setf *
Chapter Title--Attribute Reference
xxix
Running Title--Attribute Reference
size
Syntax Menu selection Description
Size Active Window
size [width, length ] none The SIZE command changes the size of the active window. You can use the SIZE command in one of two ways:
-
By supplying a specific width and length or By omitting the width and length parameters and using function keys to interactively resize the window.
Valid values for the width and length depend on the screen size and the window position on the screen. These are the minimum and maximum window sizes.
Debugger Valid widths options none -b -bb -bbb -bbbb -bbbbb 4 through 80 4 through 80 4 through 120 4 through 132 4 through 80 4 through 100
Screen size 80 characters by 25 lines 80 characters by 43 lines (EGA) 80 characters by 50 lines (VGA) 120 characters by 43 lines 132 characters by 43 lines 80 characters by 60 lines 100 characters by 60 lines
Note:
Valid lengths 3 through 24 3 through 42 3 through 49 3 through 42 3 through 42 3 through 59 3 through 59
To use larger screen sizes, you must invoke the debugger with the appropriate -b option.
The maximum sizes assume that the window is in the upper left corner (beneath the menu bar). If a window is in the middle of the display, for example, you can't size it to the maximum height and width; you can size it only to the right and bottom screen borders. If you enter the SIZE command without width and length parameters, you can use arrow keys to size the window:

Makes the active window one line longer. Makes the active window one line shorter. Makes the active window one character narrower. Makes the active window one character wider.
When you're finished using the arrow keys, you must press
or
.
xxx
Alphabetical Summary of Debugger Commands
sload
Syntax Menu selection Description
Load Symbol Table
sload object filename LoadSymbols The SLOAD command loads the symbol table of the specified object file. SLOAD is useful in a debugging environment in which the debugger cannot, or need not, load the object code (for example, if the code is in ROM). SLOAD clears the existing symbol table before loading the new one but does not modify memory or set the program entry point. Note that SLOAD closes the WATCH and DISP windows.
sound
Syntax Menu selection Description
Enable Error Beep
sound none You can cause a beep to sound every time a debugger error message is displayed. This is useful if the COMMAND window is hidden (you wouldn't see the error message). By default, sound is off. on | off
ssave
Syntax Menu selection Description
Save Screen Configuration
ssave [filename] ColorSave The SSAVE command saves the current screen configuration to a file. This saves the screen colors, window positions, window sizes, and border styles. The filename parameter names the new screen configuration file. You can include path information (including relative pathnames); if you don't supply path information, the debugger places the file in the current directory. If you don't supply a filename, then the debugger saves the current configuration into a file named init.clr and places the file in the current directory.
Chapter Title--Attribute Reference
xxxi
Running Title--Attribute Reference
step
Syntax Menu selection Description
Single-Step
step [expression] Step=F8 (in disassembly) The STEP command single-steps through assembly language or C code. If you're in C code, the debugger executes one C statement at a time. In assembly or mixed mode, the debugger executes one assembly language statement at a time. If you're single-stepping through C code and encounter a function call, the STEP command shows you the single-step execution of the called function (assuming that the function was compiled with the compiler's -g debug option). When function execution completes, single-step execution returns to the caller. If the function wasn't compiled with the debug option, the debugger executes the function but doesn't show single-step execution of the function. The expression parameter specifies the number of statements that you want to single-step. You can also use a conditional expression for conditional single-step execution (Running code conditionally, page xv, discusses this in detail).
system
Syntax Menu selection Description
Enter Operating-System Command
system [operating-system command [, flag] ] none The SYSTEM command allows you to enter operating-system commands without explicitly exiting the debugger environment. If you enter SYSTEM with no parameters, the debugger will open a system shell and display the operating-system prompt. At this point, you can enter any operating-system command. (In MS-DOS, available memory may limit the commands that you can enter.) When you finish, enter the appropriate information to return to the debugger environment:
MS-DOS exit
xxxii
exit
UNIX or
CONTROL
D
Alphabetical Summary of Debugger Commands
If you prefer, you can supply the operating-system command as a parameter to the SYSTEM command. If the result of the command is a message or other display, the debugger will blank the top of the debugger display to show the information. In this case, you can use the flag parameter to tell the debugger whether or not it should hesitate after displaying the information. Flag may be a 0 or a 1. 0 If you supply a value of 0 for flag, the debugger immediately returns to the debugger environment after the last item of information is displayed. If you supply a value of 1 for flag, the debugger does not return to the debugger environment until you press . (This is the default.)
1
take
Syntax Menu selection Description
Execute Batch File
take batch filename [, suppress echo flag] none The TAKE command tells the debugger to read and execute commands from a batch file. The batch filename parameter identifies the file that contains commands. By default, the debugger echoes the commands to the output area of the COMMAND window and updates the display as it reads the commands from the batch file. This behavior can be changed by using the suppress echo flag:
-
-
If you don't use the suppress echo flag parameter, or if you use it but supply a nonzero value, then the debugger behaves in the default manner. If you would like to suppress the echoing and updating, use the value 0 for the suppress echo flag parameter.
Chapter Title--Attribute Reference
xxxiii
Running Title--Attribute Reference
tba
Syntax Menu selection Description
Set a Tentative Breakpoint on a TIGA Module
tba function name none The TBA command tells the debugger to look for function name in the TIGA application and set a breakpoint on that function when the module is loaded by the TIGA application.
tbd
Syntax Menu selection Description
Clear a Tentative Breakpoint
tbd none The TBD command deletes a tentative breakpoint from the list of functions to be watched for. The breakpoint index parameter corresponds to the index numbers shown with the BL (breakpoint list) command. If a tentative breakpoint is resolved and active, it cannot be deleted with this command; instead, you must use the BR (breakpoint reset) command.
breakpoint index
unalias
Syntax Menu selection Description
Remove Custom Command String
unalias alias name none The UNALIAS command deletes an alias and its definition.
xxxiv
Alphabetical Summary of Debugger Commands
use
Syntax Menu selection Description
Use Different Directory
use directory name none The USE command names an additional directory that the debugger can search when looking for source files. You can specify only one directory at a time.
wa
Syntax Menu selection Description
Watch Value Add
wa expression [, label] [, display format] WatchAdd The WA command displays the value of expression in the WATCH window. If the WATCH window isn't open, executing WA opens the WATCH window. The expression parameter can be any C expression, including an expression that has side effects. It's most useful to watch an expression whose value changes over time; constant expressions provide no useful function in the watch window. The label parameter is optional. When used, it provides a label for the watched entry. If you don't use a label, the debugger displays the expression in the label field. When you use the optional display format parameter, data will be displayed in one of the following formats:
Parameter * c d e f Result Default for the data type ASCII character (bytes) Decimal Exponential floating point Decimal floating point Parameter x o p s u Result Hexadecimal Octal Valid address ASCII string Unsigned decimal
If you want to use a display format parameter without a label parameter, just insert an extra comma. For example:
wa PC,,d
Chapter Title--Attribute Reference
xxxv
Alphabetical Summary of Debugger Commands
wd
Syntax Menu selection Description
Watch Value Delete
wd index number WatchDelete The WD command deletes a specific item from the WATCH window. The WD command's index number parameter must correspond to one of the watch indexes listed in the WATCH window.
whatis
Syntax Menu selection Description
What Is This Data?
whatis symbol none The WHATIS command shows the data type of symbol in the COMMAND window display area. The symbol can be any variable (local, global, or static), a function name, structure tag, typedef name, or enumeration constant.
win
Syntax Menu selection Description
Select Active Window
win WINDOW NAME none The WIN command allows you to select the active window by name. Note that the WINDOW NAME is in uppercase (matching the name exactly as displayed). You can spell out the entire window name, but you really need to specify only enough letters to identify the window. If several of the same types of window are visible on the screen, don't use the WIN command to select one of them. If you supply an ambiguous name (such as C, which could stand for CPU or CALLS), the debugger selects the first window it finds whose name matches the name you supplied. If the debugger doesn't find the window you asked for (because you closed the window or misspelled the name), then the WIN command has no effect.
xxxvi
Running Title--Attribute Reference
wr
Syntax Menu selection Description
WATCH Window Reset
wr WatchReset The WR command deletes all items from the WATCH window and closes the window.
zoom
Syntax Menu selection Description
Enlarge Active Window
zoom none The ZOOM command makes the active window as large as possible. To "unzoom" a window, enter the ZOOM command a second time; this returns the window to its prezoom size and position.
Chapter Title--Attribute Reference
xxxvii
Summary of Special Keys
14.3 Summary of Special Keys
The debugger provides function key, cursor key, and command key sequences for performing a variety of actions:
-
Editing text on the command line Using the command history Switching modes Halting or escaping from an action Displaying the pulldown menus Running code Selecting or closing a window Moving or sizing a window Scrolling through a window's contents Editing data or selecting the active field
Editing text on the command line
To do this Enter the current command (note that if you press the return key in the middle of text, the debugger truncates the input text at the point where you press this key) 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 already on the command line Use these function keys
Using the command history
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 Use these function keys
xxxviii
Summary of Special Keys
Switching modes
To do this Switch debugging modes in this order: auto assembly mixed Use this function key
Halting or escaping from an action
The escape key acts as an end or undo key in several situations.
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 (pressing this key leaves the field unchanged) Halt the display of a long list of data in the COMMAND window display area
Displaying pulldown menus
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 an adjacent menu Execute any of the choices from a displayed pulldown menu or Press the highlighted letter corresponding to your choice Use these function keys
Chapter Title--Attribute Reference
xxxix
Summary of Special Keys
Running code
To do this Run code from the current PC (equivalent to the RUN command without an expression parameter) Single-step code from the current PC (equivalent to the STEP command without an expression parameter) Single-step code from the current PC; step over function calls (equivalent to the NEXT command without an expression parameter) Use these function keys
Selecting or closing a window
To do this Select the active window (pressing this key makes each window active in turn; stop pressing the key when the desired window becomes active) Close the CALLS or DISP window (the window must be active before you can close it) Repeat the last command Use these function keys
Moving or sizing a window
You can use the arrow keys to interactively move a window after entering the MOVE or SIZE command without parameters.
Use these function keys
To do this
xl
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
Summary of Special Keys
Scrolling a window's contents
These descriptions and instructions for scrolling apply to the active window. Some of these descriptions refer to specific windows; if no specific window is named, then the description/instructions refer to any window that is active.
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
Editing data or selecting the active field
The F9 function key makes the current field (the field that the cursor is pointing to) active. This has various effects, depending on the 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 to display a member that is an array, structure, or pointer
Chapter Title--Attribute Reference
xli
xlii
Chapter 15
Basic Information About C Expressions
Many of the debugger commands take C expressions as parameters. This allows the debugger to have a relatively small yet powerful instruction set. Because C expressions can have side effects--that is, the evaluation of some types of expressions can affect existing values--you can use the same command to display or to change a value. This reduces the number of commands in the command set. This chapter contains basic information that you'll need to know in order to use C expressions as debugger command parameters.
Synopsis Page
If you're an experienced C programmer, skip this section. Because the C expressions you'll use are parameters to debugger commands, some language features may be inappropriate. This section covers specific implementation issues (including necessary limitations and additional features) related to using C expressions as command parameters.
15.1 C Expressions for Assembly Language Programmers
Topic
ii
15.2 Restrictions and Features Associated With Expression Analysis in the Debugger Restrictionsiv Additional features
iv
iv
Chapter Title--Attribute Reference
i
C Expressions for Assembly Language Programmers
15.1 C Expressions for Assembly Language Programmers
It's not necessary for you to be an experienced C programmer in order to use the debugger. However, in order to use the debugger's full capabilities, you might find it helpful to be familiar with the rules governing C expressions. You should obtain a copy of The C Programming Language (first or second edition) by Brian W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New Jersey. This book is referred to in the C community and in Texas Instruments documentation as K&R.
Note: A single value or symbol is a legal C expression.
K&R contains a complete description of C expressions; to get you started, here's a summary of the operators that you can use in expression parameters.
-
Reference operators -> [] & indirect structure reference array reference address (unary) . * direct structure reference indirection (unary)
-
Arithmetic operators + * % (type) addition (binary) multiplication modulo typecast - / - subtraction (binary) division negation (unary)
-
Relational and logical operators > < == && ! greater than less than is equal to logical AND logical NOT (unary) >= <= != || greater than or equal to less than or equal to is not equal to logical OR
ii
C Expressions for Assembly Language Programmers
-
Increment and decrement operators ++ increment -- decrement
These unary operators can precede or follow a symbol. When the operator precedes a symbol, the symbol value is incremented/decremented before it is used in the expression; when the operator follows a symbol, the symbol value is incremented/decremented after it is used in the expression. Because these operators affect the symbol's final value, they have side effects.
-
Bitwise operators & ^ >> bitwise AND bitwise exclusive-OR right shift | << ~ bitwise OR left shift 1s complement (unary)
-
Assignment operators = -= %= ^= <<= *= assignment assignment with subtraction assignment with modulo assignment with bitwise XOR assignment with left shift assignment with multiplication += /= &= |= >>= assignment with addition assignment with division assignment with bitwise AND assignment with bitwise OR assignment with right shift
These operators support a shorthand version of the familiar binary expressions; for example, X = X + Y can be written in C as X += Y. Because these operators affect a symbol's final value, they have side effects.
Chapter Title--Attribute Reference
iii
Restrictions and Features Associated With Expression Analysis in the Debugger
15.2 Restrictions and Features Associated With Expression Analysis in the Debugger
The debugger's expression analysis is based on C expression analysis. This includes all mathematical, relational, pointer, and assignment operators. However, there are a few limitations, as well as a few additional features not described in K&R C.
Restrictions
The following restrictions apply to the debugger's expression analysis features.
-
The sizeof operator is not supported. The comma operator (,) is not supported (commas are used to separate parameter values for the debugger commands). Function calls and string constants are currently not supported in expressions. The debugger supports a limited number of type casts--the following forms are allowed. ( basic type ) ( basic type * ...) ( [ structure/union/enum] structure/union/enum tag ) ( [ structure/union/enum] structure/union/enum tag * ... ) Note that you can use up to six *s in a cast.
Additional features
-
All floating-point operations are performed in double precision using standard widening. (This is transparent.) All registers can be referenced by name. Void expressions are legal (treated like integers). The specification of variables and functions can be qualified with context information. Local variables (including local statics) can be referenced with the expression form:
function name.local name
This expression format is useful for examining the automatic variables of a function that is not currently being executed. Unless the variable is static,
iv
Restrictions and Features Associated With Expression Analysis in the Debugger
however, the function must be somewhere in the current call stack. Note that if you want to see local variables from the currently executing function, you need not use this form; you can simply specify the variable name (just as in your C source). File-scoped variables (such as statics or functions) can be referenced with the expression form:
filename.function name or filename.variable name
This expression format is useful for accessing a file-scoped static variable (or function) that may share its name with variables in other files. Note that in this expression, filename does not include the file extension; the debugger searches the object symbol table for any source filename that matches the input name, disregarding any extension. Thus, if the variable ABC is in file source.c, you can specify it as source.ABC. These expression forms can be combined into an expression of the form:
filename.function name.variable name
-
Any integral or void expression may be treated as a pointer and used with the indirection operator (*). Here are several examples of valid use of a pointer in an expression:
*123 *A5 *(A2 + 123) *(I*J)
By default, the values are treated as integers (that is, these expressions point to integer values).
-
Any expression can be typecast to a pointer to a specific type (overriding the default of pointing to an integer, as described above). Hint: You can use casting with the WA and DISP commands to display data in a desired format. For example, the expression:
*(float *)10
treats 10 as a pointer to a floating-point value at location 10 in memory. In this case, the debugger fetches the contents of memory location 10 and treats the contents as a floating-point value. If you use this expression as a parameter for the DISP command, the debugger displays memory contents as an array of floating-point values within the DISP window, beginning with memory location 10 as array member [0].
Chapter Title--Attribute Reference
v
Restrictions and Features Associated With Expression Analysis in the Debugger
Note how the first expression differs from the expression
(float)*10
In this case, the debugger fetches an integer from address 10 and converts the integer to a floating-point value. You can also typecast to user-defined types such as structures; for example, the expression:
((struct STR *)10)->field
In this case, the debugger treats memory location 10 as a pointer to a structure of type STR (assuming that a structure is at address 10) and accesses a field from that structure.
vi
Appendix A Appendix A
Troubleshooting and Technical Notes
This appendix contains troubleshooting information and additional technical information about how the debugger works with the emulator and with development boards. Most people will not need this information. However, it is provided to help you if:
-
You are having problems invoking the debugger The debugger does not seem to be operating properly You are using an advanced design or nonstandard application (if, for example, you have written your own TIGA communication driver) and you need additional information about board operation or system interfaces
In addition, if you need detailed technical information, you can refer to the user's guide or installation guide that accompanied your board.
Synopsis Page
If you followed the installation instructions in the appropriate chapter, your board and debugger should operate properly. However, if you have problems with your installation, the troubleshooting information may provide a solution. This section lists the steps that the debugger performs during the invocation process. There are special considerations for using targets that hold HCS inactive during power-up. If you are using the SDB as a target system, read this section. These sections pertain to development boards only. They describe information about how development boards communicate with the debugger.
A.1 A.2 Troubleshooting an Emulator Installation Troubleshooting a Development Board Installation Common serial link problems Running the gspsetup utility
Topic
A-2 A-3 A-4 A-5
A.3
What the Debugger Does During Invocation
A-6
A.4
Using the Emulator With Target Systems That Hold HCS Inactive During Power-Up
A-7
A.5 A.6
Debugger and Monitor Communications Using a TIGA Communication Driver
A-8 A-10
Chapter Title--Attribute Reference
A-1
Troubleshooting an Emulator Installation
A.1 Troubleshooting an Emulator Installation
Here are suggested solutions for problems that you may encounter with your new emulator system.
-
If you invoke the debugger and see this message:
CANNOT INITIALIZE TARGET SYSTEM ! ! - Check I/O configuration - Check cabling and target power
use these questions to determine the problem area:
J J
Did you reset the emulator board before invoking the debugger? If not, be sure to execute emurst before invoking the debugger again. For more information, refer to Resetting the emulator on page viii. Are you identifying the correct I/O space? If you modified the emulator's I/O switches, be sure to use the emurst -p option and the db340emu -p option with the correct port address parameter. For more information, refer to Resetting the emulator on page viii and Invoking the Debugger on page xii. Is the cable connected correctly between the emulator and the target system? (If you check this, remember to be very careful with the target cable connector.)
J -
If the debugger comes up correctly but does not recognize an execution instruction (RUN, STEP, etc.), then the HSTCTLH register's HLT bit might be set. Clear the bit by modifying the contents of memory location 0xC000 0100 or by entering this command:
? HLT=0
If the contents of memory seem to be incorrect, check the CONFIG register to ensure that you have properly selected little-endian or big-endian mode. During a reset, the four LSBs of the reset vector determine the endian mode and the memory configuration. The target '34020 will not be completely reset until an execution command (RUN, STEP, etc.) is executed. For more information about this type of problem, refer to the TMS34020 Emulator Installation Guide.
A-2
Troubleshooting a Development Board Installation
A.2 Troubleshooting a Development Board Installation
Here are suggested solutions for problems that you may encounter with your new development system.
-
CANNOT FIND EVM MONITOR. This means that the debugger cannot find the gspmon.out file. Be sure that the PATH statement and the D_DIR environment variable were set up to identify the directory that contains gspmon.out, and that the commands to do this have been executed. If you are not sure, execute the DOS SET command without parameters:
set
-
This displays the current PATH and environment variable settings. If the settings are incorrect, re-execute the autoexec or initdb.bat file that sets these commands. Correct settings are shown in Section 2.3 on page iv. CANNOT LOAD EVM MONITOR. This means that there is a problem with loading the gspmon.out file onto the development board. Execute the gspsetup utility (see page A-4); gspsetup may report one of these errors with TIGA communications:
J
J -
TIGA communications driver not installed. This means that tigacd wasn't executed; be sure to invoke the tigacd utility as described in Installing the TIGA communication driver on page vii. gspsetup lists memory errors. If gspsetup lists memory errors, then the development board is using the wrong TIGA communications driver.
CANNOT RESET EVM. This means that the debugger has loaded the gspmon.out file onto the development board, but gspmon is not operating correctly. There are two reasons that this might happen:
J
J
If you are also using a '34020 emulator in your system, then the debugger may not be able to gain control of the '34020. Run gspsetup. If it reports that it is not able to gain control of the '340 processor, check to see if an emulator is connected to the target system. If so, refer to Section 1.4 (page ix). If an emulator is not connected to the target system, your board may be inoperable. The TIGA communication driver is not installed properly. Run gspsetup to determine if this is the problem.
Chapter Title--Attribute Reference
A-3
Troubleshooting a Development Board Installation
Common serial link problems
If you are using the development board version of the debugger for debugging TIGA applications, you may experience some of these problems:
-
GSPSETUP hangs for several seconds; the PC beeps three times, then returns to DOS. This means that the serial link is not operating properly. Uninstall the tigacom and debugcom drivers by entering:
tigacom /u debugcom /u
Now reinstall tigacom and debugcom; use a lower baud rate and make sure that you are using correct communication port settings.
-
GSPSETUP or DB340 executes properly, but you encounter data errors. There are two reasons that this may happen:
J
TheTIGA communication driver may not be operating properly on the target system. To check it, first, disable the TIGACD debug mode:
tigacd /d0
Now enter:
tigalnk /lx
J -
If no errors are reported, you can assume that the TIGA communication driver is operating properly. You may be using a baud rate that is too high for the host and target systems. Uninstall tigacom and debugcom (as described above), then reinstall them with a lower baud rate.
DB340 randomly locks up; the PC beeps three times, then returns to DOS. There are three reasons that this may happen:
J J J A-4
An application or driver executing on the target system may have corrupted the settings of the COM port (mouse drivers often use a COM port). You may be using a baud rate that is too high for the host and target systems. Uninstall tigacom and debugcom, then reinstall them with a lower baud rate. You may be operating in a 386 protected mode. Latency times due to mode switching result in a lowering of the maximum baud rate that is available in real mode. Try uninstalling debugcom and tigacom, then reinstalling them at a lower baud rate.
Operation is not smooth (for example, scrolling is not smooth). Sometimes, the debugger will hang for a couple of seconds, and executing
Troubleshooting a Development Board Installation
gspsetup -d does not produce smooth output of test results. The most common cause of this is hardware interrupts conflicting with PC time. The best solution is to remove any software that may be causing these conflicts from your target and host PC systems. Types of software that can cause this problem include LAN drivers, print spoolers, and any other serial devices (although a serial mouse has no noticeable effect).
Running the gspsetup utility
The gspsetup utility is used for verifying a proper serial link, but it can also be used for other purposes. The general format for running gspsetup is: gspsetup [-options] The gspsetup program has several options; these are listed in Table A-1.
Table A-1. gspsetup Options
Option -T -t -D -d -Maddress -maddress Description Test TIGA's host-to-'340 memory interface (this helps you to be sure that the TIGA communications driver is operating correctly). Don't perform tests on memory interface (this is the opposite of -T). Display information about tests and '340 settings. Don't display information about tests and '340 settings (this is the opposite of -D). Tests memory at the specified address. This option is useful if you've written your own version of a TIGA communication driver. Use -m to check that the three 32-bit words beginning at address are valid. If they are not valid, then gspsetup will display a message stating that it is unable to communicate with the development board via TIGA. Display gspsetup options.
-H, -h, or -?
For most applications, you can invoke gspsetup without options:
gspsetup
When you do this, gspsetup:
-
Tests TIGA's host-to-'340 memory interface (as if you had used -T), Turns the information display off (as if you had used -d), and Checks that the '340 is running freely.
Chapter Title--Attribute Reference
A-5
What the Debugger Does During Invocation
A.3 What the Debugger Does During Invocation
In some circumstances, you may find it helpful to know the steps that the debugger goes through during the invocation process. These are the steps, in order, that the debugger performs when you invoke it. 1) Reads options from the command line. 2) Reads any information specified with the D_OPTIONS environment variable. 3) Reads information from the D_DIR and D_SRC environment variables. 4) This step depends on whether you're using the development board or emulator version of the debugger:
-
-
Development board version: Initializes the target and downloads gspmon. Emulator version: Resets the target system.
5) Looks for the init.clr screen configuration file (the debugger searches for this file in directories named with D_DIR). 6) Initializes the debugger screen and windows but initially displays only the COMMAND window. 7) Looks for the dbinit.cmd or emuinit.cmd batch file (the debugger searches for this file in directories named with D_DIR). If the debugger finds the file, it opens the file and reads and executes the commands it finds inside. 8) Loads any object filenames specified with D_OPTIONS or specified on the command line during invocation. 9) Determines the initial mode (auto, assembly, or mixed) and displays the appropriate windows on the screen. At this point, the debugger is ready to process any commands that you enter.
A-6
Information About Target Systems for the Emulator
A.4 Using the Emulator With Target Systems That Hold HCS Inactive During Power-Up
Note: The information in this section applies only to target systems that hold HCS inactive during power-up. This includes the '34020 SDB. In systems that hold HCS inactive during power-up, the HSTCTLH register's HLT bit is set whenever the debugger resets the '34020. This causes the '34020 to remain in a halt state until HLT is cleared. As a result, none of the debugger execution commands (RUN, STEP, etc.) will advance execution of your program. You can fix this situation by performing these steps: 1) Invoke the debugger. 2) Modify the reset vector (address 0xFFFF FFE0). If you have a reset routine, modify the reset vector to point to the beginning this routine:
? *0xFFFFFFE0 = address of your reset routine
Be sure that the four LSBs of the new value indicate little endian/big endian usage and RCA bus configuration (as appropriate). If your program doesn't have a reset routine, modify the reset vector to point to c_int00:
? *0xFFFFFFE0 = c_int00
3) Clear the HLT bit:
? HLT=0
4) Execute a single instruction:
STEP
The '34020 reset will now take effect:
-
The 28 MSBs of the program counter are set to the contents of the 28 MSBs of the reset vector. The 4 LSBs of the CONFIG register are set to the 4 LSBs of the reset vector.
5) Set the CONFIG register to an appropriate value. For example, if you are using the '34020 SDB as a target system, set CONFIG to 0x0C0A:
? CONFIG=0x0C0A
A batch file named emuinit.cmd is provided to help you perform these steps.
Chapter Title--Attribute Reference
A-7
Debugger and Monitor Communications (Development Boards Only)
A.5 Debugger and Monitor Communications (Development Boards Only)
The debugger is made up of two separate programs:
-
The first program, called the host debugger, is executed by the host PC. The second program, called the target monitor, is downloaded to the development board by the debugger. The host debugger uses the monitor to control the '340 processor on the development board.
These two programs communicate through TIGA, using an area of development board memory for passing commands and data back and forth. In most cases, you need not be concerned with the communication between the debugger and the target monitor. However, if you are debugging a sophisticated source program (such as one that modifies certain trap vectors or uses the '34020's single-step capabilities), then it may be necessary to have a greater understanding of this communication process. The target monitor is in a file named gspmon.out. Whenever you invoke the debugger, it requests TIGA for a 4K-byte area of memory on the TIGA board. If the target monitor is accidentally modified by a write to these memory locations, the debugger attempts to repair the target monitor and displays an error message in the COMMAND window. If the debugger does not operate correctly after this occurs, then it was unable to repair the target monitor. You must reload the target monitor by entering the RESET and RESTART commands. If the target monitor was corrupted because the '340 stack used this memory, exit the debugger and reinvoke it. The target monitor gains control of the '340 by having the host temporarily halt the '340 processor, changing the NMI vector to point to the beginning of the monitor code, sending an NMI to the '340, and then unhalting the '340. The '340 then immediately saves its current context (the contents of the PC and ST) and jumps to the NMI routine (which now points to the monitor program). The target monitor can then store the '340 CPU registers and other information in development board memory, where the host can access them. When the debugger wants to resume execution of the source program, it signals the target monitor to return from the NMI interrupt routine. The saved PC and ST values are restored; this causes the source code to be executed, and the '340 runs freely again.
A-8
Debugger and Monitor Communications (Development Boards Only)
Because the '340 needs to save its context on the stack, the data on the stack below the top of the stack is invalid. The target monitor uses six 32-bit memory locations:
Stack Area valid valid valid SP 6 32-bit memory locations invalid invalid invalid low '340 memory high '340 memory
When breakpoints are set in the source program, the debugger temporarily replaces the program instruction at that memory address with a TRAP 29 instruction. (TRAP 29 must be reserved for the debugger's use.) The debugger changes the TRAP 29 vector to point to the target monitor code. When the '340 executes the TRAP 29 instruction, it saves the current context and jumps to the monitor code, which indicates to the host that a breakpoint was encountered. It is important that the program being debugged does not modify the TRAP vector used for breakpoints. When the debugger is used with a '34020, it uses the single-step status bit (SS) when it is necessary to execute only a single '34020 instruction. The source program should not modify the SS bit or the single-step vector (TRAP 32). The '34010 mimics this single-step ability by examining the next instruction to be executed and placing temporary breakpoints on all the possible PC destinations. The '34020 will also use this technique when it is about to single-step an instruction that could save or modify the status register. However, the debugger cannot anticipate when an interrupt is about to occur. Thus, when a run command is executing, it is possible that an interrupt could occur, and a copy of the ST with a set SS bit could be stored on the stack. This will not cause problems for the debugger; however, it may cause problems for the source program if it saves that ST and later uses it after the debugger is exited.
Chapter Title--Attribute Reference
A-9
Using a TIGA Communication Driver (Development Boards Only)
A.6 Using a TIGA Communication Driver (Development Boards Only)
The development board version of the C source debugger uses TIGA as a software interface between the host PC and the development board. The TIGA communication driver is responsible for providing all hardware-specific communication routines. Therefore, the debugger can be used without restriction for almost any development board--provided that a TIGA communication driver is available. Use of the communication driver may differ, depending on whether you are using a manufacturer-provided driver or you are developing a driver.
-
If you already have a TIGA communication driver, load and configure it according to the manufacturer's instructions. Then execute the gspsetup utility (described in Chapter 2). gspsetup tests to see that the host-to-'340 interface is operating correctly. (Note that gspsetup does not test for TIGA compatibility and does not perform an extensive memory test.) If you do not intend to support TIGA, you can use utilities that come with the debugger to create a communication driver that duplicates a small subset of TIGA's functionality. Follow these steps: 1) Be sure that you have copied the directory \db\hll from the original debugger product diskette into the directory c:\db\hll. You may need to modify the source files contained in this directory so that they will better suit your application. Refer to the README file and the source files for more information. 2) In order to create this driver, you will need the Microsoft C compiler (version 5.1 or higher) and Microsoft assembler MASM (version 5.0 or higher), or compatible tools. When these tools are installed, make the c:\db\hll directory the current directory, then enter:
make
This creates an executable file called hllcd.exe. The executable form of the driver is a small terminate-and-stay-resident program that you install in PC memory before invoking the debugger. To install hllcd in resident memory, enter:
hllcd
3) The driver will install itself in memory and make use of a single interrupt vector in the PC interrupt vector table. The default interrupt vector is 0x7F, but this vector can be changed by adding the following line to your autoexec.bat:
SET TIGA=-i0xnn
where nn represents the hexadecimal value of the desired interrupt vector.
A-10
Using a TIGA Communication Driver (Development Boards Only)
If necessary, you can remove the communication driver from memory by entering:
hllcd /u
The README file that accompanies the debugger software describes the files and utilities that are used for creating the communication driver. It also describes the routines that are supported.
Chapter Title--Attribute Reference
A-11
A-12
Appendix B Appendix A
Debugger Messages
This appendix contains an alphabetical listing of the progress and error messages that the debugger might display in the COMMAND window display area. Each message contains both a description of the situation that causes the message and an action to take if the message indicates a problem or error.
Synopsis Page
The debugger provides you with a command that associates a beeping sound with the display of error messages. The main portion of this appendix is the alphabetical message reference. These sections supplement the actions provided with error messages.
B.1 Associating Sound With Error Messages
Topic
B-2
B.2
Alphabetical Reference of Debugger Messages
B-2
B.3 B.4
Additional Instructions for Expression Errors Additional Instructions for Hardware Errors
B-19 B-19
Chapter Title--Attribute Reference
B-1
Associating Sound With Error Messages / Alphabetical Summary of Debugger Messages
B.1 Associating Sound With Error Messages
You can associate a beeping sound with the display of error messages. To do this, use the SOUND command. The format for this command is: sound on | off
By default, no beep is associated with error messages (SOUND OFF). The beep is helpful if the COMMAND window is hidden behind other windows.
B.2 Alphabetical Summary of Debugger Messages
Symbols
`]' expected
Description
This is an expression error--it means that the parameter contained an opening [ symbol but didn't contain a closing ] symbol. See Section B.3 (page B-19).
Action
`)' expected
Description
This is an expression error--it means that the parameter contained an opening ( symbol but didn't contain a closing ) symbol. See Section B.3 (page B-19).
Action
A
Aborted by user
Description Action
B-2
The debugger halted a long COMMAND display listing (from WHATIS, DIR, ML, or BL) because you pressed the ESC key. None required; this is normal debugger behavior.
Running Title--Attribute Reference
B
Breakpoint already exists at address
Description
During single-step execution, the debugger attempted to set a breakpoint where one already existed. (This isn't necessarily a breakpoint that you set--it may have been an internal breakpoint that was used for single-stepping). None should be required; you may want to reset the program entry point (RESTART) and re-enter the single-step command.
Action
Breakpoint table full
Description
200 breakpoints are already set and there was an attempt to set another. Note that the maximum limit of 200 breakpoints includes internal breakpoints that the debugger may set for single-stepping. Under normal conditions, this should not be a problem; it is rarely necessary to set this many breakpoints. Enter a BL command to see where you have breakpoints set in your program. Use the BR command to delete all breakpoints or use the BD command to delete individual unnecessary breakpoints.
Action
C
Cannot allocate host memory
Description Action
This is a fatal error--it means that the debugger is running out of memory to run in. You might try invoking the debugger with the -v option so that fewer symbols will be loaded. Or you might want to relink your program and link in fewer modules at a time.
Chapter Title--Attribute Reference
B-3
Running Title--Attribute Reference
Corrupt call stack
Description
The debugger tried to update the CALLS window and couldn't. This may be because a function was called that didn't return. Or, it could be that the call stack was overwritten in memory. If your program called a function that didn't return, then this is normal behavior (as long as you intended for the function not to return). Otherwise, you may be overwriting program memory.
Action
Cannot change directory
Description Action
The directory name specified with the CD command either doesn't exist or is not in the current or auxiliary directories. Check the directory name that you specified. If this is really the directory that you want, re-enter the CD command and specify the entire pathname for that directory (for example, specify C:\sdb, not just sdb).
Cannot edit field
Description Action
Expressions that are displayed in the WATCH window cannot be edited. If you attempted to edit an expression in the WATCH window, you may have actually wanted to change the value of a symbol or register used in the expression. Use the ? or EVAL command to edit the actual symbol or register. The expression value will automatically be updated.
Cannot find/open initialization file
Description Action
The debugger can't find the init.cmd file. Be sure that init.cmd is in the sdb (for development boards) or emu34020 (for the emulator) directory. If it isn't, copy it from the debugger product diskette. If init.cmd is in the correct directory, verify that the D_DIR environment variable is set up to identify the sdb or emu34020 directory. See Setting Up the Debugger Environment in the appropriate installation chapter.
B-4
Running Title--Attribute Reference
Cannot halt the processor
Description Action
This is a fatal error--for some reason, pressing halt program execution.
ESC
didn't
Exit the debugger. Invoke the autoexec or initdb.bat file, then invoke the debugger again.
Cannot map into reserved memory: address
Description Action
Memory at address 0xFFFF A500 through 0xFFFF D000 has been reserved for the monitor program (gspmon). Do not use the MA command to map into this reserved space.
Cannot open config file
Description Action
The SCONFIG command can't find the screen-customization file that you specified. Be sure that the filename was typed correctly. If it wasn't, re-enter the command with the correct name. If it was, re-enter the command and specify full path information with the filename.
Cannot open "filename"
Description Action
The debugger attempted to show filename in the FILE window but could not find the file. Be sure that the file exists as named. If it does, enter the USE command to identify the file's directory.
Cannot open object file: "filename"
Description Action
The file specified with the LOAD, SLOAD, or RELOAD command is not an object file that the debugger can load. Be sure that you're loading an actual object file. Be sure that the file was linked (you may want to run gspcl again to create an executable object file).
Chapter Title--Attribute Reference
B-5
Running Title--Attribute Reference
Cannot open new window
Description
A maximum of 127 windows can be open at once. The last request to open a window would have made 128, which isn't possible. Close any unnecessary windows. Windows that can be closed include WATCH, CALLS, and DISP. To close the WATCH window, enter WD. To close the CALLS window or a DISP window, make the desired window active and press F4 .
Action
Cannot read processor status
Description Action
This is a fatal error--for some reason, pressing halt program execution.
ESC
didn't
Exit the debugger. Invoke the autoexec or initdb.bat file, then invoke the debugger again. If you are using the emulator, check the cable connections, also.
Cannot reset the processor
Description Action
This is a fatal error--for some reason, pressing halt program execution.
ESC
didn't
Exit the debugger. If you are using the development board, invoke the autoexec or initdb.bat file, then invoke the debugger again. If you are using the emulator, there may be a problem with the target system; check the cable connections.
Cannot restart processor
Description Action
If a program doesn't have an entry point, then RESTART won't reset the PC to the program entry point. Don't use RESTART if your program doesn't have an explicit entry point.
Cannot set/verify breakpoint at address
Description
Either you attempted to set a breakpoint in read-only or protected memory, or there are hardware problems with the target system or development board. Check your memory map. If the address that you wanted to breakpoint wasn't in ROM, see Section B.4 (page B-19).
Action
B-6
Running Title--Attribute Reference
Cannot step
-
If you're using a development board:
Description The monitor program has been overwritten or damaged by program execution. Action
Exit the debugger. Invoke the autoexec or initdb.bat file, then invoke the debugger.
-
If you're using an emulator:
Description There is a problem with the target system. Action
See Section B.4 (page B-19).
Cannot take address of register
Description Action
This is an expression error. C does not allow you to take the address of a register. See Section B.3 (page B-19).
Command "cmd" not found
Description Action
The debugger didn't recognize the command that you typed. Re-enter the correct command. Refer to Chapter 14 or the Quick Reference Card for a list of valid debugger commands.
Command timed out, emulator busy
-
If you're using a development board:
Description The monitor program has been overwritten or damaged by program execution. Action
Exit the debugger. Invoke the autoexec or initdb.bat file, then invoke the debugger.
-
If you're using an emulator:
Description There is a problem with the target system. Action
See Section B.4 (page B-19).
Chapter Title--Attribute Reference
B-7
Running Title--Attribute Reference
Conflicting map range
Description Action
A block of memory specified with the MA command overlaps an existing memory map entry. Blocks cannot overlap. Use the ML command to list the existing memory map; this will help you find the existing block that the new block would overlap. If the existing block is not necessary, delete it with the MD command and re-enter the MA command. If the existing block is necessary, re-enter the MA command with parameters that will not overlap the existing block.
E
Emulator I/O address is invalid
Description Action
The debugger was invoked with the -p option, and an invalid port address was used. For valid port address values, refer to Table 3-3 (page xii).
Error in expression
Description Action
This is an expression error. See Section B.3 (page B-19).
Execution error
-
If you're using a development board:
Description The monitor program has been overwritten or damaged by program execution. Action
Exit the debugger. Invoke the autoexec or initdb.bat file, then invoke the debugger.
-
If you're using an emulator:
Description There is a problem with the target system. Action
B-8
See Section B.4 (page B-19).
Running Title--Attribute Reference
F
File not found
Description
The filename specified for the FILE command was not found in the current directory or any of the directories identified with D_SRC. Be sure that the filename was typed correctly. If it wasn't, re-enter the FILE command with the correct name. If it was, re-enter the FILE command and specify full path information with the filename.
Action
File not found : "filename"
Description
The filename specified for the LOAD, RELOAD, SLOAD, or TAKE command was not found in the current directory or any of the directories identified with D_SRC. Be sure that the filename was typed correctly. If it wasn't, re-enter the command with the correct name. If it was, re-enter the command and specify full path information with the filename.
Action
File too large (filename)
Description Action
You attempted to load a file that was more than 65,518 bytes long. Try loading the file without the symbol table (SLOAD), or use gspcl to relink the program with fewer modules.
Float not allowed
Description Action
This is an expression error--a floating-point value was used invalidly. See Section B.3 (page B-19).
Function required
Description Action
The parameter for the FUNC command must be the name of a function in the program that is loaded. Re-enter the FUNC command with a valid function name.
Chapter Title--Attribute Reference
B-9
Running Title--Attribute Reference
I
Illegal cast
Description Action
This is an expression error--the expression parameter uses a cast that doesn't meet the C language rules for casts. See Section B.3 (page B-19).
Illegal left hand side of assignment
Description Action
This is an expression error--the left hand side of an assignment expression doesn't meet C language assignment rules. See Section B.3 (page B-19).
Illegal operand of &
Description Action
This is an expression error--the expression attempts to take the address of an item that doesn't have an address. See Section B.3 (page B-19).
Illegal pointer math
Description Action
This is an expression error--some types of pointer math are not valid in C expressions. See Section B.3 (page B-19).
Illegal pointer subtraction
Description Action
This is an expression error--the expression attempts to use pointers in a way that is not valid. See Section B.3 (page B-19).
Illegal structure reference
Description
This is an expression error--either the item being referenced as a structure probably is not a structure, or you are attempting to reference a nonexistent portion of a structure. See Section B.3 (page B-19).
Action
B-10
Running Title--Attribute Reference
Illegal use of structures
Description Action
This is an expression error--the expression parameter is not using structures according to the C language rules. See Section B.3 (page B-19).
Illegal use of void expression
Description Action
This is an expression error--the expression parameter does not meet the C language rules. See Section B.3 (page B-19).
Integer not allowed
Description Action
This is an expression error--the command does will not accept an integer as a parameter. See Section B.3 (page B-19).
Invalid address --- Memory access outside valid range: address
Description Action
The debugger attempted to access memory at address, which is outside the memory map. Check your memory map to be sure that you access valid memory.
Invalid argument
Description Action
One of the command parameters does not meet the requirements for the command. Re-enter the command with valid parameters. Refer to the appropriate command description in Chapter 14.
Invalid attribute name
Description
The COLOR and SCOLOR commands accept a specific set of area names for their first parameter. The parameter entered did not match one of the valid attributes. Re-enter the COLOR or SCOLOR command with a valid area name parameter. Valid area names are listed in Table 4-2 (page iii).
Chapter Title--Attribute Reference
B-11
Action
Running Title--Attribute Reference
Invalid color name
Description
The COLOR and SCOLOR commands accept a specific set of color attributes as parameters. The parameter entered did not match one of the valid attributes. Re-enter the COLOR or SCOLOR command with a valid color parameter. Valid color attributes are listed in Table 4-1 (page ii).
Action
Invalid memory attribute
Description
The third parameter of the MA command specifies the type, or attribute, of the block of memory that MA adds to the memory map. The parameter entered did not match one of the valid attributes. Re-enter the MA command. Use one of the following valid parameters to identify the memory type: R, ROM, READONLY W, WOM, WRITEONLY RW, RAM PROTECT (read-only memory) (write-only memory) (read/write memory) (no-access memory)
Action
Invalid object file
Description
The file specified with the LOAD, SLOAD, or RELOAD command either is not an object file that the debugger can load, or it has been corrupted. Be sure that you're loading an actual object file. Be sure that the file was linked (you may want to run gspcl again to create an executable object file). If the file you attempted to load was a valid executable object file, then it was probably corrupted; recompile, assemble, and link with gspcl.
Action
B-12
Running Title--Attribute Reference
Invalid watch delete
Description
The debugger can't delete the parameter supplied with the WD command. Usually, this is because the watch index doesn't exist or because a symbol name, instead of a watch index, was typed. Re-enter the WD command. Be sure to specify the watch index that matches the item you'd like to delete (this is the number in the left column of the WATCH window). Remember, you can't delete items symbolically--you must delete them by number.
Action
Invalid window position
Description
The debugger can't move the active window to the XY position specified with the MOVE command. Either the XY parameters are not within the screen limits, or the active window may be too large to move to the desired position. You can use the mouse to move the window. If you don't have a mouse, enter the MOVE command without parameters; then use the arrow keys to move the window. When you finish, you must press ESC or . If you prefer to use the MOVE command with parameters, refer to Table 6-2 (page xxvii) for a list of the XY limits. The minimum XY position is 0,1; the maximum position depends on which screen size you're using.
Action
Invalid window size
Description
The width and length specified with the SIZE or MOVE command may be too large or too small. If valid width and length were specified, then the active window is already at the far right or bottom of the screen and so cannot be made larger. You can use the mouse to size the window. If you don't have a mouse, enter the SIZE command without parameters; then use the arrow keys to move the window. When you finish, you must press ESC or . If you prefer to use the SIZE command with parameters, refer to Table 6-1 (page xxiv) for a list of valid sizes. The minimum size is 4 by 3; the maximum size depends on which screen size you're using.
Chapter Title--Attribute Reference
B-13
Action
Running Title--Attribute Reference
L
Load aborted
Description Action
This message always follows another message. Refer to the message that preceded Load aborted.
Lost power (or cable disconnected)
Description Action
Either the target cable is disconnected, or the target system is faulty. Check the target cable connections. If the target seems to be connected correctly, see Section B.4 (page B-19).
Lost processor clock
Description Action
Either the target cable is disconnected or the target system is faulty. Check the target cable connections. If the target seems to be connected correctly, see Section B.4 (page B-19).
Lval required
Description Action
This is an expression error--an assignment expression was entered that requires a legal lefthand side. See Section B.3 (page B-19).
N
Name "name" not found
Description Action
The command cannot find the object named name. If name is a symbol, be sure that it was typed correctly. If it wasn't, re-enter the command with the correct name. If it was, then be sure that the associated object file is loaded. If name was some other type of parameter, refer to the command's description for a list of valid parameters.
B-14
Running Title--Attribute Reference
M
Memory access error at address
-
If you're using a development board:
Description There is a problem with the TIGA communication driver. Action
If you're using tigacd, exit the debugger. Reinstall tigacd and invoke the debugger. If you're using your own version of a TIGA communication driver, be sure to follow the instructions in Appendix A.
-
If you're using the emulator:
Description Either the processor is receiving a bus fault, or there are problems with target system memory. Action
See Section B.4 (page B-19).
Memory map table full
Description
Too many blocks have been added to the memory map. This will rarely happen unless someone is adding blocks word by word (which is inadvisable). Stop adding blocks to the memory map. Consolidate any adjacent blocks that have the same memory attributes.
Action
P
Pointer not allowed
Description Action
This is an expression error. See Section B.3 (page B-19).
Processor is already running
Description Action
One of the RUN commands was entered while the debugger was running free from the target system. Enter the HALT command to stop the free run, then re-enter the desired RUN command.
Chapter Title--Attribute Reference
B-15
Running Title--Attribute Reference
R
Register access error
-
If you're using a development board:
Description There is a problem with the TIGA communication driver. Action
If you're using tigacd, exit the debugger. Reinstall tigacd and invoke the debugger. If you're using your own version of a TIGA communication driver, be sure to follow the instructions in Appendix A.
-
If you're using the emulator:
Description Either the processor is receiving a bus fault, or there are problems with target system memory. Action
See Section B.4 (page B-19).
S
Specified map not found
Description Action
The MD command was entered with an address or block that is not in the memory map. Use the ML command to verify the current memory map. When you are using MD, you can specify only the first address of a defined block.
Structure member not found
Description Action
This is an expression error--an expression references a nonexistent structure member. See Section B.3 (page B-19).
Structure member name required
Description Action
B-16
This is an expression error--a symbol name followed by a period but no member name. See Section B.3 (page B-19).
Running Title--Attribute Reference
Structure not allowed
Description Action
This is an expression error--the expression is attempting an operation that cannot be performed on a structure. See Section B.3 (page B-19).
T
Take file stack too deep
Description
Batch files can be nested up to 10 levels deep. Batch files can call other batch files, which can call other batch files, and so on. Apparently, the batch file that you are TAKEing calls batch files that are nested more than 10 levels. Edit the batch file that caused the error. Instead of calling another batch file from within the offending file, you may want to copy the contents of the second file into the first. This will remove a level of nesting.
Action
Too many breakpoints
Description
200 breakpoints are already set, and there was an attempt to set another. Note that the maximum limit of 200 breakpoints includes internal breakpoints that the debugger may set for single-stepping. Under normal conditions, this should not be a problem; it is rarely necessary to set this many breakpoints. Enter a BL command to see where you have breakpoints set in your program. Use the BR command to delete all breakpoints, or use the BD command to delete individual unnecessary breakpoints.
Action
Too many memory maps
Description
Too many blocks have been added to the memory map. This will rarely happen unless someone is adding blocks word by word (which is inadvisable). Stop adding blocks to the memory map. Consolidate any adjacent blocks that have the same memory attributes.
Chapter Title--Attribute Reference
B-17
Action
Running Title--Attribute Reference
Too many paths
Description
More than 20 paths have been specified cumulatively with the USE command, D_SRC environment variable, and -i debugger option. If you are entering the USE command before entering another command that has a filename parameter, don't enter the USE command. Instead, enter the second command and specify full path information for the filename.
Action
W
Window not found
Description Action
The parameter supplied for the WIN command is not a valid window name. Re-enter the WIN command. Remember that window names must be typed in uppercase letters. Here are the valid window names; the bold letters show the smallest acceptable abbreviations: CALLS COMMAND CPU DISASSEMBLY DISP FILE MEMORY WATCH
U
User halt
Description Action
The debugger halted program execution because you pressed the ESC key. None required; this is normal debugger behavior.
B-18
Additional Instructions for Expression Errors and Hardware Errors
B.3 Additional Instructions for Expression Errors
Whenever you receive an expression error, you should re-enter the command and edit the expression so that it follows the C language expression rules. If necessary, refer to a C language manual such as The C Programming Language by Brian W. Kernighan and Dennis M. Ritchie.
B.4 Additional Instructions for Hardware Errors
If you continue to receive the messages that send you to this section, this indicates persistent hardware problems.
-
Development Boards
J
J J J J J J J J
The development board memory may not be properly configured--be sure that you are using an appropriate value in the CONFIG register (refer to the TMS34020 User's Guide). Check to be sure that the HSTCTLH register's RESET bit is not set while you are using the debugger. Check to see that the stack pointer (register A15) is pointing to valid memory. Check to see that you are refreshing VRAMs correctly (refer to the TMS34020 User's Guide).
Emulator If a bus fault occurs, the emulator may not be able to access memory. The '34020 must be reset before you can use the emulator. Most target systems reset the '34020 at power-up; your target system may not be doing this. Host accesses or retries that persist for longer than one second will prevent the emulator from accessing memory. Check your host interface code. The development board memory may not be properly configured--be sure that you are using an appropriate value in the CONFIG register (refer to the TMS34020 User's Guide). Check to see that you are refreshing VRAMs correctly (refer to the TMS34020 User's Guide).
Chapter Title--Attribute Reference
B-19
B-20
Appendix C Appendix A
Glossary
A
active window: The window that is currently selected for moving, sizing, editing, closing, or some other function. aggregate type: A C data type, such as a structure or array, where a variable is composed of multiple variables, called members. aliasing: A method of customizing debugger commands; aliasing provides a shorthand method for entering often-used command strings. ANSI C: A version of the C programming language that conforms to the C standards defined by the American National Standards Institute. assembly mode: A debugging mode that shows assembly language code in the DISASSEMBLY and doesn't show the FILE window, no matter what type of code is currently running. autoexec.bat: PC. A batch file that contains DOS commands for initializing your
auto mode: A context-sensitive debugging mode that automatically switches between shown assembly language code in the DISASSEMBLY window or C code in the FILE window, depending on what type of code is currently running.
B
batch file: Either of two different types of files. One type of batch file contains DOS commands for the PC to execute. A second type of batch file contains debugger commands for the debugger to execute. The PC doesn't execute debugger batch files, and the debugger doesn't execute PC batch files. benchmarking: A type of program execution that allows you to track the number of CPU cycles consumed by a specific section of code.
Chapter Title--Attribute Reference
C-1
Running Title--Attribute Reference
breakpoint: A point within your program where execution will halt because of a previous request from you.
C
CALLS window: A window that lists the functions called by your program. casting: A feature of C expressions that allows you to use one type of data as if it were a different type of data. children: Windows opened for aggregate types that are themselves members of an aggregate type displayed in the DISP window. click: Press and release a mouse button without moving the whole mouse. CLK: A pseudoregister that shows the number of CPU cycles consumed during benchmarking. The value in CLK is valid only after entering a RUNB command but before entering another RUN command. code-display windows: Windows that show code, text files, or code-specific information. This category includes the DISASSEMBLY, FILES, and CALLS windows. COFF: Common Object File Format. An implementation of the object file format of the same name developed by AT&T. The '340 family compiler, assembler, and linker use and generate COFF files. command line: The portion of the COMMAND window where you can enter commands. command-line cursor: Block-shaped cursor that identifies the current character position on the command line. COMMAND window: A window that provides a display area where you enter commands and where the debugger echoes command entry , shows command output, and lists progress or error messages. CPU window: A window that displays the contents of '340 on-chip registers, including the program counter, status register, A-file registers, and B-file registers. current-field cursor: An icon that identifies the current field in the active window. cursor: An icon on the screen (such as a rectangle or a horizontal line) that is used as a pointing device. The cursor is usually under mouse or keyboard control.
C-2
Running Title--Attribute Reference
D
data-display windows: Windows for observing and modifying various types of data. This category includes the MEMORY, CPU, DISP, and WATCH windows. D_DIR: An environment variable that identifies the directory containing the commands and files necessary for running the debugger. debugger: A window-oriented software interface that helps you to debug '340 programs running on a '340 development board or '34020 emulator. development board: A PC board that uses a '34010 or '34020 processor and a TIGA communication driver. disassembly: A reverse assembly of the contents of memory to form assembly language code. DISASSEMBLY window: A window that displays the disassembly of memory contents. DISP window: A window that displays the members of an aggregate data type. display area: The portion of the COMMAND window where the debugger echoes command entry , shows command output, and lists progress or error messages. D_OPTIONS: An environment variable that you can use for identifying oftenused debugger options. drag: To move the mouse while pressing one of the mouse buttons. D_SRC: An environment variable that identifies directories containing program source files.
E
EGA: Enhanced Graphics Adaptor. An industry standard for video cards. EISA: Extended Industry Standard Architecture. A standard for PC buses. emulator: A debugging tool that is external to the target system and provides direct control over the '340 processor that is on the target system. emurst: A utility that resets the emulator. environment variable: A special system symbol that the debugger uses for finding directories or obtaining debugger options.
Chapter Title--Attribute Reference
C-3
Running Title--Attribute Reference
F
FILE window: A window that displays the contents of the current C code. The FILE window is primarily intended for displaying C code but can be used to display any text file.
G
gspcl: A shell utility that invokes the '340 family compiler, assembler, and linker to create an executable object file version of your program. gspmon: The development board monitor program. It contains '340 routines that the debugger uses for controlling the '340 processor. gspsetup: A utility that tests TIGA communications for the development board version of the debugger.
H
hybrid applications: '340 applications that are split into two parts. One part runs entirely on the '340 processor, a second part runs on the host PC. The two parts communicate during program execution.
I
initdb.bat: As part of normal debugger use, you must enter DOS commands to set up the debugger environment. The most convenient method for doing this is to edit your PC's autoexec.bat file or to create a separate initdb.bat file that is used only for this purpose. I/O switches: Hardware switches on the '34020 emulator board that identify the PC I/O memory space used for emulator debugger communications. ISA: Industry Standard Architecture. A subset of the EISA standard.
M
memory map: A special set of commands that tells the debugger which areas of memory can and can't be accessed. MEMORY window: A window that displays the contents of memory. menu bar: A row of pulldown menu selections, found at the top of the debugger display.
C-4
Running Title--Attribute Reference
mixed mode: A debugging mode that simultaneously shows both assembly language code in the DISASSEMBLY window and C code in the FILE window. mouse cursor: Block-shaped cursor that tracks mouse movements over the entire display.
P
PC: Either of two meanings, depending on the context and where it's used in this book: 1) In installation instructions or information relating to hardware and boards, PC means Personal Computer (as in IBM PC). 2) In general debugger and program-related information, PC means Program Counter, which is the register that identifies the current statement in your program. point: To move the mouse cursor until it overlays the desired object on the screen. port address: The PC I/O memory space that the debugger uses for communicating with the emulator. The port address is selected via switches on the emulator board and communicated to the debugger with the -p debugger option. pulldown menu: A command menu that is accessed by name or with the mouse from the menu bar at the top of the debugger display.
S
scalar type: A C type where the variable is a single variable itself, not composed of other variables. scroll: To move the contents of a window up, down, left, or right to view contents that weren't shown. SDB: Software Development Board. A standalone, high-performance, graphics-development board, compatible with the IBM PC-AT ISA bus. Provides an environment for debugging '34020 application software. side effects: A feature of C expressions in which using an assignment operator in an expression affects the value of one of the components used in the expression. single-step: A form of program execution that allows you to see the effects of each statement. The program is executed statement by statement; the debugger pauses after each statement to update the data-display windows.
Chapter Title--Attribute Reference
C-5
Running Title--Attribute Reference
standalone applications: '340 applications that execute entirely on the '340 processor without interacting with the host PC. symbol table: A file that contains the names of all variables and functions in your '340 program.
T
target system: A '340 board that works with the emulator; the emulator doesn't contain a '340 and so must use a '340 target board. Usually, the target system is a board that you have designed and that you debug using the emulator and debugger. TDB: TIGA Development Board. A standard video display adapter for ISAand EISA-based PCs; provides an environment for debugging '34010 application software. TIGA: Texas Instruments Graphical Architecture. A software interface standard that allows a host process to communicate with the '340 graphics processor residing on your development board. The current implementation of TIGA is for the PC market and serves as an interface between the '340 and an 80x86 processor running under MS-DOS. TIGA applications: A variation of a hybrid application in which the part of the program that would be controlled by the '340 is controlled by TIGA. tigacd: The TIGA communication driver, which is a terminate-and-stay resident program that runs on a PC. It is specific to a particular board and is supplied by the board manufacturer. The communication driver contains functions that are invoked by the application's calls to the application interface. This enables communication via the PC bus to the target '340 board. TMS34010: The first-generation graphics system processor from Texas Instruments. TMS34020: The second-generation graphics system processor from Texas Instruments. TMS340: A collective term used to mean '34010 or '34020 or '34010 and '34020. TRAP: A '340 processor software interrupt.
V
VGA: Video Graphics Array. An industry standard for video cards.
C-6
Running Title--Attribute Reference
W
WATCH window: A window that displays the values of selected expressions, symbols, addresses, and registers. window: A defined rectangular area of virtual space on the display.
Chapter Title--Attribute Reference
C-7
Running Title--Attribute Reference
C-8
Index
? command, 4-18, 11-3, 14-7, 14-15, 14-35 display formats, 4-27, 11-22, 14-7 modifying PC, 9-10 side effects, 11-5 -? gspsetup option, A-5 ANSI C, 5-6 archiver, 5-7 area names (for customizing the display) code-display windows, 13-5 COMMAND window, 13-4 common display areas, 13-3 data-display windows, 13-6 menus, 13-7 summary of valid names, 13-3 window borders, 13-4 arithmetic operators, 15-2 arrays displaying/modifying contents, 11-15 format in DISP window, 4-24, 11-16, 14-15 member operators, 15-2 arrow keys editing, 11-4 moving a window, 4-10, 6-26, 14-40 scrolling, 6-28, 14-41 sizing a window, 4-8, 6-23, 14-40 ASM command, 4-14, 9-3, 14-9 pulldown selection, 7-11, 9-3 assembler, 2-2, 3-3, 5-7, 5-8 assembly language code displaying, 6-2, 6-3, 9-2, 9-4 assembly mode, 4-13, 6-3 selection, 9-3 assignment operators, 11-5, 15-3 attributes, 13-2 auto mode, 4-13, 6-2--6-3 selection, 9-3 autoexec.bat development boards, 2-4--2-7 emulator, 3-4--3-12 invoking, 2-5, 3-5 sample development boards, 2-5 emulator, 3-5
A
absolute addresses, 11-7, 12-3 active window, 6-18--6-20 breakpoints, 12-3 current field, 4-7, 6-17 customizing its appearance, 13-4 default appearance, 6-18 effects on command entry, 7-3 identifying, 4-7, 6-18 selecting, 6-19, 14-36 function key method, 4-7, 6-19, 14-40 mouse method, 4-7, 6-19 WIN command, 4-6, 6-20 zooming, 4-9, 6-23, 14-37 additional software development boards, 2-3 emulator, 3-3 ADDR command, 6-7, 6-8, 9-5, 9-7, 14-8 addresses absolute addresses, 11-7, 12-3 accessible locations, 8-1 contents of (indirection), 11-8 hexadecimal notation, 11-7 in MEMORY window, 4-6, 11-7 nonexistent locations, 8-2 pointers in DISP window, 4-24 symbolic addresses, 11-7 aggregate types displaying, 4-23, 6-15, 11-15--11-17 ALIAS command, 4-30, 7-14--7-15, 14-8 aliasing, 7-14--7-15
Index-1
Index
B
-b debugger option development boards, 2-12 effect on window positions, 6-25 effect on window sizes, 6-22 emulator, 3-11 with D_OPTIONS environment variable development boards, 2-7 emulator, 3-7 BA command, 12-3, 14-9 pulldown selection, 7-10, 7-11 background, 13-3 batch files, 7-12 autoexec.bat development boards, 2-4--2-7 emulator, 3-4--3-12 dbinit.cmd 2-3, 8-2, 8-9, A-6 displaying, 9-7 emuinit.cmd, 3-3, 8-2, 8-9, A-6, A-7 execution, 14-33 halting execution, 7-12 init.clr, 2-3, 3-3, 13-9 initdb.bat development boards, 2-4--2-7 emulator, 3-4--3-12 invoking autoexec.bat, 2-5, 3-5 initdb.bat, 2-5, 3-5 mem.map, 8-8 memory maps, 8-3, 8-4, 8-8, 8-9 mono.clr, 2-3, 3-3, 13-9 sdbmap.cmd, 2-3, 8-4 TAKE command, 7-12, 8-8, 8-9, 14-33 tdbmap.cmd, 2-3, 8-3 BD command, 12-4, 14-9 pulldown selection, 7-10, 7-11 benchmarking, 4-18, 9-17 bitwise operators, 15-3 BL command, 12-5, 14-10 pulldown selection, 7-10, 7-11 blanks, 13-3 BORDER command, 13-8, 14-10 pulldown selection, 7-11 borders colors, 13-4 styles, 13-8 Index-2
BR command, 4-18, 12-4, 14-11 pulldown selection, 7-10, 7-11 breakpoints, 12-1--12-6 active window, 4-7 adding, 14-9 function key method, 12-3, 14-41 mouse method, 12-3 with commands, 12-3 benchmarking with RUNB, 4-18, 9-17 clearing, 4-18, 12-4, 14-9, 14-11 function key method, 12-4, 14-41 mouse method, 12-4 with commands, 12-4 commands BA command, 12-3, 14-9 BD command, 12-4, 14-9 BL command, 12-5, 14-10 BR command, 4-18, 12-4, 14-11 listing set breakpoints, 12-5, 14-10, 14-34 pulldown menu, 7-10, 7-11 setting, 4-16, 4-18, 12-2 function key method, 12-3, 14-41 mouse method, 12-3 with commands, 12-3 tentative breakpoints TBA command, 14-34 TBD command, 14-34
C
C bit, 11-13 C command, 4-14, 9-3, 14-11 pulldown selection, 7-11, 9-3 C source debugging, managing memory data, 11-8 displaying, 4-12, 9-4, 14-16 cache disabling, 11-13 flushing, 11-13 CALLS command, 6-9, 6-10, 14-11 CALLS window, 4-12, 6-9, 9-7 closing, 6-10, 6-30, 14-40 opening, 6-10, 14-11 carry bit, 11-13 casting, 4-26, 11-8, 15-4 CD bit, 11-13 CF bit, 11-13 CHDIR (CD) command, 4-23, 7-18, 9-9, 14-12 clearing the display area, 4-23, 7-5, 14-12
Index
"click and type" editing, 6-29, 11-4 CLK pseudoregister, 4-18, 9-17 closing a window, 6-30 CALLS window, 6-10, 6-30, 14-40 debugger, 2-13, 3-12, 14-24 DISP window, 4-25, 6-30, 11-17, 14-40 WATCH window, 6-30, 11-19, 14-37 CLS command, 4-23, 7-5, 14-12 CNEXT command, 9-13, 14-12 code-display windows, 6-5, 9-2 CALLS window, 6-9, 9-2, 9-7 DISASSEMBLY window, 4-6, 6-7, 9-2 effect of debugging modes, 9-2 FILE window, 6-8, 9-2 COLOR command, 13-2, 14-13 color.clr, 13-9 colors, 13-2 area names, 13-3--13-7 comma operator, 15-4 command history, 7-4 function key summary, 14-38 command line, 6-6, 7-2 changing the prompt, 13-12, 14-24 cursor, 6-17 customizing its appearance, 13-4, 13-12 editing, 7-3 function key summary, 14-38 COMMAND window, 6-5, 6-6, 7-2 colors, 13-4 command line, 4-5, 7-2 editing keys, 14-38 customizing, 13-4 display area, 4-5, 7-2 clearing, 14-12 commands alphabetical summary, 14-7--14-37 batch files, 7-12 breakpoint commands, 12-3--12-6, 14-5 code-execution (run) commands, 9-10, 14-6 command line, 7-2 command strings, 7-14 customizing, 7-14 data-management commands, 11-2--11-22, 14-4 entering and using, 7-1--7-18 file-display commands, 9-4, 14-4 load commands, 9-8, 14-4 memory commands, 8-5--8-10
commands (continued) memory map commands, 14-6 mode commands, 9-2, 14-3 pulldown menus, 7-6, 7-10 screen-customization commands, 13-1, 14-5 system commands, 7-16--7-18, 14-3 window commands, 6-20, 6-22, 6-25, 14-3 communication drivers, A-10--A-12 debugcom, 2-3 tigacd, 2-3 tigacom, 2-3 compiler, 2-2, 3-3, 5-6, 5-8 CONFIG register, A-7 constraints, 5-10 CPU window, 6-12, 11-2, 11-11--11-14 colors, 13-6 customizing, 13-6 CSTEP command, 4-20, 9-13, 14-14 current directory changing, 7-18, 9-9, 14-12 current field cursor, 6-17 dialog box, 7-4 current PC, 4-5, 6-7 finding, 9-10 selecting, 9-10 cursors, 6-17 command-line cursor, 6-17 current-field cursor, 6-17 mouse cursor, 6-17 customizing the display, 13-1--13-12 changing the prompt, 13-12, 14-24 colors, 13-2--13-7 init.clr, 2-3, 3-3 loading a custom display, 13-10, 14-28 mono.clr, 2-3, 3-3 saving a custom display, 13-10, 14-31 window border styles, 13-8
D
-D,-d gspsetup options, A-5 DASM command, 6-7, 9-5, 14-14 data-display windows, 4-23, 6-5, 11-2 colors, 13-6 CPU window, 6-12, 11-2, 11-11 DISP window, 6-15, 11-2, 11-15 FPUREGS window, 6-14
Index-3
Index
data-display windows (continued) I/O window, 6-13 MEMORY window, 4-6, 6-11, 11-2, 11-6 WATCH window, 4-19, 6-16, 11-2, 11-18 data-management commands, 4-21, 4-23, 11-2 ? command, 4-18, 11-3, 14-7, 14-15, 14-35 controlling data format, 4-26--4-27, 11-8 data-format control, 11-20--11-22 DISP command, 11-15, 14-15 EVAL command, 11-3 FILL command, 11-10 FPUREGS command, 14-17 IOREGS command, 14-18 MEM command, 4-6, 11-6, 14-21 MS command, 11-9 SETF command, 11-20--11-21, 14-29 side effects, 11-5 WA command, 4-19, 11-18, 14-35 WD command, 11-19, 14-36 WHATIS command, 4-22, 11-2, 14-36 WR command, 4-22, 11-19, 14-37 data memory saving, 11-9 data types, 11-20 data-display windows FPUREGS window, 14-17 I/O window, 14-18 db340 command, 1-8, 2-12--2-13, 4-4, 9-8, 9-9 options, 2-12--2-13 -b, 2-12 D_OPTIONS environment variable, 2-7 -i, 2-12 -s, 2-12 -v, 2-13 -z, 2-13 db340emu command, 1-8, 3-11--3-12, 4-4, 9-8, 9-9 options, 3-11--3-12 -b, 3-11 D_OPTIONS environment variable, 3-7 -i, 3-11 -p, 3-11 -s, 3-12 -v, 3-12 -z, 3-12 dbinit.cmd 2-3, 8-2, 8-9, A-6 D_DIR environment variable, 7-12, 13-10, 14-28 development boards, 2-6 effects on debugger invocation, A-6 emulator, 3-6 Index-4
debugcom communication driver, 2-3 debugger description, 5-2--5-4 development board version, 1-1, 2-1--2-14 environment setup, 2-4--2-7 installation, 2-1--2-14 invocation, 2-12--2-13 system overview, 1-2--1-3 development environments non-TIGA host applications, 1-7 standalone applications, 1-6 TIGA applications, 1-6 emulator version, 1-1, 3-1--3-12 environment setup, 3-4--3-8 installation, 3-1--3-12 invoking, 3-11 system overview, 1-4 invocation, 4-4 development board, 2-12 emulator, 3-11--3-12 key features, 5-3--5-4 messages, B-1--B-20 system overview, 1-1--1-8 debugging modes, 4-13--4-14, 9-3 assembly mode, 6-3 auto mode, 6-2 default mode, 6-2, 9-2 mixed mode, 6-4 pulldown menu, 4-14, 9-3 restrictions, 6-4 selection, 4-13 commands, 9-3 function key method, 9-3, 14-39 mouse method, 9-3 decrement operator, 15-3 default data formats, 11-20 debugging mode, 6-2, 9-2 display, 4-5, 6-2, 9-2, 13-11 file extensions, 5-8 memory map, 2-3, 3-3, 8-3 screen configuration file, 2-3, 3-3, 13-9 monochrome displays, 2-3, 3-3, 13-9 development boards additional software, 2-3 TIGA, 2-3 Windows 3.0, 2-3 debugger installation, 2-1--2-14 emulator in same system, 1-8, A-3 development boards (continued)
Index
hardware requirements, 2-2 software requirements, 2-2 system interface, A-8--A-9 system overview, 1-2--1-3 development environments non-TIGA host applications, 1-7 standalone applications, 1-6 TIGA applications, 1-6 dialog boxes, 7-8 DIR command, 4-23, 7-18, 14-15 directories changing current directory, 7-18, 14-12 emu34020 directory, 3-4, 3-6 for auxiliary files development boards, 2-6 emulator, 3-6 for debugger software development boards, 2-4, 2-6 emulator, 3-4, 3-6 identifying current directory, 9-9 identifying source directories, 14-35 development boards, 2-6 emulator, 3-6 listing contents of current directory, 7-18, 14-15 relative pathnames, 7-18, 14-12 sdb directory, 2-4, 2-6 search algorithm, 7-12, 9-9, A-6 DISASSEMBLY window, 4-6, 6-7 colors, 13-5 customizing, 13-5 modifying display, 14-14 DISP command, 4-23, 6-15, 11-15, 14-15 display formats, 4-27, 11-22, 14-15 DISP window, 4-23, 6-15, 11-2, 11-15 closing, 4-25, 6-30, 11-17 colors, 13-6 customizing, 13-6 identifying arrays, structures, pointers, 14-15 opening, 11-15 opening another DISP window, 11-16 function key method, 4-25, 11-16, 14-41 mouse method, 4-24, 11-16 with DISP command, 11-16 display area, 6-6 clearing, 4-23, 7-5, 14-12 display formats, 4-26--4-27, 11-20--11-22 ? command, 4-27, 11-22, 14-7 casting, 4-26 data types, 11-20
DISP command, 4-26, 4-27, 11-22, 14-15 enumerated types, 6-15 floating-point values, 6-15 integers, 6-15 MEM command, 4-27, 11-22, 14-21 pointers, 6-15 SETF command, 4-26, 11-20--11-21, 14-29 WA command, 4-26, 11-22, 14-35 display requirements, 2-2, 3-2 second monitor, 2-2 displaying assembly language code, 9-4 batch files, 9-7 C code, 9-6 data in nondefault formats, 11-20--11-22 graphics routines, 2-2 source programs, 9-4 text files, 9-7 D_OPTIONS environment variable development boards, 2-7 effects on debugger invocation, A-6 emulator, 3-7 DOS, setting up debugger environment development boards, 2-5 emulator, 3-5 drawing graphics routines, 2-2 D_SRC environment variable, 9-9 development boards, 2-6 effects on debugger invocation, A-6 emulator, 3-6
E
edit key (F9), 6-29, 11-4, 14-41 editing "click and type" method, 4-28, 11-4 command line, 7-3, 14-38 data values, 11-4, 14-41 dialog boxes, 7-9 expression side effects, 11-5 FILE, DISASSEMBLY, CALLS, 6-29 function key method, 11-4, 14-41 MEMORY, CPU, DISP, WATCH, 6-29 mouse method, 11-4 overwrite method, 11-4 window contents, 6-29 emu34020 directory, 3-4, 3-6 emuinit.cmd, 3-3, 8-2, 8-9, A-6, A-7 emulator, 1-5
Index-5
Index
additional software, 3-3 Windows 3.0, 3-3 debugger installation, 3-1--3-12 development board in same system, 1-8, A-3 hardware requirements, 3-2 resetting, 3-3, 3-8 software requirements, 3-3 system overview, 1-4--1-5 target system information, 1-8, A-7 emurst, 3-3, 3-8 -p option, 3-8 -x option, 3-8 end key scrolling, 6-28, 14-41 entering commands from pulldown menus, 7-6--7-11 on the command line, 7-2--7-5 entry point, 9-10 enumerated types, display format, 6-15 environment variables D_DIR, 7-12, 13-10 development boards, 2-6 emulator, 3-6 D_OPTIONS development boards, 2-7, 2-12 emulator, 3-7, 3-11 D_SRC, 9-9 development boards, 2-6 emulator, 3-6 for debugger options development boards, 2-7, 2-12 emulator, 3-7, 3-11 identifying auxiliary directories development boards, 2-6 identifying auxiliary directories, 3-6 identifying source directories development boards, 2-6 emulator, 3-6 error messages beeping, 14-31, B-2 EVAL command, 11-3, 14-16 modifying PC, 9-10 side effects, 11-5 executing code, 4-12, 9-10--9-15 See also run commands benchmarking, 4-18, 9-12, 9-17 conditionally, 4-21, 9-15 function key method, 14-40 executing code (continued) Index-6
halting execution, 4-16, 9-16 program entry point, 4-16, 4-18, 9-10--9-15 single stepping, 4-20, 14-12, 14-14, 14-23, 14-32 while disconnected from the target system, 9-14, 14-27 executing commands, 7-3 exiting the debugger, 2-13, 3-12, 4-30, 14-24 expressions, 15-1--15-6 addresses, 11-7 evaluation with ? command, 11-3, 14-7, 14-15, 14-35 with EVAL command, 11-3 expression analysis, 15-4 operators, 15-2--15-3 restrictions, 15-4 side effects, 11-5 void expressions, 15-4 extensions, 5-10
F
F4 key, 6-30, 11-17, 14-40 FE0 bit, 11-13 FE1 bit, 11-13 field extension bits, 11-13 size bits, 11-13 FILE command, 4-12, 4-15, 6-8, 9-6, 14-16 changing the current directory, 7-18, 14-12 pulldown selection, 7-11 FILE window, 4-12, 4-15, 6-8, 9-6 colors, 13-5 customizing, 13-5 file/load commands ADDR command, 9-5, 9-7, 14-8 CALLS command, 9-7, 14-11 DASM command, 9-5, 14-14 FILE command, 4-12, 4-15, 9-6, 14-16 FUNC command, 4-15, 9-6, 14-17 LOAD command, 4-5, 9-8, 14-19 pulldown menu, 7-11 RELOAD command, 9-8, 14-24 RESTART command, 14-25 SLOAD command, 9-8, 14-31 files saving memory to a file, 11-9 FILL command, 11-10, 14-17, 14-23 pulldown selection, 7-11 floating point
Index
display format, 4-26, 6-15 operations, 15-4 FPUREGS command, 14-17 FPUREGS window, 6-14 FS0 bits, 11-13 FS1 bits, 11-13 FUNC command, 4-15, 6-8, 9-6, 14-17 function calls displaying functions, 14-17 keyboard method, 6-10 mouse method, 6-10 executing function only, 14-25 in expressions, 11-5, 15-4 stepping over, 14-12, 14-23 tracking in CALLS window, 6-9--6-10, 9-7, 14-11
hardware checklist development boards, 2-2 emulator, 3-2 hexadecimal notation, addresses, 11-7 history of commands, 7-4 HLT bit, 11-13, A-2, A-7 home key scrolling, 6-28, 14-41 host debugger, A-8 host system, 2-2, 3-2 HSTCTLH register, 11-13, A-2
I
-i debugger option development boards, 2-12, 9-9 emulator, 3-11, 9-9 with D_OPTIONS environment variable development boards, 2-7 emulator, 3-7 I/O window, 6-13 IE bit, 11-13 increment operator, 15-3 index numbers for data in WATCH window, 6-16, 11-19 indirection operator (*), 11-8 init.clr, 2-3, 3-3, 13-9, 13-10, 14-28, A-6 initdb.bat development boards, 2-4--2-7 emulator, 3-4--3-12 invoking, 2-5, 3-5 sample development boards, 2-5 emulator, 3-5 initialization files naming an alternate file, 2-13, 3-12 installation development board debugger, 2-4 emulator debugger, 3-4 integer display format, 6-15 interrupts enable bit, 11-13
G
-g shell option, 5-8, 5-9 general-purpose registers, 11-11 global interrupt enable bit, 11-13 GO command, 4-12, 9-11, 14-18 graphics card requirements, 2-2, 3-2 graphics routines drawing, 2-2 grouping/reference operators, 15-2 gspcl shell, 5-9 gspmon, 2-3, 9-14 gspsetup options, A-5 running, A-5
H
-H,-h gspsetup options, A-5 HALT command, 9-14, 14-18 halting batch file execution, 7-12 debugger, 2-13, 3-12, 14-24 HLT bit, 11-13 program execution, 2-13, 3-12, 4-16, 9-10, 9-16 function key method, 9-16, 14-39 mouse method, 9-16 target system, 14-18
Index-7
Index
invoking autoexec.bat, 2-5, 3-5 custom displays, 13-11 debugger, 4-4 development boards, 2-12 emulator, 3-11 initdb.bat, 2-5, 3-5 shell program, 5-9 IOREGS command, 14-18 ISA, 2-2, 3-2
K
key sequences displaying functions, 14-41 displaying previous commands (command history), 14-38 editing command line, 7-3, 14-38 data values, 6-29, 14-41 halting actions, 14-39 moving a window, 6-26, 14-40 opening additional DISP windows, 11-16, 14-41 pulldown selections, 14-39 running code, 9-11, 14-40 scrolling, 6-28, 14-41 selecting the active window, 6-19, 14-40 setting/clearing breakpoints, 14-41 single stepping, 9-13 sizing a window, 6-23, 14-40 switching debugging modes, 14-39
load/file commands, 14-17 ADDR command, 9-5, 14-8 CALLS command, 9-7, 14-11 DASM command, 9-5, 14-14 FILE command, 4-12, 9-6, 14-16 FUNC command, 4-15, 9-6, 14-17 LOAD command, 4-5, 9-8, 14-19 pulldown menu, 7-11 RELOAD command, 9-8, 14-24 RESTART command, 14-25 SLOAD command, 9-8, 14-31 loading batch files, 7-12 custom displays, 13-10 monitor program, 2-3 object code, 4-4, 9-8 after invoking the debugger, 9-8 symbol table only, 9-8, 14-31 while invoking the debugger, 9-8
development boards, 2-12 emulator, 3-11
without symbol table, 9-8, 14-24 logical operators, 15-2 conditional execution, 9-15
M
-M,-m gspsetup options, A-5 MA command, 8-5, 8-7, 14-19--14-20 pulldown selection, 7-11 managing data, 11-1--11-22 basic commands, 11-2--11-3 MAP command, 8-6, 14-20 pulldown selection, 7-11 MD command, 8-7, 14-20 pulldown selection, 7-11 MEM command, 4-6, 6-12, 11-6, 14-21 display formats, 4-27, 11-22, 14-20 memory commands FILL command, 11-10, 14-17, 14-23 MA command, 8-5, 8-7, 14-19--14-20 MAP command, 8-6, 14-20 MD command, 8-7, 14-20 ML command, 8-6, 14-20 MR command, 8-7, 14-23 MS command, 11-9 pulldown menu, 7-11 data formats, 11-20
L
labels for data in WATCH window, 4-19, 6-16, 11-19 limits breakpoints, 12-2 command aliasing, 7-15 file size, 9-7 open DISP windows, 6-15 paths, 9-9 window positions, 6-25 window sizes, 6-22 linker, 2-2, 3-3, 5-7, 5-8 command files MEMORY definition, 8-2 LOAD command, 4-5, 9-8, 14-19 Index-8
Index
memory (continued) default map, 2-3, 3-3, 8-3 displaying in different numeric format, 4-26, 11-8 filling, 11-10, 14-17, 14-23 invalid locations, 8-5 mapping, 8-1--8-10 adding ranges, 8-5, 14-19 dbinit.cmd, 2-3 defining a memory map, 8-2 deleting ranges, 8-7, 14-20 development boards
sdbmap.cmd, 2-3 tdbmap.cmd, 2-3
modes (continued) commands ASM command, 4-14 C command, 4-14, 14-11 MIX command, 4-14, 14-21 mixed mode, 6-4 pulldown menu, 4-13, 4-14, 7-11, 9-3 restrictions, 6-4 selection, 4-13, 9-3 commands, 9-3 function key method, 9-3, 14-39 mouse method, 9-3 modifying colors, 13-2--13-7 command line, 7-3 command-line prompt, 13-12 current directory, 7-18, 14-12 data values, 11-4 memory map, 8-7 window borders, 13-8 monitor program default memory space, 2-3 loading, 2-3 mono.clr, 2-3, 3-3, 13-9 monochrome monitors, 13-9 mouse cursor, 6-17 requirements, 2-2, 3-2 MOVE command, 4-10, 6-25, 14-22 effect on entering other commands, 7-4 moving a window, 6-24, 14-22 function key method, 4-10, 6-26, 14-40 mouse method, 4-10, 6-24 MOVE command, 4-10, 6-25 XY screen limits, 6-25 MR command, 8-7, 14-23 pulldown selection, 7-11 MS command, 11-9 pulldown selection, 7-11 MS-DOS, exiting from system shell, 14-32
emuinit.cmd, 3-3 emulator, 3-3 enabling/disabling, 8-6 listing current map, 8-6 modifying, 8-7 multiple maps, 8-9 resetting, 8-7, 14-23 returning to default, 8-8 nonexistent locations, 8-2 requirements development boards, 2-2 emulator, 3-2 saving, 11-9 valid types, 8-5
MEMORY window, 4-6, 6-11, 11-2, 11-6, 14-21 colors, 13-6 customizing, 13-6 modifying display, 14-21 menu bar, 4-5, 7-6 customizing its appearance, 13-7 items without menus, 7-10 using menus, 7-6--7-11 messages, B-1--B-20 MIX command, 4-14, 9-3, 14-21 pulldown selection, 7-11, 9-3 mixed mode, 4-13, 6-4 selection, 9-3 ML command, 8-6, 14-21 pulldown selection, 7-11 MOD command, 14-21 modes, 6-2--6-4 assembly mode, 6-3 auto mode, 6-2
N
N bit, 11-13 natural format, 4-26, 15-5 negative bit, 11-13
Index-9
Index
NEXT command, 4-20, 9-13, 14-23 from the menu bar, 7-10 function key entry, 7-10, 14-40 non-TIGA host applications, 1-7 nonexistent locations, 8-2
O
object files creating, 9-8 loading, 14-19 after invoking the debugger, 9-8 development boards, 2-12 emulator, 3-11 symbol table only, 2-12, 14-31
development boards, 2-12 emulator, 3-12
while invoking the debugger, 4-4, 9-8
development boards, 2-12 emulator, 3-11
without symbol table, 9-8, 14-24 object format converter, 5-7 operators, 15-2--15-3 & operator, 11-7 * operator (indirection), 11-8 side effects, 11-5 overflow bit, 11-13 overwrite editing, 11-4
port address, 3-11 D_OPTIONS, 3-7 program constraints, 5-10 entry point, 9-10 resetting, 14-25 execution, halting, 2-13, 3-12, 4-16, 9-10, 9-16, 14-39 preparation for debugging, 5-8 program counter (PC), 9-10, 11-11 displaying contents of, 4-6 finding the current PC, 6-7 program memory, saving, 11-9 PROMPT command, 13-12, 14-24 pulldown selection, 7-11 PSIZE register, 11-12 pulldown menus, 7-6 colors, 13-7 correspondence to commands, 7-10 customizing their appearance, 13-7 entering parameter values, 7-8 escaping, 7-8 function key methods, 7-8, 14-39 list of menus, 7-6 mouse methods, 7-7 moving to another menu, 7-8 usage, 7-7
P
-p debugger option, 3-11 with D_OPTIONS environment variable emulator, 3-7 -p emurst option, 3-8 page-up/page-down keys, scrolling, 6-28, 14-41 parameters db340 command, 2-12--2-14 db34emu command, 3-11--3-12 entering in a dialog box, 7-8 gspcl shell, 5-9 PATH statement, 2-6, 3-6 pixel size, 11-12 pointers display format, 6-15 displaying/modifying contents, 4-24, 11-15 format in DISP window, 4-24, 11-16, 14-15 natural format, 15-5 typecasting, 15-5 Index-10
Q
QUIT command, 2-13, 3-12, 4-30, 14-24
R
re-entering commands, 7-4, 14-38 registers A and B files, 11-11 CLK pseudoregister, 4-18, 9-17 CONFIG register, A-7 displaying/modifying, 11-11--11-14 HSTCTLH register, 11-13 I/O registers, 11-12--11-13 program counter (PC), 11-11 PSIZE register, 11-12 stack pointer (SP), 11-11 status register (ST), 11-12, 11-13 relational operators, 15-2 conditional execution, 9-15 relative pathnames, 7-18, 9-9, 14-12
Index
RELOAD command, 14-24 pulldown selection, 7-11 repeating commands, 7-4, 14-38 required files development boards debugcom.exe, 2-3 gspmon.out, 2-3 tigacd, 2-3 tigacom.exe, 2-3 emulator, emurst, 3-3 required tools, 2-2, 3-3 reserved traps, 5-10 RESET command, 4-5, 9-14, 14-25 pulldown selection, 7-11 reset vector, A-7 resetting '34020 processor, A-2 emulator, 3-3, 3-8 memory map, 14-23 program entry point, 14-25 target system, 4-5, 9-14, 14-25 RESTART (REST) command, 4-16, 4-18, 9-10, 14-25 pulldown selection, 7-11 restrictions. See limits and complaints RETURN (RET) command, 9-11, 14-25 RST bit, 11-13 RUN command, 4-16, 9-11, 14-26 from the menu bar, 7-10 function key entry, 7-10, 9-11, 14-40 menu bar selections, 7-10 with conditional expression, 4-21 run commands, 4-12 CNEXT command, 9-13, 14-12 conditional parameters, 4-21 CSTEP command, 4-20, 9-13, 14-14 GO command, 9-11, 14-18 HALT command, 9-14, 14-18 menu bar selections, 7-10, 14-40 NEXT command, 4-20, 9-13, 14-23 RESET command, 9-14 RESTART command, 4-16, 4-18, 9-10 RETURN command, 9-11, 14-25 RUN command, 4-16, 9-11, 14-26 RUNB command, 4-18, 9-12, 9-17, 14-26 RUNF command, 9-14, 14-27 STEP command, 4-20, 9-12, 14-32 RUNB command, 4-18, 9-12, 9-17, 14-26
RUNF command, 1-8, 9-14, 14-27 running programs, 9-10--9-15 conditionally, 9-15 halting execution, 9-16 program entry point, 9-10--9-15 while disconnected from the target system, 9-14
S
-s debugger option development boards, 2-12, 9-8 emulator, 3-12, 9-8 with D_OPTIONS environment variable development boards, 2-7 emulator, 3-7 saving custom displays, 13-10 SCOLOR command, 13-2, 14-27 pulldown selection, 7-11 SCONFIG command, 13-10, 14-28 pulldown selection, 7-11 screen-customization commands BORDER command, 13-8, 14-10 COLOR command, 13-2, 14-13 PROMPT command, 13-12, 14-24 pulldown menu, 7-11 SCOLOR command, 13-2, 14-27 SCONFIG command, 13-10, 14-28 SSAVE command, 13-10, 14-31 scrolling, 4-11, 6-27 function key method, 4-11, 6-28, 14-41 mouse method, 4-11, 6-28, 11-7 SDB, 1-1, 1-3 debugger installation, 2-1--2-14 system overview, 1-2--1-8 target system for emulator, 1-8, A-3, A-7 sdb directory, 2-4, 2-6 sdbmap.cmd, 2-3, 8-4 SETF command, 4-26, 11-20--11-21, 14-29 shell program, 5-9 side effects, 11-5, 15-3 valid operators, 11-5 single step commands CNEXT command, 9-13, 14-12 CSTEP command, 4-20, 9-13, 14-14 menu bar selections, 7-10 NEXT command, 4-20, 9-13, 14-23 STEP command, 4-20, 9-12, 14-32
Index-11
Index
single step (continued) execution, 9-12 assembly language code, 9-12--9-13, 14-32 C code, 9-13, 14-14 function key method, 9-13, 14-40 mouse methods, 9-13 over function calls, 9-13, 14-12, 14-23 status bit, A-9 SIZE command, 4-8, 6-22, 14-30 effect on entering other commands, 7-4 sizeof operator, 15-4 sizes displayable files, 9-7 sizing a window, 6-21 function key method, 4-8, 6-23, 14-40 mouse method, 4-8, 6-21 SIZE command, 4-8, 6-22 size limits, 6-22 while moving it, 6-25, 14-22 SLOAD command, 9-8, 14-31 pulldown selection, 7-11 -s debugger option development boards, 2-12 emulator, 3-12 software checklist development boards, 2-2 emulator, 3-3 software development board. See SDB SOUND command, 14-31, B-2 SSAVE command, 13-10, 14-31 pulldown selection, 7-11 stack pointer (SP), 11-11 standalone applications, 1-6 status register (ST), 11-12 accessible bits STC, 11-13 STN, 11-13 STV, 11-13 STZ, 11-13 STEP command, 4-20, 9-12, 14-32 from the menu bar, 7-10 function key entry, 7-10, 14-40 structures direct reference operator, 15-2 displaying/modifying contents, 11-15 format in DISP window, 4-25, 11-16, 14-15 indirect reference operator, 15-2 Index-12
switch settings I/O address space, 3-7, 3-8, 3-11 symbol table loading without object code, 2-12, 9-8, 14-31 development boards, 2-12 emulator, 3-12 symbolic addresses, 11-7 SYSTEM command, 7-16--7-17, 14-32 system commands, 7-16--7-18 ALIAS command, 14-8 CD command, 4-23, 7-18, 9-9, 14-12 CLS command, 4-23, 7-5, 14-12 DIR command, 4-23, 7-18, 14-15 from debugger command line, 7-16 QUIT command, 2-13, 3-12, 4-30, 14-24 RESET command, 4-5, 14-25 SOUND command, 14-31, B-2 SYSTEM command, 14-32 system shell, 7-17 TAKE command, 7-12, 8-8, 8-9, 14-33 UNALIAS command, 14-34 USE command, 9-9, 14-35 system overview, 1-1--1-8 emulator, 1-4--1-8 SDB, 1-2--1-3 TDB, 1-2--1-8 third-party boards, 1-2--1-3 system shells, 7-16--7-17
T
-t debugger option, 2-13, 3-12 -T,-t gspsetup options, A-5 TAKE command, 7-12, 8-8, 8-9, 14-33 reading new memory map, 8-9 target monitor, A-8 target system holding HCS inactive during power-up, A-7 memory definition for debugger, 8-1--8-10 resetting, 4-5, 14-25 SDB, 1-8 TBA command, 14-34 TBD command, 14-34 TDB, 1-1, 1-3 debugger installation, 2-1--2-14 system overview, 1-2 tdbmap.cmd, 2-3, 8-3
Index
tentative breakpoints TBA command, 14-34 TBD command, 14-34 terminating the debugger, 14-24 text files displaying, 4-15, 9-7 third-party boards, 1-1, 1-3 debugger installation, 2-1--2-14 system overview, 1-2 TIGA clearing tentative breakpoints, 14-34 communication driver. See tigacd debugger applications, 1-6 development board. See TDB development board (TDB), 1-3 development board use, 1-2--1-3, 2-3 loading custom modules, 14-21 setting tentative breakpoints, 14-34 tigacd, 2-3, A-10--A-12 installing, 2-7 tigacom communication driver, 2-3 TRAP 29, 5-10, A-9 TRAP 32, 5-10 troubleshooting development board installation, A-3 emulator installations, A-2 type casting, 4-26, 15-4 type checking, 4-22, 11-2
variables aggregate values in DISP window, 4-23, 6-15, 11-15, 14-15 determining type, 11-2 displaying in different numeric format, 4-26, 15-5 displaying/modifying, 11-18 scalar values in WATCH window, 6-16, 11-18--11-19 versions debugger. See debugger (development boards or emulator) GSPCL, 5-9 void expressions, 15-4
W
WA command, 4-19, 6-16, 11-18, 14-35 display formats, 4-26, 14-35 pulldown selection, 7-11 watch commands pulldown menu, 7-11, 11-18 WA command, 4-19, 11-18, 14-35 WD command, 4-21, 11-19, 14-36 WR command, 4-22, 11-19, 14-37 WATCH window, 4-19, 6-16, 11-2, 11-18, 14-35, 14-36, 14-37 adding items, 11-18, 14-35 closing, 6-30, 11-19, 14-37 colors, 13-6 customizing, 13-6 deleting items, 11-19, 14-36 labeling watched data, 11-19, 14-35 opening, 11-18, 14-35 WD command, 4-21, 6-16, 11-19, 14-36 pulldown selection, 7-11 WHATIS command, 4-22, 11-2, 14-36 WIN command, 4-6, 6-20, 14-36 windows, 6-5--6-16 active window, 6-18--6-20 border styles, 13-8, 14-10 closing, 6-30 commands ADDR command, 6-7, 6-8 CALLS command, 6-9 DASM command, 6-7 DISP command, 6-15 FILE command, 6-8 FUNC command, 6-8 MEM command, 6-11
U
UNALIAS command, 7-15, 14-34 UNIX, exiting from system shell, 14-32 USE command, 9-9, 14-35
V
V bit, 11-13 -v debugger option development boards, 2-13 emulator, 3-12 with D_OPTIONS environment variable development boards, 2-7 emulator, 3-7 -v shell option, 5-9
Index-13
Index
windows, commands (continued) MOVE command, 4-10 SIZE command, 4-8, 14-30 WA command, 6-16 WD command, 6-16 WIN command, 4-6, 6-20, 14-22, 14-36 WR command, 6-16 ZOOM command, 14-37 editing, 6-29 moving, 4-10, 6-24, 14-22 function keys, 6-26, 14-40 mouse method, 6-24 MOVE command, 6-25 XY positions, 6-25 resizing, 4-8, 6-21 function keys, 6-23, 14-40 mouse method, 6-21 SIZE command, 6-22 while moving, 6-25, 14-22 scrolling, 4-11, 6-27 size limits, 6-22
Windows 3.0 development board use, 2-3 emulator use, 3-3 WR command, 4-22, 6-16, 11-19, 14-37 pulldown selection, 7-11
X
-x debugger option development boards, 2-13 emulator, 3-12 -x emurst option, 3-8
Z
Z bit, 11-13 -z shell option, 5-9 zero bit, 11-13 ZOOM command, 4-9, 6-23, 14-37 zooming a window, mouse method, 4-9
Index-14

▲Up To Search▲

Price & Availability of SPVU021A

	To Download SPVU021A Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .