Skip to content

Commit 513d4d6

Browse files
zzdanowiczpbg-intel
zzdanowicz
authored and
pbg-intel
committed
add version 1.1 of mutable commands extension using interface functions
Signed-off-by: Zbigniew Zdanowicz <zbigniew.zdanowicz@intel.com>
1 parent cd9eb51 commit 513d4d6

3 files changed

Lines changed: 101 additions & 88 deletions

File tree

‎scripts/core/EXT_Exp_MutableCommandList.rst‎

Lines changed: 42 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -26,24 +26,24 @@ API
2626
* Structures
2727

2828
* ${x}_mutable_command_id_exp_desc_t
29-
* ${x}_mutable_command_id_kernel_instruction_exp_desc_t
3029
* ${x}_mutable_command_list_exp_properties_t
3130
* ${x}_mutable_command_list_exp_desc_t
3231
* ${x}_mutable_commands_exp_desc_t
3332
* ${x}_mutable_kernel_argument_exp_desc_t
3433
* ${x}_mutable_group_count_exp_desc_t
3534
* ${x}_mutable_group_size_exp_desc_t
3635
* ${x}_mutable_global_offset_exp_desc_t
37-
* ${x}_mutable_kernel_instruction_exp_desc_t
3836

3937
* ${x}_mutable_graph_argument_exp_desc_t
4038

4139
* Functions
4240

4341
* ${x}CommandListGetNextCommandIdExp
42+
* ${x}CommandListGetNextCommandIdWithKernelsExp
4443
* ${x}CommandListUpdateMutableCommandsExp
4544
* ${x}CommandListUpdateMutableCommandSignalEventExp
4645
* ${x}CommandListUpdateMutableCommandWaitEventsExp
46+
* ${x}CommandListUpdateMutableCommandKernelsExp
4747

4848

4949
======================
@@ -58,7 +58,7 @@ API
5858
5959
// Discover mutable command list properties
6060
${x}_mutable_command_list_exp_properties_t mutCmdListProps = {
61-
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_LIST_EXP_PROPERTIES, // stype
61+
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_LIST_EXP_PROPERTIES, // stype
6262
nullptr, // pNext
6363
0, // mutableCommandListFlags
6464
0 // mutableCommandFlags
@@ -111,7 +111,7 @@ API
111111
112112
// Get next command identifier
113113
${x}_mutable_command_id_exp_desc_t cmdIdDesc = {
114-
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_ID_EXP_DESC // stype
114+
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_ID_EXP_DESC, // stype
115115
nullptr, // pNext
116116
0 // flags
117117
};
@@ -137,10 +137,6 @@ The application may subsequently mutate specific commands, as follows:
137137

138138
.. parsed-literal::
139139
140-
// Check the implementation support for Kernel Argument and group count mutation
141-
assert(mutCmdListProps.mutableCommandFlags & ${X}_MUTABLE_COMMAND_EXP_FLAG_KERNEL_ARGUMENTS);
142-
assert(mutCmdListProps.mutableCommandFlags & ${X}_MUTABLE_COMMAND_EXP_FLAG_GROUP_COUNT);
143-
144140
// Prepare to modify group count
145141
${x}_group_count_t groupCount = {
146142
256, // groupCountX
@@ -149,7 +145,7 @@ The application may subsequently mutate specific commands, as follows:
149145
};
150146
151147
${x}_mutable_group_count_exp_desc_t groupCountDesc = {
152-
${X}_STRUCTURE_TYPE_MUTABLE_GROUP_COUNT_EXP_DESC, // stype
148+
${X}_STRUCTURE_TYPE_MUTABLE_GROUP_COUNT_EXP_DESC, // stype
153149
nullptr, // pNext
154150
commandId, // commandId
155151
&groupCount // pGroupCount
@@ -159,7 +155,7 @@ The application may subsequently mutate specific commands, as follows:
159155
int argValue = 1;
160156
161157
${x}_mutable_kernel_argument_exp_desc_t krnlArgDesc = {
162-
${X}_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC, // stype
158+
${X}_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC, // stype
163159
&groupCountDesc, // pNext
164160
commandId, // commandId
165161
0, // argIndex
@@ -169,7 +165,7 @@ The application may subsequently mutate specific commands, as follows:
169165
170166
// Prepare to update mutable commands
171167
${x}_mutable_commands_exp_desc_t desc = {
172-
${X}_STRUCTURE_TYPE_MUTABLE_COMMANDS_EXP_DESC, // stype
168+
${X}_STRUCTURE_TYPE_MUTABLE_COMMANDS_EXP_DESC, // stype
173169
&krnlArgDesc, // pNext
174170
0 // flags
175171
};
@@ -190,23 +186,18 @@ The application may subsequently mutate specific commands, as follows:
190186
${x}CommandListClose(hCommandList);
191187
192188
// ...
193-
Note, the command list must be explicitly closed after updating mutable commands and events. This informs the implementation that the application has finished with updates and is ready to submit the command list.
194189
195-
In preparation for kernel mutation user must provide all possible kernel mutations.
190+
191+
Note, the command list must be explicitly closed after updating mutable commands and events. This informs the implementation that the application has finished with updates and is ready to submit the command list.
192+
In preparation for kernel mutation user must provide all possible kernels for the command.
196193

197194
.. parsed-literal::
198195
199196
// define all possible kernels
200197
${x}_kernel_handle_t addKernel;
201-
${x}_kernel_handle_t copyKernel;
198+
${x}_kernel_handle_t mulKernel;
202199
203-
${x}_kernel_handle_t kernels[] = {addKernel, copyKernel};
204-
205-
${x}_mutable_command_id_kernel_instruction_exp_desc_t availableKernelsDesc = {
206-
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_ID_KERNEL_INSTRUCTION_EXP_DESC, // stype
207-
2, // numKernels
208-
kernels // phKernels
209-
};
200+
${x}_kernel_handle_t kernels[] = {addKernel, mulKernel};
210201
211202
// when users want kernel mutation, they need to explicitly state this, as 0 does not include kernel instruction mutation by default
212203
${x}_mutable_command_exp_flags_t mutationFlags =
@@ -217,56 +208,59 @@ In preparation for kernel mutation user must provide all possible kernel mutatio
217208
218209
// Get next command identifier
219210
${x}_mutable_command_id_exp_desc_t cmdIdDesc = {
220-
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_ID_EXP_DESC, // stype
221-
&availableKernelsDesc, // pNext
211+
${X}_STRUCTURE_TYPE_MUTABLE_COMMAND_ID_EXP_DESC, // stype
212+
nullptr, // pNext
222213
mutationFlags // flags
223214
};
224215
225-
// retrieve id for the append operation
216+
// retrieve id for the append operation and provide all possible kernels for this command
226217
uint64_t mutableKernelCommandId = 0;
227-
${x}CommandListGetNextCommandIdExp(hCommandList, &cmdIdDesc, &mutableKernelCommandId);
218+
${x}CommandListGetNextCommandIdWithKernelsExp(hCommandList, &cmdIdDesc, &mutableKernelCommandId, 2, kernels);
228219
229220
// Encode command into command list
230221
${x}CommandListAppendLaunchKernel(hCommandList, addKernel, &groupSize, nullptr, 0, nullptr);
231222
232223
// Close the command list
233224
${x}CommandListClose(hCommandList);
234225
235-
Mutation of kernel instructions must obey two rules:
236-
- kernel mutation descriptor must be attached as first for a given command id.
237-
- kernel mutation invalidates all kernel arguments and dispatch parameters, these must be provided for the new kernel.
226+
Mutation of kernels must obey two rules:
227+
- kernel handle mutation function must be called as first for a given command id
228+
- kernel mutation invalidates all kernel arguments and dispatch parameters, these must be provided for the new kernel
238229

239230
.. parsed-literal::
240231
232+
// Update mutable kernel for the command, switch from `addKernel` to `mulKernel`
233+
${x}CommandListUpdateMutableCommandKernelsExp(hCommandList, 1, &mutableKernelCommandId, &mulKernel);
234+
241235
// modify group count
242236
${x}_group_count_t groupCount = {
243-
32, // groupCountX
244-
1, // groupCountY
245-
1 // groupCountZ
237+
32, // groupCountX
238+
1, // groupCountY
239+
1 // groupCountZ
246240
};
247241
248242
${x}_mutable_group_count_exp_desc_t groupCountDesc = {
249-
${X}_STRUCTURE_TYPE_MUTABLE_GROUP_COUNT_EXP_DESC, // stype
250-
nullptr, // pNext
251-
mutableKernelCommandId, // commandId
252-
&groupCount // pGroupCount
243+
${X}_STRUCTURE_TYPE_MUTABLE_GROUP_COUNT_EXP_DESC, // stype
244+
nullptr, // pNext
245+
mutableKernelCommandId, // commandId
246+
&groupCount // pGroupCount
253247
};
254248
255249
${x}_mutable_group_size_exp_desc_t groupSizeDesc = {
256-
${X}_STRUCTURE_TYPE_MUTABLE_GROUP_SIZE_EXP_DESC, // stype
257-
&groupCountDesc, // pNext
258-
mutableKernelCommandId, // commandId
259-
32, // groupSizeX
260-
1, // groupSizeY
261-
1, // groupSizeZ
250+
${X}_STRUCTURE_TYPE_MUTABLE_GROUP_SIZE_EXP_DESC, // stype
251+
&groupCountDesc, // pNext
252+
mutableKernelCommandId, // commandId
253+
32, // groupSizeX
254+
1, // groupSizeY
255+
1, // groupSizeZ
262256
};
263257
264258
// Prepare to modify Kernel Argument
265259
int argValue = 1;
266-
void *usmPointer = newMemory;
260+
void *usmPointer;
267261
268262
${x}_mutable_kernel_argument_exp_desc_t krnlArgMemoryDesc = {
269-
${X}_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC, // stype
263+
${X}_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC, // stype
270264
&groupSizeDesc, // pNext
271265
mutableKernelCommandId, // commandId
272266
0, // argIndex
@@ -275,7 +269,7 @@ Mutation of kernel instructions must obey two rules:
275269
};
276270
277271
${x}_mutable_kernel_argument_exp_desc_t krnlArgScalarDesc = {
278-
${X}_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC, // stype
272+
${X}_STRUCTURE_TYPE_MUTABLE_KERNEL_ARGUMENT_EXP_DESC, // stype
279273
&krnlArgMemoryDesc, // pNext
280274
mutableKernelCommandId, // commandId
281275
1, // argIndex
@@ -293,12 +287,12 @@ Mutation of kernel instructions must obey two rules:
293287
294288
// Prepare to update mutable commands
295289
${x}_mutable_commands_exp_desc_t desc = {
296-
${X}_STRUCTURE_TYPE_MUTABLE_COMMANDS_EXP_DESC, // stype
297-
&krnlDesc, // pNext
298-
0 // flags
290+
${X}_STRUCTURE_TYPE_MUTABLE_COMMANDS_EXP_DESC, // stype
291+
&krnlArgScalarDesc, // pNext
292+
0 // flags
299293
};
300294
301-
// Update mutable commands
295+
// Update mutable kernel arguments and dispatch parameters for the command
302296
${x}CommandListUpdateMutableCommandsExp(hCommandList, &desc);
303297
304298
// Close the command list

‎scripts/core/common.yml‎

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -559,22 +559,14 @@ etors:
559559
desc: $x_image_pitched_exp_desc_t
560560
version: "1.9"
561561
value: "0x0002001F"
562-
- name: MUTABLE_KERNEL_INSTRUCTION_EXP_DESC
563-
desc: $x_mutable_kernel_instruction_exp_desc_t
564-
version: "1.10"
565-
value: "0x00020020"
566-
- name: MUTABLE_COMMAND_ID_KERNEL_INSTRUCTION_EXP_DESC
567-
desc: $x_mutable_command_id_kernel_instruction_exp_desc_t
568-
version: "1.10"
569-
value: "0x00020021"
570562
- name: MUTABLE_GRAPH_ARGUMENT_EXP_DESC
571563
desc: $x_mutable_graph_argument_exp_desc_t
572564
version: "1.10"
573-
value: "0x00020022"
565+
value: "0x00020020"
574566
- name: INIT_DRIVER_TYPE_DESC
575567
desc: $x_init_driver_type_desc_t
576568
version: "1.10"
577-
value: "0x00020023"
569+
value: "0x00020021"
578570
- name: COMMAND_GRAPH_EXP_DESC
579571
desc: $x_command_graph_exp_desc_t
580572
version: "2.0"

‎scripts/core/mutableCommandList.yml‎

Lines changed: 57 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -65,20 +65,6 @@ members:
6565
- must be 0 (default, equivalent to setting all flags bar kernel instruction), or a valid combination of $x_mutable_command_exp_flag_t
6666
- in order to include kernel instruction mutation, $X_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION must be explictly included
6767
--- #--------------------------------------------------------------------------
68-
type: struct
69-
desc: "Mutable all kernels command identifier descriptor"
70-
version: "1.10"
71-
class: $xCommandList
72-
name: $x_mutable_command_id_kernel_instruction_exp_desc_t
73-
base: $x_base_desc_t
74-
members:
75-
- type: uint32_t
76-
name: numKernels
77-
desc: "[in] number of kernels in array"
78-
- type: "$x_kernel_handle_t*"
79-
name: phKernels
80-
desc: "[in] array of kernel handles"
81-
--- #--------------------------------------------------------------------------
8268
type: enum
8369
desc: "Mutable command list flags"
8470
version: "1.9"
@@ -201,20 +187,6 @@ members:
201187
desc: "[in] global offset for Z dimension to use for this kernel"
202188
--- #--------------------------------------------------------------------------
203189
type: struct
204-
desc: "Mutable kernel descriptor"
205-
version: "1.10"
206-
class: $xCommandList
207-
name: $x_mutable_kernel_instruction_exp_desc_t
208-
base: $x_base_desc_t
209-
members:
210-
- type: uint64_t
211-
name: commandId
212-
desc: "[in] command identifier"
213-
- type: $x_kernel_handle_t
214-
name: hKernel
215-
desc: "[in] kernel handle to use for this append operation"
216-
--- #--------------------------------------------------------------------------
217-
type: struct
218190
desc: "Mutable graph argument descriptor"
219191
version: "1.10"
220192
class: $xCommandList
@@ -253,6 +225,33 @@ params:
253225
desc: "[out] pointer to mutable command identifier to be written"
254226
--- #--------------------------------------------------------------------------
255227
type: function
228+
desc: "Returns a unique command identifier for the next command to be appended to a command list. Provides possible kernel handles for kernel mutation when $X_MUTABLE_COMMAND_EXP_FLAG_KERNEL_INSTRUCTION flag is present."
229+
version: "1.10"
230+
class: $xCommandList
231+
name: GetNextCommandIdWithKernelsExp
232+
details:
233+
- "This function may only be called for a mutable command list."
234+
- "This function may not be called on a closed command list."
235+
- "This function may be called from simultaneous threads with the same command list handle."
236+
- "The implementation of this function should be lock-free."
237+
params:
238+
- type: $x_command_list_handle_t
239+
name: hCommandList
240+
desc: "[in] handle of the command list"
241+
- type: "const $x_mutable_command_id_exp_desc_t*"
242+
name: desc
243+
desc: "[in][out] pointer to mutable command identifier descriptor"
244+
- type: uint32_t
245+
name: numKernels
246+
desc: "[in][optional] number of entries on phKernels list"
247+
- type: "$x_kernel_handle_t*"
248+
name: phKernels
249+
desc: "[in][optional][range(0, numKernels)] list of kernels that user can switch between using $xCommandListUpdateMutableCommandKernelsExp call"
250+
- type: uint64_t*
251+
name: pCommandId
252+
desc: "[out] pointer to mutable command identifier to be written"
253+
--- #--------------------------------------------------------------------------
254+
type: function
256255
desc: "Updates mutable commands."
257256
version: "1.10"
258257
class: $xCommandList
@@ -273,8 +272,6 @@ params:
273272
returns:
274273
- $X_RESULT_ERROR_INVALID_ARGUMENT:
275274
- "Invalid kernel argument or not matching update descriptor provided"
276-
- $X_RESULT_ERROR_INVALID_KERNEL_HANDLE:
277-
- "Invalid kernel handle provided for the mutation kernel instruction operation"
278275
--- #--------------------------------------------------------------------------
279276
type: function
280277
desc: "Updates the signal event for a mutable command in a mutable command list."
@@ -330,3 +327,33 @@ params:
330327
returns:
331328
- $X_RESULT_ERROR_INVALID_SIZE:
332329
- "The `numWaitEvents` parameter does not match that of the original command."
330+
--- #--------------------------------------------------------------------------
331+
type: function
332+
desc: "Updates the kernel for a mutable command in a mutable command list."
333+
version: "1.10"
334+
class: $xCommandList
335+
name: UpdateMutableCommandKernelsExp
336+
details:
337+
- "This function may only be called for a mutable command list."
338+
- "The kernel handle must be from the provided list for given command id."
339+
- "The application must synchronize mutable command list execution before calling this function."
340+
- "The application must close a mutable command list after completing all updates."
341+
- "This function must not be called from simultaneous threads with the same command list handle."
342+
- "This function must be called before updating kernel arguments and dispatch parameters, when kernel is mutated."
343+
- "The implementation of this function should be lock-free."
344+
params:
345+
- type: $x_command_list_handle_t
346+
name: hCommandList
347+
desc: "[in] handle of the command list"
348+
- type: uint32_t
349+
name: numKernels
350+
desc: "[in] the number of kernels to update"
351+
- type: uint64_t*
352+
name: pCommandId
353+
desc: "[in][range(0, numKernels)] command identifier"
354+
- type: "$x_kernel_handle_t*"
355+
name: phKernels
356+
desc: "[in][range(0, numKernels)] handle of the kernel for a command identifier to switch to"
357+
returns:
358+
- $X_RESULT_ERROR_INVALID_KERNEL_HANDLE:
359+
- "Invalid kernel handle provided for the mutation kernel instruction operation."

0 commit comments

Comments
 (0)