cxl.rst 16 KB

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