# Debugging Applications on the Software Simulator

## Overview

TRACE32 is normally used to debug programs on a hardware debug
platform. However, when used with the MCD software extension, TRACE32
can be used to debug programs running on the Hexagon processor
instruction set simulator (hexagon-sim).

This chapter describes how to use TRACE32 and MCD to debug programs
on the simulator.

Note

This chapter is not intended as documentation for either
TRACE32 or the simulator – it assumes users are experienced with both
these tools.

For more information see the document *Hexagon Simulator User Guide*.

## MCD

The Multi-Core Debug (MCD) extension is a dynamic library which
serves as an interface between TRACE32 and the simulator.

- It supports full multi-core debugging capabilities.
- It is available for both the Windows and Linux versions of TRACE32.

## Installation

TRACE32 must be specifically configured to load the MCD dynamic
library file. This is done using the TRACE32 configuration file,
which specifies the filename (and optionally the pathname) of the MCD
dynamic library.

The Hexagon processor software development tools provide the
following example files to support the use of MCD:

- MCD dynamic library file
- TRACE32 configuration file
- TRACE32 startup script file

The following table lists the file names and their locations
in the tools release directory.

**MCD support files**

|  | **Platform** | **T32** | **Name** | **Location** |
| --- | --- | --- | --- | --- |
| **MCD Dynamic Library File** | Linux | $T32SYS/bin/pc\_linux/t32mqdsp6<br><br><br>$T32SYS/bin/pc\_linux/t32mqdsp6-qt | hexagon-mcd32.so (or T32\_MCD.so) | &lt;install\_root&gt;qclibiss |
|  |  | $T32SYS/bin/pc\_linux64/t32mqdsp6<br><br><br>$T32SYS/bin/pc\_linux64/t32mqdsp6-qt | hexagon-mcd64.so |  |
|  | Windows | %T32SYS%binwindowst32mqdsp6.exe | hexagon-mcd32.dll (or T32\_MCD.dll) | &lt;install\_root&gt;Tools\bin |
|  |  | %T32SYS%binwindows64t32mqdsp6.exe | hexagon-mcd64.dll |  |
| **TRACE32 Configuration File** | Linux | – | linux.cfg | &lt;install\_root&gt;/Examples/TRACE32/Linux\_Example |
|  | Windows | – | win.cfg | &lt;install\_root&gt;ExamplesTRACE32Windows\_Example |
| **TRACE32 Startup Script File** | Linux | – | hexagon.cmm | &lt;install\_root&gt;/Examples/TRACE32/Linux\_Example |
|  | Windows | – | hexagon.cmm | &lt;install\_root&gt;ExamplesTRACE32Windows\_Example |

The name of the dynamic library file is specified in the example
configuration file with the following command:

PBI=MCD hexagon-mcd64.so  (Linux version)
    PBI=MCD hexagon-mcd64.dll (Windows version)
    Copy to clipboard

The pathname of the dynamic library file can be specified in two
ways:

- A system environment variable (see **MCD support variables**)
- The TRACE32 configuration file

The following table lists the path variables that are set to
include the dynamic library pathname.

**MCD support variables**

| **Platform** | **Variable** | **Location** |
| --- | --- | --- |
| Linux | LD\_LIBRARY\_PATH | `<install_root>/Tools/lib/iss` |
| Windows | PATH | `<install_root>\Tools\bin` |

Alternatively, the MCD command in the TRACE32 configuration file can
be modified to include the complete path to the dynamic library file.
For example:

PBI=MCD C:\Qualcomm\HEXAGON_Tools\version\Tools\bin\hexagon-mcd64.dll
    Copy to clipboard

Note

The startup script files are specified as command arguments
in the command used to launch TRACE32 ([Launching TRACE32/MCD with configuration file](https://docs.qualcomm.com/doc/80-N2040-28/topic/debugging-applications-on-the-software-simulator.html#launch-mcn-config)).

## Quick start guide

MCD can launch a new instance of the simulator, or connect to an
existing simulator instance.

The MCD extension is configured in TRACE32 with the PRACTICE command
`SYSTEM.MCDCONFIG`.

Note

`SYSTEM.MCDCONFIG` must be performed *before* attempting the
`SYSTEM.MODE.ATTACH` command.

### Launching TRACE32/MCD with configuration file

The following commands launch TRACE32 and MCD using the example
configuration and script files provided with the Hexagon processor
tools release.

Linux:

t32mqdsp6 -c <install_root>/Examples/TRACE32/Linux_Example/linux.cfg
              -s <install_root>/Examples/TRACE32/Linux_Example/hexagon.cmm
    Copy to clipboard

Windows:

t32mqdsp6.exe -c <install_root>\Examples\TRACE32\Windows_Example\win.cfg
                  -s <install_root>\Examples\TRACE32\Windows_Example\hexagon.cmm
    Copy to clipboard

### Configuring MCD with SYSTEM.MCDCONFIG

MCD is configured in TRACE32 with the following command:

SYSTEM.MCDCONFIG [arch=<version>]
                     [hostname=<hostname>]
                     [port=<port_number>]
                     [debug=<mask>]
                     [simargs=<valid_sim_arguments>]
                     [interactive=<yes|no>]
    Copy to clipboard

The command arguments are defined as follows:

#### arch

The optional arch argument specifies the Hexagon processor version to
simulate. The argument value is specified as v*X*, where *X* is one
of the processor versions specified in the simulator option -mv*X*.

For example, specifying v5a\_256 as the arch argument causes MCD to
launch the simulator with option -mv5a\_256. For more information on
the simulator options see the *Hexagon Simulator User Guide*.

The arch argument must match the processor architecture of the
executable file being debugged.

Note

The arch argument is ignored when attaching to an existing
simulator.

As an alternative to using arch, the Hexagon processor version can be
specified in the simargs argument using the simulator option
-mv*X*.

#### hostname

The optional hostname argument specifies the host name of the machine
a simulator instance is already running on. Any valid host name can
be specified (including “localhost”).

hostname is used to connect TRACE32 to an existing (i.e., already
running) instance of the Hexagon processor simulator. The instance
may be running on the current machine or on another machine.

Note

If hostname is specified, port must also be specified.

#### port

The optional port argument specifies the TCP/IP port that will be
used to communicate with a simulator instance. The port number value
can be any number that is acceptable to strtoul() and does not
violate the standard rules for TCP/IP port numbers.

port is used to connect TRACE32 to an existing instance of the
simulator. It must be specified if the simulator is launched
independently of TRACE32.

port is also used to launch a simulator instance on the same machine
TRACE32 is running on, but using a port number other than the default
value (808368). In this case the port parameter is specified, but
hostname is not.

Alternate port numbers are specified in cases where it is necessary
to avoid port number collisions (for example, when running multiple
MCD-extended debuggers on the same host machine, with each
communicating through a different port).

Note

As an alternative to using port, the port number can be
specified in the simargs argument using the simulator option -G.

#### debug

The optional debug argument selectively controls the printing of
diagnostic information by the MCD extension itself.

debug specifies a mask value which determines the type of information
printed. The mask value bits are defined as follows:

/* DEBUG control, settable with SYS.MCDCONFIG debug=xx */
    #define REGISTER_OPS 1     // register read/write message
    #define MEMORY_OPS 2       // memory read/write msgs
    #define STATUS_REPLY 4     // status reply msgs from simu
    #define FLOW_MSGS 8        // program flow messages
    #define PACKET_FLOW 0x10   // low-level packet diagnostics
    #define ERROR_MSGS 0x20    // error states
    #define TXLIST_MSGS 0x40   // transmit list diags
    #define TRIGGER_OPS 0x80   // breakpoint diags
    #define ALL_MSGS 0xFF      // all of the above
    Copy to clipboard

The diagnostic information is written to stderr, which can be
captured by redirecting it to a file when launching TRACE32.

For example (on Windows):

t32mqdsp6.exe -c win.cfg win.cmm 2 > my_debug_output.txt
    Copy to clipboard

The resulting file is ASCII text.

debug is used to debug the MCD extension itself (which can be useful
if it is the suspected source of a system bug). The generated
diagnostic file may provide insight into the cause of a particular
problem; however, it is primarily intended for use by the MCD
maintainers.

Note

The generated diagnostic file can grow rapidly and become
extremely large.

When using debug consider minimizing the number of open TRACE32
windows, as each open window generates constant traffic to the
simulator.

#### simargs

The optional simargs argument specifies simulator command arguments
which will be passed to the simulator instance launched by MCD.

If used, the simargs argument must appear as the last argument in the
SYSTEM.MCDCONFIG command.

The specified simulator command arguments are not checked by TRACE32
– the user is responsible for verifying that they are valid.

Note

The best way to do this is to manually launch the simulator
with the specified command arguments and see if they work as
expected.

simargs is enabled only when MCD launches a new simulator instance.
If MCD connects to an existing instance, simargs will collect the
specified simulator command arguments but then do nothing with them.

#### interactive

The optional interactive argument controls whether popup windows
appear when an error occurs (such as syntax errors or premature
simulator exits).

interactive accepts the following values:

- yes – Enable popup windows (default)
- no – Disable popup windows

Note

Popup windows are supported only in Windows.

#### Using the MCD arguments

The simplest and least error-prone way to launch a new simulator
instance is to use only the simargs argument.

The simplest way to attach to an existing simulator instance is to
specify only the port argument and optionally the hostname argument
(which defaults to “localhost” if not specified). Then, after MCD
attaches to the simulator, it will query the simulator for all the
necessary details.

Last Published: Oct 06, 2026

[Previous Topic
IDSB debug control registers](https://docs.qualcomm.com/bundle/publicresource/80-N2040-28/topics/debugging-multithreaded-applications.md) [Next Topic
Using TRACE32](https://docs.qualcomm.com/bundle/publicresource/80-N2040-28/topics/using-trace32.md)