# Simulator System API The simulator supports an API that clients can use to enable client program control of a Hexagon simulation. The API is used to perform co-simulation of the Hexagon processor with external devices and with higher-level system simulations. The simulator is designed as a library that can be dynamically loaded by a system simulator. It supports two simulation modes: - Standalone simulation (as hexagon-sim) - Simulation as part of a larger system simulation environment. The simulator library exports functions that can be called by the system simulation environment. This API supports simulation configuration as well as simulation control. The simulator library additionally supports the loading of co-simulation models and communication with them through a dedicated API. ## Simulator components Page-1 Sheet.2 COSIM COSIM Sheet.39 Hexagon Simulation Engine Hexagon Simulation Engine Sheet.40 hexagon-sim args hexagon-sim args Sheet.41 Hexagon Wrapper Hexagon Wrapper Sheet.42 system-sim system-sim Dynamic connector Dynamic connector.44 Dynamic connector.45 Dynamic connector.46 Simulator components used in standalone and system simulations hexagon-sim is a command used to execute standalone simulations from a command line interface. The command arguments specify the simulation environment. system-sim represents a host program that invokes a Hexagon simulation as part of a larger system simulation environment. The Hexagon constructor (named HexagonWrapper) is used in both standalone and system simulations to create and configure instances of the Hexagon simulator. The Hexagon simulation engine is invoked by the constructor to perform the simulation. COSIM is a co-simulation module that models one or more devices external to the Hexagon processor. Co-simulations communicate with the simulation engine through the simulator API. ## Invoke simulator in Standalone mode In Standalone mode, the simulator is configured using command-line options. hexagon-sim [options] executable Copy to clipboard This executable is analogous to a system simulation environment where the target platform consists of only the Hexagon core. The hexagon-sim executable uses the simulator API to simulate the operation of the Hexagon core. An overview of the API functionality is provided below. The command-line options are first parsed by hexagon-sim to determine the specific Hexagon processor version that is being requested to be simulated. This is determined by either the existence of an option specifically stating the version to use (such as -mv68) or, if not explicitly stated, the processor version is determined by examining the provided executable. In the latter case, the version is set to match the executable. hexagon-sim first creates an instance of the [HexagonWrapper class](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#simulator-constructor-hexagonwrapper) with the specified processor version, and then calls the [configuration member functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#simulator-configuration) based on the command-line arguments passed to it. After configuration, the simulator either runs until the program terminates, or passes control to a debugger. In debug mode, the simulator can be run either in interactive mode or with a debugger like TRACE32 or GDB. The following pseudo-code describes the functionality of hexagon-sim. #include "HexagonTypes.h" #include "HexagonWrapper.h" main(int argc, char** argv) { HEXAPI_Cpu main_arch_type; HexagonWrapper *hex; main_arch_type = findArch(argc, argv); // bail if invalid // Load architecture specific library based on command line // option and/or binary image. Put files in current dir hex = new HexagonWrapper(main_arch_type); // Call configuration methods based on command-line // options passed to the simulator ConfigureOptions(argc, argv); if (InteractiveModeRequested) { start interactive mode } else { load image and run } } Copy to clipboard ## Invoke simulator in System Simulation mode This section describes the API calls for working with the Hexagon simulator in a System Simulation mode. Each processor version of the Hexagon core has its own simulator library (which is named either libhexagonissv*<x>*.so or libhexagonissv*<x>*.dll). This library is located at $(hexagon\_TOOLS\_INSTALL\_DIR)/Tools/lib/iss. The HexagonWrapper class (libwrapper.a) is statically linked to the system simulation application that wishes to instantiate a Hexagon core. This wrapper class knows where to find the library to load for the specified simulator by using one of the following methods: - The loader’s environment variable setting (PATH on Windows, LD\_LIBRARY\_PATH on Linux) - Linking the application using a specific path to the linker (the -rpath option of ld) - Relative to the path of the hexagon-sim executable (when using hexagon-sim) The processor version type provided to the HexagonWrapper constructor determines which library is loaded. For example, if the environment variable points to the library to load, the compile line would look like this: g++ -o sys_sym sys_sym.c -I$(HEXAGON_TOOLS_INSTALL_DIR)/Tools/include/iss -L$(HEXAGON_TOOLS_INSTALL_DIR)/Tools/lib/iss -lwrapper Copy to clipboard The environment variable is set to: $(HEXAGON_TOOLS_INSTALL_DIR)/Tools/lib/iss Copy to clipboard To dynamically bind the simulator library, the runtime link path can be hard-coded into the binary as follows: g++ -o sys_sym sys_main.c -Wl,-rpath,$(HEXAGON_TOOLS_INSTALL_DIR)/Tools/lib/iss -lwrapper Copy to clipboard When hexagon-sim is invoked from the command line, the library path is determined, relative to the path from where hexagon-sim was installed. ## File handling All simulator API functions that deal with paths or filenames make the following assumptions: - The user has the correct file permissions - The entity specified by a name string has the same type as what is expected by the specification Thus, if an API function requires a string whose content describes a path (directory), the referenced directory must exist and have the correct permissions. If the string describes a file, the API assumes it is in the correct format for the platform (C:\… or /usr/…) and it exists with the correct permissions, or, in the case of a simulator-created file, the directory in which the file is to be created exists and has permissions that allow the file to be created. An enumerated type (HEXAPI\_OpenMode) is optionally passed along with filenames that directs the simulator to open the specific file in a way specified by the caller. This allows, for instance, concatenation of trace results from different portions of the simulation into a single file. Each API specifies what the simulator uses by default as the open mode. Note Opening files with HEX\_MODE\_WRITE or HEX\_MODE\_WRITEBINARY overwrites any existing data in the file. The configuration APIs only check the validity of the specified files, but not the validity of any file content. A configure command might succeed, but it will return an error later in simulation. For instance, [ConfigureCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurecosim) accepts the name of a configuration file. The cosim configuration file contains names of cosim libraries to load. If one of the cosim library names is invalid, the ConfigureCosim() function succeeds, but an error is generated later. The simulator maintains open file handles for each file specified and does not close files until the HexagonWrapper destructor is called (typically by deleting the instance). Reading or writing these files before the HexagonWrapper instance is deleted gives unpredictable results. ## Status results Most simulator API functions return a function result value indicating the result of the operation. The API defines a standard set of symbols (of type HEXAPI\_Status) for the result values, as shown in the following table. API status results | **Symbol** | **Description** | | --- | --- | | HEX\_STAT\_SUCCESS | Success | | HEX\_STAT\_ERROR | Error | | HEX\_STAT\_RANGE\_ERROR | Incorrect range | | HEX\_STAT\_INVALID\_ARGS | Invalid arguments | | HEX\_STAT\_CANNOT\_CONFIG | Cannot configure simulator | | HEX\_STAT\_CANNOT\_TRANSLATE | No translation for specified vaddr exists | | HEX\_STAT\_FILE\_ACCESS\_ERROR | File access error | | HEX\_STAT\_MEM\_ACCESS\_ERROR | Cannot access memory | | HEX\_STAT\_DEVICE\_NOT\_FOUND | Cannot find registered bus device | | HEX\_STAT\_NO\_ACTIVE\_THREADS | No threads active | | HEX\_STAT\_LOAD\_ELF\_ERROR | Error in loading ELF binary for Hexagon | Note The [Run()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#run) API function returns a function-specific result value of type HEXAPI\_CoreState. ## Simulator constructor (HexagonWrapper) Creates an instance of the simulator for use as a handle for driving the Hexagon simulation. This handle can be further configured according to the target system configuration. - **Prototype** - HexagonWrapper(HEXAPI_Cpu cpu_ver); Copy to clipboard - **Parameters** - | in | *cpu\_ver* | Hexagon processor version.
| | --- | --- | --- | - **Detailed description** - Tracing, profiling, or remote debugging features can be enabled by calling configuration functions on the handle. A simulator instance handle can be used as a client by a system scheduler, and it can be made to run for a specified number of cycles. Cosims to model external devices can be constructed and plugged in as clients to the simulator library. Note Not all of the processor versions are supported in a specific Hexagon tools release. For more information, see [Use the simulator](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html). Processors have many cpu\_ver values defined for their various micro-architectures. These values are not listed above. To determine them: - Use the -help option in hexagon-sim to list the -mv*<x>* processor version options defined in the simulator. - Then construct the necessary cpu\_ver value using the pattern HEX\_CPU\_VXX\_YY, where XX indicates the processor version and micro-architecture, and YY indicates the sum of the L2 cache and TCM sizes. For example, hexagon-sim -h -mv68 will show all revision IDs for V68 supported in this hexagon-sim instance. Hexagon-sim instances from different Hexagon tools release might show different revision IDs. Note Instead of -help, you can also use the rev\_id values listed in $(hexagon\_TOOLS\_INSTALL\_DIR)/include/iss/HexagonTypes.h as a source. - **Usage** - The following example shows how to use the constructor to create and configure an instance of the simulator for use as a handle for driving the Hexagon simulation. #include "HexagonWrapper.h" // defines enum HEXAPI_Cpu sys_main() { // instantiate HEXAGON wrapper HexagonWrapper *dsp = new HexagonWrapper(HEX_CPU_V68); HEX_4u_t actualCyc = 0; HEX_4u_t simRC; HEXAPI_CoreState runstate; // Configure DSP dsp->ConfigureTCM(0xD8000000); // if you intend to use TCM dsp->ConfigureExecutableBinary(“bootimg.pbn”); // configure cosim here dsp->EndOfConfiguration(); // after all pre-run configuration // Run DSP // Most users intend to run straight through the entire program runstate = dsp->Run(&simRC); // if "runstate" is HEX_CORE_FINISHED // "simRC" will contain the return value of the user main() // of the simulated program. However, most usage scenarios // focus on side effects and ignore the return value. // To simulate a program in repeated short segments, do this: while (...) { // run for at most 100 pcycles at a time runstate = dsp->Step(100, &actualCyc, &simRC); // check various states and decide whether to exit loop ... } } Copy to clipboard Note The function calls described in the following sections are public methods of the HexagonWrapper class. ## Co-simulation A co-simulation is a software module that models one or more devices external to the Hexagon processor. It executes in parallel with the Hexagon simulator, and it communicates with the simulator through the simulator API. One use for co-simulations is the creation of specialized monitoring components. Note Co-simulations must be written as single-threaded modules. Although you can use a cosim as a multi-threaded module, QTI does not supported it because the simulator library and l2vic/qtimer cosim are not qualified for multi-thread operations. ### Build co-simulations Co-simulations are built as shared objects or dynamically-loaded libraries. They have the following build requirements. **Windows requirements** - Supports Microsoft Visual Studio 2010 or later - Must specify DLL file, libhexagonissv*<x>*.dll - Must specify /dll option For example: link.exe vcodec.o /dll libhexagonissv\ **.dll /libpath:c:\\hexagon\\ Tools\\lib\\iss /out:vcodec.dll; Copy to clipboard **Linux requirements** - Object files must be compiled with -fPIC option - No need to specify file, libhexagonissv*<x>*.so - Must use -shared option when linking For example: g++ -c -fPIC vcodec.cpp -o vcodec.o; g++ -shared -o vcodec.so vcodec.o; Copy to clipboard ### Execute co-simulations Co-simulations are executed by being specified as arguments to the Hexagon simulator: - The simulator command option --cosim\_file is used to specify the co-simulations for a standalone simulation. (For more information, see [Use the simulator](https://docs.qualcomm.com/doc/80-N3040-23/topic/use-the-simulator.html).) - The simulator API function, [ConfigureCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurecosim), is used to specify the co-simulations for a system simulation. --cosim\_file and ConfigureCosim() both accept the pathname of a text file as an argument. The specified text file contains a list of pathnames that in turn specify the co-simulator library files. Note While it is possible to set up environment variables so the path is not specified, it is usually better for the cosim specification file to use the full path to identify the cosim module. Arguments can be passed to a co-simulation by optionally specifying them after the corresponding co-simulator library filename. For example: /user/me/mycosim/path/cosim1.so arg1 arg2 - Linux /user/me/mycosim/path/cosim2.so C:\\cosims\\cosim1.dll arg1 arg2 - Windows C:\\cosims\\cosim2.dll Copy to clipboard ### Supplied co-simulators The co-simulators described in this section are supplied with the simulator. Their arguments are specified after the co-simulator library filename in the cosim specification file, as described in [Execute co-simulations](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#simulator-execute-cosimulations). Every argument that specifies an address is a physical address, written in hexadecimal (0x) form. Note These co-simulators intercept bus transactions to the address ranges they model, so timing must be enabled (see [ConfigureTimingMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configuretimingmode)) and the modeled regions should be marked with device-type cacheability. #### QTimer co-simulator The QTimer co-simulator (*qtimer.so* on Linux, *qtimer.dll* on Windows) models the standard system QTimer block. The arguments can appear in any order. To list them, specify the co-simulator with no arguments. - **--csr\_base=***addr* - Base address of the Control and Status Registers (CSR). This argument is required. The QTimer and L2VIC register regions are located relative to this address. - **--irq\_p=***irq*[**,***irq*…] - Interrupts triggered when the physical timers pop. This argument is required. One interrupt must be specified for each physical timer frame enabled by --cnttid. - **--irq\_v=***irq*[**,***irq*…] - Interrupts triggered when the virtual timers pop. By default, no virtual timer interrupts are defined. - **--freq=***Hz* - Base timer frequency in Hz. All the timers are derived from this frequency. The default frequency is 19200000 (19.2 MHz). The frequency cannot be set to 0. - **--cnttid=***counterTimerID* - Counter ID, which selects the number of timer frames (0x1 = 1 frame, 0x11 = 2 frames). The default value is 0x11. - **--qtmr-base-offset=***offset* - Offset of the QTimer register region from the address specified by --csr\_base: QTimer base address = csr_base + offset Copy to clipboard The default offset is 0x20000. - **--qtmr-frame-slide=***stride* - Address stride between consecutive QTimer frame segments. The stride must be a non-zero power of two. The default stride is 0x1000. The size of the QTimer address window scales with this value. The window spans 16 segments (8 frames x 2 views), so it extends from the QTimer base address through the address, *base* + (16 x *stride*) - 1. - **--debug** - Writes a message to the standard error stream for bus and memory access errors. Note --qtmr-base-offset and --qtmr-frame-slide default to the values that earlier releases used, so existing co-simulator configurations are unaffected. Specify these arguments when simulating a processor version that relocates the QTimer region or changes the frame stride. For example: qtimer.so --freq=1000 --csr_base=0xfab000000 --irq_p=67 --cnttid=0x1 qtimer.so --csr_base=0xfab000000 --irq_p=67 --cnttid=0x1 --qtmr-base-offset=0x28000 --qtmr-frame-slide=0x2000 Copy to clipboard #### L2VIC co-simulator The L2VIC co-simulator (*l2vic.so* on Linux, *l2vic.dll* on Windows) models a level-2 vectored interrupt controller. It supports up to 32 slices (instantiations of a 32-interrupt controller), for a total of 1024 second-level interrupts. The arguments are positional and must be specified in the order shown. - *slices* - Number of 32-interrupt slices to model, in the range 1 through 32. This argument is required. - *base\_address* - Base address of the L2VIC register block. This argument is required. The base address is normally the CSR base address plus 0x10000. When the QTimer co-simulator is used in the same simulation, this is the address specified by its --csr\_base argument plus 0x10000. - *channels* - Number of L2VIC channels, in the range 1 through 4. This argument is optional. The default is 1 channel. Values outside the supported range are clamped to it. - **--debug=***level* - Writes co-simulator tracing information to the standard output stream. Tracing is enabled by any *level* value of 1 or greater. By default, no tracing information is written. Unlike the positional arguments, this argument can appear anywhere in the argument list. - **Detailed description** - All the modeled L2VIC controllers are tied to first-level interrupt 31 of the Hexagon processor, which must be configured as positive-edge-sensitive. Interrupt vector IDs are ordered from 0 through 1023, with 0 having the highest priority: if multiple interrupts are asserted, the processor VID register is filled with the index of the highest-priority asserted interrupt. The interrupt is cleared after the processor is interrupted. Before an interrupt can be asserted, it must be enabled, either by writing the corresponding interrupt-enable register directly or by setting the appropriate bit in the corresponding interrupt-enable-set register. The interrupt is then asserted by writing the corresponding soft-interrupt register. Note In this co-simulator only, the interrupt-pending registers can also be written directly to assert an interrupt. These registers are read-only in the actual hardware. Writes are permitted here so that, for example, a debugger can simulate external stimuli. For example: l2vic.so 3 0xfab010000 l2vic.so 4 0xb8010000 2 --debug=1 Copy to clipboard #### L2timer co-simulator The L2timer co-simulator (*L2timer.so* on Linux, *L2timer.dll* on Windows) models a general-purpose timer that asserts an interrupt through the L2VIC. The arguments are positional, and all of them are required. They must be specified in the order shown. - *clock\_rate* - Timer frequency in Hz, specified as a decimal integer. The timer counter is incremented once per tick at this frequency. - *timer\_base\_address* - Base address of the timer register block, which occupies 16 bytes. The block contains the following registers: - *timer\_base\_address* - Match value - *timer\_base\_address* + 0x4 - Count value - *timer\_base\_address* + 0x8 - Enable - *timer\_base\_address* + 0xC - Clear In the enable register, bit 0 enables the timer, and bit 1 (CLR\_ON\_MATCH\_EN) selects whether the count value is cleared when it reaches the match value. If bit 1 is clear, the counter continues to run past the match value. - *interrupt\_number* - Number of the interrupt asserted when the count value reaches the match value, specified as a decimal integer. - *l2vic\_base\_address* - Base address of the L2VIC register block, used to assert the interrupt. For example: L2timer.so 19200000 0xab000000 67 0xfab010000 Copy to clipboard #### AXI memory co-simulator The AXI memory co-simulator (*aximem.so* on Linux, *aximem.dll* on Windows) models a memory device attached to the AXI bus over a specified range of physical addresses. - *start\_address***–***end\_address* - Range of physical addresses served by the modeled memory. Both addresses are required, and *end\_address* must be greater than or equal to *start\_address*. Note Both addresses must appear in a single argument with no intervening spaces, as shown in the example below. - **Detailed description** - The end of the registered address window is rounded down to a 256-byte boundary, so specify an *end\_address* that is aligned to a 256-byte boundary to model the intended range exactly. Storage is allocated on demand in 64 KB blocks, so a large address range consumes host memory only for the parts of it that the target application accesses. The co-simulator accepts up to five outstanding bus transactions, each of which completes one tick after it is accepted. Debug reads and writes bypass the queue and complete immediately. For example: aximem.so 0xd0000000--0xd0100000 Copy to clipboard #### Invalid memory co-simulator The invalid memory co-simulator (*badMem.so* on Linux, *badMem.dll* on Windows) reports target application accesses to memory that is not present in the simulated system. The arguments specify the ranges of memory that are *valid*. The co-simulator monitors every address outside those ranges and reports an error when the target application reads or writes one of them. - **-w** | **-f** - Specifies the action taken when an invalid address is accessed. - -w - Report the access and continue the simulation (default) - -f - Report the access and end the simulation If specified, this argument must precede the address ranges. - *start\_address***–***end\_address*[**;***start\_address***–***end\_address*…] - One or more ranges of valid memory, separated by semicolons. At least one range is required, and *end\_address* must be greater than or equal to *start\_address* in each range. A maximum of 10 ranges is supported. Any ranges beyond the tenth are ignored, and a warning message is displayed. Overlapping ranges are merged. - **Detailed description** - When the target application accesses an address outside the specified valid ranges, the co-simulator displays the access type, the accessed address, the value written (for a write), and the current system state. For example: badMem.so -f 0x0--0x1fffffff;0xd0000000--0xd00fffff Copy to clipboard ## Simulator configuration The HexagonWrapper class member functions, which are described in this section, are used to configure the Hexagon simulator library. All the configuration functions have to be called before calling the runtime simulator functions or the simulator control functions. Note Simulator configuration applies to system simulations only—it does *not* apply to [co-simulation modules](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#simulator-co-simulation). Unless otherwise noted, if a configuration function of a certain type is called multiple times, the last configuration overrides the previous setting for that configuration. All filenames referred to as parameters must be in the correct form for the platform expected to be run on. Essentially, the passed-in string must be able to be passed as-is to the fopen() system call. ### [ConfigureRemoteDebug()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies TCP/IP socket that the simulator will write status information to during the simulation. - **Prototype** - HEXAPI_Status ConfigureRemoteDebug(HEX_4u_t portNum); Copy to clipboard - **Parameters** - | in | *portNum* | Assign a TCP port number that the simulator listens on for remote debugging. | | --- | --- | --- | The debugger (hexagon-gdb OR Trace32 with MCD) attaches to this port. (portNum > 1024) - **Detailed description** - The socket is specified as an integer value. This function is analogous to the `--gdbserv (-G)` option in hexagon-sim. Note The debugger connection will be made only when [Run()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#run) is called. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid port number. ### [ConfigureCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Plugs one or more external cosims into the simulator. - **Prototype** - HEXAPI_Status ConfigureCosim(const char *pCosimConfigFile, HEXAPI_OpenMode mode=HEX_MODE_READ); Copy to clipboard - **Parameters** - | in | *pCosimConfigFile* | Pointer to the configuration file for the cosims.


The configuration file contains path to cosim libraries,
followed by (optional) arguments to the cosims. This string
should contain the fully qualified name of the configuration
file. | | --- | --- | --- | | in | *mode* | Open mode for the file.
| - **Detailed description** - A cosim can register to get callbacks for memory reads/writes, bus accesses, PC execution events, and time-based events. Multiple cosims can be specified and are listed on separate lines of the configuration file. This function is analogous to the `--cosim_file` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File access error. - **Example** - Cosim configuration file content: /local/Hexagon_tools_install/Tools/lib/iss/timer.so 32000 0xAB0000002 /local/Hexagon_tools_install/Tools/lib/iss/timer.so 192000000xAB004000 3 /local/MM_cosim/ebi_bus.so 0x100000 Copy to clipboard ### [ConfigureOSAwareness()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Plugs an OS Awareness module into the simulator. - **Prototype** - HEXAPI_Status ConfigureOSAwareness(const char *pOsamConfigFile, HEXAPI_OpenMode mode=HEX_MODE_READ); Copy to clipboard - **Parameters** - | in | *pOsamConfigFile* | Pointer to the fully qualified name of the configuration file
for the OS Awareness module.


This file contains the complete path to the OS Awareness module
shared object or DLL. The string should contain the fully
qualified name of the configuration file. | | --- | --- | --- | | in | *mode* | Open mode for the file.
| - **Detailed description** - The OS Awareness module can register callbacks for the following: - The debugger, to obtain software thread state, mutex information, and so on - PC execution events - Virtual-to-physical translation for servicing Angel calls (semi-hosting) This function is analogous to the `--rtos` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File access error. ### [ConfigureExecutableBinary()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the binary file that is to be loaded into the Hexagon simulator for simulation. - **Prototype** - HEXAPI_Status ConfigureExecutableBinary(const char *pElfFile); Copy to clipboard - **Parameters** - | in | *pElfFile* | Pointer to the fully qualified name of the binary Hexagon ELF
file of the program to be simulated.
This file is opened using HEX\_MODE\_READBINARY mode. | | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File access error. ### [ConfigureAppCommandLine()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Allows command line arguments to be passed to the simulated program. - **Prototype** - HEXAPI_Status ConfigureAppComandLine(int argc, char **argv); Copy to clipboard - **Parameters** - | in | *argc* | Number of arguments in the command line. | | --- | --- | --- | | in | *argv* | Double pointer to an array of strings. | - **Detailed description** - The command line arguments are used to pass arguments to the simulated application. When individual arguments contain whitespace separators, the argument vector must include the escape character, “\”” , at the front and end of the string to preserve the interpretation of the argument. For example, my\_argv[3]=”\”Hexagon Core\””. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid port number. - **Example** - hexagon-sim --timing jpeg.exe ---o pic.ppm -i pic.jpg Copy to clipboard The command line to be passed to the simulated application: jpeg.exe -o pic.ppm -i pic.jpg Copy to clipboard ### [ConfigureSimStdin()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures standard input of the simulated program. - **Prototype** - HEXAPI_Status ConfigureSimStdin(const char *pStdin, HEXAPI_OpenMode mode=HEX_MODE_READ); Copy to clipboard - **Parameters** - | in | *pStdin* | Pointer to the fully qualified name of the file whose contents
are to be used as standard input of the simulated program.
The default value is the STDIN of the host platform. | | --- | --- | --- | | in | *mode* | Open mode for the file
| - **Detailed description** - Any read operation by the simulated program that specifies stdin explicitly or implicitly gets its input from the file associated with the pStdin file. Passing a NULL value in the pStdin file will revert to stdin of the calling process. This function is analogous to the `--sim_in` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File access error. ### [ConfigureSimStdout()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures standard output of the simulated program. - **Prototype** - HEXAPI_Status ConfigureSimStdout(const char *pStdout, HEXAPI_OpenMode mode=HEX_MODE_WRITE); Copy to clipboard - **Parameters** - | in | *pStdout* | Pointer to the fully qualified name of the file whose contents
are to be used as standard output of the simulated program.
The default value is STDOUT of the host platform. | | --- | --- | --- | | in | *mode* | Open mode for the file.
| - **Detailed description** - Any write operation by the simulated program that specifies stdout explicitly or implicitly writes its output to the file associated with the pStdout file. Passing a NULL value in the pStdout file will revert to stdout of the calling process. This function is analogous to the `--sim_out` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File access error. ### [ConfigureSimStderr()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) - **Prototype** - HEXAPI_Status ConfigureSimStderr(const char *pStderr, HEXAPI_OpenMode mode=HEX_MODE_WRITE); Copy to clipboard - **Parameters** - | in | *pStderr* | Pointer to the fully qualified name of the file whose contents
are to be used as standard error output of the simulated
program.


The default value is STDERR of the host platform. | | --- | --- | --- | | in | *mode* | Open mode for the file
- HEX\_MODE\_WRITE (default) - Create for writing; Text mode
- HEX\_MODE\_WRITEBINARY - Create binary file for writing
- HEX\_MODE\_APPEND - Append text
- HEX\_MODE\_APPENDBINARY - Append binary data | - **Detailed description** - Configures the standard error output of the simulated program. Any write operation by the simulated program that specifies stderr explicitly or implicitly writes its output to the file associated with the pStderr file. Passing a NULL value in the pStderr file will revert to stderr of the calling process. This function is analogous to the `--sim_err` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File access error. ### [ConfigureCoreFrequency()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) > > > Specifies the simulated processor clock speed (in Hertz). - **Prototype** - HEXAPI_Status ConfigureCoreFrequency(HEX_8u_t ClkHz); Copy to clipboard - **Parameters** - | in | *ClkHz* | Hexagon clock frequency in Hertz. | | --- | --- | --- | - **Detailed description** - The clock speed is specified as an integer value. It determines the ratio of simulated to real time. The default clock speed is platform-specific. This function is analogous to the `--dsp_clock` option in hexagon-sim, except that the function argument is expressed in Hz while the option argument is expressed in MHz. 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 values. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Frequency out of range. ### [ConfigureTimingMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Enables or disables timing mode. - **Prototype** - HEXAPI_Status ConfigureTimingMode(HEXAPI_TimingMode mode); Copy to clipboard - **Parameters** - | in | *mode* | Timing mode.
| | --- | --- | --- | - **Detailed description** - This function enables or disables cache and core pipeline stall modeling. Correct external bus behavior is guaranteed only when timing mode is enabled. PMU statistics are generated correctly for all events only when timing mode is enabled. Otherwise, when timing mode is disabled, statistics will be correctly generated for some but not all of the events. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureRelaxedTimingMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Enables relaxed timing mode (timing mode modelled with perfect cache). - **Prototype** - HEXAPI_Status ConfigureRelaxedTimingMode(); Copy to clipboard - **Detailed description** - This function enables relaxed timing mode, which activates core pipeline stall modeling with all caches configured as perfect. This provides pipeline behavior without cache miss penalties and with minimal memory latency, useful for isolating it from memory system effects. Relaxed timing mode implies timing mode. External bus behavior and PMU statistics for pipeline events are generated as in full timing mode. Cache miss PMU events will not be generated since all caches always hit. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureBypassIdle()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Skips the execution of pcycles while the processor is idle because all hardware threads are in Wait or Off mode. - **Prototype** - HEXAPI_Status ConfigureBypassIdle(bool enable); Copy to clipboard - **Parameters** - | in | *enable* | Profile mode.
- TRUE - Enable idle modeling
- FALSE - Disable idle modeling (default) | | --- | --- | --- | - **Detailed description** - This function speeds up the simulation when the processor is idle for a significant amount of time. If the number of skipped cycles is nonzero, the value returned by [GetSimulatedCycleCount()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#getsimulatedcyclecount) includes the number of cycles spent while the processor is idle in this way. This function is analogous to the `--bypass_idle` option in hexagon-sim. By default, this function is disabled (FALSE) for all architectures. Setting it to TRUE can accelerate programs with the DSP frequently in Idle mode, but using it will slow down programs that rarely have the DSP in Idle mode. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureCrashHandle()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Enables or disables the crash-site stop that is performed when the target application generates an exception. - **Prototype** - HEXAPI_Status ConfigureCrashHandle(bool mode); Copy to clipboard - **Parameters** - | in | *mode* | Crash-handling mode.
| | --- | --- | --- | - **Detailed description** - When the crash-site stop is enabled and the simulator is used as the simulation engine for the LLDB debugger, an exception generated by the target application returns control to the debugger at the point of failure, before the exception is committed. This allows the processor state to be queried at the point of failure. Setting *mode* to FALSE restores the legacy behavior, in which the exception is committed and the simulation exits. This function is analogous to the `--bypass_crash_handle` option in hexagon-sim. Note The crash-site stop applies only to the LLDB debugger. With other debugger front ends, the exception is always committed. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureAHB()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the address decode range destined for the AHB bus interface. - **Prototype** - HEXAPI_Status ConfigureAHB(HEX_PA_t AHBStartAddr, HEX_PA_t AHBEndAddr); Copy to clipboard - **Parameters** - | in | *AHBStartAddr* | Starting address of the AHB decode range (inclusive). | | --- | --- | --- | | in | *AHBEndAddr* | Ending address of the AHB decode range (inclusive). | - **Detailed description** - When Timing mode is switched ON, bus transactions with addresses within the provided AHB range are routed to the AHB controller. In Standalone mode, this function causes all memory accesses in the specified range to be routed to an internal bus controller that completes the transaction with a specific delay. This delay can be overridden by the `--ahbbuspenalty` option in hexagon-sim or by specifying a timed delay using [ConfigureAHBBusPenalty()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureahbbuspenalty). Additionally, the Hexagon simulator models the bus unit queuing mechanism correctly. All memory transactions outside the given range are routed to an internal AXI bus controller, which also delays the completion of bus requests by the same amount given for the AHB delay. Bus transactions can be intercepted by writing a cosim model and registering to receive callbacks for bus transactions to a specified memory range (see [AddBusAccessCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addbusaccesscallback)). The bus transactions (which can be performed using any algorithm) are completed by calling the [BusTransactionFinished()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#bustransactionfinished) method of the HexagonWrapper class. This function is analogous to the `--ahb` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_RANGE\_ERROR - Incorrect range. ### [ConfigureAXI2()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the address decode range destined for the AXI2 bus interface. - **Prototype** - HEXAPI_Status ConfigureAXI2(HEX_PA_t AXI2StartAddr, HEX_PA_t AXI2EndAddr); Copy to clipboard - **Parameters** - | in | *AXI2StartAddr* | Starting address of the AXI2 decode range (inclusive). | | --- | --- | --- | | in | *AXI2EndAddr* | Ending address of the AXI2 decode range (inclusive). | - **Detailed description** - When Timing mode is switched ON, bus transactions with addresses within the provided AXI2 range are routed to the AXI2 controller. In Standalone mode, this function causes all memory accesses in the specified range to be routed to an internal bus controller that completes the transaction with a specific delay. This delay can be overridden by the `--axi2buspenalty` option in hexagon-sim or by specifying a timed delay using [ConfigureBusPenalty()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurebuspenalty). Also, the Hexagon simulator models the bus unit queuing mechanism correctly. All memory transactions outside the given range are routed to an internal AXI bus controller, which also delays the completion of bus requests by the same amount given for the AXI2 delay. Bus transactions can be intercepted by writing a cosim model and registering to receive callbacks for bus transactions to a specified memory range (see [AddBusAccessCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addbusaccesscallback)). The bus transactions (which can be performed using any algorithm) are completed by calling the [BusTransactionFinished()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#bustransactionfinished) method of the HexagonWrapper class. This function is analogous to the `--axi2` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_RANGE\_ERROR - Incorrect range. - HEX\_STAT\_ERROR - Invalid processor version. ### [ConfigureBusRatio()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the AXI (main) bus clock rate as a non-fractional ratio of the processor clock. - **Prototype** - HEXAPI_Status ConfigureBusRatio(HEX_4u_t busRatio); Copy to clipboard - **Parameters** - | in | *busRatio* | Ratio of the AXI (main) bus clock to the processor clock.


Default value: 2 | | --- | --- | --- | - **Detailed description** - 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. This function is analogous to the `--busratio` option in hexagon-sim. Note To convert cycle counts to simulated execution times, QTI recommends explicitly specifying the AXI bus ratio and not depending on the default values. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Processor does not support this function. ### [ConfigureAHBBusRatio()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the AHB bus clock rate as a non-fractional ratio of the processor clock. - **Prototype** - HEXAPI_Status ConfigureAHBBusRatio(HEX_4u_t busRatio); Copy to clipboard - **Parameters** - | in | *busRatio* | Ratio of AHB bus clock to processor clock. Default value: 2 | | --- | --- | --- | - **Detailed description** - This function is analogous to the `--ahbbusratio` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Processor does not support this function. ### [ConfigureAXI2BusRatio()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the AXI2 bus clock rate as a non-fractional ratio of the processor clock. - **Prototype** - HEXAPI_Status ConfigureAXI2BusRatio(HEX_4u_t busRatio); Copy to clipboard - **Parameters** - | in | *busRatio* | Ratio of the AXI2 bus clock to the processor clock. Default


value: 2 | | --- | --- | --- | - **Detailed description** - This function is analogous to the `--axi2busratio` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Processor does not support this function. ### [ConfigureBusPenalty()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures the default latency for AXI (main) bus accesses across the entire memory range. - **Prototype** - HEXAPI_Status ConfigureBusPenalty(HEX_8u_t BusPenaltyInterval, HEXAPI_Interval units); Copy to clipboard - **Parameters** - | in | *BusPenaltyInterval* | AXI (main) bus penalty in simulation real-time units. | | --- | --- | --- | | in | *units* | Units that represent the BusPenaltyInterval parameter.
| - **Detailed description** - This latency can be overridden by connecting a bus cosim for appropriate address ranges. The latency is determined by the core clock frequency and simulates real time as if the core were running at the specified frequency. There is no direct relation to real time (wall-clock time). The granularity of the time increment is bounded by the current core frequency setting. The finest granularity available corresponds to the time taken by a single processor cycle. All time values are scaled according to the current processor clock frequency and are rescaled if the core frequency changes. This function is analogous to the `--buspenalty` option in hexagon-sim, except that the function accepts a time value while the option accepts a cycle count. The bus is simulated at its own frequency, as determined by the [ConfigureCoreFrequency()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurecorefrequency) and [ConfigureBusRatio()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurebusratio) settings. If units = HEX\_PCYCLE, the busRatio and busPenalty parameters are ignored for the registered callback. Use this option with care. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Incorrect parameters. ### [ConfigureAHBBusPenalty()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures the default latency for AHB bus accesses across the entire memory range. - **Prototype** - HEXAPI_Status ConfigureAHBBusPenalty(HEX_8u_t BusPenaltyInterval, HEXAPI_Interval units); Copy to clipboard - **Parameters** - | in | *BusPenaltyInterval* | AHB bus penalty in simulation real-time units. | | --- | --- | --- | | in | *units* | Units that represent the BusPenaltyInterval parameter.
| - **Detailed description** - This latency can be overridden by connecting a bus cosim for the appropriate address ranges. The latency is determined by the core clock frequency and simulates real time as if the core were running at the specified frequency. There is no direct relation to real time (wall-clock time). The granularity of the time increment is bounded by the current core frequency setting. The finest granularity available corresponds to the time taken by a single processor cycle. All time values are scaled according to the current processor clock frequency and are rescaled if the core frequency changes. This function is analogous to the `--ahbbuspenalty` option in hexagon-sim, except that the function accepts a time value while the option accepts a cycle count. The bus is simulated at its own frequency, as determined by the [ConfigureCoreFrequency()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurecorefrequency) and [ConfigureAHBBusRatio()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureahbbusratio) settings. Note To specify the bus penalty in terms of cycles, contact Hexagon technical support for assistance. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Incorrect parameters. ### [ConfigureAXI2BusPenalty()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures the default latency for AXI2 bus accesses across the entire memory range. - **Prototype** - HEXAPI_Status ConfigureAXI2BusPenalty(HEX_8u_t BusPenaltyInterval, HEXAPI_Interval units); Copy to clipboard - **Parameters** - | in | *BusPenaltyInterval* | AXI2 bus penalty in simulation real-time units. | | --- | --- | --- | | in | *units* | Units that represent the BusPenaltyInterval parameter.
| - **Detailed description** - This latency can be overridden by connecting a bus cosim for the appropriate address ranges. The latency is determined by the core clock frequency and simulates real time as if the core were running at the specified frequency. There is no direct relation to real time (wall-clock time). The granularity of the time increment is bounded by the current core frequency setting. The finest granularity available corresponds to the time taken by a single processor cycle. All time values are scaled according to the current processor clock frequency and are rescaled if the core frequency changes. This function is analogous to the `--axi2buspenalty` option in hexagon-sim, except that the function accepts a time value while the option accepts a cycle count. The bus is simulated at its own frequency, as determined by the [ConfigureCoreFrequency()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurecorefrequency) and [ConfigureAXI2BusRatio()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureaxi2busratio) settings. Note To specify the bus penalty in terms of cycles, contact Hexagon technical support for assistance. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Incorrect parameters. ### [ConfigureTCM()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the start of TCM. - **Prototype** - HEXAPI_Status ConfigureTCM(HEX_PA_t TCMStartAddr); Copy to clipboard - **Parameters** - | in | *TCMStartAddr* | Starting address of the TCM decode range. | | --- | --- | --- | - **Detailed description** - The size of TCM is determined by the specific Hexagon processor version, micro- architecture, and L2 cache configuration. When Timing mode is switched ON, within the TCM range do not result in external bus transactions. The latency of TCM is accurately modeled for the given processor version. This function is analogous to the `--tcm:lowaddr` options in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid address. This error is issued when the start address plus the TCM size overflows the address space. ### [ConfigureSubsystemBase()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the subsystem base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. Note This function is supported only for the Hexagon Tools 7.x and later releases. - **Prototype** - HEXAPI_Status ConfigureSubsystemBase(HEX_4u_t subStart); Copy to clipboard - **Parameters** - | in | *subStart* | Address value of the CFGBASE subsystem base. | | --- | --- | --- | - **Detailed description** - The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. This function is analogous to the `--subsystem_base` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureL2tcmBase()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the L2 TCM base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. Note This function is supported only for the Hexagon Tools 7.x and later releases. - **Prototype** - HEXAPI_Status ConfigureL2tcmBase(HEX_4u_t l2tcmStart); Copy to clipboard - **Parameters** - | in | *l2tcmStart* | Address value of the CFGBASE L2 TCM base. | | --- | --- | --- | - **Detailed description** - The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. This function is analogous to the `--l2tcm_base option` in hexagon-sim. If this function is not called, the simulator assigns the L2 TCM base address a default value that is internally determined. The simulator sets the value of the CFGBASE register itself to (l2tcmStart + 0x18), where 0x18 denotes 0x180000 in the physical address space. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureL2cfgBase()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the L2 configuration base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. Note This function is supported only for the Hexagon Tools 7.x and later releases. - **Prototype** - HEXAPI_Status ConfigureL2cfgBase(HEX_4u_t l2cfgStart); Copy to clipboard - **Parameters** - | in | *l2cfgStart* | Address value of the CFGBASE L2 configuration base. | | --- | --- | --- | - **Detailed description** - The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. This function is analogous to the `--l2cfg_base` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureEtmcfgBase()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the ETM base address value that is stored in the configuration table referenced by the Hexagon system-level register CFGBASE. Note This function is supported only for the Hexagon Tools 7.x and later releases. - **Prototype** - HEXAPI_Status ConfigureEtmcfgBase(HEX_4u_t etmStart); Copy to clipboard - **Parameters** - | in | *etmStart* | Address value of the CFGBASE ETM base. | | --- | --- | --- | - **Detailed description** - The base address value specifies bits [35:16] of a 36-bit physical memory address. Bits [15:0] are assumed to be 0. This function is analogous to the `--etm_base` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureMemFill()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies a value to be used for all uninitialized memory. - **Prototype** - HEXAPI_Status ConfigureMemFill(HEX_1u_t value); Copy to clipboard - **Parameters** - | in | *value* | One-byte value used to fill all of memory (that is, the initial
value of uninitialized memory).
Default: 0x1F | | --- | --- | --- | - **Detailed description** - The simulator fills all of memory with the specified value before simulation starts. This function is analogous to the `--memfill` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureMemFillRandom()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies a value to be used as a random number seed. - **Prototype** - HEXAPI_Status ConfigureMemFillRandom(HEX_4u_t seed); Copy to clipboard - **Parameters** - | in | *seed* | Value used to seed the random number generator for memory fill
operations.


The simulator fills all of memory (that is, the initial value
of uninitialized memory) with random numbers using the rand()
function of the host platform. | | --- | --- | --- | - **Detailed description** - The simulator uses the rand() host function to initialize values for all uninitialized memory. The behavior of this function depends on the host implementation of the random number generator. This function is analogous to the `--memfill_rand` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureNULLPointerBehavior()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Instructs the simulator on how NULL pointer dereferences should be handled. - **Prototype** - HEXAPI_Status ConfigureNULLPointerBehavior(HEXAPI_Nullptr behavior); Copy to clipboard - **Parameters** - | in | *behavior* | Describes how the simulator should handle NULL pointer
dereferences.
| | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureCoreDump()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Generates a binary core dump file when the target application is terminated after generating an exception. - **Prototype** - HEXAPI_Status ConfigureCoreDump(const char *filename); Copy to clipboard - **Parameters** - | in | *filename* | Pointer to the fully qualified name of the core dump file
generated by the simulator. | | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. Note This function returns HEX\_STAT\_SUCCESS even if the simulator is unable to subsequently create the core dump file. ### [ConfigureGProf()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures the data dump for the GNU profiler. - **Prototype** - HEXAPI_Status ConfigureGProf(const char *gprofPath=NULL); Copy to clipboard - **Parameters** - | in | *gprofPath* | Pointer to the string providing the path in which the gprof
files are to be created. | | --- | --- | --- | - **Detailed description** - For details, see [Chapter 3](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#use-the-simulator). The profiling files are created in the specified directory. If a NULL directory is supplied, the files are created in the current working directory. The simulator overwrites existing files without warning. This function is analogous to the `--profile` option in hexagon-sim. Note If this function is not called, gprof profiling is disabled. Calling this function either with or without a gprofPath argument will enable gprof profiling. Once enabled, there is no way to disable gprof profiling for this session. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - Problem accessing the file. ### [ConfigureProfileMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies whether gprof profiling starts from time zero. - **Prototype** - HEXAPI_Status ConfigureProfileMode(bool bTimeZero); Copy to clipboard - **Parameters** - | in | *bTimeZero* | Profile mode.
| | --- | --- | --- | - **Detailed description** - For RTOS applications, a start time of zero indicates that profile data collection begins immediately, and thus includes the OS bootup instructions. If bTimeZero is set to TRUE, gprof profile data collection starts from time zero. If bTimeZero is set to FALSE, gprof profile data collection does not start from time zero, and thus does not include the OS bootup instructions in the profile data. This function is analogous to the `--profile_timezero` option in hexagon-sim. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigurePmuStatisticsFile()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Specifies the file that the collected PMU statistics will be written to. - **Prototype** - HEXAPI_Status ConfigurePmuStatisticsFile(const char *pmuStatsFile, HEXAPI_OpenMode mode=HEX_MODE_WRITE); Copy to clipboard - **Parameters** - | in | *pmuStatsFile* | Pointer to the fully qualified name of the file to which Hexagon
PMU statistics are to be written. | | --- | --- | --- | | in | *mode* | Open mode for the file.
| - **Detailed description** - The collected data is not written to the output file until the HexagonWrapper destructor is called. Note By default, PMU statistics are collected for the entire program. To limit the collection to specific parts of a program, use ConfigurePCRangeFilter and ConfigureTimeRangeFilter. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - Problem accessing the file. ### [ConfigurePacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures the collection of instruction packet execution statistics, and enables the collection of statistics data. Note It returns HEX\_STAT\_ERROR if it is called with any other version. - **Prototype** - HEXAPI_Status ConfigurePacketAnalysis(const char *filename, HEXAPI_OpenMode mode=HEX_MODE_WRITE); Copy to clipboard - **Parameters** - | in | *filename* | Pointer to the fully qualified name of the file to which Hexagon
packet statistics are to be written. | | --- | --- | --- | | in | *mode* | Open mode for the file.
| - **Detailed description** - The collected data is not written to the output file until the HexagonWrapper destructor is called. This operation is performed in sync on the Hexagon processor and coprocessor. The mode argument is optional—if omitted, the file open mode defaults to the text file format of the host platform. This function is analogous to the `--packet_analyze` option in hexagon-sim. By default, statistics are collected for the entire program. To limit the data collection to specific parts of a program, use [ConfigurePCRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurepcrangefilter) and [ConfigureTimeRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configuretimerangefilter). Alternatively, the data collection can be controlled dynamically using [EnablePacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#enablepacketanalysis). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Incorrect parameters. - HEX\_STAT\_FILE\_ACCESS\_ERROR - Problem accessing the file. - HEX\_STAT\_ERROR - Invalid processor version. ### [ConfigureInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Configures the generation of instruction histogram data and enables the collection of histogram data. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status ConfigureInstHistogram(const char *filename, HEXAPI_OpenMode mode=HEX_MODE_WRITE); Copy to clipboard - **Parameters** - | in | *filename* | - Pointer to the fully qualified name of the file to which Hexagon
- instruction histogram data is to be written. | | --- | --- | --- | | in | *mode* | Open mode for the file.
- HEX\_MODE\_WRITE (default) - Create for writing; Text mode
- HEX\_MODE\_WRITEBINARY - Create binary file for writing
- HEX\_MODE\_APPEND - Append text
- HEX\_MODE\_APPENDBINARY - Append binary data | - **Detailed description** - The mode argument is optional—if omitted, the file open mode defaults to the text file format of the host platform. This function is analogous to the `--ihist` option in hexagon-sim. By default, histogram data is collected for the entire program. To limit the data collection to specific parts of a program, use [ConfigurePCRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurepcrangefilter) and [ConfigureTimeRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configuretimerangefilter). Alternatively, the data collection can be controlled dynamically using [EnableInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#enableinsthistogram). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_FILE\_ACCESS\_ERROR - Problem accessing the file. ### [ConfigurePCRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Enables starting and stopping of statistics collection and tracing based on instruction execution. - **Prototype** - HEXAPI_Status ConfigurePCRangeFilter(HEX_VA_t PCStart, HEX_VA_t PCEnd); Copy to clipboard - **Parameters** - | in | *PCStart* | Address of an instruction that, when committed, starts the
profiling data collection. | | --- | --- | --- | | in | *PCEnd* | Address of an instruction that, when committed, ends the
profiling data collection. | - **Detailed description** - This function applies to all forms of statistics collection: gprof and normal execution statistics. This also applies to trace generation. When the instruction at the PCStart address is committed, statistics collection is started. This means that statistics for the PCStart packet are not in the trace data. When the instruction at the PCStart address is committed, statistics collection terminates. This means that statistics the PCStart packet are in the trace data. Statistics collection will never be restarted, even if the instruction at PCStart is executed again. This routine merely enables the collection of statistical data. To print the statistical information, use [EmitPerfStatistics()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#emitperfstatistics). This function works in conjunction with [ConfigureTimeRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configuretimerangefilter). Statistics collection begins when either the TimeStart or PCStart conditions are satisfied and terminates whenever either the TimeEnd or PCEnd conditions are met. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [ConfigureTimeRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Enables starting and stopping of statistics collection and tracing based on elapsed simulation time. - **Prototype** - HEXAPI_Status ConfigureTimeRangeFilter(HEX_8u_t TimeStart, HEXAPI_Interval StartUnits, HEX_8u_t TimeEnd, HEXAPI_Interval EndUnits); Copy to clipboard - **Parameters** - | in | *TimeStart* | Time value that indicates when to start profiling data
collection. | | --- | --- | --- | | in | *StartUnits* | Units that represent the TimeStart parameter.
| | in | *TimeEnd* | Time value that indicates when to end profiling data collection. | | in | *EndUnits* | Units that represent the TimeEnd parameter.
| - **Detailed description** - This function applies to all forms of statistics collection: gprof and normal execution statistics. This also applies to trace generation. When TimeStart time has elapsed, statistics collection is started. When TimeEnd time has elapsed, statistics collection terminates. Statistics collection will never be restarted. This routine merely enables the collection of statistical data. To print the statistical information, use [EmitPerfStatistics()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#emitperfstatistics). This function works in conjunction with [ConfigurePCRangeFilter()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurepcrangefilter). Statistics collection begins when either the TimeStart or PCStart conditions are satisfied and terminates whenever either the TimeEnd or PCEnd conditions are met. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. ### [EndOfConfiguration()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Signals the end of simulator configuration. - **Prototype** - HEXAPI_Status EndOfConfiguration(); Copy to clipboard - **Detailed description** - Indicate to the simulator that the configuration functions will no longer be called. Calling this function causes the simulator to evaluate configuration options and load cosims, OS Awareness modules, symbol files, and so on If a binary image was provided, it is loaded into Hexagon simulator memory. Note Any configuration function that is called after this function returns an error (HEX\_STAT\_CANNOT\_CONFIG). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Cannot configure the simulator. End of the configuration phase. - HEX\_STAT\_ERROR - An error exists in the configuration (for example, executable image is not valid or is not readable). ### [SetTracing()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Enables or disables tracing at any time during execution. - **Prototype** - HEXAPI_Status SetTracing(HEXAPI_TracingType TracingType, const char *pTraceOutputFile, HEXAPI_OpenMode mode=HEX_MODE_WRITE); Copy to clipboard - **Parameters** - | in | *TracingType* | | | --- | --- | --- | | out | *pTraceOutputFile* | Pointer to the fully qualified name of the file to contain the
respective trace’s data. | | in | *mode* | Open mode for the file.
| - **Detailed description** - The configuration of all trace types must occur before the call to [EndOfConfiguration()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#endofconfiguration). Tracing can be enabled or disabled at any time during execution. - To disable tracing, pass a NULL pointer as the pTraceOutputFile argument in a call for that type. If pTraceOutputFile is NULL, the mode is ignored. - If the pTraceOutputFile argument is specified as non-NULL, a trace file is opened with the mode specified for the designated TracingType. - **Example** - HEX\_TRACE\_PC\_MIN is a subset of HEX\_TRACE\_PC. HEX\_TRACE\_UARCH is the union of HEX\_TRACE\_ICACHE, HEX\_TRACE\_DCACHE, HEX\_TRACE\_L2CACHE, HEX\_TRACE\_BUS, and HEX\_TRACE\_STALL. [tools/cosims]: commit f6c7debe9cbeaa4b9814deb3ac06f57dfac12cbe Date: Mon Jan 26 09:36:36 2015 -0600 [tools/include]: commit 0e39da28de130336781f1054e15ca29835e95b90 Date: Fri Jul 23 16:38:55 2010 +0000 Copy to clipboard - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Invalid tracing type. - HEX\_STAT\_FILE\_ACCESS\_ERROR - File pointer error. ### [ConfigureMaxPcycle()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#contents) Controls how many pcycles to simulate. - **Prototype** - HEXAPI_Status ConfigureMaxPcycle(HEX_8u_t limit=0); Copy to clipboard - **Parameters** - | in | *limit* | Number of pcycles to simulate. | | --- | --- | --- | - **Detailed description** - This configuration call must occur before the call to [EndOfConfiguration()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#endofconfiguration). The default argument is zero, meaning there is no limit (default simulator behavior). If the simulation is terminated because the cycle limit is reached, the hexagon-sim return status is HEX\_CORE\_CYCLE\_LIMIT. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Invalid tracing type. - HEX\_CORE\_CYCLE\_LIMIT - File pointer error. ## External device API Device registration functions are used by cosims or the system simulation application to register its callback functions with the Hexagon simulator. All the registration functions can be called before or after the configuration phase is complete. Each of these device registration/de-registration functions can be called multiple times. ### [AddBusAccessCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Registers a function to be called when the core issues a bus request for the memory within the specified range. - **Prototype** - typedef HEXAPI_TransactionStatus (*bus_transaction_request_callback) (void *handle, HEX_PA_t address, HEX_4u_t lengthInBytes, HEX_1u_t *data, HEX_4u_t requestID, HEXAPI_BusAccessType type, HEX_4u_t threadNum, HEXAPI_BusBurstType burst); HEXAPI_Status AddBusAccessCallback(void *handle, HEX_PA_t startAddr, HEX_PA_t endAddr, bus_transaction_request_callback brtc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *startAddr* | Lower bound (inclusive) of the address range to be registered
for this device. | | in | *endAddr* | Upper bound (inclusive) of the address range to be registered
for this device. | | in | *btrc* | Pointer to a function to be called when a bus request is made to
the given address region. See
[BusTransactionRequestCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#bustransactionrequestcallback). | - **Detailed description** - The registered function must have the given prototype and returns zero if the bus request can be accepted. If the bus request cannot be accepted, a non-zero value is returned and the core stalls the requesting thread and re-issues the request at a later time. If the request is accepted, the core keeps the requesting thread stalled until it receives a [BusTransactionFinished()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#bustransactionfinished) call to indicate completion of the transaction. The intent is to allow you to model a bus. Typically, the called function (btrc) registers an alarm callback ([AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addtimedcallback)) to receive notification from the simulator that the expected latency for the operation has expired. At that time, the bus model signals completion of the requested bus operation. Overlapping address ranges that are registered by different external models are rejected. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Bus address ranges overlap. ### [RemoveBusAccessCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Removes callback notification for an external bus model from the simulator. - **Prototype** - HEXAPI_Status RemoveBusAccessCallback(void *handle); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | - **Detailed description** - The callbacks associated with the handle are removed for all address ranges for which a callback was registered. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot find registered bus device. ### [AddFrequencyChangeCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model that requires simulator notification every time the Hexagon core frequency changes. It can use the new frequency to calculate appropriate delays as required. - **Prototype** - typedef void (*frequency_change_callback) (void *handle, HEX_4u_t newFrequency); HEXAPI_Status AddFrequencyChangeCallback( void *handle, frequency_change_callback fcc) Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *fcc* | Pointer to a function to call for frequency change notification.
See [FrequencyChangeCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#frequencychangecallback). | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot find registered bus device. ### [RemoveFrequencyChangeCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model to remove itself from a list of devices that have registered to get a callback every time the core frequency changes. - **Prototype** - HEXAPI_Status RemoveFrequencyChangeCallback(void *handle); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot remove call to [FrequencyChangeCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#frequencychangecallback) for the device. ### [AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model that requires notification from the simulator that interval simulator-time units have expired. This notification continues to be delivered by the simulator until canceled. - **Prototype** - typedef void (*timed_callback) (void *handle); HEXAPI_Status AddTimedCallback(void *handle, HEX_8u_t interval, HEXAPI_Interval i_typ, timed_callback tc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *interval* | Interval in terms of simulator-time units. | | in | *i\_typ* | Units that represent the interval parameter.
| | in | *tc* | Pointer to a function to be called every interval time units.
See [TimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#timedcallback). | - **Detailed description** - The granularity of the time increment is bounded by the current core frequency setting. The finest granularity available corresponds to the time taken by a single processor cycle. All time values are scaled according to the current processor clock frequency and are rescaled if the core frequency changes. The parameter handle can be anything. The addition and removal of a timedCallback is keyed on this handle. Have a unique handle for each instance of a new callback. If you add two callbacks using the same handle and then remove one callback, both callbacks are removed. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot register the callback. ### [AddTimedCallbackFP()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model that requires notification from the simulator that a specified number of simulator-time units have expired. This notification continues to be delivered by the simulator until canceled. Note This function is identical to [AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addtimedcallback), except that the time interval is expressed as a double-precision floating point value. - **Prototype** - typedef void (*timed_callback) (void *handle); HEXAPI_Status AddTimedCallbackFP(void *handle, HEX_8f_t interval, HEXAPI_Interval i_typ, timed_callback tc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *interval* | Interval in terms of simulator-time units (expressed as
double-precision floating point value). | | in | *i\_typ* | Units that represent the interval parameter.
| | in | *tc* | Pointer to a function to be called every interval time units.
See [TimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#timedcallback). | - **Detailed description** - The granularity of the time increment is bounded by the current core frequency setting. The finest granularity available corresponds to the time taken by a single processor cycle. All time values are scaled according to the current processor clock frequency and are rescaled if the core frequency changes. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot register the callback. ### [AddOneShotTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model that requires notification from the simulator that a specified number of simulator-time units have expired. This notification is delivered only once; for repeated notifications, use [AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addtimedcallback) instead. - **Prototype** - typedef void (*timed_callback) (void *handle); HEXAPI_Status AddOneShotTimedCallback(void *handle, HEX_8u_t interval, HEXAPI_Interval i_typ, timed_callback tc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs) | | --- | --- | --- | | in | *interval* | Interval in terms of simulator-time units. | | in | *i\_typ* | Units that represent the interval parameter.
| | in | *tc* | Pointer to a function to be called every interval time units.
See [TimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#timedcallback). | - **Detailed description** - The granularity of the time increment is bounded by the current core frequency setting. The finest granularity available corresponds to the time taken by a single processor cycle. All time values are scaled according to the current processor clock frequency and are rescaled if the core frequency changes. Note [RemoveTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#removetimedcallback) is not necessary for one-shot timed callbacks, except to stop the notification before it occurs. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot register the callback. ### [RemoveTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model to remove itself from a list of devices that have registered to get a callback every interval period. - **Prototype** - HEXAPI_Status RemoveTimedCallback(void *handle); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot remove TimedCallback for the device. ### [AddMemWasWrittenCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Registers an external device that monitors memory write events. - **Prototype** - typedef void (*memory_written_callback) (void *handle, HEX_PA_t address, HEX_8u_t value, HEX_4u_t sizeInBytes); HEXAPI_Status AddMemWasWrittenCallback(void *handle, HEX_PA_t startAddr, HEX_PA_t endAddr, memory_written_callback mwc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *startAddr* | Lower bound of the address range registered for this device. | | in | *endAddr* | Upper bound of the address range registered for this device.
endAddr is inclusive in the range. | | in | *mwc* | Pointer to a function to be called whenever the core writes to
memory with an address in the specified range (inclusive). See
[MemoryWasWrittenCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#memorywaswrittencallback). | - **Detailed description** - The mwc function is called by the simulator when a memory write is detected whose address is within the range of [*startAddr, endAddr*]. This function accepts overlapping ranges. Note mwc is called on *any* memory write event, even if the access results in a cache hit. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot add memory write monitor callback. ### [RemoveMemWasWrittenCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Removes notifications for an external device that tracks memory write events. - **Prototype** - HEXAPI_Status RemoveMemWasWrittenCallback(void *handle); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | - **Detailed description** - All memory ranges intercepted by the cosim associated with the handle will have their callback notifications removed. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot remove memory write monitor. ### [AddMemWasReadCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) > > > Registers an external device that monitors memory read events. - **Prototype** - typedef void (*memory_read_callback) (void *handle, HEX_PA_t address, HEX_8u_t value, HEX_4u_t sizeInBytes); HEXAPI_Status AddMemWasReadCallback(void *handle, HEX_PA_t startAddr, HEX_PA_t endAddr, memory_read_callback mrc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *startAddr* | Lower bound of the address range registered for this device. | | in | *endAddr* | Upper bound of the address range registered for this device.
endAddr is inclusive in the range. | | in | *mrc* | Pointer to a function to be called whenever the core reads from
memory with an address in the specified range (inclusive). See
[MemoryWasReadCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#memorywasreadcallback). | - **Detailed description** - The mrc function is called by the simulator when a memory read is detected whose address is within the range of [*startAddr, endAddr*]. This function accepts overlapping ranges. Note mwc is called on *any* memory read event, even if the access results in a cache hit. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot configure the memory read monitor. ### [RemoveMemWasReadCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Removes notifications for an external device that tracks memory read events. - **Prototype** - HEXAPI_Status RemoveMemWasReadCallback(void *handle); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external cosim handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | - **Detailed description** - All memory ranges intercepted by the cosim associated with the handle will have their callback notifications removed. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot remove the memory read monitor. ### [AddPCCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Registers a callback function that corresponds to the execution of an instruction indexed by a PC. - **Prototype** - typedef (void) (*pc_callback) (void *handle); HEXAPI_Status AddPCCallback(void *handle, HEX_VA_t vpc, pc_callback pcc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external cosim handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *vpc* | PC address in virtual space where the breakpoint is to be set. | | in | *pcc* | Function pointer to the callback function that is called when
vpc is reached. See [PCCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#pccallback). | - **Detailed description** - This callback function is invoked just before the instruction at PC is committed. Only one callback function that corresponds to a VPC address by one cosim can be registered. The callback is triggered when the currently executing thread’s PC register equals this value. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot register the PC callback at vpc. ### [RemovePCCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Removes a PCCallback function that corresponds to the execution of an instruction indexed by a PC. - **Prototype** - HEXAPI_Status RemovePCCallback(void *handle, HEX_VA_t vpc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external cosim handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *vpc* | PC address in virtual space where the breakpoint is to be
removed. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot remove the PC callback at vpc. ### [AddBeforeSimulationStartsCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Registers a callback function that will be called at the end of [EndOfConfiguration()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#endofconfiguration). - **Prototype** - typedef (void) (*cosim_callback)(void *handle); HEXAPI_Status AddBeforeSimulationStartsCallback(void *handle, cosim_callback cc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external cosim handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *cc* | Pointer to a function to be called after configuration has
completed but before the first cycle is simulated. | - **Detailed description** - When this callback is made, the simulator has been fully configured, including instantiating all cosims and loading the executable image (if one was specified). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Cannot set the callback. ### [AddEndOfSimulationCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Registers a callback function that will be called at the end of simulation. - **Prototype** - typedef (void) (*cosim_callback)(void *handle); HEXAPI_Status AddEndOfSimulationCallback(void *handle, cosim_callback cc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external cosim handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *cc* | Pointer to a function to be called after simulation has finished
but before resources are deallocated. | - **Detailed description** - When this callback is made, the simulation has terminated but no resources (cosims, memory, statistics, and so on) have been freed. When this callback is made, the cosim is free to make any calls that do not attempt to advance the simulation. For instance, statistics can be printed, memory can be examined, and so on - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Cannot set the callback. ### [AddCoreReadyCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model that requires notification when the core’s CORE\_READY signal changes state. - **Prototype** - typedef void (*core_ready_callback)(void *handle, HEXAPI_CoreReadyState polarity); HEXAPI_Status AddCoreReadyCallback(void *handle, core_ready_callback crc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *crc* | Pointer to a function to call for core ready state change. See
[CoreReadyCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#corereadycallback). | - **Detailed description** - This function is used primarily by cosims that are modeling second-level interrupt controllers. The state of this signal indicates whether the core is ready to accept an interrupt from the second-level controller. The polarity parameter of the callback function can be either CORE\_READY or CORE\_NOT\_READY. Note No RemoveCoreReadyCallback function is defined in the API because this callback is expected to remain active throughout the simulation. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Resource allocation error or invalid processor version. ### [AddPrivilegeChangeCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Used by an external device model that requires notification when the Hexagon processor’s privilege mode changes. - **Prototype** - typedef void (*privilege_change_callback) (void *handle, HEX_4u_t hardware_thread_id, HEXAPI_PrivilegeMode mode); HEXAPI_Status AddPrivilegeChangeCallback(void *handle, privilege_change_callback pcc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *pcc* | Pointer to a function to call for privilege state change. See
[CoreReadyCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#corereadycallback). | - **Detailed description** - The hardware\_thread\_id parameter of the callback function indicates the hardware thread associated with the privilege mode change. The mode parameter of the callback function indicates the new privilege mode. It can be either MONITOR\_MODE, USER\_MODE, GUEST\_MODE, or INVALID\_MODE. Note Before this callback was added to the simulator system API, the caller was required to poll the simulator to determine when privilege changes occurred. Note No RemovePrivilegeChangeCallback function is defined in the API because this callback is expected to remain active throughout the simulation. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Resource allocation error or invalid processor version. ### [AddQtimerCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Registers an external device that models Qtimer (a standard system module external to the Hexagon processor). Note It returns HEX\_STAT\_ERROR if it is called with any other version. - **Prototype** - typedef HEX_8u_t (*qtimer_callback) (void *handle, int index); HEXAPI_Status AddQtimerCallback(void *handle, qtimer_callback qtc); Copy to clipboard - **Parameters** - | in | *handle* | Pointer to the external bus model handle returned from
[RegisterCosim()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosim) or
[RegisterCosimArgs()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#registercosimargs). | | --- | --- | --- | | in | *qtc* | Pointer to a function to call for the Qtimer event. | - **Detailed description** - The qtc function is called by the simulator when the core needs to access Qtimer. The registered function accepts an index value that specifies the Qtimer event type. Currently this index value will always be 0, which indicates that the core issued a Qtimer read request. In this case the registered function must return (as a function result value) a 56-bit unsigned integer value indicating Qtimer’s current physical counter value. Note In future versions of the simulator, the index value might be set to other values to indicate that different types of Qtimer requests are being issued. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_DEVICE\_NOT\_FOUND - Cannot register the callback. - HEX\_STAT\_ERROR - Invalid processor version. ### [GetAPIVersion()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Returns the current API version. - **Prototype** - void GetAPIVersion(HEX_4u_t *major, HEX_4u_t *minor, HEX_4u_t *build); Copy to clipboard - **Parameters** - | out | *major* | Pointer to the major API revision number. | | --- | --- | --- | | out | *minor* | Pointer to the minor API revision number. | | out | *build* | Pointer to the build identifier. | - **Detailed description** - This function can be used by either a system simulation environment or a co-simulation model to validate compatibility with the API. The major version number increments when incompatibilities are introduced in the API. - **Returns** - None. ### [PrintBuildTag()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id4) Print the build tag information for the simulator library. The information is written to the standard output. - **Prototype** - Copy to clipboard void PrintBuild Tag(void); - **Detailed description** - Build tag information is intended primarily for users who are running system simulations, and occasionally need detailed information on how the simulator library was built. For users running standalone simulations, build tag information is generally not useful. This function is analogous to the `--build_tag` option in hexagon-sim. Note For simulator API users: if you are not sure which library versions are loaded for your run-time instance, add this call and report to QTI field support for help on determining the exact versions. - **Returns** - None. **Example** Build tag information is formatted as follows in the standard output: hexagon-sim --build_tag [arch_v62]: TAGS co-located: v62_20200227 commit f8f0b09fd5fb6625dfa4681b46782095e3e0b05f Date: Wed Jan 15 11:08:27 2020 -0600 [arch_v65]: TAGS co-located: v65_20200917 v65_20201214 commit 544bd4c15d696c584a940482d2391f48b996ad89 Date: Mon Aug 24 12:20:33 2020 -0500 [arch_v66]: TAGS co-located: v66_20201214 commit 89c837eeca7f855e12f570aaca0fa4dd0158250a Date: Fri Oct 30 15:21:06 2020 -0500 [arch_v67]: TAGS co-located: v67_20201214 commit 9a9892fbe2cf8e185aba62c05bbdf697ee6a36aa Date: Mon Nov 30 23:23:45 2020 -0800 [arch_v68]: TAGS co-located: v68_20201214 commit 43dcfbc5d76e378306a74b122d53a082e6a2f7e1 Date: Mon Dec 7 19:42:03 2020 -0800 [tools/simulator]: BRANCH: (no commit 249d91cb8546ae512cbe69bb10f7855f3aed3596 Date: Fri Feb 26 09:19:35 2021 -0800 [tools/libs]: commit 5e2b0ddfd2679a94528d4e996ad26e16e3eb18ff Date: Fri Feb 5 13:18:43 2021 -0600 [tools/cosims]: commit 7451e9c494f361b9abc874e0291da14abdeb068a Date: Mon Mar 2 18:11:24 2020 -0600 [tools/ddrclade]: Clade Version: 01, 01, 47 Clade2 Version: 01, 01, 62 Internal-use-only: S0 SD0 Copy to clipboard ## Runtime simulator calls These simulator calls are made either before or after the configuration step. These are used for changing certain simulation options at runtime or to get information at runtime. These calls can be made multiple times. ### [EVB()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id5) Specifies the value of the event vector base register. By default, the EVB is set to zero or to the entry point of the loaded binary file. - **Prototype** - void EVB(HEX_PA_t EVBStartAddr); Copy to clipboard - **Parameters** - | in | *EVBStartAddr* | Starting address of the EVB. | | --- | --- | --- | - **Returns** - None. ### [CoreFrequency()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id5) Sets or gets the Hexagon frequency anytime during the simulation. Passing a value of zero leaves the current frequency unchanged and returns the current frequency. - **Prototype** - Copy to clipboard HEX\_8u\_t CoreFrequency(HEX\_8u\_t ClkHz); - **Parameters** - | in | *ClkHz* | Hexagon clock frequency in Hertz.


If 0, return the current clock frequency. | | --- | --- | --- | - **Returns** - Hexagon clock frequency in Hz. ### [VerboseMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id5) Set the level of verbosity. Verbose messages are sent to stdout in the simulator. - **Prototype** - void VerboseMode(HEXAPI_VerboseMode mode); Copy to clipboard - **Parameters** - | in | *mode* | Verbosity level.
| | --- | --- | --- | - **Returns** - None. ### [AddSymbolFile()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id5) Specifies the file from which symbol information is loaded. - **Prototype** - HEXAPI_Status AddSymbolFile(const char *pSymFile); Copy to clipboard - **Parameters** - | in | *pSymFile* | Pointer to the fully qualified name of the ELF file that
contains symbols. | | --- | --- | --- | - **Detailed description** - Multiple symbol files can be provided by calling this function multiple times. If this function is called during the configuration phase, the file handle is added to a list of symbol file handles and the symbols are loaded at the end of the configuration phase. Note pSymFile is opened using HEX\_MODE\_READBINARY mode. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_FILE\_ACCESS\_ERROR - Problem accessing the file. ## Simulator control These simulator calls can be made only after the configuration step. These are used for runtime control and access to Hexagon core memory and registers. These calls can be made multiple times. ### [LoadExecutableBinary()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Loads or reloads an executable for simulation. - **Prototype** - HEXAPI_Status LoadExecutableBinary (const char *pElfFile=NULL); Copy to clipboard - **Parameters** - | in | *pElfFile* | Pointer to the fully qualified name of the Hexagon ELF file
executable program to load into memory for simulation.


A NULL parameter causes the existing image to be reloaded. | | --- | --- | --- | - **Detailed description** - Calling this function without a parameter (or with a NULL parameter value) causes the binary specified with [ConfigureExecutableBinary()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureexecutablebinary) to be loaded or reloaded. This is typically done to restart simulating the current program. The file is opened using HEX\_MODE\_READBINARY mode. Reset might be required for this function to act properly. If no filename is provided by this function and ConfigureExecutableBinary() was not called, this function has no effect. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Configuration error or image is not loaded. - HEX\_STAT\_FILE\_ACCESS\_ERROR - Cannot load image, or image is invalid for this processor version. ### [Run()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Runs the Hexagon core until it finishes executing (all threads stop) due to an unrecoverable error (such as a double exception) or because a breakpoint was hit. - **Prototype** - HEXAPI_CoreState Run(HEX_4u_t *result); Copy to clipboard - **Parameters** - | out | *result* | Pointer to the return code from the simulated program’s
exit() call. | | --- | --- | --- | - **Detailed description** - The execution result is the exit code of the simulated program for normal termination (HEX\_CORE\_FINISHED), or undefined for the other return values. If a valid call to [ConfigureRemoteDebug()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureremotedebug) was made in the configuration phase, the simulator will wait for a connection from the debugger and control will be passed to the debugger. A Run() call returns HEX\_CORE\_FINISHED when the debugger exits. - **Returns** - - HEX\_CORE\_FINISHED - Program is finished. - HEX\_CORE\_BREAKPOINT - Breakpoint is hit. - HEX\_CORE\_RESET - Core is in Reset. - HEX\_CORE\_ASYNCHRONOUS\_BREAK - Asynchronous break. - HEX\_CORE\_ERROR - Configuration error. ### [Step()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Steps the Hexagon core for one or more cycles. - **Prototype** - HEXAPI_CoreState Step(HEX_4u_t cycles, HEX_4u_t *cyclesExecuted, HEX_4u_t *result); Copy to clipboard - **Parameters** - | in | *cycles* | Number of Hexagon processor cycles to execute. | | --- | --- | --- | | out | *cyclesExecuted* | Pointer to the actual number of cycles executed. | | out | *result* | Pointer to the return code from the simulated program’s
exit() call. | - **Detailed description** - The actual number of cycles stepped is returned in cyclesExecuted. The result is the exit code of the simulated program on normal termination (HEX\_CORE\_FINISHED) and undefined for other return codes. This function will not connect to a debugger, regardless of whether [ConfigureRemoteDebug()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureremotedebug) was successfully called. To connect to a debugger, call [Run()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#run) in conjunction with [AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addtimedcallback) to execute the program for a specific time period with the debugger connected. - **Returns** - - HEX\_CORE\_SUCCESS - HEX\_CORE\_FINISHED - Program is finished. - HEX\_CORE\_BREAKPOINT - Breakpoint is hit. - HEX\_CORE\_RESET - Core is in Reset. - HEX\_CORE\_ASYNCHRONOUS\_BREAK - Asynchronous break. - HEX\_CORE\_ERROR - Configuration error. ### [StepTime()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Steps the processor the number of cycles equivalent to the time input parameter. - **Prototype** - HEXAPI_CoreState StepTime(HEX_8u_t time, HEXAPI_Interval units, HEX_4u_t *cyclesExecuted, HEX_4u_t *result); Copy to clipboard - **Parameters** - | in | *time* | Number of time units to step. | | --- | --- | --- | | in | *units* | Units that represent the time parameter.
| | in | *cycles* | Number of Hexagon cycles to execute. | | out | *cyclesExecuted* | Pointer to the actual number of cycles executed. | | out | *result* | Pointer to the return code from the simulated program’s
exit() call. | - **Detailed description** - The actual number of cycles stepped is returned in cyclesExecuted. The result is the exit code of the simulated program on normal termination (HEX\_CORE\_FINISHED) and undefined for other return codes. This function will not connect to a debugger, regardless of whether [ConfigureRemoteDebug()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureremotedebug) was successfully called. To connect to a debugger, call [Run()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#run) in conjunction with [AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addtimedcallback) to execute the program for a specific time period with the debugger connected. - **Returns** - - HEX\_CORE\_SUCCESS - HEX\_CORE\_FINISHED - Program is finished. - HEX\_CORE\_BREAKPOINT - Breakpoint is hit. - HEX\_CORE\_RESET - Core is in Reset. - HEX\_CORE\_ASYNCHRONOUS\_BREAK - Asynchronous break. - HEX\_CORE\_ERROR - Configuration error. ### [SetInterrupt()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Asserts an interrupt to the Hexagon core. - **Prototype** - HEXAPI_Status SetInterrupt(HEX_4u_t interruptNum, HEXAPI_InterruptPinState state); Copy to clipboard - **Parameters** - | in | *interruptNum* | Interrupt number for the Hexagon core. Range: 0 to 31 | | --- | --- | --- | | in | *state* | | - **Detailed description** - The interrupt is asserted by setting the appropriate bit in the interrupt pending register of the core to the appropriate state. The wrapper ensures that the interrupt is asserted or deasserted regardless of whether the interrupt is positive level- or edge-triggered or negative level- or edge-triggered. If the core is to vector to the interrupt handler, interrupts must be enabled and the interrupt mask must be set correctly. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Incorrect interrupt number. ### [AssertNMI](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Asserts a non-maskable interrupt to the core. It remains asserted until it is deasserted. - **Prototype** - HEXAPI_Status AssertNMI(); Copy to clipboard - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - NMI is already asserted, or this function was called during the configuration phase. ### [DeassertNMI()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Deasserts the NMI signal to the core. If no NMI is asserted, this function has no effect. - **Prototype** - HEXAPI_Status DeassertNMI(); Copy to clipboard - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - NMI is already deasserted, or this function was called during the configuration phase. ### [ClearInterrupt](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Clears a specific interrupt in the interrupt pending register of the Hexagon core. - **Prototype** - HEXAPI_Status ClearInterrupt(HEX_4u_t interruptNum); Copy to clipboard - **Parameters** - | in | *interruptNum* | Interrupt number for the Hexagon core. Range: 0 to 31 | | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Incorrect interrupt number. ### [ClearAllInterrupts()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Clears all interrupts in the interrupt pending register of the Hexagon core. - **Prototype** - Copy to clipboard void ClearAllInterrupts(); - **Returns** - None. ### [SetBreakpoint](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Sets a breakpoint at a virtual address. - **Prototype** - HEXAPI_Status SetBreakpoint(HEX_VA_t vpc); Copy to clipboard - **Parameters** - | in | *vpc* | Virtual address where a breakpoint is to be set. | | --- | --- | --- | - **Detailed description** - The list of breakpoints is maintained as an unbounded list within the simulator. Multiple calls to set a breakpoint on a certain address results in only one breakpoint being set. The simulator returns from a Run or Step command at the point just before the instruction at the specified address commits. The address passed to this function must be the address of the first instruction of a packet for the breakpoint to be recognized. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Problem setting the breakpoint. ### [ClearBreakpoint()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Clears a breakpoint at the address specified by the provided virtual address. No action is taken if there is no breakpoint set at the given address. - **Prototype** - HEXAPI_Status ClearBreakpoint(HEX_VA_t vpc); Copy to clipboard - **Parameters** - | in | *vpc* | Virtual address for which breakpoint is to be cleared | | --- | --- | --- | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Problem clearing the breakpoint. ### [ClearAllBreakpoints()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Clears all breakpoints. - **Prototype** - HEXAPI_Status ClearAllBreakpoints(); Copy to clipboard - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Problem clearing the breakpoints. ### [AssertReset()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Puts the Hexagon core into Reset mode. - **Prototype** - HEXAPI_Status AssertReset(); Copy to clipboard - **Detailed description** - When in reset mode, the core cannot step or run. The registers are cleared and so are all statistics and profile data counters. PC is set to EVB value. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Core is already in reset, or this function was called during the configuration phase. ### [DeassertReset()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Takes the Hexagon core out of Reset mode. - **Prototype** - HEXAPI_Status DeassertReset(); Copy to clipboard - **Detailed description** - The simulator vectors to the reset vector PC value (described by the EVB register). The EVB must be set at least once before the core is taken out of reset. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Core is not in reset, or this function was called during the configuration phase. ### [BusTransactionFinished()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Used by an external bus cosim to indicate completion of a bus transaction. - **Prototype** - Copy to clipboard void BusTransactionFinished(HEX\_1u\_t \* data, HEX\_4u\_t size, HEX\_4u\_t requestID); - **Parameters** - | in | *data* | Pointer to the data returned by the external bus co- simulation. | | --- | --- | --- | | in | *size* | Size of data in bytes. | | in | *requestID* | ID of the bus transaction.


This ID must correspond to the ID provided by a previous
[BusTransactionRequestCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#bustransactionrequestcallback)
call. | - **Detailed description** - The requestID for this call corresponds to the ID passed to the bus transaction request callback function by the simulator. See [AddBusAccessCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addbusaccesscallback) and [BusTransactionRequestCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#bustransactionrequestcallback). - **Returns** - None. ### [WriteThreadRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Writes a 32-bit value to a Hexagon thread register. HEXAPI\_TH\_REG is a thread register enumeration that is provided with HexagonTypes.h. - **Prototype** - HEXAPI_Status WriteThreadRegister(HEX_4u_t threadNum, HEXAPI_TH_REG index, HEX_4u_t value); Copy to clipboard - **Parameters** - | in | *threadNum* | Selected hardware thread for the register to be set. | | --- | --- | --- | | in | *index* | Selected thread register for the hardware thread. | | in | *value* | Value to be written. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid register number. ### [ReadThreadRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads a 32-bit value from a Hexagon thread register. HEXAPI\_TH\_REG is a thread register enumeration that is provided with HexagonTypes.h. - **Prototype** - HEXAPI_Status ReadThreadRegister(HEX_4u_t threadNum, HEXAPI_TH_REG index, HEX_4u_t *value); Copy to clipboard - **Parameters** - | in | *threadNum* | Selected hardware thread for the register to be read. | | --- | --- | --- | | in | *index* | Selected thread register for the hardware thread. | | out | *value* | Pointer to the value read from the register. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid register number. ### [WriteVectorRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Writes an unsigned 32-bit value to an HVX vector register. Note It returns HEX\_STAT\_ERROR if it is called with any other version. - **Prototype** - HEXAPI_Status WriteVectorRegister(char *regtype, HEX_4u_t tnum, int extno, HEX_4u_t reg_id, HEX_4u_t word_id, HEX_4u_t value); Copy to clipboard - **Parameters** - | in | *regtype* | Pointer to the register type.
| | --- | --- | --- | | in | *tnum* | Hardware thread ID. | | in | *extno* | Register context.
| | in | *reg\_id* | | | in | *word\_id* | | | in | *value* | Value written to the register. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid register number. - HEX\_STAT\_ERROR - Invalid processor architecture. ### [ReadVectorRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads an unsigned 32-bit value from an HVX vector register. Note It returns HEX\_STAT\_ERROR if it is called with any other version. - **Prototype** - HEXAPI_Status ReadVectorRegister(char *regtype, HEX_4u_t tnum, int extno, HEX_4u_t reg_id, HEX_4u_t word_id, HEX_4u_t *value_addr); Copy to clipboard - **Parameters** - | in | *regtype* | Pointer to the register type.
| | --- | --- | --- | | in | *tnum* | Hardware thread ID. | | in | *extno* | Register context.
| | in | *reg\_id* | | | in | *word\_id* | | | out | *value\_addr* | Pointer to the value read from the register. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid register number. - HEX\_STAT\_ERROR - Invalid processor architecture. ### [WriteGlobalRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Writes a 32-bit value to a Hexagon global register. HEXAPI\_G\_REG is a global register enumeration that is provided with HexagonTypes.h. - **Prototype** - HEXAPI_Status WriteGlobalRegister(HEXAPI_G_REG index, HEX_4u_t value); Copy to clipboard - **Parameters** - | in | *index* | Selected global register. | | --- | --- | --- | | in | *value* | Value to be written. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid register number. ### [ReadGlobalRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads a 32-bit value from a Hexagon global register. HEXAPI\_G\_REG is a global register enumeration that is provided with HexagonTypes.h. - **Prototype** - HEXAPI_Status ReadGlobalRegister(int index, HEX_8u_t *value); Copy to clipboard - **Parameters** - | in | *index* | Selected global register. | | --- | --- | --- | | out | *value* | Pointer to the value read from the register. | - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid register number. ### [WriteTLBRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Writes a 64-bit value to a Hexagon TLB register. - **Prototype** - HEXAPI_Status WriteTLBRegister(int index, HEX_8u_t value); Copy to clipboard - **Parameters** - | in | *index* | Selected TLB register. | | --- | --- | --- | | in | *value* | Value to be written. | - **Detailed description** - TLB register values are written to the low-level architecture library, which does not return any result status information. Thus this function returns only HEX\_STAT\_SUCCESS as a result value. - **Returns** - HEX\_STAT\_SUCCESS ### [ReadTLBRegister()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads a 64-bit value from a Hexagon TLB register. - **Prototype** - HEXAPI_Status ReadTLBRegister(int index, HEX_8u_t *value); Copy to clipboard - **Parameters** - | in | *index* | Selected TLB register. | | --- | --- | --- | | out | *value* | Pointer to the value read from the register. | - **Detailed description** - TLB register values are read from the low-level architecture library, which does not return any result status information. Thus, this function returns only HEX\_STAT\_SUCCESS as a result value. - **Returns** - HEX\_STAT\_SUCCESS ### [WriteMemory()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Writes value to Hexagon memory. - **Prototype** - HEXAPI_Status WriteMemory (HEX_PA_t paddr, HEX_4u_t size, HEX_8u_t value); Copy to clipboard - **Parameters** - | in | *paddr* | Physical address where data is to be written. | | --- | --- | --- | | in | *size* | Data size in bytes (1, 2, 4, or 8 bytes). | | in | *value* | Value to be written to Hexagon memory. | - **Detailed description** - This function is an incoherent write function in that the cache is not updated. The data value is written to the memory by potentially initiating a debug bus transaction. If the bus transaction fails, this function returns HEX\_STAT\_MEM\_ACCESS\_ERROR and no action is taken. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid size. - HEX\_STAT\_MEM\_ACCESS\_ERROR - Cannot access memory. ### [ReadMemory()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads up to a 64-bit value from Hexagon memory. - **Prototype** - HEXAPI_Status ReadMemory(HEX_PA_t paddr, HEX_4u_t size, void *value); Copy to clipboard - **Parameters** - | in | *paddr* | Physical address where data is read. | | --- | --- | --- | | in | *size* | Data size in bytes (1, 2, 4, or 8 bytes). | | out | *value* | Pointer to the value read from Hexagon memory. | - **Detailed description** - This function bypasses the cache and reads directly from memory, which could result in a debug bus transaction. If the bus transaction fails, this function returns HEX\_STAT\_MEM\_ACCESS\_ERROR and no action is taken. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid size. - HEX\_STAT\_MEM\_ACCESS\_ERROR - Cannot access memory. ### [ProbeCache()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reports whether a range of physical memory is present in the cache, and whether any of it is dirty. - **Prototype** - HEXAPI_Status ProbeCache(HEX_4u_t tnum, HEX_PA_t paddr, HEX_4u_t size, void *value); Copy to clipboard - **Parameters** - | in | *tnum* | Hardware thread number. Selects the cache that is probed. | | --- | --- | --- | | in | *paddr* | Physical address of the first byte in the probed range. | | in | *size* | Size of the probed range in bytes. | | out | *value* | Pointer to an int that receives the probe result as a bit mask:


A result of 0 indicates that no part of the range is held in
the cache. | - **Detailed description** - This function probes the L2 cache that serves the specified hardware thread. Every cache line that overlaps the range *paddr* through *paddr* + *size* - 1 is examined, and the result reports whether *any* of those lines is valid (bit 0) or modified (bit 1). The two bits are independent: a range can be reported as present without being dirty. The probe inspects the cache without modifying it. No line is allocated, evicted, or invalidated, and no bus transaction is generated. This function is supported for Hexagon V83 and later processor versions. It requires timing mode to be enabled (see [ConfigureTimingMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configuretimingmode)) and the L2 cache to be enabled, because the cache state that it reports is modeled only under those conditions. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - *value* is NULL, or the processor version does not support cache probing. ### [WriteVirtual()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Writes up to a 64-bit value at the virtual address specified by vaddr. - **Prototype** - HEXAPI_Status WriteVirtual(HEX_VA_t vaddr, HEX_4u_t ASID, HEX_4u_t size, HEX_8u_t value); Copy to clipboard - **Parameters** - | in | *vaddr* | Virtual address where data is to be written. | | --- | --- | --- | | in | *ASID* | ASID to match when doing virtual-to-physical address
translation.


An ASID value of 0xFFFFFFFF will match any ASID with a
translation for the vaddr | | in | *size* | Data size in bytes (1, 2, 4, or 8 bytes). | | in | *value* | Value to be written. | - **Detailed description** - This is a convenience function that performs virtual to physical address translation, writes the data into the cache (if present) and writes to memory if the data is not in cache. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid size. - HEX\_STAT\_CANNOT\_TRANSLATE - Cannot translate vaddr. ### [ReadVirtual()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads up to a 64-bit value at the virtual address specified by vaddr. - **Prototype** - HEXAPI_Status ReadVirtual(HEX_VA_t vaddr, HEX_4u_t ASID, HEX_4u_t size, void *value); Copy to clipboard - **Parameters** - | in | *vaddr* | Virtual address from where data is to be read. | | --- | --- | --- | | in | *ASID* | ASID to match when doing virtual-to-physical address
translation.


An ASID value of 0xFFFFFFFF will match any ASID with a
translation for the vaddr. | | in | *size* | Data size in bytes (1, 2, 4, or 8 bytes). | | out | *value* | Pointer to the value that was read. | - **Detailed description** - This is a convenience function that performs virtual to physical address translation, probes the cache for the data and reads from memory if the data is not in cache. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_INVALID\_ARGS - Invalid size. - HEX\_STAT\_CANNOT\_TRANSLATE - Cannot translate vaddr. ### [ReadSymbolValue()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads the address or value that corresponds to a symbol. - **Prototype** - HEXAPI_Status ReadSymbolValue(const char *Symbol, HEX_4u_t *value); Copy to clipboard - **Parameters** - | in | *Symbol* | Pointer to the symbol to be read from the simulator. | | --- | --- | --- | | out | *value* | Pointer to the value that corresponds to the symbol read from
the symbol files or executable loaded in the simulator. | - **Detailed description** - The simulator can provide this information if it can read symbol information from the binary or the symbol files. Note The string passed to this function is the mangled symbol name. The simulator does not perform any transformation on the symbol name passed in. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Function was called during the configuration phase. - HEX\_STAT\_CANNOT\_TRANSLATE - Symbol was not found. ### [TranslateVirtualToPhysical()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Translates a given virtual address (with ASID) into a physical address. - **Prototype** - HEXAPI_Status TranslateVirtualToPhysical(HEX_VA_t vaddr, HEX_4u_t ASID, HEX_PA_t *paddr); Copy to clipboard - **Parameters** - | in | *vaddr* | Virtual address that requires translation. | | --- | --- | --- | | in | *ASID* | ASID for which the vaddr is valid.


Specifying 0xFFFFFFFF for the ASID will match any ASID with a
translation for the vaddr. | | out | *paddr* | Pointer to the physical address that corresponds to the
specified virtual address. | - **Detailed description** - The translation algorithm looks in the RTOS structures for a valid translation. In the case of a standalone program (that is, no RTOS module is loaded), the TLB entries are searched for the translation. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_TRANSLATE - No translation for the specified vaddr exists. ### [CycleToTime()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Translates a given cycle count into units of time, taking into account the current core frequency. - **Prototype** - void CycleToTime(HEX_8u_t cycleCount, HEX_8u_t *time, HEXAPI_Interval *units); Copy to clipboard - **Parameters** - | in | *cycleCount* | Number of cycles. | | --- | --- | --- | | out | *time* | Pointer to the estimated amount of time in units returned that
it would take the simulator to execute the number of cycles
given. | | out | *units* | Units that represent the time parameter.
| - **Returns** - None. ### [TimeToCycles()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Translates a time value to a specified number of processor cycles. - **Prototype** - void TimeToCycles(HEX_8u_t time, HEX_8u_t *cycleCount, HEXAPI_Interval units); Copy to clipboard - **Parameters** - | in | *time* | Amount of time in units as specified by the units
parameter. | | --- | --- | --- | | out | *cycleCount* | Pointer to the estimated number of cycles that match the
time parameter.


Note


Due to rounding effects, the number can be off by ±1 cycle. | | in | *units* | Units that represent the time parameter.
| - **Returns** - None. ### [GetElapsedSimulationTime()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Returns the elapsed time in the specified units since the start of simulation. - **Prototype** - HEXAPI_Status GetElapsedSimulationTime(HEX_8u_t *time, HEXAPI_Interval units); Copy to clipboard - **Parameters** - | out | *time* | Pointer to the number of units that have elapsed since the start
of the simulation. | | --- | --- | --- | | in | *units* | Units that represent the time parameter.
| - **Detailed description** - The actual elapsed time is converted to the specified units, provided no underflow occurs. Note The time returned reflects all frequency change requests made by [CoreFrequency()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#corefrequency). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Time cannot be converted to the specified unit. This occurs if the actual elapsed time converted to the requested unit results in an elapsed time of zero. ### [GetSimulatedCycleCount()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Returns the number of simulated cycles since the start of simulation. - **Prototype** - HEXAPI_Status GetSimulatedCycleCount(HEX_8u_t *cycles); Copy to clipboard - **Parameters** - | out | *cycles* | Pointer to the number of simulated cycles since the start of the
simulation. | | --- | --- | --- | - **Detailed description** - The cycles returned are the actual number of cycles simulated by the simulator and may or may not match the contents of the PCYCLE register. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Function was called before [EndOfConfiguration()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#endofconfiguration). ### [EmitPerfStatistics()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Prints the performance statistics into buffer. - **Prototype** - HEXAPI_Status EmitPerfStatistics(HEX_8u_t startTimeSec, HEX_8u_t startTimeUsec, HEX_8u_t endTimeSec, HEX_8u_t endTimeUsec, char *buffer, HEX_4u_t bufferSize); Copy to clipboard - **Parameters** - | in | *startTimeSec* | Start time of the simulation run (in seconds). | | --- | --- | --- | | in | *startTimeUsec* | Start time of the simulation run (in microseconds). | | in | *endTimeSec* | End time of the simulation run (in seconds). | | in | *endTimeUsec* | End time of the simulation run (in microseconds). | | out | *buffer* | Pointer to the buffer from which the run statistics for
performance will be printed. | | in | *bufferSize* | Maximum size of the data to be copied into buffer (in bytes). | - **Detailed description** - This routine puts a maximum of bufferSize bytes into the buffer. The input parameters are starting and ending time (real time) used to calculate the ratio to real time and simulator speed. The parameters are paired so that 1.1 seconds of real time is expressed as 1 second and 100000 microseconds. The output printed to the buffer is of the following form: Done! T0: Insns=6761 Tcycles=3530 T1: Insns=0 Tcycles=0 T2: Insns=0 Tcycles=0 T3: Insns=0 Tcycles=0 T4: Insns=0 Tcycles=0 T5: Insns=0 Tcycles=0 Total: Insns=6761 Pcycles=21192 Simulator speed=0.419547 Mips Ratio to Real Time (600 MHz) = ~1/456 (elapsed time = 0.016115s) Copy to clipboard - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Buffer pointer is NULL. - HEX\_STAT\_ERROR - Function was called before [EndOfConfiguration()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#endofconfiguration). ### [EnablePacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Enables or disables the generation of instruction packet execution statistics in the file specified in [ConfigurePacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurepacketanalysis). Note It returns HEX\_STAT\_ERROR if it is called with any other version. - **Prototype** - HEXAPI_Status EnablePacketAnalysis(bool enable_disable); Copy to clipboard - **Parameters** - | in | *enable\_disable* | Analysis mode.
| | --- | --- | --- | - **Detailed description** - [ConfigurePacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurepacketanalysis) implicitly enables this function. This operation is performed on the Hexagon processor and coprocessor concurrently. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Incorrect parameter. - HEX\_STAT\_ERROR - Invalid processor version. ### [ResetPacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Resets internal data records used for packet analysis. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other processor version. - **Prototype** - HEXAPI_Status ResetPacketAnalysis(void) Copy to clipboard - **Detailed description** - This function is not required during initialization. [ConfigurePacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configurepacketanalysis)will generate the initial reset-to-zero. This function can be called when the collected data is to be reset to zero. To clear the internal data records for the next analysis, this function can be called immediately after calling [DumpPacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#dumppacketanalysis). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Invalid processor version. ### [DumpPacketAnalysis()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Dumps available internal data records that were collected for packet analysis Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other processor version. - **Prototype** - HEXAPI_Status DumpPacketAnalysis(FILE *file) Copy to clipboard - **Parameters** - | in | *file* | Pointer to the file descriptor of an open stream to which
Hexagon packet statistics are to be written. | | --- | --- | --- | - **Detailed description** - You must provide a valid FILE pointer and properly open and close the pointer. The FILE pointer can be any valid filename. This function is not required to dump the collected packet analysis data at the end of a simulation. Properly deleting the HexagonWrapper object will generate the final dump. This function can be called when the data is to be dumped before the simulator exits. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ FILE\_ACCESS\_ERROR - Bad file pointer. - HEX\_STAT\_ CANNOT\_CONFIG - Invalid processor version. ### [EnableInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Enables or disables the generation of instruction histogram data in a file specified in [ConfigureInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureinsthistogram). Note It returns HEX\_STAT\_ERROR if it is called with any other version. - **Prototype** - HEXAPI_Status EnableInstHistogram(bool enable_disable); Copy to clipboard - **Parameters** - | in | *enable\_disable* | Instruction histogram mode.
| | --- | --- | --- | - **Detailed description** - [ConfigureInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureinsthistogram) implicitly enables this function. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_INVALID\_ARGS - Incorrect parameter. - HEX\_STAT\_ERROR - Invalid processor version. ### [ResetInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Resets internal data records used for an instruction histogram. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status ResetInstHistogram (void) Copy to clipboard - **Detailed description** - This function is not required during initialization. [ConfigureInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureinsthistogram) will generate the initial reset-to-zero. This function can be called when the collected data is to be reset to zero. To reset internal data records for the next analysis, this function can be called immediately after calling [DumpInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#dumpinsthistogram). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ CANNOT\_CONFIG - Invalid processor version. ### [DumpInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Dumps internal data records collected for an instruction histogram. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status DumpInstHistogram (const char *msg) Copy to clipboard - **Parameters** - | in | *msg* | Pointer to the message string (not to a filename). | | --- | --- | --- | - **Detailed description** - You must provide a valid string as a message. The message string appears in the dump file followed by the dump contents. The msg parameter can be NULL. You are responsible for dealing with this extra message line if msg is not NULL. The Hexagon Profiler cannot handle unexpected strings mixed into the data file. The msg parameter is not a filename. There is no control over the filename used for an instruction histogram besides the original [ConfigureInstHistogram()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#configureinsthistogram)call. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ FILE\_ACCESS\_ERROR - Bad file pointer. - HEX\_STAT\_ CANNOT\_CONFIG - Invalid processor version. ### [GetPowerStatistics()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Returns a set of three performance measurement values that can be plugged into an equation that models the linear dynamic power for Hexagon processor cores. - **Prototype** - HEXAPI_Status GetPowerStatistics(bool reset, float *all_wait, float *avg_active, float *avg_pkt); Copy to clipboard - **Parameters** - | in | *reset* | Performance measurement values.
| | --- | --- | --- | | out | *all\_wait* | Pointer to the percentage of time spent in All-Wait mode. Range:
0.0 to 1.0 | | out | *avg\_active* | Pointer to the effective number of threads running (that is, the
number of threads running and not stalled, averaged over time). | | out | *avg\_pkt* | Pointer to the average number of instructions per packet. | - **Detailed description** - By default these measurement values reflect the performance of the simulation since it first began running. However, you can also reset the measurement values in order to limit the collection of performance data to specific parts of a simulation. The reset parameter controls whether the function resets the measurement values (TRUE), or whether it returns their current values (FALSE). Note When reset is TRUE, the returned measurement values are invalid. - **Returns** - - HEX\_STAT\_SUCCESS - - HEX\_STAT\_INVALID\_ARGS - One or more NULL input pointers; attempted to - use with an invalid processor version. - **Power calculation equation** - Rather than provide a function that computes the power equation, the simulator system API provides only the function GetPowerStatistics to return certain parameters used in the power equation. This is done for two reasons: - Some of the equation parameters are user-supplied. - It enables users to modify the equation if necessary. - **Equation parameters** - The power equation includes three types of parameters: - Parameters returned by GetPowerStatistics - Parameters supplied by the user - Parameters obtained from silicon measurements (or from pre-silicon estimates) The user-supplied and silicon measurement parameters are statically defined for a given processor core, while the parameters returned by GetPowerStatistics are dynamic and generated during a simulation. > > > | **Type** | **Name** | **Detailed description** | > | --- | --- | --- | > | GetPowerStatistics | allwaitFraction | Percentage of time spent in All-Wait mode (all\_wait in
GetPowerStatistics) | > | GetPowerStatistics | N | Effective number of threads running (that is, the number of
threads running and not stalled, averaged over time (avg\_active in GetPowerStatistics) | > | GetPowerStatistics | IPP | Average number of instructions per packet (avg\_pkt in GetPowerStatistics) | > | User-supplied | frequencyHEXAGON | Hexagon processor clock frequency normalized to 600 MHz | > | User-supplied | frequencyAXI | AXI clock frequency, normalized to 133 MHz | > | User-supplied | v | Core voltage normalized to the nominal voltage for the
technology | > | User-supplied | nMax | Maximum number of hardware threads | > | Silicon measurements (or pre-silicon estimates) | Pallwait | All-wait dynamic power for AXI slave logic at 133 MHz | > | Silicon measurements (or pre-silicon estimates) | P1 | Dhrystone power at maximum core frequency when a single thread
is running | > | Silicon measurements (or pre-silicon estimates) | Pall | Dhrystone power at maximum core frequency when all threads are running | > | | | | > | | | | > | | | | - **Linear power model equation** - The equation variables m, b, and P are defined in terms of the equation parameters listed in [power equation parameters](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#tbl-power-equation-parameters): \[m = (Pall - P1) / (Nmax - 1) b = P1 - m P = m \* N + b\] The (V3) empirical dynamic power scaling factor IPPadjustment is based on the average number of instructions per packet: \[IPPadjustment = 0.14 \* (IPP - 2.2) + 1\] The dynamic power (represented by dynamicPower in the following example) is based on the amount of time spent both running and in All-Wait mode: \[runtimePower = (1 - allwaitFraction) \* frequencyHEXAGON \* IPPadjustment \* P allwaitPower = allwaitFraction \* frequencyAXI \* Pallwait dynamicPower = (runtimePower + allwaitPower) \* v2\] ### [EnablePmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Enables Hexagon PMU operation. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status EnablePmu(HEX_4u_t tnum=0xffffffff); Copy to clipboard - **Parameters** - | in | *tnum* | Reserved for future use. | | --- | --- | --- | - **Detailed description** - The tnum parameter is reserved for future use and is not required in the function call: EnablePmu(); // param not required - assigned default value Copy to clipboard The PMU is automatically enabled before the simulation starts. When the PMU is enabled, the simulator will collect PMU statistics. To begin collecting PMU statistics in the middle of a program, you can: - Call [DisablePmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#disablepmu) at the beginning of the simulation, and then call EnablePmu() after hitting a breakpoint - Call [ResetPmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#resetpmu) after hitting a breakpoint (preferred method) - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support PMU. ### [DisablePmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Disables Hexagon PMU operation. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status DisablePmu(HEX_4u_t tnum=0xffffffff); Copy to clipboard - **Parameters** - | in | *tnum* | Reserved for future use. | | --- | --- | --- | - **Detailed description** - The tnum parameter is reserved for future use and is not required in the function call: DisablePmu(); // param not required - assigned default value Copy to clipboard The PMU is automatically enabled before the simulation starts. When the PMU is enabled, the simulator will collect PMU statistics. To begin collecting PMU statistics in the middle of a program, you can: - Call DisablePmu() at the beginning of the simulation, and then call [EnablePmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#enablepmu) after hitting a breakpoint - Call [ResetPmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#resetpmu) after hitting a breakpoint (preferred method) - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support PMU. ### [ResetPmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Resets Hexagon PMU counts to zero. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status ResetPmu(HEX_4u_t tnum=0xffffffff); Copy to clipboard - **Parameters** - | in | *tnum* | Reserved for future use. | | --- | --- | --- | - **Detailed description** - The tnum parameter is reserved for future use and is not required in the function call: ResetPmu(); // param not required - assigned default value Copy to clipboard The PMU is automatically enabled before the simulation starts. When the PMU is enabled, the simulator will collect PMU statistics. To begin collecting PMU statistics in the middle of a program, you can: - Call [DisablePmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#disablepmu) at the beginning of the simulation, and then call [EnablePmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#enablepmu) after hitting a breakpoint - Call ResetPmu() after hitting a breakpoint (preferred method) - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support PMU. ### [DumpPmu()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Prints PMU statistics to a specified file. Note It returns HEX\_STAT\_CANNOT\_CONFIG if it is called with any other version. - **Prototype** - HEXAPI_Status DumpPmu(FILE *fp, int including_iss_only_stats, HEX_4u_t tnum=0xffffffff); Copy to clipboard - **Parameters** - | in | *fp* | File to print PMU statistics to. | | --- | --- | --- | | in | *including\_iss\_only\_stats* | Statistics to print.
| | in | *tnum* | Reserved for future use. | - **Detailed description** - The tnum parameter is reserved and is not required in the function call: DumpPmu(f,1); // tnum not required - assigned default value Copy to clipboard This function does not print certain information that is included in the PMU statistics file generated by the standalone simulator (revision ID, cache size, full command line used to launch the simulator). - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support the specified PMU register. ### [GetPmuIndexedStats()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads a 64-bit value from the Hexagon PMU statistics register specified by the indicated hardware thread and PMU register index. - **Prototype** - HEXAPI_Status GetPmuIndexedStats(HEX_4u_t tnum, HEX_4u_t pe_num, HEX_8u_t *value); Copy to clipboard - **Parameters** - | in | *tnum* | Hardware thread of the target PMU register. | | --- | --- | --- | | in | *pe\_num* | Index value of the target PMU register. Range: 0 to 255 | | out | *value* | Pointer to the value read from the PMU register. | - **Detailed description** - Before calling GetPmuIndexedStats() to access a PMU register, you must first call [PmuIsStatModeled()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#pmuisstatmodeled) to verify that the register is modeled for the current processor version. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support the specified PMU register. ### [PmuIsStatModeled()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Reads a 32-bit value that indicates the model status of the Hexagon PMU statistics register specified by the indicated hardware thread and PMU register index. - **Prototype** - HEXAPI_Status PmuIsStatModeled(HEX_4u_t tnum, HEX_4u_t pe_num, HEX_4u_t *value); Copy to clipboard - **Parameters** - | in | *tnum* | Hardware thread of the target PMU register. | | --- | --- | --- | | in | *pe\_num* | Index value of the target PMU register. Range: 0 to 255 | | out | *value* | Pointer to the model status.
| - **Detailed description** - The model status value indicates whether the PMU register is modeled on the current processor version. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support the specified PMU register. ### [PmuGetName()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Returns a pointer to a character string containing the symbolic name of the Hexagon PMU statistics register specified by the indicated hardware thread and PMU register index. - **Prototype** - HEXAPI_Status PmuGetName(HEX_4u_t tnum, HEX_4u_t pe_num, const char **name); Copy to clipboard - **Parameters** - | in | *tnum* | Hardware thread of the target PMU register. | | --- | --- | --- | | in | *pe\_num* | Index value of the target PMU register. Range: 0 to 255 | | out | *name* | Pointer to the character string containing the symbolic name of
the specified PMU register. | - **Detailed description** - Before calling PmuGetName() to access a PMU register, you must first call [PmuIsStatModeled()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#pmuisstatmodeled) to verify that the register is modeled for the current processor version. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support the specified PMU register. ### [PmuIsMaskable()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Returns an integer value that indicates whether the specified PMU event is local (per thread) or global (across all threads). - **Prototype** - HEXAPI_Status PmuIsMaskable(HEX_4u_t tnum, HEX_4u_t pe_num, HEX_4u_t *value); Copy to clipboard - **Parameters** - | in | *tnum* | Hardware thread of the target PMU register. | | --- | --- | --- | | in | *pe\_num* | Index value of the target PMU register. Range: 0 to 255 | | out | *value* | Pointer to the value.
| - **Detailed description** - Before calling PmuIsMaskable() to determine the status of a PMU event, you must first call [PmuIsStatModeled()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#pmuisstatmodeled) to verify that the corresponding register is modeled for the current processor version. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_CANNOT\_CONFIG - Processor version does not support the specified PMU register. ### [AxiSlaveAccess()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Performs a read or write operation on the AXI slave port. - **Prototype** - typedef void (*axi_bus_finished_callback) ( void *, /* actually "system_t *" */ int threadno, /* thread number */ HEX_PA_t paddr, /* physical addr */ HEX_4u_t width, /* size of access */ int type, /* type of access */ int id, /* identifier for access */ unsigned char *dataptr); HEXAPI_Status AxiSlaveAccess(HEX_4u_t tnum, HEX_PA_t pAddr, HEX_4u_t width, HEX_4u_t type, axi_bus_finished_callback cb, HEX_4u_t id, unsigned char *dataptr, HEX_4u_t *rval); Copy to clipboard - **Parameters** - | in | *tnum* | Hardware thread. | | --- | --- | --- | | in | *pAddr* | Address to access. | | in | *width* | Size of access (in bytes). | | in | *type* | Type of access (read or write). | | in | *cb* | Callback function (called when transaction complete). | | in | *id* | AXI transaction identifier. | | in | *dataptr* | Pointer to the data pointer (source for write). | | out | *rval* | Pointer to the value.
| - **Detailed description** - If the cb parameter is specified as NULL, the operation is performed using a non-blocking call, and the data is transferred immediately. If cb is non-NULL, the operation is performed using a blocking call. In this case *no* data is transferred during the call. Instead, the callback function referenced by cb is responsible for calling [WriteMemory()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#writememory) or [ReadMemory()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#readmemory) to initiate the actual data transfer. For the transaction to complete, the return value must be HEX\_STAT\_SUCCESS and *rval* must be equal to 1. The dataptr parameter is used only for write operations. For reads, [ReadMemory()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#readmemory) must be called when cb is called. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Invalid processor version. ### [ReconnectMode()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Specifies the behavior of the simulator when the associated debugger front-end exits. - **Prototype** - Copy to clipboard void ReconnectMode(int mode); - **Parameters** - | in | *mode* | Reconnect mode.


Default: 0 | | --- | --- | --- | - **Detailed description** - If the simulator is configured to continue when the 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 reconnects if another debugger front end attempts to connect to it. - **Returns** - None. ### [PostMessageToSimulator()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#id6) Posts a message to the simulator. - **Prototype** - HEXAPI_Status PostMessageToSimulator(HEXAPI_RxMsgType msg, void *param_addr); Copy to clipboard - **Parameters** - | in | *msg* | Message type.
HEX\_RXMSG\_EXIT\_EARLY - Stop the Hexagon core by triggering an
asynchronous break ([Run()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#run)). No parameter is defined
for this message.


Note


No other message types are currently defined. | | --- | --- | --- | | in | *param\_addr* | Pointer to the message parameter.


Note


If the specified message type does not define a
message parameter, this argument is ignored. | - **Detailed description** - Depending on the message type, an optional data parameter can be specified as part of the message. The HEX\_RXMSG\_EXIT\_EARLY message type can be used with callbacks such as [AddTimedCallback()](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html#addtimedcallback) to assert control over the simulator while it is running. Note The post operation is performed using a blocking call—it will not return until the message is posted to the simulator. However, the simulator might not immediately act on the message itself. - **Returns** - - HEX\_STAT\_SUCCESS - HEX\_STAT\_ERROR - Message type is not recognized, or the message parameter cannot be decoded. Last Published: Oct 06, 2026 [Previous Topic hexagon\_buffer\_inv()](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/cache-interface.md) [Next Topic Callbacks](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/callbacks.md) Source: [https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html](https://docs.qualcomm.com/doc/80-N3040-23/topic/system-interface.html)