Info Log - Extensions

oneAPI Level Zero Specification - Version 1.19.12

Info Log - Extension Functions

zesInfoLogGetPropertiesExt

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogGetPropertiesExt(zes_info_log_handle_t hInfoLog, zes_info_log_ext_properties_t *pProperties)

Get info log properties.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hInfoLog – [in] handle of the info log

• pProperties – [in,out] Will contain the properties of the info log.

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 == pProperties

zesInfoLogCreateInstanceExt

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogCreateInstanceExt(zes_info_log_handle_t hInfoLog, const char *pInstanceName, zes_info_log_instance_ext_desc_t *pDesc, zes_info_log_instance_handle_t *phInfoLogInstance)

Create a collection instance for an info log.

• Creating a collection instance starts the collection of records into a buffer owned by that instance.

• Records collected by an instance are retrieved using zesInfoLogInstanceReadWithMetadataExt, or inspected without being consumed using zesInfoLogInstancePeekWithMetadataExt.

• Collection continues until the instance is deleted using zesInfoLogInstanceDeleteExt, which also releases the resources allocated by the instance during create operation.

• A named collection instance collects records into a buffer that is not shared with other collection instances. Named collection instances are only supported when isNamedInstanceSupported of zes_info_log_ext_properties_t is true.

• If pInstanceName is nullptr, then records are collected from the default/global buffer of the info log, which may be shared with other consumers and can have data from different sources.

• The application must not call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hInfoLog – [in] handle of the info log

• pInstanceName – [in][optional] name of the collection instance to create. if nullptr, then the default buffer of the info log shall be used.

• pDesc – [in,out] pointer to the descriptor of the collection instance to create.

• phInfoLogInstance – [out] handle of the collection instance 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_DEPENDENCY_UNAVAILABLE

• 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 == pDesc

  • nullptr == phInfoLogInstance

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

  • pInstanceName != nullptr and isNamedInstanceSupported of zes_info_log_ext_properties_t is false.

• ZE_RESULT_ERROR_HANDLE_OBJECT_IN_USE

  • A collection instance was already created with the same name.

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to collect info log records.

Info Log - Extension Enums

zes_info_log_type_ext_t

Added in version 1.19

enum zes_info_log_type_ext_t

Info log types.

Values:

enumerator ZES_INFO_LOG_TYPE_EXT_DEVICE

Log of device reported errors and other device reported information.

enumerator ZES_INFO_LOG_TYPE_EXT_FORCE_UINT32

Value marking end of ZES_INFO_LOG_TYPE_EXT_* ENUMs.

zes_info_log_format_ext_t

Added in version 1.19

enum zes_info_log_format_ext_t

Info log record formats.

Values:

enumerator ZES_INFO_LOG_FORMAT_EXT_CPER

Each record is a UEFI Common Platform Error Record (CPER). The application is responsible for decoding the record contents.

enumerator ZES_INFO_LOG_FORMAT_EXT_FORCE_UINT32

Value marking end of ZES_INFO_LOG_FORMAT_EXT_* ENUMs.

zes_info_log_record_type_ext_t

Added in version 1.19

enum zes_info_log_record_type_ext_t

Info log record types.

Values:

enumerator ZES_INFO_LOG_RECORD_TYPE_EXT_UNKNOWN

The type of the record could not be determined.

enumerator ZES_INFO_LOG_RECORD_TYPE_EXT_INFORMATIONAL

The record does not report an error.

enumerator ZES_INFO_LOG_RECORD_TYPE_EXT_ERROR_CORRECTED

The record reports an error that was corrected by the device.

enumerator ZES_INFO_LOG_RECORD_TYPE_EXT_ERROR_RECOVERABLE

The record reports an error that was not corrected by the device and that is not fatal.

enumerator ZES_INFO_LOG_RECORD_TYPE_EXT_ERROR_FATAL

The record reports an error that was not corrected by the device and that is fatal.

enumerator ZES_INFO_LOG_RECORD_TYPE_EXT_FORCE_UINT32

Value marking end of ZES_INFO_LOG_RECORD_TYPE_EXT_* ENUMs.

Info Log - Extension Structures

zes_info_log_ext_properties_t

Added in version 1.19

struct zes_info_log_ext_properties_t

Info log properties.

• This structure is returned by zesInfoLogGetPropertiesExt

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).

zes_info_log_type_ext_t infoLogType

[out] Type of the information carried by this info log.

zes_info_log_format_ext_t infoLogFormat

[out] Format of the records returned by this info log.

ze_bool_t isNamedInstanceSupported

[out] Indicates whether named collection instances are supported for this info log. If false, then zesInfoLogCreateInstanceExt must be called with pInstanceName set to nullptr.

ze_bool_t isPeekDataSupported

[out] Indicates whether the records of this info log can be read without being consumed. If false, then zesInfoLogInstancePeekWithMetadataExt shall return ZE_RESULT_ERROR_UNSUPPORTED_FEATURE.

zes_info_log_instance_ext_desc_t

Added in version 1.19

struct zes_info_log_instance_ext_desc_t

Info log collection instance descriptor.

• This structure is passed to zesInfoLogCreateInstanceExt to configure the collection instance.

• Each member is optional. If a member is nullptr, then the driver shall use its default value for that setting.

• On input, each non-null member points to the value requested by the application. On output, the driver shall update the pointed-to value with the value that was actually applied, which may be rounded to the closest value the driver supports.

Public Members

zes_structure_type_t stype

[in] type of this structure

const void *pNext

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

uint32_t *pBufferSizeInKb

[in,out][optional] pointer to the size, in kilobytes, of the buffer used to collect records. if nullptr, then the driver shall use its default buffer size. if *pBufferSizeInKb == 0, then implementation shall update pBufferSizeInKb with the default buffer size.

zes_info_log_metadata_ext_t

Added in version 1.19

struct zes_info_log_metadata_ext_t

Metadata describing a single info log record.

• An array of these structures is returned by zesInfoLogInstanceReadWithMetadataExt and by zesInfoLogInstancePeekWithMetadataExt, one element per record.

• A record is located within the data buffer returned by those functions using offset and lengthOfData.

• recordType is derived by the driver from the contents of the record. The record itself is the authoritative source of this information, and takes precedence if the two disagree.

• For an info log whose format is ZES_INFO_LOG_FORMAT_EXT_CPER, recordType reflects the severity reported in the header of the record. An individual section of that record may report a higher severity than the header does.

• The application must treat a value of recordType that it does not recognize as ZES_INFO_LOG_RECORD_TYPE_EXT_UNKNOWN. The numeric values of zes_info_log_record_type_ext_t do not express an order of severity and must not be compared for magnitude.

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).

zes_pci_address_t address

[out] PCI address of the device that generated the record. A value of 0 for domain, bus, device, and function indicates that the PCI address could not be determined.

zes_uuid_t uuid

[out] universal unique identifier of the device that generated the record. A value of 0 indicates that the UUID could not be determined.

uint64_t timestamp

[out] Time when the record was generated, in nanoseconds. The reference point of this timestamp is implementation specific and is only guaranteed to be consistent across records returned by the same info log. A value of 0 indicates that the timestamp could not be determined.

uint32_t lengthOfData

[out] Length of the record, in bytes.

uint32_t offset

[out] Byte offset of the record from the start of the returned data buffer.

zes_info_log_record_type_ext_t recordType

[out] Type of the information reported by the record. ZES_INFO_LOG_RECORD_TYPE_EXT_UNKNOWN indicates that the type could not be determined.

zes_info_log_read_status_ext_t

Added in version 1.19

struct zes_info_log_read_status_ext_t

Status of a read from an info log collection instance.

• This structure is optionally returned by zesInfoLogInstanceReadWithMetadataExt and by zesInfoLogInstancePeekWithMetadataExt.

• consumedDataSize reports the progress made through the data held by the collection instance, which is not related to the amount of record data returned by the call.

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).

int64_t droppedRecordCount

[out] Number of records that were dropped because the collection buffer overflowed. A value of -1 indicates that one or more records were dropped and that their number could not be determined. The application must check whether zesInfoLogInstanceReadWithMetadataExt or zesInfoLogInstancePeekWithMetadataExt returned ZE_RESULT_WARNING_DROPPED_DATA before inspecting droppedRecordCount, since a value of 0 is otherwise ambiguous between no records dropped and the status not having been reported.

uint64_t consumedDataSize

[out] Number of bytes that this call read out of the data held by the collection instance. This value counts all of the data that was searched, including data that does not belong to a record, and is therefore not related to the size of the record data returned by the call. For zesInfoLogInstanceReadWithMetadataExt, this data is consumed and shall not be searched again by a subsequent call. If consumedDataSize = 0, then zesInfoLogInstanceReadWithMetadataExt did not consume any data, similar to zesInfoLogInstancePeekWithMetadataExt.

ze_bool_t hasDataToRead

[out] Indicates whether the collection instance holds records that were not returned by this call. This is true when the call stopped before all records were examined, for example because timeout elapsed, because pBuffer or pDescriptors was too small to hold all of the records that were found, or because the next record available was larger than *pSize. This value is a hint. Records may be collected, and for zesInfoLogInstanceReadWithMetadataExt consumed, after this function returns.