1====================================
2Coherent Accelerator Interface (CXL)
3====================================
4
5Introduction
6============
7
8    The coherent accelerator interface is designed to allow the
9    coherent connection of accelerators (FPGAs and other devices) to a
10    POWER system. These devices need to adhere to the Coherent
11    Accelerator Interface Architecture (CAIA).
12
13    IBM refers to this as the Coherent Accelerator Processor Interface
14    or CAPI. In the kernel it's referred to by the name CXL to avoid
15    confusion with the ISDN CAPI subsystem.
16
17    Coherent in this context means that the accelerator and CPUs can
18    both access system memory directly and with the same effective
19    addresses.
20
21
22Hardware overview
23=================
24
25    ::
26
27         POWER8/9             FPGA
28       +----------+        +---------+
29       |          |        |         |
30       |   CPU    |        |   AFU   |
31       |          |        |         |
32       |          |        |         |
33       |          |        |         |
34       +----------+        +---------+
35       |   PHB    |        |         |
36       |   +------+        |   PSL   |
37       |   | CAPP |<------>|         |
38       +---+------+  PCIE  +---------+
39
40    The POWER8/9 chip has a Coherently Attached Processor Proxy (CAPP)
41    unit which is part of the PCIe Host Bridge (PHB). This is managed
42    by Linux by calls into OPAL. Linux doesn't directly program the
43    CAPP.
44
45    The FPGA (or coherently attached device) consists of two parts.
46    The POWER Service Layer (PSL) and the Accelerator Function Unit
47    (AFU). The AFU is used to implement specific functionality behind
48    the PSL. The PSL, among other things, provides memory address
49    translation services to allow each AFU direct access to userspace
50    memory.
51
52    The AFU is the core part of the accelerator (eg. the compression,
53    crypto etc function). The kernel has no knowledge of the function
54    of the AFU. Only userspace interacts directly with the AFU.
55
56    The PSL provides the translation and interrupt services that the
57    AFU needs. This is what the kernel interacts with. For example, if
58    the AFU needs to read a particular effective address, it sends
59    that address to the PSL, the PSL then translates it, fetches the
60    data from memory and returns it to the AFU. If the PSL has a
61    translation miss, it interrupts the kernel and the kernel services
62    the fault. The context to which this fault is serviced is based on
63    who owns that acceleration function.
64
65    - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
66    - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
67
68    This PSL Version 9 provides new features such as:
69
70    * Interaction with the nest MMU on the P9 chip.
71    * Native DMA support.
72    * Supports sending ASB_Notify messages for host thread wakeup.
73    * Supports Atomic operations.
74    * etc.
75
76    Cards with a PSL9 won't work on a POWER8 system and cards with a
77    PSL8 won't work on a POWER9 system.
78
79AFU Modes
80=========
81
82    There are two programming modes supported by the AFU. Dedicated
83    and AFU directed. AFU may support one or both modes.
84
85    When using dedicated mode only one MMU context is supported. In
86    this mode, only one userspace process can use the accelerator at
87    time.
88
89    When using AFU directed mode, up to 16K simultaneous contexts can
90    be supported. This means up to 16K simultaneous userspace
91    applications may use the accelerator (although specific AFUs may
92    support fewer). In this mode, the AFU sends a 16 bit context ID
93    with each of its requests. This tells the PSL which context is
94    associated with each operation. If the PSL can't translate an
95    operation, the ID can also be accessed by the kernel so it can
96    determine the userspace context associated with an operation.
97
98
99MMIO space
100==========
101
102    A portion of the accelerator MMIO space can be directly mapped
103    from the AFU to userspace. Either the whole space can be mapped or
104    just a per context portion. The hardware is self describing, hence
105    the kernel can determine the offset and size of the per context
106    portion.
107
108
109Interrupts
110==========
111
112    AFUs may generate interrupts that are destined for userspace. These
113    are received by the kernel as hardware interrupts and passed onto
114    userspace by a read syscall documented below.
115
116    Data storage faults and error interrupts are handled by the kernel
117    driver.
118
119
120Work Element Descriptor (WED)
121=============================
122
123    The WED is a 64-bit parameter passed to the AFU when a context is
124    started. Its format is up to the AFU hence the kernel has no
125    knowledge of what it represents. Typically it will be the
126    effective address of a work queue or status block where the AFU
127    and userspace can share control and status information.
128
129
130
131
132User API
133========
134
1351. AFU character devices
136^^^^^^^^^^^^^^^^^^^^^^^^
137
138    For AFUs operating in AFU directed mode, two character device
139    files will be created. /dev/cxl/afu0.0m will correspond to a
140    master context and /dev/cxl/afu0.0s will correspond to a slave
141    context. Master contexts have access to the full MMIO space an
142    AFU provides. Slave contexts have access to only the per process
143    MMIO space an AFU provides.
144
145    For AFUs operating in dedicated process mode, the driver will
146    only create a single character device per AFU called
147    /dev/cxl/afu0.0d. This will have access to the entire MMIO space
148    that the AFU provides (like master contexts in AFU directed).
149
150    The types described below are defined in include/uapi/misc/cxl.h
151
152    The following file operations are supported on both slave and
153    master devices.
154
155    A userspace library libcxl is available here:
156
157	https://github.com/ibm-capi/libcxl
158
159    This provides a C interface to this kernel API.
160
161open
162----
163
164    Opens the device and allocates a file descriptor to be used with
165    the rest of the API.
166
167    A dedicated mode AFU only has one context and only allows the
168    device to be opened once.
169
170    An AFU directed mode AFU can have many contexts, the device can be
171    opened once for each context that is available.
172
173    When all available contexts are allocated the open call will fail
174    and return -ENOSPC.
175
176    Note:
177	  IRQs need to be allocated for each context, which may limit
178          the number of contexts that can be created, and therefore
179          how many times the device can be opened. The POWER8 CAPP
180          supports 2040 IRQs and 3 are used by the kernel, so 2037 are
181          left. If 1 IRQ is needed per context, then only 2037
182          contexts can be allocated. If 4 IRQs are needed per context,
183          then only 2037/4 = 509 contexts can be allocated.
184
185
186ioctl
187-----
188
189    CXL_IOCTL_START_WORK:
190        Starts the AFU context and associates it with the current
191        process. Once this ioctl is successfully executed, all memory
192        mapped into this process is accessible to this AFU context
193        using the same effective addresses. No additional calls are
194        required to map/unmap memory. The AFU memory context will be
195        updated as userspace allocates and frees memory. This ioctl
196        returns once the AFU context is started.
197
198        Takes a pointer to a struct cxl_ioctl_start_work
199
200            ::
201
202                struct cxl_ioctl_start_work {
203                        __u64 flags;
204                        __u64 work_element_descriptor;
205                        __u64 amr;
206                        __s16 num_interrupts;
207                        __s16 reserved1;
208                        __s32 reserved2;
209                        __u64 reserved3;
210                        __u64 reserved4;
211                        __u64 reserved5;
212                        __u64 reserved6;
213                };
214
215            flags:
216                Indicates which optional fields in the structure are
217                valid.
218
219            work_element_descriptor:
220                The Work Element Descriptor (WED) is a 64-bit argument
221                defined by the AFU. Typically this is an effective
222                address pointing to an AFU specific structure
223                describing what work to perform.
224
225            amr:
226                Authority Mask Register (AMR), same as the powerpc
227                AMR. This field is only used by the kernel when the
228                corresponding CXL_START_WORK_AMR value is specified in
229                flags. If not specified the kernel will use a default
230                value of 0.
231
232            num_interrupts:
233                Number of userspace interrupts to request. This field
234                is only used by the kernel when the corresponding
235                CXL_START_WORK_NUM_IRQS value is specified in flags.
236                If not specified the minimum number required by the
237                AFU will be allocated. The min and max number can be
238                obtained from sysfs.
239
240            reserved fields:
241                For ABI padding and future extensions
242
243    CXL_IOCTL_GET_PROCESS_ELEMENT:
244        Get the current context id, also known as the process element.
245        The value is returned from the kernel as a __u32.
246
247
248mmap
249----
250
251    An AFU may have an MMIO space to facilitate communication with the
252    AFU. If it does, the MMIO space can be accessed via mmap. The size
253    and contents of this area are specific to the particular AFU. The
254    size can be discovered via sysfs.
255
256    In AFU directed mode, master contexts are allowed to map all of
257    the MMIO space and slave contexts are allowed to only map the per
258    process MMIO space associated with the context. In dedicated
259    process mode the entire MMIO space can always be mapped.
260
261    This mmap call must be done after the START_WORK ioctl.
262
263    Care should be taken when accessing MMIO space. Only 32 and 64-bit
264    accesses are supported by POWER8. Also, the AFU will be designed
265    with a specific endianness, so all MMIO accesses should consider
266    endianness (recommend endian(3) variants like: le64toh(),
267    be64toh() etc). These endian issues equally apply to shared memory
268    queues the WED may describe.
269
270
271read
272----
273
274    Reads events from the AFU. Blocks if no events are pending
275    (unless O_NONBLOCK is supplied). Returns -EIO in the case of an
276    unrecoverable error or if the card is removed.
277
278    read() will always return an integral number of events.
279
280    The buffer passed to read() must be at least 4K bytes.
281
282    The result of the read will be a buffer of one or more events,
283    each event is of type struct cxl_event, of varying size::
284
285            struct cxl_event {
286                    struct cxl_event_header header;
287                    union {
288                            struct cxl_event_afu_interrupt irq;
289                            struct cxl_event_data_storage fault;
290                            struct cxl_event_afu_error afu_error;
291                    };
292            };
293
294    The struct cxl_event_header is defined as
295
296        ::
297
298            struct cxl_event_header {
299                    __u16 type;
300                    __u16 size;
301                    __u16 process_element;
302                    __u16 reserved1;
303            };
304
305        type:
306            This defines the type of event. The type determines how
307            the rest of the event is structured. These types are
308            described below and defined by enum cxl_event_type.
309
310        size:
311            This is the size of the event in bytes including the
312            struct cxl_event_header. The start of the next event can
313            be found at this offset from the start of the current
314            event.
315
316        process_element:
317            Context ID of the event.
318
319        reserved field:
320            For future extensions and padding.
321
322    If the event type is CXL_EVENT_AFU_INTERRUPT then the event
323    structure is defined as
324
325        ::
326
327            struct cxl_event_afu_interrupt {
328                    __u16 flags;
329                    __u16 irq; /* Raised AFU interrupt number */
330                    __u32 reserved1;
331            };
332
333        flags:
334            These flags indicate which optional fields are present
335            in this struct. Currently all fields are mandatory.
336
337        irq:
338            The IRQ number sent by the AFU.
339
340        reserved field:
341            For future extensions and padding.
342
343    If the event type is CXL_EVENT_DATA_STORAGE then the event
344    structure is defined as
345
346        ::
347
348            struct cxl_event_data_storage {
349                    __u16 flags;
350                    __u16 reserved1;
351                    __u32 reserved2;
352                    __u64 addr;
353                    __u64 dsisr;
354                    __u64 reserved3;
355            };
356
357        flags:
358            These flags indicate which optional fields are present in
359            this struct. Currently all fields are mandatory.
360
361        address:
362            The address that the AFU unsuccessfully attempted to
363            access. Valid accesses will be handled transparently by the
364            kernel but invalid accesses will generate this event.
365
366        dsisr:
367            This field gives information on the type of fault. It is a
368            copy of the DSISR from the PSL hardware when the address
369            fault occurred. The form of the DSISR is as defined in the
370            CAIA.
371
372        reserved fields:
373            For future extensions
374
375    If the event type is CXL_EVENT_AFU_ERROR then the event structure
376    is defined as
377
378        ::
379
380            struct cxl_event_afu_error {
381                    __u16 flags;
382                    __u16 reserved1;
383                    __u32 reserved2;
384                    __u64 error;
385            };
386
387        flags:
388            These flags indicate which optional fields are present in
389            this struct. Currently all fields are Mandatory.
390
391        error:
392            Error status from the AFU. Defined by the AFU.
393
394        reserved fields:
395            For future extensions and padding
396
397
3982. Card character device (powerVM guest only)
399^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
400
401    In a powerVM guest, an extra character device is created for the
402    card. The device is only used to write (flash) a new image on the
403    FPGA accelerator. Once the image is written and verified, the
404    device tree is updated and the card is reset to reload the updated
405    image.
406
407open
408----
409
410    Opens the device and allocates a file descriptor to be used with
411    the rest of the API. The device can only be opened once.
412
413ioctl
414-----
415
416CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
417    Starts and controls flashing a new FPGA image. Partial
418    reconfiguration is not supported (yet), so the image must contain
419    a copy of the PSL and AFU(s). Since an image can be quite large,
420    the caller may have to iterate, splitting the image in smaller
421    chunks.
422
423    Takes a pointer to a struct cxl_adapter_image::
424
425        struct cxl_adapter_image {
426            __u64 flags;
427            __u64 data;
428            __u64 len_data;
429            __u64 len_image;
430            __u64 reserved1;
431            __u64 reserved2;
432            __u64 reserved3;
433            __u64 reserved4;
434        };
435
436    flags:
437        These flags indicate which optional fields are present in
438        this struct. Currently all fields are mandatory.
439
440    data:
441        Pointer to a buffer with part of the image to write to the
442        card.
443
444    len_data:
445        Size of the buffer pointed to by data.
446
447    len_image:
448        Full size of the image.
449
450
451Sysfs Class
452===========
453
454    A cxl sysfs class is added under /sys/class/cxl to facilitate
455    enumeration and tuning of the accelerators. Its layout is
456    described in Documentation/ABI/testing/sysfs-class-cxl
457
458
459Udev rules
460==========
461
462    The following udev rules could be used to create a symlink to the
463    most logical chardev to use in any programming mode (afuX.Yd for
464    dedicated, afuX.Ys for afu directed), since the API is virtually
465    identical for each::
466
467	SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
468	SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
469	                  KERNEL=="afu[0-9]*.[0-9]*s", SYMLINK="cxl/%b"
470