cxl.h 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265
  1. /* SPDX-License-Identifier: GPL-2.0-or-later */
  2. /*
  3. * Copyright 2015 IBM Corp.
  4. */
  5. #ifndef _MISC_CXL_H
  6. #define _MISC_CXL_H
  7. #include <linux/pci.h>
  8. #include <linux/poll.h>
  9. #include <linux/interrupt.h>
  10. #include <uapi/misc/cxl.h>
  11. /*
  12. * This documents the in kernel API for driver to use CXL. It allows kernel
  13. * drivers to bind to AFUs using an AFU configuration record exposed as a PCI
  14. * configuration record.
  15. *
  16. * This API enables control over AFU and contexts which can't be part of the
  17. * generic PCI API. This API is agnostic to the actual AFU.
  18. */
  19. /* Get the AFU associated with a pci_dev */
  20. struct cxl_afu *cxl_pci_to_afu(struct pci_dev *dev);
  21. /* Get the AFU conf record number associated with a pci_dev */
  22. unsigned int cxl_pci_to_cfg_record(struct pci_dev *dev);
  23. /*
  24. * Context lifetime overview:
  25. *
  26. * An AFU context may be inited and then started and stoppped multiple times
  27. * before it's released. ie.
  28. * - cxl_dev_context_init()
  29. * - cxl_start_context()
  30. * - cxl_stop_context()
  31. * - cxl_start_context()
  32. * - cxl_stop_context()
  33. * ...repeat...
  34. * - cxl_release_context()
  35. * Once released, a context can't be started again.
  36. *
  37. * One context is inited by the cxl driver for every pci_dev. This is to be
  38. * used as a default kernel context. cxl_get_context() will get this
  39. * context. This context will be released by PCI hot unplug, so doesn't need to
  40. * be released explicitly by drivers.
  41. *
  42. * Additional kernel contexts may be inited using cxl_dev_context_init().
  43. * These must be released using cxl_context_detach().
  44. *
  45. * Once a context has been inited, IRQs may be configured. Firstly these IRQs
  46. * must be allocated (cxl_allocate_afu_irqs()), then individually mapped to
  47. * specific handlers (cxl_map_afu_irq()).
  48. *
  49. * These IRQs can be unmapped (cxl_unmap_afu_irq()) and finally released
  50. * (cxl_free_afu_irqs()).
  51. *
  52. * The AFU can be reset (cxl_afu_reset()). This will cause the PSL/AFU
  53. * hardware to lose track of all contexts. It's upto the caller of
  54. * cxl_afu_reset() to restart these contexts.
  55. */
  56. /*
  57. * On pci_enabled_device(), the cxl driver will init a single cxl context for
  58. * use by the driver. It doesn't start this context (as that will likely
  59. * generate DMA traffic for most AFUs).
  60. *
  61. * This gets the default context associated with this pci_dev. This context
  62. * doesn't need to be released as this will be done by the PCI subsystem on hot
  63. * unplug.
  64. */
  65. struct cxl_context *cxl_get_context(struct pci_dev *dev);
  66. /*
  67. * Allocate and initalise a context associated with a AFU PCI device. This
  68. * doesn't start the context in the AFU.
  69. */
  70. struct cxl_context *cxl_dev_context_init(struct pci_dev *dev);
  71. /*
  72. * Release and free a context. Context should be stopped before calling.
  73. */
  74. int cxl_release_context(struct cxl_context *ctx);
  75. /*
  76. * Set and get private data associated with a context. Allows drivers to have a
  77. * back pointer to some useful structure.
  78. */
  79. int cxl_set_priv(struct cxl_context *ctx, void *priv);
  80. void *cxl_get_priv(struct cxl_context *ctx);
  81. /*
  82. * Allocate AFU interrupts for this context. num=0 will allocate the default
  83. * for this AFU as given in the AFU descriptor. This number doesn't include the
  84. * interrupt 0 (CAIA defines AFU IRQ 0 for page faults). Each interrupt to be
  85. * used must map a handler with cxl_map_afu_irq.
  86. */
  87. int cxl_allocate_afu_irqs(struct cxl_context *cxl, int num);
  88. /* Free allocated interrupts */
  89. void cxl_free_afu_irqs(struct cxl_context *cxl);
  90. /*
  91. * Map a handler for an AFU interrupt associated with a particular context. AFU
  92. * IRQS numbers start from 1 (CAIA defines AFU IRQ 0 for page faults). cookie
  93. * is private data is that will be provided to the interrupt handler.
  94. */
  95. int cxl_map_afu_irq(struct cxl_context *cxl, int num,
  96. irq_handler_t handler, void *cookie, char *name);
  97. /* unmap mapped IRQ handlers */
  98. void cxl_unmap_afu_irq(struct cxl_context *cxl, int num, void *cookie);
  99. /*
  100. * Start work on the AFU. This starts an cxl context and associates it with a
  101. * task. task == NULL will make it a kernel context.
  102. */
  103. int cxl_start_context(struct cxl_context *ctx, u64 wed,
  104. struct task_struct *task);
  105. /*
  106. * Stop a context and remove it from the PSL
  107. */
  108. int cxl_stop_context(struct cxl_context *ctx);
  109. /* Reset the AFU */
  110. int cxl_afu_reset(struct cxl_context *ctx);
  111. /*
  112. * Set a context as a master context.
  113. * This sets the default problem space area mapped as the full space, rather
  114. * than just the per context area (for slaves).
  115. */
  116. void cxl_set_master(struct cxl_context *ctx);
  117. /*
  118. * Map and unmap the AFU Problem Space area. The amount and location mapped
  119. * depends on if this context is a master or slave.
  120. */
  121. void __iomem *cxl_psa_map(struct cxl_context *ctx);
  122. void cxl_psa_unmap(void __iomem *addr);
  123. /* Get the process element for this context */
  124. int cxl_process_element(struct cxl_context *ctx);
  125. /*
  126. * These calls allow drivers to create their own file descriptors and make them
  127. * identical to the cxl file descriptor user API. An example use case:
  128. *
  129. * struct file_operations cxl_my_fops = {};
  130. * ......
  131. * // Init the context
  132. * ctx = cxl_dev_context_init(dev);
  133. * if (IS_ERR(ctx))
  134. * return PTR_ERR(ctx);
  135. * // Create and attach a new file descriptor to my file ops
  136. * file = cxl_get_fd(ctx, &cxl_my_fops, &fd);
  137. * // Start context
  138. * rc = cxl_start_work(ctx, &work.work);
  139. * if (rc) {
  140. * fput(file);
  141. * put_unused_fd(fd);
  142. * return -ENODEV;
  143. * }
  144. * // No error paths after installing the fd
  145. * fd_install(fd, file);
  146. * return fd;
  147. *
  148. * This inits a context, and gets a file descriptor and associates some file
  149. * ops to that file descriptor. If the file ops are blank, the cxl driver will
  150. * fill them in with the default ones that mimic the standard user API. Once
  151. * completed, the file descriptor can be installed. Once the file descriptor is
  152. * installed, it's visible to the user so no errors must occur past this point.
  153. *
  154. * If cxl_fd_release() file op call is installed, the context will be stopped
  155. * and released when the fd is released. Hence the driver won't need to manage
  156. * this itself.
  157. */
  158. /*
  159. * Take a context and associate it with my file ops. Returns the associated
  160. * file and file descriptor. Any file ops which are blank are filled in by the
  161. * cxl driver with the default ops to mimic the standard API.
  162. */
  163. struct file *cxl_get_fd(struct cxl_context *ctx, struct file_operations *fops,
  164. int *fd);
  165. /* Get the context associated with this file */
  166. struct cxl_context *cxl_fops_get_context(struct file *file);
  167. /*
  168. * Start a context associated a struct cxl_ioctl_start_work used by the
  169. * standard cxl user API.
  170. */
  171. int cxl_start_work(struct cxl_context *ctx,
  172. struct cxl_ioctl_start_work *work);
  173. /*
  174. * Export all the existing fops so drivers can use them
  175. */
  176. int cxl_fd_open(struct inode *inode, struct file *file);
  177. int cxl_fd_release(struct inode *inode, struct file *file);
  178. long cxl_fd_ioctl(struct file *file, unsigned int cmd, unsigned long arg);
  179. int cxl_fd_mmap(struct file *file, struct vm_area_struct *vm);
  180. __poll_t cxl_fd_poll(struct file *file, struct poll_table_struct *poll);
  181. ssize_t cxl_fd_read(struct file *file, char __user *buf, size_t count,
  182. loff_t *off);
  183. /*
  184. * For EEH, a driver may want to assert a PERST will reload the same image
  185. * from flash into the FPGA.
  186. *
  187. * This is a property of the entire adapter, not a single AFU, so drivers
  188. * should set this property with care!
  189. */
  190. void cxl_perst_reloads_same_image(struct cxl_afu *afu,
  191. bool perst_reloads_same_image);
  192. /*
  193. * Read the VPD for the card where the AFU resides
  194. */
  195. ssize_t cxl_read_adapter_vpd(struct pci_dev *dev, void *buf, size_t count);
  196. /*
  197. * AFU driver ops allow an AFU driver to create their own events to pass to
  198. * userspace through the file descriptor as a simpler alternative to overriding
  199. * the read() and poll() calls that works with the generic cxl events. These
  200. * events are given priority over the generic cxl events, so they will be
  201. * delivered first if multiple types of events are pending.
  202. *
  203. * The AFU driver must call cxl_context_events_pending() to notify the cxl
  204. * driver that new events are ready to be delivered for a specific context.
  205. * cxl_context_events_pending() will adjust the current count of AFU driver
  206. * events for this context, and wake up anyone waiting on the context wait
  207. * queue.
  208. *
  209. * The cxl driver will then call fetch_event() to get a structure defining
  210. * the size and address of the driver specific event data. The cxl driver
  211. * will build a cxl header with type and process_element fields filled in,
  212. * and header.size set to sizeof(struct cxl_event_header) + data_size.
  213. * The total size of the event is limited to CXL_READ_MIN_SIZE (4K).
  214. *
  215. * fetch_event() is called with a spin lock held, so it must not sleep.
  216. *
  217. * The cxl driver will then deliver the event to userspace, and finally
  218. * call event_delivered() to return the status of the operation, identified
  219. * by cxl context and AFU driver event data pointers.
  220. * 0 Success
  221. * -EFAULT copy_to_user() has failed
  222. * -EINVAL Event data pointer is NULL, or event size is greater than
  223. * CXL_READ_MIN_SIZE.
  224. */
  225. struct cxl_afu_driver_ops {
  226. struct cxl_event_afu_driver_reserved *(*fetch_event) (
  227. struct cxl_context *ctx);
  228. void (*event_delivered) (struct cxl_context *ctx,
  229. struct cxl_event_afu_driver_reserved *event,
  230. int rc);
  231. };
  232. /*
  233. * Associate the above driver ops with a specific context.
  234. * Reset the current count of AFU driver events.
  235. */
  236. void cxl_set_driver_ops(struct cxl_context *ctx,
  237. struct cxl_afu_driver_ops *ops);
  238. /* Notify cxl driver that new events are ready to be delivered for context */
  239. void cxl_context_events_pending(struct cxl_context *ctx,
  240. unsigned int new_events);
  241. #endif /* _MISC_CXL_H */