cxl: Add documentation for userspace APIs
This documentation gives an overview of the hardware architecture, userspace APIs via /dev/cxl/afuM.N and the syfs files. It also adds a MAINTAINERS file entry for cxl. Signed-off-by: Ian Munsie <imunsie@au1.ibm.com> Signed-off-by: Michael Neuling <mikey@neuling.org> Signed-off-by: Michael Ellerman <mpe@ellerman.id.au>
Este cometimento está contido em:
Ian Munsie
cometido por
Michael Ellerman
Michael Ellerman
ascendente
881632c905
cometimento
a9282d01cf
@@ -11,6 +11,8 @@ bootwrapper.txt
|
||||
cpu_features.txt
|
||||
- info on how we support a variety of CPUs with minimal compile-time
|
||||
options.
|
||||
cxl.txt
|
||||
- Overview of the CXL driver.
|
||||
eeh-pci-error-recovery.txt
|
||||
- info on PCI Bus EEH Error Recovery
|
||||
firmware-assisted-dump.txt
|
||||
|
||||
379
Documentation/powerpc/cxl.txt
Ficheiro normal
379
Documentation/powerpc/cxl.txt
Ficheiro normal
@@ -0,0 +1,379 @@
|
||||
Coherent Accelerator Interface (CXL)
|
||||
====================================
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The coherent accelerator interface is designed to allow the
|
||||
coherent connection of accelerators (FPGAs and other devices) to a
|
||||
POWER system. These devices need to adhere to the Coherent
|
||||
Accelerator Interface Architecture (CAIA).
|
||||
|
||||
IBM refers to this as the Coherent Accelerator Processor Interface
|
||||
or CAPI. In the kernel it's referred to by the name CXL to avoid
|
||||
confusion with the ISDN CAPI subsystem.
|
||||
|
||||
Coherent in this context means that the accelerator and CPUs can
|
||||
both access system memory directly and with the same effective
|
||||
addresses.
|
||||
|
||||
|
||||
Hardware overview
|
||||
=================
|
||||
|
||||
POWER8 FPGA
|
||||
+----------+ +---------+
|
||||
| | | |
|
||||
| CPU | | AFU |
|
||||
| | | |
|
||||
| | | |
|
||||
| | | |
|
||||
+----------+ +---------+
|
||||
| PHB | | |
|
||||
| +------+ | PSL |
|
||||
| | CAPP |<------>| |
|
||||
+---+------+ PCIE +---------+
|
||||
|
||||
The POWER8 chip has a Coherently Attached Processor Proxy (CAPP)
|
||||
unit which is part of the PCIe Host Bridge (PHB). This is managed
|
||||
by Linux by calls into OPAL. Linux doesn't directly program the
|
||||
CAPP.
|
||||
|
||||
The FPGA (or coherently attached device) consists of two parts.
|
||||
The POWER Service Layer (PSL) and the Accelerator Function Unit
|
||||
(AFU). The AFU is used to implement specific functionality behind
|
||||
the PSL. The PSL, among other things, provides memory address
|
||||
translation services to allow each AFU direct access to userspace
|
||||
memory.
|
||||
|
||||
The AFU is the core part of the accelerator (eg. the compression,
|
||||
crypto etc function). The kernel has no knowledge of the function
|
||||
of the AFU. Only userspace interacts directly with the AFU.
|
||||
|
||||
The PSL provides the translation and interrupt services that the
|
||||
AFU needs. This is what the kernel interacts with. For example, if
|
||||
the AFU needs to read a particular effective address, it sends
|
||||
that address to the PSL, the PSL then translates it, fetches the
|
||||
data from memory and returns it to the AFU. If the PSL has a
|
||||
translation miss, it interrupts the kernel and the kernel services
|
||||
the fault. The context to which this fault is serviced is based on
|
||||
who owns that acceleration function.
|
||||
|
||||
|
||||
AFU Modes
|
||||
=========
|
||||
|
||||
There are two programming modes supported by the AFU. Dedicated
|
||||
and AFU directed. AFU may support one or both modes.
|
||||
|
||||
When using dedicated mode only one MMU context is supported. In
|
||||
this mode, only one userspace process can use the accelerator at
|
||||
time.
|
||||
|
||||
When using AFU directed mode, up to 16K simultaneous contexts can
|
||||
be supported. This means up to 16K simultaneous userspace
|
||||
applications may use the accelerator (although specific AFUs may
|
||||
support fewer). In this mode, the AFU sends a 16 bit context ID
|
||||
with each of its requests. This tells the PSL which context is
|
||||
associated with each operation. If the PSL can't translate an
|
||||
operation, the ID can also be accessed by the kernel so it can
|
||||
determine the userspace context associated with an operation.
|
||||
|
||||
|
||||
MMIO space
|
||||
==========
|
||||
|
||||
A portion of the accelerator MMIO space can be directly mapped
|
||||
from the AFU to userspace. Either the whole space can be mapped or
|
||||
just a per context portion. The hardware is self describing, hence
|
||||
the kernel can determine the offset and size of the per context
|
||||
portion.
|
||||
|
||||
|
||||
Interrupts
|
||||
==========
|
||||
|
||||
AFUs may generate interrupts that are destined for userspace. These
|
||||
are received by the kernel as hardware interrupts and passed onto
|
||||
userspace by a read syscall documented below.
|
||||
|
||||
Data storage faults and error interrupts are handled by the kernel
|
||||
driver.
|
||||
|
||||
|
||||
Work Element Descriptor (WED)
|
||||
=============================
|
||||
|
||||
The WED is a 64-bit parameter passed to the AFU when a context is
|
||||
started. Its format is up to the AFU hence the kernel has no
|
||||
knowledge of what it represents. Typically it will be the
|
||||
effective address of a work queue or status block where the AFU
|
||||
and userspace can share control and status information.
|
||||
|
||||
|
||||
|
||||
|
||||
User API
|
||||
========
|
||||
|
||||
For AFUs operating in AFU directed mode, two character device
|
||||
files will be created. /dev/cxl/afu0.0m will correspond to a
|
||||
master context and /dev/cxl/afu0.0s will correspond to a slave
|
||||
context. Master contexts have access to the full MMIO space an
|
||||
AFU provides. Slave contexts have access to only the per process
|
||||
MMIO space an AFU provides.
|
||||
|
||||
For AFUs operating in dedicated process mode, the driver will
|
||||
only create a single character device per AFU called
|
||||
/dev/cxl/afu0.0d. This will have access to the entire MMIO space
|
||||
that the AFU provides (like master contexts in AFU directed).
|
||||
|
||||
The types described below are defined in include/uapi/misc/cxl.h
|
||||
|
||||
The following file operations are supported on both slave and
|
||||
master devices.
|
||||
|
||||
|
||||
open
|
||||
----
|
||||
|
||||
Opens the device and allocates a file descriptor to be used with
|
||||
the rest of the API.
|
||||
|
||||
A dedicated mode AFU only has one context and only allows the
|
||||
device to be opened once.
|
||||
|
||||
An AFU directed mode AFU can have many contexts, the device can be
|
||||
opened once for each context that is available.
|
||||
|
||||
When all available contexts are allocated the open call will fail
|
||||
and return -ENOSPC.
|
||||
|
||||
Note: IRQs need to be allocated for each context, which may limit
|
||||
the number of contexts that can be created, and therefore
|
||||
how many times the device can be opened. The POWER8 CAPP
|
||||
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
|
||||
left. If 1 IRQ is needed per context, then only 2037
|
||||
contexts can be allocated. If 4 IRQs are needed per context,
|
||||
then only 2037/4 = 509 contexts can be allocated.
|
||||
|
||||
|
||||
ioctl
|
||||
-----
|
||||
|
||||
CXL_IOCTL_START_WORK:
|
||||
Starts the AFU context and associates it with the current
|
||||
process. Once this ioctl is successfully executed, all memory
|
||||
mapped into this process is accessible to this AFU context
|
||||
using the same effective addresses. No additional calls are
|
||||
required to map/unmap memory. The AFU memory context will be
|
||||
updated as userspace allocates and frees memory. This ioctl
|
||||
returns once the AFU context is started.
|
||||
|
||||
Takes a pointer to a struct cxl_ioctl_start_work:
|
||||
|
||||
struct cxl_ioctl_start_work {
|
||||
__u64 flags;
|
||||
__u64 work_element_descriptor;
|
||||
__u64 amr;
|
||||
__s16 num_interrupts;
|
||||
__s16 reserved1;
|
||||
__s32 reserved2;
|
||||
__u64 reserved3;
|
||||
__u64 reserved4;
|
||||
__u64 reserved5;
|
||||
__u64 reserved6;
|
||||
};
|
||||
|
||||
flags:
|
||||
Indicates which optional fields in the structure are
|
||||
valid.
|
||||
|
||||
work_element_descriptor:
|
||||
The Work Element Descriptor (WED) is a 64-bit argument
|
||||
defined by the AFU. Typically this is an effective
|
||||
address pointing to an AFU specific structure
|
||||
describing what work to perform.
|
||||
|
||||
amr:
|
||||
Authority Mask Register (AMR), same as the powerpc
|
||||
AMR. This field is only used by the kernel when the
|
||||
corresponding CXL_START_WORK_AMR value is specified in
|
||||
flags. If not specified the kernel will use a default
|
||||
value of 0.
|
||||
|
||||
num_interrupts:
|
||||
Number of userspace interrupts to request. This field
|
||||
is only used by the kernel when the corresponding
|
||||
CXL_START_WORK_NUM_IRQS value is specified in flags.
|
||||
If not specified the minimum number required by the
|
||||
AFU will be allocated. The min and max number can be
|
||||
obtained from sysfs.
|
||||
|
||||
reserved fields:
|
||||
For ABI padding and future extensions
|
||||
|
||||
CXL_IOCTL_GET_PROCESS_ELEMENT:
|
||||
Get the current context id, also known as the process element.
|
||||
The value is returned from the kernel as a __u32.
|
||||
|
||||
|
||||
mmap
|
||||
----
|
||||
|
||||
An AFU may have an MMIO space to facilitate communication with the
|
||||
AFU. If it does, the MMIO space can be accessed via mmap. The size
|
||||
and contents of this area are specific to the particular AFU. The
|
||||
size can be discovered via sysfs.
|
||||
|
||||
In AFU directed mode, master contexts are allowed to map all of
|
||||
the MMIO space and slave contexts are allowed to only map the per
|
||||
process MMIO space associated with the context. In dedicated
|
||||
process mode the entire MMIO space can always be mapped.
|
||||
|
||||
This mmap call must be done after the START_WORK ioctl.
|
||||
|
||||
Care should be taken when accessing MMIO space. Only 32 and 64-bit
|
||||
accesses are supported by POWER8. Also, the AFU will be designed
|
||||
with a specific endianness, so all MMIO accesses should consider
|
||||
endianness (recommend endian(3) variants like: le64toh(),
|
||||
be64toh() etc). These endian issues equally apply to shared memory
|
||||
queues the WED may describe.
|
||||
|
||||
|
||||
read
|
||||
----
|
||||
|
||||
Reads events from the AFU. Blocks if no events are pending
|
||||
(unless O_NONBLOCK is supplied). Returns -EIO in the case of an
|
||||
unrecoverable error or if the card is removed.
|
||||
|
||||
read() will always return an integral number of events.
|
||||
|
||||
The buffer passed to read() must be at least 4K bytes.
|
||||
|
||||
The result of the read will be a buffer of one or more events,
|
||||
each event is of type struct cxl_event, of varying size.
|
||||
|
||||
struct cxl_event {
|
||||
struct cxl_event_header header;
|
||||
union {
|
||||
struct cxl_event_afu_interrupt irq;
|
||||
struct cxl_event_data_storage fault;
|
||||
struct cxl_event_afu_error afu_error;
|
||||
};
|
||||
};
|
||||
|
||||
The struct cxl_event_header is defined as:
|
||||
|
||||
struct cxl_event_header {
|
||||
__u16 type;
|
||||
__u16 size;
|
||||
__u16 process_element;
|
||||
__u16 reserved1;
|
||||
};
|
||||
|
||||
type:
|
||||
This defines the type of event. The type determines how
|
||||
the rest of the event is structured. These types are
|
||||
described below and defined by enum cxl_event_type.
|
||||
|
||||
size:
|
||||
This is the size of the event in bytes including the
|
||||
struct cxl_event_header. The start of the next event can
|
||||
be found at this offset from the start of the current
|
||||
event.
|
||||
|
||||
process_element:
|
||||
Context ID of the event.
|
||||
|
||||
reserved field:
|
||||
For future extensions and padding.
|
||||
|
||||
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
|
||||
structure is defined as:
|
||||
|
||||
struct cxl_event_afu_interrupt {
|
||||
__u16 flags;
|
||||
__u16 irq; /* Raised AFU interrupt number */
|
||||
__u32 reserved1;
|
||||
};
|
||||
|
||||
flags:
|
||||
These flags indicate which optional fields are present
|
||||
in this struct. Currently all fields are mandatory.
|
||||
|
||||
irq:
|
||||
The IRQ number sent by the AFU.
|
||||
|
||||
reserved field:
|
||||
For future extensions and padding.
|
||||
|
||||
If the event type is CXL_EVENT_DATA_STORAGE then the event
|
||||
structure is defined as:
|
||||
|
||||
struct cxl_event_data_storage {
|
||||
__u16 flags;
|
||||
__u16 reserved1;
|
||||
__u32 reserved2;
|
||||
__u64 addr;
|
||||
__u64 dsisr;
|
||||
__u64 reserved3;
|
||||
};
|
||||
|
||||
flags:
|
||||
These flags indicate which optional fields are present in
|
||||
this struct. Currently all fields are mandatory.
|
||||
|
||||
address:
|
||||
The address that the AFU unsuccessfully attempted to
|
||||
access. Valid accesses will be handled transparently by the
|
||||
kernel but invalid accesses will generate this event.
|
||||
|
||||
dsisr:
|
||||
This field gives information on the type of fault. It is a
|
||||
copy of the DSISR from the PSL hardware when the address
|
||||
fault occurred. The form of the DSISR is as defined in the
|
||||
CAIA.
|
||||
|
||||
reserved fields:
|
||||
For future extensions
|
||||
|
||||
If the event type is CXL_EVENT_AFU_ERROR then the event structure
|
||||
is defined as:
|
||||
|
||||
struct cxl_event_afu_error {
|
||||
__u16 flags;
|
||||
__u16 reserved1;
|
||||
__u32 reserved2;
|
||||
__u64 error;
|
||||
};
|
||||
|
||||
flags:
|
||||
These flags indicate which optional fields are present in
|
||||
this struct. Currently all fields are Mandatory.
|
||||
|
||||
error:
|
||||
Error status from the AFU. Defined by the AFU.
|
||||
|
||||
reserved fields:
|
||||
For future extensions and padding
|
||||
|
||||
Sysfs Class
|
||||
===========
|
||||
|
||||
A cxl sysfs class is added under /sys/class/cxl to facilitate
|
||||
enumeration and tuning of the accelerators. Its layout is
|
||||
described in Documentation/ABI/testing/sysfs-class-cxl
|
||||
|
||||
Udev rules
|
||||
==========
|
||||
|
||||
The following udev rules could be used to create a symlink to the
|
||||
most logical chardev to use in any programming mode (afuX.Yd for
|
||||
dedicated, afuX.Ys for afu directed), since the API is virtually
|
||||
identical for each:
|
||||
|
||||
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
|
||||
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
|
||||
KERNEL=="afu[0-9]*.[0-9]*s", SYMLINK="cxl/%b"
|
||||
Criar uma nova questão referindo esta
Bloquear um utilizador