Download Altera Debug Client: Guide for Compiling, Downloading, and Debugging Nios II Apps and more Study notes Microprocessors in PDF only on Docsity!
Altera Debug Client
This tutorial presents an introduction to the Altera Debug Client, which can be used to compile, assemble, download and debug programs for Altera’s Nios II processor. The tutorial gives step-by-step instructions that illustrate the features of the Altera Debug Client. The process of downloading and debugging a Nios II application requires the presence of an actual FPGA device to implement the Nios II processor. For the purposes of this tutorial, it is assumed that the user has access to the Altera DE2 Development and Education board connected to a computer that has Quartus II (version 5.1 or higher) and Nios II software installed. The screen captures in the tutorial were obtained using version 2.2 of the Altera Debug Client; if other versions of the software are used, some of the images may be slightly different.
Who should use the Altera Debug Client
The Altera Debug Client is intended to be used in an educational environment by professors and students. For commercial system and application development, Altera’s Nios II Integrated Development Environment should be used.
Contents
- 1 Installing the Altera Debug Client
- 2 Starting the Altera Debug Client
- 3 Configuring a Nios II System
- 4 Configuring a Nios II Program
- 5 Compiling and Loading the Program
- 6 Running the Program
- 7 Using the Disassembly Window
- 8 Single step
- 9 Using Breakpoints
- 10 Examining and Changing Register Values
- 11 Examining and Changing Memory Contents
- 12 Setting a Watch Expression
- 13 Examining the Instruction Trace
- 14 Using Configuration Files
- 15 Using the Terminal
Figure 2. Altera Debug Client Install Wizard.
Figure 3. Choosing which components to install.
- The installer is now ready to begin copying files. Click Install to install the Debug Client. During the installation process, you will be asked if you would like a shortcut to the Altera Debug Client to be placed on your Windows Desktop. Answering yes will install an icon similar to the one shown in Figure 5 on your desktop.
- Assuming that the install was successful, the screen shown in Figure 6 will be displayed. Click on the Finish button to complete the installation. Should an error occur, a window will suggest the appropriate action. Errors include: - Quartus II Software is not installed or the Quartus II version is too old. - Nios II SDK Software is not installed or the version is too old.
Figure 4. Specifying the installation location of the tutorial and sample files.
Figure 5. Altera Debug Client desktop icon.
Figure 6. Altera Debug Client installation finished.
3 Configuring a Nios II System
Nios II systems have a user-configurable architecture. The designer may choose from a variety of peripherals and memory options in Altera’s SOPC Builder. The Altera Debug Client needs information describing the Nios II system that is being targeted in order to compile and load programs for the system. Systems created by Altera’s SOPC Builder are described by a .ptf file located in the Quartus II project’s main directory. This file contains information about all the peripherals connected to the Nios II processor, including the system memory map. To describe the Nios II system to the Debug Client, click the Nios II > Configure system... menu item or click
the toolbar button. The Nios II System Configuration window will appear, similar to Figure 8. Proceed with the steps below to configure the example system.
Figure 8. Initial Nios II System Configuration window.
- Select the cable from the Cable drop-down list that corresponds to the DE2 board. The DE2 board is connected via a USB-Blaster cable.
- Click Browse... to display a window similar to Figure 9. Navigate to <TUTORIAL_FILES>\example\hw\system.ptf, which is the system description file for the example sys- tem. Select system.ptf and click Load.
Figure 9. Select system description file window.
- In the System Configuration window in Figure 8, click Load. The fields in the .text section and .data section will now be enabled.
- Nios II programs are compiled into an Executable and Linking Format (ELF) file. This format supports sections, which can be used to divide a program into multiple parts, such as an executable code section and a data section. Each section has its own set of attributes, including memory location, alignment, and size. The partitioning of a program into different sections is performed by the linker, which receives this information via either a linker script or linker invocation arguments. The Altera Debug Client allows the user to specify the linker arguments for two sections of the program, as described below. Each section will be placed at the address value of base address of memory device + start offset. If a start offset is not specified, its default value will be zero. The .text section contains the program machine code. The .text section of the System Configuration window is used to place the machine code at different memory locations. Use the following settings: - Memory device: memory/s1 (0h - 7fffh), corresponding to the on-chip memory of the Nios II system (this is the default and only choice in the example system.ptf that we are using) - Start offset in device: 1000 , corresponding to a 4096-byte offset into the on-chip memory to start the .text section
The .data section contains program data, such as variables or constants. The .data section of the System Configuration window is used to place the data at different memory locations. Use the following settings:
- Memory device: memory/s1 (0h - 7fffh), corresponding to the on-chip memory of the Nios II system (this is the default and only choice in the example system.ptf that we are using)
- Start offset in device: 1000 , corresponding to a 4096-byte offset into the on-chip memory to start the .data section. Note that the .text and .data offsets are the same, which would lead to an overlap of the two sections in memory. However, because the two offsets are exactly the same, the linker script used to produce the program executable will instead automatically place the .data section immediately after the .text section.
- If there is more than one terminal device available in the system, one can be chosen from the Terminal device list to be connected to the terminal in the Debug Client. In this example, jtag_uart is the only terminal device present.
- Your system configuration should appear as shown in Figure 10. Click OK to save the system configuration.
Figure 10. Nios II System Configuration window configured for the example system.
Figure 13. Nios II Program Configuration window configured for the example program.
5 Compiling and Loading the Program
After successfully configuring the system and program, the program can be compiled and downloaded onto the DE2 board. There are three different commands that can be used to compile and/or load a program:
- Actions > Compile menu item or toolbar button: Compiles the source files into an ELF and SREC file. Build warnings and errors will show up in the Info & Errors window. The generated ELF and SREC files are placed in the same directory as the first source file.
- Actions > Load menu item or toolbar button: Loads the compiled SREC file onto the board and begins a debugging session in the Debug Client. Loading progress messages are displayed in the Info & Errors window.
- Actions > Compile & Load menu item or toolbar button: Performs the operations of both compilation and loading. In this example, the program has not yet been compiled, so it cannot be loaded (the Load option is disabled).
Click the Actions > Compile & Load menu item or click the toolbar button to begin the compilation and loading process. Throughout the process, messages are displayed in the Info & Errors window. The messages should resemble those shown in Figure 15. After successfully completing this step, your Debug Client display should look similar to Figure 16. At this point, the program is paused at its first instruction.
Figure 14. A compiler error message.
Compilation errors
During the process of developing software, you will likely encounter compilation errors. Error messages from the Nios II assembler or from the C compiler are displayed in the Info & Errors window. An example of a compiler error message is shown in Figure 14. The file name and the line number corresponding to the source of the error are displayed, in addition to an indication of the cause of the error. You may be able to deduce the real cause of the error from the message or you may need to do some additional searching.
Figure 15. Compilation and loading messages (the Info & Errors window has been maximized).
Figure 16. The Altera Debug Client window after loading the example program.
settings can be changed by right-clicking on the window and selecting the appropriate menu item, as shown in Figure 18. The display in the window also uses a color-coded scheme, as detailed in Table 1.
Figure 18. Pop-up menu to configure the display of the Disassembly window.
Color Description Brown Source code Green Disassembled instruction name Blue Registers Orange Immediate & offset values Dark blue Address values & labels Purple Clickable link Gray Machine encoding of the instruction
Table 1. Disassembly window color-coded scheme.
By scrolling using the vertical scrollbar on the right side of the Disassembly window or by using a mouse scroll wheel, different regions of memory can be disassembled and displayed. It is also possible to scroll to a memory address or an instruction symbol directly by using the Goto instruction panel in the Disassembly window. Access this panel through the Actions > Goto instruction... menu item and enter a symbol name or an instruction address in hexadecimal format. The instruction address must be a multiple of 4 because every instruction address is aligned on a 32-bit word boundary. For example, enter _start or 1000 and press Go. The Disassembly window will show the 0x00001000 address as its first instruction, as shown in Figure 19, which also corresponds to the _start symbol. Also note that the instruction is highlighted with a pink background.
Figure 19. Goto instruction panel in the Disassembly window.
Register and memory values can be examined in the Disassembly window while the program is in a Paused state. This is done by hovering your mouse over a register or a register + offset in the window, as shown in Figure 20. The Disassembly window also produces special clickable links in its display of branch instructions. Clicking one of these links will display the instruction that the processor would jump to if the branch was taken. Figure 21 shows one example of a link associated with a call instruction.
Figure 20. Examining a memory value in the Disassembly window.
Figure 21. A clickable link in the Disassembly window.
Assembly Language and Machine Instructions
The Disassembly window is a good place to examine what machine instructions are produced by the compiler from your assembly-language instructions or C code. The translation from assembly-language instructions to machine instructions is handled by the Nios II assembler and it is a transparent process to the programmer. However, it is beneficial to examine the disassembled code and compare it with the source code. This is readily done because the Debug Client displays both the source statements and the disassembled code in different colors. Observe that pseu- doinstructions are implemented as different machine instructions. For example, the movia pseudoinstruction is implemented by the two instructions orhi and ori, as shown at the address values 0000102c and 00001030 , respectively, in Figure 17.
8 Single step
Before discussing the single step action, it is convenient (for demonstration purposes) to restart execution of the
program from the beginning. Click the Actions > Restart menu item or click the toolbar button to restart the program. Notice that the pc register value displayed in the Registers window is 0x00001000 and the Disassembly window is highlighting that instruction. The Debug Client has the ability to perform single step actions. Each single step consists of executing a single machine instruction and returning control to the Debug Client. Note that if the program being debugged was written in C, each individual single step will still correspond to one assembly language instruction generated from the C code. The ability to step through statements in the high-level source code is not supported by the Debug Client; however, Altera’s Nios II Integrated Development Environment supports this advanced feature. The single step action is invoked by clicking on the Actions > Single step menu item or by clicking on the toolbar button. The instruction that is executed by the processor is the one highlighted by the Disassembly window before the single step. Since the first step in this section was to restart the program, the first single step will execute the instruction at 0x1000, which will zero out the upper-16-bits of the sp register. Subsequent single steps will continue to execute one instruction at a time, in sequential order. Single stepping at a branch instruction may jump to a non-sequential instruction address if the branch is taken. You can observe this behavior by single stepping to 0x00001028, which is a call instruction. Single stepping at this instruction will set the pc value to 0x000011b0, which is the location of the UPDATE_HEX_DISPLAY label.
Figure 23. The Debug Client after the breakpoint has been triggered.
Figure 24. Breakpoints window.
- The window in Figure 26 will appear. This window contains information about the syntax used to describe a condition. For this example type r2 == 0.
- Press Ok. The Condition field for the breakpoint will now show the condition you entered.
The conditional breakpoint is now set. Run the program and as the dE2 digits on the hexadecimal display disappear and the program begins to shift the digits to the left, the breakpoint will trigger. The Info & Errors
Figure 25. Adding a breakpoint, in this case a write watchpoint, in the Breakpoints window.
Figure 26. Edit breakpoint condition window.
window will again have a message about the cause of the breakpoint, including the trigger condition that was satisfied, as shown in Figure 27.
Figure 27. Message displayed in the Info & Errors window due to a triggered conditional breakpoint.
10 Examining and Changing Register Values
The Registers window displays the value of each register in the Nios II processor and allows the user to change most of the register values. The number format of the register values can be changed by right-clicking in the Registers window, as shown in Figure 28. You can choose among binary, octal, decimal, and hexadecimal repre- sentations in both signed and unsigned versions. Every time program execution is stopped, the debugger updates all of the register values and highlights any changes in red. The user can also change the register values while the program is stopped. As a demostration of changing a register value, this section of the tutorial will set a breakpoint to halt the program when the hexadecimal display is showing ....dE2. (. represents a blank) and the scroll direction is to the right. When the breakpoint is triggered, you will toggle the shift direction via the Registers window and then resume program execution. The detailed steps are as follows:
- Eventually the conditional breakpoint that was set in step 2 will trigger again. Continue on to the next section of the tutorial when this occurs.
11 Examining and Changing Memory Contents
The Memory window displays the contents of the system’s memory space and allows the user to edit its values. The memory display will look similar to Figure 30, with hexadecimal addresses in the left-most column and consecutive values displayed horizontally. The numbers at the top of the window represent hexadecimal address offsets from the corresponding address in the left-most column. For example, referring to Figure 30, the address of the last word in the second row is 0x00000010 + 0xc = 0x0000001c.
Figure 30. Example Memory window.
The display is configurable by a number of parameters:
- Memory element size: the display can format the memory contents as bytes, half-words (2-bytes), or words (4-bytes). This can be configured from the context menu accessible by right-clicking on the Memory window, as shown in Figure 31.
Figure 31. View as menu used to select the memory element size in the Memory window.
- Number of words per line: the number of words per line can be configured to make it easier to find memory addresses. This can be configured from the context menu accessible by right-clicking on the Memory window, as shown in Figure 32.
- Number format: this is similar to the number format option in the Register window. This can also be configured from the context menu accessible by right-clicking on the Memory window.
Figure 32. Number of words per line menu in the Memory window.
- Display order: the display can display addresses increasing from left-to-right or right-to-left. Configure this option by right-clicking on the Memory window, as shown in Figure 33.
Figure 33. Display order menu in the Memory window.
Similar to the Disassembly window, you can view different memory regions by scrolling using the vertical scroll bar on the right or by using a mouse scroll wheel. There is also a Goto memory address panel in the Memory window analagous to the Goto instruction window. Click the Actions > Goto memory address... menu item to display the Goto memory address panel. As shown in Figure 34, you can enter any address in hexadecimal, press Go, and the Memory window will display that address. In this example, display the 11f address, which is where the buffer used by the program is stored.
Figure 34. Goto Memory Address window.
Since the program reads from this buffer and passes the value to the hexadecimal display, the value shown on the hexadecimal display can be changed by changing the memory value. Proceed as follows:
