Nios2-SW-UserGuide

First Silicon Solutions, Inc. Page 1 of 34 NiosII Software UserGuide System Navigator for the Nios® II Processor Core April 13, 2005 First Silicon Solutions, Inc. 4000 SW Kruse Way Place Bldg 3, Suite 210 Lake Oswego, OR 97035 voice: +1-503-489-0311 fax: +1-503-489-0315 info@fs2.com support@fs2.com document 10455.000 Copyright © 2004 First Silicon Solutions, Inc. Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 2 of 34 Table of Contents 1. Product Manuals................................................................................................................................ 3 2. Introduction........................................................................................................................................ 3 2.1. Opening the FS2 Console Window from the Nios II IDE ............................................................. 4 2.2. Using the HW Triggers and Events Window................................................................................ 5 2.3. Hardware Resources ................................................................................................................... 8 2.4. Using the Symbol Window to Program Events and Triggers....................................................... 9 2.5. Using the HW Triggers Window to set a breakpoint on a single data address..........................10 2.6. Triggering on a data address and value .................................................................................... 11 2.7. Triggering on a data address range ...........................................................................................12 2.8. Other HW Trigger choices.......................................................................................................... 13 2.9. Loading Symbols for HW Trace window .................................................................................... 13 2.10. HW Trace with Source lines inserted in between disassembled instructions ............................ 14 2.11. Speeding up HW Trace Window scrolling with Memory Cache definitions ...............................16 2.12. Tracing Load/Store cycles.......................................................................................................... 16 2.13. Aligning load/store cycles with instructions ................................................................................18 2.14. HW Trace Source Window .........................................................................................................18 2.15. HW Trace with Timestamps ....................................................................................................... 19 3. Performance Monitor....................................................................................................................... 22 3.1. Enabling Performance Monitor Hardware..................................................................................22 3.2. Performance Monitor Window ....................................................................................................22 4. Using the Host-Target Memory Cache System............................................................................... 26 4.1. Mapping Memory Ranges .......................................................................................................... 26 4.2. Working with Cached Memory ................................................................................................... 26 4.3. Initializing and Invalidating Cached Memory..............................................................................27 4.4. Downloading Code to Initialize Memory Cache .........................................................................27 4.5. Removing Memory Cache Ranges ............................................................................................ 27 4.6. Memory Cache Window .............................................................................................................28 5. Peripheral Window ..........................................................................................................................29 5.1. Creating New Peripheral Entries ................................................................................................ 32 Appendix A. Header formats used by Peripheral window to load structure information.............................34 Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 3 of 34 1. Product Manuals The documentation for the FS2 probe and software has been divided into these three manuals: Nios II Quick Start ([SOPC_KIT_NIOS2]\bin\fs2\Doc\Nios2-QuickStart.pdf) which covers:  Hardware installation and target connection  Software installation and bringing up the FS2 Console  FS2 Console CLI (command line interface) commands and examples for checking status and diagnosing problems  Host port connection errors Nios II Hardware Reference ([SOPC_KIT_NIOS2]\bin\fs2\Doc\Nios2-HW-Reference.pdf) which covers:  JTAG hardware connection and usage  Mictor38 hardware connection and usage  All CLI (tcl command line interface) command examples and reference  JTAG Chaining  Debugger AC Parameters  Debugger error codes Nios II Software User Guide ([SOPC_KIT_NIOS2]\bin\fs2\Doc\Nios2-SW-UserGuide.pdf) which covers:  Bringing up the FS2 Console from the Altera Nios II IDE (Integrated Debug Environment which is Eclipse-based)  Console windows for hardware triggers, trace, performance monitoring, and peripherals  Examples using these windows  Peripheral window load information 2. Introduction The System Navigator product supports JTAG-based debugging of the Altera® Nios® II processor core. 1 Referring to the diagram below, the product consists of hardware and software. The software consists of a host Application Binary Interface (ABI), Command-Line Interface (CLI), optional source-level debugger and the FS2 windows for supporting the product hardware features. The hardware includes Nios II OCI (On-Chip Instrumentation) and the FS2 System Navigator Family of probes. 1 FS2 and OCI are registered trademarks of First Silicon Solutions, Inc Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 4 of 34 This manual will cover the top box – the FS2 GUI windows for hardware support. CLI ABI Source-level debugger FS2 Probe Hardware Nios II OCI FS2 GUI windows for hardware support 2.1. Opening the FS2 Console Window from the Nios II IDE From the Nios II IDE environment, first click on the Run > Debug… menu item (or from the debug toolbar icon) which brings up the main Debug window. Next, click on the Debugger tab view. Now the check the “Launch FS2 Console Window” checkbox to enable the FS2 Console which in turn enables you to open the other HW debug windows (example below). To actually launch the FS2 Console Window you click on the “Debug” button to start debugging the active program. This sets up the probe, downloads the program, and executes the start-up code until it gets to the first source line of main(). Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 5 of 34 2.2. Using the HW Triggers and Events Window Once the FS2 Console window is up, open the HW Triggers and Events window by selecting it from the console Window menu. Note: if this results in a message like: “Current System Analyzer for Nios® II Processor system was not built with Data Triggers.” then Data Triggers have not been included in the Nios II JTAG Debug Module of your Nios II processor. Use the JTAG Debug Module window in the Altera SOPC Builder environment (described in the Nios II HW Reference manual) to select the desired debug features. Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 6 of 34 The following screen is an example of the HW Triggers and Events window with a data range trigger condition. On-line help for this window is available from the Help > HW Triggers menu item. This section will describe how to use this window to define events and program triggers from them. The upper pane is the list of defined events, and the buttons on the right side provide creating, editing, and deleting events. The bottom pane is where triggers are created and removed. It expands to hold the triggers that can be created with the hardware in the OCI (On-Chip Instrumentation) block. Events pane buttons:  New Create a new event by bringing up the Edit dialog.  Edit Bring up the Edit Event dialog on the selected event. Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 7 of 34 You can change the name of the event name, which must be unique in the list. Next, select the type. Execution is a new type support which is the equivalent of a HW breakpoint. Data types are READ, WRITE, or both. Next, fill in the Address: field and optional Range which is only for Data event types. If it is a Data type, you can also fill in a Data value field and mask. The bottom status line reports information about the event such as the message that is in the screen shot – “Hardware does not support event: Incomplete event: no address”. Note: there are some event patterns that are not supported by the trigger hardware, such as execution address ranges and Data type data value ranges. These exist for use in the HW Trace window for Finding or Marking trace lines. The other Event pane buttons are:  Duplicate This operation can save time by creating another event with a new name – usually with “new1_” as a prefix – just like the one already selected. Double click or Edit the new event to change one or more of its parameters.  Add to triggers takes the selected event and makes a trigger out of it in the lower pane. Depending on its type it will make a data trigger (0-3) or execution trigger (4-7). Sometimes the button is grayed out which means that it is not possible to make a trigger out of the selected event – either it is not programmed to be a legitimate HW trigger or resources are all used up. The event list has pre-existing events, the number of them depending on the hardware resources built into the Nios II. The maximum number is eight – namely 4 data recognizers named !dbrk0 .. !dbrk3 and 4 execution recognizers named !xbrk0 .. !xbrk3. These events map to what the hardware triggers are programmed to or what it will be programmed to when the next Resume command is given. You can program the pre-existing events directly by editing them (but the names are fixed) or you can drag and drop a user-defined event on top of one which will use the values of that event. These events also reflect the values defined by the trigger command in the FS2 Console window. Refer to the Nios II Hardware Reference manual for the trigger command definitions. HW Triggers pane. The bottom pane holds the currently programmed hardware triggers. Each box is labeled with the trigger number or, if a paired trigger, even and odd numbers (e.g. “Triggers 0 and 1”). The trigger condition is on the left side and the choice of actions on the right. Two buttons – “Create data trigger” and “Create execution trigger” will create a default trigger with the default event in it. You can then edit the condition and/or actions from this point. The Event pulldown (a partial screen shown below) will list all events for that trigger type (execution or data) and you then click on the one you want. You can also drag and drop an event into the Event: field. In the previous screen of the complete HW Triggers and Events window, the programmed trigger is a Data trigger with an address range. The “button_io” event is defined to have an address range of Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 8 of 34 0x920830..0x92083F. For some hardware configurations, state triggering is supported, meaning, there are two conditional states that can be used to qualify the event condition, state 0 and state 1. The State: field allows you to select which of the two states is ANDed to the condition. When the processor is started (Resume’d) from its halted state, the starting trigger state is 0. The Action choices are:  Break Nios – halt the cpu  Trigger out – pulse the trigger out signal on the probe front panel. This signal is also available internally to be routed to other on-chip logic such as another cpu core or SignalTap.  Trace on, off – turn the trace on or turn trace off. These allow conditions to qualify tracing based on event and state conditions. For example, you may only want to trace inside one function, so you define an event recognizing the address of the function entry and define a trigger to turn trace on and define an event for the address of the function exit and define a trigger to turn trace off.  Trace cycle – for a Data event, a match with it and the state will cause that bus cycle to be stored in the trace. This is normally used with the “Collect trace initially” unchecked in the Trace Mode window. It can also be used with “Trace execution” unchecked where the trace only stores these cycles and no others – useful for viewing reads or writes to specific addresses such as hardware ports.  Go to state 0, 1 – The checked action can cause the state sequence to change to state 0 or 1 on the next cycle. This is useful for generating trigger sequences and “window” triggering, where two events can define a trigger window to be open or closed, and a third event to trigger only when the “window” is open. Save and restore Trigger events and setups are saved in the fs2.ini file. When a new debug session is started, these setups are not loaded and programmed into the hardware until the HW Triggers and Events window is opened. 2.3. Hardware Resources The table below indicates the availability of HW Triggers features for the various choices of evaluation boards and JTAG connection types. Basic SDK Kit USB Blaster, ByteBlaster Basic SDK Kit + FS2 Licensed Download. USB Blaster, ByteBlaster FS2 SNav OE /T probe w/external trace 38-pin Mictor target connection EPP Parallel and USB PC host Connection 2 xbrk w/trig control 2 dbrk w/trig control 2-state triggering ------- ------- ------- 4 xbrk w/trig control 4 dbrk w/trig control 2-state triggering stop trace on buffer full ------ ------ 4 xbrk w/trig control 4 dbrk w/trig control 2-state triggering stop trace on buffer full timestamp 128K frames of trace Only two triggers are available for USB Blaster/ByteBlaster. This can be increased to 4 each by purchasing a license from FS2 at http://www.fs2.com/isa -nios.html). Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 9 of 34 2.4. Using the Symbol Window to Program Events and Triggers The Symbol window is opened from the Console Window > Symbol menu. It displays the symbols already loaded by the HW Trace window or allows you to load the symbols in the same way as the HW Trace window does (see section 2.9) An example, taken from the count_binary.c program, follows: You can sort by any of the columns (Type, Name, Address, Size, Filename) by clicking on that column. Type fields are:  left column: g = global, l = local  right column: O = Object or variable, F = function, = label (has address but size is 0) The Search: field allows you to enter a name or a partial name and keep finding the next occurrence of this match. The buttons are:  Load symbol file Brings up a file browser to locate the build file or symbol file. A build file has suffix of .elf, .objdump, or .out. A symbol file is automatically created by this window or the HW Trace window and has a suffix of .fs2.  Refresh If you have rebuilt the software, this button will regenerate the .fs2 file then load it.  Copy name to clipboard Useful if you are creating or editing an event and you want the event name to be the same as the symbol name. After clicking this button, you only have to Ctrl-V into the Edit Event Name: field.  Copy address to clipboard is useful to grab the address and paste it (Ctrl-V) into an address field of an event. The address column is displayed in hex, the size column in decimal. The Filename column shows the path, filename, and line number where the code symbol is located, Drag and Drop is supported between this window and the Event or Trigger panes. You can drop a symbol onto an event in the event pane or in the Edit Event dialog. Note that when dropping symbols Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 10 of 34 like a function, the event is set up to be an execution range, which is not supported by the OCI triggers, so you may want to uncheck the Range checkbox to make it a valid HW trigger. When you drop a symbol into an event, the name of the symbol is held in the address field, not the absolute address. This is useful because if/when you rebuild the software, the symbol address is updated with the new address; you do not have to re-create all your events. Expressions. The address or address range fields of an event support expressions, including the “sizeof()” function. Notice in the dialog box below that the right area (below the Cancel button) shows the current hex value of each field. They update as you type in the expression. Notice also that the Data field is entered in decimal. 2.5. Using the HW Triggers Window to set a breakpoint on a single data address This section uses the Nios II IDE example program count_binary.c, and is built from the niosII_stratix_1s10/full_featured Nios II reference design. The first data trigger example shown below causes the Nios II to break on any access to address 0x920840 which is the Peripheral IO block driving the 8 LEDs. To set this up, first create a default event with the “New” button, change its default name to LED_IO in the Edit Event dialog, then set its address to 0x920840. Set the Type: to Data and check both Read and Write. Use the tab key to move between fields. If a value is prefixed with 0x, the value is hex, if not, the value is decimal. If an invalid address is entered the text will turn red and the last valid entry will be used until the error is corrected. Click OK on the Edit Event dialog. Next we need to create a trigger using this event. Click on the “Create data trigger” button at the bottom of the window then click on the Event list down arrow and select LED_IO. Now set the Action “Break Nios” check box which will halt the processor when the trigger pattern goes true. Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 11 of 34 The Nios II IDE-generated system.h file contains information on each of the peripheral hardware devices. These can be viewed in the Peripheral Window (see later section) which includes a tooltip pop-up that shows the address of the peripheral the mouse pointer is over. 2.6. Triggering on a data address and value To trigger on a specific value written to the LEDs, double click on the LED_IO event. The following Edit Event dialog shows the setup for breaking the Nios II when the value 0x55 is stored (Write) to the LED address: Click OK to close the dialog, then Resume the debugger. The resulting source window looks as follows. Notice when landing the cursor over the “count” variable, the value “85” pops up, which is the decimal equivalent of 0x55. Nios II Software User Guide System Navigator for Nios® II First Silicon Solutions, Inc. Page 12 of 34 2.7. Triggering on a data address range The next example shows a data trigger/event setup over a contiguous range of addresses. The address range is 0x920830 through 0x92083F which is the register range of the peripheral Buttons hardware. Notice that the Data trigger is p