C Specification

To get information that is common to all memory objects (buffer and image objects), call the function

cl_int clGetMemObjectInfo(
    cl_mem memobj,
    cl_mem_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

Parameters

  • memobj specifies the memory object being queried.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetMemObjectInfo is described in the Memory Object Info table.

  • param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

  • param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Memory Object Info table.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. List of supported param_names by https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clGetMemObjectInfo
cl_mem_info Return type Info. returned in param_value

CL_​MEM_​TYPE

cl_mem_object_type

Returns one of the following values:

CL_​MEM_​OBJECT_​BUFFER if memobj is created with clCreateBuffer or clCreateSubBuffer.

cl_image_desc.image_type argument value if memobj is created with clCreateImage, clCreateImage2D or clCreateImage3D.

CL_​MEM_​OBJECT_​PIPE if memobj is created with clCreatePipe.

CL_​MEM_​FLAGS

cl_mem_flags

Return the flags argument value specified when memobj is created with clCreateBuffer,
clCreateSubBuffer,
clCreateImage or
clCreateImage2D or
clCreateImage3D or
clCreatePipe.

If memobj is a sub-buffer the memory access qualifiers inherited from parent buffer is also returned.

CL_​MEM_​SIZE

size_t

Return actual size of the data store associated with memobj in bytes.

CL_​MEM_​HOST_​PTR

void *

If memobj is created with clCreateBuffer, clCreateImage, clCreateImage2D or clCreateImage3D and CL_​MEM_​USE_​HOST_​PTR is specified in mem_flags, return the host_ptr argument value specified when memobj is created. Otherwise a NULL value is returned.

If memobj is created with clCreateSubBuffer, return the host_ptr + origin value specified when memobj is created. host_ptr is the argument value specified to clCreateBuffer and CL_​MEM_​USE_​HOST_​PTR is specified in mem_flags for memory object from which memobj is created. Otherwise a NULL value is returned.

CL_​MEM_​MAP_​COUNT11

cl_uint

Map count.

CL_​MEM_​REFERENCE_​COUNT12

cl_uint

Return memobj reference count.

CL_​MEM_​CONTEXT

cl_context

Return context specified when memory object is created. If memobj is created using clCreateSubBuffer, the context associated with the memory object specified as the buffer argument to clCreateSubBuffer is returned.

CL_​MEM_​ASSOCIATED_​MEMOBJECT

Missing before version 1.1.

cl_mem

Return memory object from which memobj is created. This returns the memory object specified as buffer argument to clCreateSubBuffer if memobj is a subbuffer object created using clCreateSubBuffer.

This returns the mem_object specified in cl_image_desc if memobj is an image object.

Otherwise a NULL value is returned.

CL_​MEM_​OFFSET

Missing before version 1.1.

size_t

Return offset if memobj is a sub-buffer object created using clCreateSubBuffer.

This return 0 if memobj is not a subbuffer object.

CL_​MEM_​USES_​SVM_​POINTER

Missing before version 2.0.

cl_bool

Return CL_​TRUE if memobj is a buffer object that was created with CL_​MEM_​USE_​HOST_​PTR or is a sub-buffer object of a buffer object that was created with CL_​MEM_​USE_​HOST_​PTR and the host_ptr specified when the buffer object was created is a SVM pointer; otherwise returns CL_​FALSE.

11

The map count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for debugging.

12

The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.

clGetMemObjectInfo returns CL_​SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_​INVALID_​VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the Memory Object Info table and param_value is not NULL.

  • CL_​INVALID_​MEM_​OBJECT if memobj is a not a valid memory object.

  • CL_​OUT_​OF_​RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_​OUT_​OF_​HOST_​MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

See Also

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.