13H6964 000011 Twelfth edition (August 2000) This edition RI
|
|
|
Top Searches for this datasheet
RISCWatch Debugger User's Guide
13H6964 000011
Twelfth edition (August 2000)
This edition RISCWatch Debugger User's Guide applies RISCWatch Debugger Version subsequent versions debugger until otherwise indicated versions technical newsletters. following paragraph does apply United Kingdom country where such provisions inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS MANUAL WITHOUT WARRANTY KIND, EITHER EXPRESSED IMPLIED, INCLUDING, LIMITED IMPLIED WARRANTIES MERCHANTABILITY FITNESS PARTICULAR PURPOSE. Some states allow disclaimer express implied warranties certain transactions; therefore, this statement apply you. does warrant that contents this publication accompanying source code examples, whether individually more groups, will meet your requirements that publication accompanying source code examples error-free. This publication could contain technical inaccuracies typographical errors. Changes periodically made information herein; these changes will incorporated editions publication. make improvements and/or changes product(s) and/or program(s) described this publication time. possible that this publication contain references information about, products (machines programs), programming, services that announced your country. Such references information must construed mean that intends announce such products, programming, services your country. reference licensed program this publication intended state imply that only IBM's licensed program. functionally equivalent program instead. part this publication reproduced distributed form means, stored data base retrieval system, without written permission IBM. Requests copies this publication technical information about products should made your Authorized Dealer your Marketing Representative. Forms user's reader's comments provided page xvii page xix, respectively. also address written comments about this publication Corporation Department YM5A P.O. 12195 Research Triangle Park, 27709 distribute whatever information supply believes appropriate without incurring obligation you. ©Copyright International Business Machines Corporation 1997, 2000. rights reserved. Printed United States America. 4321 Notice U.S. Government Users-Documentation Related Restricted Rights -Use, duplication, disclosure subject restrictions forth Schedule Contract with Corporation.
RISCWatch Debugger User's Guide
Patents Trademarks
have patents pending patent applications covering subject matter this publication. furnishing this publication does give license these patents. send license inquiries, writing, Director Licensing, Corporation, Harbor Drive, Stamford, 06904, United States America. following terms trademarks Corporation: AIX/Windows Open PowerPC PowerPC Architecture RISC System/6000 RISCTrace RISCWatch following term registered trademark United States other countries licensed exclusively through X/Open Company Limited: UNIX Windows trademark Microsoft Corporation. Other terms which trademarks property their respective owners.
RISCWatch Debugger User's Guide
Contents
Contents. Figures xiii Tables User's Comments Form. xvii Reader's Comments Form. About This Book.
Should This Book This Book Conventions Used This Book xxii Numeric Notation Input Conventions. xxii Highlighting Conventions. xxii Syntax Diagram Conventions. xxiii Where Find More Information xxiv Related Publications xxiv
Introducing RISCWatch Debugger
Embedded System Software Development Programming Languages Features.
Quick Start
Starting Debugger. Entering Commands Loading Demo Program. Scrolling Through Source Code. Setting Breakpoints. Stepping Through Code. Altering Displaying Variables 2-10 Debugging Assembly Level 2-14
Using RISCWatch Debugger.
Debugger Facilities Environment Resources. Core ASIC Resources Processors, Cores Chip Resources Processor Configuration File (PCF) 3-10
Contents
File Management File Syntax REFER Definitions. MACRO Definitions CHIP Definitions
3-10 3-11 3-11 3-12 3-12
INCLUDE Definitions. 3-14 EXEC Definitions. 3-15 FIELD Definitions 3-16 NAME Definitions 3-16 Definitions 3-16 Definitions. 3-17 REGALIAS Definitions 3-19 REGFLD Definitions. 3-19 Definitions Compiling Example MEMACC Command. 3-20 3-20 3-21 3-23
MEMACC 3-24 Practical Application Example. 3-26 Window Descriptor File 3-28 Multi-Processor Resources. File Syntax. Board Definitions Debugging Context Windows. 3-28 3-28 3-29 3-31 3-31 3-32
Invoking Debugger. 3-33 JTAG Ethernet Targets RISCWatch Processor Probe. 3-35 Main Window Resources Menus File Menu Source Menu Hardware Menu Window Menu Utilities Menu Help Menu Command Line Usage 3-38 3-39 3-41 3-41 3-41 3-42 3-42 3-42 3-42
RISCWatch Debugger User's Guide
Command History Usage 3-42 Message Window 3-43 Running Your Programs Preparing Program Debug Loading Files Loading Boot Boot Image Files Executing Program. Following Program Execution Flow Input Line Usage Source Level Debugging. Source Window Scrolling Source Window Contents Using Keyboard Assembly Debug Window Programs Window Callers Window Files Window Functions Window Load Memory Window. Managing Breakpoints Using Software Breakpoints Using Hardware Breakpoints. Breakpoints Window. Breakpoint Select Window 3-43 3-43 3-44 3-46 3-47 3-47 3-48 3-51 3-51 3-54 3-54 3-58 3-60 3-61 3-62 3-63 3-70 3-71 3-72 3-73 3-75
Open Debugging. 3-66
Reading Writing Program Variables. 3-77 Local Variables Window 3-77 Global Variables Window 3-79 Inspect Variable Windows 3-81 Variable Configuration Window 3-83 Change Variable Window. 3-85 Formatting Examples 3-88 Expansion/Contraction from Locals Globals Window 3-88 Displaying ASCII Strings. 3-90 Handling Multiple Data Elements Referenced Single Pointer 3-91 Changing Multiple Instances Variable Within Array 3-94 Type Casting Variable 3-102 Source Variable Command Support. 3-103 Reading Writing Memory 3-104
Contents
Memory Coherency Window (JTAG Targets Only) ASCII Memory Window Custom Memory Window Cache Windows (JTAG Targets Only)
3-105 3-108 3-110 3-113
Save Memory Window. 3-114 Reading Writing Registers 3-116 Register Windows 3-117 Register Field Windows 3-118 User-Defined Windows File Syntax Keyword Definition/Syntax. Creating Window Example. Command Files. Using Shell Scripts Execute Command Files. Startup Command File Special Command File Commands. Blank Lines Comments Command Files Command File Programming Command File Special Expressions Command File Parameters Command File Pseudo-Variables Command File Programming Example Running Command File Command File Window 3-119 3-120 3-120 3-123 3-123 3-125 3-126 3-126 3-126 3-127 3-127 3-129 3-130 3-131 3-133 3-133 3-135
Processor Resources 3-137 Processor Reset Window (JTAG Targets Only). 3-138 General Resources. Window Layout. Output Window. Window List. Files. Logging Control. Logging User Comments Screen Capture Calculator Window 3-138 3-138 3-139 3-141 3-141 3-142 3-142 3-143 3-143
Online Help 3-145
Using Processor-Specific Debug Features.
viii
RISCWatch Debugger User's Guide
PowerPC 400Series Implementation Notes Managing Hardware Breakpoints Trace Events Using RISCTrace (400Series JTAG Processor Probe Only) RISCTrace Operational Notes RISCTrace Output Trigger/Trace Window (400Series Only)
RISCTrace Controls 4-10 Compound Trigger/Trace Window (401, Series Only) 4-12 Memory Resources. 4-15 Translation Lookaside Buffer Window (Applicable Processors Only) 4-15 Processor Resources. 4-16
Debugger Command Reference.
Processors Currently Supported. Reading Syntax Diagrams Using RISCWatch Debugger Commands. Window Quick Reference Command Quick Reference asmstep 5-12 assign 5-13 assm. 5-15 attach. 5-17 beep 5-18 5-19 5-20 bpmode 5-24 callstep 5-26 capture 5-27 cfss 5-30 color. 5-32 config. 5-34 create 5-35 delay. 5-37 detach. 5-38 dis. 5-39 down. 5-41 5-43 exec. 5-44 expr 5-45
Contents
fctrl 5-47 file. 5-49 find 5-50 findb 5-52 finde 5-54 focus. 5-56 fold 5-57 fprdisp 5-58 fprint 5-59 freeze 5-62 funcdisp. 5-63 goto 5-65 halt 5-66 hidewins 5-67 5-68 jtag 5-69 kill_thread. 5-70 line. 5-71 linestep. 5-72 load 5-73 5-77 logging. 5-78 logoff 5-80 memacc. 5-81 memchk. 5-84 memcoh 5-85 memcopy. 5-87 memfill. 5-88 memfind 5-89 memrwait. 5-91 memwwait 5-92 mpsset. 5-93 pagedn 5-94 pageup 5-95 parms 5-96 poll. 5-98 post 5-100 prefer. 5-101
RISCWatch Debugger User's Guide
print quit. read reset restart retstep save. set. showip socket srcdisp srchpath. srcline start_thread stop. stuff. timer trace unassign uncreate unload. varinfo. varvis view window write.
5-105 5-106 5-107 5-109 5-110 5-111 5-112 5-113 5-115 5-117 5-122 5-123 5-124 5-125 5-126 5-128 5-129 5-130 5-131 5-133 5-134 5-135 5-137 5-139 5-140 5-141 5-143 5-145 5-147 5-148 5-150
Interfacing RISCWatch Target Board.
IEEE 1149.1 (JTAG) Port. Trace Status Port (400Series JTAG Processor Probe Only) JTAG Trace Connector Requirements. Target Monitor Debugging
Register Definition File (Outdated)
Register Definition File
Contents
File Syntax Register Definitions Register Definitions. MMIO Register Definitions ALIAS Definitions Register Field Definitions
Index
RISCWatch Debugger User's Guide
Figures
Figure 2-1. Sample Main Window. Figure 2-2. Sample Files Window Figure 2-3. Sample Source Window Figure 2-4. Sample Breakpoints Window. Figure 2-5. Sample Functions Window Figure 2-6. Sample Callers Window Figure 2-7. Sample Locals Window 2-10 Figure 2-8. Sample Variable Configuration Window 2-11 Figure 2-9. Change Display Information 2-12 Figure 2-10. Change Base Variable. 2-13 Figure 2-11. Sample Assembly Debug Window 2-15 Figure 3-1. Sample Main Window. 3-38 Figure 3-2. Main Window Menu Options. 3-40 Figure 3-3. Sample Input Line Displayed. 3-49 Figure 3-4. Sample Source Window 3-51 Figure 3-5. Sample Assembly Debug Window 3-55 Figure 3-6. Sample Programs Window 3-58 Figure 3-7. Sample Callers Window 3-60 Figure 3-8. Sample Files Window 3-61 Figure 3-9. Sample Functions Window 3-62 Figure 3-10. Load Memory. 3-64 Figure 3-11. Sample Open Window. 3-66 Figure 3-12. Sample Breakpoints Window. 3-73 Figure 3-13. Sample Breakpoint Select Window 3-76 Figure 3-14. Sample Locals Window 3-77 Figure 3-15. Sample Globals Window 3-80 Figure 3-16. Sample Inspect Window 3-82 Figure 3-17. Sample Variable Configuration Window 3-83 Figure 3-18. Change Variable Window 3-85 Figure 3-19. Sample Unexpanded Structure Variable 3-88 Figure 3-20. Sample Expanded Structure Variable 3-88 Figure 3-21. Further Structure Variable Expansion 3-89 Figure 3-22. Single-Element Structure Variable Expansion. 3-89 Figure 3-23. Structure Variable Contraction 3-90 Figure 3-24. Sample Pointer Variable. 3-90 Figure 3-25. Sample ASCII String Display. 3-90 Figure 3-26. Sample Character Array 3-91 Figure 3-27. Sample Array Element Display. 3-91 Figure 3-28. Sample struct record Pointer Display 3-92 Figure 3-29. Sample Initial struct record Pointer Expansion. 3-92 Figure 3-30. Changing Pointer Variables. 3-93
Figures
xiii
Figure 3-31. Sample Pointer Variable Shown Array 3-93 Figure 3-32. Sample Expanded Pointer Variable Shown Array 3-94 Figure 3-33. Sample char Array Display 3-95 Figure 3-34. Changing Multiple Elements Variable Array. 3-96 Figure 3-35. Updated Display Variable Array 3-97 Figure 3-36. Sample Multi-Element, Multilevel Variable Display 3-98 Figure 3-37. Updated Multi-Element, Multilevel Variable Display. 3-99 Figure 3-38. Sample Change Value Display. 3-100 Figure 3-39. Sample Result Change Value Update. 3-101 Figure 3-40. Sample Variable Type Cast. 3-102 Figure 3-41. Sample Memory Access Window. 3-105 Figure 3-42. Sample ASCII Memory Window 3-108 Figure 3-43. Custom Memory Window 3-110 Figure 3-44. Sample Data Cache Window 3-113 Figure 3-45. Save Memory 3-115 Figure 3-46. Sample Register Window 3-117 Figure 3-47. Sample Register Field Window 3-118 Figure 3-48. Sample User-Defined Window 3-125 Figure 3-49. Sample Command File Window 3-135 Figure 3-50. Sample Processor Reset Window. 3-138 Figure 3-51. Sample Output Window. 3-139 Figure 3-52. Sample Comment Window. 3-142 Figure 3-53. Sample Calculator Window 3-143 Figure 4-1. Sample Trace Output File Figure 4-2. Sample Trigger/Trace Window with Trace Supported. Figure 4-3. Sample Compound Trigger/Trace Window with Trace Supported 4-13 Figure 4-4. Sample Window. 4-15 Figure A-1. JTAG Header Connector (top view). Figure A-2. RISCTrace Header (top view). Figure A-1. RISCTrace RISCWatch Headers
RISCWatch Debugger User's Guide
Tables
Table 3-1. Quick Reference RISCWatch Debugger Table 3-2. Input Line Functions 3-48 Table 3-3. Keyboard Options Scrolling 3-54 Table 4-1. Quick Reference Processor-Specific Debug Features Table 5-1. Syntax Summary Debugger Commands Table 5-2. Windows that support capture total 5-29 Table A-1. PowerPC 400Series JTAG Interface Connections Resistors. Table A-2. PowerPC 6xx/7xx JTAG Interface Connections Resistors. Table A-3. RISCTrace Header Description. Table A-1. Mictor Connector Signal Assignments
Tables
RISCWatch Debugger User's Guide
User's Comments Form
hope delighted with this product, only tell Your comments suggestions will help improve products. Please take minutes know what think completing this form. wish this form, please send following number care 'PowerPC Embedded Tools Software Feedback': FAX: (919) 543-7575 wish send your comments softcopy, please send following Internet address: INTERNET: ppcsupp@us.ibm.com also contact page: INTERNET: Please indicate which product commenting marking appropriate box:
Open Real-Time Operating System
PowerPC Evaluation Board High C/C++ Compiler
RISCWatch Debugger
order properly process your information, please also include version number product indicated above. Version: Please check appropriate boxes below, describe your host, target application:
Host Platform
RS/6000 (Win95/98/NT) 401_ 403_ 604e
(Solaris)
405_ 740/750
Target Processor
603e/ev 750cx
Other:_ Other Evaluation Board (please specify):
Target Platform Target Application
Evaluation Board
Other Platform:_ Monitor Open Monitor
Other:_
User's Comments Form
xvii
Interface Used
JTAG (via Parallel Port) Ethernet
JTAG (via Ethernet)
Please rate characteristics product scale being best):
ease installation ease amount function provided level which helped your reliability (frequency failure) performance error messages problem support service price, considering value received
What your overall impression product?
overall
Please include additional comments below. PLEASE SPECIFIC POSSIBLE. Please tell improve this product: Please tell what especially liked about product: Thank your response. When send information IBM, grant right distribute information without incurring obligation you. course retain right information choose. Please provide following information should necessary contact reason order properly address your input: Name: Company: Phone: Internet Address:
xviii
RISCWatch Debugger User's Guide
Reader's Comments Form
hope find this publication useful, readable technically accurate, only tell Your comments suggestions will help improve technical publications. Please take minutes know what think completing this form. wish this form, please send following number care 'PowerPC Embedded Tools Software Feedback': FAX: (919) 543-7575 wish send your comments softcopy, please send following Internet address: INTERNET: ppcsupp@us.ibm.com also contact page: INTERNET: Please indicate which publication commenting marking appropriate box:
High C/C++ Language Reference High C/C++ Compiler, Linker Assembler Open User's Guide Open Programmer's Reference Volume Open Programmer's Reference Volume PowerPC Evaluation Board User's Guide RISCWatch Debugger User's Guide
order properly process your information, please also include edition number date book indicated above back title page, top).
Edition Date:
Please rate characteristics book scale being best).
accurate complete well laid well organized easy understand
Reader's Comments Form
applies your tasks enough examples
What your overall impression book?
overall
additional comments, either attach marked-up hardcopy applicable) include your comments below. PLEASE SPECIFIC POSSIBLE INCLUDE PAGE NUMBER SECTION PUBLICATION WHERE HAVE COMMENT. Specific Comments Problems: Please tell improve this book: Please tell what especially liked about book: Thank your response. When send information IBM, grant right distribute information without incurring obligation you. course retain right information choose. Please provide following information should necessary contact reason order properly address your input: Name: Company: Phone: Internet Address:
RISCWatch Debugger User's Guide
About This Book
This book describes IBM® RISCWatchDebugger, windowing environment, debugging facilities commands. This publication contains information needed RISCWatch, hardware software development tool PowerPCprocessors. RISCWatch Debugger supports numerous PowerPC processors versions. more information current processors supported other date information, please refer README file included with product, visit site Support additional PowerPC processors targets planned future RISCWatch releases.
Should This Book
This book for:
Programmers engineers will RISCWatch Debugger develop
embedded applications using PowerPC processors Users should understand:
Functions, architecture, features their host systems PowerPC instruction architecture assembler programming programming
information concerning features operations specific PowerPC processor, please refer document each individual device.
This Book
This manual describes RISCWatch debugger facilities, windows, functions provided specifically support PowerPC processors embedded applications. This book divided into following chapters:
Chapter "Introducing RISCWatch Debugger," describes RISCWatch
debugger functions features.
Chapter "Quick Start," introduces RISCWatch Debugger means
brief demo with descriptions main windows debugger functions.
About This Book
Chapter "Using RISCWatch Debugger," shows debugging tasks
relation sample debugger windows some specific features debugger.
Chapter "Using Processor-Specific Debug Features," describes RISCWatch
features windows applicable specific PowerPC processors.
Chapter "Debugger Command Reference," provides detailed descriptions
debugger commands.
Appendix "Interfacing RISCWatch Target Board," describes required
connections interfacing RISCWatch PowerPC processor target development board.
Appendix "Register Definition File (Outdate)," describes file format
Register Definition File (RDF) which used custom register definitions RISCWatch debugger. detailed information about installing configuring RISCWatch Debugger, consult accompanying RISCWatch Debugger Installation Guide.
Conventions Used This Book
This book follows numeric highlighting notation conventions based those used RISC System/6000and Advanced Interactive Executive (AIXTM) publications.
Numeric Notation Input Conventions
general, numbers used exactly shown. Unless noted otherwise, numbers decimal, and, entered part command, entered without format information. hexadecimal digits through typically appear uppercase. Hexadecimal numbers preceded "0x" shown below: 0x1A7
Highlighting Conventions
code examples, this book uses highlighting. This book uses following highlighting conventions:
names invariant objects known RISCWatch appear bold type.
some text, however, such lists, special typographic treatment used. Examples such objects include:
File command names Data types structures
xxii
RISCWatch Debugger User's Guide
Constants flags Variable names that supplied user programs appear italic type.
some text, however, such lists, special typographic treatment used. Examples these objects include arguments other parameters. Names objects keywords known RISCWatch Debugger must entered exactly written.
Syntax Diagram Conventions
Throughout this book, diagrams illustrate syntax string formats commands. following list shows read these diagrams:
Read syntax diagrams from left right, from bottom, following
path line.
symbol begins diagram. symbol indicates continuation diagram next line. symbol indicates continuation diagram from previous line. symbol terminates diagram.
Keywords regular type, variables italics. Keywords must
typed exactly shown.
Keywords variables main path diagram required.
keyword
variable1
variable2
Keywords variables shown branches below main path optional.
keyword
variable1
variable2
Keywords variables appear stack, indicating that only item
stack chosen. item stack main path, must choose item from stack. items stack below main path, choose item from stack. example, following syntax diagram, must choose either variable1 variable2. However, because variable3 variable4 below main path, neither required.
keyword
variable1 variable2 variable3 variable4
About This Book
xxiii
repeat separator returning arrow that surrounds syntax element
group shows that element group repeated.
variable1
keyword
Where Find More Information
following sections list sources information about related RISCWatch.
Related Publications
This book refers following publications, which available from your Microelectronics representative:
RISC System/6000 Publications
RISC System/6000: POWERstation POWERserver Hardware Technical Information General Architectures, SA23-2643
Publications
This book refers following publications. words "IBM Version RISC System/6000" actually part title each book; however, references these books, those words omitted.
Assembler Language Reference, SC23-2642 Commands Reference, Volume SC23-2537 Commands Reference, Volume SC23-2538 Commands Reference, Volume SC23-2539 Commands Reference, Volume SC23-2540 Commands Reference, Volume SC23-2639 Commands Reference, Volume SC23-2640 Editing Concepts Procedures, GC23-2212 Files Reference, GC23-2200
Compiler/6000 Publications
Language Reference, SC09-1260 User's Guide, SC09-1259
High C/C++ Publications
xxiv
RISCWatch Debugger User's Guide
following list includes books High C/C++ library:
High C/C++ Programmer's Guide PowerPC, 92G6920 High C/C++ Language Reference PowerPC, 92G6923 Assembler User's Guide PowerPC, 92G6921 Linker User's Guide PowerPC, 92G6922 PowerPC Embedded Application Binary Interface
copy EABI specification found RISCWatch page
PowerPC Embedded Solutions
PowerPC Embedded Processor Solutions, SC09-3032-00
Open Publications
following list includes books Open library:
Open Programmer's Reference, Volume 92G6911 Open Programmer's Reference, Volume 92G6912 Open User's Guide, 92G6897
PowerPC 400Series User's Manuals
PPC403GA Embedded Controller User's Manual, 13H6960
PowerPC Evaluation Board User's Manual, 13H6987
PPC403GB Embedded Controller User's Manual, 13H6985 PPC403GC Embedded Controller User's Manual, 13H6986
PowerPC User's Manuals
PowerPC RISC Microprocessor User's Manual, SC22-9899-00 PowerPC Evaluation Board User's Manual, 92G8620 PowerPC RISC Microprocessor User's Manual, MPR603UMU-01 PowerPC 603e RISC Microprocessor User's Manual, MPR603EUM-01 PowerPC RISC Microprocessor User's Manual, MPR604UMU-01 PowerPC Evaluation Board User's Manual, 92G8622
PowerPC
PowerPC Microprocessor Family: Programming Environments, MPRPPCFPE-01
About This Book
xxvi
RISCWatch Debugger User's Guide
Chapter Introducing RISCWatch Debugger
RISCWatch Debugger provides powerful, flexible debugging environment support hardware software development using PowerPC processors embedded applications.
Embedded System Software Development
Embedded systems typically developed cross-development environment consisting host computers target systems. host computers provide software project management tools embedded system application developers. developers restricted limited computing resources typically available target embedded system. Developers write, compile, debug embedded application programs host computers. When appropriate, application programs loaded target embedded system, where they tested target operating environment. Embedded system development iterative process; application programs refined host computers tested target system until programs meet functional performance requirements application. Eventually, application programs shipped part embedded system.
Programming Languages
Application programs PowerPC processors typically written C/C++ assembler. Formats currently supported include ELF/DWARF (SVR4 PowerPC Embedded ABI) XCOFF/STABS.
Features
RISCWatch development debug tool PowerPC processors. RISCWatch employs graphical user interface allowing complete access PowerPC processor functions. Following list RISCWatch features:
Robust source program debug capability Low-level hardware program debug (assembly level) Read, modify write processor registers Read, modify write processor register fields
Introducing RISCWatch Debugger
User defined registers (DCR, SPR, Memory mapped) Read, modify write processor memory (single, multi-byte access)
with memory fill write verification testing
Memory loading many types file formats (ELF, XCOFF, Motorola 32-bit,
straight binary)
Save/load processor memory image to/from file Save/load processor register values to/from file Command file execution, including nesting capabilities Command file execution with user-created variables, programming
constructs, expressions printf-like function
Command file single-step execution Batch mode command file execution Program assembler disassembler allowing memory read write
capability
Single-step execution (assembly source level) loaded programs Set/clear multiple-event breakpoints Saving loading customized window layout User-defined windows consisting register, register field, memory,
disassembly, command execution status interfaces
Processor reset functions Logging commands messages File browsing Operating System command execution capability On-line help screens including extensive processor register definitions Multiprocessor support with User-defined board configurations Resizable windows with configurable user interface control colors User-defined Core+ASIC interface customized chip support RISCTrace interface PowerPC 400Series real-time trace debug
RISCWatch Debugger User's Guide
Chapter Quick Start
Included with RISCWatch debugger some example files that used quickly demonstrate some capabilities tool. They include source, object, executable files necessary proceed with following tutorial. sections designed performed sequentially, actions described each applied various stages debug session. general, windows descriptions will appear exactly stated text. However, there slight differences what pictured versus what user will actually when running through demonstration. example, program loaded location other than that specified load command, addresses shown window might match what appears document. However, functions performed equivalent.
Starting Debugger
Figure 2-1. Sample Main Window
Main Window, illustrated figure 2.1, first window seen when RISCWatch started. Perform following steps display this window:
Quick Start
Edit "rwppc.env" file designate "target processor", "target type", "target name", RISCWatch directory, described "Environment Resources" page "Invoking Debugger" page 3-33. Edit additional environment resources required your specific setup. From RISC System/6000 workstation running Motif, change installation directory, type "rwppc". From running Windows, double-click RISCWatch icon created during program installation.
Entering Commands
enter debugger commands from command line Main window, single-click Command area give `focus', type desired command, then press "Enter". "Command Quick Reference" page complete list valid commands. demonstration program, enter command "srchpath xxxx", where xxxx fully qualified directory path where examples reside. Note that when command entered, displayed command history window. also displayed, along with associated messages, below command line message window.
Loading Demo Program
Enter from command line: load file demo t=0x35000 d=0x37000
Note: address 0x35000 will work most Monitor targets. Refer Eval User's Guide (section 7.5) instructions valid address determined Monitor targets.
RISCWatch Debugger User's Guide
Scrolling Through Source Code
Figure 2-2. Sample Files Window
that program been loaded, next step bring source files. Move cursor "Source" menu entry Main screen single click left mouse button. Then, single click "Files" choice. Figure shows sample Files display. Move cursor "Source" menu entry Main screen single click left mouse button. Then, single click "Source" choice. Source window should displayed. Single-click left mouse button "demo1.c" entry Files window. will become highlighted, following will appear Source Window:
Quick Start
Figure 2-3. Sample Source Window
Move cursor Main window, single-click left mouse button Command area enable command line. Enter "pagedn source" command line. source window will scroll down page. Enter "pageup" command line. source window will scroll page. Notice that "source" wasn't specified this time because last command stored subsequent commands use. Move cursor back Source window, place cursor down arrow found scroll area right side window. Hold down left mouse button. source code will scroll down line time while button being held down. scroll will also move down along right side screen. Move cursor area above scroll bar, placing between arrow. Press left mouse button once. This will move source code page.
RISCWatch Debugger User's Guide
Move cursor scroll itself. Hold down left mouse button move mouse down. source code will scroll down with movement mouse. Move cursor back Main window, single-click left mouse button Command area enable command line. Enter "top" command line. Source window will scroll source file.
Setting Breakpoints
Move cursor back Source window, scroll down through code until line view. Single-click left mouse button, Source window left side which shows line numbers, line entry. "BP" indicator will appear next line number This means breakpoint been set. Move cursor "Source" menu entry Main screen single-click left mouse button. Then, single-click "Breakpoints" option. Figure shows display.
Figure 2-4. Sample Breakpoints Window
Quick Start
Various information about breakpoint displayed Breakpoints window, including type (hardware software), address, function name, source file, line number corresponding breakpoint. Move cursor button over entry Breakpoints window single-click left mouse button. entry highlighted, corresponding location Source window highlighted. Delete button also enabled. Single-click left mouse button again entry. highlight removed, Delete button disabled. Move cursor "Source" menu entry Main screen single click left mouse button. Then, single click left mouse button "Functions" option. Figure shows display.
Figure 2-5. Sample Functions Window
Locate entry "routine2; demo2.c". Move cursor this entry, single-click left mouse button. source file containing routine2 (demo2.c) will shown Source window, entry will highlighted Functions window. Double-click left mouse button Functions widow line corresponding "routine2; demo2.c" function entry. This will breakpoint
RISCWatch Debugger User's Guide
beginning routine2 function. "BP" indicator will appear Source window first executable line function. Information about breakpoint will also appear Breakpoints window. Move cursor newly added routine2 entry Breakpoints window. Double-click left mouse button entry. breakpoint removed from Breakpoints, Functions, Source windows.
Stepping Through Code
Move cursor "Run" button Source window, single-click left mouse button. program "run" until hits breakpoint earlier this example. source file corresponding breakpoint location that stopped program execution displayed Source window. source line corresponding current Instruction Pointer address indicated ">>" next line number where program stopped. Press "Show button Source window. Information relating current Instruction Pointer listed Main window status message area. Press "Line step" button Source window. ">>" appears next source line, which highlighted. Move cursor source line over source line "routine4();" single-click left mouse button. indicator appears next line, breakpoint entry entered Breakpoints window. Press "Run" button once more, program runs break just set. ">>" appears next line number which highlighted.
Quick Start
Move cursor "Source" menu entry Main screen single click left mouse button. Then, single click left mouse button "Callers" option. Figure shows display.
Figure 2-6. Sample Callers Window
information contained Callers window essentially "push down" stack that contains information about current call stack. Press "Line step" button Source window. ">>" appears next source line, which highlighted. Notice program step into routine4() function. Line step command essentially steps over function calls. press "Call step" button Source window. This command causes debugger enter context called function. file containing routine2() function displayed Source window. first executable source line highlighted, ">>" indicator shows source line corresponding current instruction pointer. Callers window also updated reflect current debugger context. Press "Line step" button Source window times. ">>" will next source line "routine3():", line number press "Call step" button Source window. file containing routine3() function displayed Source window. first executable source line highlighted, ">>" indicator shows source line corresponding current instruction pointer. Callers window again updated reflect current debugger context, routine3. Single-click "routine2" entry Callers window. context switched back function that made call, namely routine2(), with Source window being updated show file line where function call made. Callers window used this manner traverse call stack.
RISCWatch Debugger User's Guide
Press "Show button Source window. current information again displayed message area Main window. Source window also returned current context, which function listed Callers window. Press "Ret step" button Source window. This returns debugger context calling function. Notice that Callers window also updated stack entry "popped" from current call stack. Press "Ret step" button again, debugger traverses stack again, returning original caller main(). press "Restart" button Source window. program essentially reloaded, instruction pointer reset entry point program. Notice breakpoints that have been saved messages that appear Main window. entry point this example startup code that source files associated with Thus debugger displays messages that indicate unable display code Source window. Press "Run" button. Since breaks still set, program stops again breakpoint line demo1.c.
Quick Start
Altering Displaying Variables
Move cursor "Source" menu entry Main screen single click left mouse button. Then, single click left mouse button "Locals" option. Figure shows display.
Figure 2-7. Sample Locals Window
This window lists defined local variables current debugger context, their current values. window contents custom tailored variety ways. Refer "Variable Configuration Window" page 3-83 complete description available options. Only will shown this example. Press "Var. Config" (Variable Configuration)" button Locals window. Figure shows window that will displayed. Press "Address" button Display info. area. Single-click variable shown Visible area. This moves variable Visible area, meaning variable will longer shown. This used reduce clutter uninteresting variables also reduce number variable values requiring refresh when debugger context changes.
2-10
RISCWatch Debugger User's Guide
Figure 2-8. Sample Variable Configuration Window
Press "OK" button Variable Configuration window. This applies changes removes window. Notice variable longer shown, that addresses variables displayed. Individual variables also custom tailored. Single-click "show_out" variable Locals window. Figure shows display.
Quick Start
2-11
Figure 2-9. Change Display Information
"Address" button Display info. field selected because previous Variable Configuration window update. Press button again deselect "Address" button. Press "OK" button apply change remove window. Notice Locals window display longer shows address show_out variable. Move cursor again show_out variable double-click left mouse button. Notice that variable "expanded" show another level detail structure. Double-click show_out variable again show even more detail. Move cursor down three lines ".name:" variable name, double-click Notice that just that variable gets expanded even further. Single-click ".name:" variable. Notice Change Array Variable window that subrange shown tailored. Change "0,2" "2,6" then press "OK". only array elements shown Locals window ".name:" array.
2-12
RISCWatch Debugger User's Guide
Single-click next ".count:" variable. Figure 2-10 shows display.
Figure 2-10. Change Base Variable
Press "Hexadecimal" button Value format field. Enter Change value field, press "OK". Notice that display ".count:" variable hex, reflects decimal value just entered. Single-click "r1var:" variable, change Value format "Hexadecimal" well. Press "OK" button change variable.
Quick Start
2-13
Press "Line step" button Source window. Notice variables updated since moved invisible earlier. Press "Line step" button again. Notice that variable "show_out.show_in.count" updated Locals window source line executed. Globals window operates same manner Locals, contains variables defined global program.
Debugging Assembly Level
Assembly level debug accomplished several ways. source disassembly Source window. Another actual memory disassembly found Assembly Debug window. Press "Delete All" button Breakpoints window. Notice that breakpoints cleared both Source Breakpoints windows. Single-click source code line Source window breakpoint. that breakpoint pressing "Run" button Source window. Press "Call step" button Source window. Notice that source file associated with called function, routine5, shown Source window. addition, some buttons have been disabled, some warning messages have been posted Main window. Also, local variable information available. This result stepping into function that compiled with debug information-a prime example might desirable assembly level debug with source level debugger. Notice also that warning message presents opportunity return immediately calling function case Call step issued inadvertent, user decides step through assembly code. since still reading this, we'll have assume hard core user want move Move cursor back Main window "Hardware" menu entry single-click left mouse button. Then, single-click "Asm Debug" option. Figure 2-11 shows display.
2-14
RISCWatch Debugger User's Guide
Figure 2-11. Sample Assembly Debug Window
This contains memory disassembly number instructions, beginning with corresponding current instruction pointer. Press "Asmstep" button Assembly Debug window. Notice current instruction indicator moved next assembly instruction. Also notice that "Return step" button Source window been disabled. This debugger's politely saying that your chance return easily previous warning message, chose you're your getting back! This done either pressing "Asmstep" button until return made, going back source line calling function setting break after line running We'll former since this function only instructions. Press "Asmstep" button until return made calling function. Source window updated show source file containing original call. Notice that current instruction pointer still pointing line number containing call.
Quick Start
2-15
source disassembly feature used show this case. Press "Source/Asm" button Source Mode area Source window. This produces mixed source disassembly listing window. Notice that there more than assembly instruction associated with each source line. example, returned from function call, we're still same source line call itself. Breakpoints also while mixed mode. Move cursor "cror 31,31,31" instruction below routine2() source line single-click Notice that breakpoint indicated Source, Assembly Debug, Breakpoints windows. Press "Run" button Source window. Notice that current instruction pointer updated breakpoint address both Source Assembly Debug windows. Press "Source only" button Display mode area Source window. Notice that break still shown source line corresponding assembly line which breakpoint set. Numerous other screens also useful when doing assembly level debug. Please refer Table 3-1, "Quick Reference RISCWatch Debugger" page 3-2, list available windows.
2-16
RISCWatch Debugger User's Guide
Chapter Using RISCWatch Debugger
RISCWatch designed several configurations:
Normal mode
user interacts with graphical user interface. This mode which RISCWatch usually run.
Command file batch mode
RISCWatch runs commands contained ASCII file. shell script can, example, invoke RISCWatch several times with several command files. graphical user interface available this mode. "Running Command File" page 3-133 more details RISCWatch this mode.
mode (non-PC host only)
This mode allows RISCWatch UNIX (RISC System/6000) workstation which does have graphical user interface windowing system available. This mode provides command line interface where commands typed after prompt resulting execution messages printed terminal. This mode invoked starting RISCWatch with -tty command line option. Target types currently supported RISCWatch described "Environment Resources" page 3-5.
Debugger Facilities
RISCWatch Debugger many facilities that used develop, test, debug your evaluation board code programs. find necessary perform certain tasks, this section used quick lookup facilities that might used accomplish those tasks. Table below provides quick reference RISCWatch resources, both this chapter general debug features next chapter processor-specific debug features.
Using RISCWatch Debugger
Table 3-1. Quick Reference RISCWatch Debugger Task Resource Setting Environment initialize environment resources, register definition files, multi-processor files Invoking Debugger bring RISCWatch Main Window Main Window Resources Overview menus windows Applicable Sections "Environment Resources" page "Core ASIC Resources" page "Multi-Processor Resources" page 3-28 "Invoking Debugger" page 3-33 "JTAG Ethernet Targets RISCWatch Processor Probe" page 3-35 "Main Window Resources" page 3-38 "Menus" page 3-39 "Command Line Usage" page 3-42 "Command History Usage" page 3-42 "Message Window" page 3-43 "Preparing Program Debug" page 3-43 "Loading Files" page 3-44 "Loading Boot Boot Image Files" page 3-46 "Executing Program" page 3-47 "Following Program Execution Flow" page 3-47 "Input Line Usage" page 3-48 "Scrolling Source Window Contents Using Keyboard" page 3-54 "Source Window" page 3-51 "Assembly Debug Window" page 3-54 "Programs Window" page 3-58 "Callers Window" page 3-60 "Files Window" page 3-61 "Functions Window" page 3-62 "Load Memory Window" page 3-63 Open Debugging" page 3-66
Running Your Programs compile, load, execute programs
Source Level Debugging interface debug your source code
Open Debugging interface display operating system information control debug attachment
RISCWatch Debugger User's Guide
Table 3-1. Quick Reference RISCWatch Debugger Task Resource Managing Breakpoints interface command hardware software breakpoints Applicable Sections "Managing Breakpoints" page 3-70 "Using Software Breakpoints" page 3-71 "Using Hardware Breakpoints" page 3-72 "Breakpoints Window" page 3-73 "Breakpoint Select Window" page 3-75 "Trigger/Trace Window (400Series Only)" page "Compound Trigger/Trace Window (401, Series Only)" page 4-12 "Reading Writing Program Variables" page 3-77 "Local Variables Window" page 3-77 "Global Variables Window" page 3-79 "Inspect Variable Windows" page 3-81 "Variable Configuration Window" page 3-83 "Change Variable Window" page 3-85 "Formatting Examples" page 3-88 "Source Variable Command Support" page 3-103 "Reading Writing Memory" page 3-104 "Assembly Debug Window" page 3-54 "Memory Coherency Window (JTAG Targets Only)" page 3-105 "ASCII Memory Window" page 3-108 "Custom Memory Window" page 3-110 "Cache Windows (JTAG Targets Only)" page 3-113 "Translation Lookaside Buffer Window (Applicable Processors Only)" page 4-15 "Load Memory Window" page 3-63 "Save Memory Window" page 3-114 "Reading Writing Registers" page 3-116 "Register Windows" page 3-117 "Register Field Windows" page 3-118
Reading Writing Program Variables interface read, modify, write program variables
Reading Writing Memory interface command read, modify, write processor memory many different formats
Reading Writing Registers interface command read, modify, write processor registers register fields
Using RISCWatch Debugger
Table 3-1. Quick Reference RISCWatch Debugger Task Resource User-Defined Windows create customized windows Applicable Sections "User-Defined windows allow RISCWatch user create windows containing customizable register, register field, memory, disassembly, button entries. Using simple syntax, ASCII files created define contents user-defined window." page 3-119 "Command Files" page 3-125 "Command File Programming" page 3-127 "Command File Special Expressions" page 3-129 "Command File Parameters" page 3-130 "Command File Pseudo-Variables" page 3-131 "Running Command File" page 3-133 "Command File Programming Example" page 3-133 "Running Command File" page 3-133 "Command File Window" page 3-135 "Processor Resources" page 3-137 "Processor Reset Window (JTAG Targets Only)" page 3-138 "Window Layout" page 3-138 "Output Window" page 3-139 "Window List" page 3-141 "Log Files" page 3-141 "Logging Control" page 3-142 "Logging User Comments" page 3-142 "Screen Capture" page 3-143 "Calculator Window" page 3-143 "Online Help" page 3-145 "Using RISCTrace (400Series JTAG Processor Probe Only)" page
Command Files create command files which used perform repetitious tasks help automate testing
Processor Resources interface perform processor resets read processor status General Resources various program resources
RISCTrace Describes using RISCTrace trace capabilities 400Series processors
prove helpful glance through each sections listed Table gain overall picture available facilities that RISCWatch offers. Such understanding help avoid doing something "the hard way."
RISCWatch Debugger User's Guide
Environment Resources
RISCWatch employs environment resources file specify configure various resources. This file, rwppc.env, designed allow RISCWatch user tailor program operation meet specific operating preferences. This file should examined changed where necessary, before RISCWatch ensure that environment will conform your debugging needs. What follows list environment resources that used rwppc.env file their functionality: Environment variable Description PROC Specifies target processor name non-MPS RISCWatch debug sessions (required). README file provided with RISCWatch list valid processor names. Specifies revision number target processor. This field required when debugging 6xx/7xx processor which RISCWatch supports more than revision number. example, debugging 603e processor, "REV must designated. jtag_par, jtag_par1, jtag_par2, jtag_par3, jtag_eth, rom_mon, osopen (one required) Refer README file which came with RISCWatch information concerning host target requirements proper RISCWatch operation. Each target type described below. JTAG parallel port target. RISCWatch connected JTAG port, PowerPC 400Series target system, through RISCWatch parallel port adapter. suffix (1,2, used specify specific parallel port address hosts uses 0x3BC, uses 0x378, uses 0x0278). optional suffix should only used default address (designated jtag_par) does determine correct address JTAG Ethernet target. RISCWatch connected Ethernet RISCWatch processor probe. JTAG connector processor probe then connected JTAG port PowerPC 400Series PowerPC 6xx/7xx target system.
TARGET_TYPE
jtag_par<1,2,3>
jtag_eth
Using RISCWatch Debugger
rom_mon
monitor target. RISCWatch connected Ethernet SLIP PowerPC target system running Monitor PowerPC debug mode. Open target. RISCWatch connected Ethernet SLIP PowerPC target system running IBM's Open real-time operating system. Name target found TCP/IP services file (required JTAG Ethernet, Open Monitor targets) TCP/IP dotted address also used. fully qualified path name directory which RISCWatch executable support files reside. This required targets. Path names used source/object/command file search, delimited colons (:); host, delimiter semicolon instead colon. specified, default current directory) fully qualified path name directory where RISCWatch maintain files. Indicates number stack frames show Callers Window. designated, default setting twelve. Save/load window layout when ending/beginning session. "SAVE" will save layout exit. "LOAD" will load layout when starting. "LOADSAVE" omitting variable altogether) will both. "NONE" will neither. Allows renaming applprog executable Open target only) Specifies font size main window text command history message windows. This size should Specifies color background control areas (non-MPS) Specifies color foreground control areas (non-MPS) Specifies color background text areas (non-MPS) Specifies color foreground text areas (non-MPS) Specifies color background window areas (non-MPS) Specifies color foreground window areas (non-MPS)
os_open
TARGET_NAME
RWPPC_DIR
SEARCH_PATH
LOG_FILE_DIR STACK_FRAMES
LAYOUT
APPLPROG_NAME FONT_SIZE
COLOR_CTRL_BG COLOR_CTRL_FG COLOR_TEXT_BG COLOR_TEXT_FG COLOR_WIN_BG COLOR_WIN_FG
RISCWatch Debugger User's Guide
MPS_FILE
Specifies file containing multiprocessor support configuration options. "Multi-Processor Resources" page 3-28 Specifies single file containing user defined registers, register fields chips. "Core ASIC Resources" page additional information Specifies file containing user defined register register fields been replaced PRD_FILE environment variable. "Core ASIC Resources" page Specifies command file which will each time RISCWatch started. See"Command Files" page 3-125. Specifies firmware loading sequence JTAG ethernet targets. When RISCWatch first invoked, time stamp comparison made between preloaded Processor Probe firmware firmware files (drivers) provided with RISCWatch. time stamps match, RISCWatch firmware files loaded. This default operation RISCWatch PROBE_FLASH designated environment file. Processor Probe will loaded with RISCWatch firmware files. firmware file time stamp checks ignored. Warning: user assumes responsibility guaranteeing that firmware loaded Processor Probe compatible with target processor version RISCWatch being used. Processor Probe will loaded with firmware files provided with RISCWatch. firmware file time stamp checks ignored. RISCWatch initialization time will extended load both generic processor specific driver files. Specifies more RISCWatch commands executed prior starting trace. more than command needed, each additional command must preceded semicolon (i.e. TRACE_ENABLE write 22;set gpio 15). This optional variable only applicable PowerPC 400Series Core+ASIC JTAG targets, where unique register memory initialization required enable trace feature. designated commands will executed during
PRD_FILE
REG_FILE
STARTUP_FILE
PROBE_FLASH AUTO
TRACE_ENABLE
Using RISCWatch Debugger
processing trace command, which called from RISCWatch Trigger Compound Trigger windows. Please note that exec command valid TRACE _ENABLE designation. TRACE_DISABLE Specifies more RISCWatch commands executed immediately following first stop request after trace run. more than command needed, each additional command must preceded semicolon (i.e. TRACE_DISABLE write 22;set gpio 15;memacc clear). This optional variable only applicable PowerPC 400Series Core+ASIC JTAG targets, where unique register memory initialization required disable trace feature. designated commands will executed during processing trace command, which called from RISCWatch Trigger Compound Trigger windows. Please note that exec command valid TRACE _DISABLE designation. Specifies binary sequence added each JTAG SCAN_IR command. This variable only applicable PowerPC 400Series Core+ASIC JTAG targets. binary sequence indicates number bits added SCAN_IR chain well value needed communicate with core processor. example, `IR_SEG0 100' indicates value three additional bits that connected (TDO) SCAN_IR chain. user assumes responsibility identifying correct binary sequence.
IR_SEG0
File syntax consists placing resource name line, then following with more spaces, equal sign, more spaces then specifying resource value. example: RWPPC_DIR /usr/rwppc enhance readability this file, comment blank lines allowed. comment only start first column does beginning with character. Every time RISCWatch started, attempts locate environment resources file using following rules: Check current directory; relative absolute path given executable, environment file same directory executable.
RISCWatch Debugger User's Guide
Check directory specified environment variable PATH; else Print error message terminate RISCWatch.
Core ASIC Resources
With introduction PowerPC Core growing library chip peripherals, offers high-performance custom processors. Using single PowerPC core, hundreds unique chips developed satisfy specific customer needs. Many basic functions performed debugger (line stepping, memory display, etc.) depend both PowerPC core peripheral resources. RISCWatch allows users define both register organization memory configuration their Core+ASIC environment. following user interfaces provided accomplish this task: Processor Definition File: used define processor ASIC resources that RISCWatch will need access memacc Command: used define correct access size read/write restrictions memory access initiated RISCWatch Window Descriptor File: used create User-Defined RISCWatch windows which used display specified registers, register fields, memory regions.
following sections provide additional details about these Core+ASIC interfaces. Please read sections complete understanding flexibility RISCWatch provides custom chip designs.
Processors, Cores Chip Resources
When RISCWatch first started, Processor Resource Definition (PRD) file read determine debug environment. PROC environment variable, designated environment file (rwppc.env), used index into file completely define unique resources (processor, cores, registers, TLBs, caches, etc.) specified target. default file updated with each version RISCWatch contain latest definitions standard PowerPC chips. With increasing popularity Core ASIC designs, flexible debug solution needed allow debugging non-standard, customer specific PowerPC parts. RISCWatch makes Processor Configuration Files (PCF) provide this solution. These ASCII text formatted files allow users define processor,
Using RISCWatch Debugger
core, chip resources (registers, cache, memory, etc.) needed uniquely define custom design. Users working standard PowerPC parts (403GCX, 603e, etc.) resources defined default RISCWatch file (rwppc.prd) their debugging sessions. This file loaded default totally transparent user. custom Core ASIC solution being used, additional register definitions needed, file will need created compiling more customer supplied Processor Configuration Files.
Processor Configuration File (PCF)
Processor Configuration Files (PCF), introduced with RISCWatch version 4.3, created user prior starting RISCWatch. These files contain resource definitions required uniquely define target debug environment. This file format, with enhanced support Indirectly Mapped Registers, replaces Register Definition File format previous releases (see Appendix "Register Definition File (Outdated)"). Once created, file must compiled into loadable form. user must invoke RISCWatch compiler program (rwpcfc) with file name designated input argument. errors detected, Processor Resource Definition (PRD) file created. This file will have same base file name, with file extension ".prd". RISCWatch PRD_FILE environment variable used identify name customized file. Upon initial program startup, RISCWatch will read designated file determine unique target debug environment. Only file designated located using following rules:
file name qualified (directory path indicated), file search
performed using specified directory only.
name qualified, file search performed using directory
paths designated with RISCWatch SEARCH_PATH environment variable. found, current directory searched.
File Management
Processor Configuration File (PCF) ASCII file that created with text editor. Once defined, must compiled rwpcfc compiler program. Typically, file contains definitions unique ASIC macro. easiest approach simply definitions into single file necessary information easily located edited needed. Other times might make more sense create multiple files, each containing necessary details separate macro. will each user determine which method works best them.
3-10
RISCWatch Debugger User's Guide
just file created, simply compiled own. multiple file approach used, there needs "master" which used gather other low-level files into one, coherent entity. When low-level files compiled, they need -refer flag which tells compiler that they will later included, referred (using REFER), another file. Regardless deeply these low-level files nested, they will included another file, they need compiled with -refer flag. Once time compile highest level "master" file, -refer flag used since represents highest level user compilation. Successful compilation highest level "master" file will result valid file whose name then specified RISCWatch environment file with PRD_FILE variable. RISCWatch comes with default file (rwppc.prd) which automatically loaded PRD_FILE environment variable specified.
File Syntax
general syntax rules file follows: character denotes start comment. text following character given line will ignored. Blank lines allowed will ignored. error detected while compiling will generate error messages terminate execution compiler. values preceded `0x', such 0x12AB0423. Implied values preceded `0x', such ABCD1245.
following sections define complete list definitions their valid line entries.
REFER Definitions
REFER definition indicates that current file will resources defined another file. This functionality allows file refer resources defined another. rwpcfc compiler does allow reference before definition. this reason, REFER definitions should appear very file that when resources referenced later current file, compiler will already aware them. Each REFER definition must adhere following syntax: REFER filename.prd
Using RISCWatch Debugger
3-11
Where:
filename.prd name file which result successfully
compiling associated file.
Note: resource referenced before been defined, error message will
generated compile will aborted. Place REFER definitions near file define resources before they referenced further down file.
MACRO Definitions
MACRO definition basic building block file allows high degree modularity reusability. carefully defining file MACROs along logical functional divisions, references made them countless other definitions. Such abilities seem important only chip being defined becomes crucial same similar resources used multiple ASIC designs. Each MACRO definition must adhere following syntax: DEFINE MACRO macro_name
macro_def
Where:
macro_name unique name being assigned this MACRO
name which other definitions will reference This name only contain alpha-numeric underscore characters. Note: prefix "PPC_" been reserved debugger use. Therefore macro_name begin with "PPC_"
macro_def represents more MACRO definitions, each which defines
resource. resources which defined MACRO fields (FIELD definition), registers (REG definition) register fields (REGFLD definition). below information about these definitions. Note: resource referenced before been defined, error message will generated compile will aborted.
CHIP Definitions
There forms CHIP definitions. used define chip based existing RISCWatch defined core (DEFINE CHIP) while other used resources existing RISCWatch defined chip (APPEND CHIP). DEFINE CHIP definition must adhere following syntax: DEFINE CHIP chip_name
dc_def
3-12
RISCWatch Debugger User's Guide
Where:
chip_name unique name being assigned this CHIP
name used PROC environment variable. dc_def represents more DEFINE CHIP entries, each which defines includes resource. resources which defined names (NAME definition), PVRs (PVR definition) firmware revisions (REV definition). resources which included macros single core (INCLUDE definition). below information about these definitions. following restrictions apply DEFINE CHIP definition There must only INCLUDE CORE definition There zero more INCLUDE MACRO definitions There zero more DEFINE NAME definitions There must least DEFINE definition
APPEND CHIP definition must adhere following syntax: APPEND CHIP chip_name
ac_def
Where:
chip_name unique name being assigned this CHIP
name used PROC environment variable. ac_def represents more APPEND CHIP entries, each which defines includes resource. resources which defined field (FIELD definition), name (NAME definition), register (REG definition), register field (REGFLD definition), register alias (REGALIAS definition), PVRs (PVR definition) firmware revisions (REV definition). resources which included macros single chip (INCLUDE CHIP definition). below information about these definitions. following restrictions apply APPEND CHIP definition included MACROs only contain REG, REGFLD REGALIAS entries There zero more definitions. There zero more REGFLD definitions. There zero more REGALIAS definitions.
Using RISCWatch Debugger
3-13
There must INCLUDE CHIP definition.
Note: resource referenced before been defined, error message will
generated compile will aborted. list RISCWatch defined CHIPs COREs which available use, on-line available program Help pulldown, visit RISCWatch Support Center page. following sections define complete list valid line entries DEFINE MACRO, DEFINE CHIP APPEND CHIP definitions.
INCLUDE Definitions
There three forms INCLUDE definitions which allow inclusion previously defined CHIP, CORE, MACRO definition. INCLUDE CHIP definition must adhere following syntax: INCLUDE CHIP chip_name Where:
chip_name unique name chip being included. These chip
names defined representative parts contained PowerPC processor library. Examples valid chip names include PPC_403GCX, PPC_603EV, PPC_740, PPC_750, PPC_401C2. INCLUDE CORE definition must adhere following syntax: INCLUDE CORE core_name Where:
core_name unique name core being included. These core
names defined representative parts contained PowerPC ASIC library. Examples valid cores names include PPC_401M1_CORE, PPC_401B2_CORE, PPC_401C2_CORE. INCLUDE MACRO definition must adhere following syntax: INCLUDE MACRO macro_name [offset] Where:
macro_name unique name previously defined MACRO
definition.
offset optional address offset which used relocatable register
MACROs. offset added subtracted (depending specified sign) each register definition contained referenced MACRO. This
3-14
RISCWatch Debugger User's Guide
allows "base" definition defined once then relocated anywhere memory address space. Note: resource referenced before been defined, error message will generated compile will aborted. list RISCWatch defined CHIP, CORE MACRO names available INCLUDE directive, online available program Help pulldown, visit RISCWatch Support Center page.
EXEC Definitions
EXEC definition used associate name with ordered sequence RISCWatch commands which will executed whenever register referenced from read written (See REXEC WEXEC keywords listed under Definitions). Each EXEC definition must adhere following syntax: DEFINE EXEC exec_name
command
ENDEXEC Where:
exec_name unique name being assigned this EXEC
name used definitions that reference This name only contain alpha-numeric underscore characters. command list more RISCWatch commands which will executed order which they listed. There only command specified line. Parameters passed into EXEC using PARMS command (see "Command File Parameters" listed under "Command Files"). EXEC definition basically mini-command file (see "Command Files") which executed whenever customized registers read from written Such functionality provides great deal power must used responsibly. Care must taken avoid "dangerous" operations. other processor resources manipulated while EXEC runs, usually wise back data values before EXEC starts executing then restore these values just before leaving EXEC. facilitate transfer data values into these customized register EXEC definitions, RISCWatch provides $INPUT $RETURN pseudo-variables. Whenever command used write value register which uses EXEC definition, commands inside EXEC reference $INPUT obtain data value written. Likewise, while using command read EXEC definition register, $RETURN value read that referenced once EXEC returns.
Using RISCWatch Debugger
3-15
"PCF Example" section which follows more details.
FIELD Definitions
FIELD definition used associate name with defined logical groupings that referenced later another resource. Each FIELD definition must adhere following syntax: DEFINE FIELD field_name {field_def} Where:
field_name unique name being assigned this FIELD
name used other definitions reference This name only contain alpha-numeric underscore characters. field_def defines more fields. Each field must adhere following syntax:
name start length
Where:
NAME Definitions
name unique name being assigned this field name used reference This name only contain alpha-numeric underscore characters. start decimal physical starting (MSB=0) this field length decimal length this field bits
NAME definition used define name given chip. Many chips known both marketing name (i.e. 740), "pet" name (i.e. Arthur). This definition allows number "pet" names defined intended give unique code name given chip definition. Once defined, "pet" name used when specifying value PROC variable RISCWatch environment file. NAME definition must adhere following syntax: DEFINE NAME user_name Where:
user_name unique name being assigned. This name only
contain alpha-numeric underscore characters.
Definitions
definition used define value given chip. When RISCWatch started, PROC environment variable, along with file, used define resources target system. Once communication with chip been established, register will read compared
3-16
RISCWatch Debugger User's Guide
definition value. miscompare these values will result warning error message user. Multiple definitions allowed help account changes multiple revisions same ASIC. definition must adhere following syntax: DEFINE pvr_value Where:
pvr_value processor's unique value implied
hexadecimal number (ex. DEFINE 40ABCD04).
Definitions
definition used define instance physical register. Each definition must adhere following syntax: DEFINE reg_class reg_name #|address|addr_reg addr_val data_reg bit_width R|W|RW [access] [VOLATILE] [display] [REXEC exec_name[{parm_list}]] [WEXEC exec_name[{parm_list}]] Where:
reg_class class register being defined; DCR, IMR, MMIO reg_name unique name being assigned this name
which other definitions will reference This name only contain alpha-numeric underscore characters. Note: registers being defined because they part ASIC macro should common naming prefix that they grouped together RISCWatch. naming convention RISCWatch supports ASIC register prefixes letters acronym macro, followed number (usually starting with ending with underscore (_). This prefix then added beginning each register contained that macro. following this convention, RISCWatch able detect prefix group registers accordingly. This allows RISCWatch create ASICs entry Hardware Register pulldown listing prefixes detected during initialization. Selecting these prefixes then creates Register window containing registers with this prefix thereby grouping them together represent associated macro. example, macro were being added, registers defined with could prefixed with `PLB0_'. RISCWatch could then detect this common prefix Hardware
Using RISCWatch Debugger
3-17
Register ASICs pulldown would list `PLB0'. Selecting this entry would bring Register window with PLB0 prefixed registers
number register. address address MMIO register. addr_reg name address register Indirectly Mapped
Register (IMR).
addr_val value written addr_reg access register's
contents.
data_reg name data register register. bit_width decimal width this register bits. R|W|RW defines register's access; read-only (R), write-only
read-write (RW).
access optional parameter MMIO registers which used JTAG
ethernet JTAG parallel port RISCWatch targets. decimal number which indicates access size, bits, RISCWatch must when reading writing this memory location. access size should with each multiple identifying unique PowerPC load/store instruction use. example, access size "16" instructs RISCWatch read register executing "load halfword" PowerPC instruction. Specifying access size will override access size settings made with memacc command. access size specified, RISCWatch will access size defined memory region. memacc page 5-81 information about unique memory region access size. VOLATILE optional keyword which indicates this register will change value after read operation performed. must entered uppercase. RISCWatch users must issue explicit read display contents volatile register. This keeps RISCWatch from asynchronously reading register thus avoiding changes Having auto-update
3-18
RISCWatch Debugger User's Guide
mode enabled window containing these registers will cause them read during update. display optional keyword which indicates default display format floating point registers; REXEC optional keyword which indicates that previously defined EXEC entry read value this register. WEXEC optional keyword which indicates that previously defined EXEC entry write value this register. exec_name name previously defined EXEC entry which run. parm_list optional list more parameters whose values passed specified EXEC entry. Note: resource referenced before been defined, error message will generated compile will aborted.
REGALIAS Definitions
REGALIAS definition used refer previously defined register another name. REGALIAS definition must adhere following syntax: DEFINE REGALIAS new_reg exist_reg Where:
new_reg register alias name. exist_reg name previously defined register.
Note: resource referenced before been defined, error message will
generated compile will aborted.
REGFLD Definitions
REGFLD definition used define register field. Each REGFLD definition must adhere following syntax: DEFINE REGFLD register field_name|{field_def} Where:
register name previously defined register. field_name name previously defined FIELD entry. field_def defines more fields. Each field must adhere
following syntax:
name start length
Where:
Using RISCWatch Debugger
3-19
name unique name being assigned this field
name which will referenced. This name only contain alpha-numeric underscore characters. start decimal physical starting (MSB=0) this field. length decimal length this field bits. Note: resource referenced before been defined, error message will generated compile will aborted.
Definitions
definition used indicate RISCWatch which Processor Probe firmware files used with specific definition chip/core. chips/cores with multiple revisions, multiple definitions used define unique files each, necessary. definition must adhere following syntax: DEFINE driver generics Where:
processor revision number. should used PowerPC
family cores/chips.
driver name Processor Probe driver filename used
this revision. Such names usually start with "E34" have ".X" extension. generics name Processor Probe generics filename used this revision. Such names usually start with "E34" have ".X" extension.
Compiling
Once file been created, must compiled rwpcfc verify that file syntax correct that definitions complete. file turned into format which loaded RISCWatch time. compiler program, rwpcfc, installed same directory main RISCWatch executable. This also where default RISCWatch file located. This file contains number predefined processors, cores other resources that need referenced. compiler, following syntax: rwpcfc [-log] [-refer] filename.pcf Where:
3-20
RISCWatch Debugger User's Guide
-log optional flag. present, messages which usually printed
screen directed rwpcfc file (rwpcfc.log).
-refer optional flag. must specified when compiling file which
will REFERred another file (see REFER definition above). other words, file A.pcf "REFER B.prd" line file B.pcf must have been compiled with -refer flag, since being REFERred only file being defined compiled, this option will used. filename.pcf name file that compiled. this time, compiler DOS-based tool Windows 95/98 long filenames supported. errors detected, appropriate error message will printed screen file. These should used correct source error message(s) prior attempting recompile. Successful compilation will result valid file whose name then specified RISCWatch environment file with PRD_FILE variable. When RISCWatch started, this variable will used load appropriate resource information uniquely defined processor/core designated PROC environment variable value.
Example
following examples provided acquaint users with some more common coding file. this example, simple memory mapped registers added existing chip function previously accomplished with Register Definition File). addition, register fields have been defined MMIO_2 MMIO_3:
APPEND CHIP MY_403GB INCLUDE CHIP PPC_403GB DEFINE MMIO MMIO_1 0xA000 DEFINE MMIO MMIO_2 0xA004 DEFINE MMIO MMIO_3 0xA008 VOLATILE DEFINE MMIO MMIO_4 0xA00C VOLATILE DEFINE REGFLD MMIO_2 AVRL AVRR DEFINE REGFLD MMIO_3 AVRL AVRR
Using RISCWatch Debugger
3-21
Once compiled, this would result custom file which would using PRD_FILE environment variable while defined chip, MY_403GB, would using PROC environment variable. next example, MACRO will used accomplish same results previous example. addition, macro IMR_REGS defined demonstrate define registers. Note DEFINE FIELD registers that share same register field designations:
DEFINE MACRO MMIO_REGS DEFINE MMIO MMIO_1 0xA000 DEFINE MMIO MMIO_2 0xA004 DEFINE MMIO MMIO_3 0xA008 VOLATILE DEFINE MMIO MMIO_4 0xA00C VOLATILE DEFINE FIELD MMIO_FIELD1 AVRL AVRR DEFINE REGFLD MMIO_2 MMIO_FIELD1 DEFINE REGFLD MMIO_3 MMIO_FIELD1 DEFINE MACRO IMR_REGS DEFINE T0_ADDR 0x0180 DEFINE T0_DATA 0x0181 DEFINE T0_REG1 T0_ADDR 0x00000001 T0_DATA DEFINE T0_REG2 T0_ADDR 0x00000002 T0_DATA DEFINE T0_REG3 T0_ADDR 0x00000003 T0_DATA APPEND CHIP MY_403GB INCLUDE CHIP PPC_403GB INCLUDE MACRO MMIO_REGS INCLUDE MACRO IMR_REGS
next example, MACRO will used define base registers which located anywhere within chip's address space. Using offset feature INCLUDE MACRO statement, this registers used different processors different memory locations:
DEFINE MACRO BASE_REGS DEFINE MMIO BASE_1 DEFINE MMIO BASE_2 DEFINE MMIO BASE_3 DEFINE MMIO BASE_4
3-22
RISCWatch Debugger User's Guide
APPEND CHIP MY_A1 INCLUDE CHIP PPC_401A1 INCLUDE MACRO BASE_REGS 0xA0000000 APPEND CHIP MY_B2 INCLUDE CHIP PPC_401B2 INCLUDE MACRO BASE_REGS 0xFFF00000
next example, MACRO will used define customized register which uses DEFINE EXEC definitions create read write "routines" which then used manipulate contents this specialized register:
DEFINE MACRO CUST_REG DEFINE EXEC cust_read PARMS {stuff_instr} STUFF stuff_instr $RETURN 0x00E80024 ENDEXEC DEFINE EXEC cust_write PARMS {stuff_instr} WRITE 0x00E80024 $INPUT STUFF stuff_instr ENDEXEC DEFINE APU1 0xFFFF REXEC cust_read{0x90A10024} WEXEC cust_write{0x80A10024}
MEMACC Command
When memory read write operation requested, RISCWatch must first determine request valid then determine proper proceed with request. Performing read invalid memory address, issuing store word instruction memory region configured half word access, could result unwanted machine checks, data corruption, system hangs. When RISCWatch first started, target processor name (designated with PROC environment variable) used define type memory address validation perform. RISCWatch internal address validation summarized follows:
Using RISCWatch Debugger
3-23
403GA processor targets, RISCWatch will read bank
registers determine valid address regions read/write access restrictions. Four byte word access assumed valid read write operation. Access type defaults instruction data. 403GC processor targets, RISCWatch will default operations defined 403GA translation off. translation read determine valid address regions access restrictions. Four byte word access assumed valid read/write operations. Access type determined instruction data translation bits defined machine state register (MSR). Since Open performs address validation when translation RISCWatch assumes addresses valid Open targets. 405GP processor targets, RISCWatch will read SDRAM registers determine address regions read/write access restrictions when address translation off. translation read determine valid address regions access restrictions. Four byte word access assumed valid read/write operations. Access type determined instruction data translation bits defined machine state register (MSR). Since Open performs address validation when translation RISCWatch assumes addresses valid Open targets. targets, addresses assumed valid both read write access. Access size defaults bytes. Access type defaults instruction data. Core+ASIC processors, addresses assumed valid both read write accesses when address translation off. Access size defaults bytes. Access type defaults instruction data. enabled, addresses checked against current entries. Note: Monitor Open targets, access size governed monitor code running target processor. Obviously, internal address validation adequate users. effort provide additional memory access protection, RISCWatch provides memacc command which allows user define unique memory configuration associated with processor target.
MEMACC
Users override RISCWatch internal address validation checks executing memacc command. command syntax defined follows:
memacc beg_addr end_addr [access [size [type]]]
Where:
3-24
RISCWatch Debugger User's Guide
keyword memacc command indicating that entry
added list user defined address regions.
beg_addr indicates beginning address target memory being defined
with this command. address designated (leading "0x" "0X"), octal (leading decimal. end_addr indicates last address target memory being defined with command. address designated (leading "0x" "0X"), octal (leading decimal access optional parameter which indicates access restrictions specified region. Access "RO" (read only), "WO" (write only), "NA" access), "RW" (read/write). specified, access defaults "RW". size optional parameter which used JTAG ethernet JTAG parallel port RISCWatch targets. decimal number which indicates maximum access byte size RISCWatch when reading writing specified memory region. Size 0,1, with each multiple identifying unique PowerPC load/store instruction use. example, access size instructs RISCWatch read memory executing "load word" PowerPC instruction. access size specified, default size defined target processor will used. size also indicates that default size, used RISCWatch internal address checking, should used. type optional parameter indicating valid type access specified memory region. Valid types IMEM (instruction memory), DMEM (data memory), (instruction data memory). specified command, type defaults MEM. Since users aware internal access types used various RISCWatch screens, default setting should normally used. Note: Additional variations memacc command possible pertinent this discussion. memacc page 5-81 additional information. Examples: memacc 0x40000000 0x40000009 memacc 0xFFFF0000 0xFFFFFFFF memacc 0x4000000a 0x4FFFFFFF Each "memacc add" command adds entry list user defined address definitions. When RISCWatch performs memory operation, address validation proceeds follows: Check user defined address regions first determine address read/written. Entries searched LIFO, meaning last "memacc add" command entered checked before previous entries.
Using RISCWatch Debugger
3-25
Perform internal address checking defined target processor portion address range included user defined entries.
Practical Application Example
following example provided demonstrate memacc command used customize RISCWatch memory access. Example: RISCWatch running customized chip that built around PowerPC Core. There byte region memory, starting address 0x50004444, which accessed with load/store halfword PowerPC instructions. other addresses, starting 0x50000000 ending 0x5FFFFFFF, considered invalid. store load these addresses will result machine check. Memory mapped addresses 0x40000000 0x40000009 byte read/write access locations used serial port operations. Addresses 0x4000000A 0x4FFFFFFF invalid other addresses valid read/write regions which accessed PowerPC load/store word instructions.
Based target processor, RISCWatch perform internal address checking:
Every address, from 0x00000000 0xFFFFFFFF, valid both read
write operations.
Access size defaults This means PowerPC load/store word
instructions used access memory.
Note: user always option using RISCWatch
internal address checking. This accomplished completely defining entire address space with "memacc add" commands. example, "memacc 0xFFFFFFFF" defines entire address space read/write region byte access size. With possible addresses defined, there need RISCWatch perform internal address checking. Using default internal checking base, "memacc add" commands must issued indicate address regions that allow byte read/write access. These would addresses from 0x40000000 0x5FFFFFFF. following commands should added RISCWatch start-up command file (designated with STARTUP_FILE environment variable): memacc 0x50000000 0x5FFFFFFF memacc 0x50004444 0x50004445
3-26
RISCWatch Debugger User's Guide
memacc 0x40000000 0x40000009 memacc 0x4000000a 0x4FFFFFFF
Note: Notice addresses overlap between first second commands. Since second command issued after first, RISCWatch will restrictions second command, since LIFO search order used.
RISCWatch customized unique memory constraints presented this example. attempt read/write memory addresses 0x0400000a 0x50004444, 0x50004446 0x5FFFFFFF, will flagged error memory access will attempted. attempt read/write memory addresses 0x40000000 0x40000009 will performed using PowerPC load/store byte instructions. PowerPC load/store halfword instructions will used access halfword that exists address 0x50004444. other address regions will considered valid read/write requests that performed using PowerPC load/store word instructions.
Using RISCWatch Debugger
3-27
Window Descriptor File
Once unique memory access restrictions register definitions complete using memacc command creating Processor Configuration File), RISCWatch commands issued read alter resources which accessible from core processor. addition, users create their customized windows which display Core+ASIC resources. Please "User-Defined Windows" page 3-119 details about customized RISCWatch windows.
Multi-Processor Resources
effort support multi-processor PowerPC systems, RISCWatch allows user create Multi-Processor Support (MPS) file. This file, created prior starting RISCWatch, contains information which allows single RISCWatch session communicate each processor. Currently, certain restrictions apply when running RISCWatch multi-processor environment:
PowerPC processors must identical. example, RISCWatch
currently debug both 403GA 603e processor from single session. JTAG targets, each processor must only device JTAG scan chain. Only parallel port target allowed. target processor scan chain contain multiple devices. following sections provide additional details needed RISCWatch multi-processor environment.
File Syntax
file ASCII file that created with text editor. file identified RISCWatch MPS_FILE environment variable, must have file extension ".mps". general syntax rules follows: character denotes start comment. text following character given line will ignored. Blank lines allowed will ignored. error detected during processing file will surface error message RISCWatch file execution will terminate.
3-28
RISCWatch Debugger User's Guide
Board Definitions
Board definitions span multiple lines file used identify type PowerPC chip board communication protocol RISCWatch should use. Each board definition must adhere following syntax:
BOARD brd_name target_name [target_type [wbg [wfg [cbg [cfg [tbg [tfg]]]]]]] CHIP proc_id chip_name bypass length ENDBOARD
Where:
BOARD indicates start board definition must appear
uppercase.
brd_name indicates user defined name board. name must
enclosed double quotes. Names exceeding characters will truncated. target_name indicates valid target name found TCP/IP services file TCP/IP dotted address (e.g. 7.1.1.100). This overrides TARGET_NAME designation made rwppc.env file. target_type indicates type RISCWatch target use. Valid target types those defined TARGET_TYPE environment variable. "Environment Resources" page valid target types use. target type designated, default JTAG_ETH used. indicates window background color RISCWatch windows associated with this board definition. color page 5-32 valid color designations. value "DEFAULT" indicates host system default. indicates window foreground color RISCWatch windows associated with this board definition. command color page 5-32 valid color designations. value "DEFAULT" indicates host system default. indicates control button background color RISCWatch windows associated with this board definition. color page 5-32 valid color designations. value "DEFAULT" indicates host system default. indicates control button foreground color RISCWatch windows associated with this board definition. color page 5-32 valid color designations. value "DEFAULT" indicates host system default. indicates text background color RISCWatch windows associated with this board definition. color page 5-32 valid color designations. value "DEFAULT" indicates host system default.
Using RISCWatch Debugger
3-29
indicates text foreground color RISCWatch windows
associated with this board definition. color page 5-32 valid color designations. value "DEFAULT" indicates host system default. CHIP keyword indicating chip information will follow. must designated uppercase. least chip entry must designated each board defined syntax error will occur. proc_id indicates valid processor target name. Valid processor names those defined PROC environment variable. "Environment Resources" page valid processor names use. chip_name indicates user defined name chip. name must enclosed double quotes. Names exceeding characters will truncated. decimal number indicating size JTAG instruction register. bypass value used this chip JTAG bypass mode. value specified (leading "0x" "0X") decimal. length indicates number bits scan chain when this chip JTAG bypass mode. Note: bypass length fields required when JTAG scan chain more than chip hooked this case, multiple CHIP records would defined single board. noted earlier, this type configuration currently supported. Example: BOARD "BRD1" 7.1.1.100 jtag_eth BLUE WHITE CHIP 403GCX "chip_a" ENDBOARD BOARD "BRD2" 7.1.1.21 jtag_eth WHITE WHITE BLACK WHITE CHIP 403GCX "chip_b" ENDBOARD above example, RISCWatch will initialized communicate with boards. 403GCX chip first board will identified "chip_a", second board's chip will called "chip_b". windows containing blue background will "chip_a", while those having background will "chip_b". When file designated, TARGET_NAME TARGET_TYPE environment variable designations (specified rwppc.env file) will ignored.
3-30
RISCWatch Debugger User's Guide
Debugging
When RISCWatch started, MPS_FILE environment variable setting detected rwppc.env environment file. specified file found, read used RISCWatch mode. file located using following rules:
file name qualified (directory path indicated), file search
performed using specified directory only. name qualified, file search performed using directory paths designated with RISCWatch SEARCH_PATH environment variable. found, current directory searched. Once mode, RISCWatch ability switch communications target amongst chips that were specified file. This switching ability allows resources particular chip specified debugged though were single chip system. following sections contain more information individual chips identified debugged using RISCWatch interface.
Context
given moment, RISCWatch only communicate with single chip. environment, necessary debug resources several chips which reside physically separate boards. communicate with each individual chip, there must RISCWatch switch communications path "talk" particular chip. resources specified file define communications paths RISCWatch will communicate with chips system. target names types that were specified used select proper physical communications path. These resources managed internally RISCWatch transparent user. chip names specified file used uniquely identify particular chip particular board. These names serve user communicate RISCWatch which chip's resources debugged. switch communications path talk particular chip, mpsset command used. argument supplied mpsset command simply chip name specified file. RISCWatch then able this name look communications path specified chip. RISCWatch configures communications that able debug resources specified chip. Using mpsset command referred setting context. within this context that particular chip's resources will accessed.
Using RISCWatch Debugger
3-31
RISCWatch Main window will primary means identifying what context currently set. status bar, located bottom Main window, will display name chip which currently being debugged. context said have been this chip that displayed status bar. command issued from command line Main window will execute this context. read register command executed, specified register will read from current context (the chip displayed status bar). register from different chip read, mpsset command must issued switch context that chip then "read register" command used. When running command file, commands executed under current context. switch context during execution command file, simply issue mpsset necessary.
Windows
mode, windows classified being three types: dynamic specific neutral RISCWatch Main window only instance dynamic window. This window have context switched using mpsset command. current context displayed status bar. specific windows assigned current context upon creation context changed thereafter. processor accesses commands issued from such window will only pertain context other. context each these windows will displayed window's title bar. What will displayed chip name assigned that context file. Most windows RISCWatch specific. neutral windows assigned context because they access processor resources they simply current context displayed Main window status bar). Examples neutral windows include Calculator, Command File, Log, Memory Load, Memory Save, MPS, Output Window List. window only available mode used shortcut context well providing status each chip. Displayed this window boards chips defined file. mouse used select chip which turn issues appropriate mpsset command switch context this chip.
3-32
RISCWatch Debugger User's Guide
Invoking Debugger
Before RISCWatch started first time, items need taken care First, make sure that RISCWatch executable directory that located PATH environment variable. Prior starting RISCWatch, change environment resource file rwppc.env match specific target configuration plan use. Below complete list different target types available brief description some steps that need taken. "Environment Resources" page additional resource setup information.
JTAG Parallel Port Target: Verify that JTAG hardware installed defined RISCWatch Debugger Installation Guide. Verify that rwppc.env file designates `TARGET_TYPE jtag_par', discussed "Environment Resources" page 3-5.
JTAG Ethernet Target (RISCWatch Processor Probe Connection): Verify that Processor Probe hardware installed defined RISCWatch Debugger Installation Guide. Verify that rwppc.env file designates `TARGET_TYPE jtag_eth', discussed "Environment Resources" page 3-5. Verify that rwppc.env file designates `TARGET_NAME x.x', where `x.x' replaced TCP/IP name address chosen processor probe during installation. Verify proper installation network recognition RISCWatch Processor Probe. This accomplished `pinging' TARGET_NAME from host system (ex. `ping 7.1.1.100').
Monitor Target: Verify that host configured correctly Ethernet setup, discussed configuration section evaluation board user's documentation. These instructions describe specific host configuration steps other setup (editing /etc/services files) required RISCWatch successful host/target communication. Verify that target monitor debug mode, discussed PowerPC evaluation board user's documentation. This typically involves starting terminal emulation screen, resetting board, enabling ethernet serial port boot source, selecting option enable monitor debug.
Using RISCWatch Debugger
3-33
Verify that rwppc.env file designates `TARGET_TYPE rom_mon' discussed "Environment Resources" page 3-5. Verify that rwppc.env file designates `TARGET_NAME x.x', where `x.x' replaced TCP/IP name address chosen monitor. PowerPC evaluation board user's documentation more information about setting local address monitor. From host system, ping TARGET_NAME verify proper network monitor initialization `ping 7.1.1.4'). Note that monitor must debug mode when ping command issued.
Open Target Verify that Open running target system. RISCWatch cannot communicate with Open programs that have called rsld_start(). Loading Open image performed using other RISCWatch targets (see "Loading Boot Boot Image Files" page 3-46) using monitor bootp support. PowerPC evaluation board user's documentation Open User's Guide, listed "Related Publications" page xxiv this user's guide. Verify that rwppc.env file designates `TARGET_TYPE osopen' discussed "Environment Resources" page 3-5. Verify that rwppc.env file designates `TARGET_NAME x.x', where `x.x' replaced TCP/IP address chosen Open image. From host system, ping TARGET_NAME verify proper network Open initialization `ping 7.1.1.4').
Under normal circumstances, RISCWatch will started described "Starting Debugger" page 2-1. RISCWatch does have command line parameters which have specified depending RISCWatch. Here list command line parameters that RISCWatch understands: -echo used echo each command file line executed; this debug command file execution. This option only available non-PC platform. used display help information RISCWatch which lists available command line options overrides PROC setting specified environment resources file (rwppc.env). This allows multiple icons hosts defined different processors while using only environment file. README file list currently supported processor names.
-help -procNAME
3-34
RISCWatch Debugger User's Guide
-rev
Overrides setting specified environment resources file. This distinguishes between different 6xx/7xx processor revision levels when connected RISCWatch Processor Probe. -rev flag must used when debugging 6xx/7xx processor which RISCWatch supports more than revision level. example, debugging 603e Rev3 processor, would -rev3 distinguish Revision from other supported revision levels. Once proper JTAG driver loaded into Processor Probe memory, -rev flag required. RISCWatch only supports revision level given processor, -rev flag required.
-tty
specifies that RISCWatch mode. mode command line driven mode RISCWatch that does rely user interface input output. This option only available non-PC host.
JTAG Ethernet Targets RISCWatch Processor Probe
RISCWatch processor probe Ethernet-to-JTAG convertor, converting commands sent from RISCWatch appropriate series processor accesses through JTAG port probe. probe dedicated JTAG controller chip drive JTAG signals hardware opposed slower, emulated approach software. talk RISCWatch, processor probe contains programs flash memory: interface that RISCWatch communicates with (called "Generics"), underlying specific JTAG device driver. When RISCWatch JTAG Ethernet target initially invoked, RISCWatch will check version Generics specific JTAG driver loaded processor probe requested with -proc flag PROC environment variable) against versions files located directory specified RWPPC_DIR environment variable. Generics JTAG drivers match, file(s) from RWPPC_DIR will loaded into processor probe. Because loading processor probe corrupt processor's JTAG controller, recommended that processor reset after loading complete.
Note: wish maintain current processor state, processor probe must disconnected from target until correct Generics JTAG driver loaded.
Generics JTAG driver filenames supported currently available processors included README file provided this version RISCWatch. following some considerations note when using Processor Probe:
Using RISCWatch Debugger
3-35
JTAG connections, target processor clock speed must least twice JTAG clock speed. Processor Probe targets JTAG clock speed defaults 10Mhz. RISCWatch command `jtag' (see 5-69) used lower JTAG clock speed. Because high speed JTAG interface with Processor Probe, possible that noise interface target adversely affect data passed between RISCWatch target. memory register reads appear unstable when using processor probe connection, using `jtag' command lower JTAG clock speed fixes problem. RISCWatch will attempt update Processor Probe flash memory detects that processor type desired RISCWatch session does match processor type which Processor Probe currently initialized (this behavior overridden using PROBE_FLASH environment variable).Updating Processor Probe flash memory with JTAG connector connected target typically puts processor into unrecoverable state. Therefore, RISCWatch will always attempt reset processor after Processor Probe flash memory updated. PROBE_FLASH environment variable used disable updates Processor Probe flash memory. "Environment Resources," details force, completely bypass, reflash Processor Probe. suggested procedure when updating Processor Probe flash memory follows: Start with Processor Probe connected target. Following update flash, warning message saying RISCWatch unable soft stop processor while RISCWatch coming attempt reset target from RISCWatch `reset' command Reset window. reset from RISCWatch fails, reset target reset switch. that doesn't satisfactorily reset entire board, power reset will required target. Following reset, enter `stop' command from RISCWatch start debugging.
Operational Notes:
Disconnecting/connecting Processor Probe from/to target while power applied affect state target reset target required. Cycling power Processor Probe typically puts target unrecoverable state reset target will required. Always wait
3-36
RISCWatch Debugger User's Guide
LEDs front Processor Probe stop blinking before resetting target.
RISCWatch will allow more than copy RISCWatch communicate with Processor Probe time. Processor Probe use, error message "communications port already use" will appear. some conditions communications link close correctly, thereby locking RISCWatch from coming again. couple more common situations where this occur are:
Rebooting while RISCWatch running Disconnecting Processor Probe from host while
RISCWatch running, subsequently terminating that RISCWatch session with Processor Probe still disconnected. this condition occurs, cycling power Processor probe will clear communications link.
Using RISCWatch Debugger
3-37
Main Window Resources
RISCWatch employs graphical user interface (GUI) that needs have host platform window system running. When RISCWatch started, will bring windows specified rwppc.lay file. first time RISCWatch run, other time when rwppc.lay file available, LOAD_LAYOUT specified environment file, debugger brings only main command window. this window, shown Figure 3-1, that will used access debugger features.
Figure 3-1. Sample Main Window
Note: list items found bottom screen different depending level RISCWatch, target type, etc.
window resides menu which contains names major program access points. Directly below menu scrolling window which maintains history commands entered through command line interface. Commands this window re-executed edited then executed described "Command History Usage" page 3-42.
3-38
RISCWatch Debugger User's Guide
Directly below command history window command line interface that used send commands RISCWatch processed. commands entered here same ones which used command file help automate development testing products using supported PowerPC processors. list commands their syntax, select Help option from menu bar. Directly beneath command line interface, scrolling message window which maintains history entered commands their resultant status, help error messages. each command entered, echoed this window will followed status error messages. This format allows commands their resultant actions viewed time. bottom Main Window resides status bar, which displays updated information about current debug activity. message area shows progress messages. area indicates whether multiprocessor support enabled. chip area identifies chip name corresponding current debug context. target type area indicates method communication being used current debug session. processor status field also indicates whether target processor either running, stopped, halted, powered off, status unknown.
Menus
RISCWatch menus used access those parts program which require interaction with user. Menu items commands sub-menus. Selecting item runs corresponding command displays corresponding sub-menu. Menu items selected clicking menu option pull down corresponding menu. Moving mouse menu item highlights item. Clicking highlighted item selects item. Unavailable selections grayed-out. Clicking outside menu closes menu without making selection. Clicking menu displays pull-down containing selections that particular menu, shown "Main Window Menu Options" page 3-40.
Using RISCWatch Debugger
3-39
File Menu
Command File (See 3-133.) Load Save View Quit
Source Menu
Main Window Menu Options Hardware Menu
Breakpoints (See 3-73.) Callers (See 3-60.) Files (See 3-61.) Functions (See 3-62.) Globals (See 3-79.) Locals (See 3-77.) Open (See 3-66.) Programs (See 3-58.) Source (See 3-51.) Debug (See 3-54.) Memory (See 3-104.) Register (See 3-117.) Fields (See 3-118.) Reset (See 3-138.) Trigger/Trace (See 4-8.) Calculator (See 3-143.) List (See 3-141.) Output (See 3-135.) List (See 3-141.) User-Defined (See 3-119.)
Window Menu
Utilities Menu
Beep (See 3-42.) Logging (See 3-141.)
Help Menu
About Install Guide PowerPC Manuals User's Guide
Figure 3-2. Main Window Menu Options
3-40
RISCWatch Debugger User's Guide
menu contains following menus:
File Source Hardware Window Utilities Help
What follows list menus their selections. Next each selection brief description function.
File Menu
Command File Load Save View Quit command file Load memory/register/layout file Save memory/register/layout file View selected file Terminate program Displays breakpoints Displays called functions Displays files current context Displays functions current context Displays global variables Displays local variables Display Open threads status Open target only) Displays programs current context Displays source file current context Displays Assembly Debug window Displays memory window pull-down Displays register access window Displays register field access window Reset processor, display reset window (JTAG target only) Displays Hardware Trigger/Trace window
Source Menu
Breakpoints window Callers window Files window Functions window Globals window Locals window Open window Programs window Source window
Hardware Menu
Asm. Debug Memory Register Fields Reset Trigger/Trace
Using RISCWatch Debugger
3-41
Window Menu
Calculator List Output User-Defined Displays desktop Calculator window Display window list Command Message Output information window Loads user-defined window Turns program error beep Enable/disable logging give current logging status Display RISCWatch version information Frequently asked questions Display RISCWatch User's Guide Display RISCWatch User's Guide
Utilities Menu
Beep Logging
Help Menu
About Install Guide User's Guide
PowerPC Manuals Display links various PowerPC documentation
Command Line Usage
RISCWatch supports rich commands which used access processor resources, thereby facilitating debug software hardware. list RISCWatch commands their syntax given section "Command Quick Reference" page 5-4. These commands typed into command file executed RISCWatch used user interface command line. command line interface between RISCWatch user. simply single-line text editor that used compose commands their arguments. Commands that valid from command line also entered input line, described "Input Line Usage" page 3-48. command line understands alphanumeric keys well Enter, Backspace, Delete, Insert, Home, arrow keys.
Command History Usage
RISCWatch Main window maintains list commands program executed since started. This list consists scrollable window located between menu command line interface. After more than commands have been entered, scroll attached window will need used view commands which have scrolled off.
3-42
RISCWatch Debugger User's Guide
using scroll attached window, possible view commands entered since RISCWatch started. This proves helpful times precise order which commands were issued. command history list also useful editing executing previously entered commands. edit previous command, simply place mouse over command click left mouse button. RISCWatch will place command command line where edited executed desired. arrow down arrow keys also used retrieve previously issued commands from command history list. arrow navigates sequentially back through list while down arrow moves forward through list. execute previously entered command, simply place mouse over command double-click left mouse button. RISCWatch will execute command though been typed user. down arrow keys also used sequentially scroll through history entered commands. each command recalled turn, will appear command line. From there edited desired executed.
Message Window
message window located bottom RISCWatch
Other recent searches
ZL50115 - ZL50115 ZL50115 Datasheet
ZL50110 - ZL50110 ZL50110 Datasheet
ZL50111 - ZL50111 ZL50111 Datasheet
ZL50114 - ZL50114 ZL50114 Datasheet
TLS-SMD-10F-5050X-30 - TLS-SMD-10F-5050X-30 TLS-SMD-10F-5050X-30 Datasheet
STHS2375A - STHS2375A STHS2375A Datasheet
STHS2375L - STHS2375L STHS2375L Datasheet
STHS2376A - STHS2376A STHS2376A Datasheet
STHS2376L - STHS2376L STHS2376L Datasheet
STHS2377A - STHS2377A STHS2377A Datasheet
STHS2377L - STHS2377L STHS2377L Datasheet
ST7262 - ST7262 ST7262 Datasheet
MS2372 - MS2372 MS2372 Datasheet
MMVL535T1 - MMVL535T1 MMVL535T1 Datasheet
MIL-T10727 - MIL-T10727 MIL-T10727 Datasheet
74LV573 - 74LV573 74LV573 Datasheet
Privacy Policy | Disclaimer
© 2012 Datasheet Archive
