[deliverable/linux.git] / Documentation / powerpc / cxl.txt

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.

    A userspace library libcxl is available here:
	https://github.com/ibm-capi/libcxl
    This provides a C interface to this kernel API.

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"
Commit	Line	Data
a9282d01 IM	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 FPGA
	25	+----------+ +---------+
	26	\| \| \| \|
	27	\| CPU \| \| AFU \|
	28	\| \| \| \|
	29	\| \| \| \|
	30	\| \| \| \|
	31	+----------+ +---------+
	32	\| PHB \| \| \|
	33	\| +------+ \| PSL \|
	34	\| \| CAPP \|<------>\| \|
	35	+---+------+ PCIE +---------+
	36
	37	The POWER8 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
	63	AFU Modes
	64	=========
65
66	There are two programming modes supported by the AFU. Dedicated
67	and AFU directed. AFU may support one or both modes.
68
69	When using dedicated mode only one MMU context is supported. In
70	this mode, only one userspace process can use the accelerator at
71	time.
72
73	When using AFU directed mode, up to 16K simultaneous contexts can
74	be supported. This means up to 16K simultaneous userspace
75	applications may use the accelerator (although specific AFUs may
76	support fewer). In this mode, the AFU sends a 16 bit context ID
77	with each of its requests. This tells the PSL which context is
78	associated with each operation. If the PSL can't translate an
79	operation, the ID can also be accessed by the kernel so it can
80	determine the userspace context associated with an operation.
81
82
83	MMIO space
84	==========
85
86	A portion of the accelerator MMIO space can be directly mapped
87	from the AFU to userspace. Either the whole space can be mapped or
88	just a per context portion. The hardware is self describing, hence
89	the kernel can determine the offset and size of the per context
90	portion.
91
92
93	Interrupts
94	==========
95
96	AFUs may generate interrupts that are destined for userspace. These
97	are received by the kernel as hardware interrupts and passed onto
98	userspace by a read syscall documented below.
99
100	Data storage faults and error interrupts are handled by the kernel
101	driver.
102
103
104	Work Element Descriptor (WED)
105	=============================
106
107	The WED is a 64-bit parameter passed to the AFU when a context is
108	started. Its format is up to the AFU hence the kernel has no
109	knowledge of what it represents. Typically it will be the
110	effective address of a work queue or status block where the AFU
111	and userspace can share control and status information.
112
113
114
115
116	User API
117	========
118
119	For AFUs operating in AFU directed mode, two character device
120	files will be created. /dev/cxl/afu0.0m will correspond to a
121	master context and /dev/cxl/afu0.0s will correspond to a slave
122	context. Master contexts have access to the full MMIO space an
123	AFU provides. Slave contexts have access to only the per process
124	MMIO space an AFU provides.
125
126	For AFUs operating in dedicated process mode, the driver will
127	only create a single character device per AFU called
128	/dev/cxl/afu0.0d. This will have access to the entire MMIO space
129	that the AFU provides (like master contexts in AFU directed).
130
131	The types described below are defined in include/uapi/misc/cxl.h
132
133	The following file operations are supported on both slave and
134	master devices.
135
dc12f20b	136	A userspace library libcxl is available here:
aee85fb6 MN	137	https://github.com/ibm-capi/libcxl
aee85fb6 MN	138	This provides a C interface to this kernel API.
a9282d01 IM	139
	140	open
	141	----
	142
	143	Opens the device and allocates a file descriptor to be used with
	144	the rest of the API.
	145
	146	A dedicated mode AFU only has one context and only allows the
	147	device to be opened once.
	148
	149	An AFU directed mode AFU can have many contexts, the device can be
	150	opened once for each context that is available.
	151
	152	When all available contexts are allocated the open call will fail
	153	and return -ENOSPC.
	154
	155	Note: IRQs need to be allocated for each context, which may limit
	156	the number of contexts that can be created, and therefore
	157	how many times the device can be opened. The POWER8 CAPP
	158	supports 2040 IRQs and 3 are used by the kernel, so 2037 are
	159	left. If 1 IRQ is needed per context, then only 2037
	160	contexts can be allocated. If 4 IRQs are needed per context,
	161	then only 2037/4 = 509 contexts can be allocated.
	162
	163
	164	ioctl
	165	-----
	166
	167	CXL_IOCTL_START_WORK:
	168	Starts the AFU context and associates it with the current
	169	process. Once this ioctl is successfully executed, all memory
	170	mapped into this process is accessible to this AFU context
	171	using the same effective addresses. No additional calls are
	172	required to map/unmap memory. The AFU memory context will be
	173	updated as userspace allocates and frees memory. This ioctl
	174	returns once the AFU context is started.
	175
	176	Takes a pointer to a struct cxl_ioctl_start_work:
	177
	178	struct cxl_ioctl_start_work {
	179	__u64 flags;
	180	__u64 work_element_descriptor;
	181	__u64 amr;
	182	__s16 num_interrupts;
	183	__s16 reserved1;
	184	__s32 reserved2;
	185	__u64 reserved3;
	186	__u64 reserved4;
	187	__u64 reserved5;
	188	__u64 reserved6;
	189	};
	190
	191	flags:
	192	Indicates which optional fields in the structure are
	193	valid.
	194
	195	work_element_descriptor:
	196	The Work Element Descriptor (WED) is a 64-bit argument
	197	defined by the AFU. Typically this is an effective
	198	address pointing to an AFU specific structure
	199	describing what work to perform.
	200
	201	amr:
	202	Authority Mask Register (AMR), same as the powerpc
203	AMR. This field is only used by the kernel when the
204	corresponding CXL_START_WORK_AMR value is specified in
205	flags. If not specified the kernel will use a default
206	value of 0.
207
208	num_interrupts:
209	Number of userspace interrupts to request. This field
210	is only used by the kernel when the corresponding
211	CXL_START_WORK_NUM_IRQS value is specified in flags.
212	If not specified the minimum number required by the
213	AFU will be allocated. The min and max number can be
214	obtained from sysfs.
215
216	reserved fields:
217	For ABI padding and future extensions
218
219	CXL_IOCTL_GET_PROCESS_ELEMENT:
220	Get the current context id, also known as the process element.
221	The value is returned from the kernel as a __u32.
222
223
224	mmap
225	----
226
227	An AFU may have an MMIO space to facilitate communication with the
228	AFU. If it does, the MMIO space can be accessed via mmap. The size
229	and contents of this area are specific to the particular AFU. The
230	size can be discovered via sysfs.
231
232	In AFU directed mode, master contexts are allowed to map all of
233	the MMIO space and slave contexts are allowed to only map the per
234	process MMIO space associated with the context. In dedicated
235	process mode the entire MMIO space can always be mapped.
236
237	This mmap call must be done after the START_WORK ioctl.
238
239	Care should be taken when accessing MMIO space. Only 32 and 64-bit
240	accesses are supported by POWER8. Also, the AFU will be designed
241	with a specific endianness, so all MMIO accesses should consider
242	endianness (recommend endian(3) variants like: le64toh(),
243	be64toh() etc). These endian issues equally apply to shared memory
244	queues the WED may describe.
245
246
247	read
248	----
249
250	Reads events from the AFU. Blocks if no events are pending
251	(unless O_NONBLOCK is supplied). Returns -EIO in the case of an
252	unrecoverable error or if the card is removed.
253
254	read() will always return an integral number of events.
255
256	The buffer passed to read() must be at least 4K bytes.
257
258	The result of the read will be a buffer of one or more events,
259	each event is of type struct cxl_event, of varying size.
260
261	struct cxl_event {
262	struct cxl_event_header header;
263	union {
264	struct cxl_event_afu_interrupt irq;
265	struct cxl_event_data_storage fault;
266	struct cxl_event_afu_error afu_error;
267	};
268	};
269
270	The struct cxl_event_header is defined as:
271
272	struct cxl_event_header {
273	__u16 type;
274	__u16 size;
275	__u16 process_element;
276	__u16 reserved1;
277	};
278
279	type:
280	This defines the type of event. The type determines how
281	the rest of the event is structured. These types are
282	described below and defined by enum cxl_event_type.
283
284	size:
285	This is the size of the event in bytes including the
286	struct cxl_event_header. The start of the next event can
287	be found at this offset from the start of the current
288	event.
289
290	process_element:
291	Context ID of the event.
292
293	reserved field:
294	For future extensions and padding.
295
296	If the event type is CXL_EVENT_AFU_INTERRUPT then the event
297	structure is defined as:
298
299	struct cxl_event_afu_interrupt {
300	__u16 flags;
301	__u16 irq; /* Raised AFU interrupt number */
302	__u32 reserved1;
303	};
304
305	flags:
306	These flags indicate which optional fields are present
307	in this struct. Currently all fields are mandatory.
308
309	irq:
310	The IRQ number sent by the AFU.
311
312	reserved field:
313	For future extensions and padding.
314
315	If the event type is CXL_EVENT_DATA_STORAGE then the event
316	structure is defined as:
317
318	struct cxl_event_data_storage {
319	__u16 flags;
320	__u16 reserved1;
321	__u32 reserved2;
322	__u64 addr;
323	__u64 dsisr;
324	__u64 reserved3;
325	};
326
327	flags:
328	These flags indicate which optional fields are present in
329	this struct. Currently all fields are mandatory.
330
331	address:
332	The address that the AFU unsuccessfully attempted to
333	access. Valid accesses will be handled transparently by the
334	kernel but invalid accesses will generate this event.
335
336	dsisr:
337	This field gives information on the type of fault. It is a
338	copy of the DSISR from the PSL hardware when the address
339	fault occurred. The form of the DSISR is as defined in the
340	CAIA.
341
342	reserved fields:
343	For future extensions
344
345	If the event type is CXL_EVENT_AFU_ERROR then the event structure
346	is defined as:
347
348	struct cxl_event_afu_error {
349	__u16 flags;
350	__u16 reserved1;
351	__u32 reserved2;
352	__u64 error;
353	};
354
355	flags:
356	These flags indicate which optional fields are present in
357	this struct. Currently all fields are Mandatory.
358
359	error:
360	Error status from the AFU. Defined by the AFU.
361
362	reserved fields:
363	For future extensions and padding
364
365	Sysfs Class
366	===========
367
368	A cxl sysfs class is added under /sys/class/cxl to facilitate
369	enumeration and tuning of the accelerators. Its layout is
370	described in Documentation/ABI/testing/sysfs-class-cxl
371
aee85fb6	372
a9282d01 IM	373	Udev rules
	374	==========
	375
	376	The following udev rules could be used to create a symlink to the
	377	most logical chardev to use in any programming mode (afuX.Yd for
	378	dedicated, afuX.Ys for afu directed), since the API is virtually
	379	identical for each:
	380
	381	SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
	382	SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
	383	KERNEL=="afu[0-9].[0-9]s", SYMLINK="cxl/%b"