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