Skip to content

Commit b97930a

Browse files
jabradjabrad
authored
Add parameterized append functions with pNext (#427)
* Add parameterized append functions with pNext Add three new "WithParameters" variants of append functions that include a pNext parameter for future extensibility: - zeCommandListAppendMemoryCopyWithParameters - zeCommandListAppendMemoryFillWithParameters - zeCommandListImmediateAppendCommandListsWithParameters Deprecate zeCommandListImmediateAppendCommandListsExp as it lacks pNext. Part of Level Zero API version 1.16. Signed-off-by: Radoslaw Jablonski <radoslaw.jablonski@intel.com> * Add parameterized append functions with pNext Add three new "WithParameters" variants of append functions that include a pNext parameter for future extensibility: - zeCommandListAppendMemoryCopyWithParameters - zeCommandListAppendMemoryFillWithParameters - zeCommandListImmediateAppendCommandListsWithParameters Deprecate zeCommandListImmediateAppendCommandListsExp as it lacks pNext. Part of Level Zero API version 1.16. Signed-off-by: Radoslaw Jablonski <radoslaw.jablonski@intel.com> --------- Signed-off-by: Radoslaw Jablonski <radoslaw.jablonski@intel.com>
1 parent 7ec0905 commit b97930a

3 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎scripts/core/EXT_Exp_ImmediateCommandListAppend.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ from templates import helper as th
1414
Immediate Command List Append Extension
1515
=========================================
1616

17+
This experimental extension is deprecated since version 1.16.
18+
Please use ${x}CommandListImmediateAppendCommandListsWithParameters instead.
19+
1720
API
1821
----
1922

‎scripts/core/copy.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,55 @@ returns:
5353
- "`(nullptr == phWaitEvents) && (0 < numWaitEvents)`"
5454
--- #--------------------------------------------------------------------------
5555
type: function
56+
desc: "Copies host, device, or shared memory with additional parameters."
57+
version: "1.16"
58+
class: $xCommandList
59+
name: AppendMemoryCopyWithParameters
60+
details:
61+
- "The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created."
62+
- "The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution."
63+
- "The application must ensure the events are accessible by the device on which the command list was created."
64+
- "The application must ensure the command list and events were created, and the memory was allocated, on the same context."
65+
- "The application must **not** call this function from simultaneous threads with the same command list handle."
66+
- "The implementation of this function should be lock-free."
67+
analogue:
68+
- "**clEnqueueCopyBuffer**"
69+
- "**clEnqueueReadBuffer**"
70+
- "**clEnqueueWriteBuffer**"
71+
- "**clEnqueueSVMMemcpy**"
72+
params:
73+
- type: $x_command_list_handle_t
74+
name: hCommandList
75+
desc: "[in] handle of command list"
76+
- type: "void*"
77+
name: dstptr
78+
desc: "[in] pointer to destination memory to copy to"
79+
- type: "const void*"
80+
name: srcptr
81+
desc: "[in] pointer to source memory to copy from"
82+
- type: size_t
83+
name: size
84+
desc: "[in] size in bytes to copy"
85+
- type: "const void*"
86+
name: pNext
87+
desc: "[in][optional] additional extensions passed to the function"
88+
- type: $x_event_handle_t
89+
name: hSignalEvent
90+
desc: "[in][optional] handle of the event to signal on completion"
91+
- type: uint32_t
92+
name: numWaitEvents
93+
desc: "[in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`"
94+
- type: "$x_event_handle_t*"
95+
name: phWaitEvents
96+
desc: "[in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching"
97+
returns:
98+
- $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT
99+
- $X_RESULT_ERROR_INVALID_SIZE:
100+
- "`(nullptr == phWaitEvents) && (0 < numWaitEvents)`"
101+
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
102+
- "an extension passed via pNext is not supported"
103+
--- #--------------------------------------------------------------------------
104+
type: function
56105
desc: "Initializes host, device, or shared memory."
57106
class: $xCommandList
58107
name: AppendMemoryFill
@@ -100,6 +149,60 @@ returns:
100149
- $X_RESULT_ERROR_INVALID_SIZE:
101150
- "`(nullptr == phWaitEvents) && (0 < numWaitEvents)`"
102151
--- #--------------------------------------------------------------------------
152+
type: function
153+
desc: "Initializes host, device, or shared memory with additional parameters."
154+
version: "1.16"
155+
class: $xCommandList
156+
name: AppendMemoryFillWithParameters
157+
details:
158+
- "The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created."
159+
- "The implementation must not access the memory pointed to by ptr as it is free to be modified by either the Host or device up until execution."
160+
- "The ptr must be aligned to pattern_size."
161+
- "The value to initialize memory to is described by the pattern and the pattern size."
162+
- "The pattern size must be a power-of-two and less than or equal to the `maxMemoryFillPatternSize` member of $x_command_queue_group_properties_t."
163+
- "The application must ensure the events are accessible by the device on which the command list was created."
164+
- "The application must ensure the command list and events were created, and the memory was allocated, on the same context."
165+
- "The application must **not** call this function from simultaneous threads with the same command list handle."
166+
- "The implementation of this function should be lock-free."
167+
analogue:
168+
- "**clEnqueueFillBuffer**"
169+
- "**clEnqueueSVMMemFill**"
170+
params:
171+
- type: $x_command_list_handle_t
172+
name: hCommandList
173+
desc: "[in] handle of command list"
174+
- type: "void*"
175+
name: ptr
176+
desc: "[in] pointer to memory to initialize"
177+
- type: "const void*"
178+
name: pattern
179+
desc: "[in] pointer to value to initialize memory to"
180+
- type: size_t
181+
name: pattern_size
182+
desc: "[in] size in bytes of the value to initialize memory to"
183+
- type: size_t
184+
name: size
185+
desc: "[in] size in bytes to initialize"
186+
- type: "const void*"
187+
name: pNext
188+
desc: "[in][optional] additional extensions passed to the function"
189+
- type: $x_event_handle_t
190+
name: hSignalEvent
191+
desc: "[in][optional] handle of the event to signal on completion"
192+
- type: uint32_t
193+
name: numWaitEvents
194+
desc: "[in][optional] number of events to wait on before launching; must be 0 if `nullptr == phWaitEvents`"
195+
- type: "$x_event_handle_t*"
196+
name: phWaitEvents
197+
desc: "[in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching"
198+
returns:
199+
- $X_RESULT_ERROR_INVALID_SYNCHRONIZATION_OBJECT
200+
- $X_RESULT_ERROR_UNSUPPORTED_ALIGNMENT
201+
- $X_RESULT_ERROR_INVALID_SIZE:
202+
- "`(nullptr == phWaitEvents) && (0 < numWaitEvents)`"
203+
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
204+
- "an extension passed via pNext is not supported"
205+
--- #--------------------------------------------------------------------------
103206
type: struct
104207
desc: "Copy region descriptor"
105208
class: $xCommandList

‎scripts/core/immediateCommandListAppend.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ version: "1.9"
3131
class: $xCommandList
3232
name: ImmediateAppendCommandListsExp
3333
details:
34+
- "@deprecated since 1.16. Please use $xCommandListImmediateAppendCommandListsWithParameters."
3435
- "The application must call this function only with command lists created with $xCommandListCreateImmediate."
3536
- "The command lists passed to this function in the `phCommandLists` argument must be regular command lists (i.e. not immediate command lists)."
3637
- "The application may call this function from simultaneous threads."
@@ -58,3 +59,43 @@ params:
5859
desc: |
5960
[in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing appended command lists.
6061
- if not null, all wait events must be satisfied prior to the start of any appended command list(s)
62+
--- #--------------------------------------------------------------------------
63+
type: function
64+
desc: "Appends command lists to dispatch from an immediate command list with additional parameters."
65+
version: "1.16"
66+
class: $xCommandList
67+
name: ImmediateAppendCommandListsWithParameters
68+
details:
69+
- "The application must call this function only with command lists created with $xCommandListCreateImmediate."
70+
- "The command lists passed to this function in the `phCommandLists` argument must be regular command lists (i.e. not immediate command lists)."
71+
- "The application may call this function from simultaneous threads."
72+
- "The implementation of this function should be lock-free."
73+
params:
74+
- type: "$x_command_list_handle_t"
75+
name: hCommandListImmediate
76+
desc: "[in] handle of the immediate command list"
77+
- type: uint32_t
78+
name: numCommandLists
79+
desc: "[in] number of command lists"
80+
- type: "$x_command_list_handle_t*"
81+
name: phCommandLists
82+
desc: "[in][range(0, numCommandLists)] handles of command lists"
83+
- type: "const void*"
84+
name: pNext
85+
desc: "[in][optional] additional extensions passed to the function"
86+
- type: $x_event_handle_t
87+
name: hSignalEvent
88+
desc: |
89+
[in][optional] handle of the event to signal on completion
90+
- if not null, this event is signaled after the completion of all appended command lists
91+
- type: uint32_t
92+
name: numWaitEvents
93+
desc: "[in][optional] number of events to wait on before executing appended command lists; must be 0 if nullptr == phWaitEvents"
94+
- type: "$x_event_handle_t*"
95+
name: phWaitEvents
96+
desc: |
97+
[in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing appended command lists.
98+
- if not null, all wait events must be satisfied prior to the start of any appended command list(s)
99+
returns:
100+
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
101+
- "an extension passed via pNext is not supported"

0 commit comments

Comments
 (0)