ComputeMux CMake¶

The CMake for ComputeMux aims to make it as easy as possible for customer teams to integrate their compiler and runtime target into the oneAPI Construction Kit build.

modules/mux/CMakeLists.txt creates a static library target mux using add_ca_library() that frontend APIs implemented by the oneAPI Construction Kit, such as OpenCL, build on. ComputeMux library code provides entry points to the Mux API which perform implementation agnostic error checking of argument invalid usage, and then direct control flow through to a desired Mux implementation. The CA_MUX_ENABLE_SHARED option can be set to ‘TRUE’ if mux should be built as a shared library.

To allow customer teams to hook their ComputeMux implementation into the oneAPI Construction Kit ComputeMux CMakeLists provides the functions add_mux_target() and add_mux_compiler_target() which can be invoked by the customer code.

ComputeMux CMakeLists¶

modules/mux/targets/CMakeLists.txt provides the following variables and functions to be used when incorporating a ComputeMux target into the build.

MUX_TARGET_LIBRARIES¶: Variable containing a list of ComputeMux target libraries

CA_HOST_CL_DEVICE_NAME_PREFIX¶

ComputeAorta host CPU device names are always prefixed. The prefix together with the device type enables detection if a device is a CPU host device.

This variable is exported to ${CMAKE_BINARY_DIR}/source/cl/include/cl/config.h by source/cl/CMakeLists.txt. It has to be defined here to be available when Mux target CMakeLists.txt files are processed.

get_ca_host_arch¶

A CMake function that sets the given variable in the parent scope to the name of the host architecture.

Arguments:

target Library or executable target to link OpenCL into.

The following arguments are required:

parent_variable_name Name of the variable in the function’s parent scope to set to the architecture name.

The following keyword arguments are available:

ARCH <architecture> - (optional) Use the provided architecture instead of the native architecture CMake targets. The string is case-independent. “host” is supported in addition to the handled architectures listed below.
Handled architectures:
- Arm
- AArch64
- x86
- x86_64
- riscv64

get_ca_host_device_name¶

A CMake function that sets the given variable in the parent scope to the name of the host device.

The value stored in the parent scope variable can be passed to add_mux_target() as their DEVICE_NAMES parameter.

Important

This function MUST only be used for host CPU devices.

The following arguments are required:

parent_variable_name - name of the variable in the function’s parent scope to set to the architecture name.

The following keyword arguments are available:

ARCH <architecture> - (optional) use the provided architecture instead of the native architecture CMake targets. The string is case-independent. “host” is supported in addition to the handled architectures listed below and results in a name that clc can disambiguate from the normal host architecture device name.
Handled architectures:
- Arm
- AArch64
- x86
- x86_64

add_mux_target¶

The add_mux_target function makes mux aware of the existence of a mux target, ensuring that mux has the required information to properly integrate the target into the build. It also creates a custom target to generate an API header file for a mux implementation.

The following arguments are required:

target - the mux implementation CMake target.

The following keyword arguments are available:

HEADER_DIR <path> - (required) the output directory for the generated header file.
CAPABILITIES - (required) the target’s supported capabilities.
DEVICE_NAMES - (required) the names of the target’s devices, one item per device the mux target returns from <target>GetDevices().
CLANG_FORMAT_EXECUTABLE <path> - (optional) the path to a clang-format executable, use this to override the default clang-format configuration used by ComputeAorta e.g. if an alternate version is present than the one required by ComputeAorta.

The following CMake cached variables are set:

<target>_CAPABILITES
<target>_DEVICE_NAMES

The following CMake targets are added:

<target>-api-generate

modules/compiler/targets/CMakeLists.txt provides the following variables and functions to be used when incorporating a ComputeMux compiler into the build.

MUX_COMPILER_LIBRARIES¶: Variable containing a list of ComputeMux compiler libraries

add_mux_compiler_target¶

The add_mux_compiler_target function makes ComputeMux aware of the existence of a compiler target implementing the ComputeMux compiler API, ensuring that ComputeMux has the required information to properly integrate the compiler into the build.

The following arguments are required:

target - the compiler implementation CMake target.

The following keyword arguments are available:

COMPILER_INFO - (required) the fully qualified name of a function that returns static instance(s) of the compiler::Info object, describing each compiler configuration this target supports.
HEADER_FILE <path> - (required) the path to a header file that declares the above class or struct.

Host ComputeMux Target CMake¶

modules/mux/source/host/CMakeLists.txt integrates our Host CPU Mux target into the build and defines the following options implemented through add_ca_option().

CA_HOST_ENABLE_BUILTIN_KERNEL¶: Enable host reporting of builtin kernels. Defaults to the value of CA_ENABLE_DEBUG_SUPPORT as builtin kernels are implemented in software on host for testing purposes.

CA_HOST_ENABLE_BUILTINS_EXTENSION¶: Enable host specific extension cl_codeplay_host_builtins for builds where a compiler is available. Defaults to the value of CA_ENABLE_DEBUG_SUPPORT as the extension is primarily for testing the target specific CL extension mechanism.

CA_HOST_ENABLE_PAPI_COUNTERS¶: Enable counter type query pools in Host, supported with PAPI. Requires an installation of the PAPI library and headers.

mux-config Script¶

modules/mux/cmake/mux-config.cmake contains a CMake script that is run as part of the mux-config custom target as a dependency of the mux target.

A CMake script for creating the config.h header used to provide an API for selecting mux devices.

Script should be invoked using -P as part of an internal CMAKE_COMMAND. The following CMake input variables are required to be set:

MUX_TARGET_LIBRARIES - Input variable containing a list of Mux targets.
MUX_CONFIG_HEADER - Input variable containing the path to the header file to be written to.

ComputeMux Runtime API Generate CMake Target¶

modules/mux/tools/api/CMakeLists.txt defines a target mux-api-generate for generating C++ header file based on available Mux targets.

It is a convenient target for the oneAPI Construction Kit developers making Mux API changes to run. Developers can modify the mux.xml schema and then run the target, invoking Python scripts that update generated C++ header files, bump Mux version numbers, and add a stub TODO in the Mux changes.md document for the developer to replace.

Target mux-api-generate is created in this CMake file using add_custom_target and added as a dependency to our mux target.

mux-api-generate generates a header in the build directory called select.h which is used to switch between each of the Mux targets listed in MUX_TARGET_LIBRARIES for every Mux entry point. This model allows abstraction between the APIs we target and the Mux implementation, as Mux is responsible for plumbing control flow through to the correct backend.

Generation is performed by a Python script generate.py based on the mux.xml XML schema describing the Mux specification. update_version.py is also run by the mux-api-generate target to update the Mux API version in relevant documentation files spec.rst and changes.md to match the mux.xml version.