Name

    ARM_import_memory

Name Strings

    cl_arm_import_memory
    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.

Contributors

    Robert Elliott, Arm Ltd.
    Vatsalya Prasad, Arm Ltd.
    Kévin Petit, Arm Ltd.
    Sam Laynton, Arm Ltd.
    James Morrissey, Arm Ltd.
    Einar Hov, Arm Ltd.

Contact

    Kévin Petit, ARM (kevin.petit 'at' ARM.com)

IP Status

    No claims or disclosures are known to exist.

Version

    Revision: #11, Feb 15th, 2021

Number

    OpenCL Extension #38

Status

    Complete.

Extension Type

    OpenCL device extension

Dependencies

    Requires OpenCL version 1.0 or later. Requires OpenCL 1.2 for host access
    cl_mem_flags use when importing, as these were introduced in OpenCL 1.2.

Overview

    This extension adds a new function that allows for direct memory import into
    OpenCL via the clImportMemoryARM function.

    Memory imported through this interface will be mapped into the device's page
    tables directly, providing zero copy access. It will never fall back to copy
    operations and aliased buffers, instead producing an error when mapping is
    not possible.

    Types of memory supported for import are specified as additional extension
    strings.

Header File

    cl_ext.h

Glossary

    Protected memory: a zone of memory that is protected using TrustZone Media
                      Protection.

New Types

    None

New Procedures and Functions

    The new function

      cl_mem clImportMemoryARM( cl_context context,
                                cl_mem_flags flags,
                                const cl_import_properties_arm *properties,
                                void *memory,
                                size_t size,
                                cl_int *errorcode_ret );

    Description

      Given a suitable pointer to an external memory allocation <memory> this
      function will map the memory into the device page tables.

      The flags argument provides standard OpenCL memory object flags.

      Valid <flags> are:

        * CL_MEM_READ_WRITE, CL_MEM_WRITE_ONLY, CL_MEM_READ_ONLY
        * CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY, CL_MEM_HOST_NO_ACCESS -
          where the host flags are only hints and only apply from OpenCL 1.2
          onwards.
        * CL_MEM_USE_HOST_PTR - this flag has no effect, it is ignored.

      The properties argument provides a list of key value pairs, with a zero
      terminator. properties can be NULL or point to a single zero value if the
      default behaviour is desired.

      Valid <properties> are:

        * CL_IMPORT_TYPE_ARM
        * CL_IMPORT_TYPE_PROTECTED_ARM
        * CL_IMPORT_DMA_BUF_DATA_CONSISTENCY_WITH_HOST_ARM
        * CL_IMPORT_ANDROID_HARDWARE_BUFFER_PLANE_INDEX_ARM
        * CL_IMPORT_ANDROID_HARDWARE_BUFFER_LAYER_INDEX_ARM

      Valid values for CL_IMPORT_TYPE_ARM are:

        * 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:

        * CL_FALSE - the memory is imported with no special behaviour, this is
                     the default.
        * CL_TRUE - the memory is imported as protected memory.

      When CL_IMPORT_TYPE_PROTECTED_ARM is set to CL_TRUE, the following
      restrictions apply:

        * CL_MEM_HOST_NO_ACCESS is the only accepted host access flag, all others
          are rejected. If host access flags are omitted, then this is assumed.
        * CL_IMPORT_TYPE_DMA_BUF_ARM is the only valid value for
          CL_IMPORT_TYPE_ARM.

      Valid values for CL_IMPORT_DMA_BUF_DATA_CONSISTENCY_WITH_HOST_ARM are:

        * CL_FALSE - maintaining data consistency between memory and the host's
                     view of it is the application's responsibility (default).
        * CL_TRUE - data consistency between memory and the host's view is
                    managed by the OpenCL runtime.

      Valid values for CL_IMPORT_ANDROID_HARDWARE_BUFFER_PLANE_INDEX_ARM and
      CL_IMPORT_ANDROID_HARDWARE_BUFFER_LAYER_INDEX_ARM are integers in the
      range [0; num_{planes,layers}).

      If <properties> is NULL, default values are taken.

      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.

      CL_INVALID_VALUE if memory is NULL.

      CL_INVALID_VALUE if an out-of-range plane or layer index is passed via
      CL_IMPORT_ANDROID_HARDWARE_BUFFER_PLANE_INDEX_ARM or
      CL_IMPORT_ANDROID_HARDWARE_BUFFER_LAYER_INDEX_ARM.

      CL_INVALID_OPERATION when host virtual pages in the range of <memory> to
      <memory>+<size> are not mapped in the userspace address space. This does
      _not_ include cases where physical pages are not allocated. For specific
      behaviour see documentation for those memory types.

      CL_INVALID_OPERATION when an imported memory object has been passed to
      one of the following API functions (they can't be used with imported
      memory objects):

             * clEnqueueMapBuffer
             * clEnqueueMapImage
             * clEnqueueUnmapMemObject
             * clEnqueueReadImage
             * clEnqueueWriteImage
             * clEnqueueReadBuffer
             * clEnqueueReadBufferRect
             * clEnqueueWriteBuffer
             * clEnqueueWriteBufferRect
             * clEnqueueCopyBuffer
             * clEnqueueCopyBufferRect
             * clEnqueueCopyBufferToImage
             * clEnqueueCopyImageToBuffer
             * clEnqueueCopyImage
             * clEnqueueFillBuffer
             * clEnqueueFillImage

      CL_INVALID_OPERATION if a host memory flag other than CL_MEM_HOST_NO_ACCESS
      is used when CL_IMPORT_TYPE_PROTECTED_ARM is set to CL_TRUE.

      CL_INVALID_OPERATION if a command that makes use of a protected memory
      object is enqueued to a command queue that has CL_QUEUE_PROFILING_ENABLE
      set.

      Futher error information may be reported via the cl_context callback
      function.

New memory import types

    Linux dma_buf memory type - CL_IMPORT_TYPE_DMA_BUF_ARM

      If the extension string cl_arm_import_memory_dma_buf is exposed then
      importing from dma_buf file handles is supported.

      When CL_IMPORT_DMA_BUF_DATA_CONSISTENCY_WITH_HOST_ARM is set to CL_TRUE,
      the OpenCL runtime manages data consistency between the host CPU and the
      memory backing the dma_buf allocation. The application is still responsible
      for ensuring that changes to the memory done outside of the coherency domain
      in which the host CPU and the OpenCL device reside are made visibible to
      that coherency domain before using that memory from an OpenCL command. This
      can be achieved either by not enqueueing the workload until the data is
      visible, or by using a user event to prevent the command from being executed
      until the expected data has reached memory.

      Prior to the introduction of CL_IMPORT_DMA_BUF_DATA_CONSISTENCY_WITH_HOST_ARM
      drivers always managed data consistency between the host CPU and memory.

      Flags attached to a dma_buf file handle take precedence over memory flags
      supplied to clImportMemoryARM. For example, if a dma_buf allocation
      originally created with a read-only flag is passed to clImportMemoryARM
      with the READ_WRITE flag, the more restrictive READ_ONLY will take
      precedence.

      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.

      See also, the code example below.

    Host process memory type - CL_IMPORT_TYPE_HOST_ARM

      If the extension string cl_arm_import_memory_host is exposed then importing
      from normal userspace allocations (such as those created via malloc) is
      supported.

      If the host OS is linux and overcommit of VA is allowed, then this
      function will commit and pin physical pages for the VA range. This may
      cause larger physical allocations than the application typically provokes
      if memory is sparsely used. In this case sub-ranges of the host allocation
      should be passed to the import function individually.

      It is the application's responsibility to align for the datatype being
      accessed. Though the application is free to provide allocations without
      any specific alignment on coherent systems, there is a requirement to
      provide pointers aligned to a cache line on systems where there is no
      HW-managed coherency between CPU and GPU. When alignment is less than a
      page size then whole pages touched by addresses in the range of <memory>
      to <memory>+<size> will be mapped into the device. If the page is already
      mapped by another unaligned import, an error will occur.

      Cache coherency will be HW-managed on systems where it is supported.
      Otherwise, cache maintenance operations will be added by the CL runtime
      where needed.

      Importing host memory that is otherwise being used by a device outside
      of the CPU/GPU coherency domain isn't guaranteed to work and the GPU
      caches may contain stale data.

      Importing dma_buf pages through a CPU mapping is undefined.

      Importing two allocations that aren't page-aligned and that request
      different memory flags is unsupported; an error will be returned.

      This method is recommended to be used when interoperating with an existing
      host library which performs its own allocation and cannot be passed
      handles to mapped OpenCL buffers.

      See also, the code example below.

    Protected memory

      If the extension string cl_arm_import_memory_protected is exposed then
      using CL_IMPORT_TYPE_PROTECTED_ARM in the list of <properties> is
      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.

      In version 1.0.0:

      Multiplanar buffers are only supported when backed by a single dma_buf.

      In version 1.1.0:

      It is possible to select the specific plane or layer to import via
      CL_IMPORT_ANDROID_HARDWARE_BUFFER_PLANE_INDEX_ARM and/or
      CL_IMPORT_ANDROID_HARDWARE_BUFFER_LAYER_INDEX_ARM. The imported memory
      will start at the first pixel for the imported plane/layer.

      <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

Interactions with other extensions

    This extension produces cl_mem memory objects which are compatible with all
    other uses of cl_mem in the standard API, including creating images from
    the resulting cl_mem and subject to the restrictions listed in this
    document.

    In order to guarantee data consistency, applications must ensure that neither
    the host nor any device attempt to perform simultaneous read and write
    operations on any part of the memory backing an imported buffer or sub-buffers
    created therefrom, even if these accesses do not overlap. For example, this
    implies that it is not possible to write part of the memory backing an imported
    buffer on the host while reading a sub-buffer created from that buffer on a
    device, even if the memory written by the host is not visible through the
    sub-buffer.

    This extension also provides an alternative to image import via EGL.

Sample Code

    CL_IMPORT_TYPE_DMA_BUF_ARM

      #define WIDTH  1024
      #define HEIGHT 512

      // Create buffer to be used as a hardware texture with graphics APIs (can also
      // include video/camera use flags here)
      int dma_buf_handle = get_dma_buf_handle_from_exporter_kernel_module( ..., WIDTH * HEIGHT * 2 );

      cl_int error = CL_SUCCESS;
      cl_mem buffer = clImportMemoryARM( ctx,
                                         CL_MEM_READ_WRITE,
                                         { CL_IMPORT_TYPE_ARM, CL_IMPORT_TYPE_DMA_BUF_ARM, 0 },
                                         &dma_buf_handle
                                         WIDTH * HEIGHT * 2,
                                         &error );

      if( error == CL_SUCCESS )
      {
          // Use <buffer> as you would any other cl_mem buffer
      }


    CL_IMPORT_TYPE_HOST_ARM

      #define WIDTH  1024
      #define HEIGHT 512

      // tightly packed buffer we will treat as RGB565
      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,
                                         allocptr,
                                         WIDTH * HEIGHT * 2,
                                         &error );

      if( error == CL_SUCCESS )
      {
          // Use <buffer> as you would any other cl_mem buffer
      }

    CL_IMPORT_TYPE_PROTECTED_ARM

      #define BUFFER_SIZE 4096

      // Platform specific method of allocating protected memory and obtaining
      // a handle. For example, from a protected dma_buf or ION region.
      int protected_fd = protected_alloc( BUFFER_SIZE );

      cl_int error = CL_SUCCESS;
      // Import memory of type dma_buf and identify it as protected
      const cl_import_properties_arm properties = {
          CL_IMPORT_TYPE_ARM, CL_IMPORT_TYPE_DMA_BUF_ARM,
          CL_IMPORT_TYPE_PROTECTED_ARM, CL_TRUE,
          0
      };
      cl_mem buffer = clImportMemoryARM( context,
                                         CL_MEM_READ_WRITE,
                                         properties,
                                         &protected_fd,
                                         BUFFER_SIZE,
                                         &error );

      if( error == CL_SUCCESS )
      {
          // 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

Revision History

    Revision: #1, Apr 27th, 2015 - Initial revision
    Revision: #2, Apr 28th, 2015 - Added properties field to avoid type
                                   inferrence. Added Issues section.
    Revision: #3, May 5th, 2015  - Added image support info in Issues.
    Revision: #4, Aug 4th, 2015  - Revised based on implementation and design
                                   changes made during review.
    Revision: #5, May 3rd, 2017  - Additional restrictions on host operations
                                   and general cleanup / clarification.
    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.
    Revision: #10, Feb 13th, 2020 - Make dma_buf <-> host data consistency optional.
    Revision: #11, Feb 15th, 2021 - Add support for Android hardware buffer
                                    plane/layer selection.