Skip to content

Commit 3d598ab

Browse files
AhmedAmraniAkdiAhmedAmraniAkdi
authored
publish cl_img_safety_mechanisms extension (#1408)
* publish cl_img_safety_mechanisms extension * Add Types entry for cl_context_safety_properties_img, bump revision version to 1.0.0
1 parent e658e7b commit 3d598ab

3 files changed

Lines changed: 274 additions & 5 deletions

File tree

‎extensions/cl_img_safety_mechanisms.asciidoc‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
// Copyright 2018-2025 The Khronos Group. This work is licensed under a
2+
// Creative Commons Attribution 4.0 International License; see
3+
// http://creativecommons.org/licenses/by/4.0/
4+
5+
:data-uri:
6+
:icons: font
7+
include::../config/attribs.txt[]
8+
:source-highlighter: coderay
9+
10+
= cl_img_safety_mechanisms
11+
12+
== Name Strings
13+
14+
`cl_img_safety_mechanisms` +
15+
`cl_img_workgroup_protection` +
16+
`cl_img_enhanced_event_execution_status`
17+
18+
`cl_img_safety_mechanisms` will be reported if `cl_img_workgroup_protection` or `cl_img_enhanced_event_execution_status` is present.
19+
20+
== Contact
21+
22+
Imagination Technologies Developer Forum: +
23+
https://forums.imgtec.com/
24+
25+
Ahmed Amrani Akdi, Imagination Technologies (Ahmed.Akdi 'at' imgtec.com)
26+
27+
== Contributors
28+
29+
Jeremy Kemp, Imagination Technologies
30+
Ahmed Amrani Akdi, Imagination Technologies
31+
32+
== Notice
33+
34+
Copyright (c) 2020-2025 Imagination Technologies Ltd. All Rights Reserved.
35+
36+
== Status
37+
38+
Shipping.
39+
40+
== Version
41+
42+
Built On: {docdate} +
43+
Version: 1.0.0
44+
45+
== Dependencies
46+
47+
This extension is written against the OpenCL Specification
48+
Version 3.0.5.
49+
50+
This extension requires OpenCL 3.0 or later.
51+
52+
== Overview
53+
54+
This extension allows applications to enable safety features to help detect and recover from faults that may result in unexpected behaviour.
55+
56+
== New API Types
57+
58+
[source,c]
59+
----
60+
typedef cl_bitfield cl_context_safety_properties_img;
61+
----
62+
63+
== New API Enums
64+
65+
Additional _properties_ values that can be passed to `clCreateContext` or `clCreateContextFromType`:
66+
67+
[source,c]
68+
----
69+
#define CL_CONTEXT_SAFETY_PROPERTIES_IMG 0x40D9
70+
----
71+
72+
Valid property values for `cl_context_safety_properties_img` where _properties_ is `CL_CONTEXT_SAFETY_PROPERTIES_IMG` when passed to `clCreateContext` or `clCreateContextFromType`:
73+
74+
[source,c]
75+
----
76+
#define CL_CONTEXT_WORKGROUP_PROTECTION_IMG (1 << 0)
77+
#define CL_CONTEXT_ENHANCED_EVENT_EXECUTION_STATUS_IMG (1 << 1)
78+
----
79+
80+
Additional _param_name_ values that can be passed to `clGetDeviceInfo`:
81+
[source,c]
82+
----
83+
#define CL_DEVICE_WORKGROUP_PROTECTION_SVM_CAPABILITIES_IMG 0x40DA
84+
#define CL_DEVICE_WORKGROUP_PROTECTION_DEVICE_ENQUEUE_CAPABILITIES_IMG 0x40DB
85+
#define CL_DEVICE_SAFETY_MEM_SIZE_IMG 0x40DC
86+
----
87+
88+
Additional values that can be returned in _param_value_ when *clGetEventInfo* is called with `CL_EVENT_COMMAND_EXECUTION_STATUS` given as _param_name_:
89+
90+
[source,c]
91+
----
92+
#define CL_ECC_RECOVERED_IMG 0x40DD
93+
#define CL_PAGE_FAULT_IMG -1127
94+
#define CL_SAFETY_FAULT_IMG -1128
95+
#define CL_GENERAL_FAULT_IMG -1129
96+
#define CL_ECC_UNRECOVERED_IMG -1130
97+
----
98+
99+
== Modifications to the OpenCL API Specification
100+
101+
(Modify Section 4.2, *Querying Devices*) ::
102+
+
103+
--
104+
(Add the following to Table 5. List of supported _param_names_ by `clGetDeviceInfo`) ::
105+
+
106+
[cols="1,1,4",options="header"]
107+
|====
108+
| Device Info
109+
| Return Type
110+
| Description
111+
112+
| `CL_DEVICE_WORKGROUP_PROTECTION_SVM_CAPABILITIES_IMG`
113+
Missing before version 2.0.
114+
| `cl_device_svm_capabilities`
115+
116+
| Describes the various shared virtual memory (SVM) memory allocation types the device supports when operating with workgroup protection enabled. Contexts created with the `CL_CONTEXT_WORKGROUP_PROTECTION_IMG` property value are considered to have workgroup protection enabled. This parameter is present when the `cl_img_workgroup_protection` extension is present. This is a bit-field that describes a combination of the following values:
117+
118+
`CL_DEVICE_SVM_COARSE_GRAIN_BUFFER` - Support for coarse-grain buffer sharing using `clSVMAlloc`. Memory consistency is guaranteed at synchronization points and the host must use calls to clEnqueueMapBuffer and `clEnqueueUnmapMemObject`.
119+
`CL_DEVICE_SVM_FINE_GRAIN_BUFFER` - Support for fine-grain buffer sharing using `clSVMAlloc`. Memory consistency is guaranteed at synchronization points without need for clEnqueueMapBuffer and `clEnqueueUnmapMemObject`.
120+
`CL_DEVICE_SVM_FINE_GRAIN_SYSTEM` - Support for sharing the host’s entire virtual memory including memory allocated using `malloc`. Memory consistency is guaranteed at synchronization points.
121+
`CL_DEVICE_SVM_ATOMICS` - Support for the OpenCL 2.0 atomic operations that provide memory consistency across the host and all OpenCL devices supporting fine-grain SVM allocations.
122+
123+
The mandated minimum capability for an OpenCL 2.0, 2.1, or 2.2 device is `CL_DEVICE_SVM_COARSE_GRAIN_BUFFER`.
124+
125+
For other device versions there is no mandated minimum capability.
126+
127+
|`CL_DEVICE_WORKGROUP_PROTECTION_DEVICE_ENQUEUE_CAPABILITIES_IMG`
128+
129+
|`cl_device_device_enqueue_capabilities`
130+
| May return 0, indicating that device does not support device-side enqueue and on-device queues when operating with workgroup protection enabled. Otherwise, describes device-side enqueue capabilities of the device. This is a bit-field that describes one or more of the following values:
131+
132+
`CL_DEVICE_QUEUE_SUPPORTED` - Device supports device-side enqueue and on-device queues.
133+
`CL_DEVICE_QUEUE_REPLACEABLE_DEFAULT` - Device supports a replaceable default on-device queue.
134+
135+
If `CL_DEVICE_QUEUE_REPLACEABLE_DEFAULT` is set, `CL_DEVICE_QUEUE_SUPPORTED` must also be set.
136+
137+
Devices that set `CL_DEVICE_QUEUE_SUPPORTED` for `CL_DEVICE_WORKGROUP_PROTECTION_DEVICE_ENQUEUE_CAPABILITIES_IMG` must also return `CL_TRUE` for `CL_DEVICE_GENERIC_ADDRESS_SPACE_SUPPORT`.
138+
139+
|`CL_DEVICE_SAFETY_MEM_SIZE_IMG`
140+
141+
|`cl_ulong`
142+
143+
| May return 0, indicating that device does not support workgroup protection. Otherwise, returns the size of the memory where memory objects are allocated when operating with workgroup protection enabled.
144+
|====
145+
--
146+
147+
(Modify Section 4.4, *Contexts*) ::
148+
+
149+
--
150+
151+
(Add the following to Table 7. List of supported context creation properties by `clCreateContext`) ::
152+
+
153+
[cols="1,1,4",options="header"]
154+
|====
155+
| Context Property
156+
| Property Value
157+
| Description
158+
159+
| `CL_CONTEXT_SAFETY_PROPERTIES_IMG`
160+
| `cl_context_safety_properties_img`
161+
| This bitfield allows a context to be created with a range of safety mechanisms that will apply to all commands enqueued to the context when the `cl_img_safety_mechanisms` extension is present.
162+
163+
If `CL_CONTEXT_WORKGROUP_PROTECTION_IMG` is specified, all kernel commands enqueued to this context will enable error checking at the workgroup level to verify that all memory operations within each workgroup workgroup perform as expected. This may effect performance. This property requires the `cl_img_workgroup_protection` extension to be present.
164+
165+
If `CL_CONTEXT_ENHANCED_EVENT_EXECUTION_STATUS_IMG` is specified, additional event execution status' will be available. This property requires the `cl_img_enhanced_event_execution_status` extension to be present.
166+
--
167+
168+
(Modify Section 5.11, *Event Objects*) ::
169+
+
170+
--
171+
172+
(Add the following to the second paragraph) ::
173+
+
174+
When the `cl_img_safety_mechanisms` extension is present, an event object must be passed to _event_ for every clEnqueue* call where the _context_ associated with _command_queue_ was created with the `CL_CONTEXT_WORKGROUP_PROTECTION_IMG` property value. It is strongly recommended that the execution state of every event object is queried to check for completeness or errors. Not passing a valid event object to _event_ will to cause `clEnqueue*` to return `CL_INVALID_EVENT`.
175+
176+
(Add the following bullets to _The execution status of an enqueued command at any given point in time can be one of the following:_) ::
177+
+
178+
* `CL_PAGE_FAULT_IMG` This indicates that the command was present during execution that resulted in a page fault and is an error code. This status can only be reported if the `cl_img_enhanced_event_execution_status` extension is present.
179+
* `CL_SAFETY_FAULT_IMG` This indicates that the command was present during execution that resulted in workgroup protection identifying an error with the command and is an error code. This status can only be reported if the the associated _context_ was created with the `CL_CONTEXT_WORKGROUP_PROTECTION_IMG` property value, and the `cl_img_enhanced_event_execution_status` and `cl_img_workgroup_protection` extensions are present.
180+
* `CL_GENERAL_FAULT_IMG` This indicates that the command was present during execution that resulted in an error with the command and is an error code. This status can only be reported if the `cl_img_enhanced_event_execution_status` extension is present.
181+
* `CL_ECC_RECOVERED_IMG` This indicates that the command has successfully completed and is considered to have the same semantics as `CL_COMPLETE`. It also indicates that the command was present during execution that resulted in an ECC event where memory was successfully self-corrected. This status can only be reported when `CL_DEVICE_ERROR_CORRECTION_SUPPORT` is `CL_TRUE` and the `cl_img_enhanced_event_execution_status` extension is present. This is not an error code.
182+
* `CL_ECC_UNRECOVERED_IMG` This indicates that the command was present during execution that resulted in an ECC event where memory was not successfully self-corrected and is an error code. This status can only be reported when `CL_DEVICE_ERROR_CORRECTION_SUPPORT` is `CL_TRUE` and the `cl_img_enhanced_event_execution_status` extension is present.
183+
184+
(Add the following to Table 36. List of supported param_names by clGetEventInfo) ::
185+
+
186+
[cols="1,1,4",options="header"]
187+
|====
188+
| Event Info
189+
| Return Type
190+
| Info. returned in _param_value_
191+
192+
| `CL_EVENT_COMMAND_EXECUTION_STATUS`
193+
| `cl_int`
194+
| `CL_PAGE_FAULT_IMG` (during execution, the command was present during a page fault and should be considered to have failed execution)
195+
196+
`CL_SAFETY_FAULT_IMG` (during execution, this command was present when workgroup protection detected an error and should be considered to have failed execution)
197+
198+
`CL_GENERAL_FAULT_IMG` (during execution, the command was present during a general fault and should be considered to have failed execution)
199+
200+
`CL_ECC_RECOVERED_IMG` (during execution, the command was present during an ECC event where the memory successfully self-corrected. This can be considered to have the same semantics as `CL_COMPLETE` and should not be considered to have failed execution)
201+
202+
`CL_ECC_UNRECOVERED_IMG` (during execution, the command was present during an ECC event where the memory did not successfully self-correct and should be considered to have failed execution)
203+
|====
204+
--
205+
206+
== Interactions with Other Extensions
207+
208+
If `cl_khr_priority_hints` is supported then any command queue created with either `clCreateCommandQueue` or `clCreateCommandQueueWithProperties` where _context_ has the `CL_CONTEXT_SAFETY_PROPERTIES_IMG` and `CL_QUEUE_PRIORITY_KHR` properties then the requested priority will be ignored.
209+
210+
== Issues
211+
212+
== Version History
213+
214+
[cols="5,15,15,70"]
215+
[grid="rows"]
216+
[options="header"]
217+
|====
218+
| Version | Date | Author | Changes
219+
| 1.0.0 | 2025-07-08 | Ahmed Amrani Akdi | *Updated to 1.0.0 version for publishing.*
220+
| 0.6.0 | 2025-05-02 | Ahmed Amrani Akdi | *Added `CL_DEVICE_SAFETY_MEM_SIZE_IMG`*
221+
| 0.5.0 | 2022-01-17 | Jeremy Kemp | *Added `CL_DEVICE_WORKGROUP_PROTECTION_DEVICE_ENQUEUE_CAPABILITIES_IMG`*
222+
| 0.4.0 | 2020-12-03 | Jeremy Kemp | *Added event execution status as extension. Tidy up*
223+
| 0.3.0 | 2020-11-25 | Jeremy Kemp | *Added SVM queries. Added new event status codes. Lots of additional updates and fixes*
224+
| 0.2.1 | 2020-11-06 | Jeremy Kemp | *Resolved Issue 3. Removed `cl_arm_import_memory` restriction*
225+
| 0.2.0 | 2020-10-09 | Jeremy Kemp | *Resolved Issue 3. Removed `cl_img_command_status_query`. Typo fixes*
226+
| 0.1.0 | 2020-10-02 | Jeremy Kemp | *Initial revision*
227+
|====

‎extensions/extensions.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ include::cl_img_memory_management.asciidoc[]
6969
<<<
7070
include::cl_img_mem_properties.asciidoc[]
7171
<<<
72+
include::cl_img_safety_mechanisms.asciidoc[]
73+
<<<
7274
include::cl_img_swap_ops.asciidoc[]
7375
<<<
7476
include::cl_img_use_gralloc_ptr.asciidoc[]

‎xml/cl.xml‎

Lines changed: 45 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ server's OpenCL/api-docs repository.
222222
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_device_enqueue_capabilities</name>;</type>
223223
<type category="define">typedef <type>cl_uint</type> <name>cl_mipmap_filter_mode_img</name>;</type>
224224
<type category="define">typedef <type>cl_bitfield</type> <name>cl_mem_alloc_flags_img</name>;</type>
225+
<type category="define">typedef <type>cl_bitfield</type> <name>cl_context_safety_properties_img</name>;</type>
225226
<type category="define">typedef <type>cl_uint</type> <name>cl_layer_info</name>;</type>
226227
<type category="define">typedef <type>cl_uint</type> <name>cl_layer_api_version</name>;</type>
227228
<type category="define">typedef <type>cl_uint</type> <name>cl_icdl_info</name>;</type>
@@ -693,7 +694,11 @@ server's OpenCL/api-docs repository.
693694
<enum value="-1124" name="CL_ERROR_RESERVED2_IMG"/>
694695
<enum value="-1125" name="CL_ERROR_RESERVED3_IMG"/>
695696
<enum value="-1126" name="CL_CANCELLED_IMG"/>
696-
<unused start="-1127" end="-1137"/>
697+
<enum value="-1127" name="CL_PAGE_FAULT_IMG"/>
698+
<enum value="-1128" name="CL_SAFETY_FAULT_IMG"/>
699+
<enum value="-1129" name="CL_GENERAL_FAULT_IMG"/>
700+
<enum value="-1130" name="CL_ECC_UNRECOVERED_IMG"/>
701+
<unused start="-1131" end="-1137"/>
697702
</enums>
698703

699704
<enums start="-1138" end="-1141" name="ErrorCodes.1138" vendor="Khronos" comment="For cl_khr_command_buffer related extensions">
@@ -1266,6 +1271,12 @@ server's OpenCL/api-docs repository.
12661271
<enum bitpos="4" name="CL_MEM_ALLOC_GPU_LOCAL_IMG"/>
12671272
<enum bitpos="5" name="CL_MEM_ALLOC_GPU_PRIVATE_IMG"/>
12681273
</enums>
1274+
1275+
<enums name="cl_context_safety_properties_img" vendor="IMG" type="bitmask">
1276+
<enum bitpos="0" name="CL_CONTEXT_WORKGROUP_PROTECTION_IMG"/>
1277+
<enum bitpos="1" name="CL_CONTEXT_ENHANCED_EVENT_EXECUTION_STATUS_IMG"/>
1278+
</enums>
1279+
12691280
<enums name="cl_device_scheduling_controls_capabilities_arm" vendor="Arm" type="bitmask">
12701281
<enum bitpos="0" name="CL_DEVICE_SCHEDULING_KERNEL_BATCHING_ARM"/>
12711282
<enum bitpos="1" name="CL_DEVICE_SCHEDULING_WORKGROUP_BATCH_SIZE_ARM"/>
@@ -2142,10 +2153,12 @@ server's OpenCL/api-docs repository.
21422153
<enum value="0x40D6" name="CL_COMMAND_GENERATE_MIPMAP_IMG"/>
21432154
<enum value="0x40D7" name="CL_MEM_ALLOC_FLAGS_IMG"/>
21442155
<enum value="0x40D8" name="CL_DEVICE_MEMORY_CAPABILITIES_IMG"/>
2145-
<enum value="0x40D9" name="CL_RESERVED0_IMG"/>
2146-
<enum value="0x40DA" name="CL_RESERVED1_IMG"/>
2147-
<enum value="0x40DB" name="CL_RESERVED2_IMG"/>
2148-
<unused start="0x40DC" end="0x40DF"/>
2156+
<enum value="0x40D9" name="CL_CONTEXT_SAFETY_PROPERTIES_IMG"/>
2157+
<enum value="0x40DA" name="CL_DEVICE_WORKGROUP_PROTECTION_SVM_CAPABILITIES_IMG"/>
2158+
<enum value="0x40DB" name="CL_DEVICE_WORKGROUP_PROTECTION_DEVICE_ENQUEUE_CAPABILITIES_IMG"/>
2159+
<enum value="0x40DC" name="CL_DEVICE_SAFETY_MEM_SIZE_IMG"/>
2160+
<enum value="0x40DD" name="CL_ECC_RECOVERED_IMG"/>
2161+
<unused start="0x40DE" end="0x40DF"/>
21492162
</enums>
21502163

21512164
<enums start="0x40E0" end="0x40EF" name="enums.40E0" vendor="Khronos SPIR WG" comment="Per Bugs 11309,11310">
@@ -6933,6 +6946,33 @@ server's OpenCL/api-docs repository.
69336946
<require comment="cl_device_info">
69346947
<enum name="CL_DEVICE_MEMORY_CAPABILITIES_IMG"/>
69356948
</require>
6949+
</extension>
6950+
<extension name="cl_img_safety_mechanisms" revision="1.0.0" supported="opencl">
6951+
<require>
6952+
<type name="CL/cl.h"/>
6953+
</require>
6954+
<require comment="cl_context_properties">
6955+
<enum name="CL_CONTEXT_SAFETY_PROPERTIES_IMG"/>
6956+
</require>
6957+
<require comment="Types">
6958+
<type name="cl_context_safety_properties_img"/>
6959+
</require>
6960+
<require comment="cl_context_safety_properties_img">
6961+
<enum name="CL_CONTEXT_WORKGROUP_PROTECTION_IMG"/>
6962+
<enum name="CL_CONTEXT_ENHANCED_EVENT_EXECUTION_STATUS_IMG"/>
6963+
</require>
6964+
<require comment="cl_device_info">
6965+
<enum name="CL_DEVICE_WORKGROUP_PROTECTION_SVM_CAPABILITIES_IMG"/>
6966+
<enum name="CL_DEVICE_WORKGROUP_PROTECTION_DEVICE_ENQUEUE_CAPABILITIES_IMG"/>
6967+
<enum name="CL_DEVICE_SAFETY_MEM_SIZE_IMG"/>
6968+
</require>
6969+
<require comment="Error codes">
6970+
<enum name="CL_ECC_RECOVERED_IMG"/>
6971+
<enum name="CL_PAGE_FAULT_IMG"/>
6972+
<enum name="CL_SAFETY_FAULT_IMG"/>
6973+
<enum name="CL_GENERAL_FAULT_IMG"/>
6974+
<enum name="CL_ECC_UNRECOVERED_IMG"/>
6975+
</require>
69366976
</extension>
69376977
<extension name="cl_arm_controlled_kernel_termination" revision="0.0.0" supported="opencl">
69386978
<require comment="Types">

0 commit comments

Comments
 (0)