numba_vulkan.libclc#

Access to libclc, LLVM’s implementation of the OpenCL math library.

Vulkan’s own math library (GLSL.std.450) is small and 32-bit only. libclc provides the missing functions, and double precision versions of all of them, as LLVM bitcode. Its clspv build is written for Vulkan shaders, which makes it this target’s counterpart of CUDA’s libdevice.

Wheels bundle the bitcode; see find_bitcode for where it is looked for and version for which one is in use.

Attributes#

`CALLING_CONVENTION`
`ENV_VAR`
`CACHE_ENV_VAR`

Functions#

`find_bitcode`()	Locate libclc's `clspv--.bc`.
`available`()	Whether libclc can be used.
`version`()	Describe the libclc in use.
`read_bitcode`()	Contents of the bitcode file.
`cache_directory`()	Directory for files derived from libclc.
`prepared_bitcode`()	libclc in the form that is linked into kernels; see _prepare.
`mangle`(name, types)	Symbol of a libclc function.
`call`(builder, name, args[, restype])	Emit a call to a libclc function.

Module Contents#

numba_vulkan.libclc.CALLING_CONVENTION = 'spir_func'#

numba_vulkan.libclc.ENV_VAR = 'NUMBA_VULKAN_LIBCLC'#

numba_vulkan.libclc.CACHE_ENV_VAR = 'NUMBA_VULKAN_CACHE_DIR'#

numba_vulkan.libclc.find_bitcode()#

Locate libclc’s clspv--.bc.

The NUMBA_VULKAN_LIBCLC environment variable takes precedence and may name the file or the directory containing it. Otherwise the package’s own data directory and the usual system locations are searched.

Returns:: Path of the bitcode file, or None if libclc is not installed.
Return type:: str or None

numba_vulkan.libclc.available()#

Whether libclc can be used.

Return type:: bool

numba_vulkan.libclc.version()#

Describe the libclc in use.

The bundled copy carries a libclc-version.txt, written when the wheel was built. A copy from the Nix store is identified by its path.

Returns:: For example "22.1.8 (nixpkgs 774debe...)"; None if libclc is missing or its version is unknown.
Return type:: str or None

Examples

>>> from numba_vulkan import libclc
>>> libclc.version()
'22.1.8 (nixpkgs 774debe7a0d1b496e35677ad955a1011c6ff74f3)'

numba_vulkan.libclc.read_bitcode()#

Contents of the bitcode file.

Return type:: bytes
Raises:: FileNotFoundError – If libclc is not installed.

numba_vulkan.libclc.cache_directory()#

Directory for files derived from libclc.

NUMBA_VULKAN_CACHE_DIR if set, otherwise numba-vulkan below XDG_CACHE_HOME or ~/.cache.

Return type:: str

numba_vulkan.libclc.prepared_bitcode()#

libclc in the form that is linked into kernels; see _prepare.

Preparing takes a few seconds, so the result is kept in cache_directory, named after a hash of the original file. If that directory cannot be written, the work is redone once per process.

Return type:: bytes
Raises:: FileNotFoundError – If libclc is not installed.

numba_vulkan.libclc.mangle(name, types)#

Symbol of a libclc function.

libclc uses the Itanium C++ scheme, for example _Z3sind for sin(double).

Parameters:

name (str) – OpenCL name of the function.
types (sequence of llvmlite.ir.Type) – Scalar argument types.

Return type:

str

numba_vulkan.libclc.call(builder, name, args, restype=None)#

Emit a call to a libclc function.

Parameters:

builder (llvmlite.ir.IRBuilder) – Builder positioned where the code is emitted.
name (str) – OpenCL name of the function, for example "erf".
args (list of llvmlite.ir.Value) – Scalar arguments.
restype (llvmlite.ir.Type, optional) – Return type; that of the first argument by default.

Returns:

The result.

Return type:

llvmlite.ir.Value

Notes

The functions use the spir_func calling convention. Calling them with any other convention is undefined behaviour that LLVM turns into unreachable code.