-
Notifications
You must be signed in to change notification settings - Fork 93
/
zet_api.h
3260 lines (2991 loc) · 186 KB
/
zet_api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
*
* Copyright (C) 2019-2021 Intel Corporation
*
* SPDX-License-Identifier: MIT
*
* @file zet_api.h
* @version v1.11-r1.11.3
*
*/
#ifndef _ZET_API_H
#define _ZET_API_H
#if defined(__cplusplus)
#pragma once
#endif
// 'core' API headers
#include "ze_api.h"
#if defined(__cplusplus)
extern "C" {
#endif
// Intel 'oneAPI' Level-Zero Tool API common types
#if !defined(__GNUC__)
#pragma region common
#endif
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle to a driver instance
typedef ze_driver_handle_t zet_driver_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of device object
typedef ze_device_handle_t zet_device_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of context object
typedef ze_context_handle_t zet_context_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of command list object
typedef ze_command_list_handle_t zet_command_list_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of module object
typedef ze_module_handle_t zet_module_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of function object
typedef ze_kernel_handle_t zet_kernel_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of metric group's object
typedef struct _zet_metric_group_handle_t *zet_metric_group_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of metric's object
typedef struct _zet_metric_handle_t *zet_metric_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of metric streamer's object
typedef struct _zet_metric_streamer_handle_t *zet_metric_streamer_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of metric query pool's object
typedef struct _zet_metric_query_pool_handle_t *zet_metric_query_pool_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of metric query's object
typedef struct _zet_metric_query_handle_t *zet_metric_query_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of tracer object
typedef struct _zet_tracer_exp_handle_t *zet_tracer_exp_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Debug session handle
typedef struct _zet_debug_session_handle_t *zet_debug_session_handle_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Defines structure types
typedef enum _zet_structure_type_t
{
ZET_STRUCTURE_TYPE_METRIC_GROUP_PROPERTIES = 0x1, ///< ::zet_metric_group_properties_t
ZET_STRUCTURE_TYPE_METRIC_PROPERTIES = 0x2, ///< ::zet_metric_properties_t
ZET_STRUCTURE_TYPE_METRIC_STREAMER_DESC = 0x3, ///< ::zet_metric_streamer_desc_t
ZET_STRUCTURE_TYPE_METRIC_QUERY_POOL_DESC = 0x4, ///< ::zet_metric_query_pool_desc_t
ZET_STRUCTURE_TYPE_PROFILE_PROPERTIES = 0x5, ///< ::zet_profile_properties_t
ZET_STRUCTURE_TYPE_DEVICE_DEBUG_PROPERTIES = 0x6, ///< ::zet_device_debug_properties_t
ZET_STRUCTURE_TYPE_DEBUG_MEMORY_SPACE_DESC = 0x7, ///< ::zet_debug_memory_space_desc_t
ZET_STRUCTURE_TYPE_DEBUG_REGSET_PROPERTIES = 0x8, ///< ::zet_debug_regset_properties_t
ZET_STRUCTURE_TYPE_GLOBAL_METRICS_TIMESTAMPS_EXP_PROPERTIES = 0x9, ///< ::zet_metric_global_timestamps_resolution_exp_t. Deprecated, use
///< ::ZET_STRUCTURE_TYPE_METRIC_GLOBAL_TIMESTAMPS_RESOLUTION_EXP.
ZET_STRUCTURE_TYPE_METRIC_GLOBAL_TIMESTAMPS_RESOLUTION_EXP = 0x9, ///< ::zet_metric_global_timestamps_resolution_exp_t
ZET_STRUCTURE_TYPE_TRACER_EXP_DESC = 0x00010001, ///< ::zet_tracer_exp_desc_t
ZET_STRUCTURE_TYPE_METRICS_CALCULATE_EXP_DESC = 0x00010002, ///< ::zet_metric_calculate_exp_desc_t. Deprecated, use
///< ::ZET_STRUCTURE_TYPE_METRIC_CALCULATE_EXP_DESC.
ZET_STRUCTURE_TYPE_METRIC_CALCULATE_EXP_DESC = 0x00010002, ///< ::zet_metric_calculate_exp_desc_t
ZET_STRUCTURE_TYPE_METRIC_PROGRAMMABLE_EXP_PROPERTIES = 0x00010003, ///< ::zet_metric_programmable_exp_properties_t
ZET_STRUCTURE_TYPE_METRIC_PROGRAMMABLE_PARAM_INFO_EXP = 0x00010004, ///< ::zet_metric_programmable_param_info_exp_t
ZET_STRUCTURE_TYPE_METRIC_PROGRAMMABLE_PARAM_VALUE_INFO_EXP = 0x00010005, ///< ::zet_metric_programmable_param_value_info_exp_t
ZET_STRUCTURE_TYPE_METRIC_GROUP_TYPE_EXP = 0x00010006, ///< ::zet_metric_group_type_exp_t
ZET_STRUCTURE_TYPE_EXPORT_DMA_EXP_PROPERTIES = 0x00010007, ///< ::zet_export_dma_buf_exp_properties_t
ZET_STRUCTURE_TYPE_METRIC_TRACER_EXP_DESC = 0x00010008, ///< ::zet_metric_tracer_exp_desc_t
ZET_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
} zet_structure_type_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Base for all properties types
typedef struct _zet_base_properties_t
{
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).
} zet_base_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Base for all descriptor types
typedef struct _zet_base_desc_t
{
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_base_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported value types
typedef enum _zet_value_type_t
{
ZET_VALUE_TYPE_UINT32 = 0, ///< 32-bit unsigned-integer
ZET_VALUE_TYPE_UINT64 = 1, ///< 64-bit unsigned-integer
ZET_VALUE_TYPE_FLOAT32 = 2, ///< 32-bit floating-point
ZET_VALUE_TYPE_FLOAT64 = 3, ///< 64-bit floating-point
ZET_VALUE_TYPE_BOOL8 = 4, ///< 8-bit boolean
ZET_VALUE_TYPE_STRING = 5, ///< C string
ZET_VALUE_TYPE_UINT8 = 6, ///< 8-bit unsigned-integer
ZET_VALUE_TYPE_UINT16 = 7, ///< 16-bit unsigned-integer
ZET_VALUE_TYPE_FORCE_UINT32 = 0x7fffffff
} zet_value_type_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Union of values
typedef union _zet_value_t
{
uint32_t ui32; ///< [out] 32-bit unsigned-integer
uint64_t ui64; ///< [out] 64-bit unsigned-integer
float fp32; ///< [out] 32-bit floating-point
double fp64; ///< [out] 64-bit floating-point
ze_bool_t b8; ///< [out] 8-bit boolean
} zet_value_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Typed value
typedef struct _zet_typed_value_t
{
zet_value_type_t type; ///< [out] type of value
zet_value_t value; ///< [out] value
} zet_typed_value_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Enables driver instrumentation and dependencies for device metrics
///////////////////////////////////////////////////////////////////////////////
/// @brief Enables driver instrumentation and dependencies for program
/// instrumentation
///////////////////////////////////////////////////////////////////////////////
/// @brief Enables driver instrumentation and dependencies for program debugging
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_base_properties_t
typedef struct _zet_base_properties_t zet_base_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_base_desc_t
typedef struct _zet_base_desc_t zet_base_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_typed_value_t
typedef struct _zet_typed_value_t zet_typed_value_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_device_debug_properties_t
typedef struct _zet_device_debug_properties_t zet_device_debug_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_config_t
typedef struct _zet_debug_config_t zet_debug_config_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_event_info_detached_t
typedef struct _zet_debug_event_info_detached_t zet_debug_event_info_detached_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_event_info_module_t
typedef struct _zet_debug_event_info_module_t zet_debug_event_info_module_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_event_info_thread_stopped_t
typedef struct _zet_debug_event_info_thread_stopped_t zet_debug_event_info_thread_stopped_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_event_info_page_fault_t
typedef struct _zet_debug_event_info_page_fault_t zet_debug_event_info_page_fault_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_event_t
typedef struct _zet_debug_event_t zet_debug_event_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_memory_space_desc_t
typedef struct _zet_debug_memory_space_desc_t zet_debug_memory_space_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_debug_regset_properties_t
typedef struct _zet_debug_regset_properties_t zet_debug_regset_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_group_properties_t
typedef struct _zet_metric_group_properties_t zet_metric_group_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_properties_t
typedef struct _zet_metric_properties_t zet_metric_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_streamer_desc_t
typedef struct _zet_metric_streamer_desc_t zet_metric_streamer_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_query_pool_desc_t
typedef struct _zet_metric_query_pool_desc_t zet_metric_query_pool_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_profile_properties_t
typedef struct _zet_profile_properties_t zet_profile_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_profile_free_register_token_t
typedef struct _zet_profile_free_register_token_t zet_profile_free_register_token_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_profile_register_sequence_t
typedef struct _zet_profile_register_sequence_t zet_profile_register_sequence_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_tracer_exp_desc_t
typedef struct _zet_tracer_exp_desc_t zet_tracer_exp_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_tracer_exp_desc_t
typedef struct _zet_metric_tracer_exp_desc_t zet_metric_tracer_exp_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_entry_exp_t
typedef struct _zet_metric_entry_exp_t zet_metric_entry_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_group_type_exp_t
typedef struct _zet_metric_group_type_exp_t zet_metric_group_type_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_export_dma_buf_exp_properties_t
typedef struct _zet_export_dma_buf_exp_properties_t zet_export_dma_buf_exp_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_global_timestamps_resolution_exp_t
typedef struct _zet_metric_global_timestamps_resolution_exp_t zet_metric_global_timestamps_resolution_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_calculate_exp_desc_t
typedef struct _zet_metric_calculate_exp_desc_t zet_metric_calculate_exp_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_programmable_exp_properties_t
typedef struct _zet_metric_programmable_exp_properties_t zet_metric_programmable_exp_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_value_uint64_range_exp_t
typedef struct _zet_value_uint64_range_exp_t zet_value_uint64_range_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_value_fp64_range_exp_t
typedef struct _zet_value_fp64_range_exp_t zet_value_fp64_range_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_programmable_param_info_exp_t
typedef struct _zet_metric_programmable_param_info_exp_t zet_metric_programmable_param_info_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_programmable_param_value_info_exp_t
typedef struct _zet_metric_programmable_param_value_info_exp_t zet_metric_programmable_param_value_info_exp_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Forward-declare zet_metric_programmable_param_value_exp_t
typedef struct _zet_metric_programmable_param_value_exp_t zet_metric_programmable_param_value_exp_t;
#if !defined(__GNUC__)
#pragma endregion
#endif
// Intel 'oneAPI' Level-Zero Tool APIs for Device
#if !defined(__GNUC__)
#pragma region device
#endif
#if !defined(__GNUC__)
#pragma endregion
#endif
// Intel 'oneAPI' Level-Zero Tool APIs for Context
#if !defined(__GNUC__)
#pragma region context
#endif
#if !defined(__GNUC__)
#pragma endregion
#endif
// Intel 'oneAPI' Level-Zero Tool APIs for Command List
#if !defined(__GNUC__)
#pragma region cmdlist
#endif
#if !defined(__GNUC__)
#pragma endregion
#endif
// Intel 'oneAPI' Level-Zero Tool APIs for Module
#if !defined(__GNUC__)
#pragma region module
#endif
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported module debug info formats.
typedef enum _zet_module_debug_info_format_t
{
ZET_MODULE_DEBUG_INFO_FORMAT_ELF_DWARF = 0, ///< Format is ELF/DWARF
ZET_MODULE_DEBUG_INFO_FORMAT_FORCE_UINT32 = 0x7fffffff
} zet_module_debug_info_format_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Retrieve debug info from module.
///
/// @details
/// - The caller can pass nullptr for pDebugInfo when querying only for
/// size.
/// - The implementation will copy the native binary into a buffer supplied
/// by the caller.
/// - The application may call this function from simultaneous threads.
/// - The implementation of this function should be lock-free.
///
/// @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_NULL_HANDLE
/// + `nullptr == hModule`
/// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION
/// + `::ZET_MODULE_DEBUG_INFO_FORMAT_ELF_DWARF < format`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pSize`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetModuleGetDebugInfo(
zet_module_handle_t hModule, ///< [in] handle of the module
zet_module_debug_info_format_t format, ///< [in] debug info format requested
size_t* pSize, ///< [in,out] size of debug info in bytes
uint8_t* pDebugInfo ///< [in,out][optional] byte pointer to debug info
);
#if !defined(__GNUC__)
#pragma endregion
#endif
// Intel 'oneAPI' Level-Zero Tool APIs for Program Debug
#if !defined(__GNUC__)
#pragma region debug
#endif
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported device debug property flags
typedef uint32_t zet_device_debug_property_flags_t;
typedef enum _zet_device_debug_property_flag_t
{
ZET_DEVICE_DEBUG_PROPERTY_FLAG_ATTACH = ZE_BIT(0), ///< the device supports attaching for debug
ZET_DEVICE_DEBUG_PROPERTY_FLAG_FORCE_UINT32 = 0x7fffffff
} zet_device_debug_property_flag_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Device debug properties queried using ::zetDeviceGetDebugProperties.
typedef struct _zet_device_debug_properties_t
{
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).
zet_device_debug_property_flags_t flags; ///< [out] returns 0 (none) or a valid combination of
///< ::zet_device_debug_property_flag_t
} zet_device_debug_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Retrieves debug properties of the device.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDevice`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pDebugProperties`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDeviceGetDebugProperties(
zet_device_handle_t hDevice, ///< [in] device handle
zet_device_debug_properties_t* pDebugProperties ///< [in,out] query result for debug properties
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Debug configuration provided to ::zetDebugAttach
typedef struct _zet_debug_config_t
{
uint32_t pid; ///< [in] the host process identifier
} zet_debug_config_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Attach to a device.
///
/// @details
/// - The device must be enabled for debug; see
/// ::zesSchedulerSetComputeUnitDebugMode.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDevice`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == config`
/// + `nullptr == phDebug`
/// - ::ZE_RESULT_ERROR_UNSUPPORTED_FEATURE
/// + attaching to this device is not supported
/// - ::ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS
/// + caller does not have sufficient permissions
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + a debugger is already attached
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugAttach(
zet_device_handle_t hDevice, ///< [in] device handle
const zet_debug_config_t* config, ///< [in] the debug configuration
zet_debug_session_handle_t* phDebug ///< [out] debug session handle
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Close a debug session.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugDetach(
zet_debug_session_handle_t hDebug ///< [in][release] debug session handle
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported debug event flags.
typedef uint32_t zet_debug_event_flags_t;
typedef enum _zet_debug_event_flag_t
{
ZET_DEBUG_EVENT_FLAG_NEED_ACK = ZE_BIT(0), ///< The event needs to be acknowledged by calling
///< ::zetDebugAcknowledgeEvent.
ZET_DEBUG_EVENT_FLAG_FORCE_UINT32 = 0x7fffffff
} zet_debug_event_flag_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported debug event types.
typedef enum _zet_debug_event_type_t
{
ZET_DEBUG_EVENT_TYPE_INVALID = 0, ///< The event is invalid
ZET_DEBUG_EVENT_TYPE_DETACHED = 1, ///< The tool was detached
ZET_DEBUG_EVENT_TYPE_PROCESS_ENTRY = 2, ///< The debuggee process created command queues on the device
ZET_DEBUG_EVENT_TYPE_PROCESS_EXIT = 3, ///< The debuggee process destroyed all command queues on the device
ZET_DEBUG_EVENT_TYPE_MODULE_LOAD = 4, ///< An in-memory module was loaded onto the device
ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD = 5, ///< An in-memory module is about to get unloaded from the device
ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED = 6, ///< The thread stopped due to a device exception
ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE = 7, ///< The thread is not available to be stopped
ZET_DEBUG_EVENT_TYPE_PAGE_FAULT = 8, ///< A page request could not be completed on the device
ZET_DEBUG_EVENT_TYPE_FORCE_UINT32 = 0x7fffffff
} zet_debug_event_type_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported debug detach reasons.
typedef enum _zet_debug_detach_reason_t
{
ZET_DEBUG_DETACH_REASON_INVALID = 0, ///< The detach reason is not valid
ZET_DEBUG_DETACH_REASON_HOST_EXIT = 1, ///< The host process exited
ZET_DEBUG_DETACH_REASON_FORCE_UINT32 = 0x7fffffff
} zet_debug_detach_reason_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Event information for ::ZET_DEBUG_EVENT_TYPE_DETACHED
typedef struct _zet_debug_event_info_detached_t
{
zet_debug_detach_reason_t reason; ///< [out] the detach reason
} zet_debug_event_info_detached_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Event information for ::ZET_DEBUG_EVENT_TYPE_MODULE_LOAD and
/// ::ZET_DEBUG_EVENT_TYPE_MODULE_UNLOAD
typedef struct _zet_debug_event_info_module_t
{
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_module_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Event information for ::ZET_DEBUG_EVENT_TYPE_THREAD_STOPPED and
/// ::ZET_DEBUG_EVENT_TYPE_THREAD_UNAVAILABLE
typedef struct _zet_debug_event_info_thread_stopped_t
{
ze_device_thread_t thread; ///< [out] the stopped/unavailable thread
} zet_debug_event_info_thread_stopped_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Page fault reasons.
typedef enum _zet_debug_page_fault_reason_t
{
ZET_DEBUG_PAGE_FAULT_REASON_INVALID = 0, ///< The page fault reason is not valid
ZET_DEBUG_PAGE_FAULT_REASON_MAPPING_ERROR = 1, ///< The address is not mapped
ZET_DEBUG_PAGE_FAULT_REASON_PERMISSION_ERROR = 2, ///< Invalid access permissions
ZET_DEBUG_PAGE_FAULT_REASON_FORCE_UINT32 = 0x7fffffff
} zet_debug_page_fault_reason_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Event information for ::ZET_DEBUG_EVENT_TYPE_PAGE_FAULT
typedef struct _zet_debug_event_info_page_fault_t
{
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_page_fault_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Event type-specific information
typedef union _zet_debug_event_info_t
{
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_info_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief A debug event on the device.
typedef struct _zet_debug_event_t
{
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_event_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Read the topmost debug event.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == event`
/// - ::ZE_RESULT_NOT_READY
/// + the timeout expired
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugReadEvent(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
uint64_t 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.
zet_debug_event_t* event ///< [in,out] a pointer to a ::zet_debug_event_t.
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Acknowledge a debug event.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == event`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugAcknowledgeEvent(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
const zet_debug_event_t* event ///< [in] a pointer to a ::zet_debug_event_t.
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Interrupt device threads.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is already stopped or unavailable
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugInterrupt(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread ///< [in] the thread to interrupt
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Resume device threads.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is already running or unavailable
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugResume(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread ///< [in] the thread to resume
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported device memory space types.
typedef enum _zet_debug_memory_space_type_t
{
ZET_DEBUG_MEMORY_SPACE_TYPE_DEFAULT = 0, ///< default memory space (attribute may be omitted)
ZET_DEBUG_MEMORY_SPACE_TYPE_SLM = 1, ///< shared local memory space (GPU-only)
ZET_DEBUG_MEMORY_SPACE_TYPE_ELF = 2, ///< ELF file memory space
ZET_DEBUG_MEMORY_SPACE_TYPE_FORCE_UINT32 = 0x7fffffff
} zet_debug_memory_space_type_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Device memory space descriptor
typedef struct _zet_debug_memory_space_desc_t
{
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_memory_space_desc_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Read memory.
///
/// @details
/// - The thread identifier 'all' can be used for accessing the default
/// memory space, e.g. for setting breakpoints.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == desc`
/// + `nullptr == buffer`
/// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION
/// + `::ZET_DEBUG_MEMORY_SPACE_TYPE_ELF < desc->type`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is running or unavailable
/// + the memory cannot be accessed from the supplied thread
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugReadMemory(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread, ///< [in] the thread identifier.
const zet_debug_memory_space_desc_t* desc, ///< [in] memory space descriptor
size_t size, ///< [in] the number of bytes to read
void* buffer ///< [in,out] a buffer to hold a copy of the memory
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Write memory.
///
/// @details
/// - The thread identifier 'all' can be used for accessing the default
/// memory space, e.g. for setting breakpoints.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == desc`
/// + `nullptr == buffer`
/// - ::ZE_RESULT_ERROR_INVALID_ENUMERATION
/// + `::ZET_DEBUG_MEMORY_SPACE_TYPE_ELF < desc->type`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is running or unavailable
/// + the memory cannot be accessed from the supplied thread
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugWriteMemory(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread, ///< [in] the thread identifier.
const zet_debug_memory_space_desc_t* desc, ///< [in] memory space descriptor
size_t size, ///< [in] the number of bytes to write
const void* buffer ///< [in] a buffer holding the pattern to write
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Supported general register set flags.
typedef uint32_t zet_debug_regset_flags_t;
typedef enum _zet_debug_regset_flag_t
{
ZET_DEBUG_REGSET_FLAG_READABLE = ZE_BIT(0), ///< register set is readable
ZET_DEBUG_REGSET_FLAG_WRITEABLE = ZE_BIT(1), ///< register set is writeable
ZET_DEBUG_REGSET_FLAG_FORCE_UINT32 = 0x7fffffff
} zet_debug_regset_flag_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Device register set properties queried using
/// ::zetDebugGetRegisterSetProperties.
typedef struct _zet_debug_regset_properties_t
{
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
} zet_debug_regset_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Retrieves debug register set properties.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDevice`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pCount`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugGetRegisterSetProperties(
zet_device_handle_t hDevice, ///< [in] device handle
uint32_t* 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.
zet_debug_regset_properties_t* 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.
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Retrieves debug register set properties for a given thread.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pCount`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is running or unavailable
/// - ::ZE_RESULT_ERROR_INVALID_ARGUMENT
/// + the thread argument specifies more than one or a non-existant thread
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugGetThreadRegisterSetProperties(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread, ///< [in] the thread identifier specifying a single stopped thread
uint32_t* 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.
zet_debug_regset_properties_t* 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.
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Read register state.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is running or unavailable
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugReadRegisters(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread, ///< [in] the thread identifier
uint32_t type, ///< [in] register set type
uint32_t 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
uint32_t count, ///< [in] the number of registers to read; start+count must be less than or
///< equal to the `count` member of ::zet_debug_register_group_properties_t
///< for the type
void* pRegisterValues ///< [in,out][optional][range(0, count)] buffer of register values
);
///////////////////////////////////////////////////////////////////////////////
/// @brief Write register state.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDebug`
/// - ::ZE_RESULT_ERROR_NOT_AVAILABLE
/// + the thread is running or unavailable
ZE_APIEXPORT ze_result_t ZE_APICALL
zetDebugWriteRegisters(
zet_debug_session_handle_t hDebug, ///< [in] debug session handle
ze_device_thread_t thread, ///< [in] the thread identifier
uint32_t type, ///< [in] register set type
uint32_t 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
uint32_t count, ///< [in] the number of registers to write; start+count must be less than
///< or equal to the `count` member of
///< ::zet_debug_register_group_properties_t for the type
void* pRegisterValues ///< [in,out][optional][range(0, count)] buffer of register values
);
#if !defined(__GNUC__)
#pragma endregion
#endif
// Intel 'oneAPI' Level-Zero Tool APIs for Metric
#if !defined(__GNUC__)
#pragma region metric
#endif
///////////////////////////////////////////////////////////////////////////////
/// @brief Retrieves metric group for a device.
///
/// @details
/// - The application may call this function from simultaneous threads.
///
/// @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_NULL_HANDLE
/// + `nullptr == hDevice`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pCount`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetMetricGroupGet(
zet_device_handle_t hDevice, ///< [in] handle of the device
uint32_t* pCount, ///< [in,out] pointer to the number of metric groups.
///< if count is zero, then the driver shall update the value with the
///< total number of metric groups available.
///< if count is greater than the number of metric groups available, then
///< the driver shall update the value with the correct number of metric
///< groups available.
zet_metric_group_handle_t* phMetricGroups ///< [in,out][optional][range(0, *pCount)] array of handle of metric groups.
///< if count is less than the number of metric groups available, then
///< driver shall only retrieve that number of metric groups.
);
///////////////////////////////////////////////////////////////////////////////
#ifndef ZET_MAX_METRIC_GROUP_NAME
/// @brief Maximum metric group name string size
#define ZET_MAX_METRIC_GROUP_NAME 256
#endif // ZET_MAX_METRIC_GROUP_NAME
///////////////////////////////////////////////////////////////////////////////
#ifndef ZET_MAX_METRIC_GROUP_DESCRIPTION
/// @brief Maximum metric group description string size
#define ZET_MAX_METRIC_GROUP_DESCRIPTION 256
#endif // ZET_MAX_METRIC_GROUP_DESCRIPTION
///////////////////////////////////////////////////////////////////////////////
/// @brief Metric group sampling type
typedef uint32_t zet_metric_group_sampling_type_flags_t;
typedef enum _zet_metric_group_sampling_type_flag_t
{
ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_EVENT_BASED = ZE_BIT(0), ///< Event based sampling
ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_TIME_BASED = ZE_BIT(1), ///< Time based sampling
ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_EXP_TRACER_BASED = ZE_BIT(2), ///< Experimental Tracer based sampling
ZET_METRIC_GROUP_SAMPLING_TYPE_FLAG_FORCE_UINT32 = 0x7fffffff
} zet_metric_group_sampling_type_flag_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Metric group properties queried using ::zetMetricGroupGetProperties
typedef struct _zet_metric_group_properties_t
{
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).
char name[ZET_MAX_METRIC_GROUP_NAME]; ///< [out] metric group name
char description[ZET_MAX_METRIC_GROUP_DESCRIPTION]; ///< [out] metric group description
zet_metric_group_sampling_type_flags_t samplingType; ///< [out] metric group sampling type.
///< returns a combination of ::zet_metric_group_sampling_type_flag_t.
uint32_t domain; ///< [out] metric group domain number. Cannot use multiple, simultaneous
///< metric groups from the same domain.
uint32_t metricCount; ///< [out] metric count belonging to this group
} zet_metric_group_properties_t;
///////////////////////////////////////////////////////////////////////////////
/// @brief Retrieves attributes of a metric group.
///
/// @details
/// - The application may call this function from simultaneous threads.
///
/// @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_NULL_HANDLE
/// + `nullptr == hMetricGroup`
/// - ::ZE_RESULT_ERROR_INVALID_NULL_POINTER
/// + `nullptr == pProperties`
ZE_APIEXPORT ze_result_t ZE_APICALL
zetMetricGroupGetProperties(
zet_metric_group_handle_t hMetricGroup, ///< [in] handle of the metric group
zet_metric_group_properties_t* pProperties ///< [in,out] metric group properties