From 9225db823ce4b908ac8d22593b77602024da3880 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henry=20Linjam=C3=A4ki?= Date: Fri, 9 Aug 2024 10:21:25 +0300 Subject: [PATCH 1/4] Extension for command-buffer internal buffer property --- ...hr_command_buffer_internal_buffer.asciidoc | 256 +++++ ...cl_khr_command_buffer_internal_buffer.html | 960 ++++++++++++++++++ 2 files changed, 1216 insertions(+) create mode 100644 extensions/cl_khr_command_buffer_internal_buffer.asciidoc create mode 100644 extensions/cl_khr_command_buffer_internal_buffer.html diff --git a/extensions/cl_khr_command_buffer_internal_buffer.asciidoc b/extensions/cl_khr_command_buffer_internal_buffer.asciidoc new file mode 100644 index 000000000..b78640171 --- /dev/null +++ b/extensions/cl_khr_command_buffer_internal_buffer.asciidoc @@ -0,0 +1,256 @@ +// Copyright 2024 The Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +:data-uri: +:icons: font +include::../config/attribs.txt[] +//include::{generated}/api/api-dictionary.asciidoc[] +:source-highlighter: coderay + += cl_khr_command_buffer_internal_buffer + +== XXX - Not complete yet!!! + +== Name Strings + +`cl_khr_command_buffer_internal_buffer` + +== Contact + +Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + +https://github.com/KhronosGroup/OpenCL-Docs + +== Contributors + +Henry Linjamäki, Intel + +Pekka Jääskeläinen, Intel + +Ben Ashbaugh, Intel + +== Notice + +TODO + +== Status + +Draft spec, NOT APPROVED!! + +== Version + +Built On: {docdate} + +Version: 0.1.0 + +== Dependencies + +This extension requires OpenCL 1.2. + +This extension requires `cl_khr_command_buffer`. + +== Overview + +This extension adds a new buffer creation property, +`CL_MEM_COMMAND_BUFFER_INTERNAL`. This property instructs the runtime +to create a buffer object that is only accessible by commands recorded +by a single command-buffer the buffer is associated with. The contents +of the buffer with this property are not accessible nor observable by +the host and non-recording commands. The property potentially enables +runtimes to potentially optimize command-buffers to: + +* free space by deallocating the "internal buffers" while the associated + command-buffers are not executed and reallocate them when needed. + +* reduce memory usage by sharing data storage among the internal + buffers. In C analogy: ++ +[source,c] +---- +cl_mem in, out; +void a_command_buffer() { + cl_mem buf0 = ..., buf1 = ..., buf2 = ...; + kernelA(in, buf0); + kernelB(buf0, buf1); + kernelC(buf1, buf2) + kernelD(buf2, out); +} +// --> +void a_command_buffer() { + cl_mem buf0 = ..., buf1 = ...; + kernelA(in, buf0); + kernelB(buf0, buf1); + kernelC(buf1, buf0) + kernelD(buf0, out); +} +---- +* fuse kernels together as intermediate results do not need to be + preserved. In C analogy: ++ +[source,c] +---- +cl_mem in, w, out; +void a_command_buffer() { + cl_mem buf0 = ...; + convolutionKernel(in, w, buf0); + reluKernel(buf0, out); +} +// --> +void a_command_buffer() { + convolutionPlusReluKernel(in, w, out); +} +---- + +== New API Functions + +None. + +== New API Types + +None. + +== New API Enums + +[source,c] +---- +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR 0x???? +---- + +== Modifications to the OpenCL API Specification + +(Modify Section 5.2.1, *Creating Buffer Objects*) :: ++ +-- + +(Add the following to the table of buffer creation properties) :: ++ +-- +[cols="2,1,2",stripes=odd,options="header"] +|=== +| Propery | Property Value | Description + +| `CL_MEM_COMMAND_BUFFER_INTERNAL_KHR` | `cl_khr_command_buffer` a| +This property can be used if *cl_khr_command_buffer_internal_buffer* +extension is supported. + +This property constraints the created buffer to be only accessible by +commands recorded into the associated command buffer. Reading from or +writing to the buffer by commands which are not part of the associated +command-buffer is considered undefined behavior. + +The associated command-buffer may deallocate storage and reallocate +the storage as needed during its execution and otherwise. Multiple +buffers associated with the same command-buffer may share same data +storage. + +// A consequence of the last sentence: CL_MEM_SIZE queries on two or +// more buffers associated with the same command-buffer may not +// reflect the actual storage used on during execution of the +// command-buffer. IOW: the storage used may be lower than +// `CL_MEM_SIZE(buf1) + CL_MEM_SIZE(buf2)`. + +The contents of the buffer are not guaranteed to be preserved +after the associated command-buffer execution completes. + +This property is incompatible with *CL_MEM_COPY_HOST_PTR* and +*CL_MEM_USE_HOST_PTR* memory flags and *CL_MEM_DEVICE_HANDLE_LIST_KHR* +buffer creation property. + +This property implies *CL_MEM_HOST_NO_ACCESS* memory flag. + +The reference count of the associated command-buffer is not increased +when the buffer is created. When the associated command-buffer is +released the buffer becomes invalid. +|=== + +-- +-- +// End (Modify Section 5.2.1, *Creating Buffer Objects*) + +(Add to the list of error codes for *clEnqueueReadBuffer*, *clEnqueueWriteBuffer*, *clEnqueueReadBufferRect*, *clEnqueueWriteBufferRect*, *clEnqueueCopyBuffer*, *clEnqueueCopyBufferRect*, *clEnqueueFillBuffer* and *clEnqueueMapBuffer*) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if a memory object passed to this function + is a buffer object or references a buffer object created with + *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. + +// "references a buffer": E.g. sub-buffers. +-- + +(Add to the list of error codes for *clCreateImage* and *clCreateImageWithProperties* ) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if the _buffer_ or _mem_object_ field of + _image_desc_ is a buffer object or references a buffer object + created with *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. +-- + +(Add to the list of error codes for *clCommandCopyBufferKHR*, *clCommandCopyBufferRectKHR*, *clCommandCopyBufferToImageKHR*, *clCommandCopyImageKHR*, *clCommand CopyImageToBufferKHR*, *clCommandFillBufferKHR* and *clCommandFillImageKHR*) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if a memory object passed to this function + is a buffer object or references a buffer object created with + *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. +-- + +(Add to the list of error codes for *clEnqueueNDRangeKernel* and *clEnqueueTask*) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if the kernel has an argument that is a + buffer object or references a buffer object created with + *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. +-- + +(Add to the list of error codes for *clEnqueueNativeKernel*) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if a memory object in _mem_list_ is a buffer + object or references a buffer object created with + *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. +-- + +(Add to the list of error codes for *clCommandNDRangeKernelKHR*) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if the kernel has an argument that is a + buffer object or references a buffer object created with + *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property and _command_buffer_ + is not same as the command-buffer the buffer is associated with. +-- + +(Add to the list of error code for *clUpdateMutableCommandsKHR*) :: ++ +-- +* *CL_INVALID_MEM_OBJECT* if a new kernel argument value is a buffer + object or references a buffer object created with + *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property and _command_buffer_ + is not same as the command-buffer the buffer is associated with. +-- + +== Issues + +. Should we add memory object query for returning the associated +command-buffer handle? ++ +-- +*UNRESOLVED* +-- + +. Should we add a command-buffer query for returning total internal +storage size the command-buffer allocates for its execution? ++ +-- +*UNRESOLVED* +-- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 0.1.0 | 2024-08-22 | +Henry Linjamäki + +Pekka Jääskeläinen + +Ben Ashbaugh | +*Initial revision* + +|==== diff --git a/extensions/cl_khr_command_buffer_internal_buffer.html b/extensions/cl_khr_command_buffer_internal_buffer.html new file mode 100644 index 000000000..8feaaf3ee --- /dev/null +++ b/extensions/cl_khr_command_buffer_internal_buffer.html @@ -0,0 +1,960 @@ + + + + + + + +cl_khr_command_buffer_internal_buffer + + + + + + + +
+
+

XXX - Not complete yet!!!

+
+ +
+
+
+

Name Strings

+
+
+

cl_khr_command_buffer_internal_buffer

+
+
+
+
+

Contact

+
+
+

Please see the Issues list in the Khronos OpenCL-Docs repository:
+https://github.com/KhronosGroup/OpenCL-Docs

+
+
+
+
+

Contributors

+
+
+

Henry Linjamäki, Intel
+Pekka Jääskeläinen, Intel
+Ben Ashbaugh, Intel

+
+
+
+
+

Notice

+
+
+

TODO

+
+
+
+
+

Status

+
+
+

Draft spec, NOT APPROVED!!

+
+
+
+
+

Version

+
+
+

Built On: 2024-08-22
+Version: 0.1.0

+
+
+
+
+

Dependencies

+
+
+

This extension requires OpenCL 1.2.

+
+
+

This extension requires cl_khr_command_buffer.

+
+
+
+
+

Overview

+
+
+

This extension adds a new buffer creation property, +CL_MEM_COMMAND_BUFFER_INTERNAL. This property instructs the runtime +to create a buffer object that is only accessible by commands recorded +by a single command-buffer the buffer is associated with. The contents +of the buffer with this property are not accessible nor observable by +the host and non-recording commands. The property potentially enables +runtimes to potentially optimize command-buffers to:

+
+
+
    +
  • +

    free space by deallocating the "internal buffers" while the associated +command-buffers are not executed and reallocate them when needed.

    +
    • +
  • +

    reduce memory usage by sharing data storage among the internal +buffers. In C analogy:

    +
    +
    +
    cl_mem in, out;
+void a_command_buffer() {
+  cl_mem buf0 = ..., buf1 = ..., buf2 = ...;
+  kernelA(in, buf0);
+  kernelB(buf0, buf1);
+  kernelC(buf1, buf2)
+  kernelD(buf2, out);
+}
+// -->
+void a_command_buffer() {
+  cl_mem buf0 = ..., buf1 = ...;
+  kernelA(in, buf0);
+  kernelB(buf0, buf1);
+  kernelC(buf1, buf0)
+  kernelD(buf0, out);
+}
    +
    +
    +
    • +
  • +

    fuse kernels together as intermediate results do not need to be +preserved. In C analogy:

    +
    +
    +
    cl_mem in, w, out;
+void a_command_buffer() {
+  cl_mem buf0 = ...;
+  convolutionKernel(in, w, buf0);
+  reluKernel(buf0, out);
+}
+// -->
+void a_command_buffer() {
+  convolutionPlusReluKernel(in, w, out);
+}
    +
    +
    +
    • +
+
+
+
+
+

New API Functions

+
+
+

None.

+
+
+
+
+

New API Types

+
+
+

None.

+
+
+
+
+

New API Enums

+
+
+
+
CL_MEM_COMMAND_BUFFER_INTERNAL_KHR 0x????
+
+
+
+
+
+

Modifications to the OpenCL API Specification

+
+
+
+
(Modify Section 5.2.1, Creating Buffer Objects)
+
+
+
+
+
+
(Add the following to the table of buffer creation properties)
+
+
+
+
+
+
+
+ +++++ + + + + + + + + + + + + + + +
ProperyProperty ValueDescription

CL_MEM_COMMAND_BUFFER_INTERNAL_KHR

cl_khr_command_buffer

+

This property can be used if cl_khr_command_buffer_internal_buffer +extension is supported.

+
+
+

This property constraints the created buffer to be only accessible by +commands recorded into the associated command buffer. Reading from or +writing to the buffer by commands which are not part of the associated +command-buffer is considered undefined behavior.

+
+
+

The associated command-buffer may deallocate storage and reallocate +the storage as needed during its execution and otherwise. Multiple +buffers associated with the same command-buffer may share same data +storage.

+
+
+

The contents of the buffer are not guaranteed to be preserved +after the associated command-buffer execution completes.

+
+
+

This property is incompatible with CL_MEM_COPY_HOST_PTR and +CL_MEM_USE_HOST_PTR memory flags and CL_MEM_DEVICE_HANDLE_LIST_KHR +buffer creation property.

+
+
+

This property implies CL_MEM_HOST_NO_ACCESS memory flag.

+
+
+

The reference count of the associated command-buffer is not increased +when the buffer is created. When the associated command-buffer is +released the buffer becomes invalid.

+
+
+
+ +
+
+
+
+
(Add to the list of error codes for clEnqueueReadBuffer, clEnqueueWriteBuffer, clEnqueueReadBufferRect, clEnqueueWriteBufferRect, clEnqueueCopyBuffer, clEnqueueCopyBufferRect, clEnqueueFillBuffer and clEnqueueMapBuffer)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a memory object passed to this function +is a buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clCreateImage and clCreateImageWithProperties )
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if the buffer or mem_object field of +image_desc is a buffer object or references a buffer object +created with CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clCommandCopyBufferKHR, clCommandCopyBufferRectKHR, clCommandCopyBufferToImageKHR, clCommandCopyImageKHR, clCommand CopyImageToBufferKHR, clCommandFillBufferKHR and clCommandFillImageKHR)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a memory object passed to this function +is a buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clEnqueueNDRangeKernel and clEnqueueTask)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if the kernel has an argument that is a +buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clEnqueueNativeKernel)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a memory object in mem_list is a buffer +object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clCommandNDRangeKernelKHR)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if the kernel has an argument that is a +buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property and command_buffer +is not same as the command-buffer the buffer is associated with.

    +
    • +
+
+
+
+
+
(Add to the list of error code for clUpdateMutableCommandsKHR)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a new kernel argument value is a buffer +object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property and command_buffer +is not same as the command-buffer the buffer is associated with.

    +
    • +
+
+
+
+
+
+
+
+
+
+

Issues

+
+
+
    +
  1. +

    Should we add memory object query for returning the associated +command-buffer handle?

    +
    +
    +
    +

    UNRESOLVED

    +
    +
    +
    +
    2. +
  2. +

    Should we add a command-buffer query for returning total internal +storage size the command-buffer allocates for its execution?

    +
    +
    +
    +

    UNRESOLVED

    +
    +
    +
    +
    3. +
+
+
+
+
+

Version History

+
+ ++++++ + + + + + + + + + + + + + + + + +
VersionDateAuthorChanges

0.1.0

2024-08-22

Henry Linjamäki
+Pekka Jääskeläinen
+Ben Ashbaugh

Initial revision

+
+
+
+ + + \ No newline at end of file From 2807294b02247fe7a6b5834c7f38b2aa8556dd18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henry=20Linjam=C3=A4ki?= Date: Thu, 22 Aug 2024 15:11:48 +0300 Subject: [PATCH 2/4] Address feedback --- ...t_command_buffer_internal_buffer.asciidoc} | 110 +- ...cl_khr_command_buffer_internal_buffer.html | 960 ------------------ 2 files changed, 58 insertions(+), 1012 deletions(-) rename extensions/{cl_khr_command_buffer_internal_buffer.asciidoc => cl_ext_command_buffer_internal_buffer.asciidoc} (76%) delete mode 100644 extensions/cl_khr_command_buffer_internal_buffer.html diff --git a/extensions/cl_khr_command_buffer_internal_buffer.asciidoc b/extensions/cl_ext_command_buffer_internal_buffer.asciidoc similarity index 76% rename from extensions/cl_khr_command_buffer_internal_buffer.asciidoc rename to extensions/cl_ext_command_buffer_internal_buffer.asciidoc index b78640171..c9dbec9c5 100644 --- a/extensions/cl_khr_command_buffer_internal_buffer.asciidoc +++ b/extensions/cl_ext_command_buffer_internal_buffer.asciidoc @@ -8,13 +8,13 @@ include::../config/attribs.txt[] //include::{generated}/api/api-dictionary.asciidoc[] :source-highlighter: coderay -= cl_khr_command_buffer_internal_buffer += cl_ext_command_buffer_internal_storage == XXX - Not complete yet!!! == Name Strings -`cl_khr_command_buffer_internal_buffer` +`cl_ext_command_buffer_internal_storage` == Contact @@ -44,12 +44,12 @@ Version: 0.1.0 This extension requires OpenCL 1.2. -This extension requires `cl_khr_command_buffer`. +This extension requires `cl_ext_command_buffer`. == Overview This extension adds a new buffer creation property, -`CL_MEM_COMMAND_BUFFER_INTERNAL`. This property instructs the runtime +`CL_MEM_COMMAND_BUFFER_INTERNAL_EXT`. This property instructs the runtime to create a buffer object that is only accessible by commands recorded by a single command-buffer the buffer is associated with. The contents of the buffer with this property are not accessible nor observable by @@ -60,43 +60,14 @@ runtimes to potentially optimize command-buffers to: command-buffers are not executed and reallocate them when needed. * reduce memory usage by sharing data storage among the internal - buffers. In C analogy: -+ -[source,c] ----- -cl_mem in, out; -void a_command_buffer() { - cl_mem buf0 = ..., buf1 = ..., buf2 = ...; - kernelA(in, buf0); - kernelB(buf0, buf1); - kernelC(buf1, buf2) - kernelD(buf2, out); -} -// --> -void a_command_buffer() { - cl_mem buf0 = ..., buf1 = ...; - kernelA(in, buf0); - kernelB(buf0, buf1); - kernelC(buf1, buf0) - kernelD(buf0, out); -} ----- + buffers. + * fuse kernels together as intermediate results do not need to be - preserved. In C analogy: -+ -[source,c] ----- -cl_mem in, w, out; -void a_command_buffer() { - cl_mem buf0 = ...; - convolutionKernel(in, w, buf0); - reluKernel(buf0, out); -} -// --> -void a_command_buffer() { - convolutionPlusReluKernel(in, w, out); -} ----- + preserved. + +The buffers created with the new property are similar to the OpenVX's +virtual data objects. + == New API Functions @@ -108,9 +79,18 @@ None. == New API Enums +Accepted value to *cl_mem_properties*: + +[source,c] +---- +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT 0x???? +---- + +Accepted value to *cl_mem_info*: + [source,c] ---- -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR 0x???? +CL_MEM_ASSOCIATED_COMMAND_BUFFER_EXT 0x???? ---- == Modifications to the OpenCL API Specification @@ -126,8 +106,8 @@ CL_MEM_COMMAND_BUFFER_INTERNAL_KHR 0x???? |=== | Propery | Property Value | Description -| `CL_MEM_COMMAND_BUFFER_INTERNAL_KHR` | `cl_khr_command_buffer` a| -This property can be used if *cl_khr_command_buffer_internal_buffer* +| `CL_MEM_COMMAND_BUFFER_INTERNAL_EXT` | `cl_ext_command_buffer` a| +This property can be used if *cl_ext_command_buffer_internal_storage* extension is supported. This property constraints the created buffer to be only accessible by @@ -150,7 +130,7 @@ The contents of the buffer are not guaranteed to be preserved after the associated command-buffer execution completes. This property is incompatible with *CL_MEM_COPY_HOST_PTR* and -*CL_MEM_USE_HOST_PTR* memory flags and *CL_MEM_DEVICE_HANDLE_LIST_KHR* +*CL_MEM_USE_HOST_PTR* memory flags and *CL_MEM_DEVICE_HANDLE_LIST_EXT* buffer creation property. This property implies *CL_MEM_HOST_NO_ACCESS* memory flag. @@ -169,7 +149,7 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if a memory object passed to this function is a buffer object or references a buffer object created with - *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. + *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property. // "references a buffer": E.g. sub-buffers. -- @@ -179,7 +159,7 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if the _buffer_ or _mem_object_ field of _image_desc_ is a buffer object or references a buffer object - created with *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. + created with *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property. -- (Add to the list of error codes for *clCommandCopyBufferKHR*, *clCommandCopyBufferRectKHR*, *clCommandCopyBufferToImageKHR*, *clCommandCopyImageKHR*, *clCommand CopyImageToBufferKHR*, *clCommandFillBufferKHR* and *clCommandFillImageKHR*) :: @@ -187,7 +167,7 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if a memory object passed to this function is a buffer object or references a buffer object created with - *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. + *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property. -- (Add to the list of error codes for *clEnqueueNDRangeKernel* and *clEnqueueTask*) :: @@ -195,7 +175,7 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if the kernel has an argument that is a buffer object or references a buffer object created with - *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. + *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property. -- (Add to the list of error codes for *clEnqueueNativeKernel*) :: @@ -203,7 +183,7 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if a memory object in _mem_list_ is a buffer object or references a buffer object created with - *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property. + *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property. -- (Add to the list of error codes for *clCommandNDRangeKernelKHR*) :: @@ -211,7 +191,7 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if the kernel has an argument that is a buffer object or references a buffer object created with - *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property and _command_buffer_ + *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property and _command_buffer_ is not same as the command-buffer the buffer is associated with. -- @@ -220,17 +200,36 @@ released the buffer becomes invalid. -- * *CL_INVALID_MEM_OBJECT* if a new kernel argument value is a buffer object or references a buffer object created with - *CL_MEM_COMMAND_BUFFER_INTERNAL_KHR* property and _command_buffer_ + *CL_MEM_COMMAND_BUFFER_INTERNAL_EXT* property and _command_buffer_ is not same as the command-buffer the buffer is associated with. -- +(Modify Section 5.5.6, *Memory Object Quaries*) :: ++ +-- + +(Add the following to the table of supported _param_names_ for *clGetMemObjectInfo*) :: ++ +-- +[cols="2,1,2",stripes=odd,options="header"] +|=== +| Memory Object Info | Return Type | Description + +| `CL_MEM_ASSOCIATED_COMMAND_BUFFER_EXT` | `cl_khr_command_buffer` | + +Returns the command-buffer object the buffer is associated with if it +was created with `CL_MEM_COMMAND_BUFFER_INTERNAL_EXT.` Otherwise, returns +NULL. +-- +-- + == Issues . Should we add memory object query for returning the associated command-buffer handle? + -- -*UNRESOLVED* +*RESOLVED*. Added the query. -- . Should we add a command-buffer query for returning total internal @@ -253,4 +252,11 @@ Pekka Jääskeläinen + Ben Ashbaugh | *Initial revision* +| Version | Date | Author | Changes +| 0.1.1 | 2024-08-22 | +Henry Linjamäki + +Pekka Jääskeläinen + a| +* Rename the extension. +* Add query to retrieve the associated command-buffer. +* Other changes from feedback. |==== diff --git a/extensions/cl_khr_command_buffer_internal_buffer.html b/extensions/cl_khr_command_buffer_internal_buffer.html deleted file mode 100644 index 8feaaf3ee..000000000 --- a/extensions/cl_khr_command_buffer_internal_buffer.html +++ /dev/null @@ -1,960 +0,0 @@ - - - - - - - -cl_khr_command_buffer_internal_buffer - - - - - - - -
-
-

XXX - Not complete yet!!!

-
- -
-
-
-

Name Strings

-
-
-

cl_khr_command_buffer_internal_buffer

-
-
-
-
-

Contact

-
-
-

Please see the Issues list in the Khronos OpenCL-Docs repository:
-https://github.com/KhronosGroup/OpenCL-Docs

-
-
-
-
-

Contributors

-
-
-

Henry Linjamäki, Intel
-Pekka Jääskeläinen, Intel
-Ben Ashbaugh, Intel

-
-
-
-
-

Notice

-
-
-

TODO

-
-
-
-
-

Status

-
-
-

Draft spec, NOT APPROVED!!

-
-
-
-
-

Version

-
-
-

Built On: 2024-08-22
-Version: 0.1.0

-
-
-
-
-

Dependencies

-
-
-

This extension requires OpenCL 1.2.

-
-
-

This extension requires cl_khr_command_buffer.

-
-
-
-
-

Overview

-
-
-

This extension adds a new buffer creation property, -CL_MEM_COMMAND_BUFFER_INTERNAL. This property instructs the runtime -to create a buffer object that is only accessible by commands recorded -by a single command-buffer the buffer is associated with. The contents -of the buffer with this property are not accessible nor observable by -the host and non-recording commands. The property potentially enables -runtimes to potentially optimize command-buffers to:

-
-
-
    -
  • -

    free space by deallocating the "internal buffers" while the associated -command-buffers are not executed and reallocate them when needed.

    -
    • -
  • -

    reduce memory usage by sharing data storage among the internal -buffers. In C analogy:

    -
    -
    -
    cl_mem in, out;
-void a_command_buffer() {
-  cl_mem buf0 = ..., buf1 = ..., buf2 = ...;
-  kernelA(in, buf0);
-  kernelB(buf0, buf1);
-  kernelC(buf1, buf2)
-  kernelD(buf2, out);
-}
-// -->
-void a_command_buffer() {
-  cl_mem buf0 = ..., buf1 = ...;
-  kernelA(in, buf0);
-  kernelB(buf0, buf1);
-  kernelC(buf1, buf0)
-  kernelD(buf0, out);
-}
    -
    -
    -
    • -
  • -

    fuse kernels together as intermediate results do not need to be -preserved. In C analogy:

    -
    -
    -
    cl_mem in, w, out;
-void a_command_buffer() {
-  cl_mem buf0 = ...;
-  convolutionKernel(in, w, buf0);
-  reluKernel(buf0, out);
-}
-// -->
-void a_command_buffer() {
-  convolutionPlusReluKernel(in, w, out);
-}
    -
    -
    -
    • -
-
-
-
-
-

New API Functions

-
-
-

None.

-
-
-
-
-

New API Types

-
-
-

None.

-
-
-
-
-

New API Enums

-
-
-
-
CL_MEM_COMMAND_BUFFER_INTERNAL_KHR 0x????
-
-
-
-
-
-

Modifications to the OpenCL API Specification

-
-
-
-
(Modify Section 5.2.1, Creating Buffer Objects)
-
-
-
-
-
-
(Add the following to the table of buffer creation properties)
-
-
-
-
-
-
-
- ----- - - - - - - - - - - - - - - -
ProperyProperty ValueDescription

CL_MEM_COMMAND_BUFFER_INTERNAL_KHR

cl_khr_command_buffer

-

This property can be used if cl_khr_command_buffer_internal_buffer -extension is supported.

-
-
-

This property constraints the created buffer to be only accessible by -commands recorded into the associated command buffer. Reading from or -writing to the buffer by commands which are not part of the associated -command-buffer is considered undefined behavior.

-
-
-

The associated command-buffer may deallocate storage and reallocate -the storage as needed during its execution and otherwise. Multiple -buffers associated with the same command-buffer may share same data -storage.

-
-
-

The contents of the buffer are not guaranteed to be preserved -after the associated command-buffer execution completes.

-
-
-

This property is incompatible with CL_MEM_COPY_HOST_PTR and -CL_MEM_USE_HOST_PTR memory flags and CL_MEM_DEVICE_HANDLE_LIST_KHR -buffer creation property.

-
-
-

This property implies CL_MEM_HOST_NO_ACCESS memory flag.

-
-
-

The reference count of the associated command-buffer is not increased -when the buffer is created. When the associated command-buffer is -released the buffer becomes invalid.

-
-
-
- -
-
-
-
-
(Add to the list of error codes for clEnqueueReadBuffer, clEnqueueWriteBuffer, clEnqueueReadBufferRect, clEnqueueWriteBufferRect, clEnqueueCopyBuffer, clEnqueueCopyBufferRect, clEnqueueFillBuffer and clEnqueueMapBuffer)
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if a memory object passed to this function -is a buffer object or references a buffer object created with -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    -
    • -
-
-
-
-
-
(Add to the list of error codes for clCreateImage and clCreateImageWithProperties )
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if the buffer or mem_object field of -image_desc is a buffer object or references a buffer object -created with CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    -
    • -
-
-
-
-
-
(Add to the list of error codes for clCommandCopyBufferKHR, clCommandCopyBufferRectKHR, clCommandCopyBufferToImageKHR, clCommandCopyImageKHR, clCommand CopyImageToBufferKHR, clCommandFillBufferKHR and clCommandFillImageKHR)
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if a memory object passed to this function -is a buffer object or references a buffer object created with -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    -
    • -
-
-
-
-
-
(Add to the list of error codes for clEnqueueNDRangeKernel and clEnqueueTask)
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if the kernel has an argument that is a -buffer object or references a buffer object created with -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    -
    • -
-
-
-
-
-
(Add to the list of error codes for clEnqueueNativeKernel)
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if a memory object in mem_list is a buffer -object or references a buffer object created with -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property.

    -
    • -
-
-
-
-
-
(Add to the list of error codes for clCommandNDRangeKernelKHR)
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if the kernel has an argument that is a -buffer object or references a buffer object created with -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property and command_buffer -is not same as the command-buffer the buffer is associated with.

    -
    • -
-
-
-
-
-
(Add to the list of error code for clUpdateMutableCommandsKHR)
-
-
-
-
-
    -
  • -

    CL_INVALID_MEM_OBJECT if a new kernel argument value is a buffer -object or references a buffer object created with -CL_MEM_COMMAND_BUFFER_INTERNAL_KHR property and command_buffer -is not same as the command-buffer the buffer is associated with.

    -
    • -
-
-
-
-
-
-
-
-
-
-

Issues

-
-
-
    -
  1. -

    Should we add memory object query for returning the associated -command-buffer handle?

    -
    -
    -
    -

    UNRESOLVED

    -
    -
    -
    -
    2. -
  2. -

    Should we add a command-buffer query for returning total internal -storage size the command-buffer allocates for its execution?

    -
    -
    -
    -

    UNRESOLVED

    -
    -
    -
    -
    3. -
-
-
-
-
-

Version History

-
- ------ - - - - - - - - - - - - - - - - -
VersionDateAuthorChanges

0.1.0

2024-08-22

Henry Linjamäki
-Pekka Jääskeläinen
-Ben Ashbaugh

Initial revision

-
-
-
- - - \ No newline at end of file From e8723b1e9454281d6689aefd7bf2cafe65f82cfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henry=20Linjam=C3=A4ki?= Date: Thu, 22 Aug 2024 15:21:05 +0300 Subject: [PATCH 3/4] Rename extension files, fix unterminated table --- ..._command_buffer_internal_storage.asciidoc} | 0 ...l_ext_command_buffer_internal_storage.html | 970 ++++++++++++++++++ 2 files changed, 970 insertions(+) rename extensions/{cl_ext_command_buffer_internal_buffer.asciidoc => cl_ext_command_buffer_internal_storage.asciidoc} (100%) create mode 100644 extensions/cl_ext_command_buffer_internal_storage.html diff --git a/extensions/cl_ext_command_buffer_internal_buffer.asciidoc b/extensions/cl_ext_command_buffer_internal_storage.asciidoc similarity index 100% rename from extensions/cl_ext_command_buffer_internal_buffer.asciidoc rename to extensions/cl_ext_command_buffer_internal_storage.asciidoc diff --git a/extensions/cl_ext_command_buffer_internal_storage.html b/extensions/cl_ext_command_buffer_internal_storage.html new file mode 100644 index 000000000..9e2866b07 --- /dev/null +++ b/extensions/cl_ext_command_buffer_internal_storage.html @@ -0,0 +1,970 @@ + + + + + + + +cl_ext_command_buffer_internal_storage + + + + + + + +
+
+

XXX - Not complete yet!!!

+
+ +
+
+
+

Name Strings

+
+
+

cl_ext_command_buffer_internal_storage

+
+
+
+
+

Contact

+
+
+

Please see the Issues list in the Khronos OpenCL-Docs repository:
+https://github.com/KhronosGroup/OpenCL-Docs

+
+
+
+
+

Contributors

+
+
+

Henry Linjamäki, Intel
+Pekka Jääskeläinen, Intel
+Ben Ashbaugh, Intel

+
+
+
+
+

Notice

+
+
+

TODO

+
+
+
+
+

Status

+
+
+

Draft spec, NOT APPROVED!!

+
+
+
+
+

Version

+
+
+

Built On: 2024-08-22
+Version: 0.1.0

+
+
+
+
+

Dependencies

+
+
+

This extension requires OpenCL 1.2.

+
+
+

This extension requires cl_ext_command_buffer.

+
+
+
+
+

Overview

+
+
+

This extension adds a new buffer creation property, +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT. This property instructs the runtime +to create a buffer object that is only accessible by commands recorded +by a single command-buffer the buffer is associated with. The contents +of the buffer with this property are not accessible nor observable by +the host and non-recording commands. The property potentially enables +runtimes to potentially optimize command-buffers to:

+
+
+
    +
  • +

    free space by deallocating the "internal buffers" while the associated +command-buffers are not executed and reallocate them when needed.

    +
    • +
  • +

    reduce memory usage by sharing data storage among the internal +buffers.

    +
    • +
  • +

    fuse kernels together as intermediate results do not need to be +preserved.

    +
    • +
+
+
+

The buffers created with the new property are similar to the OpenVX’s +virtual data objects.

+
+
+
+
+

New API Functions

+
+
+

None.

+
+
+
+
+

New API Types

+
+
+

None.

+
+
+
+
+

New API Enums

+
+
+

Accepted value to cl_mem_properties:

+
+
+
+
CL_MEM_COMMAND_BUFFER_INTERNAL_EXT 0x????
+
+
+
+

Accepted value to cl_mem_info:

+
+
+
+
CL_MEM_ASSOCIATED_COMMAND_BUFFER_EXT 0x????
+
+
+
+
+
+

Modifications to the OpenCL API Specification

+
+
+
+
(Modify Section 5.2.1, Creating Buffer Objects)
+
+
+
+
+
+
(Add the following to the table of buffer creation properties)
+
+
+
+
+
+
+
+ +++++ + + + + + + + + + + + + + + +
ProperyProperty ValueDescription

CL_MEM_COMMAND_BUFFER_INTERNAL_EXT

cl_ext_command_buffer

+

This property can be used if cl_ext_command_buffer_internal_storage +extension is supported.

+
+
+

This property constraints the created buffer to be only accessible by +commands recorded into the associated command buffer. Reading from or +writing to the buffer by commands which are not part of the associated +command-buffer is considered undefined behavior.

+
+
+

The associated command-buffer may deallocate storage and reallocate +the storage as needed during its execution and otherwise. Multiple +buffers associated with the same command-buffer may share same data +storage.

+
+
+

The contents of the buffer are not guaranteed to be preserved +after the associated command-buffer execution completes.

+
+
+

This property is incompatible with CL_MEM_COPY_HOST_PTR and +CL_MEM_USE_HOST_PTR memory flags and CL_MEM_DEVICE_HANDLE_LIST_EXT +buffer creation property.

+
+
+

This property implies CL_MEM_HOST_NO_ACCESS memory flag.

+
+
+

The reference count of the associated command-buffer is not increased +when the buffer is created. When the associated command-buffer is +released the buffer becomes invalid.

+
+
+
+ +
+
+
+
+
(Add to the list of error codes for clEnqueueReadBuffer, clEnqueueWriteBuffer, clEnqueueReadBufferRect, clEnqueueWriteBufferRect, clEnqueueCopyBuffer, clEnqueueCopyBufferRect, clEnqueueFillBuffer and clEnqueueMapBuffer)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a memory object passed to this function +is a buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clCreateImage and clCreateImageWithProperties )
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if the buffer or mem_object field of +image_desc is a buffer object or references a buffer object +created with CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clCommandCopyBufferKHR, clCommandCopyBufferRectKHR, clCommandCopyBufferToImageKHR, clCommandCopyImageKHR, clCommand CopyImageToBufferKHR, clCommandFillBufferKHR and clCommandFillImageKHR)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a memory object passed to this function +is a buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clEnqueueNDRangeKernel and clEnqueueTask)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if the kernel has an argument that is a +buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clEnqueueNativeKernel)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a memory object in mem_list is a buffer +object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property.

    +
    • +
+
+
+
+
+
(Add to the list of error codes for clCommandNDRangeKernelKHR)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if the kernel has an argument that is a +buffer object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property and command_buffer +is not same as the command-buffer the buffer is associated with.

    +
    • +
+
+
+
+
+
(Add to the list of error code for clUpdateMutableCommandsKHR)
+
+
+
+
+
    +
  • +

    CL_INVALID_MEM_OBJECT if a new kernel argument value is a buffer +object or references a buffer object created with +CL_MEM_COMMAND_BUFFER_INTERNAL_EXT property and command_buffer +is not same as the command-buffer the buffer is associated with.

    +
    • +
+
+
+
+
+
(Modify Section 5.5.6, Memory Object Quaries)
+
+
+
+
+
+
(Add the following to the table of supported param_names for clGetMemObjectInfo)
+
+
+
+
+
+
+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Memory Object InfoReturn TypeDescription

CL_MEM_ASSOCIATED_COMMAND_BUFFER_EXT

cl_khr_command_buffer

Returns the command-buffer object the buffer is associated with if it +was created with CL_MEM_COMMAND_BUFFER_INTERNAL_EXT. Otherwise, returns +NULL. —  —  +== Issues

+

. Should we add memory object query for returning the associated +command-buffer handle? ++ — RESOLVED. Added the query. —  +. Should we add a command-buffer query for returning total internal +storage size the command-buffer allocates for its execution? ++ — UNRESOLVED —  +== Version History

+

[cols="5,15,15,70"] +[grid="rows"] +[options="header"]

====

Version

Date

Author

Changes

0.1.0

2024-08-22

Henry Linjamäki
+Pekka Jääskeläinen
+Ben Ashbaugh

Initial revision

Version

Date

Author

Changes

0.1.1

2024-08-22

Henry Linjamäki
+Pekka Jääskeläinen

+
    +
  • +

    Rename the extension.

    +
    • +
  • +

    Add query to retrieve the associated command-buffer.

    +
    • +
  • +

    Other changes from feedback.

    +
    • +
+

====

+
+
+
+ + + \ No newline at end of file From c26307b9c4e1c352cb6be367080d0c6f28c289cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henry=20Linjam=C3=A4ki?= Date: Thu, 22 Aug 2024 15:27:54 +0300 Subject: [PATCH 4/4] Fix unterminated table --- ...t_command_buffer_internal_storage.asciidoc | 1 + ...l_ext_command_buffer_internal_storage.html | 84 +++++++++++++------ 2 files changed, 61 insertions(+), 24 deletions(-) diff --git a/extensions/cl_ext_command_buffer_internal_storage.asciidoc b/extensions/cl_ext_command_buffer_internal_storage.asciidoc index c9dbec9c5..0a106e2cd 100644 --- a/extensions/cl_ext_command_buffer_internal_storage.asciidoc +++ b/extensions/cl_ext_command_buffer_internal_storage.asciidoc @@ -220,6 +220,7 @@ released the buffer becomes invalid. Returns the command-buffer object the buffer is associated with if it was created with `CL_MEM_COMMAND_BUFFER_INTERNAL_EXT.` Otherwise, returns NULL. +|=== -- -- diff --git a/extensions/cl_ext_command_buffer_internal_storage.html b/extensions/cl_ext_command_buffer_internal_storage.html index 9e2866b07..e68e7afdb 100644 --- a/extensions/cl_ext_command_buffer_internal_storage.html +++ b/extensions/cl_ext_command_buffer_internal_storage.html @@ -898,30 +898,69 @@

Modifications to the Ope

cl_khr_command_buffer

Returns the command-buffer object the buffer is associated with if it was created with CL_MEM_COMMAND_BUFFER_INTERNAL_EXT. Otherwise, returns -NULL. —  —  -== Issues

-

. Should we add memory object query for returning the associated -command-buffer handle? -+ — RESOLVED. Added the query. —  -. Should we add a command-buffer query for returning total internal -storage size the command-buffer allocates for its execution? -+ — UNRESOLVED —  -== Version History

-

[cols="5,15,15,70"] -[grid="rows"] -[options="header"]

+NULL.

+ + +
+
+ +
+
+ + +
+

Issues

+
+
+
    +
  1. +

    Should we add memory object query for returning the associated +command-buffer handle?

    +
    +
    +
    +

    RESOLVED. Added the query.

    +
    +
    +
    +
    2. +
  2. +

    Should we add a command-buffer query for returning total internal +storage size the command-buffer allocates for its execution?

    +
    +
    +
    +

    UNRESOLVED

    +
    +
    +
    +
    3. +
+
+
+
+
+

Version History

+
+ ++++++ + - - - + + + + + + - - - - + - - - -

====

Version

Date

VersionDateAuthorChanges

Author

Changes

0.1.0

2024-08-22

Henry Linjamäki
Pekka Jääskeläinen
@@ -932,13 +971,11 @@

Modifications to the Ope

Version

Date

Author

Changes

Changes

0.1.1

2024-08-22

Henry Linjamäki
Pekka Jääskeläinen
@@ -954,7 +991,6 @@

Modifications to the Ope

====
@@ -963,7 +999,7 @@

Modifications to the Ope