Skip to content

Commit 2da2960

Browse files
AshwinKumarKulkarnipbg-intel
AshwinKumarKulkarni
authored and
pbg-intel
committed
Updates to sysman vf telemetry APIs
Signed-off-by: Kulkarni, Ashwin Kumar <[email protected]>
1 parent 4cd5949 commit 2da2960

File tree

3 files changed

+265
-20
lines changed

3 files changed

+265
-20
lines changed

‎scripts/sysman/EXT_Exp_VirtualFunctionManagement.rst‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,25 +22,36 @@ API
2222
* Functions
2323

2424
* ${s}DeviceEnumEnabledVFExp
25+
* ${s}DeviceEnumActiveVFExp
2526
* ${s}VFManagementGetVFCapabilitiesExp
27+
* ${s}VFManagementGetVFMemoryUtilizationExp2
28+
* ${s}VFManagementGetVFEngineUtilizationExp2
29+
* ${s}VFManagementGetVFPropertiesExp
2630
* ${s}VFManagementGetVFMemoryUtilizationExp
2731
* ${s}VFManagementGetVFEngineUtilizationExp
32+
* ${s}VFManagementSetVFTelemetryModeExp
33+
* ${s}VFManagementSetVFTelemetrySamplingIntervalExp
2834

2935
* Enumerations
3036

3137
* ${s}_vf_management_exp_version_t
38+
* ${s}_vf_info_mem_type_exp_flags_t
39+
* ${s}_vf_info_util_exp_flags_t
3240

3341
* Structures
3442

3543
* ${s}_vf_exp_capabilities_t
44+
* ${s}_vf_util_mem_exp2_t
45+
* ${s}_vf_util_engine_exp2_t
46+
* ${s}_vf_exp_properties_t
3647
* ${s}_vf_util_mem_exp_t
3748
* ${s}_vf_util_engine_exp_t
3849

3950
Virtual Function Management
4051
~~~~~~~~~~~~~~~~~~~~~~~~~~~
4152
This feature adds the ability to retrieve telemetry from PF domain for monitoring per VF memory and engine utilization.
4253
This telemetry is used to determine if a VM has oversubscribed GPU memory or observe engine business for a targeted workload.
43-
If VF has no activity value to report, then implementation shall reflect that appropriately in ${s}_vf_util_engine_exp_t struct so that percentage
54+
If VF has no activity value to report, then implementation shall reflect that appropriately in ${s}_vf_util_engine_exp2_t struct so that percentage
4455
calculation results in value of 0.
4556

4657
The following pseudo-code demonstrates a sequence for obtaining the engine activity for all Virtual Functions from Physical Function environment:
@@ -57,9 +68,9 @@ The following pseudo-code demonstrates a sequence for obtaining the engine activ
5768
${s}DeviceEnumEnabledVFExp(hDevice, &numVf, vfs.data());
5869
5970
// Gather VF properties
60-
std::vector <${s}_vf_exp_capabilities_t> vfProps(numVf);
71+
std::vector <${s}_vf_exp_capabilities_t> vfCapabs(numVf);
6172
for (uint32_t i = 0; i < numVf; i++) {
62-
${s}VFManagementGetVFCapabilitiesExp(vfs[i], &vfProps[i]);
73+
${s}VFManagementGetVFCapabilitiesExp(vfs[i], &vfCapabs[i]);
6374
}
6475
6576
// Detect the info types a particular VF supports
@@ -68,10 +79,10 @@ The following pseudo-code demonstrates a sequence for obtaining the engine activ
6879
${s}_vf_handle_t activeVf = vfs[0];
6980
uint32_t engineStatCount = 0;
7081
71-
${s}VFManagementGetVFEngineUtilizationExp(activeVf, &engineStatCount, nullptr);
82+
${s}VFManagementGetVFEngineUtilizationExp2(activeVf, &engineStatCount, nullptr);
7283
// Allocate memory for vf engine stats
73-
${s}_vf_util_engine_exp_t* engineStats0 = (${s}_vf_util_engine_exp_t*) allocate(engineStatCount * sizeof(${s}_vf_util_engine_exp_t));
74-
${s}VFManagementGetVFEngineUtilizationExp(activeVf, &engineStatCount, engineStats0);
84+
${s}_vf_util_engine_exp2_t* engineStats0 = (${s}_vf_util_engine_exp2_t*) allocate(engineStatCount * sizeof(${s}_vf_util_engine_exp2_t));
85+
${s}VFManagementGetVFEngineUtilizationExp2(activeVf, &engineStatCount, engineStats0);
7586
sleep(1)
76-
${s}_vf_util_engine_exp_t* engineStats1 = (${s}_vf_util_engine_exp_t*) allocate(engineStatCount * sizeof(${s}_vf_util_engine_exp_t));
77-
${s}VFManagementGetVFEngineUtilizationExp(activeVf, &engineStatCount, &engineStats1);
87+
${s}_vf_util_engine_exp2_t* engineStats1 = (${s}_vf_util_engine_exp2_t*) allocate(engineStatCount * sizeof(${s}_vf_util_engine_exp2_t));
88+
${s}VFManagementGetVFEngineUtilizationExp2(activeVf, &engineStatCount, &engineStats1);

‎scripts/sysman/common.yml‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -233,9 +233,9 @@ etors:
233233
value: "0x00020004"
234234
desc: $s_subdevice_exp_properties_t
235235
version: "1.9"
236-
- name: VF_EXP_CAPABILITIES
236+
- name: VF_EXP_PROPERTIES
237237
value: "0x00020005"
238-
desc: $s_vf_exp_capabilities_t
238+
desc: $s_vf_exp_properties_t
239239
version: "1.10"
240240
- name: VF_UTIL_MEM_EXP
241241
value: "0x00020006"
@@ -245,6 +245,18 @@ etors:
245245
value: "0x00020007"
246246
desc: $s_vf_util_engine_exp_t
247247
version: "1.9"
248+
- name: VF_EXP_CAPABILITIES
249+
value: "0x00020008"
250+
desc: $s_vf_exp_capabilities_t
251+
version: "1.10"
252+
- name: VF_UTIL_MEM_EXP2
253+
value: "0x00020009"
254+
desc: $s_vf_util_mem_exp2_t
255+
version: "1.10"
256+
- name: VF_UTIL_ENGINE_EXP2
257+
value: "0x00020010"
258+
desc: $s_vf_util_engine_exp2_t
259+
version: "1.10"
248260
--- #-------------------------------------------------------------------------
249261
type: struct
250262
desc: "Base for all properties types"

‎scripts/sysman/virtualFunctionManagement.yml‎

Lines changed: 232 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,93 @@ etors:
2626
desc: "version 1.0 (deprecated)"
2727
- name: "1_1"
2828
value: "$X_MAKE_VERSION( 1, 1 )"
29-
desc: "version 1.1"
29+
desc: "version 1.1 (deprecated)"
30+
- name: "1_2"
31+
value: "$X_MAKE_VERSION( 1, 2 )"
32+
desc: "version 1.2"
33+
--- #--------------------------------------------------------------------------
34+
type: enum
35+
desc: "Virtual function memory types (deprecated)"
36+
version: "1.9"
37+
class: $sVFManagement
38+
name: $s_vf_info_mem_type_exp_flags_t
39+
etors:
40+
- name: MEM_TYPE_SYSTEM
41+
desc: "System memory"
42+
- name: MEM_TYPE_DEVICE
43+
desc: "Device local memory"
44+
--- #--------------------------------------------------------------------------
45+
type: enum
46+
desc: "Virtual function utilization flag bit fields (deprecated)"
47+
version: "1.9"
48+
class: $sVFManagement
49+
name: $s_vf_info_util_exp_flags_t
50+
etors:
51+
- name: INFO_NONE
52+
desc: "No info associated with virtual function"
53+
- name: INFO_MEM_CPU
54+
desc: "System memory utilization associated with virtual function"
55+
- name: INFO_MEM_GPU
56+
desc: "Device memory utilization associated with virtual function"
57+
- name: INFO_ENGINE
58+
desc: 'Engine utilization associated with virtual function'
59+
--- #--------------------------------------------------------------------------
60+
type: struct
61+
desc: "Virtual function management properties (deprecated)"
62+
version: "1.9"
63+
class: $sVFManagement
64+
name: $s_vf_exp_properties_t
65+
base: $s_base_properties_t
66+
members:
67+
- type: $s_pci_address_t
68+
name: "address"
69+
desc: "[out] Virtual function BDF address"
70+
- type: $s_uuid_t
71+
name: uuid
72+
desc: "[out] universal unique identifier of the device"
73+
- type: $s_vf_info_util_exp_flags_t
74+
name: "flags"
75+
desc: "[out] utilization flags available. May be 0 or a valid combination of $s_vf_info_util_exp_flag_t."
76+
--- #--------------------------------------------------------------------------
77+
type: struct
78+
desc: "Provides memory utilization values for a virtual function (deprecated)"
79+
version: "1.9"
80+
class: $sVFManagement
81+
name: $s_vf_util_mem_exp_t
82+
base: $s_base_state_t
83+
members:
84+
- type: $s_vf_info_mem_type_exp_flags_t
85+
name: "memTypeFlags"
86+
desc: "[out] Memory type flags."
87+
- type: uint64_t
88+
name: "free"
89+
desc: "[out] Free memory size in bytes."
90+
- type: uint64_t
91+
name: "size"
92+
desc: "[out] Total allocatable memory in bytes."
93+
- type: uint64_t
94+
name: "timestamp"
95+
desc: "[out] Wall clock time from VF when value was sampled."
96+
--- #--------------------------------------------------------------------------
97+
type: struct
98+
desc: "Provides engine utilization values for a virtual function (deprecated)"
99+
version: "1.9"
100+
class: $sVFManagement
101+
name: $s_vf_util_engine_exp_t
102+
base: $s_base_state_t
103+
members:
104+
- type: $s_engine_group_t
105+
name: "type"
106+
desc: "[out] The engine group."
107+
- type: uint64_t
108+
name: "activeCounterValue"
109+
desc: "[out] Represents active counter."
110+
- type: uint64_t
111+
name: "samplingCounterValue"
112+
desc: "[out] Represents counter value when activeCounterValue was sampled."
113+
- type: uint64_t
114+
name: "timestamp"
115+
desc: "[out] Wall clock time when the activeCounterValue was sampled."
30116
--- #--------------------------------------------------------------------------
31117
type: struct
32118
desc: "Virtual function management capabilities"
@@ -49,7 +135,7 @@ type: struct
49135
desc: "Provides memory utilization values for a virtual function"
50136
version: "1.10"
51137
class: $sVFManagement
52-
name: $s_vf_util_mem_exp_t
138+
name: $s_vf_util_mem_exp2_t
53139
base: $s_base_state_t
54140
members:
55141
- type: $s_mem_loc_t
@@ -63,9 +149,9 @@ type: struct
63149
desc: "Provides engine utilization values for a virtual function"
64150
details:
65151
- "Percent utilization is calculated by taking two snapshots (s1, s2) and using the equation: %util = (s2.activeCounterValue - s1.activeCounterValue) / (s2.samplingCounterValue - s1.samplingCounterValue)"
66-
version: "1.9"
152+
version: "1.10"
67153
class: $sVFManagement
68-
name: $s_vf_util_engine_exp_t
154+
name: $s_vf_util_engine_exp2_t
69155
base: $s_base_state_t
70156
members:
71157
- type: $s_engine_group_t
@@ -82,6 +168,142 @@ type: function
82168
desc: "Get handle of virtual function modules"
83169
version: "1.9"
84170
class: $sDevice
171+
name: EnumActiveVFExp
172+
details:
173+
- "1.11" : "[DEPRECATED] No longer supported. Use $sDeviceEnumEnabledVFExp."
174+
- "The application may call this function from simultaneous threads."
175+
- "The implementation of this function should be lock-free."
176+
params:
177+
- type: $s_device_handle_t
178+
name: hDevice
179+
desc: "[in] Sysman handle of the device."
180+
- type: "uint32_t*"
181+
name: pCount
182+
desc: |
183+
[in,out] pointer to the number of components of this type.
184+
if count is zero, then the driver shall update the value with the total number of components of this type that are available.
185+
if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.
186+
- type: "$s_vf_handle_t*"
187+
name: phVFhandle
188+
desc: |
189+
[in,out][optional][range(0, *pCount)] array of handle of components of this type.
190+
if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.
191+
--- #--------------------------------------------------------------------------
192+
type: function
193+
desc: "Get virtual function management properties"
194+
version: "1.9"
195+
class: $sVFManagement
196+
name: GetVFPropertiesExp
197+
details:
198+
- "1.11": "[DEPRECATED] No longer supported. Use $sVFManagementGetVFCapabilitiesExp."
199+
- "The application may call this function from simultaneous threads."
200+
- "The implementation of this function should be lock-free."
201+
params:
202+
- type: $s_vf_handle_t
203+
name: hVFhandle
204+
desc: "[in] Sysman handle for the VF component."
205+
- type: $s_vf_exp_properties_t*
206+
name: pProperties
207+
desc: "[in,out] Will contain VF properties."
208+
--- #--------------------------------------------------------------------------
209+
type: function
210+
desc: "Get memory activity stats for each available memory types associated with Virtual Function (VF)"
211+
version: "1.9"
212+
class: $sVFManagement
213+
name: GetVFMemoryUtilizationExp
214+
details:
215+
- "1.11": "[DEPRECATED] No longer supported. Use $sVFManagementGetVFMemoryUtilizationExp2."
216+
- "The application may call this function from simultaneous threads."
217+
- "The implementation of this function should be lock-free."
218+
params:
219+
- type: $s_vf_handle_t
220+
name: hVFhandle
221+
desc: "[in] Sysman handle for the component."
222+
- type: "uint32_t*"
223+
name: pCount
224+
desc: |
225+
[in,out] Pointer to the number of VF memory stats descriptors.
226+
- if count is zero, the driver shall update the value with the total number of memory stats available.
227+
- if count is greater than the total number of memory stats available, the driver shall update the value with the correct number of memory stats available.
228+
- The count returned is the sum of number of VF instances currently available and the PF instance.
229+
- type: $s_vf_util_mem_exp_t*
230+
name: pMemUtil
231+
desc: |
232+
[in,out][optional][range(0, *pCount)] array of memory group activity counters.
233+
- if count is less than the total number of memory stats available, then driver shall only retrieve that number of stats.
234+
- the implementation shall populate the vector pCount-1 number of VF memory stats.
235+
--- #--------------------------------------------------------------------------
236+
type: function
237+
desc: "Get engine activity stats for each available engine group associated with Virtual Function (VF)"
238+
version: "1.9"
239+
class: $sVFManagement
240+
name: GetVFEngineUtilizationExp
241+
details:
242+
- "1.11": "[DEPRECATED] No longer supported. Use $sVFManagementGetVFEngineUtilizationExp2."
243+
- "The application may call this function from simultaneous threads."
244+
- "The implementation of this function should be lock-free."
245+
params:
246+
- type: $s_vf_handle_t
247+
name: hVFhandle
248+
desc: "[in] Sysman handle for the component."
249+
- type: "uint32_t*"
250+
name: pCount
251+
desc: |
252+
[in,out] Pointer to the number of VF engine stats descriptors.
253+
- if count is zero, the driver shall update the value with the total number of engine stats available.
254+
- if count is greater than the total number of engine stats available, the driver shall update the value with the correct number of engine stats available.
255+
- The count returned is the sum of number of VF instances currently available and the PF instance.
256+
- type: $s_vf_util_engine_exp_t*
257+
name: pEngineUtil
258+
desc: |
259+
[in,out][optional][range(0, *pCount)] array of engine group activity counters.
260+
- if count is less than the total number of engine stats available, then driver shall only retrieve that number of stats.
261+
- the implementation shall populate the vector pCount-1 number of VF engine stats.
262+
--- #--------------------------------------------------------------------------
263+
type: function
264+
desc: "Configure utilization telemetry enabled or disabled associated with Virtual Function (VF)"
265+
version: "1.9"
266+
class: $sVFManagement
267+
name: SetVFTelemetryModeExp
268+
details:
269+
- "1.11": "[DEPRECATED] No longer supported."
270+
- "The application may call this function from simultaneous threads."
271+
- "The implementation of this function should be lock-free."
272+
params:
273+
- type: $s_vf_handle_t
274+
name: hVFhandle
275+
desc: "[in] Sysman handle for the component."
276+
- type: $s_vf_info_util_exp_flags_t
277+
name: "flags"
278+
desc: "[in] utilization flags to enable or disable. May be 0 or a valid combination of $s_vf_info_util_exp_flag_t."
279+
- type: $x_bool_t
280+
name: "enable"
281+
desc: "[in] Enable utilization telemetry."
282+
--- #--------------------------------------------------------------------------
283+
type: function
284+
desc: "Set sampling interval to monitor for a particular utilization telemetry associated with Virtual Function (VF)"
285+
version: "1.9"
286+
class: $sVFManagement
287+
name: SetVFTelemetrySamplingIntervalExp
288+
details:
289+
- "1.11": "[DEPRECATED] No longer supported."
290+
- "The application may call this function from simultaneous threads."
291+
- "The implementation of this function should be lock-free."
292+
params:
293+
- type: $s_vf_handle_t
294+
name: hVFhandle
295+
desc: "[in] Sysman handle for the component."
296+
- type: $s_vf_info_util_exp_flags_t
297+
name: "flag"
298+
desc: "[in] utilization flags to set sampling interval. May be 0 or a valid combination of $s_vf_info_util_exp_flag_t."
299+
- type: uint64_t
300+
name: "samplingInterval"
301+
desc: "[in] Sampling interval value."
302+
--- #--------------------------------------------------------------------------
303+
type: function
304+
desc: "Get handle of virtual function modules"
305+
version: "1.10"
306+
class: $sDevice
85307
name: EnumEnabledVFExp
86308
details:
87309
- "The application may call this function from simultaneous threads."
@@ -120,9 +342,9 @@ params:
120342
--- #--------------------------------------------------------------------------
121343
type: function
122344
desc: "Get memory activity stats for each available memory types associated with Virtual Function (VF)"
123-
version: "1.9"
345+
version: "1.10"
124346
class: $sVFManagement
125-
name: GetVFMemoryUtilizationExp
347+
name: GetVFMemoryUtilizationExp2
126348
details:
127349
- "The application may call this function from simultaneous threads."
128350
- "The implementation of this function should be lock-free."
@@ -137,7 +359,7 @@ params:
137359
[in,out] Pointer to the number of VF memory stats descriptors.
138360
- if count is zero, the driver shall update the value with the total number of memory stats available.
139361
- if count is greater than the total number of memory stats available, the driver shall update the value with the correct number of memory stats available.
140-
- type: $s_vf_util_mem_exp_t*
362+
- type: $s_vf_util_mem_exp2_t*
141363
name: pMemUtil
142364
desc: |
143365
[in,out][optional][range(0, *pCount)] array of memory group activity counters.
@@ -146,9 +368,9 @@ params:
146368
--- #--------------------------------------------------------------------------
147369
type: function
148370
desc: "Get engine activity stats for each available engine group associated with Virtual Function (VF)"
149-
version: "1.9"
371+
version: "1.10"
150372
class: $sVFManagement
151-
name: GetVFEngineUtilizationExp
373+
name: GetVFEngineUtilizationExp2
152374
details:
153375
- "The application may call this function from simultaneous threads."
154376
- "The implementation of this function should be lock-free."
@@ -163,7 +385,7 @@ params:
163385
[in,out] Pointer to the number of VF engine stats descriptors.
164386
- if count is zero, the driver shall update the value with the total number of engine stats available.
165387
- if count is greater than the total number of engine stats available, the driver shall update the value with the correct number of engine stats available.
166-
- type: $s_vf_util_engine_exp_t*
388+
- type: $s_vf_util_engine_exp2_t*
167389
name: pEngineUtil
168390
desc: |
169391
[in,out][optional][range(0, *pCount)] array of engine group activity counters.

0 commit comments

Comments
 (0)