-
Notifications
You must be signed in to change notification settings - Fork 21
/
Copy pathxpum_api.h
executable file
·1590 lines (1468 loc) · 80.9 KB
/
xpum_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) 2021-2023 Intel Corporation
* SPDX-License-Identifier: MIT
* @file xpum_api.h
*/
#ifndef _XPUM_API_H
#define _XPUM_API_H
#if defined(__cplusplus)
#pragma once
#endif
#include "xpum_structs.h"
#ifdef _WIN32
#ifdef XPUM_EXPORTS
#define XPUM_API __declspec(dllexport)
#else
#define XPUM_API __declspec(dllimport)
#endif
#else
#define XPUM_API
#endif
#if defined(__cplusplus)
namespace xpum {
extern "C" {
#endif
/**************************************************************************/
/** @defgroup BASIC_API Basic API
* XPUM Basic APIs
* @{
*/
/**************************************************************************/
/**
* @brief This method is used to initialize XPUM within this process.
*
* @details Below environment variables will impact the XPUM initialization:
* - XPUM_DISABLE_PERIODIC_METRIC_MONITOR: value options are {0,1}, default is 0. Whether disable periodic metric monitor or not. 0 means metric-pulling tasks will periodically run and collect GPU telemetries once core library is initialized. 1 means metric-pulling tasks will only run and collect GPU telemetries when calling stats related APIs.
* - XPUM_METRICS: enabled metric indexes, value options are listed below, default value: "0,4-31,36-39". Enables metrics which are separated by comma, use hyphen to indicate a range (e.g., 0,4-7,27-29). It will take effect during core initialization.
* - 0 GPU_UTILIZATION
* - 1 EU_ACTIVE
* - 2 EU_STALL
* - 3 EU_IDLE
* - 4 POWER
* - 5 ENERGY
* - 6 GPU_FREQUENCY
* - 7 GPU_CORE_TEMPERATURE
* - 8 MEMORY_USED
* - 9 MEMORY_UTILIZATION
* - 10 MEMORY_BANDWIDTH
* - 11 MEMORY_READ
* - 12 MEMORY_WRITE
* - 13 MEMORY_READ_THROUGHPUT
* - 14 MEMORY_WRITE_THROUGHPUT
* - 15 ENGINE_GROUP_COMPUTE_ALL_UTILIZATION
* - 16 ENGINE_GROUP_MEDIA_ALL_UTILIZATION
* - 17 ENGINE_GROUP_COPY_ALL_UTILIZATION
* - 18 ENGINE_GROUP_RENDER_ALL_UTILIZATION
* - 19 ENGINE_GROUP_3D_ALL_UTILIZATION
* - 20 RAS_ERROR_CAT_RESET
* - 21 RAS_ERROR_CAT_PROGRAMMING_ERRORS
* - 22 RAS_ERROR_CAT_DRIVER_ERRORS
* - 23 RAS_ERROR_CAT_CACHE_ERRORS_CORRECTABLE
* - 24 RAS_ERROR_CAT_CACHE_ERRORS_UNCORRECTABLE
* - 25 RAS_ERROR_CAT_DISPLAY_ERRORS_CORRECTABLE
* - 26 RAS_ERROR_CAT_DISPLAY_ERRORS_UNCORRECTABLE
* - 27 RAS_ERROR_CAT_NON_COMPUTE_ERRORS_CORRECTABLE
* - 28 RAS_ERROR_CAT_NON_COMPUTE_ERRORS_UNCORRECTABLE
* - 29 GPU_REQUEST_FREQUENCY
* - 30 MEMORY_TEMPERATURE
* - 31 FREQUENCY_THROTTLE
* - 32 PCIE_READ_THROUGHPUT
* - 33 PCIE_WRITE_THROUGHPUT
* - 34 PCIE_READ
* - 35 PCIE_WRITE
* - 36 ENGINE_UTILIZATION
* - 37 FABRIC_THROUGHPUT
* - 38 FREQUENCY_THROTTLE_REASON_GPU
* - 39 MEDIA_ENGINE_FREQUENCY
* - XPUM_ENABLED_GPU_IDS: enabled GPU Ids, if this environment variable is not set that means all GPU Ids enabled, if this environment variable is set then just enabled GPU Ids will be discovered. Enabled GPU ids which are separated by comma, use hyphen to indicate a range (e.g., 0,1,4-7).
*
* @return \ref xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumInit(void);
/**
* @brief This method is used to shut down XPUM.
*
* @return \ref xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumShutdown(void);
/**
* @brief This method is used to get XPUM version
*
* @param versionInfoList IN/OUT: First pass NULL to query version info count.
* Then pass array with desired length to
* store version info data.
* @param count IN/OUT: When \a versionInfoList is NULL, \a count will be filled with the number of
* available version info, and return.
* When \a versionInfoList is not NULL, \a count denotes the length of \a versionInfoList,
* \a count should be equal to or larger than the number of available version info,
* when return, the \a count will store real number of entries returned by
* \a versionInfoList
* @return
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than the count of version info
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumVersionInfo(xpum_version_info versionInfoList[], int *count);
/** @} */ // Closing for BASIC_API
/**************************************************************************/
/** @defgroup DEVICE_API Device API
* These APIs are for device
* @{
*/
/**************************************************************************/
/**
* @brief Get all device basic info
* @details This method is used to get identifiers corresponding to all the devices on the system.
* The identifier represents device id corresponding to each device on the system and is immutable
* during the lifespan of the engine. The list should be queried again if the engine is restarted.
*
* @param deviceList OUT: The array to store device infos
* @param count IN/OUT: When \a deviceList is NULL, \a count will be filled with the number of
* available devices, and return.
* When \a deviceList is not NULL, \a count denotes the length of \a deviceList,
* \a count should be equal to or larger than the number of available devices,
* when return, the \a count will store real number of devices returned by
* \a deviceList
* @return \ref xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetDeviceList(xpum_device_basic_info deviceList[], int *count);
/**
* @brief Get device properties corresponding to the \a deviceId.
*
* @param deviceId IN: Device id
* @param pXpumProperties OUT: Device properties
* @return \ref xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetDeviceProperties(xpum_device_id_t deviceId, xpum_device_properties_t *pXpumProperties);
/**
* @brief Get device property name string
*
* @param name IN: Device property name enum value
* @return const char*
* @note Support Platform: Linux, Windows
*/
XPUM_API const char *getXpumDevicePropertyNameString(xpum_device_property_name_t name);
/**
* @brief Get device id corresponding to the \a PCI BDF address.
*
* @param bdf IN: The PCI BDF address string
* @param deviceId OUT: Device id
* @return \ref xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetDeviceIdByBDF(const char *bdf, xpum_device_id_t *deviceId);
/**
* @brief Get all AMC firmware versions
*
* @param versionList IN/OUT: The array to store AMC firmware version
* @param count IN/OUT: When \a versionList is NULL, \a count will be filled with the number of AMC firmware versions, and return.
* When \a versionList is not NULL, \a count denotes the length of \a versionList, \a count should be equal to or larger than the number of AMC firmware versions, when return, the \a count will store real number of AMC firmware versions returned by \a versionList
* @param username IN: Username used for redfish host authentication
* @param password IN: Password used for redfish host authentication
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetAMCFirmwareVersions(xpum_amc_fw_version_t versionList[], int *count, const char *username, const char *password);
/**
* @brief Get error message when fail to get amc firmware versions
*
* @param buffer IN/OUT: The buffer to store error message
* @param count IN/OUT: When \a buffer is NULL, \a count will be filled with the length of buffer needed, and return.
* When \a buffer is not NULL, \a count denotes the length of \a buffer, \a count should be equal to or larger than needed length, if not, it will return XPUM_BUFFER_TOO_SMALL; if return successfully, the error message will be stored in \a buffer
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetAMCFirmwareVersionsErrorMsg(char* buffer, int *count);
/**
* @brief Get device serial number from AMC
*
* @param deviceId IN: Device id
* @param username IN: Username used for redfish host authentication
* @param password IN: Password used for redfish host authentication
* @param serialNumber OUT: Device serial number
* @param amcFwVersion OUT: AMC firmware version
* @return xpum_result_t
* - \ref XPUM_OK
* - \ref XPUM_RESULT_DEVICE_NOT_FOUND
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetSerialNumberAndAmcFwVersion(xpum_device_id_t deviceId, const char *username, const char *password, char serialNumber[XPUM_MAX_STR_LENGTH], char amcFwVersion[XPUM_MAX_STR_LENGTH]);
/** @} */ // Closing for DEVICE_API
/// @cond DAEMON_ONLY
/**************************************************************************/
/** @defgroup GROUP_MANAGEMENT_API Group management
* These APIs are for group management
* @{
*/
/**************************************************************************/
/**
* @brief Create device group
* @details Instead of executing an operation separately for each entity, the group enables
* the user to execute same operation on all the entities present in the group
* as a single API call.
*
* @param groupName IN: Group name for the group to create
* @param pGroupId OUT: Pointer to group id that newly created
* @return \ref xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGroupCreate(const char *groupName, xpum_group_id_t *pGroupId);
/**
* @brief Used to destroy a group represented by \a groupId.
*
* @param groupId IN: The id for the group to destroy
* @return \ref xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGroupDestroy(xpum_group_id_t groupId);
/**
* @brief Used to add specified entity to the group represented by \a groupId.
*
* @param groupId IN: The id for the group to add device
* @param deviceId IN: The device id to add
* @return \ref xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGroupAddDevice(xpum_group_id_t groupId, xpum_device_id_t deviceId);
/**
* @brief Used to remove specified entity from the group represented by \a groupId.
*
* @param groupId IN: The id for the group to remove device
* @param deviceId IN: The device id to remove
* @return \ref xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGroupRemoveDevice(xpum_group_id_t groupId, xpum_device_id_t deviceId);
/**
* @brief Used to get information corresponding to the group represented by \a groupId.
*
* @param groupId IN: The id for the group to get info
* @param pGroupInfo OUT: Pointer to group info struct
* @return \ref xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGroupGetInfo(xpum_group_id_t groupId, xpum_group_info_t *pGroupInfo);
/**
* @brief Get all group ids
*
* @param groupIds OUT: Array to store group ids
* @param count OUT: Count of groups
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetAllGroupIds(xpum_group_id_t groupIds[], int *count);
/** @} */ // Closing for GROUP_MANAGEMENT_API
/// @endcond
/**************************************************************************/
/** @defgroup HEALTH_API Device health
* These APIs are for health
* @{
*/
/**************************************************************************/
/**
* @brief Set health configuration by device
*
* @param deviceId IN: Device id
* @param key IN: Configuration key to set
* @param value IN: Pointer to configuration value to set,
* the type of value is decided by \a key type,
* which should be documented
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumSetHealthConfig(xpum_device_id_t deviceId, xpum_health_config_type_t key, void *value);
/// @cond DAEMON_ONLY
/**
* @brief Set health configuration by group
*
* @param groupId IN: Group id
* @param key IN: Configuration key to set
* @param value IN: Pointer to health configuration value to set
* the type of value is decided by \a key type,
* which should be documented
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumSetHealthConfigByGroup(xpum_group_id_t groupId, xpum_health_config_type_t key, void *value);
/// @endcond
/**
* @brief Get health configuration by device
*
* @param deviceId IN: Device id
* @param key IN: Configuration key to get
* @param value OUT: Pointer to configuration value to get
* the type of value is decided by \a key type,
* which should be documented
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetHealthConfig(xpum_device_id_t deviceId, xpum_health_config_type_t key, void *value);
/// @cond DAEMON_ONLY
/**
* @brief Get health configuration by group
*
* @param groupId IN: Group id
* @param key IN: Configuration key to get
* @param deviceIdList OUT: Array of device ids in this group
* @param valueList OUT: Array to store configuration values for devices' \a key in \a deviceIdList
* @param count IN/OUT: The number of entries that \a deviceIdList and \a valueList array can store,
* count should equal to or larger than device count of the group ( \a groupid );
* when return, the \a count will store real number of entries returned by
* \a deviceIdList and \a valueList
* @return
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than device count of group
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetHealthConfigByGroup(xpum_group_id_t groupId,
xpum_health_config_type_t key,
xpum_device_id_t deviceIdList[],
void *valueList[],
int *count);
/// @endcond
/**
* @brief Get health status by device for specific health type
*
* @param deviceId IN: Device id
* @param type IN: Health type to get
* @param data OUT: Health status data
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetHealth(xpum_device_id_t deviceId, xpum_health_type_t type, xpum_health_data_t *data);
/// @cond DAEMON_ONLY
/**
* @brief Get health status by group for specific health type
*
* @param groupId IN: Group id
* @param type IN: Health type to get
* @param dataList OUT: Array of health status datas, the array length should equal
* to device count of this group.
* @param count IN/OUT: The number of entries that \a dataList array can store,
* count should equal to or larger than device count of the group ( \a groupid );
* when return, the \a count will store real number of entries returned by
* \a dataList
* @return
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than device count of group
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetHealthByGroup(xpum_group_id_t groupId,
xpum_health_type_t type,
xpum_health_data_t dataList[],
int *count);
/// @endcond
/** @} */ // Closing for HEALTH_API
/**************************************************************************/
/** @defgroup CONFIGURATION_API Device configurations
* These APIs are for configuration
* @{
*/
/**************************************************************************/
/**
* @brief Get device standby mode
* @details This function is used to get the standby mode of device
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDeviceStandbys(xpum_device_id_t deviceId,
xpum_standby_data_t dataArray[], uint32_t *count);
/**
* @brief Set device standby mode
* @details This function is used to set the standby mode of device
*
* @param deviceId IN: The device Id
* @param standby IN: The standby mode need to be set
* @return xpum_result_t
* - \ref XPUM_OK if set successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumSetDeviceStandby(xpum_device_id_t deviceId,
const xpum_standby_data_t standby);
/**
* @brief Get device power limit
* @details This function is used to get the power limit of device
*
* @param deviceId IN: The device Id
* @param tileId IN: The tile Id. if tileId is -1, return device's powerlimit; otherwise return tile's powerlimit.
* @param pPowerLimits IN/OUT: The detailed power limit data. Parameter \'interval\' has been obsoleted.
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetDevicePowerLimits(xpum_device_id_t deviceId, int32_t tileId, xpum_power_limits_t *pPowerLimits);
/**
* @brief Set device sustained power limit
* @details This function is used to set the sustained power limit of device
*
* @param deviceId IN: The device Id
* @param tileId IN: The tile Id
* @param sustained_limit IN: The sustained power limit need to be set. Parameter \'interval\' will be ignored.
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumSetDevicePowerSustainedLimits(xpum_device_id_t deviceId, int32_t tileId, const xpum_power_sustained_limit_t sustained_limit);
/**
* @brief Get device frequency ranges
* @details This function is used to get the frequency ranges
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetDeviceFrequencyRanges(xpum_device_id_t deviceId, xpum_frequency_range_t *dataArray, uint32_t *count);
/**
* @brief Set device frequency ranges
* @details This function is used to set the frequency ranges
*
* @param deviceId IN: The device Id
* @param frequency IN: The frequency ranges need to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumSetDeviceFrequencyRange(xpum_device_id_t deviceId, const xpum_frequency_range_t frequency);
/**
* @brief Get device scheduler mode
* @details This function is used to get the scheduler mode
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDeviceSchedulers(xpum_device_id_t deviceId,
xpum_scheduler_data_t dataArray[], uint32_t *count);
/**
* @brief Set device the scheduler(timeout) mode
* @details This function is used to set the scheduler (timeout) mode
*
* @param deviceId IN: The device Id
* @param sched_timeout IN: The scheduler timeout mode need to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumSetDeviceSchedulerTimeoutMode(xpum_device_id_t deviceId,
const xpum_scheduler_timeout_t sched_timeout);
/**
* @brief Get device the power props mode
* @details This function is used to get the power props
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetDevicePowerProps(xpum_device_id_t deviceId,
xpum_power_prop_data_t dataArray[], uint32_t *count);
/**
* @brief Set device the scheduler(time slice) mode
* @details This function is used to set the scheduler (time slice) mode
*
* @param deviceId IN: The device Id
* @param sched_timeslice IN: The scheduler time slice mode need to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumSetDeviceSchedulerTimesliceMode(xpum_device_id_t deviceId,
const xpum_scheduler_timeslice_t sched_timeslice);
/**
* @brief Set device the scheduler(exclusive) mode
* @details This function is used to set the scheduler (exclusive) mode. Caution: It calls xpumShutdown internally.Please make sure other API calls are finished before calling the API, the behaviour of calling other APIs during setting is undefined. And it is recommended to stop current process and use a new process to initialize XPUM after setting.
*
* @param deviceId IN: The device Id
* @param sched_exclusive IN: The scheduler time slice mode need to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumSetDeviceSchedulerExclusiveMode(xpum_device_id_t deviceId,
const xpum_scheduler_exclusive_t sched_exclusive);
/**
* @brief Set device the scheduler(debug) mode
* @details This function is used to set the scheduler (debug) mode. It is not supported since 1.2.25
*
* @param deviceId IN: The device Id
* @param sched_debug IN: The scheduler debug mode need to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumSetDeviceSchedulerDebugMode(xpum_device_id_t deviceId,
const xpum_scheduler_debug_t sched_debug);
/**
* @brief Get device available frequency clocks
* @details This function is used to get available frequency clocks
*
* @param deviceId IN: The device Id
* @param tileId IN: The tile Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetFreqAvailableClocks(xpum_device_id_t deviceId, uint32_t tileId, double dataArray[], uint32_t *count);
/**
* @brief Get the client processes of the device
* @details This function is used to get the client processes of the device
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDeviceProcessState(xpum_device_id_t deviceId, xpum_device_process_t dataArray[], uint32_t *count);
/**
* @brief Apply PPR to the device
* @details This function is used to apply PPR to the device. Caution: xpumApplyPPR calls xpumShutdown internally, please make sure other API calls are finished before calling xpumApplyPPR, the behaviour of calling other APIs during applying ppr is undefined. And it is recommended to stop current process and use a new process to initialize XPUM after resetting.
*
* @param deviceId IN: The device Id
* @param diagResult OUT: PPR diag test result
* @param healthStete OUT: memory health state after running PPR
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_UPDATE_FIRMWARE_TASK_RUNNING if device is updating firmware
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumApplyPPR(xpum_device_id_t deviceId, xpum_diag_result_t* diagResult, xpum_health_status_t* healthState);
/**
* @brief Reset the device
* @details This function is used to reset the device. Caution: xpumResetDevice calls xpumShutdown internally, please make sure other API calls are finished before calling xpumResetDevice, the behaviour of calling other APIs during resetting is undefined. And it is recommended to stop current process and use a new process to initialize XPUM after resetting.
*
* @param deviceId IN: The device Id
* @param force IN: force to reset the device or not
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_UPDATE_FIRMWARE_TASK_RUNNING if device is updating firmware
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumResetDevice(xpum_device_id_t deviceId, bool force);
/**
* @brief Get the GPU function component occupancy ratio of the device
* @details This function is used to get the gpu function component occupancy ratio of the device
*
* @param deviceId IN: The device Id\
* @param tileId IN: The tile Id\
* @param samplingInterval IN: The sampling interval
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of tile, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDeviceComponentOccupancyRatio(xpum_device_id_t deviceId,
xpum_device_tile_id_t tileId,
xpum_sampling_interval_t samplingInterval,
xpum_device_components_ratio_t dataArray[],
uint32_t *count);
/**
* @brief Get the device utiliztions by processes
* @details This function is used to get the device utiliztions by process
*
* @param deviceId IN: The device Id
* @param utilInterval IN: The interval in microseond to caculate utilization, range (0, 1000 * 1000]
* @param dataArray IN/OUT: The array to store raw data.
* @param count IN/OUT: The count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* - \ref XPUM_INTERVAL_INVALID if \a interval is not in (0, 1000 * 1000]
* @note Support Platform: Linux
*/
//The API returns 0 GPU utilization (all engines) due to not ready
//southbound interface.
XPUM_API xpum_result_t xpumGetDeviceUtilizationByProcess(xpum_device_id_t deviceId,
uint32_t utilInterval, xpum_device_util_by_process_t dataArray[],
uint32_t *count);
/**
* @brief Get the device (all) utiliztions by processes
* @details This function is used to get the device utiliztions by process
*
* @param utilInterval IN: The interval in microseond to caculate utilization, range (0, 1000 * 1000]
* @param dataArray IN/OUT: The array to store raw data.
* @param count IN/OUT: The count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* - \ref XPUM_INTERVAL_INVALID if \a interval is not in (0, 1000 * 1000]
* @note Support Platform: Linux
*/
//The API returns 0 GPU utilization (all engines) due to not ready
//southbound interface.
XPUM_API xpum_result_t xpumGetAllDeviceUtilizationByProcess(uint32_t utilInterval,
xpum_device_util_by_process_t dataArray[],
uint32_t *count);
/**
* @brief Get the performance factor of the device
* @details This function is used to get the performance factor of device
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetPerformanceFactor(xpum_device_id_t deviceId, xpum_device_performancefactor_t dataArray[], uint32_t *count);
/**
* @brief Set the performance factor of the device
* @details This function is used to set the performance factor of device
*
* @param deviceId IN: The device Id
* @param performanceFactor IN: The performanceFactor to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumSetPerformanceFactor(xpum_device_id_t deviceId, xpum_device_performancefactor_t performanceFactor);
/**
* @brief Get the fabric port configuration of the device
* @details This function is used to get the fabric port configuration of the device
*
* @param deviceId IN: The device Id
* @param dataArray IN/OUT: First pass NULL to query raw data count. Then pass array with desired length to store raw data.
* @param count IN/OUT: When \a dataArray is NULL, \a count will be filled with the number of available entries, and return. When \a dataArray is not NULL, \a count denotes the length of \a dataArray, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a dataArray
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetFabricPortConfig(xpum_device_id_t deviceId, xpum_fabric_port_config_t dataArray[], uint32_t *count);
/**
* @brief Set the fabric port configuration of the device
* @details This function is used to set the fabric port configuration of the device
*
* @param deviceId IN: The device Id
* @param fabricPortConfig IN: The fabric port configuration to be set
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumSetFabricPortConfig(xpum_device_id_t deviceId, xpum_fabric_port_config_t fabricPortConfig);
/**
* @brief Get the memory ECC state of the device
* @details This function is used to get the memory ECC state of the device
*
* @param deviceId IN: The device Id
* @param available OUT: memory ECC is available, or not
* @param configurable OUT: memory ECC is configurable, or not
* @param current OUT: the current state of memory ECC
* @param pending OUT: the pending state of memory ECC
* @param action OUT: the action need to do to switch to the pending state
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetEccState(xpum_device_id_t deviceId, bool* available, bool* configurable,
xpum_ecc_state_t* current, xpum_ecc_state_t* pending, xpum_ecc_action_t* action);
/**
* @brief Set the memory ECC state of the device
* @details This function is used to set the memory ECC state of the device
*
* @param deviceId IN: The device Id
* @param newState IN: new state to set
* @param available OUT: memory ECC is available, or not
* @param configurable OUT: memory ECC is configurable, or not
* @param current OUT: the current state of memory ECC
* @param pending OUT: the pending state of memory ECC
* @param action OUT: the action need to do to switch to the pending state
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_GENERIC_ERROR if set failure
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumSetEccState(xpum_device_id_t deviceId, xpum_ecc_state_t newState, bool* available, bool* configurable,
xpum_ecc_state_t* current, xpum_ecc_state_t* pending, xpum_ecc_action_t* action);
/** @} */ // Closing for CONFIGURATION_API
/**************************************************************************/
/** @defgroup FIRMWARE_UPDATE_API Firmware flash
* APIs are for firmware update
* @{
*/
/**************************************************************************/
/**
* @brief Run firmware flashing by device
* @details This function will return immediately. To query the firmware flash job status, call \ref xpumGetFirmwareFlashResult
*
* @param deviceId IN: Device id
* @param job IN: The job description for firmware flash
* @param username IN: Username used for authentication
* @param password IN: Password used for authentication
* @return xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumRunFirmwareFlash(xpum_device_id_t deviceId, xpum_firmware_flash_job *job, const char *username, const char *password);
/**
* @brief Run firmware flashing by device
* @details This function will return immediately. To query the firmware flash job status, call \ref xpumGetFirmwareFlashResult
*
* @param deviceId IN: Device id
* @param job IN: The job description for firmware flash
* @param username IN: Username used for authentication
* @param password IN: Password used for authentication
* @param force IN: Force to flash firmware or not
* @return xpum_result_t
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumRunFirmwareFlashEx(xpum_device_id_t deviceId, xpum_firmware_flash_job *job, const char *username, const char *password, bool force);
/**
* @brief Get the status of firmware flash job
* @details This function will return immediately. Caller may have to call this function multiple times until \a result indicates
* firmware flash job is finished.
*
* @param deviceId IN: Device id
* @param firmwareType IN: The firmware type to query status
* @param result OUT: The result of the job
* @return
* - \ref XPUM_OK
* - \ref XPUM_RESULT_DEVICE_NOT_FOUND
* - \ref XPUM_UPDATE_FIRMWARE_IMAGE_FILE_NOT_FOUND
* - \ref XPUM_UPDATE_FIRMWARE_UNSUPPORTED_AMC
* - \ref XPUM_UPDATE_FIRMWARE_UNSUPPORTED_AMC_SINGLE
* - \ref XPUM_UPDATE_FIRMWARE_UNSUPPORTED_GFX_ALL
* - \ref XPUM_UPDATE_FIRMWARE_MODEL_INCONSISTENCE
* - \ref XPUM_UPDATE_FIRMWARE_IGSC_NOT_FOUND
* - \ref XPUM_UPDATE_FIRMWARE_INVALID_FW_IMAGE
* - \ref XPUM_UPDATE_FIRMWARE_FW_IMAGE_NOT_COMPATIBLE_WITH_DEVICE
* - \ref XPUM_GENERIC_ERROR
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetFirmwareFlashResult(xpum_device_id_t deviceId,
xpum_firmware_type_t firmwareType,
xpum_firmware_flash_task_result_t *result);
/**
* @brief Get error message when fail to flash firmware
*
* @param buffer IN/OUT: The buffer to store error message
* @param count IN/OUT: When \a buffer is NULL, \a count will be filled with the length of buffer needed, and return.
* When \a buffer is not NULL, \a count denotes the length of \a buffer, \a count should be equal to or larger than needed length, if not, it will return XPUM_BUFFER_TOO_SMALL; if return successfully, the error message will be stored in \a buffer
* @return xpum_result_t
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux, Windows
*/
XPUM_API xpum_result_t xpumGetFirmwareFlashErrorMsg(char* buffer, int *count);
/** @} */ // Closing for FIRMWARE_UPDATE_API
/**************************************************************************/
/** @defgroup DIAGNOSTICS_API Diagnostics
* These APIs are for diagnostics
* @{
*/
/**************************************************************************/
/**
* @brief Run diagnostics on single device
* This function will return immediately. To get detailed information about diagnostics task, call \ref xpumGetDiagnosticsResult
*
* @param deviceId IN: Device id
* @param level IN: The diagnostics level to run
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumRunDiagnostics(xpum_device_id_t deviceId, xpum_diag_level_t level);
/**
* @brief Run multiple specific diagnostics on single device
* This function will return immediately. To get detailed information about diagnostics task, call \ref xpumGetDiagnosticsResult
*
* @param deviceId IN: Device id
* @param types IN: The array to store diagnostics type
* @param count IN: The count of types
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumRunMultipleSpecificDiagnostics(xpum_device_id_t deviceId, xpum_diag_task_type_t types[], int count);
/// @cond DAEMON_ONLY
/**
* @brief Run diagnostics on a group of devices
* This function will return immediately. To get detailed information about diagnostics task, call \ref xpumGetDiagnosticsResultByGroup
*
* @param groupId IN: Group id
* @param level IN: The diagnostics level to run
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumRunDiagnosticsByGroup(xpum_group_id_t groupId, xpum_diag_level_t level);
/// @endcond
/// @cond DAEMON_ONLY
/**
* @brief Run multiple specific diagnostics on a group of devices
* This function will return immediately. To get detailed information about diagnostics task, call \ref xpumGetDiagnosticsResultByGroup
*
* @param groupId IN: Group id
* @param types IN: The array to store diagnostics type
* @param count IN: The count of types
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumRunMultipleSpecificDiagnosticsByGroup(xpum_group_id_t groupId, xpum_diag_task_type_t types[], int count);
/// @endcond
/**
* @brief Get diagnostics result
* This function will return immediately. Caller may have to call this function multiple times until \a result indicates
* diagnostics job is finished.
*
* @param deviceId IN: The device id to query diagnostics status
* @param result OUT: The status of diagnostics task run on device with \a deviceId
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDiagnosticsResult(xpum_device_id_t deviceId, xpum_diag_task_info_t *result);
/// @cond DAEMON_ONLY
/**
* @brief Get diagnostics result by group
*
* @param groupId IN: The group id to query diagnostics status
* @param resultList OUT: The status of diagnostics task run on device of group with \a groupId
* @param count IN/OUT: The number of entries that \a resultList array can store,
* count should equal to or larger than device count of the group ( \a groupid );
* when return, the \a count will store real number of entries returned by
* \a resultList
* @return
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than device count of group
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDiagnosticsResultByGroup(xpum_group_id_t groupId,
xpum_diag_task_info_t resultList[],
int *count);
/// @endcond
/**
* @brief Get diagnostics media codec result
*
* @param deviceId IN: The device id to query diagnostics media codec result
* @param resultList OUT: The result of diagnostics media codec result run on device with \a deviceId
* @param count IN/OUT: When \a resultList is NULL, \a count will be filled with the number of available entries, and return. When \a resultList is not NULL, \a count denotes the length of \a resultList, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a resultList
* @return
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDiagnosticsMediaCodecResult(xpum_device_id_t deviceId,
xpum_diag_media_codec_metrics_t resultList[],
int *count);
/**
* @brief Get diagnostics xe link throughput result
*
* @param deviceId IN: The device id to query diagnostics xe link throughput result
* @param resultList OUT: The result of diagnostics xe link throughput result run on device with \a deviceId
* @param count IN/OUT: When \a resultList is NULL, \a count will be filled with the number of available entries, and return. When \a resultList is not NULL, \a count denotes the length of \a resultList, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a resultList
* @return
* - \ref XPUM_OK if query successfully
* - \ref XPUM_BUFFER_TOO_SMALL if \a count is smaller than needed
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumGetDiagnosticsXeLinkThroughputResult(xpum_device_id_t deviceId,
xpum_diag_xe_link_throughput_t resultList[],
int *count);
/**
* @brief Run stress test on GPU
* This function will return immediately. To check status of a stress test , call \ref xpumCheckStress
*
* @param deviceId IN: Device id, -1 means run stress test on all GPU devices
* @param stressTime IN: The time (in minutes) to run the stress test. 0 means unlimited time.
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumRunStress(xpum_device_id_t deviceId, uint32_t stressTime);
/**
* @brief Check stress test status
*
* @param deviceId IN: The device id to check stress test status
* @param resultList OUT: The status of stress test run on device with \a deviceId
* @param count IN/OUT: When \a resultList is NULL, \a count will be filled with the number of available entries, and return. When \a resultList is not NULL, \a count denotes the length of \a resultList, \a count should be equal to or larger than the number of available entries, when return, the \a count will store real number of entries returned by \a resultList
* @return xpum_result_t
* @note Support Platform: Linux
*/
XPUM_API xpum_result_t xpumCheckStress(xpum_device_id_t deviceId, xpum_diag_task_info_t resultList[], int *count);
/**
* @brief Run precheck on the machine. It works even if XPUM is not initialized.
*
* @param resultList OUT: The component list result of precheck
* @param count IN/OUT: The number of entries that \a resultList array can store,
* count should equal to or larger than component count;
* when return, the \a count will store real number of entries returned by
* \a resultList
* @param options IN: The options for precheck that can be used to set log source, time range, etc.
*