Lauterbach MicroBlaze Debugger User manual

MANUAL
Release 09.2021
MicroBlaze Debugger and Trace

MicroBlaze Debugger and Trace | 2
©1989-2021 Lauterbach GmbH
MicroBlaze Debugger and Trace
TRACE32 Online Help
TRACE32 Directory
TRACE32 Index
TRACE32 Documents ...................................................................................................................... 
ICD In-Circuit Debugger ................................................................................................................ 
Processor Architecture Manuals .............................................................................................. 
MicroBlaze ............................................................................................................................... 
MicroBlaze Debugger and Trace ......................................................................................... 1
General Note ...................................................................................................................... 4
Brief Overview of Documents for New Users ................................................................. 4
MicroBlaze debug and trace features supported by TRACE32 .................................... 5
ESD Protection .................................................................................................................. 6
Quick Start of the Debugger ............................................................................................. 7
Quick-Start of the Real-Time Trace ................................................................................. 10
Compiling Software with Debug Information ................................................................. 11
Troubleshooting ................................................................................................................ 12
SYStem.Up Errors 12
FAQ ..................................................................................................................................... 12
Displaying MicroBlaze Core Configuration .................................................................... 13
CPU specific Implementations ......................................................................................... 14
Memory Accesses Causing Bus Errors 14
Breakpoints 15
Software Breakpoints 15
On-chip Breakpoints 15
Breakpoints in ROM 15
Example for Breakpoints 16
SYStem.Option.BrkHandler Control writing of software break handler 17
SYStem.Option.BrkVector Configures an alternative breakvector 17
SYStem.Option.IMASKASM Interrupt disable on ASM 18
SYStem.Option.IMASKHLL Interrupt disable on HLL 18
SYStem.Option.LittleEndian Select little endian mode 18
SYStem.Option.MMUSPACES Separate address spaces by space IDs 18
SYStem.Option.ResetMode Select the reset mode 19
SYStem.Option.DUALPORT Use real-time access by default 20

MicroBlaze Debugger and Trace | 3
©1989-2021 Lauterbach GmbH
SYStem.Option.MDMSINGLELMB Use MDM LMB master 0 for all cores 20
TERM.METHOD.MDMUART Terminal configuration 20
Memory Classes 22
Register Names 22
CPU specific SYStem Commands ...................................................................................23
SYStem.CPU Select the used CPU 23
SYStem.JtagClock Selects the frequency for the debug interface 24
SYStem.LOCK Lock and tristate the debug port 24
SYStem.MemAccess Run-time memory access 25
SYStem.Mode Select operation mode 26
SYStem.CONFIG Configure debugger according to target topology 27
Daisy-Chain Example 29
TapStates 30
SYStem.CONFIG.CORE Assign core to TRACE32 instance 31
SYStem.CONFIG.state Display target configuration 32
SYStem.CONFIG.MDM.DebugPort Set core to debug 32
SYStem.CONFIG.MDM.RESet Reset MDM configuration 32
SYStem.CONFIG.MDM.view Display MDM configuration 33
SYStem.CONFIG.MDM.UserInst Set default user BSCAN port 33
TrOnchip Commands ........................................................................................................ 34
TrOnchip.state Display on-chip trigger window 34
TrOnchip.RESet Set on-chip trigger to default state 34
TrOnchip.CONVert Adjust range breakpoint in on-chip resource 34
TrOnchip.VarCONVert Adjust complex breakpoint in on-chip resource 35
CPU specific MMU Commands ........................................................................................ 36
MMU.DUMP Page wise display of MMU translation table 36
MMU.List Compact display of MMU translation table 37
MMU.SCAN Load MMU table from CPU 39
Real-Time Trace ................................................................................................................. 40
SYStem.Option.DTM Control data trace messages 40
SYStem.Option.QUICKSTOP Control trace of software breakpoints 40
Configuring your FPGA .................................................................................................... 41
JTAG Connector ................................................................................................................ 42
Mechanical Description 42
JTAG Connector for Xilinx Microblaze 42

MicroBlaze Debugger and Trace | 4
©1989-2021 Lauterbach GmbH
MicroBlaze Debugger and Trace
Version 04-Nov-2021
General Note
Before starting please be sure to have up to date debugger software by getting an update from the
LAUTERBACH website. Note that the downloads on the website are stable releases but not necessarily the
latest versions. Therefore in case of problems please contact LAUTERBACH support at
suppor[email protected] for getting the latest software update.
Brief Overview of Documents for New Users
Architecture-independent information:
•“Debugger Basics - Training” (training_debugger.pdf): Get familiar with the basic features of a
TRACE32 debugger.
•“T32Start” (app_t32start.pdf): T32Start assists you in starting TRACE32 PowerView instances
for different configurations of the debugger. T32Start is only available for Windows.
•“General Commands” (general_ref_<x>.pdf): Alphabetic list of debug commands.
Architecture-specific information:
•“Processor Architecture Manuals”: These manuals describe commands that are specific for the
processor architecture supported by your debug cable. To access the manual for your processor
architecture, proceed as follows:
- Choose Help menu > Processor Architecture Manual.
•“OS Awareness Manuals” (rtos_<os>.pdf): TRACE32 PowerView can be extended for operating
system-aware debugging. The appropriate OS Awareness manual informs you how to enable the
OS-aware debugging.
Please note that multicore configuration will be required in most cases, even when there is only a single
Microblaze processor in the target. For information about setting up multicore-configuration see the
application note “Connecting to MicroBlaze Targets for Debug and Trace” (app_microblaze.pdf).

MicroBlaze Debugger and Trace | 5
©1989-2021 Lauterbach GmbH
MicroBlaze debug and trace features supported by TRACE32
TRACE32 for MicroBlaze supports the following features:
• Basic debugging (stop, go, software breakpoints, ...).
• Debugging Linux kernel code and user applications.
• MMU translation.
• Onchip breakpoints (program breakpoints, data write and read breakpoints).
• Off-chip program and data trace are supported via the MicroBlaze Debug Module (MDM).
• Use the Xilinx Vivado Design Suite for hardware analysis and the Lauterbach TRACE32
infrastructure for software debugging - over a single (shared) connection to the target board via
Lauterbach hardware. For more details, see “Integration for Xilinx Vivado” (int_vivado.pdf).
NOTE: • As onchip breakpoints require additional FPGA resources and may slow
down the maximum frequency of a MicroBlaze design, it is necessary to
explicitly configure them in the FPGA design.
• Trace via the MicroBlaze Debug Module requires at least Vivado 2018.3
or Vivado 2018.2 with a special patch, see Xilinx application note
AR71422.
• There is a deprecated MicroBlaze trace IP (Xilinx MicroBlaze Trace Core,
XMTC). Support for this IP has ended with Xilinx EDK 12.4. This trace is
no longer supported with TRACE32.

MicroBlaze Debugger and Trace | 6
©1989-2021 Lauterbach GmbH
ESD Protection
WARNING: To prevent debugger and target from damage it is recommended to connect or
disconnect the Debug Cable only while the target power is OFF.
Recommendation for the software start:
1. Disconnect the Debug Cable from the target while the target power is
off.
2. Connect the host system, the TRACE32 hardware and the Debug
Cable.
3. Power ON the TRACE32 hardware.
4. Start the TRACE32 software to load the debugger firmware.
5. Connect the Debug Cable to the target.
6. Switch the target power ON.
7. Configure your debugger e.g. via a start-up script.
Power down:
1. Switch off the target power.
2. Disconnect the Debug Cable from the target.
3. Close the TRACE32 software.
4. Power OFF the TRACE32 hardware.

MicroBlaze Debugger and Trace | 7
©1989-2021 Lauterbach GmbH
Quick Start of the Debugger
For getting started with debugging, the installation DVD contains sample bit streams and scripts for ML310,
ML403, Spartan3EStarter, Spartan3ADSP1800Starter boards. You find them in the TRACE32 demo folder:
~~/demo/microblaze/hardware
The following example uses ML403. Configure the target with the bit stream
~~/demo/microblaze/hardware/memecfx12lc/stopandgo/download.bit
The FPGA configuration can be done using Xilinx Vivado (or its predecessor Xilinx iMPACT) or the
TRACE32 command JTAG.PROGRAM (or the old version of the command, JTAG.LOADBIT).
After starting the TRACE32 software enter the following commands for connecting to the target and load a
sample file:
Multicore configuration will be required in most cases, even when there is only a
single Microblaze processor in the target. For information about setting up
multicore-configuration see the application note “Connecting to MicroBlaze
Targets for Debug and Trace” (app_microblaze.pdf).

MicroBlaze Debugger and Trace | 8
©1989-2021 Lauterbach GmbH
1. Select the correct endianness of your core:
2. Configure multicore settings for telling the debugger where the MicroBlaze core is located in the
JTAG scan chain. If in doubt, you can use the command SYStem.DETECT.SHOWChain to get a
list of all JTAG TAPs. The correct TAP to use is the one of the Xilinx FPGA. For example, for the
Xilinx EVB ML403 use the following settings:.
3. If your FPGA design contains multiple MicroBlaze processors, select which one you want to
debug:
4. Attach to the target and enter debug mode, using the multicore settings from above:
This command resets the CPU and enters debug mode. After executing this command, memory and
registers can be accessed.
SYStem.Option.LittleEnd ON
SYStem.CONFIG.IRPOST 28.
SYStem.CONFIG.IRPRE 8.
SYStem.CONFIG.DRPOST 2.
SYStem.CONFIG.DRPRE 1.
; Note the ´.´ indicating
; decimal numbers.
; Setting "Specifies the JTAG user-defined register used" in the
; Vivado MDM configuration dialog or configuration C_JTAG_CHAIN
SYStem.CONFIG.MDM UserInst USER2
; Which MDM debug port your core is connected to, valid range
; 0.--31.
SYStem.CONFIG.MDM DebugPort 0.
SYStem.Up

MicroBlaze Debugger and Trace | 9
©1989-2021 Lauterbach GmbH
5. Load a sample program..
Note the option /CYGDRIVE. As the Xilinx MicroBlaze compiler is executed within a Cygwin
environment it creates debug symbols with paths beginning with \cygdrive\c\. By using the
option /CYGDRIVE TRACE32 internally converts this prefix to the correct syntax e.g. to c:\ on
windows hosts. Refer for more information to Data.LOAD.Elf.
6. Open the disassembly and register windows:
7. You are now ready to debug your program.
CD ~~/demo/microblaze/hardware/ml403/mb.v710d.xmtc.100b.noddrram
Data.LOAD.Elf sieve_00000000.elf /CYGDRIVE
Data.List ; Open disassembly window
Register ; Open register window

MicroBlaze Debugger and Trace | 10
©1989-2021 Lauterbach GmbH
Quick-Start of the Real-Time Trace
To use real-time trace, you first have to correctly configure the block design in Vivado. Also note that you
need at least Vivado 2018.3 or Vivado 2018.2 with a special patch from Xilinx answer record AR71422.
1. In the configuration dialog of the core, select “Advanced” at the top, Navigate to the tab “Debug”
and select “External Trace” and set “Trace Buffer Size” to “8kB”.
2. In the configuration dialog of the MicroBlaze Debug Module, set “Select External Trace Output
Interface” to “EXTERNAL” and set “External Trace Data Width” to twice the desired trace port
width (number of data pins connected from the FPGA to the off-chip trace connector).
3. In the “Block Properties” of the MDM, set “CONFIG.C_TRACE_PROTOCOL” to 1. Alternatively,
use the following command in the TCL console, assuming your MDM has the default instance
name “mdm_0”:
4. Connect an appropriate clock signal to the TRACE.TRACE_CLOCK port and export the
TRACE.TRACE_DATA signal. Also export the that feeds TRACE.TRACE_CLOCK. Leave
TRACE.TRACE_CLK_OUT and TRACE.TRACE_CTL unconnected.
5. Use ODDR buffers to create DDR (double data rate) signalling on the external trace port. Refer
to ~~/demo/microblaze/etc/hdl/mdm_parallel_trace_adapter.vhd in your TRACE32 installation
directory for an example module you can instantiate in your block design.
After you have programmed your modified design to the FPGA, connect for debugging as usual. To
configure and enable trace, use the following commands:
set_property CONFIG.C_TRACE_PROTOCOL 1 [get_bd_cells /mdm_0]
Trace.METHOD Analyzer ; Tell TRACE32 that we wish to use off-chip trace.
Trace.PortSize 16. ; Configure the number of connected data pins
Trace.AutoFocus ; Execute a test program to detect the best
; electrical parameters for sampling.