cl_arm_import_memory extension specification updates (#74)
* A few clarifications to cl_arm_import_memory
Signed-off-by: Kevin Petit <kevin.petit@arm.com>
* Add cl_arm_import_memory_android_hardware_buffer
Signed-off-by: Kevin Petit <kevin.petit@arm.com>
diff --git a/extensions/arm/cl_arm_import_memory.txt b/extensions/arm/cl_arm_import_memory.txt
index 7f46b7d..4807e0b 100644
--- a/extensions/arm/cl_arm_import_memory.txt
+++ b/extensions/arm/cl_arm_import_memory.txt
@@ -8,6 +8,7 @@
cl_arm_import_memory_host
cl_arm_import_memory_dma_buf
cl_arm_import_memory_protected
+ cl_arm_import_memory_android_hardware_buffer
cl_arm_import_memory will be reported if at least one of the other extension
strings is also reported.
@@ -30,7 +31,7 @@
Version
- Revision: #6, Jan 5th, 2018
+ Revision: #9, Jan 10th, 2020
Number
@@ -114,6 +115,7 @@
* CL_IMPORT_TYPE_HOST_ARM - this is the default
* CL_IMPORT_TYPE_DMA_BUF_ARM
+ * CL_IMPORT_TYPE_ANDROID_HARDWARE_BUFFER_ARM
Valid values for CL_IMPORT_TYPE_PROTECTED_ARM are:
@@ -133,12 +135,20 @@
Valid <memory> pointer is dependent on the TYPE passed in properties.
+ <size> must be greater than 0 and represents the size of the memory
+ object to be created.
+
Errors
CL_INVALID_CONTEXT on invalid context.
CL_INVALID_VALUE on invalid flag input.
+ CL_INVALID_BUFFER_SIZE when size is 0.
+
+ CL_INVALID_BUFFER_SIZE when size is greater than the size of the
+ allocation being imported.
+
CL_INVALID_PROPERTY when invalid properties or combination of properties
are passed.
@@ -204,6 +214,9 @@
dma_buf allocations are page-aligned and their size is a whole number of
pages.
+ <size> must be less than or equal to the size of the imported dma_buf
+ allocation.
+
If an application only requires communication between the host CPU and
the GPU, it should favour using host imports as described further.
@@ -256,6 +269,18 @@
allowed. If the property's value is set to CL_TRUE, then the memory
is imported as protected memory.
+ Android hardware buffer
+
+ This allows to directly import a AHardwareBuffer. This will acquire
+ a reference on the AHardwareBuffer object that will not be released until
+ the cl_mem is destroyed.
+
+ Multiplanar buffers are only supported when backed by a single dma_buf.
+
+ <size> may be set to CL_IMPORT_MEMORY_WHOLE_ALLOCATION_ARM to require
+ that the memory object have the same size as the imported
+ AHardwareBuffer.
+
New Tokens
None
@@ -309,14 +334,14 @@
#define HEIGHT 512
// tightly packed buffer we will treat as RGB565
- char *buffer = malloc( WIDTH * HEIGHT * 2 );
+ char *allocptr = malloc( WIDTH * HEIGHT * 2 );
// The type CL_IMPORT_TYPE_HOST_ARM can be omitted as it is the default
cl_int error = CL_SUCCESS;
cl_mem buffer = clImportMemoryARM( ctx,
CL_MEM_READ_WRITE,
NULL,
- buffer,
+ allocptr,
WIDTH * HEIGHT * 2,
&error );
@@ -352,6 +377,28 @@
// Use <buffer> as cl_mem buffer, observing the usage restrictions above.
}
+ CL_IMPORT_TYPE_ANDROID_HARDWARE_BUFFER_ARM
+
+ AHardwareBuffer *ahb = ...
+
+ cl_int error = CL_SUCCESS;
+
+ const cl_import_properties_arm properties = {
+ CL_IMPORT_TYPE_ARM, CL_IMPORT_TYPE_ANDROID_HARDWARE_BUFFER_ARM,
+ 0
+ };
+ cl_mem buffer = clImportMemoryARM( context,
+ CL_MEM_READ_WRITE,
+ properties,
+ ahb,
+ CL_IMPORT_MEMORY_WHOLE_ALLOCATION_ARM,
+ &error );
+
+ if( error == CL_SUCCESS )
+ {
+ // Use <buffer> as cl_mem buffer, observing the usage restrictions above.
+ }
+
Conformance Tests
None
@@ -369,3 +416,6 @@
Revision: #6, Jan 5th, 2018 - Support creating a sub-buffer from an imported
buffer.
Revision: #7, Jun 19th, 2018 - Add support for protected memory imports.
+ Revision: #8, Aug 21st, 2019 - Clarified requirements on the size
+ parameter to clImportMemoryARM.
+ Revision: #9, Jan 10th, 2020 - Add support for Android harware buffers.
