Info Log Instance - Extensions

Info Log Instance - Extensions#

oneAPI Level Zero Specification - Version 1.19.12

Info Log Instance - Extension Functions#

zesInfoLogInstanceReadWithMetadataExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogInstanceReadWithMetadataExt(zes_info_log_instance_handle_t hInfoLogInstance, uint64_t timeout, uint32_t *pSize, uint8_t *pBuffer, uint32_t *pRecordCount, zes_info_log_metadata_ext_t *pDescriptors, zes_info_log_read_status_ext_t *pReadStatus)#

Read collected info log records and their metadata.

  • A call in which *pSize is zero or *pRecordCount is zero on input is a query call. A query call reports the total size, in bytes, of the record data and the total number of records that were found, does not write to pBuffer or pDescriptors, and does not consume any record. pBuffer and pDescriptors may be nullptr on a query call and are otherwise ignored by it.

  • The application can optionally make a query call first to determine the size of the buffer and the number of descriptors it must provide.

  • Records are consumed as they are returned. A record returned by one call will not be returned again by a subsequent call.

  • zesInfoLogInstancePeekWithMetadataExt returns the same records without consuming them.

  • This function searches the data held by the collection instance for records. The amount of data that must be searched is not related to the amount of record data returned, because the collection instance may hold a large amount of data that contains no record. timeout bounds the search and applies to the query call as well.

  • hasDataToRead in zes_info_log_read_status_ext_t reports whether records remain, and is the value the application should use to decide whether to call this function again.

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

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

Parameters:

  • hInfoLogInstance – [in] handle of the info log collection instance

  • timeout – [in] maximum time, in milliseconds, that this function may spend searching the collection instance for records. if zero, then the function shall return immediately without searching. if UINT64_MAX, then the function shall not return until it has searched all of the data held by the collection instance. when this time elapses, the function shall return ZE_RESULT_SUCCESS with the records it has found so far, which may be none. due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

  • pSize – [in,out] pointer to the size, in bytes, of the record data. on input, the value is the size of pBuffer. if the value is zero, or if *pRecordCount is zero, then this is a query call: the driver shall update the value with the total size of the record data that was found and shall not consume any record. otherwise, on output the driver shall update the value with the size of the record data written to pBuffer.

  • pBuffer – [in,out][optional][range(0, *pSize)] buffer that will contain the record data. the driver shall not write to this buffer on a query call, and the application may pass nullptr for such a call.

  • pRecordCount – [in,out] pointer to the number of records. on input, the value is the number of elements in pDescriptors. if the value is zero, or if *pSize is zero, then this is a query call: the driver shall update the value with the total number of records that were found and shall not consume any record. otherwise, on output the driver shall update the value with the number of records written to pDescriptors.

  • pDescriptors – [in,out][optional][range(0, *pRecordCount)] array of metadata describing each record written to pBuffer. the driver shall not write to this array on a query call, and the application may pass nullptr for such a call. the application must initialize the stype member of each element in the array.

  • pReadStatus – [in,out][optional] pointer to a structure that will contain the status of this call. if nullptr, then the driver shall not report the status of this call, and the application cannot determine whether records were dropped or whether records remain available. the application must initialize the stype member.

Returns:

zesInfoLogInstancePeekWithMetadataExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogInstancePeekWithMetadataExt(zes_info_log_instance_handle_t hInfoLogInstance, uint64_t timeout, uint32_t *pSize, uint8_t *pBuffer, uint32_t *pRecordCount, zes_info_log_metadata_ext_t *pDescriptors, zes_info_log_read_status_ext_t *pReadStatus)#

Read collected info log records and their metadata without consuming them.

  • This function is equivalent to zesInfoLogInstanceReadWithMetadataExt, except that the records it returns are not consumed and remain available to subsequent calls to either function.

  • Reading records without consuming them is only supported when isPeekDataSupported of zes_info_log_ext_properties_t is true.

  • As with zesInfoLogInstanceReadWithMetadataExt, a call in which *pSize is zero or *pRecordCount is zero on input is a query call, which reports the total size, in bytes, of the record data and the total number of records that were found without writing to pBuffer or pDescriptors.

  • The application should then call this function with *pSize and *pRecordCount both non-zero to inspect the records that are available.

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

  • The application must not call this function and zesInfoLogInstanceReadWithMetadataExt simultaneously with the same handle.

Parameters:

  • hInfoLogInstance – [in] handle of the info log collection instance

  • timeout – [in] maximum time, in milliseconds, that this function may spend searching the collection instance for records. if zero, then the function shall return immediately without searching. if UINT64_MAX, then the function shall not return until it has searched all of the data held by the collection instance. when this time elapses, the function shall return ZE_RESULT_SUCCESS with the records it has found so far, which may be none. due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

  • pSize – [in,out] pointer to the size, in bytes, of the record data. on input, the value is the size of pBuffer. if the value is zero, or if *pRecordCount is zero, then this is a query call: the driver shall update the value with the total size of the record data that was found. otherwise, on output the driver shall update the value with the size of the record data written to pBuffer.

  • pBuffer – [in,out][optional][range(0, *pSize)] buffer that will contain the record data. the driver shall not write to this buffer on a query call, and the application may pass nullptr for such a call.

  • pRecordCount – [in,out] pointer to the number of records. on input, the value is the number of elements in pDescriptors. if the value is zero, or if *pSize is zero, then this is a query call: the driver shall update the value with the total number of records that were found. otherwise, on output the driver shall update the value with the number of records written to pDescriptors.

  • pDescriptors – [in,out][optional][range(0, *pRecordCount)] array of metadata describing each record written to pBuffer. the driver shall not write to this array on a query call, and the application may pass nullptr for such a call. the application must initialize the stype member of each element in the array.

  • pReadStatus – [in,out][optional] pointer to a structure that will contain the status of this call. if nullptr, then the driver shall not report the status of this call, and the application cannot determine whether records were dropped or whether records remain available. the application must initialize the stype member.

Returns:

zesInfoLogInstanceDeleteExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesInfoLogInstanceDeleteExt(zes_info_log_instance_handle_t hInfoLogInstance)#

Delete a collection instance of an info log.

  • Deleting a collection instance stops the collection of records into that instance and releases the resources used by the instance.

  • 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:

hInfoLogInstance – [in][release] handle of the info log collection instance to delete

Returns:

In this class