Description

OpenCL C has a hierarchical memory architecture represented by address spaces, as defined in section 5 of the Embedded C Specification. It extends the C syntax to allow an address space name as a valid type qualifier (section 5.1.2 of the Embedded C Specification). OpenCL implements disjoint named address spaces with the spelling __global, __local, __constant and __private. The address space qualifier may be used in variable declarations to specify the region where objects are to be allocated. If the type of an object is qualified by an address space name, the object is allocated in the specified address space. Similarly, for pointers, the type pointed to can be qualified by an address space signaling the address space where the object pointed to is located.

The address space name spelling without the __ prefix, i.e. global, local, constant and private, are valid and may be substituted for the corresponding address space names with the __ prefix.

Examples:

// declares a pointer p in the global address space that
// points to an object in the global address space
__global int *__global p;

void foo (...)
{
    // declares an array of 4 floats in the private address space
    __private float x[4];
    ...
}

For OpenCL C 2.0, or OpenCL C 3.0 with the __opencl_c_generic_address_space feature macro, there is an additional unnamed generic address space.

Most of the restrictions from section 5.1.2 and section 5.3 of the Embedded C Specification apply in OpenCL C, e.g. address spaces can not be used with a return type, a function parameter, or a function type, and multiple address space qualifiers are not allowed. However, in OpenCL C it is allowed to qualify local variables with an address space qualifier.

Examples:

// OK.
int f() { ... }

// Error. Address space qualifier cannot be used with a non-pointer return type.
private int f() { ... }

// OK. Address space qualifier can be used with a pointer return type.
local int *f() { ... }

// Error. Multiple address spaces specified for a type.
private local int i;

// OK. The first address space qualifies the object pointed to and the second
// qualifies the pointer.
private int *local ptr;

The __global, __constant, __local, __private, global, constant, local, and private names are reserved for use as address space qualifiers and shall not be used otherwise. The __generic and generic names are reserved for future use.

The size of pointers to different address spaces may differ. It is not correct to assume that, for example, sizeof(__global int *) always equals sizeof(__local int *).

See Also

Document Notes

For more information, see the OpenCL C Specification

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

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0