Info Log Decoder Context - Extensions

oneAPI Level Zero Specification - Version 1.21.26

Info Log Decoder Context - Extension Functions

zesInfoLogDecoderContextCreateExt

Added in version 1.21

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogDecoderContextCreateExt(zes_info_log_handle_t hInfoLog, zes_info_log_decoder_context_handle_t *phDecoderContext)

Create a decoder context for an info log.

• A decoder context decodes the records returned by zesInfoLogInstanceReadWithMetadataExt or by zesInfoLogInstancePeekWithMetadataExt into named fields, which the application reads one at a time using zesInfoLogDecoderContextReadFieldExt.

• Any number of decoder contexts may exist for one info log.

• The application may call this function from simultaneous threads.

Parameters:

• hInfoLog – [in] handle of the info log that the records are read from

• phDecoderContext – [out] handle of the decoder context that was created.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hInfoLog

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phDecoderContext

zesInfoLogDecoderContextGetFieldInfoExt

Added in version 1.21

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogDecoderContextGetFieldInfoExt(zes_info_log_decoder_context_handle_t hDecoderContext, uint32_t *pCount, zes_info_log_decodable_field_info_ext_t *pFieldInfos)

Get the fields that a decoder context can decode from an info log record.

• The application should first call this function with pCount pointing to a value of zero to retrieve the number of fields that can be decoded.

• A call in which *pCount is greater than zero and pFieldInfos is nullptr shall report the number of fields and shall not write any descriptor, as a call with a count of zero does.

• The application may call this function from simultaneous threads.

Parameters:

• hDecoderContext – [in] handle of the decoder context

• pCount – [in,out] pointer to the number of fields that can be decoded. if count is zero, then the driver shall update the value with the total number of fields that can be decoded and shall not return any descriptor. if count is greater than the number of fields that can be decoded, then the driver shall update the value with the correct number of fields.

• pFieldInfos – [in,out][optional][range(0, *pCount)] array of field descriptions, one element per field. if count is less than the number of fields that can be decoded, then the driver shall only retrieve that number of descriptors.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDecoderContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zesInfoLogDecoderContextDecodeStartExt

Added in version 1.21

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogDecoderContextDecodeStartExt(zes_info_log_decoder_context_handle_t hDecoderContext, uint32_t size, const uint8_t *pBuffer, uint32_t recordCount, const zes_info_log_metadata_ext_t *pDescriptors)

Start decoding info log records in a decoder context.

• The application must not call this function from simultaneous threads with the same decoder context handle.

• The application may call this function from simultaneous threads with different decoder context handles.

Parameters:

• hDecoderContext – [in] handle of the decoder context

• size – [in] size, in bytes, of the record data in pBuffer, as returned in *pSize by the read or peek call

• pBuffer – [in][optional][range(0, size)] the record data, as returned in pBuffer by the read or peek call

• recordCount – [in] number of records in the batch, as returned in *pRecordCount by the read or peek call

• pDescriptors – [in][optional][range(0, recordCount)] array of metadata describing each record, as returned in pDescriptors by the read or peek call

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDecoderContext

zesInfoLogDecoderContextReadFieldExt

Added in version 1.21

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogDecoderContextReadFieldExt(zes_info_log_decoder_context_handle_t hDecoderContext, uint32_t fieldId, uint32_t recordId, void *pOutBuffer, size_t bufferLen, size_t *pBytesCopied)

Read field values of one record that a decoder context is decoding.

• The application must not call this function from simultaneous threads with the same decoder context handle.

• The application may call this function from simultaneous threads with different decoder context handles.

Parameters:

• hDecoderContext – [in] handle of the decoder context, which must be decoding a batch

• fieldId – [in] identifier of the field to read, as reported in fieldId of zes_info_log_decodable_field_info_ext_t

• recordId – [in] index of the record in the pDescriptors that was passed to zesInfoLogDecoderContextDecodeStartExt

• pOutBuffer – [in,out][range(0, bufferLen)] buffer that will contain the value of the field

• bufferLen – [in] size, in bytes, of pOutBuffer

• pBytesCopied – [out] pointer to the number of bytes written to pOutBuffer. the driver shall update the value with zero when the record does not carry the field.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDecoderContext

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pOutBuffer

  • nullptr == pBytesCopied

zesInfoLogDecoderContextDecodeStopExt

Added in version 1.21

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogDecoderContextDecodeStopExt(zes_info_log_decoder_context_handle_t hDecoderContext)

Stop decoding of info log records that a decoder context is decoding.

• The application must not call this function from simultaneous threads with the same decoder context handle.

• The application may call this function from simultaneous threads with different decoder context handles.

Parameters:

hDecoderContext – [in] handle of the decoder context

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDecoderContext

zesInfoLogDecoderContextDeleteExt

Added in version 1.21

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogDecoderContextDeleteExt(zes_info_log_handle_t hInfoLog, zes_info_log_decoder_context_handle_t hDecoderContext)

Delete a decoder context of an info log.

• The application must ensure that no other function is using the handle when calling this function.

• The application must not call this function from simultaneous threads with the same handle.

• The implementation of this function must be thread-safe.

Parameters:

• hInfoLog – [in] handle of the info log that the decoder context was created from

• hDecoderContext – [in][release] handle of the decoder context to delete

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hInfoLog

  • nullptr == hDecoderContext

Info Log Decoder Context - Extension Enums

zes_info_log_field_type_ext_t

Added in version 1.21

Member of: zes_info_log_decodable_field_info_ext_t

enum zes_info_log_field_type_ext_t

Data types of a field decoded from an info log record.

Values:

enumerator ZES_INFO_LOG_FIELD_TYPE_EXT_UINT32

The value of the field is a uint32_t.

enumerator ZES_INFO_LOG_FIELD_TYPE_EXT_INT64

The value of the field is an int64_t.

enumerator ZES_INFO_LOG_FIELD_TYPE_EXT_DOUBLE

The value of the field is a double.

enumerator ZES_INFO_LOG_FIELD_TYPE_EXT_STRING

The value of the field is a null terminated array of char.

enumerator ZES_INFO_LOG_FIELD_TYPE_EXT_RAW_BYTES

The value of the field is an array of uninterpreted bytes.

enumerator ZES_INFO_LOG_FIELD_TYPE_EXT_FORCE_UINT32

Value marking end of ZES_INFO_LOG_FIELD_TYPE_EXT_* ENUMs.

Info Log Decoder Context - Extension Structures

zes_info_log_decodable_field_info_ext_t

Added in version 1.21

Used by: zesInfoLogDecoderContextGetFieldInfoExt

struct zes_info_log_decodable_field_info_ext_t

Description of one field that a decoder context can decode from an info log record.

• An array of these structures is returned by zesInfoLogDecoderContextGetFieldInfoExt, one element per field.

• The fields that are reported are a property of the format of the info log, reported in infoLogFormat of zes_info_log_ext_properties_t, and not of a batch of records. Whether a given record carries a given field is reported per record by zesInfoLogDecoderContextReadFieldExt.

• The application must locate a field by name, and must then use the fieldId, type and requiredBytes that are reported for that name.

Public Members

zes_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

char desc[ZES_INFO_LOG_FIELD_DESC_SIZE]

[out] human readable description of the field (NULL terminated string value).

char name[ZES_STRING_PROPERTY_SIZE]

[out] name of the field (NULL terminated string value).

uint32_t fieldId

[out] identifier of the field, to be passed to zesInfoLogDecoderContextReadFieldExt.

zes_info_log_field_type_ext_t type

[out] data type of the value of the field.

size_t requiredBytes

[out] number of bytes that the application must provide to zesInfoLogDecoderContextReadFieldExt to read this field. For ZES_INFO_LOG_FIELD_TYPE_EXT_STRING this value includes the null terminator.

size_t elementCount

[out] number of elements of the data type that the field holds.

char versionString[ZES_STRING_PROPERTY_SIZE]

[out] version of this extension in which the field was first reported.