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 and Vulkan, 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.
See also
See Runtime CMake Integration for a detailed description on adding a target to Mux.
Once Mux targets have been integrated by hooking into our CMake, the variable
MUX_TARGET_LIBRARIES will contain a list
of Mux implementations to include in the build. So that our mux static
library code can detect and select between these libraries we generate header
files config.h and
select.h.
See also
The root oneAPI Construction Kit CMakeLists.txt provides
ca_option() CA_MUX_TARGETS_TO_ENABLE to overwrite
MUX_TARGET_LIBRARIES with forced Mux targets. Option defaults to an empty
string, enabling all targets found in the source tree.
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.hbysource/cl/CMakeLists.txt. It has to be defined here to be available when Mux targetCMakeLists.txtfiles 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:
targetLibrary or executable target to link OpenCL into.
- The following arguments are required:
parent_variable_nameName 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 theirDEVICE_NAMESparameter.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 thatclccan disambiguate from the normal host architecture device name.- Handled architectures:
Arm
AArch64
x86
x86_64
- add_mux_target
The
add_mux_targetfunction 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 aclang-formatexecutable, use this to override the defaultclang-formatconfiguration 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_targetfunction 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_ENABLED
Option for enabling host Mux target, defaults to on.
- CA_HOST_ENABLE_BUILTIN_KERNEL
Enable host reporting of builtin kernels. Defaults to the value of
CA_ENABLE_DEBUG_SUPPORTas builtin kernels are implemented in software on host for testing purposes.
- CA_HOST_ENABLE_BUILTINS_EXTENSION
Enable host specific extension
cl_codeplay_host_builtinsfor builds where a compiler is available. Defaults to the value ofCA_ENABLE_DEBUG_SUPPORTas 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.
