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.

MicroBlaze Debugger and Trace | 11
©1989-2021 Lauterbach GmbH
Compiling Software with Debug Information
For debugging, the target programs need to contain debug information. It is recommended to compile
MicroBlaze software with the GCC option -g3. The option -g creates debug info that does not work well
with TRACE32. Also keep in mind that using code optimization can cause problems with debugging.
NOTE: It is recommended to compile MicroBlaze software with the GCC option -g3.

MicroBlaze Debugger and Trace | 12
©1989-2021 Lauterbach GmbH
Troubleshooting
SYStem.Up Errors
The SYStem.Up command is used to establish a debug connection to the target. If you receive error
messages while executing this command this may have one reasons listed below.
FAQ
Please refer to our Frequently Asked Questions page on the Lauterbach website.
All The target has no power.
All The multicore settings are incorrect. For information how to calculate the
multicore settings see “Connecting to MicroBlaze Targets for Debug and
Trace” (app_microblaze.pdf)
All The debugger software is out of date. The Microblaze architecture evolves
rapidly and therefore regular updates of the debugger software are necessary.
Note that the software downloads on the LAUTERBACH website represent
stable releases but are not necessarily the latest versions. If the problems persist
after updating from the website, please contact LAUTERBACH support.
All The target FPGA is not configured correctly. The FPGA configuration (e.g. via
ACE files) can be disturbed, if the debug cable is attached to the target but the
debugger is powered down. Try to detach the debug cable and attach it after
FPGA configuration.
All The target is in reset:
The debugger controls the processor reset and use the RESET line to reset the
CPU on every SYStem.Up.
All You used a wrong JTAG connector on the target. In particular on ML310 always
use the 14pin JTAG connector J9 for debugging Microblaze.

MicroBlaze Debugger and Trace | 13
©1989-2021 Lauterbach GmbH
Displaying MicroBlaze Core Configuration
As the Microblaze core is configurable the available debug features depend on the current core.
The configuration of the core can be displayed using the command per.When pointing the mouse at an
entry, the debugger displays an explanation in the status line.

MicroBlaze Debugger and Trace | 14
©1989-2021 Lauterbach GmbH
CPU specific Implementations
This section gives information about design decision regarding the implementation of some special features.
Memory Accesses Causing Bus Errors
Bus errors can be caused by pointers to invalid address regions or memory that is not mapped by the MMU
(e.g. when using an operating system). Normally bus errors are detected by the debugger and displayed as
“?????????” in memory dump windows.
However, due to a core limitation detecting bus errors while the core is inside an exception handler would
alter the system state in a way preventing correct continuation of the program. Therefore inside an exception
handler (MSR.EIP=1) , the debugger uses a different memory access method that preserves the correct
system state but does not detect bus errors. In this case the contents of invalid memory regions will show
random data.
Under Linux the most common case for this problem is when a system call branches to the hardware
exception vector on 0x20. In this case the core switches to real mode (MSR.VM=0) but the stack pointer R1
still points to an address in (now unmapped) virtual memory, until it is adapted a few instructions later. If
there is an open register window, the stack area will consequently show random data for a few cycles
(instead of indicating a bus error). Once the stack pointer is set up correctly inside the exception handler, the
stack area is displayed correctly.

MicroBlaze Debugger and Trace | 15
©1989-2021 Lauterbach GmbH
Breakpoints
There are two types of breakpoints available:
• Software breakpoints (SW-BP) and
• Onchip breakpoints.
Software Breakpoints
Software breakpoints are implemented via a breakpoint instruction. These are the default breakpoints and
are usually used in RAM areas. Utilizing advanced TRACE32 mechanisms, in software breakpoints can
also be used in FLASH areas.There is no restriction in the number of software breakpoints.
For using SW breakpoints with ucLinux or other operating systems, setting the option
SYStem.Option.BrkVector may be required.
On-chip Breakpoints
Onchip breakpoints (Lauterbach terminology) allow to stop the core in specific conditions. As this is
implemented via hardware-resources, they are also referred to as “hardware breakpoints” in non-
Lauterbach terminology.
The following list gives an overview of the usage of the on-chip breakpoints by TRACE32-ICD:
•Instruction breakpoints stop the core when it reaches a certain program location.
•Read/Write address breakpoints can stop the core upon read or write data accesses.
•Data breakpoints stop the program when a specific data value is written to an address or when
a specific data value is read from an address.
Breakpoints in ROM
With the command MAP.BOnchip <address_range>, TRACE32 is configured to use onchip breakpoints in
the specified address range. Therefore the command Break.Set will set an onchip breakpoint in this range
and the parameter /Onchip can be omitted. Typically this feature is used with ROM or FLASH memories
that prevent the use of software breakpoints.
NOTE: The number of available onchip breakpoints depends on the configuration of the
MicroBlaze core defined in the FPGA design.

MicroBlaze Debugger and Trace | 16
©1989-2021 Lauterbach GmbH
Example for Breakpoints
Assume you have a target with FLASH from 0to 0xFFFFF and RAM from 0x100000 to 0x11FFFF. The
command to configure TRACE32 correctly for this configuration is:
The following breakpoint combinations are possible.
Software breakpoints:
On-chip breakpoints:
Map.BOnchip 0x0--0x0FFFFF
Break.Set 0x100000 /Program ; Software Breakpoint 1
Break.Set 0x101000 /Program ; Software Breakpoint 2
Break.Set 0xx /Program ; Software Breakpoint 3
Break.Set 0x100 /Program ; On-chip Breakpoint 1
Break.Set 0x0ff00 /Program ; On-chip Breakpoint 2

MicroBlaze Debugger and Trace | 17
©1989-2021 Lauterbach GmbH
SYStem.Option.BrkHandler Control writing of software break handler
Default: AUTO
The option controls whether the debugger writes a handler for software breakpoints to the target memory.
The address can be configured via SYStem.Option.BrkVector.
The option AUTO detects if the software breakpoint handler is required by the current core.
This can be overridden by the options ON or OFF for special cases. The breakpoint handler should be
switched OFF when
• using Linux because it utilizes a breakpoint handler created by the kernel
• if the vector table resides in ROM or “fetch-only” memory areas. In this case the vector table pre-
loaded with the memory image must contain a breakpoint handler.
If all program memory is read-only consider the use of OnChip breaks as alternative.
SYStem.Option.BrkVector Configures an alternative breakvector
Use this option to set an alternative address for the software breakpoint handler created by the debugger.
Changing the default address is necessary when the vector 0x18 is occupied e.g. by interrupt handlers.
The option must be set before attaching to the target to have an effect.
The vector should be 32bit-aligned. Do not use 0x0 as break vector.
For ucLinux it is recommended to set the handler address to 0x70.
Format: SYStem.Option.BrkHandler [AUTO | ON | OFF]
NOTE: A software breakpoint handler is required for using software breakpoints on
MicroBlaze cores with versions < 7.20.A.
Format: SYStem.Option.BrkVector <vector>
<vector>: 0…0xFFFC, 32-bit aligned

MicroBlaze Debugger and Trace | 18
©1989-2021 Lauterbach GmbH
When changing the breakpoint vector, the debugger automatically uses a matching opcode for software
breakpoints.
SYStem.Option.IMASKASM Interrupt disable on ASM
Mask interrupts during assembler single steps. Useful to prevent interrupt disturbance during assembler
single stepping.
SYStem.Option.IMASKHLL Interrupt disable on HLL
Mask interrupts during HLL single steps. Useful to prevent interrupt disturbance during HLL single stepping.
SYStem.Option.LittleEndian Select little endian mode
Selects endianness.
SYStem.Option.MMUSPACES Separate address spaces by space IDs
Default: OFF.
Enables the use of space IDs for logical addresses to support multiple address spaces.
NOTE: For additional information see SYStem.Option.BrkHandler.
Format: SYStem.Option.IMASKASM [ON | OFF]
Format: SYStem.Option.IMASKHLL [ON | OFF]
Format: SYStem.Option.LittleEndian [ON | OFF]
Format: SYStem.Option.MMUSPACES [ON | OFF]
SYStem.Option.MMUspaces [ON | OFF](deprecated)
SYStem.Option.MMU [ON | OFF](deprecated)

MicroBlaze Debugger and Trace | 19
©1989-2021 Lauterbach GmbH
For an explanation of the TRACE32 concept of address spaces (zone spaces, MMU spaces, and machine
spaces), see “TRACE32 Glossary” (glossary.pdf).
Examples:
SYStem.Option.ResetMode Select the reset mode
Use this option to select the reset mode. CORE will only reset the MicroBlaze core while SYSTEM will also
reset the peripherals.
Note that a reset of the MicroBlaze core does not reset the register R1-R31, caches and UTLB.
NOTE: SYStem.Option.MMUSPACES should not be set to ON if only one translation
table is used on the target.
If a debug session requires space IDs, you must observe the following
sequence of steps:
1. Activate SYStem.Option.MMUSPACES.
2. Load the symbols with Data.LOAD.
Otherwise, the internal symbol database of TRACE32 may become
inconsistent.
;Dump logical address 0xC00208A belonging to memory space with
;space ID 0x012A:
Data.dump D:0x012A:0xC00208A
;Dump logical address 0xC00208A belonging to memory space with
;space ID 0x0203:
Data.dump D:0x0203:0xC00208A
Format: SYStem.Option.ResetMode <mode>
<mode>: CORE | SYSTEM

MicroBlaze Debugger and Trace | 20
©1989-2021 Lauterbach GmbH
SYStem.Option.DUALPORT Use real-time access by default
If this option is enabled all memory access use real-time access if possible. This has the same effect as
using the “E:” access class modifier.
SYStem.Option.MDMSINGLELMB Use MDM LMB master 0 for all cores
If multiple cores are connected to a single MDM with master ports enabled, there are two options to
implement run-time memory access:
TERM.METHOD.MDMUART Terminal configuration
Configures the TRACE32 terminal functionality to access the UART controller of the MDM core. Use this
option when your design handles STDIO via MDM UART.
Sample script for opening term window attached to MDM UART core:
Format: SYStem.Option.DUALPORT [ON |OFF]
Format: SYStem.Option.MDMSINGLELMB [ON |OFF]
OFF Use a separate LMB master for each core.
This is the default setting. In this mode, the debugger will always use the
LMB master corresponding to the core. If the core at debug port x is
debugged, the debugger uses LMB master x. Use this mode if different
LMB slaves are mapped to the same address on different cores,
ON Use a single LMB master for all cores.
In this mode, the debugger always uses LMB master 0. Use this mode if
the cores have a common address map.
Format: TERM.METHOD.MDMUART
TERM.RESet
TERM.METHOD.MDMUART
TERM.SIZE 110. 1000.
TERM.GATE
; be sure to reset term functionality
; configure MDM UART for stdio
; cosmetics
; make T32 poll the target for data