Debug

Contents

Debug#

oneAPI Level Zero Specification - Version 1.18.31

Debug Functions#

zetDebugAttach#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugAttach(zet_device_handle_t hDevice, const zet_debug_config_t *config, zet_debug_session_handle_t *phDebug)#

Attach to a device.

Parameters:

  • hDevice – [in] device handle

  • config – [in] the debug configuration

  • phDebug – [out] debug session handle

Returns:

zetDebugDetach#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugDetach(zet_debug_session_handle_t hDebug)#

Close a debug session.

Parameters:

hDebug – [in][release] debug session handle

Returns:

zetDebugReadEvent#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadEvent(zet_debug_session_handle_t hDebug, uint64_t timeout, zet_debug_event_t *event)#

Read the topmost debug event.

Parameters:

  • hDebug – [in] debug session handle

  • timeout – [in] if non-zero, then indicates the maximum time (in milliseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then immediately returns the status of the event; if UINT64_MAX, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

  • event – [in,out] a pointer to a zet_debug_event_t.

Returns:

zetDebugAcknowledgeEvent#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugAcknowledgeEvent(zet_debug_session_handle_t hDebug, const zet_debug_event_t *event)#

Acknowledge a debug event.

Parameters:

  • hDebug – [in] debug session handle

  • event – [in] a pointer to a zet_debug_event_t.

Returns:

zetDebugInterrupt#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugInterrupt(zet_debug_session_handle_t hDebug, ze_device_thread_t thread)#

Interrupt device threads.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread to interrupt

Returns:

zetDebugResume#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugResume(zet_debug_session_handle_t hDebug, ze_device_thread_t thread)#

Resume device threads.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread to resume

Returns:

zetDebugReadMemory#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadMemory(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, const zet_debug_memory_space_desc_t *desc, size_t size, void *buffer)#

Read memory.

  • The thread identifier ‘all’ can be used for accessing the default memory space, e.g. for setting breakpoints.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier.

  • desc – [in] memory space descriptor

  • size – [in] the number of bytes to read

  • buffer – [in,out] a buffer to hold a copy of the memory

Returns:

zetDebugWriteMemory#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugWriteMemory(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, const zet_debug_memory_space_desc_t *desc, size_t size, const void *buffer)#

Write memory.

  • The thread identifier ‘all’ can be used for accessing the default memory space, e.g. for setting breakpoints.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier.

  • desc – [in] memory space descriptor

  • size – [in] the number of bytes to write

  • buffer – [in] a buffer holding the pattern to write

Returns:

zetDebugGetRegisterSetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugGetRegisterSetProperties(zet_device_handle_t hDevice, uint32_t *pCount, zet_debug_regset_properties_t *pRegisterSetProperties)#

Retrieves debug register set properties.

Parameters:

  • hDevice – [in] device handle

  • pCount – [in,out] pointer to the number of register set properties. if count is zero, then the driver shall update the value with the total number of register set properties available. if count is greater than the number of register set properties available, then the driver shall update the value with the correct number of registry set properties available.

  • pRegisterSetProperties – [in,out][optional][range(0, *pCount)] array of query results for register set properties. if count is less than the number of register set properties available, then driver shall only retrieve that number of register set properties.

Returns:

zetDebugReadRegisters#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugReadRegisters(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, uint32_t type, uint32_t start, uint32_t count, void *pRegisterValues)#

Read register state.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier

  • type – [in] register set type

  • start – [in] the starting offset into the register state area; must be less than the count member of zet_debug_regset_properties_t for the type

  • count – [in] the number of registers to read; start+count must be less than or equal to the count member of zet_debug_regset_properties_t for the type

  • pRegisterValues – [in,out][optional][range(0, count)] buffer of register values

Returns:

zetDebugWriteRegisters#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugWriteRegisters(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, uint32_t type, uint32_t start, uint32_t count, void *pRegisterValues)#

Write register state.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier

  • type – [in] register set type

  • start – [in] the starting offset into the register state area; must be less than the count member of zet_debug_regset_properties_t for the type

  • count – [in] the number of registers to write; start+count must be less than or equal to the count member of zet_debug_regset_properties_t for the type

  • pRegisterValues – [in,out][optional][range(0, count)] buffer of register values

Returns:

zetDebugGetThreadRegisterSetProperties#

Added in version 1.5

ZE_APIEXPORT ze_result_t ZE_APICALL zetDebugGetThreadRegisterSetProperties(zet_debug_session_handle_t hDebug, ze_device_thread_t thread, uint32_t *pCount, zet_debug_regset_properties_t *pRegisterSetProperties)#

Retrieves debug register set properties for a given thread.

Parameters:

  • hDebug – [in] debug session handle

  • thread – [in] the thread identifier specifying a single stopped thread

  • pCount – [in,out] pointer to the number of register set properties. if count is zero, then the driver shall update the value with the total number of register set properties available. if count is greater than the number of register set properties available, then the driver shall update the value with the correct number of registry set properties available.

  • pRegisterSetProperties – [in,out][optional][range(0, *pCount)] array of query results for register set properties. if count is less than the number of register set properties available, then driver shall only retrieve that number of register set properties.

Returns:

Debug Enums#

zet_debug_event_flags_t#

Added in version 1.0

enum zet_debug_event_flag_t#

Values:

enumerator ZET_DEBUG_EVENT_FLAG_NEED_ACK#

The event needs to be acknowledged by calling zetDebugAcknowledgeEvent.

enumerator ZET_DEBUG_EVENT_FLAG_FORCE_UINT32#

Value marking end of ZET_DEBUG_EVENT_FLAG_* ENUMs.

zet_debug_event_type_t#

Added in version 1.0

enum zet_debug_event_type_t#

Supported debug event types.

Values:

enumerator ZET_DEBUG_EVENT_TYPE_INVALID#

The event is invalid.

enumerator ZET_DEBUG_EVENT_TYPE_DETACHED#

The tool was detached.

enumerator ZET_DEBUG_EVENT_TYPE_PROCESS_ENTRY#

The debuggee process created command queues on the device.

enumerator ZET_DEBUG_EVENT_TYPE_PROCESS_EXIT#

The debuggee process destroyed all command queues on the device.

enumerator ZET_DEBUG_EVENT_TYPE_MODULE_LOAD#

An in-memory module was loaded onto the device.

enumerator ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD#

An in-memory module is about to get unloaded from the device.

enumerator ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED#

The thread stopped due to a device exception.

enumerator ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE#

The thread is not available to be stopped.

enumerator ZET_DEBUG_EVENT_TYPE_PAGE_FAULT#

A page request could not be completed on the device. (since v1.1)

enumerator ZET_DEBUG_EVENT_TYPE_FORCE_UINT32#

Value marking end of ZET_DEBUG_EVENT_TYPE_* ENUMs.

zet_debug_detach_reason_t#

Added in version 1.0

enum zet_debug_detach_reason_t#

Supported debug detach reasons.

Values:

enumerator ZET_DEBUG_DETACH_REASON_INVALID#

The detach reason is not valid.

enumerator ZET_DEBUG_DETACH_REASON_HOST_EXIT#

The host process exited.

enumerator ZET_DEBUG_DETACH_REASON_FORCE_UINT32#

Value marking end of ZET_DEBUG_DETACH_REASON_* ENUMs.

zet_debug_page_fault_reason_t#

Added in version 1.1

enum zet_debug_page_fault_reason_t#

Page fault reasons.

Values:

enumerator ZET_DEBUG_PAGE_FAULT_REASON_INVALID#

The page fault reason is not valid.

enumerator ZET_DEBUG_PAGE_FAULT_REASON_MAPPING_ERROR#

The address is not mapped.

enumerator ZET_DEBUG_PAGE_FAULT_REASON_PERMISSION_ERROR#

Invalid access permissions.

enumerator ZET_DEBUG_PAGE_FAULT_REASON_FORCE_UINT32#

Value marking end of ZET_DEBUG_PAGE_FAULT_REASON_* ENUMs.

zet_debug_memory_space_type_t#

Added in version 1.0

enum zet_debug_memory_space_type_t#

Supported device memory space types.

Values:

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_DEFAULT#

default memory space (attribute may be omitted)

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_SLM#

shared local memory space (GPU-only)

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_ELF#

ELF file memory space. (since v1.10)

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_BARRIER#

Barrier memory space. (since v1.14)

enumerator ZET_DEBUG_MEMORY_SPACE_TYPE_FORCE_UINT32#

Value marking end of ZET_DEBUG_MEMORY_SPACE_TYPE_* ENUMs.

zet_debug_regset_flags_t#

Added in version 1.0

enum zet_debug_regset_flag_t#

Values:

enumerator ZET_DEBUG_REGSET_FLAG_READABLE#

register set is readable

enumerator ZET_DEBUG_REGSET_FLAG_WRITEABLE#

register set is writeable

enumerator ZET_DEBUG_REGSET_FLAG_FORCE_UINT32#

Value marking end of ZET_DEBUG_REGSET_FLAG_* ENUMs.

Debug Structures#

zet_debug_config_t#

Added in version 1.0

struct zet_debug_config_t#

Debug configuration provided to zetDebugAttach.

Public Members

uint32_t pid#

[in] the host process identifier

zet_debug_event_info_detached_t#

Added in version 1.0

struct zet_debug_event_info_detached_t#

Event information for ZET_DEBUG_EVENT_TYPE_DETACHED.

Public Members

zet_debug_detach_reason_t reason#

[out] the detach reason

zet_debug_event_info_module_t#

Added in version 1.0

struct zet_debug_event_info_module_t#

Event information for ZET_DEBUG_EVENT_TYPE_MODULE_LOAD and ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD.

Public Members

zet_module_debug_info_format_t format#

[out] the module format

uint64_t moduleBegin#

[out] the begin address of the in-memory module (inclusive)

uint64_t moduleEnd#

[out] the end address of the in-memory module (exclusive)

uint64_t load#

[out] the load address of the module on the device

zet_debug_event_info_thread_stopped_t#

Added in version 1.0

struct zet_debug_event_info_thread_stopped_t#

Event information for ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED and ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE.

Public Members

ze_device_thread_t thread#

[out] the stopped/unavailable thread

zet_debug_event_info_page_fault_t#

Added in version 1.1

struct zet_debug_event_info_page_fault_t#

Event information for ZET_DEBUG_EVENT_TYPE_PAGE_FAULT.

Public Members

uint64_t address#

[out] the faulting address

uint64_t mask#

[out] the alignment mask

zet_debug_page_fault_reason_t reason#

[out] the page fault reason

zet_debug_event_info_t#

Added in version 1.0

union zet_debug_event_info_t#
#include <zet_api.h>

Event type-specific information.

Public Members

zet_debug_event_info_detached_t detached#

[out] type == ZET_DEBUG_EVENT_TYPE_DETACHED

zet_debug_event_info_module_t module#

[out] type == ZET_DEBUG_EVENT_TYPE_MODULE_LOAD or ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD

zet_debug_event_info_thread_stopped_t thread#

[out] type == ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED or ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE

zet_debug_event_info_page_fault_t page_fault#

[out] type == ZET_DEBUG_EVENT_TYPE_PAGE_FAULT

zet_debug_event_t#

Added in version 1.0

struct zet_debug_event_t#

A debug event on the device.

Public Members

zet_debug_event_type_t type#

[out] the event type

zet_debug_event_flags_t flags#

[out] returns 0 (none) or a combination of zet_debug_event_flag_t

zet_debug_event_info_t info#

[out] event type specific information

zet_debug_memory_space_desc_t#

Added in version 1.0

struct zet_debug_memory_space_desc_t#

Device memory space descriptor.

Public Members

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

zet_debug_memory_space_type_t type#

[in] type of memory space

uint64_t address#

[in] the virtual address within the memory space

zet_debug_regset_properties_t#

Added in version 1.0

struct zet_debug_regset_properties_t#

Device register set properties queried using zetDebugGetRegisterSetProperties.

Public Members

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

uint32_t type#

[out] device-specific register set type

uint32_t version#

[out] device-specific version of this register set

zet_debug_regset_flags_t generalFlags#

[out] general register set flags

uint32_t deviceFlags#

[out] device-specific register set flags

uint32_t count#

[out] number of registers in the set

uint32_t bitSize#

[out] the size of a register in bits

uint32_t byteSize#

[out] the size required for reading or writing a register in bytes