# Timer interface

The simulator supports a built-in timer to enable users to collect
execution statistics on specific parts of the target application
being simulated. The information is collected by inserting timer
function calls directly into the application source code.

The timer interface provides the following information:

- Number of times the specified section of code was executed
- Total number of cycles executed in the code section
- Minimum, maximum, and average number of cycles executed during each
pass through the code section
- Processor cycle count
- Hardware thread processor cycle counts

The timer interface functions are accessed by including the library
header file, *hexagon\_sim\_timer.h*.

Note

To use the timer interface, an application must be linked
with the library file, libhexagon.a. For more information,
see the appropriate application build document.

## Timer functions

The timer interface’s timer functions are used to get the number of
cycles simulated while executing specific sections of code in the
target application. The following example shows how the timer
functions are used:

#include "hexagon_sim_timer.h"
    ...
    main()
    {
       hexagon_sim_init_timer();
       ...
       hexagon_sim_start_timer();
       <*timed user code*>;
       hexagon_sim_end_timer();
       ...
       hexagon_sim_show_timer(stdout);
    }
    Copy to clipboard

The timer has the following properties:

- Only one timer instance is supported for each application.
- Timing information is collected cumulatively across multiple calls to
[hexagon_sim_start_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_start_timer) and
[hexagon_sim_end_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_end_timer). This enables
the timer functions to appear in loop code and still collect useful
timing information.

The timer can be used to collect execution statistics on multiple
parts of an application (each delimited by hexagon\_sim\_start\_timer()
and hexagon\_sim\_end\_timer()). However, because only a single timer
instance is supported for each application, the following
restrictions apply:

- The timed parts of the application must be non-overlapping (and thus
non-nested).
- Each time the application transitions between the timed parts,
[hexagon_sim_show_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_show_timer) and
[hexagon_sim_init_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_init_timer) must be called
to respectively capture the execution statistics from the previous
part and reset the timer for the next part.

### [hexagon_sim_end_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#contents)

Stops the operation of the simulation timer.

**Prototype**

> 
> 
> void hexagon_sim_end_timer();
>     Copy to clipboard

- **Detailed description**
    - The timer is assumed to have been previously started with
[hexagon_sim_start_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_start_timer). If
hexagon\_sim\_end\_timer() is called without a matching call to
hexagon\_sim\_start\_timer(), the validity of the resulting timing
information) is undefined.

Timing information is collected cumulatively across multiple calls to
hexagon\_sim\_start\_timer() and hexagon\_sim\_end\_timer().
[hexagon_sim_show_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_show_timer) is called to
summarize and write the collected timing information.

For a programming example, see [timer functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#simulation-timer-functions).

Note

hexagon\_sim\_end\_timer() is independent of the simulation
timer, and it can be called independently of the timer-related
functions.

- **Returns**
    - None.

### [hexagon_sim_init_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#contents)

Before calling the other timer functions, initializes (or resets) the
simulation timer for subsequent timer operations.

- **Prototype**
    - void hexagon_sim_init_timer();
    Copy to clipboard

- **Detailed description**
    - The sample count and all cycle counts are set to zero. For a
programming example, see [timer functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#simulation-timer-functions).

- **Returns**
    - None.

### [hexagon_sim_prof_off()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#contents)

Disables timer data collection even if the timer is started
([hexagon_sim_show_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_show_timer)).

- **Prototype**
    - void hexagon_sim_prof_off();
    Copy to clipboard

- **Detailed description**
    - To re-enable timer data collection, call [hexagon_sim_prof_on()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_prof_on).

- **Returns**
    - None.

### [hexagon_sim_prof_on()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#contents)

Re-enables timer data collection after it was disabled using
[hexagon_sim_prof_off()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_prof_off).

- **Prototype**
    - void hexagon_sim_prof_on();
    Copy to clipboard

- **Returns**
    - None.

### [hexagon_sim_show_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#contents)

Summarizes the collected timer information and write it to the
specified stream.

- **Prototype**
    - void hexagon_sim_show_timer(FILE *file);
    Copy to clipboard

**Parameters**

> 
> 
> | in | file | Pointer to the file descriptor of an open stream to which timer<br>information is written. |
> | --- | --- | --- |

- **Detailed description**
    - This function summarize information collected so far by the timer,
and then it writes the corresponding execution statistics to the
specified stream.

The summary includes the following information:

- Number of times the section of code was executed (samples)
- Total number of cycles executed in the code section
- Minimum, maximum, and average number of cycles executed during each
pass through the code section

For example:

Samples=25
    Total cycles=5691225
    Max cycles=234223
    Min cycles=211092
    Avg cycles=227649
    Copy to clipboard

The code section is specified by calls to [hexagon_sim_start_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_start_timer) and
[hexagon_sim_end_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_end_timer).

For a programming example, see [timer functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#simulation-timer-functions).

- **Returns**
    - None.

### [hexagon_sim_start_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#contents)

Starts the operation of the simulation timer.

- **Prototype**
    - void hexagon_sim_start_timer();
    Copy to clipboard

- **Detailed description**
    - The timer is assumed to have been previously initialized with
[hexagon_sim_init_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_init_timer).

Timing information is collected cumulatively across multiple calls to
hexagon\_sim\_start\_timer() and [hexagon_sim_end_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_end_timer).
[hexagon_sim_show_timer()](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#hexagon_sim_show_timer)is called to
summarize and write the collected timing information.

For a programming example, see [timer functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/timer-interface.html#simulation-timer-functions).

- **Returns**
    - None.

## Cycle count function

Cycle counts are defined as the number of cycles executed by the
target application since it first began executing.

The Hexagon processor has multiple hardware threads, each with a
dedicated cycle count. The cycle counts are not synchronized: when
the processor cycle count increments, each of the cycle counts may or
may not increment, depending on whether the corresponding hardware
thread is currently in a wait state.

Note

The cycle count function, while part of the timer
interface, is independent of the timer and can be called
independently of the timer-related functions.

Thread cycle counts are for hardware threads only—they have no
relation to the software threads supported by the RTOS. For accurate
cycle counts on RTOS applications, use the RTOS profiling services or
the standalone tools hexagon-gprof and hexagon\_profiler (both are
part of the standard Hexagon tools release).

### hexagon\_sim\_read\_pcycles()

Returns the total processor cycle count, which indicates the number
of processor cycles executed for all hardware threads on the Hexagon
processor.

- **Prototype**
    - unsigned long long hexagon_sim_read_pcycles();
    Copy to clipboard

- **Detailed description**
    - The processor cycle count is reset to 0 after a processor reset.

The following example shows how hexagon\_sim\_read\_pcycles() can be
used to determine the processor cycle count for a specific section of
the application code:

start_cycles = hexagon_sim_read_pcycles();
    <*profiled user code*>;
    pcycle_count = hexagon_sim_read_pcycles() - start_cycles;
    Copy to clipboard

- **Returns**
    - Processor cycle count.

Last Published: Oct 06, 2026

[Previous Topic
Interfaces](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/interfaces.md) [Next Topic
Cache interface](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/cache-interface.md)