# HTP API Usage Guidelines

## Minimum Mandatory API Callflows

QNN has a wide assortment of APIs to support various usecases and features. The callflow to initialize
a QNN backend and execute a model requires that the following minimum subset of APIs are utilized to
create the base QNN components based on the different usecases that follow:

### Logging Enabled | Online Prepare | Specified Device

1. QnnLog\_create
2. QnnBackend\_create
3. QnnDevice\_create
4. QnnContext\_create
5. QnnGraph\_create
6. loop N times : QnnTensor\_createGraphTensor
7. loop M times : QnnGraph\_addNode
8. QnnGraph\_finalize
9. QnnGraph\_execute
10. QnnContext\_free
11. QnnDevice\_free
12. QnnBackend\_free
13. QnnLog\_free

### Logging Enabled | Offline Prepare | Specified Device

1. QnnLog\_create
2. QnnBackend\_create
3. QnnDevice\_create
4. QnnContext\_createFromBinary
5. QnnGraph\_retrieve
6. QnnGraph\_execute
7. QnnContext\_free
8. QnnDevice\_free
9. QnnBackend\_free
10. QnnLog\_free

### Logging Disabled (Default to WARN) | Offline Prepare | Default Device

1. QnnBackend\_create
2. QnnContext\_createFromBinary
3. QnnGraph\_retrieve
4. QnnGraph\_execute
5. QnnContext\_free
6. QnnBackend\_free

## API Use Guidelines

For every `Qnn*_create` API that is called, the corresponding `Qnn*_free` API must also be invoked
by the client to release the associated resources or handles. These free APIs must be called in the
reverse order of their related create APIs, following FILO (first‑in, last‑out) semantics, to avoid
issues during QNN deinitialization and process exit.

Many QNN APIs must be invoked in specific orders or only after certain prerequisite APIs. In general,
all QNN APIs must be called after `QnnBackend_create()`. The only exception is the set of `QnnLog_*`
APIs, which do not require a backend handle and may therefore be called before `QnnBackend_create()`.
Though technically `QnnDevice_create()` does not require a backend handle, it is strongly encouraged
to call `QnnDevice_create()` after `QnnBackend_create()` to ensure proper initialization of resources

The following is a near exhaustive list of QNN APIs, organized to illustrate the typical call sequence
required for correct use of the QNN backend. Some APIs may be invoked multiple times and not strictly in
the sequence shown, as long as all prerequisite handles and resources have been created successfully prior
to those APIs are called.

### API DEMARCATION LEGEND

**A** = Alternate API
**O** = Optional API
**PC** = Anytime [\*\*](https://docs.qualcomm.com/doc/80-63442-10/topic/htp_api_usage_guidelines.html#id1)P\*\*ost [\*\*](https://docs.qualcomm.com/doc/80-63442-10/topic/htp_api_usage_guidelines.html#id3)C\*\*reate of Respective API (QnnGraph\_\*, QnnDevice\_\*, etc)
Please note that all APIs are mandatory unless otherwise marked optional or alternate

### Expanded Callflow | Logging Enabled | Offline Prepare | Specified Device

1. QnnLog\_create
2. QnnLog\_setLogLevel **(O)** **(PC)**
3. QnnBackend\_create
4. QnnDevice\_getPlatformInfo **(O)** **(PC)**
5. QnnDevice\_create
6. QnnDevice\_getInfo **(O)** **(PC)**
7. QnnDevice\_setConfig **(O)** **(PC)**
8. QnnDevice\_freePlatformInfo **(O)**
9. QnnDevice\_getInfrastructure **(O)**
10. QnnContext\_validateBinary **(O)**
11. - QnnContext\_createFromBinary
    - 1. QnnContext\_createFromBinaryListAsync **(A)**
    2. QnnContext\_createFromBinaryWithCallback **(A)**
    3. QnnContext\_createFromBinaryWithSignal **(A)**
12. QnnContext\_getProperty **(O)** **(PC)**
13. QnnContext\_setConfig **(O)** **(PC)**
14. QnnGraph\_retrieve
15. QnnProfile\_create **(O)**
16. QnnProfile\_setConfig **(O)** **(PC)**
17. - QnnGraph\_execute **(PC)**
    - 1. QnnGraph\_executeAsync **(A)** **(PC)**
18. QnnProfile\_getEvents **(O)** **(PC)**
19. QnnProfile\_getSubEvents **(O)** **(PC)**
20. QnnProfile\_getEventData **(O)** **(PC)**
21. QnnProfile\_getExtendedEventData **(O)** **(PC)**
22. QnnProfile\_free **(O)**
23. QnnContext\_free
24. QnnDevice\_free
25. QnnBackend\_free
26. QnnLog\_free

### Online Prepare Alternates

1. … <Backend\_Init> …
2. QnnDevice\_create
3. QnnContext\_create
4. QnnGraph\_create
5. QnnGraph\_getProperty **(O)** **(PC)**
6. loop N times : QnnTensor\_createGraphTensor
7. loop M times : QnnGraph\_addNode
8. QnnTensor\_createContextTensor **(O)**
9. - QnnGraph\_finalize
    - 1. QnnContext\_getBinarySize **(O)** **(PC)**
    2. QnnContext\_getBinary **(O)** **(PC)**
    3. QnnContext\_getBinarySectionSize **(O)** **(PC)**
    4. QnnContext\_getBinarySection **(O)** **(PC)**
10. QnnGraph\_setConfig **(O)** **(PC)**
11. QnnGraph\_prepareExecutionEnvironment **(O)** **(PC)**
12. QnnGraph\_execute
13. QnnGraph\_releaseExecutionEnvironment **(O)** **(PC)**
14. … <Backend\_Deinit> …

### Post Backend Create APIs

- QnnBackend\_setConfig **(O)**
- QnnBackend\_getApiVersion **(O)**
- QnnBackend\_getBuildId **(O)**
- - QnnBackend\_registerOpPackage **(O)**
    - - QnnBackend\_getSupportedOperations **(O)**
    - QnnBackend\_validateOpConfig **(O)**
- QnnBackend\_getProperty **(O)**
- QnnProperty\_hasCapability **(O)**
- - QnnSignal\_create **(O)**
    - - QnnSignal\_setConfig **(O)**
    - QnnSignal\_trigger **(O)**
    - QnnSignal\_free **(O)**

The below APIs are not commonly used due to obsolescence driven by iterative QNN development, but are
still backwards compatible with the QNN interface. These can be called at any given time, though
QnnError\_getMessage() is generally called after other APIs to retrieve error messages.
QnnError\_freeVerboseMessage() API must be called to free memory allocated to receive the error messages.

### Outdated APIs

- QnnError\_getMessage **(O)**
- QnnError\_getVerboseMessage **(O)**
- QnnError\_freeVerboseMessage **(O)**

### Feature Specific APIs

There are a handful of APIs not covered in various sections and callflows above that are specifically
designed for special usecase scenarios / feature utilization. This includes but is not limited to
[external memory mapping](https://docs.qualcomm.com/doc/80-63442-10/topic/htp_shared_buffer_tutorial.html) and [LoRa](https://docs.qualcomm.com/doc/80-63442-10/topic/general_tutorials.html). For use of APIs targeted towards that feature and others, please refer to
their feature specific documentation pages.

Last Published: Jun 04, 2026

[Previous Topic
HTP](https://docs.qualcomm.com/bundle/publicresource/80-63442-10/topics/htp_backend.md) [Next Topic
Qualcomm Hexagon Plugin Interface](https://docs.qualcomm.com/bundle/publicresource/80-63442-10/topics/htp_qhpi.md)