File QnnProfile.h

↰ Parent directory (include/QNN)

Profile component API.

Definition (include/QNN/QnnProfile.h)

Detailed Description

Requires Backend to be initialized. Provides means to profile QNN backends to evaluate performance (memory and timing) of graphs and operations.

Includes

Full File Listing

Profile component API. 

    Requires Backend to be initialized.
    Provides means to profile QNN backends to evaluate performance
    (memory and timing) of graphs and operations.

Defines

QNN_PROFILE_EVENTTYPE_INIT 100

QnnProfile_EventType_t definition to get stats related to creation of context and graphs. If supported, this profile data captures stats starting with the context creation (QnnContext_create) and ending with graph finalize (QnnGraph_finalize). Alternatively, in case of loading a cached context, it captures stats for creating context from the cache (QnnContext_createFromBinary).

Note

init information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

If unit information is not available, the value should be interpreted as time in microseconds.

QNN_PROFILE_EVENTTYPE_FINALIZE 300

QnnProfile_EventType_t definition to get stats related to finalize operation on graphs in a context. If supported, this profile data captures stats for graph finalize (QnnGraph_finalize).

Note

finalize information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

If unit information is not available, the value should be interpreted as time in microseconds.

QNN_PROFILE_EVENTTYPE_EXECUTE 400

QnnProfile_EventType_t definition to get stats related to execution of graphs in a context (QnnGraph_execute or QnnGraph_executeAsync). Basic level might include stats related to execution of entire graphs. In addition, detailed level can include stats related to individual nodes in graphs as sub-events.

Note

execute information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

If unit information is not available, the value should be interpreted as time in microseconds.

QNN_PROFILE_EVENTTYPE_NODE 404

QnnProfile_EventType_t definition to get data related to execution of an operation. This value can be interpreted appropriately in conjunction with the unit.

Note

node specific information is available on QNN_PROFILE_LEVEL_DETAILED level

Note

This is a sub-event of the QNN_PROFILE_EVENTTYPE_EXECUTE event.

QNN_PROFILE_EVENTTYPE_EXECUTE_QUEUE_WAIT 405

QnnProfile_EventType_t definition to get stats related to time spent waiting in a queue when executing a graph.

Note

execute enqueue information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

This is a sub-event of the QNN_PROFILE_EVENTTYPE_EXECUTE event.

QNN_PROFILE_EVENTTYPE_EXECUTE_PREPROCESS 406

QnnProfile_EventType_t definition to get stats related to time spent pre-processing in preparation of executing a graph.

Note

execute preprocess information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

This is a sub-event of the QNN_PROFILE_EVENTTYPE_EXECUTE event.

QNN_PROFILE_EVENTTYPE_EXECUTE_DEVICE 407

QnnProfile_EventType_t definition to get stats related to time spent on-device executing a graph.

Note

execute device information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

This is a sub-event of the QNN_PROFILE_EVENTTYPE_EXECUTE event.

QNN_PROFILE_EVENTTYPE_EXECUTE_POSTPROCESS 408

QnnProfile_EventType_t definition to get stats related to time spent post-processing after execution of a graph.

Note

execute postprocess information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

This is a sub-event of the QNN_PROFILE_EVENTTYPE_EXECUTE event.

QNN_PROFILE_EVENTTYPE_DEINIT 500

QnnProfile_EventType_t definition to get stats related to deinit graphs and free context operation. This profile data captures stats for QnnContext_free.

Note

deinit information maybe available on both QNN_PROFILE_LEVEL_BASIC and QNN_PROFILE_LEVEL_DETAILED levels

Note

If unit information is not available, the value should be interpreted as time in microseconds.

QNN_PROFILE_EVENTTYPE_TRACE 600

QnnProfile_EventType_t definition to get traces related to graph preparation and execution steps. This profile data captures stats for QnnGraph_execute.

Note

trace information is available on QNN_PROFILE_LEVEL_DETAILED level only.

QNN_PROFILE_EVENTTYPE_BACKEND 1000

QnnProfile_EventType_t definition reserved for each back end to define and extend.

Note

The client should consult the backend-specific SDK documentation for information regarding interpretation of unit, value and identifier.

QNN_PROFILE_LEVEL_BASIC 1

Basic QnnProfile_Level_t definition that allows to collect performance metrics for graph finalization and execution stages.

QNN_PROFILE_LEVEL_DETAILED 2

Detailed QnnProfile_Level_t definition that allows to collect performance metrics for each operation in the graph.

QNN_PROFILE_LEVEL_BACKEND 1000

QnnProfile_Level_t definition reserved for each back end to define and extend.

QNN_PROFILE_EVENTUNIT_MICROSEC 1

QnnProfile_EventUnit_t definition to provide profiling measurement as time in microseconds.

QNN_PROFILE_EVENTUNIT_BYTES 2

QnnProfile_EventUnit_t definition to provide profiling measurement as memory in bytes.

QNN_PROFILE_EVENTUNIT_CYCLES 3

QnnProfile_EventUnit_t definition to provide profiling measurement as time in cycles.

QNN_PROFILE_EVENTUNIT_COUNT 4

QnnProfile_EventUnit_t definition to provide profiling measurement as a count.

QNN_PROFILE_EVENTUNIT_OBJECT 5

QnnProfile_EventUnit_t definition to provide profiling measurement as an opaque object.

QNN_PROFILE_EVENTUNIT_NONE 6

QnnProfile_EventUnit_t definition to provide profiling measurement with no unit.

QNN_PROFILE_EVENTUNIT_BACKEND 1000

QnnProfile_EventUnit_t definition reserved for each back end to define and extend.

QNN_PROFILE_EVENT_DATA_INIT

{                                 \

0u,      /*type*/               \

0u,      /*unit*/               \

0u,      /*value*/              \

NULL     /*identifier*/         \

}


QnnProfile_EventData_t initializer macro.

QNN_PROFILE_BACKEND_OPAQUE_OBJECT_INIT   {                                            \     QNN_OPAQUE_OBJECT_INIT

, /*opaqueObject*/   \

NULL                    /*fileName*/       \

}


QnnProfile_BackendOpaqueObject_t initializer macro.

QNN_PROFILE_EXTENDED_EVENT_DATA_V1_INIT

{                                             \

0u,               /*type*/                  \

0u,               /*unit*/                  \

{                                           \

QNN_SCALAR_INIT

/*value*/                 \

},                                          \

0u,               /*timestamp*/             \

NULL              /*identifier*/            \

}


QnnProfile_ExtendedEventDataV1_t initializer macro.

QNN_PROFILE_EXTENDED_EVENT_DATA_INIT   {                                                  \     QNN_PROFILE_DATA_VERSION_1

, /*version*/          \

{                                                \

QNN_PROFILE_EXTENDED_EVENT_DATA_V1_INIT

/*v1*/ \

}                                                \

}


QnnProfile_ExtendedEventData_t initializer macro.

QNN_PROFILE_CONFIG_INIT   {                                                 \     QNN_PROFILE_CONFIG_OPTION_UNDEFINED

, /*option*/ \

{                                               \

NULL /*customConfig*/                         \

}                                               \

}


QnnProfile_Config_t initializer macro.

Typedefs

typedef uint32_t QnnProfile_EventType_t

Backend defined type for a profiled event such as time_taken, time_start, memory.

typedef uint64_t QnnProfile_EventValue_t

Represents a profiled event value.

typedef uint32_t QnnProfile_Level_t

Profile levels supported by each backend.

typedef uint64_t QnnProfile_EventId_t

ID of a profiling event.

typedef uint32_t QnnProfile_EventUnit_t

Unit of measurement of a profiling event.

typedef void *QnnProfile_CustomConfig_t

Profile specific object for custom configuration.

Please refer to documentation provided by the backend for usage information

Enums

enum QnnProfile_Error_t

QNN Profile API result / error codes.

Values:

enumerator QNN_PROFILE_MIN_ERROR = 12000
enumerator QNN_PROFILE_NO_ERROR = 0

Qnn Profile success.

enumerator QNN_PROFILE_ERROR_UNSUPPORTED = QNN_COMMON_ERROR_NOT_SUPPORTED

Backend does not support requested functionality.

enumerator QNN_PROFILE_ERROR_INVALID_ARGUMENT = QNN_COMMON_ERROR_INVALID_ARGUMENT

Invalid function argument.

enumerator QNN_PROFILE_ERROR_MEM_ALLOC = QNN_COMMON_ERROR_MEM_ALLOC

General error relating to memory allocation in Profile API.

enumerator QNN_PROFILE_ERROR_INVALID_HANDLE = 12000 + 0

Invalid/NULL QNN profile handle.

enumerator QNN_PROFILE_ERROR_HANDLE_IN_USE = 12000 + 1

Attempt to free or reconfigure a profile handle that is in-use.

enumerator QNN_PROFILE_ERROR_INCOMPATIBLE_EVENT = 12000 + 2

Event is incompatible with API.

enumerator QNN_PROFILE_MAX_ERROR = 12999
enumerator QNN_PROFILE_ERROR_UNDEFINED = 0x7FFFFFFF
enum QnnProfile_ExtendedEventDataVersion_t

Values:

enumerator QNN_PROFILE_DATA_VERSION_1 = 1
enumerator QNN_PROFILE_DATA_VERSION_UNDEFINED = 0x7FFFFFFF
enum QnnProfile_ConfigOption_t

This enum defines profile config options.

Values:

enumerator QNN_PROFILE_CONFIG_OPTION_CUSTOM = 0

Sets backend custom configs, see backend specific documentation.

enumerator QNN_PROFILE_CONFIG_OPTION_MAX_EVENTS = 1

This config sets the maximum number of profiling events that can be stored in the profile handle. Once the maximum number of events is reached, no more events will be stored. The absolute maximum number of events is subject to a maximum limit determined by the backend and available system resources. The default maximum number of events is backend-specific, refer to SDK documentation.

enumerator QNN_PROFILE_CONFIG_OPTION_ENABLE_OPTRACE = 2

Set optrace profiling support via enableOptrace flag. Please note that the trace information is available on QNN_PROFILE_LEVEL_DETAILED level only.

enumerator QNN_PROFILE_CONFIG_OPTION_UNDEFINED = 0x7FFFFFFF

Value selected to ensure 32 bits.

Functions

Qnn_ErrorHandle_t QnnProfile_create(Qnn_BackendHandle_t backend, QnnProfile_Level_t level, Qnn_ProfileHandle_t *profile)

Create a handle to a profile object.

Parameters

  • backend – [in] A backend handle.

  • level – [in] Granularity level at which the profile should collect events.

  • profile – [out] A profile handle.

Returns

Error code

  • QNN_SUCCESS: No error encountered

  • QNN_PROFILE_ERROR_INVALID_ARGUMENT: profile is NULL or level is invalid.

  • QNN_PROFILE_ERROR_UNSUPPORTED: Profiling is unsupported on a backend.

  • QNN_PROFILE_ERROR_MEM_ALLOC: Error in allocating memory when creating profile handle

  • QNN_PROFILE_ERROR_INVALID_HANDLE: backend is not a valid handle

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnProfile_setConfig(Qnn_ProfileHandle_t profileHandle, const QnnProfile_Config_t **config)

A function to set/modify configuration options on an already created profile handle.

Parameters

  • profileHandle – [in] A profile 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. If a backend cannot support all provided configs it will fail.

Returns

Error code:

  • QNN_SUCCESS: no error is encountered

  • QNN_PROFILE_ERROR_INVALID_HANDLE: profileHandle is not a valid handle

  • QNN_PROFILE_ERROR_INVALID_ARGUMENT: at least one config option is invalid

  • QNN_PROFILE_ERROR_HANDLE_IN_USE: when attempting to reconfigure a profile handle

  • QNN_PROFILE_ERROR_UNSUPPORTED: Config option is not supported

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnProfile_getEvents(Qnn_ProfileHandle_t profile, const QnnProfile_EventId_t **profileEventIds, uint32_t *numEvents)

Get Qnn profile events collected on the profile handle.

Parameters

  • profile – [in] A profile handle.

  • profileEventIds – [out] Returns handles to Qnn profile events collected on this profile object.

  • numEvents – [out] Number of profile events.

Returns

Error code

  • QNN_SUCCESS: No error encountered

  • QNN_PROFILE_ERROR_INVALID_ARGUMENT: profileEventIds or numEvents is NULL.

  • QNN_PROFILE_ERROR_INVALID_HANDLE: profile is not a valid handle.

  • QNN_PROFILE_ERROR_MEM_ALLOC: error related to memory allocation

Note

profileEvents parameter: profile event memory is associated with the profile object and released on profile object release in QnnProfile_free().

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnProfile_getSubEvents(QnnProfile_EventId_t eventId, const QnnProfile_EventId_t **subEventIds, uint32_t *numSubEvents)

Get Qnn profile event handles nested within this Qnn profile event handle.

Parameters

  • eventId – [in] QNN Profile event whose sub events are being queried.

  • subEventIds – [out] Nested profile events on this event.

  • numSubEvents – [out] Number of profile events.

Returns

Error code

  • QNN_SUCCESS: No error encountered

  • QNN_PROFILE_ERROR_INVALID_ARGUMENT: subEventIds or numSubEvents is NULL.

  • QNN_PROFILE_ERROR_INVALID_HANDLE: eventId does not identify a valid event.

  • QNN_PROFILE_ERROR_MEM_ALLOC: error related to memory allocation

Note

subEventIds parameter: profile event memory is associated with the profile object and released on profile object release in QnnProfile_free().

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnProfile_getEventData(QnnProfile_EventId_t eventId, QnnProfile_EventData_t *eventData)

Query the data associated with this profile event.

Parameters

  • eventId – [in] Qnn profile event being queried.

  • eventData – [out] Event data associated to this event.

Returns

Error code

  • QNN_SUCCESS: No error encountered

  • QNN_PROFILE_ERROR_UNSUPPORTED: API not supported.

  • QNN_PROFILE_ERROR_INCOMPATIBLE_EVENT: eventData is incompatible with the API. Use QnnProfile_getExtendedEventData instead.

  • QNN_PROFILE_ERROR_INVALID_ARGUMENT: eventData is NULL.

  • QNN_PROFILE_ERROR_INVALID_HANDLE: eventId does not identify a valid event.

  • QNN_PROFILE_ERROR_MEM_ALLOC: error related to memory allocation

Note

eventData parameter: eventData memory is associated with the profile object and released on profile object release in QnnProfile_free().

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnProfile_getExtendedEventData(QnnProfile_EventId_t eventId, QnnProfile_ExtendedEventData_t *eventData)

Query the data associated with this profile extended event.

Parameters

  • eventId – [in] Qnn profile extended event being queried.

  • eventData – [out] Event data associated to this extended event.

Returns

Error code

  • QNN_SUCCESS: No error encountered

  • QNN_PROFILE_ERROR_UNSUPPORTED: API not supported.

  • QNN_PROFILE_ERROR_INVALID_ARGUMENT: eventData is NULL.

  • QNN_PROFILE_ERROR_INVALID_HANDLE: eventId does not identify a valid event.

  • QNN_PROFILE_ERROR_MEM_ALLOC: error related to memory allocation

Note

eventData parameter: eventData memory is associated with the profile object and released on profile object release in QnnProfile_free().

Note

Use corresponding API through QnnInterface_t.

Qnn_ErrorHandle_t QnnProfile_free(Qnn_ProfileHandle_t profile)

Free memory associated with the profile handle. All associated QnnProfile_EventId_t event handles are implicitly freed.

Parameters

profile – [in] Handle to be freed.

Returns

Error code

  • QNN_SUCCESS: No error encountered

  • QNN_PROFILE_ERROR_INVALID_HANDLE: profile is not a valid handle.

  • QNN_PROFILE_ERROR_MEM_ALLOC: error related to memory de-allocation

  • QNN_PROFILE_ERROR_HANDLE_IN_USE: profile is in-use and cannot be freed.

Note

Releasing the profile handle invalidates the memory returned via calls on this handle such as QnnProfile_getEvents(), QnnProfile_getSubEvents(), QnnProfile_getEventData(), QnnProfile_getExtendedEventData(), etc.

Note

The profile handle cannot be freed when it is bound to another API component or in use by an API call.

Note

Use corresponding API through QnnInterface_t.

struct QnnProfile_EventData_t
#include <QnnProfile.h>

This struct provides event information.

Public Members

QnnProfile_EventType_t type

Type of event.

QnnProfile_EventUnit_t unit

Unit of measurement for the event.

QnnProfile_EventValue_t value

Value for the event.

const char *identifier

Identifier for the event.

struct QnnProfile_BackendOpaqueObject_t
#include <QnnProfile.h>

A struct which defines a backend opaque object.

Public Members

Qnn_OpaqueObject_t opaqueObject

Opaque object.

const char *fileName

Name of the file. Can be NULL.

struct QnnProfile_ExtendedEventDataV1_t
#include <QnnProfile.h>

This struct provides extended event information.

Public Members

QnnProfile_EventType_t type

Type of the event.

QnnProfile_EventUnit_t unit

Unit of measurement for the event.

uint64_t timestamp

Timestamp for the event, represented in microsecond unit.

const char *identifier

Identifier for the event. Can be NULL.

union unnamed
#include <QnnProfile.h>

Event data The field used is dependent on the event unit.

Public Members

Qnn_Scalar_t value

Used for MICROSEC, BYTES, CYCLES, COUNT.

QnnProfile_BackendOpaqueObject_t backendOpaqueObject

Used for OBJECT.

struct QnnProfile_ExtendedEventData_t
#include <QnnProfile.h>

Public Members

QnnProfile_ExtendedEventDataVersion_t version
union unnamed
#include <QnnProfile.h>

Public Members

QnnProfile_ExtendedEventDataV1_t v1
struct QnnProfile_Config_t
#include <QnnProfile.h>

This struct provides profile configuration.

Public Members

QnnProfile_ConfigOption_t option
union unnamed
#include <QnnProfile.h>

Public Members

QnnProfile_CustomConfig_t customConfig
uint64_t numMaxEvents
uint8_t enableOptrace