File QnnDevice.h

↰ Parent directory (include/QNN)

Device component API.

Definition (include/QNN/QnnDevice.h)

Detailed Description

This is the top level QNN API component for hardware resource management.

Includes

Full File Listing

Device component API. 

    This is the top level QNN API component for hardware resource management.

Defines

QNN_DEVICE_DEFAULT_DEVICE_ID 0xFFFFFFFF

Reserved value to select a default device.

QNN_DEVICE_DEFAULT_CORE_ID 0xFFFFFFFF

Reserved value to select a default core.

QNN_DEVICE_CORE_INFO_V1_INIT   {                                                   \     QNN_DEVICE_DEFAULT_CORE_ID

, /*coreId*/            \

0u,                         /*coreType*/          \

NULL                        /*coreInfoExtension*/ \

}


QnnDevice_CoreInfoV1_t initializer macro.

QNN_DEVICE_CORE_INFO_INIT   {                                             \     QNN_DEVICE_CORE_INFO_VERSION_1

, /*version*/ \

{                                           \

QNN_DEVICE_CORE_INFO_V1_INIT

/*v1*/       \

}                                           \

}


QnnDevice_CoreInfo_t initializer macro.

QNN_DEVICE_HARDWARE_DEVICE_INFO_V1_INIT   {                                                       \     QNN_DEVICE_DEFAULT_DEVICE_ID

, /*deviceId*/            \

0u,                           /*deviceType*/          \

0u,                           /*numCores*/            \

NULL,                         /*cores*/               \

NULL                          /*deviceInfoExtension*/ \

}


QnnDevice_HardwareDeviceInfoV1_t initializer macro.

QNN_DEVICE_HARDWARE_DEVICE_INFO_INIT   {                                                        \     QNN_DEVICE_HARDWARE_DEVICE_INFO_VERSION_1

, /*version*/ \

{                                                      \

QNN_DEVICE_HARDWARE_DEVICE_INFO_V1_INIT

/*v1*/       \

}                                                      \

}


QnnDevice_HardwareDeviceInfo_t initializer macro.

QNN_DEVICE_PLATFORM_INFO_V1_INIT

{                                      \

0u,      /*numHwDevices*/            \

NULL     /*hwDevices*/               \

}


QnnDevice_PlatformInfoV1_t initializer macro.

QNN_DEVICE_PLATFORM_INFO_INIT   {                                                 \     QNN_DEVICE_PLATFORM_INFO_VERSION_1

, /*version*/ \

{                                               \

QNN_DEVICE_PLATFORM_INFO_V1_INIT

/*v1*/       \

}                                               \

}


QnnDevice_PlatformInfo_t initializer macro.

QNN_DEVICE_CONFIG_INIT   {                                                \     QNN_DEVICE_CONFIG_OPTION_UNDEFINED

, /*option*/ \

{                                              \

NULL /*customConfig*/                        \

}                                              \

}


QnnDevice_Config_t initializer macro.

Typedefs

typedef struct _QnnDevice_Infrastructure_t *QnnDevice_Infrastructure_t

Backend specific opaque infrastructure object.

Please refer to the documentation provided by the backend for usage information.

typedef struct _QnnDevice_CoreInfoExtension_t *QnnDevice_CoreInfoExtension_t

Backend-defined structure to populate backend specific information for core info.

typedef struct _QnnDevice_DeviceInfoExtension_t *QnnDevice_DeviceInfoExtension_t

Backend-defined structure to populate backend specific information for device info.

typedef void *QnnDevice_CustomConfig_t

Backend specific object for custom configuration.

Please refer to documentation provided by the backend for usage information

Enums

enum QnnDevice_Error_t

QNN Device API result / error codes.

Values:

enumerator QNN_DEVICE_MIN_ERROR = 14000
enumerator QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE = QNN_COMMON_ERROR_NOT_SUPPORTED

There is optional API component that is not supported yet. See QnnProperty.

enumerator QNN_DEVICE_ERROR_MEM_ALLOC = QNN_COMMON_ERROR_MEM_ALLOC

Memory allocation/deallocation failure.

enumerator QNN_DEVICE_ERROR_INVALID_ARGUMENT = QNN_COMMON_ERROR_INVALID_ARGUMENT

Invalid function argument.

enumerator QNN_DEVICE_ERROR_INVALID_HANDLE = 14000 + 0

Invalid handle.

enumerator QNN_DEVICE_ERROR_INVALID_CONFIG = 14000 + 1

Invalid config values.

enumerator QNN_DEVICE_ERROR_HARDWARE_UNAVAILABLE = 14000 + 2

Hardware unavailable.

enumerator QNN_DEVICE_ERROR_ASSOCIATED_TO_CONTEXT = 14000 + 3

Device is associated to a context.

enumerator QNN_DEVICE_NO_ERROR = 0

Qnn Device success.

enumerator QNN_DEVICE_MAX_ERROR = 14999
enumerator QNN_DEVICE_ERROR_UNDEFINED = 0x7FFFFFFF
enum QnnDevice_CoreInfoVersion_t

Enum to distinguish core info versions.

Values:

enumerator QNN_DEVICE_CORE_INFO_VERSION_1 = 1
enumerator QNN_DEVICE_CORE_INFO_VERSION_UNDEFINED = 0x7FFFFFFF
enum QnnDevice_HardwareDeviceInfoVersion_t

Enum to distinguish device info versions.

Values:

enumerator QNN_DEVICE_HARDWARE_DEVICE_INFO_VERSION_1 = 1
enumerator QNN_DEVICE_HARDWARE_DEVICE_INFO_VERSION_UNDEFINED = 0x7FFFFFFF
enum QnnDevice_PlatformInfoVersion_t

Enum to distinguish platform info versions.

Values:

enumerator QNN_DEVICE_PLATFORM_INFO_VERSION_1 = 1
enumerator QNN_DEVICE_PLATFORM_INFO_VERSION_UNDEFINED = 0x7FFFFFFF
enum QnnDevice_ConfigOption_t

This enum defines config options to control QnnDevice_Config_t.

Values:

enumerator QNN_DEVICE_CONFIG_OPTION_CUSTOM = 0

sets backend custom options

enumerator QNN_DEVICE_CONFIG_OPTION_PLATFORM_INFO = 1

select QnnDevice_PlatformInfo_t

enumerator QNN_DEVICE_CONFIG_OPTION_UNDEFINED = 0x7FFFFFFF

Unused, present to ensure 32 bits.

Functions

Qnn_ErrorHandle_t QnnDevice_getPlatformInfo(Qnn_LogHandle_t logger, const QnnDevice_PlatformInfo_t **platformInfo)

A function to get the collection of devices and cores that a QNN backend is able to recognize and communicate with. Memory is owned by the backend and deallocated with a call to QnnDevice_freePlatformInfo().

Parameters

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

  • platformInfo – [out] Information about the platform. Memory for this information is owned and managed by QNN backend.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_DEVICE_ERROR_INVALID_ARGUMENT: platformInfo is NULL

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

  • QNN_DEVICE_ERROR_MEM_ALLOC: failure in allocating memory for platformInfo

  • QNN_DEVICE_ERROR_INVALID_HANDLE: invalid logger

Note

This function may not be supported for offline preparation

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnDevice_freePlatformInfo(Qnn_LogHandle_t logger, const QnnDevice_PlatformInfo_t *platformInfo)

A function to free the memory allocated during QnnDevice_getPlatformInfo()

Parameters

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

  • platformInfo – [in] Information about the platform. Memory for this information is owned and managed by QNN backend.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_DEVICE_ERROR_INVALID_ARGUMENT: platformInfo is NULL

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

  • QNN_DEVICE_ERROR_MEM_ALLOC: failure in de-allocating memory for platformInfo

  • QNN_DEVICE_ERROR_INVALID_HANDLE: invalid logger

Note

This function may not be supported for offline preparation.

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnDevice_getInfrastructure(const QnnDevice_Infrastructure_t *deviceInfra)

Get device hardware infrastructure interface object.

This is optional capability, support is advertised via QnnProperty. If supported, please refer to documentation and/or header file provided by the backend for usage information.

Parameters

deviceInfra – [out] Pointer to infrastructure interface object. The pointer returned is a backend owned memory.

Returns

Error code:

  • QNN_SUCCESS: No error encountered

  • QNN_DEVICE_ERROR_INVALID_HANDLE: device is not a valid handle

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

  • QNN_DEVICE_ERROR_INVALID_ARGUMENT: if deviceInfra is NULL

  • QNN_DEVICE_ERROR_MEM_ALLOC: insufficient memory to return deviceInfra

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnDevice_create(Qnn_LogHandle_t logger, const QnnDevice_Config_t **config, Qnn_DeviceHandle_t *device)

Create a logical device handle to a subset of hardware resources available on the platform.

Parameters

  • logger – [in] A handle to the logger, use NULL handle to disable logging. QnnDevice 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.

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

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_DEVICE_ERROR_INVALID_ARGUMENT: device is NULL

  • QNN_DEVICE_ERROR_INVALID_HANDLE: logger is not a valid handle

  • QNN_DEVICE_ERROR_INVALID_CONFIG: one or more configuration values is invalid

  • QNN_DEVICE_ERROR_MEM_ALLOC: failure in allocating memory when creating device

  • QNN_DEVICE_ERROR_HARDWARE_UNAVAILABLE: requested hardware resources are unavailable

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION: SSR occurence (successful recovery)

  • QNN_COMMON_ERROR_SYSTEM_COMMUNICATION_FATAL: SSR occurence (unsuccessful recovery)

Note

NULL value for config creates a device handle with default configuration. Unless mentioned in backend specific headers, default configuration would enable all the devices and cores present on a platform for which a backend can control.

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnDevice_setConfig(Qnn_DeviceHandle_t device, const QnnDevice_Config_t **config)

A function to set/modify configuration options on an already created device. Backends are not required to support this API.

Parameters

  • device – [in] A device 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_DEVICE_ERROR_INVALID_HANDLE: device is not a valid handle

  • QNN_DEVICE_ERROR_INVALID_ARGUMENT: at least one argument is invalid

  • QNN_DEVICE_ERROR_INVALID_CONFIG: one or more configuration values is invalid

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

  • QNN_DEVICE_ERROR_ASSOCIATED_TO_CONTEXT: device has associated contexts. Free the associations before attempting to change the config.

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnDevice_getInfo(Qnn_DeviceHandle_t device, const QnnDevice_PlatformInfo_t **platformInfo)

A function to get platform info associated with a device handle.

Parameters

  • device – [in] A device handle.

  • platformInfo – [out] Information about the platform. Memory for this information is owned and managed by QNN backend.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_DEVICE_ERROR_INVALID_HANDLE: device is not a valid handle

  • QNN_DEVICE_ERROR_INVALID_ARGUMENT: platformInfo is NULL

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnDevice_free(Qnn_DeviceHandle_t device)

Free the created device and perform any deallocation of the resources allocated during device create.

Parameters

device – [in] A device handle.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_DEVICE_ERROR_INVALID_HANDLE: device is not a valid handle

  • QNN_DEVICE_ERROR_MEM_ALLOC: an error is encountered with de-allocation of associated memory, failure to invalidate handles or other allocated resources

  • QNN_DEVICE_ERROR_ASSOCIATED_TO_CONTEXT: One or more contexts associated with the device handle is not freed

  • QNN_DEVICE_ERROR_UNSUPPORTED_FEATURE: API is not supported

Note

Use corresponding API through QnnInterface_t.

struct QnnDevice_CoreInfoV1_t
#include <QnnDevice.h>

Version 1 of the structure defining per Core info.

Public Members

uint32_t coreId

ID of the enumerated core.

uint32_t coreType

Type of the core, as specified by the backend.

QnnDevice_CoreInfoExtension_t coreInfoExtension

Backend specific extension for core info. Refer to backend headers for the definition.

struct QnnDevice_CoreInfo_t
#include <QnnDevice.h>

Structure defining per core info.

Public Members

QnnDevice_CoreInfoVersion_t version
union unnamed
#include <QnnDevice.h>

Public Members

QnnDevice_CoreInfoV1_t v1

Core info which corresponds to version QNN_DEVICE_CORE_INFO_VERSION_1.

struct QnnDevice_HardwareDeviceInfoV1_t
#include <QnnDevice.h>

Version 1 of the structure defining Hardware Device info.

Public Members

uint32_t deviceId

ID of the device.

uint32_t deviceType

Type of the device.

uint32_t numCores

Number of cores in a device.

QnnDevice_CoreInfo_t *cores

Array of core info structures.

QnnDevice_DeviceInfoExtension_t deviceInfoExtension

Backend specific extension for device info. Refer to backend headers for the definition.

struct QnnDevice_HardwareDeviceInfo_t
#include <QnnDevice.h>

Structure defining hardware device info (typically a SoC or PCIe extension)

Public Members

QnnDevice_HardwareDeviceInfoVersion_t version
union unnamed
#include <QnnDevice.h>

Public Members

QnnDevice_HardwareDeviceInfoV1_t v1

Device info which corresponds to version QNN_DEVICE_HARDWARE_DEVICE_INFO_VERSION_1.

struct QnnDevice_PlatformInfoV1_t
#include <QnnDevice.h>

Version 1 of the structure defining platform info.

Public Members

uint32_t numHwDevices

Number of devices.

QnnDevice_HardwareDeviceInfo_t *hwDevices

Array of device info structures.

struct QnnDevice_PlatformInfo_t
#include <QnnDevice.h>

Structure defining the platform info.

Public Members

QnnDevice_PlatformInfoVersion_t version
union unnamed
#include <QnnDevice.h>

Public Members

QnnDevice_PlatformInfoV1_t v1

Platform info which corresponds to version QNN_DEVICE_PLATFORM_INFO_VERSION_1.

struct QnnDevice_Config_t
#include <QnnDevice.h>

This struct provides device configuration.

Public Members

QnnDevice_ConfigOption_t option
union unnamed
#include <QnnDevice.h>

Public Members

QnnDevice_CustomConfig_t customConfig
QnnDevice_PlatformInfo_t *hardwareInfo