Skip to content

Add cl_arm_memory_controls v0.2 extension #1640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kpet wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add cl_arm_memory_controls v0.2 extension #1640

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 214 additions & 0 deletions extensions/cl_arm_memory_controls.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,214 @@

:data-uri:
:icons: font
include::../config/attribs.txt[]
include::{generated}/api/api-dictionary-no-links.asciidoc[]
:source-highlighter: coderay

= cl_arm_memory_controls

== Name Strings

`cl_arm_memory_controls`

== Contact

Kevin Petit (kevin.petit 'at' arm.com)

== Contributors

Kevin Petit, Arm Ltd. +

== Notice

Copyright (c) 2025-2026 Arm Ltd.

== Status

Complete

== Version

Built On: {docdate} +
Version: 0.2.0

== Dependencies

This extension is written against the OpenCL Specification v3.0.19.

This extension requires OpenCL 3.0.

== Overview

This extension gives applications explicit control over some aspects of memory
management. It can be used for performance tuning or debugging.

== New API Enums

Accepted value for the _param_name_ parameter to *clGetDeviceInfo*:

[source,c]
----
CL_DEVICE_MEMORY_CONTROLS_CAPABILITIES_ARM 0x41F5

CL_DEVICE_MEMORY_CONTROLS_COHERENCY_ARM (1 << 0)
CL_DEVICE_MEMORY_CONTROLS_LOCAL_MEMORY_ARM (1 << 1)
----

Accepted value for the _properties_ parameter to *clCreateBufferWithProperties* and *clCreateImageWithProperties*:

[source,c]
----
CL_MEM_COHERENCY_ARM 0x41F6

CL_MEM_COHERENCY_INNER_SHAREABLE_ARM (1 << 0)
CL_MEM_COHERENCY_OUTER_SHAREABLE_ARM (1 << 1)
----

Accepted value for the _param_name_ parameter to *clSetKernelExecInfo*:

[source,c]
----
CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_ARM 0x41F7

typedef enum {
CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_GLOBAL_ARM = 1,
CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_COMPUTE_UNIT_ARM = 2,
CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_AUTO_ARM = 3,
} cl_kernel_exec_info_local_memory_backing_arm;
Comment on lines +74 to +78

@bashbaug bashbaug Oct 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, maybe not a big deal, but this does not exactly match what gets generated for the headers.

typedef cl_uint             cl_kernel_exec_info_local_memory_backing_arm;
...
/* cl_kernel_exec_info */
#define CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_GLOBAL_ARM 1
#define CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_COMPUTE_UNIT_ARM 2
#define CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_AUTO_ARM   3


CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_HASHING_ARM 0x41F8
----

== Modifications to the OpenCL API Specification

(Modify Section 4.2, *Querying Devices*) ::
+
--

(Add the following to Table 5, _Device Queries_) ::
+
--

[cols="1,1,4",options="header"]
|====
| cl_device_info
| Return Type
| Description

| {CL_DEVICE_MEMORY_CONTROLS_CAPABILITIES_ARM}
| {cl_device_memory_controls_capabilities_arm_TYPE}
| Returns a bitfield of the memory controls this device supports:
+
- {CL_DEVICE_MEMORY_CONTROLS_COHERENCY_ARM} is set when the device supports
{CL_MEM_COHERENCY_ARM}. +
- {CL_DEVICE_MEMORY_CONTROLS_LOCAL_MEMORY_ARM} is set when the device supports
{CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_ARM} and
{CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_HASHING_ARM}. +
|====

--
--

(Modify Section 5.2.1, *Creating Buffer Objects* and Section 5.3.1, *Creating Image Objects* ) ::
+
--

(Add the following to Table 18, _List of supported buffer creation properties_ and Table 22, _List of supported image creation properties_) ::
+
--
[cols="1,1,4",options="header"]
|====
| Property
| Property Value
| Description

| {CL_MEM_COHERENCY_ARM}
| {cl_mem_coherency_flags_arm_TYPE}
| Override the coherency settings selected by the implementation.
+
- {CL_MEM_COHERENCY_INNER_SHAREABLE_ARM}, when set, enables inner shareability
for the memory that backs the memory object. If it is not set, then inner
shareability is disabled. Inner shareability is always supported. +
- {CL_MEM_COHERENCY_OUTER_SHAREABLE_ARM}, when set, enables outer shareability
for the memory that backs the memory object. If it is not set, then outer
shareability is disabled. If it is set and one or more devices do not support
outer shareability then memory object creation will fail. If it is set then
{CL_MEM_COHERENCY_INNER_SHAREABLE_ARM} must be set. +
|====
--

(Add the following to the list of error conditions for *clCreateBufferWithProperties* and *clCreateImageWithProperties*)::
+
--
* {CL_INVALID_PROPERTY}
** if {CL_MEM_COHERENCY_ARM} with {CL_MEM_COHERENCY_OUTER_SHAREABLE_ARM} set is
included in _properties_ and one or more devices in the context do not support
outer shareability.
** if {CL_MEM_COHERENCY_ARM} is included in _properties_ with
{CL_MEM_COHERENCY_OUTER_SHAREABLE_ARM} set but {CL_MEM_COHERENCY_INNER_SHAREABLE_ARM}
not set.
** if {CL_MEM_COHERENCY_ARM} is included in _properties_ and _host_ptr_ is an SVM
pointer and {CL_MEM_USE_HOST_PTR} is set in _flags_.
--

--

(Modify Section 5.9, *Kernel Objects*) ::
+
--

(Add the following to Table 31, _List of param_values accepted by *clSetKernelExecInfo*_) ::
+
--
[cols="1,1,4",options="header"]
|====
| cl_kernel_exec_info
| Type
| Description

| {CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_ARM}
| {cl_kernel_exec_info_local_memory_backing_arm_TYPE}
| Selects the backing for local memory. Valid values are: +
+
- {CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_GLOBAL_ARM} specifies that local
memory is backed with global memory. +
- {CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_COMPUTE_UNIT_ARM} specifies that
local memory is backed by memory wihin the compute unit. +
- {CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_AUTO_ARM} specifies that the
implementation selects the backing for local memory. +

| {CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_HASHING_ARM}
| {cl_bool_TYPE}
| Enables or disables address hashing when local memory is backed within the
compute unit ({CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_COMPUTE_UNIT_ARM}
or {CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_AUTO_ARM}). This control
has no effect otherwise. +
+
- {CL_FALSE} specifies that address hashing is disabled. +
- {CL_TRUE} specifies that address hashing is enabled. +

|====
--

--

== Interactions with Other Extensions

None.

== Issues

None.

== Revision History

[cols="5,15,15,70"]
[grid="rows"]
[options="header"]
|====
| Version | Date | Author | Changes
| 0.2.0 | 2026-03-02 | Kévin Petit | Add support for local memory controls
| 0.1.0 | 2025-08-04 | Kévin Petit | Initial version
|====

2 changes: 2 additions & 0 deletions extensions/extensions.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ include::cl_ext_image_raw10_raw12.asciidoc[]
<<<
include::cl_arm_controlled_kernel_termination.asciidoc[]
<<<
include::cl_arm_memory_controls.asciidoc[]
<<<
include::cl_arm_printf.asciidoc[]
<<<
include::cl_arm_protected_memory_allocation.asciidoc[]
Expand Down
55 changes: 53 additions & 2 deletions xml/cl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,9 @@ server's OpenCL/api-docs repository.
<type category="define">typedef <type>cl_properties</type> <name>cl_svm_free_properties_khr</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_svm_free_flags_khr</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_svm_pointer_info_khr</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_memory_controls_capabilities_arm</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_mem_coherency_flags_arm</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_kernel_exec_info_local_memory_backing_arm</name>;</type>

<comment>Structure types</comment>
<type category="struct" name="cl_dx9_surface_info_khr">
Expand Down Expand Up @@ -1554,6 +1557,21 @@ server's OpenCL/api-docs repository.
<enums name="cl_svm_free_flags_khr" vendor="Khronos" type="bitmask">
<unused start="0" end="31"/>
</enums>
<enums name="cl_device_memory_controls_capabilities_arm" vendor="Arm" type="bitmask">
<enum bitpos="0" name="CL_DEVICE_MEMORY_CONTROLS_COHERENCY_ARM"/>
<enum bitpos="1" name="CL_DEVICE_MEMORY_CONTROLS_LOCAL_MEMORY_ARM"/>
<unused start="2" end="63"/>
</enums>
<enums name="cl_mem_coherency_flags_arm" vendor="Arm" type="bitmask">
<enum bitpos="0" name="CL_MEM_COHERENCY_INNER_SHAREABLE_ARM"/>
<enum bitpos="1" name="CL_MEM_COHERENCY_OUTER_SHAREABLE_ARM"/>
<unused start="2" end="63"/>
</enums>
<enums name="cl_kernel_exec_info_local_memory_backing_arm" vendor="Arm" type="enum">
<enum value="1" name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_GLOBAL_ARM"/>
<enum value="2" name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_COMPUTE_UNIT_ARM"/>
<enum value="3" name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_AUTO_ARM"/>
</enums>

<enums start="0x10000" end="0x1FFFF" name="cl_khronos_vendor_id" vendor="Khronos">
<comment>
Expand Down Expand Up @@ -2442,8 +2460,11 @@ server's OpenCL/api-docs repository.
<unused start="0x41F2" end="0x41F2" comment="Reserved for cl_arm_core_builtins"/>
<enum value="0x41F3" name="CL_QUEUE_COMPUTE_UNIT_LIMIT_ARM"/>
<unused start="0x41F4" end="0x41F4" comment="Reserved"/>
<unused start="0x41F5" end="0x41F6" comment="Reserved"/>
<unused start="0x41F7" end="0x41FF"/>
<enum value="0x41F5" name="CL_DEVICE_MEMORY_CONTROLS_CAPABILITIES_ARM"/>
<enum value="0x41F6" name="CL_MEM_COHERENCY_ARM"/>
<enum value="0x41F7" name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_ARM"/>
<enum value="0x41F8" name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_HASHING_ARM"/>
<unused start="0x41F9" end="0x41FF"/>
</enums>

<enums start="0x4200" end="0x420F" name="enums.4200" vendor="Intel">
Expand Down Expand Up @@ -8200,5 +8221,35 @@ server's OpenCL/api-docs repository.
<extension name="cl_arm_integer_dot_product_accumulate_int8" revision="1.0.0" supported="opencl" comment="OpenCL C only"/>
<extension name="cl_arm_integer_dot_product_accumulate_int16" revision="1.0.0" supported="opencl" comment="OpenCL C only"/>
<extension name="cl_arm_integer_dot_product_accumulate_saturate_int8" revision="1.0.0" supported="opencl" comment="OpenCL C only"/>
<extension name="cl_arm_memory_controls" revision="0.2.0" supported="opencl">
<require comment="Types">
<type name="cl_device_memory_controls_capabilities_arm"/>
<type name="cl_mem_coherency_flags_arm"/>
<type name="cl_kernel_exec_info_local_memory_backing_arm"/>
</require>
<require comment="cl_device_info">
<enum name="CL_DEVICE_MEMORY_CONTROLS_CAPABILITIES_ARM"/>
</require>
<require comment="cl_device_memory_controls_capabilities_arm">
<enum name="CL_DEVICE_MEMORY_CONTROLS_COHERENCY_ARM"/>
<enum name="CL_DEVICE_MEMORY_CONTROLS_LOCAL_MEMORY_ARM"/>
</require>
<require comment="cl_mem_properties">
<enum name="CL_MEM_COHERENCY_ARM"/>
</require>
<require comment="cl_mem_coherency_flags_arm">
<enum name="CL_MEM_COHERENCY_INNER_SHAREABLE_ARM"/>
<enum name="CL_MEM_COHERENCY_OUTER_SHAREABLE_ARM"/>
</require>
<require comment="cl_kernel_exec_info">
<enum name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_ARM"/>
<enum name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_HASHING_ARM"/>
</require>
<require comment="cl_kernel_exec_info">
<enum name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_GLOBAL_ARM"/>
<enum name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_COMPUTE_UNIT_ARM"/>
<enum name="CL_KERNEL_EXEC_INFO_LOCAL_MEMORY_BACKING_AUTO_ARM"/>
</require>
</extension>
</extensions>
</registry>
Loading