DOKK / manpages / debian 10 / libcxl-dev / cxl.3.en
CXL(3) CXL Programmer's Manual CXL(3)

cxl - Coherent Accelerator Interface (CXL) library functions

#include <libcxl.h>

The coherent accelerator interface is designed to allow the coherent connection of accelerators (FPGAs and other devices) to a POWER system. Coherent in this context means that the accelerator and CPUs can both access system memory directly and with the same effective addresses. IBM refers to this as the Coherent Accelerator Processor Interface (CAPI). In the Linux world it is referred to by the name CXL to avoid confusion with the ISDN CAPI subsystem.

The Linux kernel interacts with the device POWER Service Layer (PSL). Userland interacts with the device Accelerator Function Unit (AFU). See the Linux kernel source file Documentation/powerpc/cxl.txt for a detailed description of the coherent accelerator interface.

The CXL library provides a userland API to coherently attached devices. CXL devices can be enumerated. Their capabilities can be queried. AFUs can be opened, attached to the current process, and started. Jobs, described by AFU specific Work Element Descriptors (WEDs), can be submitted and executed by AFUs. AFU MMIO space can be mapped into the current process memory, and AFUs can be configured and controlled via MMIO reads and writes. Also if an AFU exports an AFU Error Buffer (afu_err_buff), its contents can be queried.

Macro Description
CXL_DEV_DIR CXL device directory pathname
CXL_KERNEL_API_VERSION maximum supported CXL kernel API compatible version
CXL_MMIO_BIG_ENDIAN big-endian AFU flag
CXL_MMIO_HOST_ENDIAN host-endian AFU flag
CXL_MMIO_LITTLE_ENDIAN little-endian AFU flag
CXL_MODE_DEDICATED dedicated process mode flag
CXL_MODE_DIRECTED AFU directed mode flag
CXL_SYSFS_CLASS sysfs CXL class pathname

Macro Description
cxl_for_each_adapter enumerate the available CXL adapters
cxl_for_each_adapter_afu enumerate the AFUs of a CXL adapter
cxl_for_each_afu enumerate the available AFUs

Function Description
cxl_adapter_dev_name return the CXL adapter device name
cxl_adapter_free free the CXL adapter data structures
cxl_adapter_next iterate to the next CXL adapter
cxl_adapter_afu_next iterate to the next AFU of a CXL adapter
cxl_afu_dev_name return the AFU device name
cxl_afu_next iterate to the next AFU

Function Description
cxl_afu_fd return the file descriptor of an AFU handle
cxl_afu_fd_to_h create an AFU handle from the file descriptor of an already open AFU
cxl_afu_free free the data structures of an AFU handle
cxl_afu_get_process_element get the process element associated with an open AFU handle
cxl_afu_open_dev open an AFU by device name
cxl_afu_open_h open an AFU by AFU handle
cxl_afu_opened return whether an AFU handle is opened

Function Description
cxl_work_alloc allocate and initialize a work structure
cxl_work_disable_wait indicate that a host thread will not wait
cxl_work_enable_wait indicate that a host thread will wait
cxl_work_free free a work structure
cxl_work_get_amr get the value of the authority mask register
cxl_work_get_num_irqs get the number of interrupts requested
cxl_work_get_tid get the tid of the thread that will wait
cxl_work_get_wed get the value of the work element descriptor
cxl_work_set_amr set the value of the authority mask register
cxl_work_set_num_irqs set the number of interrupts requested
cxl_work_set_wed set the value of the work element descriptor

Function Description
cxl_afu_attach attach the calling process's memory to an open AFU
cxl_afu_attach_full attach the calling process's memory to an open AFU (Deprecated Interface)
cxl_afu_attach_work attach the calling process's memory to an open AFU

Function Description
cxl_afu_host_thread_wait wait for AFU notification

Function Description
cxl_get_base_image get the revision level of the initial PSL image loaded on the CXL device
cxl_get_caia_version get the CAIA version supported by a CXL adapter
cxl_get_image_loaded returns which of the user and factory PSL images is currently loaded on the CXL device
cxl_get_psl_revision get the revision level of the current PSL image loaded on the CXL device
cxl_get_psl_timebase_synced get the status of timebase on the CXL device
cxl_get_tunneled_ops_supported get the status of tunneled operations on the CXL device

Function Description
cxl_get_mmio_size get the total size of the MMIO space of an AFU, including all per-process areas
cxl_get_pp_mmio_len get the per-process MMIO space length
cxl_get_pp_mmio_off get the per-process MMIO space offset

Function Description
cxl_afu_sysfs_pci get the sysfs path to the PCI device corresponding with an AFU
cxl_get_mmio_size get the size of the MMIO space available to a non-master process
cxl_get_mode get the current programming mode of an AFU
cxl_get_modes_supported get the programming modes supported by an AFU
cxl_get_prefault_mode get the mode for prefaulting segments
cxl_get_api_version get the version of the kernel CXL API
cxl_get_api_version_compatible get the lowest CXL API version compatible with the kernel
cxl_get_cr_class get the class code out of an AFU configuration record
cxl_get_cr_device get the device ID out of an AFU configuration record
cxl_get_cr_vendor get the vendor ID out of an AFU configuration record
cxl_get_irqs_max get the maximum number of AFU interrupts available to a context,
if it was the only context running
cxl_get_irqs_min get the minimum number of AFU interrupts required for each context
cxl_set_irqs_max administratively restrict the maximum number of AFU interrupts
that can be used by a single context
cxl_set_mode set the programming mode of an AFU
cxl_set_prefault_mode set the mode for prefaulting segments

Function Description
cxl_fprint_event print out a description of a CXL event for debugging
cxl_fprint_unknown_event print out a hex dump of a raw CXL event for debugging
cxl_event_pending return whether a CXL event is pending
cxl_read_event read one CXL event from an AFU
cxl_read_expected_event read one CXL event from an AFU, and treat it as a failure,
if it did not match an expected event

Function Description
cxl_mmio_map map the per-process Problem State Area of an AFU to memory
cxl_mmio_ptr return the address of the mapped AFU Problem State Area
cxl_mmio_read32 read a 32-bit word from the mapped AFU Problem State Area
cxl_mmio_read64 read a 64-bit word from the mapped AFU Problem State Area
cxl_mmio_unmap unmap an AFU Problem State Area
cxl_mmio_write32 write a 32-bit word to the mapped AFU Problem State Area
cxl_mmio_write64 write a 32-bit word to the mapped AFU Problem State Area

Function Description
cxl_errinfo_read read and copy the contents of afu_err_info buffer into the provided buffer
cxl_errinfo_size returns the size of afu_err_buff in bytes

cxl_adapter_afu_next(3), cxl_adapter_dev_name(3), cxl_adapter_free(3), cxl_adapter_next(3), cxl_afu_attach(3), cxl_afu_attach_full(3), cxl_afu_attach_work(3), cxl_afu_attach_work(3), cxl_afu_dev_name(3), cxl_afu_fd(3), cxl_afu_fd_to_h(3), cxl_afu_free(3), cxl_afu_get_process_element(3), cxl_afu_host_thread_wait(3), cxl_afu_next(3), cxl_afu_open_dev(3), cxl_afu_open_h(3), cxl_afu_opened(3), cxl_afu_sysfs_pci(3), cxl_errinfo_read(3), cxl_errinfo_size(3), cxl_event_pending(3), cxl_for_each_adapter(3), cxl_for_each_adapter_afu(3), cxl_for_each_afu(3), cxl_fprint_event(3), cxl_fprint_unknown_event(3), cxl_get_api_version(3), cxl_get_api_version_compatible(3), cxl_get_base_image(3), cxl_get_caia_version(3), cxl_get_cr_class(3), cxl_get_cr_device(3), cxl_get_cr_vendor(3), cxl_get_image_loaded(3), cxl_get_irqs_max(3), cxl_get_irqs_min(3), cxl_get_mmio_size(3), cxl_get_mode(3), cxl_get_modes_supported(3), cxl_get_pp_mmio_len(3), cxl_get_pp_mmio_off(3), cxl_get_prefault_mode(3), cxl_get_psl_revision(3), cxl_get_psl_timebase_synced(3), cxl_get_tunneled_ops_supported(3), cxl_mmio_install_sigbus_handler(3), cxl_mmio_map(3), cxl_mmio_ptr(3), cxl_mmio_read32(3), cxl_mmio_read64(3), cxl_mmio_unmap(3), cxl_mmio_write32(3), cxl_mmio_write64(3), cxl_read_event(3), cxl_read_expected_event(3), cxl_set_irqs_max(3), cxl_set_mode(3), cxl_set_prefault_mode(3) cxl_work_alloc(3), cxl_work_disable_wait(3), cxl_work_enable_wait(3), cxl_work_free(3), cxl_work_get_amr(3), cxl_work_get_num_irqs(3), cxl_work_get_tid(3), cxl_work_get_wed(3), cxl_work_set_amr(3), cxl_work_set_num_irqs(3), cxl_work_set_wed(3)

2018-04-26 LIBCXL 1.7