# Runtime support library The standalone runtime support library supports the following features: - Memory management - Multi-threaded programming - Thread synchronization (using mutexes) - Interrupt handling - HVX engine management The library is accessed by including the library header file, `hexagon_standalone.h`. The [Functions and macros](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-runtime-sup-lib-func-macros) section describes the functions and macros that are defined in the library. For an example program, see [Example](https://docs.qualcomm.com/doc/80-N3040-23/topic/example.html). ## Cache properties The address translation functions (see [add\_translation()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation), [add\_translation\_fixed()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation-fixed), and [add\_translation\_extended()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation-extended)) accept a parameter that specifies the following cache properties of a remapped memory page: - Cached or uncached - Cache write-back (WB) or write-through (WT) These properties can be specified for the L1 data and instruction caches, and for the L2 cache. The following table lists the cache properties and the values used to specify them. | Value | L1 data cache | L1 instruction cache | L2 cache | | --- | --- | --- | --- | | 0 | Cached, WB | Cached | Uncached | | 1 | Cached, WT | Cached | Uncached | | 2 | Device-type, SFC | Uncached | Uncached | | 3 | Uncached, SFC | Uncached | Uncached | | 4 | Device-type | Uncached | Uncached | | 5 | Cached, WT | Uncached | Cached, WT | | 6 | Uncached | Uncached | Uncached | | 7 | Cached, WB | Cached | Cached, WB^1^ | | 8 | Cached, WB | Cached | Cached, WT | | 9 | Cached, WT | Cached | Cached, WB | | 10 | Cached, WB | Uncached | Cached, WB/AUX^2^ | | 11 | Cached, WT | Uncached | Cached, WT/AUX | | 12 | Reserved | Reserved | Reserved | | 13 | Uncached | Uncached | Cached, WT | | 14 | reserved | Reserved | Reserved | | 15 | Uncached | Uncached | Cached, WB | Note 1. If L2$ supports write-back and WB feature is enabled; otherwise use WT. 2. Lines will be allocated into Auxiliary partition of L2$. The following table lists the cache properties for V67 Small Core (V67t) and the values used to specify them. | Value | L1 data cache | 1 instruction cache | L2 Behavior | | --- | --- | --- | --- | | 0 | Reserved | Reserved | Reserved | | 1 | Cacheable | WT Cached | Uncached | | 2 | Device-type, SFC | Uncached | Uncached | | 3 | Uncached SFC | Uncached | Uncached | | 4 | Device-type | Uncached | Uncached | | 5 | Cacheable, WT | Uncached | Uncached | | 6 | Uncached | Uncached | Uncached | | 7 | Cacheable, WB | Cached | Cached, WB | | 8-15 | Reserved | Reserved | Reserved | ## Functions and macros ### add\_translation() Remaps a Hexagon processor memory page. **Prototype** void add_translation(void *va, void *pa, int cacheability) Copy to clipboard **Parameters** | *va* | Pointer to the virtual memory address. | | --- | --- | | *pa* | Pointer to the corresponding physical memory address. | | *cacheability* | Cache properties (see [Cache properties](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-runtime-sup-lib-cache-prop)).


By default, the cacheability setting of each page is 0. | **Detailed description** The `add_translation()` function is not designed to be thread safe. It can be called only from thread 0 and before any other threads are created. The library defines memory as consisting of 4096 1 MB pages. By default, each page is assigned a one-to-one mapping between virtual and physical memory. However, standalone applications can remap individual pages to different areas in physical memory. The application code remaps a page by calling `add_translation()`. For example: add_translation(0x100000, 0xD8000000, 2); add_translation(0x200000, 0xD8100000, 4); Copy to clipboard For more information on memory management and caches, see the appropriate *Qualcomm Hexagon Programmer’s Reference Manual*. ### add\_translation\_fixed() Remaps a Hexagon processor memory page using a fixed TLB entry. **Prototype** void add_translation_fixed(int index void *va, void *pa, int cacheability, int permissions) Copy to clipboard **Parameters** | *index* | Index of a fixed TLB entry (1 through 5). | | --- | --- | | *va* | Pointer to the virtual memory address.


If this parameter is NULL, the entry specified by the index parameter is invalid. | | *pa* | Pointer to the corresponding physical memory address. | | *cacheability* | Cache properties (see [Cache properties](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-runtime-sup-lib-cache-prop)). | | *permissions* | Memory access rights:


Multiple memory access rights can be specified by adding the individual permission values. For example, read/write permission is specified with the value 3 (1+2). | **Detailed description** The `add_translation_fixed()` function is not designed to be thread safe. It can be called only from thread 0 and before any other threads are created. The default TLB miss handler maintains a table of TLB entries for the address translations performed by a standalone application (see [add\_translation()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation)). The handler uses a round-robin replacement strategy for all TLB entries except the first six: - TLB index zero (0) is reserved and always provides translation for the TLB table. - TLB entries 1 through 5 are excluded from the TLB-entry replacement strategy (that is, they are fixed) to support programs that require specific address translations. The application code remaps a page using one of the fixed TLB entries by calling `add_translation_fixed()`. For example: add_translation_fixed(1, 0x100000, 0xD8000000, 2, 4); add_translation_fixed(4, 0x200000, 0xD8100000, 4, 7); Copy to clipboard Note This function uses the same default page size as described in *Detailed description* for [add\_translation()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation)). ### add\_translation\_extended() Remaps a Hexagon processor memory page using direct access to a TLB entry. This function is valid only for Hexagon processor version V5 or greater. **Prototype** int add_translation_extended(int index void *va, uint64_t pa, unsigned int page_size, unsigned int xwru, unsigned int cccc, unsigned int asid, unsigned int aa, unsigned int vg) Copy to clipboard **Parameters** | *index* | Index of a fixed TLB entry (1 through 5). | | --- | --- | | *va* | Pointer to the virtual memory address. | | *pa* | Corresponding physical memory address. | | *page\_size* | Page size (in bytes).
| | *xwru* | Integer value interpreted as a 4-bit value representing the X, W, R, and U bits in a TLB entry. | | *cccc* | Cache properties (see [Cache properties](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-runtime-sup-lib-cache-prop)). | | *asid* | Integer value interpreted as a 7-bit value representing the ASID bit field in a TLB entry. | | *aa* | Integer value interpreted as a 2-bit value representing the A1 and A0 bits in a TLB entry. | | *vg* | Integer value interpreted as a 2-bit value representing the V and G bits in a TLB entry. | **Detailed description** The `add_translation_extended()` function is similar to [add\_translation\_fixed()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation-fixed), but it allows you to directly set the individual fields in a TLB entry. This function can also be used to specify page mappings with physical addresses that exceed 32 bits. Note This function uses the same default page size as described in *Detailed description* for [add\_translation()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-add-translation). This `add_translation_extended()` function is not designed to be thread safe. It can be called only from thread 0 and before any other threads are created. All TLB fields must be set to valid values. Note Allocating a `page_size` of 4 KB, 16 KB, 64 KB, or 256 KB (any size less than 1 MB) will leave the remainder of the address space around the allocated `page_size` address area, within the 1 MB block in which it sits, unusable unless you manually create a TLB table entry. Any memory access of the unusable memory space will result in a TLB miss-RW exception. **Returns** - 0 — If the specified page is successfully remapped. - Non-0 — Otherwise. ### thread\_create() Creates and starts a new thread. **Prototype** void thread_create(void (*pc) (void *), void *sp, int threadno, void *param); Copy to clipboard **Parameters** | *pc* | Pointer to the function executed by the thread. | | --- | --- | | *sp* | Pointer to the memory area used as a thread stack.


This parameter must be 8-byte aligned. Also, it must be set to the highest stack address in the thread stack memory area because the stack grows downward.


For more information on stacks, see the appropriate *Qualcomm Hexagon Programmer’s Reference Manual*. | | *threadno* | Hardware thread number assigned to the thread (0 through 5). | | *param* | Pointer to the data structure accessed by the thread. | ### thread\_create\_extended() Creates and starts a new thread using stack protection attributes. Note This function is intended for use only with processor version V61 or greater. If used with earlier processor versions, the `framekey` and `stacksize` attributes are ignored, and the function is then equivalent to `thread_create()`. **Prototype** void thread_create_extended(void (*pc) (void *), void *sp, int threadno, unsigned framekey, unsigned stacksize, void *param); Copy to clipboard **Parameters** | *pc* | Pointer to the function executed by thread. | | --- | --- | | *sp* | Pointer to the memory area used as thread stack.


This parameter must be 8-byte aligned. Also, it must be set to the highest stack address in the thread stack memory area because the stack grows downward. | | *threadno* | Hardware thread number assigned to thread (0 through 5). | | *framekey* | 32-bit value used to scramble return addresses stored on stack. | | *stacksize* | Size (in bytes) of memory area used as thread stack.


This parameter must be greater than 0; it is used to set the FRAMELIMIT control register.


For more information on stacks, see the appropriate *Qualcomm Hexagon Programmer’s Reference Manual*. | | *param* | Pointer to the data structure accessed by thread. | **Detailed description** This function is similar to [thread\_create()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-thread-create), but it allows you to specify the `framekey` and `stacksize` stack protection attributes. ### thread\_stop() Stops execution of the currently executing thread. **Prototype** void thread_stop(void); Copy to clipboard ### thread\_join() Suspends the currently executing thread until the specified threads stop. **Prototype** void thread_join(int mask); Copy to clipboard **Parameters** | *mask* | Bit mask that specifies one or more hardware threads.


Bits 0 through 5 in the value indicate whether the corresponding hardware thread numbers are specified (for example, bit 0 = thread 0). | | --- | --- | ### thread\_get\_tnum() Returns the hardware thread number (0 through 5) assigned to the currently executing thread. This function is implemented as a macro. **Prototype** int thread_get_tnum(void); Copy to clipboard ### lockMutex() Locks a specified mutex. **Prototype** void lockMutex(int *mutex); Copy to clipboard **Parameters** | *mutex* | Pointer to the address of the variable used as a mutex. | | --- | --- | **Detailed description** The variable referenced by mutex must be a global variable that is initialized to 0 before use as a mutex. If the mutex variable is declared in internal memory, the variable’s memory attributes must be specified as cached and write-back; otherwise, the mutex behavior is undefined. If the mutex variable is declared in external memory, the variable’s memory attributes must be specified as uncached; otherwise, the mutex behavior is undefined. External-memory mutexes have additional system requirements. For more information, see the appropriate *Qualcomm Hexagon Programmer’s Reference Manual*. ### unlockMutex() Unlocks a specified mutex. (For more information, see [lockMutex()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-lockmutex)) **Prototype** void unlockMutex(int *mutex); Copy to clipboard **Parameters** | *mutex* | Pointer to the address of the variable used as a mutex. | | --- | --- | ### trylockMutex() Attempts to lock a specified mutex. **Prototype** int trylockMutex(int *mutex); Copy to clipboard **Parameters** | *mutex* | Pointer to the address of the variable used as a mutex. | | --- | --- | **Detailed description** If the specified mutex is not being used, this function performs a normal lock operation and returns the result value 1. Otherwise, it does not attempt to lock the mutex and returns the result value 0. For more information, see [lockMutex()](https://docs.qualcomm.com/doc/80-N3040-23/topic/runtime-support-library.html#hsapp-func-macros-lockmutex)). ### register\_interrupt() Assigns a callback function to an interrupt. **Prototype** void register_interrupt(int intno, void (*IRQ_handler)(int intno)); Copy to clipboard **Parameters** | *intno* | Interrupt number (0 through 31). | | --- | --- | | *IRQ\_handler* | Pointer to the interrupt callback function. | **Detailed description** Interrupt callbacks are functions that are called by an interrupt. A callback function is defined in the application. It must be defined to accept the interrupt identifier as a function argument. The argument enables a single callback function to be written so it can handle multiple interrupts. The Hexagon processor uses an L2 vectored interrupt controller (L2VIC) to manage interrupts. When the handler function is called, the `intno` parameter is always set to 31, with the actual interrupt number (0 through 1023) being stored in the Hexagon system-level register VID. To access the actual interrupt number, the handler can define a simple register-access function. For example: static inline uint32 get_int_number(void) { uint32 reg; asm volatile ("%0=vid;" :"=r"(reg)); return reg; } void IRQ_handler(int intno) { uint32 INT_number; INT_number = get_int_number(); switch (INT_number) { case 0: // Code to process interrupt number 0 break; case 1: // Code to process interrupt number 1 break; case default: // Code to process interrupts 2 to 1023 break; } } Copy to clipboard If no callback function is assigned to an interrupt, the interrupt triggers an empty callback function. For more information, see the appropriate *Qualcomm Hexagon Programmer’s Reference Manual*. ### SIM\_ACQUIRE\_HVX Acquires an HVX engine before using it. Use of this macro is system-dependent. **Prototype** SIM_ACQUIRE_HVX; Copy to clipboard **Detailed description** When the number of hardware threads is greater than the number of HVX units, a thread using HVX instructions must first explicitly acquire one of the HVX engines. A thread acquires an HVX engine by calling the macro, `SIM_ACQUIRE_HVX`. When a thread is finished using the HVX engine, it must call `SIM_RELEASE_HVX` to release the engine. ### SIM\_RELEASE\_HVX Releases an HVX resource. Use of this macro is system-dependent. **Prototype** SIM_RELEASE_HVX; Copy to clipboard ### acquire\_vector\_unit() Grabs a vector unit. **Prototype** int acquire_vector_unit(hexagon_vector_wait_t wait); Copy to clipboard **Parameters** | *wait* | The input can be one of the following:
| | --- | --- | **Returns** - 1 - If a vector unit as been acquired. - 0 - If a vector unit has not been acquired. - Number of vector units that are free. This value is returned when `HEXAGON_VECTOR_CHECK` is passed. `HEXAGON_VECTOR_CHECK` does not lock the unit. ### release\_vector\_unit() Unlocks a vector unit. **Prototype** void release_vector_unit(); Copy to clipboard **Detailed description** Unlocking the vector resource allows other threads to use it. This thread’s `SSR:XA` and `SSR:XE` bits are reset. Subsequent HVX instructions will fault with an illegal execution of coprocessor instruction, `SSR:CAUSE` of 0x16. The `SIM_RELEASE_HVX` macro calls `release_vector_unit()`. ### set\_double\_vector\_mode() Puts a vector unit into Double Vector mode. **Prototype** void set_double_vector_mode(); Copy to clipboard **Detailed description** Code used in this mode must be built with the `-mhvx=double` option. The `SIM_SET_HVX_DOUBLE_MODE` macro calls `set_double_vector_mode()`. ### clear\_double\_vector\_mode() Clears the 128-byte vector mode bit in the `SYSCFG` register. **Prototype** void clear_double_vector_mode(); Copy to clipboard **Detailed description** Code used in this mode must be built with the `-mhvx=single` option. The `SIM_CLEAR_HVX_DOUBLE_MODE` macro calls `clear_double_vector_mode()`. ### power\_vector\_unit() Provides subsystem addresses for clock, reset, and power delay; and enables or disables the unit. **Prototype** extern void power_vector_unit (uint32_t volatile *clockbase, uint32_t volatile *resetbase, uint32_t volatile *powerbase, int delay, int state); Copy to clipboard **Parameters** | *clockbase* | Pointer to the clock subsystem address. | | --- | --- | | *resetbase* | Pointer to the reset subsystem address. | | *powerbase* | Pointer to the power delay subsystem address. | | *state* | Specify whether the unit is disabled (0) or enabled (1). | **Detailed description** This function is used for very low-level verification and configuration on hardware. This function will not do anything if it is called while running on a simulator (it is a no-operation function). The function will perform its stated operations only when running on real hardware. Last Published: Oct 06, 2026 [Previous Topic Parameters](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/build-procedure.md) [Next Topic Example](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/example.md)