# Configuration

In earlier releases the architecture version was fixed when the library was
built, and behavior was adjusted through individual API calls. In this release
one library contains every supported architecture, and the selection is made at
run time from a TOML configuration. See [Replace configuration calls](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-migration.html#libnative-migration-config) for the
mapping from the old functions to their replacements.

## Configuration sources

Libnative uses a three-stage configuration system. Each stage overrides the
previous ones:

- **Stage 0** – Built-in defaults, compiled into the library. A reference copy
is installed as `defaults.toml`; see [Default configuration reference](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-configuration.html#libnative-config-defaults).
- **Stage 1** – File-based configuration, read at program execution from a file
named `libnative.toml` in the working directory. A missing file is not an
error.
- **Stage 2** – Function-based configuration, applied with
`libnative_configure()`.

Later stages override individual keys of earlier ones rather than replacing
whole sections. For example, passing nothing but `strict_ieee` changes that
setting while keeping the default architecture version and everything else.

## Configuration API

The configuration API is declared in `libnative_config.h`:

| Function | Description |
| --- | --- |
| `void libnative_configure(const char* toml_string)` | Applies a TOML string. Must be called before the first intrinsic call. |
| `int lnconfig_get_int(const char* section, const char* key)` | Reads an integer setting. |
| `bool lnconfig_get_bool(const char* section, const char* key)` | Reads a boolean setting. |
| `const char* lnconfig_get_string(const char* section, const char* key)` | Reads a string setting. |

Getters are provided for convenience. They will abort on an unknown section or
key, or on a type mismatch.

Warning

A TOML string that fails to parse is **ignored**. Libnative makes no
attempt to report configuration errors or correct malformed strings.

Section headers and keys must be separated by newlines. This is valid:

[general]
    arch = 89
    Copy to clipboard

This is **not** valid TOML and will be discarded:

[general] arch = 89
    Copy to clipboard

## When configuration can be changed

All configuration can be modified with `libnative_configure()` prior to
calling the first intrinsic. At that point the configuration becomes finalized
and cannot be further modified; attempting to do so causes an assert.

Libnative initializes itself lazily on the first intrinsic call. During
finalization it checks certain configuration settings and asserts if a bad
configuration is detected.

Note

Libnative’s error checking here is lightweight by design. It is assumed
that a user changing advanced settings knows what they are doing, and many
configurations which either do not correspond to a real Hexagon core or are
totally invalid will pass Libnative’s error checking. Users targeting a
specific core should refer to the configuration of that core, keeping in mind
that Libnative makes no attempt at modeling microarchitecture and has no
concept of specific Hexagon cores.

## General settings

| Setting | Default | Description |
| --- | --- | --- |
| `arch` | `91` | Hexagon architecture version. See [Supported versions](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-architecture-versions.html#libnative-arch-supported). |
| `strict_ieee` | `false` | `false`: v79-and-earlier QFloat behavior. `true`: system IEEE<br>behavior. Requires v81 or later. |
| `use_tls` | `true` | `false`: use a unified heap for Libnative state rather than<br>thread-local storage. |

`strict_ieee` replaces the `enable_qfloat_strict_ieee_mode()` and
`disable_qfloat_strict_ieee_mode()` functions documented in earlier releases.

## Example configuration

A minimal configuration that selects an architecture and sets an HMX
microarchitectural option looks like this:

[general]
    arch = 89
    
    [hmx_arch_proc_options]
    QDSP6_MX_ROWS = 16
    Copy to clipboard

`QDSP6_MX_ROWS` is only required for certain HMX modeling configurations and
is not necessary otherwise.

## HMX microarchitectural options

The `[hmx_arch_proc_options]` section is an advanced, rarely needed escape
hatch.

Warning

These options represent microarchitectural and debugging parameters used in
the emulation of HMX. They can cause unexpected behavior which manifests in
hard-to-predict ways. It is therefore strongly advised that they are modified
with extreme caution. Changing these settings will only be necessary in a
very small minority of cases. These defaults are subject to change at any time.

The reference copy of `defaults.toml` provided with Libnative contains a full
list of these settings and their defaults.

## Default configuration reference

`defaults.toml` can be found in the `Tools/libnative/share/` directory, and
contains a full list of the default configuration options that Libnative is built
with. It is not required for Libnative to run. Unless you would like to override
an option shown in this file, specifying the option in later configuration is
not necessary.

## USR register access

Modification of the USR bits is permitted with:

uint32_t libnative_get_usr(void);
    void     libnative_set_usr(uint32_t value);
    Copy to clipboard

Unlike the TOML configuration, these bits are a part of Libnative’s runtime
state, and can be changed at any time without limitation.

Last Published: Oct 06, 2026

[Previous Topic
Confirm which library you have](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/libnative-ug-build-and-link.md) [Next Topic
Architecture versions](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/libnative-ug-architecture-versions.md)