SimXMD User Guide (c)2013 Ruediger Willenberg, University of Toronto Last updated: September 4, 2013 Support and prerequisites This software is developed and tested on the following system: Processor: x86 64 OS: 64-bit-Linux Kernel: 3.4.33.-2.24-desktop Distribution: OpenSUSE 12.2 Desktop: KDE 4.8.5r2 Qt framework 4.8.1 (minimum: 4.7) Xilinx EDK 14.2 (minimum: 13.1) MentorGraphics ModelSim SE 10.1c (minimum: 6.6) EDK simulation libraries compiled with compedklib for the installed ModelSim version I expect this to work on a lot of other constellations (e.g. other Linux systems, other Qt versions, Xilinx and ModelSim tool versions), but there has been no extensive testing. If you can report success, consider emailing me at [email protected] (please put [SimXMD] into the subject line). You should have the Qt cross-platform application framework (version 4.7 or newer) installed (SimXMD has not been tested with versions 5.x). It can be downloaded at http://qt-project.org/downloads Installation To install SimXMD follows these steps: • Open a terminal • Set the environment variable MODELSIM PATH to ModelSim's installation path example for bash: > export MODELSIM PATH=/opt/Modelsim/10.1c/ • Enter the unzipped SimXMD source directory • On the command-line, enter: > qmake > make > sudo make install SimXMD is installed into /usr/local/bin/simxmd by default. To change the installation path, set the environment variable SIMXMD PATH before calling qmake. If you install SimXMD to a location in your home directory, you don't need to use sudo for make install. NOTE: SimXMD needs the PATH variable to point towards various EDK commandline tools. Since the simplest way to start SimXMD will often be directly out of an EDK project, I suggest to add a path to SimXMD into the script(s) you use to setup a working environment for your Xilinx and ModelSim tools anyway. As an example, a bash script could be easily extended this way: export PATH=/usr/local/bin/simxmd/:$fPATHg 1 SimXMD User Guide (c)2013 Ruediger Willenberg, University of Toronto A Quick Start Debugging with SimXMD can always be started in four quick steps: • Generate a simulation model with XPS • Let SimXMD modify the simulation model • Initiate the simulation • Connect to the simulated MicroBlaze processor with a debugger of your choice The SimXMD sources include an example project for EDK versions 14.x, with all the project settings ready to jump right in. The later chapters will explain the limited number of steps necessary to make your own projects work with SimXMD. This example assumes that you start Xilinx Platform Studio with the path settings recommended above. 1. Extract the demo project in $SIMXMD SOURCE/xps demo project/SimXMD Demo v14.tar.gz 2. Start XPS and open the project. Depending on your EDK version, XPS will suggest to update certain pcores to newer versions, or in some rare cases even tell you it can't auto-update because newer versions are not downwards compati- ble. In the latter case, try to edit the version in the system.mhs file by hand to an available one; there are rarely real compatibility issues. Select Project ! Export Hardware Design to SDK to launch the Xilinx SDK; make sure that Include Bitstream and BMM file is unchecked so that XPS does not implement the hardware. When prompted, enter the workspace path ./SDK. Make sure to re-build everything by selecting Project ! Clean.... Close the SDK. This is a simple project with a MicroBlaze, on-chip BlockRAM for code and data and two periph- erals connected through Fast Simplex Links (FIFOs). The first peripheral is a network component that will receive encrypted packets of 32-bit words. The second component is a co-processor that can decrypt the packets. 3. Export the simulation model by selecting Simulation ! Generate Simulation HDL files. 4. Start SimXMD by pushing the left X-shaped custom command button. SimXMD will start in GUI mode with three text fields logging debugger communication, processor- specific data and simulator communication. The GUI is purely optional for those logging purposes and for interactive changes of project options. Alternatively, you can start the console version of SimXMD by pushing the right X-shaped custom command button. In the background, SimXMD automatically parsed the project data and modified the simulation model when it was started. The only indication of this is that the central logging window in the GUI shows some information about the selected processor and its assigned binary. 5. Go back to XPS. Start the simulator by selecting Simulation ! Launch HDL Simulator 6. In the ModelSim console, type > do sx start.do ModelSim now compiles the simulation model, starts the simulation and populates the wave win- dow, all of it using the scripts generated for these purposes by XPS and SimXMD . 2 SimXMD User Guide (c)2013 Ruediger Willenberg, University of Toronto Additionally, SimXMD modifications add a few waveforms that illustrate the processor's execution state. The added scripts also start a TCP server that can automatically receive ModelSim commands from SimXMD and run the binary execution to the beginning of main(). Finally, an extra SimXMD menu is added to ModelSim so that any control of SimXMD can be exerted through the ModelSim GUI. SimXMD itself, with or without GUI, can always stay in the background. After the startup, SimXMD should automatically connect to ModelSim's TCP port. This is visible in Modelsim's wave window through a thin white cursor that marks the upcoming processor instruction (the first instruction of main()). The white cursor is also designated RUN MODE in the bottom of the wave window (more about modes later). We can now connect a debugger! 7. Select the ModelSim menu entry SimXMD ! Start command-line GDB. A terminal window with the command-line version of the GNU debugger should open and indicate it is connected to the processor with the binary execution at the start of main(). You can now freely debug the program running on the simulated MicroBlaze. As an example, display the current program counter at main() with (gdb) display $pc Now use the program counter value (e.g. 0x24c)) to read the first instruction word in main() (gdb) x /1xw 0x24c or disassemble that instruction with (gdb) disas 0x24c,+4 You can cross-check all three results in the top of the wave window at the white Run mode cur- sor. 8. Close GDB and select the ModelSim menu entry SimXMD ! Start Xilinx SDK debugger. Xilinx SDK starts in the workspace managing the Microblaze software project network rx test, which has also been assigned to the processor for simulation in XPS. A specific debug configuration for the project named SimXMD microblaze 0 has been added to the workspace. You can activate it by press- ing F11 or clicking on the bug icon. SDK will connect to the simulator through SimXMD, the same way that the command-line GDB did. It will display all the typical trappings of a graphical debugger, a source code window indicating the code position, variable and register displays etc. Use the keys or buttons for step, step over, finish and continue (with breakpoints) to move code execution forward. In the simulator's wave window, you can see how the simulation moves forward in the same steps. At any time, the debugger will display accurate register, variable and memory state of the moment that is marked by the white cursor in the waveform window. 3 SimXMD User Guide (c)2013 Ruediger Willenberg, University of Toronto Run Replay Run x2 0x3 0x4 0x5 x2 0x3 0x4 0x5 x2 0x3 0x4 0x5 x2 0x3 0x4 0x5 0x6 (A) PC = 5 (B) PC = 5 (C) PC = 3 (D) PC = 6 int main() int main() int main() int main() { { { { a = functionA(); a = functionA(); a = functionA(); a = functionA(); b = functionB(a); b = functionB(a); b = functionB(a); b = functionB(a); c = b + 5 * d; c = b + 5 * d; c = b + 5 * d; c = b + 5 * d; return c; return c; return c; return c; } } } } Debugging in Run and Replay modes SimXMD can run in two different modes, the previously mentioned Run mode and Replay mode: • Run mode, which SimXMD starts in when connecting to the simulator, always transmits the most recently simulated processor state to the debugger. Any Step or Continue command from the debugger results in running the simulation up to the next break condition. • Replay mode parses earlier processor and memory state information and therefore allows \re-executing" earlier code in the debugger. This is useful because it allows to home in on earlier time stretches in simulation where problems have been identified in the hardware signals. These critical areas can be re-executed and debugged unlimited times. The figure above illustrates how to use modes and switch between them: A. Debugging starts in Run mode as described. The ModelSim wave window will show a white locked cursor at the most recent instruction. The cursor name RUN MODE appears at the bottom of the window. B. To switch to Replay mode, mark the moment in simulation that you would start debugging from with an active cursor. Choose the menu entry SimXMD ! Debug from Cursor (Replay Mode) in ModelSim. SimXMD marks the time with a locked white cursor named GO TO CURSOR and pops up a dialog informing you to press Step or Continue in the debugger to complete the transition. At this point, the debugger is unaware of the change and still shows the most recent Run mode code position. C. As soon as the user selects Step or Continue, SimXMD finds the next break time, positions the white locked cursor there and names it REPLAY MODE.