table of contents
| CXL(3) | CXL Programmer's Manual | CXL(3) |
NAME¶
cxl - Coherent Accelerator Interface (CXL) library functions
SYNOPSIS¶
#include <libcxl.h>
DESCRIPTION¶
Introduction¶
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.
Constant macros¶
| 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 |
Enumeration macros¶
| 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 |
Enumeration functions¶
| 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 |
Open AFU functions¶
| 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 |
Work Structure Handling functions¶
| 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 |
Attach AFU Context functions¶
| 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 |
Wait for AFU Notification function¶
| Function | Description |
| cxl_afu_host_thread_wait | wait for AFU notification |
CXL Adapter Sysfs Helper functions¶
| 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 |
AFU Directed Master Context Sysfs Helper functions¶
| 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 |
AFU Context Sysfs Helper functions¶
| 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 |
Events functions¶
| 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 |
AFU MMIO functions¶
| 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 |
AFU Error Buffer query functions¶
| 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 |
SEE ALSO¶
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 |