= Using the Xilinx SDK Debugger = Sometimes it is necessary to use the debugger within the Xilinx SDK to help debug problems within the code running on a Microblaze processor in an WARP reference design. The debugger can set break points and step through code line-by-line. However, the mapping of C code to machine instructions may not be one-to-one due to some of the compiler optimizations that the reference designs were forced to turn on to save code space. This tutorial goes through the process of setting up the debugger; starting the debugger and running code with the debugger. You can find additional information on the Xilinx SDK debugger on the Xilinx website. NOTE: This tutorial is based on [wiki:802.11/Download 802.11 Reference Design v1.3.0] but the concepts should apply generically. '''Limitations:''' Even though a reference design can have multiple CPUs, the debugger can only debug one of the processors at a time. Whichever processor(s) are not being debugged will be free running in the background waiting on any interrupts / IPC messages from the processor that is being debugged. For example, in the case of the 802.11 Reference design the debugger can operate on either CPU_HIGH or CPU_LOW but not both. == Setting up the Debugger == 1. Click and highlight the project in the "Project Explorer" window to debug. For example, in the 802.11 Reference design, lets debug the "AP" code in CPU_HIGH. For this, click and highlight the {{{wlan_mac_high_ap}}} project. 2. Set up the "Debug Configurations". To do this either: a. At the top of the screen in the main tool bar, click the small arrow next to little bug icon (if you mouse over this icon it will say "Debug As...") and select "Debug Configurations..."; or b. From the menus, select "Run" --> "Debug Configurations..." [[Image(init_debug_configurations.png, 600px)]] 3. In the left pane of this new window, click and highlight "Xilinx C/C++ ELF". 4. In the toolbar of this window, there is an icon that looks like a sheet of paper with a "+" icon the top corner (if you mouse over this icon it will say "New launch configuration"). Click this icon. Alternately, you can double click the "Xilinx C/C++ ELF" configuration. [[Image(elf_debug_configuration.png, 600px)]] 5. A new launch configuration will appear in the left pane under "Xilinx C/C++ ELF" whose name will match the project highlighted in the first step. For the AP, the name will be {{{wlan_mac_high_ap Debug}}}. In the right pane, there are a few tabs that can be altered: a. '''"Debugger Options" tab:''' 1. (Optional) Uncheck the "Stop at main() when debugging". Having this box checked will cause the debugger to place a breakpoint at the first line of the main() function. This will cause the debugger to stop at the beginning of main() after you attach the debugger and require you to press the "Play" button to start code execution. b. '''"Common" tab:''' 1. (Optional) Check the box next to "Debug" to display this debug configuration in the favorites menu. 2. (Optional) Uncheck the "Allocate Console (necessary for input)". There is a UART-over-JTAG protocol, but that has not been configured in the FPGA hardware project. Finally hit "Apply" and "Close." == Starting the Debugger == 1. Program the WARP board like normal using the menu "Xilinx Tools" --> "Program FPGA". In the dialog box that pops up, there is an ELF file listed in each of the processors in the reference design. Click on the arrow next to the ELF for the processor to be debugged and select "bootloop". For example, to debug the AP code in CPU_HIGH, select "bootloop" for {{{mb_high}}} and make sure that the appropriate ELF file is selected for {{{mb_low}}}. Then select "Program". [[Image(program_fpga.png, 600px)]] The reason to use "bootloop" is so that the ELF is only downloaded when the debugger is attached. This will prevent any race conditions / initialization issues that might occur by having the ELF run before the debugger is attached. 2. Click the arrow next the the "bug" icon again. This time, click the name of the configuration created earlier. In the case of the "AP", the name will be {{{wlan_mac_high_ap Debug}}}. This will attach the debugger and download the AP ELF. This process will take some time. 3. There might be a couple of pop-up windows that will appear (feel free to select the box to ignore this message in the future): a. '''Reset status''': This is an informative message and can be ignored b. '''Perspective Switch''': This is also an informative message. Select "Yes". [[Image(perspective_switch.png, 600px)]] == Using the Debugger == 1. The Debug perspective is pretty intuitive and makes it easy to add breakpoints, read and write specific memory addresses, etc. [[Image(debug_view.png, 600px)]] 2. Depending on your debug configuration options, the code will automatically begin to run or the code will be stopped at the beginning of main() and the "Play" button at the top of the screen will start the execution of the code. The code execution will automatically pause if it runs into a breakpoint or you can manually press the "Pause" button to see where the state of the code and any variables. [[Image(debug_pause.png, 600px)]] 3. When you are finished debugging, use the "Stop" button to terminate the debugger. To return to the "C/C++" view, select that (instead of the "Debug" view) from the menu in the upper right-hand corner of the SDK window. If you have any questions, please use the [http://warpproject.org/forums/ forums].