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