# Restrictions and known behavior

Libnative makes certain compromises in order to function:

- Libnative is not cycle accurate, and provides no timing model. Further,
Libnative is not a performance model, and makes no claim about the runtime
of the Hexagon target it models.
- Libnative is not bit-exact with XQFloat. This is not possible while keeping the
structs 32-bit, as there is no way to model the extra four bits.

Libnative is bit-exact with all non-XQFloat intrinsics on v81 and later, and is
bit-exact with all intrinsics, including QFloat, on v68 through v79.

## Configuration is fixed after initialization

The configuration must be complete before the first intrinsic call. Libnative
initializes itself lazily on that call and freezes the configuration; a later
attempt to reconfigure prints a diagnostic and aborts.

One process therefore exercises one configuration. A test matrix over
architectures needs one process per combination. See
[When configuration can be changed](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-configuration.html#libnative-config-timing).

## Diagnostics and failure behavior

Invalid configuration and misuse of the configuration API produce a diagnostic on
standard error and abort.

The messages a user is most likely to see:

| Message | Cause |
| --- | --- |
| `Libnative configured with unsupported arch vNN` | `arch` is not one of the compiled-in versions. See<br>[Supported versions](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-architecture-versions.html#libnative-arch-supported). |
| `libnative_configure() called after config was finalized` | A configuration call was made after the first intrinsic call. |
| `Config section [S] does not exist` /<br>`Config key [S].K does not exist` | A getter was called with an unknown section or key, or with a value of the<br>wrong type. |

Warning

A TOML string that fails to parse is ignored rather than diagnosed,
so a syntax error produces no message of its own. See
[Configuration API](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-configuration.html#libnative-config-api).

## Threading

Emulated state is per thread by default. Setting `use_tls = false` makes
Libnative use a single shared copy on a unified heap instead; see
[General settings](https://docs.qualcomm.com/doc/80-N3040-23/topic/libnative-ug-configuration.html#libnative-config-general). Sharing emulated state across threads with
`use_tls = false` is not advised, as Libnative does not enforce atomic
accesses in this mode.

Last Published: Oct 06, 2026

[Previous Topic
Selecting the version](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/libnative-ug-architecture-versions.md) [Next Topic
Profiler User Guide](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/index_80-n2040-10_profiler_user_guide.md)