File QnnBackend.h

↰ Parent directory (include/QNN)

Backend component API.

Definition (include/QNN/QnnBackend.h)

Detailed Description

This is top level QNN API component. Most of the QNN API requires backend to be created first.

Includes

Full File Listing

Backend component API. 

    This is top level QNN API component.
    Most of the QNN API requires backend to be created first.

Defines

QNN_BACKEND_CONFIG_INIT   {                                                 \     QNN_BACKEND_CONFIG_OPTION_UNDEFINED

, /*option*/ \

{                                               \

NULL /*customConfig*/                         \

}                                               \

}


QnnBackend_Config_t initializer macro.

QNN_BACKEND_OPERATION_NAME_INIT

{                                     \

NULL,     /*packageName*/           \

NULL,     /*name*/                  \

NULL      /*target*/                \

}


QnnBackend_OperationName_t initializer macro.

QNN_BACKEND_PROPERTY_INIT   {                                                   \     QNN_BACKEND_PROPERTY_OPTION_UNDEFINED

, /*option*/ \

{                                                 \

NULL /*customProperty*/                         \

}                                                 \

}


QnnBackend_Property_t initializer macro.

Typedefs

typedef void *QnnBackend_CustomConfig_t

Backend specific object for custom configuration.

Please refer to documentation provided by the backend for usage information

typedef void *QnnBackend_CustomProperty_t

Backend specific object for custom property.

Please refer to documentation provided by the backend for usage information

Enums

enum QnnBackend_Error_t

QNN Backend API result / error codes.

Values:

enumerator QNN_BACKEND_MIN_ERROR = 4000
enumerator QNN_BACKEND_NO_ERROR = 0

Qnn Backend success.

enumerator QNN_BACKEND_ERROR_MEM_ALLOC = QNN_COMMON_ERROR_MEM_ALLOC

General error relating to memory allocation in Backend API.

enumerator QNN_BACKEND_ERROR_UNSUPPORTED_PLATFORM = QNN_COMMON_ERROR_PLATFORM_NOT_SUPPORTED

Backend attempted to be created on an unsupported platform.

enumerator QNN_BACKEND_ERROR_CANNOT_INITIALIZE = 4000 + 0

Backend failed to initialize.

enumerator QNN_BACKEND_ERROR_TERMINATE_FAILED = 4000 + 2

Failed to free allocated resources during termination.

enumerator QNN_BACKEND_ERROR_NOT_SUPPORTED = 4000 + 3

Backend does not support requested functionality.

enumerator QNN_BACKEND_ERROR_INVALID_ARGUMENT = 4000 + 4

Invalid function argument.

enumerator QNN_BACKEND_ERROR_OP_PACKAGE_NOT_FOUND = 4000 + 5

Could not find specified op package.

enumerator QNN_BACKEND_ERROR_OP_PACKAGE_IF_PROVIDER_NOT_FOUND = 4000 + 6

Could not load interface provider from op package library.

enumerator QNN_BACKEND_ERROR_OP_PACKAGE_REGISTRATION_FAILED = 4000 + 7

Failed to register op package.

enumerator QNN_BACKEND_ERROR_OP_PACKAGE_UNSUPPORTED_VERSION = 4000 + 8

Backend does not support the op config’s interface version.

enumerator QNN_BACKEND_ERROR_OP_PACKAGE_DUPLICATE = 4000 + 9

An Op with the same package name and op name was already registered.

enumerator QNN_BACKEND_ERROR_INCONSISTENT_CONFIG = 4000 + 10

Inconsistent backend configuration.

enumerator QNN_BACKEND_ERROR_INVALID_HANDLE = 4000 + 11

Invalid backend handle.

enumerator QNN_BACKEND_ERROR_INVALID_CONFIG = 4000 + 12

Invalid config.

enumerator QNN_BACKEND_MAX_ERROR = 4999
enumerator QNN_BACKEND_ERROR_UNDEFINED = 0x7FFFFFFF
enum QnnBackend_ConfigOption_t

This enum defines backend config options.

Values:

enumerator QNN_BACKEND_CONFIG_OPTION_CUSTOM = 0

Sets backend custom options via QnnBackend_CustomConfig_t.

enumerator QNN_BACKEND_CONFIG_OPTION_ERROR_REPORTING = 1

Sets error reporting level.

enumerator QNN_BACKEND_CONFIG_OPTION_PLATFORM = 2

Key-value pair of platform options.

enumerator QNN_BACKEND_CONFIG_OPTION_UNDEFINED = 0x7FFFFFFF
enum QnnBackend_PropertyOption_t

This enum defines backend property options.

Values:

enumerator QNN_BACKEND_PROPERTY_OPTION_CUSTOM = 0

Gets backend custom properties, see backend specific documentation.

enumerator QNN_BACKEND_PROPERTY_OPTION_UNDEFINED = 0x7FFFFFFF

Value selected to ensure 32 bits.

Functions

Qnn_ErrorHandle_t QnnBackend_create(Qnn_LogHandle_t logger, const QnnBackend_Config_t **config, Qnn_BackendHandle_t *backend)

Initialize a backend library and create a backend handle. Function is re-entrant and thread-safe.

Parameters

  • logger – [in] A handle to the logger, use NULL handle to disable logging. QnnBackend doesn’t manage the lifecycle of logger and must be freed by using QnnLog_free().

  • config – [in] Pointer to a NULL terminated array of config option pointers. NULL is allowed and indicates no config options are provided. All config options have default value, in case not provided. If same config option type is provided multiple times, the last option value will be used.

  • backend – [out] A handle to the created backend.

Returns

Error code:

  • QNN_SUCCESS: No error encountered

  • QNN_BACKEND_ERROR_UNSUPPORTED_PLATFORM: Backend attempted to be created on unsupported platform

  • QNN_BACKEND_ERROR_INCONSISTENT_CONFIG: One or more backend configurations are inconsistent between multiple create calls. Refer to backend headers for which configuration options must be consistent.

  • QNN_BACKEND_ERROR_CANNOT_INITIALIZE: backend failed to initialize

  • QNN_BACKEND_ERROR_MEM_ALLOC: error related to memory allocation

  • QNN_BACKEND_ERROR_INVALID_HANDLE: logger is not a valid handle

  • QNN_BACKEND_ERROR_INVALID_CONFIG: one or more config values is invalid

  • QNN_BACKEND_ERROR_NOT_SUPPORTED: an optional feature is not supported

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_setConfig(Qnn_BackendHandle_t backend, const QnnBackend_Config_t **config)

A function to set/modify configuration options on an already generated backend.

Parameters

  • backend – [in] A backend handle.

  • config – [in] Pointer to a NULL terminated array of config option pointers. NULL is allowed and indicates no config options are provided. All config options have default value, in case not provided. If same config option type is provided multiple times, the last option value will be used.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_BACKEND_ERROR_INVALID_HANDLE: backend is not a valid handle

  • QNN_BACKEND_ERROR_INVALID_CONFIG: at least one config option is invalid

  • QNN_BACKEND_ERROR_NOT_SUPPORTED: an optional feature is not supported

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_getApiVersion(Qnn_ApiVersion_t *pVersion)

Get the QNN API version.

Parameters

pVersion – [out] Pointer to version object.

Returns

Error code:

  • QNN_SUCCESS: No error encountered

  • QNN_BACKEND_ERROR_INVALID_ARGUMENT: if pVersion was NULL

Note

Safe to call any time, backend does not have to be created.

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_getBuildId(const char **id)

Get build id for backend library.

Parameters

id – [out] Pointer to string containing the build id.

Returns

Error code:

  • QNN_SUCCESS: No error encountered

  • QNN_BACKEND_ERROR_NOT_SUPPORTED: No build ID is available

  • QNN_BACKEND_ERROR_INVALID_ARGUMENT: if id is NULL

Note

Safe to call any time, backend does not have to be created.

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_registerOpPackage(Qnn_BackendHandle_t backend, const char *packagePath, const char *interfaceProvider, const char *target)

Register an operation package with the backend handle.

Parameters

  • backend – [in] A backend handle.

  • packagePath – [in] Path on disk to the op package library to load.

  • interfaceProvider – [in] The name of a function in the op package library which satisfies the QnnOpPackage_InterfaceProvider_t interface. The backend will use this function to retrieve the op package’s interface.

  • target – [in] An optional parameter specifying the target platform on which the backend must register the op package. Required in scenarios where an op package is to be loaded on a processing unit that is different from the target on which the backend runs. Ex: loading a DSP op package on ARM for optional online context caching. Refer to additional documentation for a list of permissible target names.

Returns

Error code:

  • QNN_SUCCESS: No error encountered

  • QNN_BACKEND_ERROR_INVALID_ARGUMENT: if packagePath or interfaceProvider is NULL

  • QNN_BACKEND_ERROR_OP_PACKAGE_NOT_FOUND: Could not open packagePath

  • QNN_BACKEND_ERROR_OP_PACKAGE_IF_PROVIDER_NOT_FOUND: Could not find interfaceProvider symbol in package library

  • QNN_BACKEND_ERROR_OP_PACKAGE_REGISTRATION_FAILED: Op package registration failed

  • QNN_BACKEND_ERROR_OP_PACKAGE_UNSUPPORTED_VERSION: Op package has interface version not supported by this backend

  • QNN_BACKEND_ERROR_NOT_SUPPORTED: Op package registration is not supported.

  • QNN_BACKEND_ERROR_INVALID_HANDLE: backend is not a valid handle

  • QNN_BACKEND_ERROR_OP_PACKAGE_DUPLICATE: OpPackageName+OpName must be unique. Op package content information can be be obtained with QnnOpPackage interface. Indicates that an Op with the same package name and op name was already registered.

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION: SSR occurence (successful recovery)

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION_FATAL: SSR occurence (unsuccessful recovery)

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_getSupportedOperations(Qnn_BackendHandle_t backend, uint32_t *numOperations, const QnnBackend_OperationName_t **operations)

Get the supported operations registered to a backend handle including built-in ops.

Parameters

  • backend – [in] A backend handle. Can be NULL to obtain the built-in op package.

  • numOperations – [out] Number of supported operations.

  • operations – [out] Array of operation names. Memory is backend owned and de-allocated during QnnBackend_free.

Returns

Error code:

  • QNN_SUCCESS: No error encountered

  • QNN_BACKEND_ERROR_INVALID_ARGUMENT: if numOperations or operations is NULL

  • QNN_BACKEND_ERROR_INVALID_HANDLE: backend is not a valid handle

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION: SSR occurence (successful recovery)

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION_FATAL: SSR occurence (unsuccessful recovery)

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_validateOpConfig(Qnn_BackendHandle_t backend, Qnn_OpConfig_t opConfig)

A method to validate op config with an appropriate op package This is a wrapper API around the actual OpPackage interface method that performs op validation. Backend may pick an appropriate op package among ones that are registered with it for validation based on the attributes of the op configuration.

Parameters

  • backend – [in] A backend handle.

  • opConfig – [in] Fully qualified struct containing the configuration of the operation.

Returns

Error code

  • QNN_SUCCESS if validation is successful

  • QNN_OP_PACKAGE_ERROR_VALIDATION_FAILURE: op config validation failed

  • QNN_BACKEND_ERROR_NOT_SUPPORTED: Validation API not supported

  • QNN_BACKEND_ERROR_OP_PACKAGE_NOT_FOUND: No op package with matching op config attributes found.

  • QNN_BACKEND_ERROR_INVALID_HANDLE: backend is not a valid handle

Note

inputTensors and outputTensors inside opConfig must be fully qualified for complete validation. However, their IDs (id) and names (name) are ignored during validation.

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_getProperty(Qnn_BackendHandle_t backendHandle, QnnBackend_Property_t **properties)

A function to get a list of backend properties. Backends are not required to support this API.

Parameters

  • backendHandle – [in] A backend handle.

  • [in/out] – properties Pointer to a null terminated array of pointers containing the properties associated with the passed backendHandle. Memory for this information is owned and managed by the client. Client needs to populate the property options being requested. If contextHandle is not recognized, the pointer properties points to is set to nullptr.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_BACKEND_ERROR_INVALID_HANDLE: backendHandle is not a valid handle

  • QNN_BACKEND_ERROR_INVALID_ARGUMENT: properties is NULL or at least one property option is invalid

  • QNN_BACKEND_ERROR_NOT_SUPPORTED: at least one valid property option is not supported

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnBackend_free(Qnn_BackendHandle_t backend)

Free all resources associated with a backend handle.

Parameters

backend – [in] handle to be freed.

Returns

Error code:

  • QNN_SUCCESS: No error encountered.

  • QNN_BACKEND_ERROR_MEM_ALLOC: error related to memory deallocation

  • QNN_BACKEND_ERROR_TERMINATE_FAILED: indicates failure to free resources or failure to invalidate handles and pointers allocated by the library

  • QNN_BACKEND_ERROR_INVALID_HANDLE: backend is not a valid handle

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION: SSR occurence (successful recovery)

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION_FATAL: SSR occurence (unsuccessful recovery)

Note

Use corresponding API through QnnInterface_t.

struct QnnBackend_Config_t
#include <QnnBackend.h>

This struct provides backend configuration.

Public Members

QnnBackend_ConfigOption_t option
union unnamed
#include <QnnBackend.h>

Public Members

QnnBackend_CustomConfig_t customConfig
Qnn_ErrorReportingConfig_t errorConfig

Applies error reporting configuration across backend. All QNN contexts share this common error configuration for APIs that are independent of a context.

const char *platformOption

Null-terminated platform option key-value pair. Multiple platform options can be specified. Max length is 1024.

struct QnnBackend_OperationName_t
#include <QnnBackend.h>

Struct which encapsulates the fully-qualified name of an operation.

Public Members

const char *packageName

The op package to which the operation belongs.

const char *name

The type name of the operation.

const char *target

The intended target platform for the combination of domain and operation name. Target may be unused (NULL) by some backends.

struct QnnBackend_Property_t
#include <QnnBackend.h>

This struct provides backend property. Option is specified by the client. Everything else is written by the backend.

Public Members

QnnBackend_PropertyOption_t option
union unnamed
#include <QnnBackend.h>

Public Members

QnnBackend_CustomProperty_t customProperty