Page-1

# Use the simulator This chapter explains how to execute an application on the simulator. The following block diagram shows how the simulator is used. Using the simulator You can use the simulator as follows: - Simulation engine The simulator supports interactive source-level debugging for the TRACE32 or LLDB debugger. This use of the simulator is invisible to debugger users. - Standalone application The simulator performs non-interactive simulation of target applications: target applications are executed straight through to the end. This is useful for tasks such as regression tests. - API The simulator supports Hexagon processor core simulation in a system simulation environment. The simulator API offers a rich interface for simplified integration into system simulation environments. ## Input to the simulator The simulator accepts executable object files produced by the linker. - Profile files - Binary data files that contain information on how the target application executed. This information is displayed by inputting the file to the Hexagon profiler. - Trace files - Contain histories of how the application executed. Separate trace files can be generated for program counter accesses and for memory, bus, and cache accesses. - Statistics files - Contain summaries of instruction usage, cache usage, and bus traffic. The simulator might read or write data files as part of simulating file input/output operations performed by the target application. It might also generate files containing profile, trace, or statistics information. ## Run the simulator To run the simulator from a command line, type: hexagon-sim [option...] input_file Copy to clipboard The simulator accepts the filename of the target application to be executed along with one or more command-line options. For example: hexagon-sim -mv68 --rtos q.cfg a.out Copy to clipboard Command switches are used to control various simulator options. A switch consists of one or two dash characters followed by a switch name and optional parameter. Note that switch names are case-sensitive. Switches must be separated by at least one space. The command switch (`--`) when delimited by spaces on either side is used to separate the command arguments of the target application from those of the simulator. For example: hexagon-sim --rtos q.cfg a.out -- 10 // 10 is target app arg hexagon-sim --rtos q.cfg -- a.out 10 // alternate form Copy to clipboard The filename argument can be specified on either side of the `--` switch. To list the available command options, type: hexagon-sim --help Copy to clipboard The simulator displays on the screen the proper command line syntax, followed by a list of the available command options. ## Options The simulator options are used to control simulation features from the command line. They are specified by the command switches listed below. Several simulator options are used to specify the simulated target hardware environment. While these options do have default values, the defaults are not universally suitable for all target hardware environments. Thus it is recommended to explicitly specify all the target hardware options as part of a simulation. This practice is especially important when simulating program performance. For example, in cycle-sensitive simulations the bus ratio and bus penalty should be specified for all buses (processor, AHB, AXI2) used in the target hardware environment. If simulated time is the goal of the simulation, the DSP clock frequency should be specified in addition to parameters that have a significant impact on the cycle count. Many additional revision IDs (or core IDs) are not listed here. To view them for a specific Hexagon simulator version, use `hexagon-sim -h -mv` with the respective hexagon architecture version, *<x>*. Note Some options have alternate abbreviated switches defined for ease of use. [Simulator information](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-simulator-information) --build_tag --help [version] | -h [version] --version | -v Copy to clipboard [Status messages](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-status-messages) --quiet | -q --verbose Copy to clipboard [Processor version](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-version) -mv68 | -mv69 | -mv71 | -mv71t | -mv73 | -mv75 | -mv79 -mv81 | -mv83 | -mv85 | -mv89 | -mv91 Copy to clipboard [Processor attributes](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-attributes) --ahbbuspenalty bus cycles --ahbbusratio ratio --axi2buspenalty bus cycles --axi2busratio ratio --buspenalty bus cycles --busratio ratio --dsp_clock MHz --stackstart address --v2p_translation mode Copy to clipboard [Simulation environment](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-simulation-environment) --bypass_crash_handle --connection_timeout seconds --coredump filename --cosim_file filename --gdbserv port | -G port --nullptr action --plimit pcycles_to_simulate --reconnect --sim_in filename | -I filename --sim_out filename | -O filename --sim_err filename | -E filename --simulated_returnval --usefs pathname Copy to clipboard [RTOS applications](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-rtos-applications) --rtos filename --symfile filename Copy to clipboard [Memory initialization](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-memory-initialization) --memfill value --memfill_rand seed Copy to clipboard [Processor modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-modeling) --bypass_idle --timing --timing_nodbc --relaxed_timing Copy to clipboard [TCM modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-tcm-modeling) --tcm:lowaddr address --tcm:highaddr address Copy to clipboard [System configuration modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-system-configuration-modeling) --etm_base value --l2cfg_base value --l2tcm_base value --subsystem_base value Copy to clipboard [Bus modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-bus-modeling) --ahb:lowaddr address --ahb:highaddr address --axi2:lowaddr address --axi2:highaddr address Copy to clipboard [gprof Profiling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-gprof-profiling) --fast-profile --profile | -p --profile_timezero mode Copy to clipboard [Statistics](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-statistics) --packet_analyze filename --pmu_statsfile filename Copy to clipboard [Trace](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-trace) --bustrace filename | -b filename --coproctrace filename --memtrace filename | -m filename --pctrace filename | -t filename --pctrace_min filename | -u filename --pctrace_nano filename --uarchtrace filename Copy to clipboard [Cache trace](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-cache-trace) --dcachetrace filename --icachetrace filename --l2cachetrace filename Copy to clipboard [Filtering](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-filtering) --pcfilter startaddress-endaddress --timefilter_ns starttime-endtime Copy to clipboard ### Simulator information These options are used as sole command arguments; they do not perform any simulation. - **--build\_tag** - Displays the git tags used to build the simulator and accompanying libraries to the console, and exit. The output can be redirected into a file. The contents of the file are useful when reporting a problem related to the simulator. **--help [***version***]** | **-h [***version***]** > > > Displays simulator command options and exit. > > > If a processor version option is specified as an argument (-help > -mv68, and so on), the simulator additionally lists information on > all the processor version options that are defined for the specified > processor version. > > > If the specified option includes both a processor version and > micro-architecture (such as -mv68na), the simulator additionally > lists the information for only that option. > > > Using the *version* argument is the only way to list all the > processor version options that are defined for Hexagon V68 and later > processors. > > > For more information on the processor version options, see [processor version](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-version). - **--version** | **-v** - Displays the version numbers of the simulator and its associated API, and exit. For more information on the simulator API, see [Interfaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/interfaces.html). ### Status messages - **--quiet** | **-q** - Does not display simulator-generated messages. - **--verbose** - Displays any warning messages. Warnings can be generated by multiple causes such as processor interrupts and exception events ([warning messages](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-warning-messages)) being generated by the target application. ### Processor version - **-mv68** | **-mv69** | **-mv71** | **-mv71t** | **-mv73** | **-mv75** | **-mv79** | **-mv81** | **-mv83** | **-mv85** | **-mv89** | **-mv91** - Specifies the Hexagon processor version and micro-architecture to simulate. These versions have properties listed when you use the hexagon-sim -h -mv*<x>* option with the respective Hexagon architecture version, *<x>* (see [simulator information](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-simulator-information)). The simulator input file must have been generated with a processor version that is compatible with the specified processor version. The default version is the one specified in the executable object file. The generic options (such as -mv68) are provided for cases where the specific micro- architecture is not relevant. Note Not all -mv\*<x>\* options are supported in a specific Hexagon tools release. For more information, see [processor versions](https://docs.qualcomm.com/doc/80-N3040-23/topic/sim-ug-overview.html#simulator-processor-versions). For more information on the processors, see the *Qualcomm Hexagon Programmer’s Reference Manual*. ### Processor attributes - **--buspenalty** *bus cycles* - Specifies the AXI (main) bus access latency in terms of bus cycles. The latency is specified as an integer value. A space must appear after the switch name. Latencies are expressed in terms of bus cycles. The default latency is 75 bus cycles. The bus is simulated at its own frequency, as determined by the --dsp\_clock and --busratio option settings. - **--busratio** *ratio* - Specifies the AXI (main) bus frequency in terms of a ratio with the Hexagon processor frequency. The default ratio is 2. If the ratio is set to 1, a bus cycle is defined to equal a pcycle. If the ratio is set to 2, a bus cycle is defined to be twice as long as a pcycle (and so on). For example, if the processor runs at 600 MHz and the ratio is 3, the bus runs at 200 MHz. - **--ahbbuspenalty** *bus cycles* - Specifies the AHB bus access latency in terms of bus cycles. The latency is specified as an integer value. A space must appear after the switch name. Latencies are expressed in terms of bus cycles. The default latency is 75 bus cycles. The bus is simulated at its own frequency, as determined by the --dsp\_clock and --ahbbusratio option settings. - **--ahbbusratio** *ratio* - Specifies the AHB bus frequency in terms of a ratio with the Hexagon processor frequency. The default ratio is 2. - **--axi2buspenalty** *bus cycles* - Specifies the AXI2 bus access latency in terms of bus cycles. The latency is specified as an integer value. A space must appear after the switch name. Latencies are expressed in terms of bus cycles. The default latency is 75 bus cycles. The bus is simulated at its own frequency, as determined by the --dsp\_clock and --axi2busratio option settings. - **--axi2busratio** *ratio* - Specifies the AXI2 bus frequency in terms of a ratio with the Hexagon processor frequency. The default ratio is 2. - **--dsp\_clock** *MHz* - Specifies the simulated processor clock speed (in MHz). The clock speed is specified as an integer value. A space must appear after the switch name. The clock speed determines the ratio of simulated to real time ([screen messages](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-screen-messages)). The default clock speed is platform-specific. Note If you intend to convert cycle counts to simulated execution times, it is recommended to explicitly specify a clock speed and to not depend on the default value. - **--stackstart** *address* - Specifies the base address of the processor stack for thread 0. Used for standalone applications. The default stack base address is 0x40000000. For more information on changing the stack location, see the *Qualcomm Hexagon Stand-alone Application User Guide* (80-N2040-22). - **--v2p\_translation** *mode* - Specifies whether or not virtual-to-physical address translation is performed for applications where the Hexagon processor MMU is enabled. - If mode is set to 1, the simulator performs virtual-to-physical address translation. - If mode is set to 0, the simulator assumes all addresses are physical. The default mode is 0. When virtual-to-physical address translation is disabled in the simulator, it can still be performed by an external object such as a debugger or OS Awareness module. ### Simulation environment - **--bypass\_crash\_handle** - Disables the crash-site stop, causing the simulator to commit the exception and exit when the target application crashes. By default, when the simulator is used as the simulation engine for the LLDB debugger and the target application generates an exception, the simulator stops at the crash site and returns control to the debugger before the exception is committed. This allows you to query the processor state at the point of failure. Specify this option to restore the legacy behavior, in which the exception is committed and the simulation exits. Note The crash-site stop applies only to the LLDB debugger. With other debugger front ends, the exception is always committed. - **--connection\_timeout** *seconds* - Optionally used when --gdbserv is used to limit the waiting time for the debugger front end to connect. Without this flag, the simulator waits forever. With this flag, the simulator waits for the specified seconds, prints an error message, and then quits (if no connection is made). - **--coredump** *filename* - Generates a binary core dump file when the target application is terminated after generating an exception. If an exception occurs when this option is not specified, the simulator will display a message suggesting that you generate a core dump file and analyze it in the debugger. For more information, see *Hexagon LLDB Debugger User Guide* (80- N2040-31). - **--cosim\_file** *filename* - Specifies the co-simulators that are to register with the simulator. A space must appear after the switch name. The specified file is a text file that contains a list of pathnames specifying co- simulator library files (\*.dll on Windows, \*.so on Linux). Alternatively, the co- simulator library filenames can be specified in the text file without pathnames, with the pathname being set in an environment variable (PATH on Windows, LD\_LIBRARY\_PATH on Linux). Predefined arguments to a co-simulator are specified after the corresponding library filename. For more information on co-simulators, see [Interfaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/interfaces.html). For the arguments accepted by the QTimer co-simulator, see [QTimer co-simulator arguments](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#simulator-qtimer-cosim-arguments). - **--gdbserv** *port* | **-G** *port* - Specifies TCP/IP socket that the simulator will write status information to during the simulation. The socket is specified as an integer value. Typically, this option is not user-specified. It is used by the TRACE32 and LLDB debuggers to automatically start the simulator and connect to it. - **--nullptr** *action* - Specifies the action taken by the simulator when the target application performs a NULL pointer dereference. The action is specified as an integer value. Supported values for *action*: - 0 - Ignore any NULL pointer dereferences A NULL pointer dereference is defined as an indirect memory reference through virtual address 0. - 1 - Write warning message to the standard output - 2 - Write error message to standard output and exit simulation (default) - **--plimit** *pcycle\_to\_simulate* - Control the total amount of pcycles to limit the simulation. The return value for hexagon-sim is a specific status code to highlight the nature of the exit from the simulation. Typically, this flag is useful to prevent runaway tests. - **--reconnect** - Causes the simulator to continue running when the associated debugger front end exits. The simulator continues to execute in its current state (on hold, running a simulation, and so on) while also monitoring the socket connection. After a fixed period of time (such as 120 seconds) to allow TCP to wait out an obsoleted socket, the simulator will reconnect if another debugger front-end attempts to connect to it. By default, the simulator exits whenever the debugger front-end exits. - **--sim\_err** *filename* | **-E** *filename* - Uses the specified file as the standard error stream for the target application. A space must appear after the switch name. - **--sim\_in** *filename* | **-I** *filename* - Uses the specified file as the standard input for the target application. A space must appear after the switch name. - **--sim\_out** *filename* | **-O** *filename* - Uses the specified file as the standard output for the target application. A space must appear after the switch name. - **--simulated\_returnval** - Causes the simulator to return a specific value to its caller indicating the final execution status of the target application. - **--usefs** *pathname* - Causes the simulator to search for files in the directory with the specified path. It is used for accessing shared object files that are loaded during program execution. If this option is not specified, the simulator assumes that all such files are stored in the current directory. Note This option affects only files being opened for reading. New files are always created in the current directory. ### RTOS applications - **--rtos** *filename* - Simulates the specified target application as an RTOS application. The *filename* argument specifies the name of a text file that contains the pathname for an *RTOS Awareness module*, a dynamic library that enables the simulation and debugging of an application system. The specified RTOS Awareness module must match the processor version used in the simulation ([processor version](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-version)). For more information, see the corresponding RTOS documentation. If the --rtos option is not used, the simulator assumes that the target application is a standalone application. Note The timer co-simulator must always be specified (with --cosim\_file) when running an RTOS application. For more information, see the corresponding RTOS documentation. - **--symfile** *filename* - Loads symbols from the specified relocatable file. A space must appear after the switch name. When an RTOS application system is built, the symbol information contained in the relocatable files is removed (stripped) from the final executable file. The simulator requires this information to execute the application system; therefore, to provide this information, the affected relocatable files must be specified with the --symfile option. Multiple files must be specified with multiple --symfile options. Note When running an RTOS application, the RTOS kernel file must always be specified with this option. ### Memory initialization - **--memfill** *value* - Initializes all bytes of simulated processor memory with the specified value before loading and executing the target application. The default value is 0x1F. - **--memfill\_rand** *seed* - Initializes all bytes of simulated processor memory with random values before loading and executing the target application. The specified integer value indicates the seed of the random number sequence used to generate the random values. Note This option is used for application testing in situations where uninitialized values might be causing application errors. ### Processor modeling - **--bypass\_idle** - Skips the execution of pcycles while the processor is idle due to all hardware threads being in wait or off mode. This option speeds up the simulation when the processor is idle for a significant amount of time. If the number of skipped cycles is nonzero, the simulator screen messages include an extra line that indicates the number of pcycles spent while the processor is idle in this way ([screen messages](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-screen-messages)). By default, this option is OFF for all architectures. Using it can accelerate programs with the DSP frequently in Idle mode, but using it slows down programs that rarely have the DSP in Idle mode. - **--timing** - Models the following processor micro-architecture as part of the simulation: - Cache (attributes are modeled, but not the actual data) - Multi-threading mode (SMT, IMT) - Processor stalls When timing is enabled, the simulation more accurately models the operation of the processor hardware. This impacts the speed of the simulation and improves the accuracy of the profiling PMU statistics collected ([PMU statistics files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-pmu-statistics-files)). This option is automatically mapped to the --timing\_nodbc option. - **Cache** - Perfect caches are assumed and no modeling of data is performed. Instead, all data requests that would be serviced from the cache in the actual hardware are serviced by the backing memory storage model. - **Multi-threading mode** - For some processors, processor modeling includes the modeling of Simultaneous Multi-Threading (SMT) mode. In SMT mode, the four hardware threads are divided into two clusters. In many cases, packets can execute simultaneously on both clusters, so up to two packets can commit in a cycle. Without SMT, the processor modeling default is Interleaved Multi-Threading (IMT) mode, where packets are executed on the hardware threads in round-robin order. (This mode is commonly known as a *barrel processor*.) For more information on caches and multi-threading, see the *QualcommHexagon Programmer’s Reference Manual*. - **--timing\_nodbc** - Legacy option that is maintained for backward compatibility. This option is internally mapped to --timing. - **--relaxed\_timing** - This option enables --timing with perfect cache. Cache miss penalities are removed and memory latencies are minimized. ### TCM modeling - **--tcm:lowaddr** *address* | **--tcm:highaddr** *address* - Uses the specified low and high memory addresses as the address range of the TCM memory area. A space must appear after the switch name. Note QTI recommends reading the TCM starting address from the CFG table and avoiding hard-coding the TCM address inside your code. For more information on TCM, see the *Qualcomm Hexagon Programmer’sReference Manual*. ### System configuration modeling These options are supported only in the Hexagon 7.x tool releases. Note Avoid using these options unless absolutely necessary. The effect is to load a specific value into a specific slot of the CFG table (a read-only area in the actual hardware) and nothing else. - **--etm\_base** *value* - Specifies the ETM base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. - **--l2cfg\_base** *value* - Specifies the L2 configuration base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. - **--l2tcm\_base** *value* - Specifies the L2 TCM base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. The simulator sets the value of the CFGBASE register itself to (*value* + 0x18), where 0x18 denotes 0x180000 in the physical address space. If this option is not used, the simulator assigns the L2 TCM base address a default value that is internally determined. - **--subsystem\_base** *value* - Specifies the subsystem base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. ### Bus modeling Note To enable an address decode range for AHB or AXI2, both the low and high addresses must be specified. For details on AHB and AXI2, see [Interfaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/interfaces.html). - **--ahb:lowaddr** *address* | **--ahb:highaddr** *address* - Uses the specified low and high memory addresses as the address decode range for the AHB bus interface. A space must appear after the switch name. - **--axi2:lowaddr** *address* | **--axi2:highaddr** *address* - Uses the specified low and high memory addresses as the address decode range for the AXI2 bus interface. A space must appear after the switch name. ### gprof Profiling - **--fast-profile** - Generates a profile data file (named gmon) for use with the text-based Hexagon gprof profiler. Fast profile data files contain information on how the target application executed, with reduced called-function accuracy to improve profiling times. Only the function call graph is affected. Every function called is still counted. The information is displayed by inputting the files to the profiler. When the target application is a multi-threaded standalone application this option creates separate profile data files for each hardware thread (named gmon.t\_0, gmon.t\_1, …). When the target application is a multi-threaded RTOS application, this option creates separate profile data files for each software thread (named gmon.name1, gmon.name2, …) and an additional profile data file for the application startup code (named gmon.t\_Startup\_0). By default, the simulator generates profile data files in a format that is specific to the Hexagon processor. The processor-specific data format differs from the standard GNU format by enabling histogram buckets to contain values up to 2^64^-1. The values are pseudo-encoded values of variable length. This change removes the scaling inaccuracies that resulted from rounding values stored in the GNU-style profile data files. Note The gmon.t\_Startup\_0 file is created only in the 7.x tools releases. For more information on profile data files, see [profile data files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-profile-data-files). For more information on the gprof profiler, see the *Qualcomm Hexagon gprof Profiler User Guide* (80-N2040-29). - **--profile** | **-p** - Generates a profile data file (named gmon) for use with the text-based Hexagon gprof profiler. Profile data files contain information on how the target application executed. The information is displayed by inputting the files to the profiler. When the target application is a multi-threaded standalone application this option creates separate profile data files for each hardware thread (named gmon.t\_0, gmon.t\_1, …). When the target application is a multi-threaded RTOS application, this option creates separate profile data files for each software thread (named gmon.name1, gmon.name2, …) and an additional profile data file for the application startup code (named gmon.t\_Startup\_0). By default, the simulator generates profile data files in a format that is specific to the Hexagon processor. The processor-specific data format differs from the standard GNU format by enabling histogram buckets to contain values up to 2^64^-1. The values are pseudo-encoded values of variable length. This change removes the scaling inaccuracies that resulted from rounding values stored in the GNU-style profile data files. Note The gmon.t\_Startup\_0 file is created only in the 7.x tools releases. For more information on profile data files, see [profile-data-files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-profile-data-files). For more information on the gprof profiler, see the *Qualcomm Hexagon gprof Profiler User Guide* (80-N2040-29). - **--profile\_timezero** *mode* - Specifies whether or not gprof profiling starts from time zero. For RTOS applications, a zero start time indicates that profile data collection begins immediately, and thus includes the OS boot-up instructions. If mode is set to 1, gprof profile data collection starts from time zero. If mode is set to 0, OS boot-up instructions are not included in the profile data. Note Previous simulator versions that did not support this option behaved as if the mode were set to 0. ### Statistics - **--packet\_analyze** *filename* - Note It applies to the Hexagon processor and coprocessor concurrently. Generates a packet statistics file with the specified name. A space must appear after the switch name. Packet statistics files contain the number of commits, stalls, and bus accesses performed by the instruction packet at the specified memory address. The stalls and bus accesses are expressed in terms of PMU events. The Hexagon profiler can postprocess the output to produce an HTML file. If a filename is not specified, a packet statistics file is not generated. For more information on packet statistics files, see [packet statistics files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-packet-statistics-files). - **--pmu\_statsfile** *filename* - Generates a PMU statistics file with the specified name. A space must appear after the switch name. PMU statistics files contain the raw PMU event values for each hardware thread. The PMU monitors a wide variety of events related to instruction scheduling, and bus and cache accesses. This option must be used with the --timing option ([processor modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-modeling)).to ensure that the generated statistics file contains valid data. If this option is not specified, a PMU statistics file is automatically generated with the default filename, pmu\_statsfile.txt. For more information on PMU events, see [PMU statistics files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-pmu-statistics-files). ### Trace - **--bustrace** *filename* | **-b** *filename* - Generates a bus trace file with the specified name. A space must appear after the switch name. Bus trace files contain a record of the buses accessed during execution of the target application. Note This option must be used with the --timing option ([processor modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-modeling)). For more information on bus trace files, see [bus trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-bus-trace-files). - **--coproctrace** *filename* - Produces a trace of micro-architecture-level activities for the HVX coprocessor. Because it is a micro-architecture-level trace, the file size is huge and the contents might be slightly different between simulator versions. For the output to be useful, the operation requires --timing. - **--memtrace** *filename* | **-m** *filename* - Generates a memory trace file with the specified name. A space must appear after the switch name. Memory trace files contain a record of the memory accesses performed during execution of the target application (including both instruction and data accesses). For more information on memory trace files, see [memory trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-memory-trace-files). - **--pctrace** *filename* | **-t** *filename* - Generates a program counter trace file with the specified name. A space must appear after the switch name. Program counter trace files contain the following information: - A record of the program counter (PC) value at each cycle in the target application, including all stall cycles. - The instruction packet executed at each PC value (for committed cycles only). - The contents of all processor registers after each cycle. For more information on program counter trace files, see [program counter trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-program-counter-trace-files). - **--pctrace\_min** *filename* | **-u** *filename* - Generates a minimal program counter trace file with the specified name. A space must appear after the switch name. Minimal program counter trace files contain less information than regular program counter trace files—they include only a record of the program counter (PC) value at each cycle in the target application. Unlike regular program counter trace files, they do not include information on stalls, packets, or registers. Note This option is a subset of --pctrace and overrides it. For more information on program counter trace files, see [program counter trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-program-counter-trace-files). - **--pctrace\_nano** *filename* - Generates an ultra minimal program counter trace file with the specified name. A space must appear after the switch name. Ultra minimal program counter trace files contain less information than minimal program trace files. They are intended for use when you are first investigating the behavior of a program and need only minimal information on the program counter (PC) value. Note This option is a subset of --pctrace and --pctrace\_min, and it overrides both of them. For more information on program counter trace files, see [program counter trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-program-counter-trace-files). - **--uarchtrace** *filename* - Generates a micro-architecture trace file with the specified name. A space must appear after the switch name. Micro-architecture trace files contain a record of major micro-architecture events (cache misses, packets executed, stall cycles, bus requests, and so on). Micro-architecture trace files can generate huge amounts of data. Therefore, this option should be used with filtering to limit the collection of trace file data to relatively small time periods. Note Because of differences in the processor architecture, the contents of a micro- architecture trace file might differ between processor versions. For more information on micro-architecture trace files, see [program counter trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-program-counter-trace-files). ### Cache trace - **--dcachetrace** *filename* - Generates a data cache trace file with the specified name. A space must appear after the switch name. Data cache trace files contain a record of the data cache accesses during execution of the target application. For more information on data cache trace files, see [data cache trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-data-cache-trace-files). - **--icachetrace** *filename* - Generates an instruction cache trace file with the specified name. A space must appear after the switch name. Instruction cache trace files contain a record of the instruction cache accesses during execution of the target application. For more information on instruction cache trace files, see [L2 cache trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-l2-cache-trace-files). - **--l2cachetrace** *filename* - Causes the simulator to generate an L2 cache trace file with the specified name. A space must appear after the switch name. L2 cache trace files contain a record of the L2 cache accesses during execution of the target application. Note The cache trace options can be used only if processor modeling is enabled (see [processor modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-modeling)). For more information on L2 cache trace files, see [L2 cache trace files](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-l2-cache-trace-files). ### Filtering - **--pcfilter** *startaddress***-***endaddress* - Data collection begins when the instruction at a specified start address is executed, and it continues until the instruction at a specified end address is executed. No space can appear between the dash and address values. Once constrained data collection ends, it does not start again during the program execution (even if the start address is executed again). Note Filtering applies to all forms of data collection in the simulator: profile, statistics, and trace data. Filtering by address works in conjunction with filtering by time (using the --timefilter\_ns option). In particular, filtering begins when either the start-address condition or start-time condition is satisfied, and it ends when either the end-address condition or end-time condition is satisfied. - **--timefilter\_ns** *starttime***-***endtime* - Data collection begins when the simulation reaches a specified start time, and it continues until the simulation reaches a specified end time. Time is expressed in units of nanoseconds. No space can appear between the dash and address values. Once constrained data collection ends, it does not start again during the program execution. Note Filtering applies to all forms of data collection in the simulator: profile, statistics, and trace data. Filtering by time works in conjunction with filtering by address (using the --pcfilter option). In particular, filtering begins when either the start-time condition or start-address condition is satisfied, and it ends when either the end-time condition or end-address condition is satisfied. ## Screen messages When the simulator is executed, it displays the following information on the screen: $ hexagon-sim -mv68 a.elf Hexagon-sim INFO: the rev_id used in the simulation is 0x00008c68 (v68na) hello, world Done! T0: Insns=5648 Tcycles=7931 T1: Insns=0 Tcycles=0 T2: Insns=0 Tcycles=0 T3: Insns=0 Tcycles=0 Total: Insns=5648 Pcycles=47587 Copy to clipboard The processor version that is being simulated (in this case, V68) is displayed immediately after the simulator command. While not necessary, it is recommended that you always specify the processor version on the command line (see [processor version](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-version)). Specify the exact revision ID (such as -mv68na) so the simulator behaves as close as possible to the usage scenario. Remember that within the same architecture versions, all the core variations can have very different parameters. Any text written to the standard output by the target application (hello, world in this case) is displayed immediately after the processor version information. When the simulator executes to the end of the target application, it displays the following information: - The status message, Done! - The number of instructions executed and the thread cycle count (Tcycles) for each hardware thread (T0 through T5 for processor versions with six threads) - The total number of instructions executed and total processor cycle count (Pcycles) for all hardware threads Note The end of simulation statistics are focused on packet counts and pcycles. Note The simulator-generated messages can be suppressed with the --quiet option ([status messages](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-status-messages)). ### Additional information In some Hexagon tools releases, the simulator displays the following additional information on the screen: - The simulator speed (in terms of millions of instructions per wall-clock second) - The processor clock rate, the speed ratio of the simulator to the actual processor, and the simulator execution time in wall-clock seconds The processor clock rate (600 MHz in this case) is determined by the --dsp\_clock option ([processor attributes](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-attributes)). The speed ratio indicates that the target application was simulated at a rate that is a certain number of times slower than a 600 MHz Hexagon processor would execute the same application in real time (based on wall-clock seconds). The ratio is based on processor cycles, not on instructions per second—it is computed with the following formula: `(Pcycles / wall_clock_seconds) / processor_clock_MHz` Note The reported simulator speed and speed ratio may vary according to factors such as the overall computer load and complexity of instructions being simulated. However, any such variations will not in any way affect the performance of the algorithm being simulated. ### Idle modeling When --bypass\_idle is used ([processor modeling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-processor-modeling)) and the number of recorded idle cycles is nonzero, the simulator screen messages include an extra line indicating the total number of processor cycles simulated, which includes the simulated idle cycles: `Total simulated Pcycles (including wait) = 1000013401` ## Warning messages The simulator displays warning messages on the screen to indicate various events. Here are some of the more common ones: - Incorrectly-specified command-line options or option arguments - A command line is too long - NULL pointer dereferences were performed by the target application - Hexagon processor interrupts or exceptions that occur while the target application is executing For example: WARNING: NULL pointer dereference: TNUM=0 PCYC=23860 PC=4a5 VADDR=0 WARNING: register_tlb_missrw_exception in arch/system.c:339: TLB miss-RW exception detected on tnum=0 PC:2400, badva=0x3ffffff8 access_type=S cycle=1866 Copy to clipboard The --nullptr option ([simulation environment](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-simulation-environment)) controls warning messages for NULL pointer dereferences. The --verbose option ([simulator information](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-simulator-information)) controls warning messages for processor interrupts and exceptions. For more information on processor interrupt and exception events, see the *Qualcomm Hexagon Programmer’s Reference Manual*. ## Profile data files Profile data files are binary files that contain information on how the target application executed (for example, call graphs and execution time per function). This information is not directly human-readable; it is displayed by inputting the profile data file to the Hexagon gprof profiler. Command option used for generating profile data files | **Target profiler** | **Command options** | **Profile data file** | | --- | --- | --- | | hexagon-gprof |

--profile

--fast-profile

| gmon.t\_x | In some cases, the simulator might generate multiple profile data files for an application. Note Some profile data might be inaccurate due to data normalization. For more information on the options and data file, see [gprof profiling](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-gprof-profiling). For more information on the gprof profiler, see the *Qualcomm Hexagon gprof Profiler User Guide* (80-N2040-29). ## Trace files Trace files are text files that contain a detailed record of the execution events that occur during the execution of a target application. The simulator can generate separate trace files for the following execution events: - Program counter (PC) accesses - Hardware thread stalls - Memory accesses - Bus accesses - Micro-architecture events - Data cache accesses - Instruction cache accesses - L2 cache accesses The generation of each type of trace file is controlled by the corresponding trace option ([trace](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-trace) and [cache trace](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-cache-trace)). A trace file contains a sequence of trace entries, with each entry occupying one or more lines in the file (depending on the trace type). An individual trace entry consists of a series of *name =value* pairs that display information specific to the trace type. Note Trace files can become indefinitely large for longer programs. They can be reduced in size by filtering the generated trace data ([filtering](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-filtering)). ### Program counter trace files Program counter trace files contain the following information: - A record of the program counter (PC) value at each cycle in the target application, including all stall cycles. - The instruction packet executed at each PC value (for committed cycles only). - The contents of all processor registers after each cycle. #### File syntax Trace entries for program counter trace files have the following (multi-line) syntax: Tnum VA=addr PA=addr PCYC=val instruction/status Thread registers: register: value ... Global registers: register: value ... Copy to clipboard Note The trace file syntax described here applies to V60 and later processors. The syntax used for earlier processor versions differs somewhat in field names and field ordering. #### Options - **T***num* - Hardware thread number (decimal digit). - **VA=***addr* - Virtual address of instruction (hexadecimal value with leading 0x). - **PA=***addr* - Physical address of instruction (hexadecimal value with leading 0x). - **PCYC=***val* - Processor cycle (decimal value). - *instruction/status* - Instruction packet disassembly or status of thread. - *register***:** *value* - Register name/value pair (hexadecimal value with leading 0x). Note A minimal program counter trace file can be generated using the simulator option --pctrace\_min ([trace](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-trace)). The minimal trace file lists only the hardware thread number, PC virtual/physical address, and cycle number. ### Memory trace files Memory trace files contain a record of the memory accesses performed during execution of the target application (including both instruction and data accesses). #### File syntax Trace entries for memory trace files have the following syntax: TNUM=num:TYPE=(IF|DR|DW):PCYC=val:PC=addr:VA=addr:PA=addr:WIDTH=val:DATA=val:val: Copy to clipboard Note The trace file syntax described here applies to Hexagon V60 and later processors. The syntax used for earlier processor versions differs somewhat in field names and field ordering. #### Options - **TNUM=***num* - Hardware thread number (decimal digit). - **TYPE=***type* - Memory access type. - **IF** - Instruction fetch from memory. - **DR** - Data read from memory. - **DW** - Data write to memory. - **PCYC=***val* - Processor cycle (decimal value). - **PC=***addr* - Instruction address making request (hexadecimal value with no leading 0x). - **VA=***addr* - Virtual address accessed (hexadecimal value with no leading 0x). - **PA=***addr* - Physical address accessed (hexadecimal value with no leading 0x). - **WIDTH=***val* - Number of bytes read (possible values 1, 2, 4, 8, 12, 16). - **DATA=***val***:***val***:** - Actual data values read (two hexadecimal values with no leading 0x). Note When WIDTH=12 or 16, only 8 data bytes are printed. ### Bus trace files Bus trace files contain a record of the buses accessed by the target application. #### File syntax Trace entries for bus trace files have the following syntax: PCYC=val:Tnum:PC=addr:(BUSREQ|BUSRSP):TYPE=(IFETCH|DREAD|DWRITE):ID=val:PA=addr:WIDTH=val[:DELAY=val] Copy to clipboard Note The trace file syntax described here applies to Hexagon V60 and later processors. The syntax used for earlier processor versions differs somewhat in field names and field ordering. #### Options - **PCYC=***val* - Processor cycle (decimal value). - **T***num* - Hardware thread number (decimal digit). - **PC=***addr* - Packet address making request (hexadecimal value with no leading 0x). - **BUSREQ** - Bus access request. - **BUSRSP** - Bus returned data or responded to request. - **TYPE=***type* - Memory access type. - **IFETCH** - Instruction fetch. - **DREAD** - Data read. - **DWRITE** - Data write. - **ID=***val* - Bus request identifier. - **PA=***addr* - Physical address accessed (hexadecimal value with no leading 0x). - **WIDTH=***val* - Number of bytes accessed (decimal value). - **DELAY=***val* - Latency (in pcycles) between bus request and response (decimal value). Note A physical address can appear in a bus trace without appearing in the corresponding memory trace, if a cache line containing the address is prefetched but never used. ### Micro-architecture trace files Micro-architecture trace files contain a record of major micro-architecture events (cache misses, packets executed, stall cycles, bus requests, and so on). #### File syntax Trace entries for micro-architecture trace files have the following syntax: PCYC=val:Tnum:PC=addr:(BUSREQ|BUSRSP):TYPE=(IFETCH|DREAD|DWRITE):ID=val:PA=addr:WIDTH=val[:DELAY=val] PCYC=val:Tnum:PC=addr:STALL:stalltype PCYC=val:Tnum:PC=addr:COMMIT PCYC=val:Tnum:PC=addr:instruction Copy to clipboard Note The trace file syntax described here applies to Hexagon V60 and later processors. The syntax used for earlier processor versions differs somewhat in field names and field ordering. #### Options - **PCYC=***val* - Processor cycle (decimal value). - **T***num* - Hardware thread number (decimal digit). - **PC=***addr* - Packet address making request (hexadecimal value with no leading 0x). - **BUSREQ** - Bus access request. - **BUSRSP** - Bus returned data or responded to request. - **TYPE=***type* - Memory access type. - **IFETCH** - Instruction fetch. - **DREAD** - Data read. - **DWRITE** - Data write. - **ID=***val* - Bus request identifier. - **PA=***addr* - Physical address accessed (hexadecimal value with no leading 0x). - **WIDTH=***val* - Number of bytes accessed (decimal value). - **DELAY=***val* - Latency (in pcycles) between bus request and response (decimal value). - **STALL=***stalltype* - Packet stall (unquoted string value). - **COMMIT** - Packet commit. - *instruction* - Instruction packet disassembly. ### Instruction cache trace files Instruction cache trace files contain a record of the instruction cache accesses during execution of the target application. #### File syntax Trace entries for instruction cache trace files have one of the following syntaxes: PCYC=val:Tnum:PC=addr:ICACHE:(MISS|REPLACE):VA=addr:PA=addr Copy to clipboard Note The trace file syntax described here applies to Hexagon V60 and later processors. The syntax used for earlier processor versions differs somewhat in field names and field ordering. #### Options - **PCYC=***val* - Processor cycle (decimal value). - **T***num* - Hardware thread number (decimal digit). - **PC=***addr* - Packet address making request (hexadecimal value with no leading 0x). - **ICACHE** - Instruction cache operation. - **MISS** - Instruction cache miss. - **REPLACE** - Instruction cache replace. - **VA=***addr* - Virtual address accessed (hexadecimal value with no leading 0x). - **PA=***addr* - Physical address accessed (hexadecimal value with no leading 0x). ### Data cache trace files Data cache trace files contain a record of the data cache accesses during execution of the target application. #### File syntax Trace entries for data cache trace files have one of the following syntaxes: PCYC=val:Tnum:PC=addr:DCACHE:(MISS|HIT):TYPE=(DCFETCH|DREAD|DWRITE):VA=addr:PA=addr[:WAY=val] Copy to clipboard Note The trace file syntax described here applies to Hexagon V60 and later processors. The syntax used for earlier processor versions differs in field names and field ordering. #### Options - **PCYC=***val* - Processor cycle (decimal value). - **T***num* - Hardware thread number (decimal digit). - **PC=***addr* - Packet address making request (hexadecimal value with no leading 0x). - **DCACHE** - Data cache operation. - **MISS** - Data cache miss. - **HIT** - Data cache hit. - **TYPE=***type* - Memory access type. - **DCFETCH** - Data cache fetch. - **DREAD** - Data read. - **DWRITE** - Data write. - **VA=***addr* - Virtual address accessed (hexadecimal value with no leading 0x). - **PA=***addr* - Physical address accessed (hexadecimal value with no leading 0x). - **WAY=***val* - Number of L1 cache ways (decimal value). ### L2 cache trace files L2 cache trace files contain a record of the L2 cache accesses during execution of the target application. #### File syntax Trace entries for L2 cache trace files have one of the following syntaxes: PCYC=val:Tnum:PC=addr:L2CACHE:cacheop:VA=addr:PA=addr:INDEX=val[:WAY=val] Copy to clipboard Note The trace file syntax described here applies to Hexagon V60 and later processors. The syntax used for earlier processor versions differs in field names and field ordering. #### Options - **PCYC=***val* - Processor cycle (decimal value). - **T***num* - Hardware thread number (decimal digit). - **PC=***addr* - Packet address making request (hexadecimal value with no leading 0x). - **L2CACHE:***cacheop* - L2 cache operation. - **MISS** - Data cache miss. - **HIT** - Data cache hit. - **LOAD** - Memory load. - **STORE** - Memory store. - **SCALAR** - Access by processor core. - **IPREFETCH** - Access due to instruction prefetch. - **REPLACE** - Access due to instruction cache replace. - **CLEAN** - Instruction cache replace does not require memory write. - **DIRTY** - Instruction cache replace requires memory write. - **VA=***addr* - Virtual address accessed (hexadecimal value with no leading 0x). - **PA=***addr* - Physical address accessed (hexadecimal value with no leading 0x). - **INDEX=***val* - L2 cache index (decimal value). - **WAY=***val* - Number of L2 cache ways (decimal value). ## PMU statistics files The simulator collects PMU statistics while an application is running. When the application terminates, the collected statistics are written to a PMU statistics file. PMU statistics files are text files that contain the same execution information that the Hexagon Performance Monitor Unit generates to support on-target performance tracking: - Instruction scheduling details - Bus access events - Cache access events The statistics filename is determined by the --pmu\_statsfile option ([13](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-statistics)). The default name is pmu\_statsfile.txt. For more information on the symbols used in PMU statistics files to represent Hexagon processor execution events, see the *Qualcomm Hexagon Programmer’s Reference Manual*. ## Packet statistics files The simulator collects statistics on the instruction packets executed while an application is running. When the application terminates, the simulator writes the collected statistics to a *packet statisticsfile*. Packet statistics files are text files that contain the following execution information for each instruction packet: - Address - Packet start address (in virtual memory) - commits - Packet execution count - stalls - Packet stall counts (for each stall type) - bus - Bus access counts (for each access type) The packet statistics file is enabled by the --packet\_analyze option ([statistics](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html#simulator-statistics)). Packet statistics files are written in JSON format, which can be read by Python or Perl scripts ([http://json.org/example](http://json.org/example)). To postprocess the JSON file produced with the `--packet-analyze` option, see the *Hexagon Profiler User Guide* (80-N2040-10). The following code is an example of a single instruction packet entry from a packet statistics file: { // beginning of file "0x000069bc": { // instruction packet address "commits": 12, "stalls": { "FE_NEWVALUE_MISPREDICT_CYCLES": 9, "IU_FETCH_CROSS_CYCLES": 3, "IU_HIT_CYCLES": 26, "DCACHE_DEMAND_MISS_CYCLES": 157, "TOTAL_STALLS": 195 }, "bus": { } "AXI_READ_REQUEST": 1 }, // end of first packet // subsequent packets are listed here Copy to clipboard [Statistics](https://docs.qualcomm.com/doc/80-N3040-23/topic/statistics.html) defines the symbols used in packet statistics files to represent the stall and bus access event types. Note The packet entries in a packet statistics file are not sorted. Note The JSON format used in a packet statistics file will not change in the future. However, additional metadata might be added to the file header, and additional attributes might be added to individual packets. Last Published: Oct 06, 2026 [Previous Topic Type definitions](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/sim-ug-overview.md)