__CONSTANT(3clc)

💅 __CONSTANT — OpenCL Manual, but make it a group chat ✨

okay bestie, we're doing the __CONSTANT(3clc) page today. yes, from the OpenCL Manual. it's giving "type qualifier era" and honestly? iconic. let's get into it 🫶

---

🌸 NAME 🌸

__constant — the Address Space Qualifier, babe.

__constant constant

---

✨ DESCRIPTION ✨

so OpenCL has these disjoint address spaces and there are exactly four of them, no more no less: __global, __local, __constant, and __private. the address space qualifier is what you slap onto a variable declaration to say which region of memory is gonna hold that object. the C syntax for type qualifiers got extended in OpenCL so an address space name counts as a valid type qualifier. if your object's type is qualified with an address space name → congrats, it lives there. if not → it just chills in the generic address space. periodt.

also!! the address space names without the __ prefix — so like global, local, constant and private — can be substituted for the versions with the __ prefix. same energy, less typing. 💅

the generic address space name for arguments to a function in a program, or for local variables of a function, is __private. and listen: all function arguments shall be in the __private address space. all of them. no exceptions, bestie.

per functionQualifiers(3clc), function arguments declared to be a pointer of a type can point to one of these address spaces only: __global, __local or __constant. a pointer to address space A can only be assigned to a pointer to the same address space A. casting a pointer to address space A into a pointer to address space B? illegal 🚫 nope, don't do it, that's a whole crime.

function arguments of type otherDataTypes(3clc), otherDataTypes(3clc), otherDataTypes(3clc), otherDataTypes(3clc), otherDataTypes(3clc), and otherDataTypes(3clc) refer to image memory objects allocated in the __global address space. yes, six of them, all identical in the source, we don't make the rules 🌈

---

📝 NOTES 📝

the __constant (or just constant) address space name is used to describe variables allocated in global memory that get accessed inside a kernel(s) as read-only variables. these read-only variables can be accessed by all (global) work-items of the kernel while it's executing. pointers to the __constant address space are allowed as arguments to functions (including kernel functions) and for variables declared inside functions. so yes, that's a thing you can do 🎀

all string literal storage shall be in the __constant address space. every single one. they live there now.

NOTE: each argument to a kernel that's a pointer to the __constant address space gets counted separately towards the maximum number of such arguments, and that max is defined as CL_DEVICE_MAX_CONSTANT_ARGS, which is described in the table for clGetDeviceInfo(3clc). so like, they stack. count them. 💀

variables in the program scope, or in the outermost scope of kernel functions, can be declared in the __constant address space. but — and this is the important part — these variables are required to be initialized, and the values used to initialize them must be a compile time constant. writing to such a variable results in a compile-time error. do not attempt. it will not go well.

implementations are not required to aggregate these declarations into the fewest number of constant arguments. this behavior is implementation defined. so it's giving "whatever the implementation feels like" 🙈

therefore: portable code must conservatively assume that each variable declared inside a function, or in program scope, allocated in the __constant address space, counts as a separate constant argument. assume the worst, write the safest code, that's the vibe.

🦋 Example 🦋

there is no generic address space name for program scope variables. all program scope variables must be declared in the __constant address space. for example:

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

// declares an array of 4 floats in the
__private address space.  float x[4];

there is no address space for function return values. using an address space qualifier in a function return type declaration will generate a compilation error, unless the return type is declared as a pointer type and the qualifier is used on the points-to address space.

for example:

__private int f() { ... } // should
generate an error __local int *f() {
... } // allowed __local int *
__private f() { ... }; // should
generate an error.

---

⭐ SPECIFICATION ⭐

OpenCL Specification[1]

---

🔥 SEE ALSO 🔥

global(3clc), local(3clc), private(3clc)

---

👑 AUTHORS 👑

The Khronos Group

---

💜 COPYRIGHT 💜

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

---

🧚 NOTES 🧚

1. OpenCL Specification — page 222, section 6.5 - Address Space Qualifiers

---

and that's the whole page bestie, no cap 💖 this was brought to you by The Khronos Group, dated 01/14/2021, and yes it's still __CONSTANT(3clc) — she ate and left no crumbs, mwah 💅✨