api/footnotes.asciidoc

// Copyright 2017-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

// Please keep footnotes in alphabetical order!

// Note: Follows the suggested syntax from:
// https://github.com/asciidoctor/asciidoctor-pdf/issues/1397

:fn-atomic-scope-work-item: pass:n[ \
Note that this flag does not provide meaning for atomic memory operations, but only for atomic fence operations in certain circumstances, refer to the Memory Scope section of the OpenCL C specification. \
]

:fn-create-context-all-or-subset: pass:n[ \
{clCreateContextfromType} may may create a context for all or a subset of the actual physical devices present in the platform that match _device_type_. \
]

:fn-default-device-queue: pass:n[ \
The application must create a default device queue if any kernels containing calls to `get_default_queue` are enqueued. \
There can only be one default device queue for each device within a context. \
If a default device queue has already been created, calling {clCreateCommandQueueWithProperties} with {CL_QUEUE_PROPERTIES} set to {CL_QUEUE_ON_DEVICE} and {CL_QUEUE_ON_DEVICE_DEFAULT} will return the default device queue that has already been created and increment its reference count by 1. \
]

:fn-depth-image-requirements: pass:n[ \
Support for the {CL_DEPTH} image channel order is required only for 2D images and 2D image arrays. \
]

:fn-duplicate-devices: pass:n[ \
Duplicate devices specified in _devices_ are ignored. \
]

:fn-endianness: pass:n[ \
Note that we are talking about the programming model here. \
In reality, little endian systems might choose to simply address their bytes from "the right" or reverse the "order" of the bits in the byte. \
Either of these choices would mean that no big swap would need to occur in hardware. \
]

:fn-error-precedence: pass:n[ \
The OpenCL specification does not describe the order of precedence for error codes returned by API calls. \
]

:fn-event-status-order: pass:n[ \
The error code values are negative, and event state values are positive. \
The event state values are ordered from the largest value {CL_QUEUED} for the first or initial state to the smallest value ({CL_COMPLETE} or negative integer value) for the last or complete state. \
The value of {CL_COMPLETE} and {CL_SUCCESS} are the same. \
]

:fn-get-device-ids-all-or-subset: pass:n[ \
{clGetDeviceIDs} may return all or a subset of the actual physical devices present in the platform and that match _device_type_. \
]

:fn-image-array-performance: pass:n[ \
Note that reading and writing 2D image arrays from a kernel with `image_array_size` equal to one may perform worse than 2D images. \
]

:fn-image-from-buffer: pass:n[ \
To create a 2D image from a buffer object that share the data store between the image and buffer object. \
]

:fn-image-from-image: pass:n[ \
To create an image object from another image object that share the data store between these image objects. \
]

:fn-image-mem-fence: pass:n[ \
This value for memory_scope can only be used with atomic_work_item_fence with flags set to `CLK_IMAGE_MEM_FENCE`. \
]

:fn-int64-performance: pass:n[ \
Note that the performance of 64-bit integer arithmetic can vary significantly between embedded devices. \
]

:fn-map-count-usage: pass:n[ \
The map count returned should be considered immediately stale. \
It is unsuitable for general use in applications. \
This feature is provided for debugging. \
]

:fn-max-read-image-args: pass:n[ \
A kernel that uses an image argument with the write_only or read_write image qualifier may result in additional read_only images resources being created internally by an implementation. \
The internally created read_only image resources will count against the max supported read image arguments given by {CL_DEVICE_MAX_READ_IMAGE_ARGS}. \
Enqueuing a kernel that requires more images than the implementation can support will result in a {CL_OUT_OF_RESOURCES} error being returned. \
]

:fn-native-rounding-modes: pass:n[ \
The optional rounding modes should be included as a device capability only if it is supported natively. \
All explicit conversion functions with specific rounding modes must still operate correctly. \
]

:fn-null-terminated-string: pass:n[ \
A null terminated string is returned by OpenCL query function calls if the return type of the information being queried is a {char_TYPE}[\]. \
]

:fn-out-of-order-device-queue: pass:n[ \
Only out-of-order device queues are supported. \
]

:fn-platform-profile: pass:n[ \
The platform profile returns the profile that is implemented by the OpenCL framework. \
If the platform profile returned is FULL_PROFILE, the OpenCL framework will support devices that are FULL_PROFILE and may also support devices that are EMBEDDED_PROFILE. \
The compiler must be available for all devices i.e. {CL_DEVICE_COMPILER_AVAILABLE} is {CL_TRUE}. \
If the platform profile returned is EMBEDDED_PROFILE, then devices that are only EMBEDDED_PROFILE are supported. \
]

:fn-race-condition: pass:n[ \
There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with {clEnqueueNDRangeKernel}. \
Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. \
Rather than attempt to share {cl_kernel_TYPE} objects among multiple host threads, applications are strongly encouraged to make additional {cl_kernel_TYPE} objects for kernel functions for each host thread. \
]

:fn-readimageh: pass:n[ \
And *read_imageh*, if the `cl_khr_fp16` extension is supported. \
]

:fn-reference-count-usage: pass:n[ \
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. \
]

:fn-setkernelarg-prefer-unset-on-error: pass:n[ \
Implementations are encouraged to favor this option as it makes it more likely that errors will be managed by applications. \
]

:fn-srgb-image-requirements: pass:n[ \
Support for reading from the {CL_sRGBA} image channel order is optional for 1D image buffers. \
Support for writing to the {CL_sRGBA} image channel order is optional for all image types. \
]

:fn-thread-safe: pass:n[ \
Please refer to the OpenCL glossary for the OpenCL definition of thread-safe. \
This definition may be different from usage of the term in other contexts. \
]

:fn-unsafe-denorms-are-zero: pass:n[ \
As per the definition of `-cl-denorms-are-zero`, the inclusion of this option with `-cl-unsafe-math-optimizations` means that the implementation may flush denormal numbers to zero but is not required to. \
]

:fn-vendor-id: pass:n[ \
OpenCL adopters must report a valid vendor ID for their implementation. \
If there is no valid PCI vendor ID defined for the physical device, implementations must obtain a Khronos vendor ID. \
This is a unique identifier greater than the largest PCI vendor ID (`0x10000`) and is representable by a {cl_uint_TYPE}. \
Khronos vendor IDs are synchronized across APIs by utilizing Vulkan's vk.xml as the central Khronos vendor ID registry. \
An ID must be reserved here prior to use in OpenCL, regardless of whether a vendor implements Vulkan. \
Only once the ID has been allotted may it be exposed to OpenCL by proposing a merge request against cl.xml, in the `main` branch of the OpenCL-Docs project. \
The merge must define a new enumerant by adding an `<enum>` tag to the {cl_khronos_vendor_id_TYPE} `<enums>` tag, with the `<value>` attribute set as the acquired Khronos vendor ID. \
The `<name>` attribute must identify the vendor/adopter, and be of the form `CL_KHRONOS_VENDOR_ID_<vendor>`. \
]