1 // SPDX-License-Identifier: GPL-2.0+
2 // Copyright 2017 IBM Corp.
9 * Opencapi drivers all need some common facilities, like parsing the
10 * device configuration space, adding a Process Element to the Shared
11 * Process Area, etc...
13 * The ocxl module provides a kernel API, to allow other drivers to
14 * reuse common code. A bit like a in-kernel library.
17 #define OCXL_AFU_NAME_SZ (24+1) /* add 1 for NULL termination */
20 struct ocxl_afu_config {
22 int dvsec_afu_control_pos; /* offset of AFU control DVSEC */
23 char name[OCXL_AFU_NAME_SZ];
29 u8 global_mmio_bar; /* global MMIO area */
30 u64 global_mmio_offset;
32 u8 pp_mmio_bar; /* per-process MMIO area */
36 u8 pasid_supported_log;
40 struct ocxl_fn_config {
41 int dvsec_tl_pos; /* offset of the Transaction Layer DVSEC */
42 int dvsec_function_pos; /* offset of the Function DVSEC */
43 int dvsec_afu_info_pos; /* offset of the AFU information DVSEC */
49 OCXL_BIG_ENDIAN = 0, /**< AFU data is big-endian */
50 OCXL_LITTLE_ENDIAN = 1, /**< AFU data is little-endian */
51 OCXL_HOST_ENDIAN = 2, /**< AFU data is the same endianness as the host */
54 // These are opaque outside the ocxl driver
59 // Device detection & initialisation
62 * Open an OpenCAPI function on an OpenCAPI device
64 * @dev: The PCI device that contains the function
66 * Returns an opaque pointer to the function, or an error pointer (check with IS_ERR)
68 struct ocxl_fn *ocxl_function_open(struct pci_dev *dev);
71 * Get the list of AFUs associated with a PCI function device
73 * Returns a list of struct ocxl_afu *
75 * @fn: The OpenCAPI function containing the AFUs
77 struct list_head *ocxl_function_afu_list(struct ocxl_fn *fn);
80 * Fetch an AFU instance from an OpenCAPI function
82 * @fn: The OpenCAPI function to get the AFU from
83 * @afu_idx: The index of the AFU to get
85 * If successful, the AFU should be released with ocxl_afu_put()
87 * Returns a pointer to the AFU, or NULL on error
89 struct ocxl_afu *ocxl_function_fetch_afu(struct ocxl_fn *fn, u8 afu_idx);
92 * Take a reference to an AFU
94 * @afu: The AFU to increment the reference count on
96 void ocxl_afu_get(struct ocxl_afu *afu);
99 * Release a reference to an AFU
101 * @afu: The AFU to decrement the reference count on
103 void ocxl_afu_put(struct ocxl_afu *afu);
107 * Get the configuration information for an OpenCAPI function
109 * @fn: The OpenCAPI function to get the config for
111 * Returns the function config, or NULL on error
113 const struct ocxl_fn_config *ocxl_function_config(struct ocxl_fn *fn);
116 * Close an OpenCAPI function
118 * This will free any AFUs previously retrieved from the function, and
119 * detach and associated contexts. The contexts must by freed by the caller.
121 * @fn: The OpenCAPI function to close
124 void ocxl_function_close(struct ocxl_fn *fn);
126 // Context allocation
129 * Allocate an OpenCAPI context
131 * @context: The OpenCAPI context to allocate, must be freed with ocxl_context_free
132 * @afu: The AFU the context belongs to
133 * @mapping: The mapping to unmap when the context is closed (may be NULL)
135 int ocxl_context_alloc(struct ocxl_context **context, struct ocxl_afu *afu,
136 struct address_space *mapping);
139 * Free an OpenCAPI context
141 * @ctx: The OpenCAPI context to free
143 void ocxl_context_free(struct ocxl_context *ctx);
146 * Grant access to an MM to an OpenCAPI context
147 * @ctx: The OpenCAPI context to attach
148 * @amr: The value of the AMR register to restrict access
149 * @mm: The mm to attach to the context
151 * Returns 0 on success, negative on failure
153 int ocxl_context_attach(struct ocxl_context *ctx, u64 amr,
154 struct mm_struct *mm);
157 * Detach an MM from an OpenCAPI context
158 * @ctx: The OpenCAPI context to attach
160 * Returns 0 on success, negative on failure
162 int ocxl_context_detach(struct ocxl_context *ctx);
167 * Allocate an IRQ associated with an AFU context
168 * @ctx: the AFU context
169 * @irq_id: out, the IRQ ID
171 * Returns 0 on success, negative on failure
173 extern int ocxl_afu_irq_alloc(struct ocxl_context *ctx, int *irq_id);
176 * Frees an IRQ associated with an AFU context
177 * @ctx: the AFU context
178 * @irq_id: the IRQ ID
180 * Returns 0 on success, negative on failure
182 extern int ocxl_afu_irq_free(struct ocxl_context *ctx, int irq_id);
185 * Gets the address of the trigger page for an IRQ
186 * This can then be provided to an AFU which will write to that
187 * page to trigger the IRQ.
188 * @ctx: The AFU context that the IRQ is associated with
189 * @irq_id: The IRQ ID
191 * returns the trigger page address, or 0 if the IRQ is not valid
193 extern u64 ocxl_afu_irq_get_addr(struct ocxl_context *ctx, int irq_id);
196 * Provide a callback to be called when an IRQ is triggered
197 * @ctx: The AFU context that the IRQ is associated with
198 * @irq_id: The IRQ ID
199 * @handler: the callback to be called when the IRQ is triggered
200 * @free_private: the callback to be called when the IRQ is freed (may be NULL)
201 * @private: Private data to be passed to the callbacks
203 * Returns 0 on success, negative on failure
205 int ocxl_irq_set_handler(struct ocxl_context *ctx, int irq_id,
206 irqreturn_t (*handler)(void *private),
207 void (*free_private)(void *private),
213 * Get a pointer to the config for an AFU
215 * @afu: a pointer to the AFU to get the config for
217 * Returns a pointer to the AFU config
219 struct ocxl_afu_config *ocxl_afu_config(struct ocxl_afu *afu);
222 * Assign opaque hardware specific information to an OpenCAPI AFU.
224 * @dev: The PCI device associated with the OpenCAPI device
225 * @private: the opaque hardware specific information to assign to the driver
227 void ocxl_afu_set_private(struct ocxl_afu *afu, void *private);
230 * Fetch the hardware specific information associated with an external OpenCAPI
231 * AFU. This may be consumed by an external OpenCAPI driver.
235 * Returns the opaque pointer associated with the device, or NULL if not set
237 void *ocxl_afu_get_private(struct ocxl_afu *dev);
241 * Read a 32 bit value from global MMIO
244 * @offset: The Offset from the start of MMIO
245 * @endian: the endianness that the MMIO data is in
246 * @val: returns the value
248 * Returns 0 for success, negative on error
250 int ocxl_global_mmio_read32(struct ocxl_afu *afu, size_t offset,
251 enum ocxl_endian endian, u32 *val);
254 * Read a 64 bit value from global MMIO
257 * @offset: The Offset from the start of MMIO
258 * @endian: the endianness that the MMIO data is in
259 * @val: returns the value
261 * Returns 0 for success, negative on error
263 int ocxl_global_mmio_read64(struct ocxl_afu *afu, size_t offset,
264 enum ocxl_endian endian, u64 *val);
267 * Write a 32 bit value to global MMIO
270 * @offset: The Offset from the start of MMIO
271 * @endian: the endianness that the MMIO data is in
272 * @val: The value to write
274 * Returns 0 for success, negative on error
276 int ocxl_global_mmio_write32(struct ocxl_afu *afu, size_t offset,
277 enum ocxl_endian endian, u32 val);
280 * Write a 64 bit value to global MMIO
283 * @offset: The Offset from the start of MMIO
284 * @endian: the endianness that the MMIO data is in
285 * @val: The value to write
287 * Returns 0 for success, negative on error
289 int ocxl_global_mmio_write64(struct ocxl_afu *afu, size_t offset,
290 enum ocxl_endian endian, u64 val);
293 * Set bits in a 32 bit global MMIO register
296 * @offset: The Offset from the start of MMIO
297 * @endian: the endianness that the MMIO data is in
298 * @mask: a mask of the bits to set
300 * Returns 0 for success, negative on error
302 int ocxl_global_mmio_set32(struct ocxl_afu *afu, size_t offset,
303 enum ocxl_endian endian, u32 mask);
306 * Set bits in a 64 bit global MMIO register
309 * @offset: The Offset from the start of MMIO
310 * @endian: the endianness that the MMIO data is in
311 * @mask: a mask of the bits to set
313 * Returns 0 for success, negative on error
315 int ocxl_global_mmio_set64(struct ocxl_afu *afu, size_t offset,
316 enum ocxl_endian endian, u64 mask);
319 * Set bits in a 32 bit global MMIO register
322 * @offset: The Offset from the start of MMIO
323 * @endian: the endianness that the MMIO data is in
324 * @mask: a mask of the bits to set
326 * Returns 0 for success, negative on error
328 int ocxl_global_mmio_clear32(struct ocxl_afu *afu, size_t offset,
329 enum ocxl_endian endian, u32 mask);
332 * Set bits in a 64 bit global MMIO register
335 * @offset: The Offset from the start of MMIO
336 * @endian: the endianness that the MMIO data is in
337 * @mask: a mask of the bits to set
339 * Returns 0 for success, negative on error
341 int ocxl_global_mmio_clear64(struct ocxl_afu *afu, size_t offset,
342 enum ocxl_endian endian, u64 mask);
344 // Functions left here are for compatibility with the cxlflash driver
347 * Read the configuration space of a function for the AFU specified by
348 * the index 'afu_idx'. Fills in a ocxl_afu_config structure
350 int ocxl_config_read_afu(struct pci_dev *dev,
351 struct ocxl_fn_config *fn,
352 struct ocxl_afu_config *afu,
356 * Tell an AFU, by writing in the configuration space, the PASIDs that
357 * it can use. Range starts at 'pasid_base' and its size is a multiple
360 * 'afu_control_offset' is the offset of the AFU control DVSEC which
361 * can be found in the function configuration
363 void ocxl_config_set_afu_pasid(struct pci_dev *dev,
364 int afu_control_offset,
365 int pasid_base, u32 pasid_count_log);
368 * Get the actag configuration for the function:
369 * 'base' is the first actag value that can be used.
370 * 'enabled' it the number of actags available, starting from base.
371 * 'supported' is the total number of actags desired by all the AFUs
374 int ocxl_config_get_actag_info(struct pci_dev *dev,
375 u16 *base, u16 *enabled, u16 *supported);
378 * Tell a function, by writing in the configuration space, the actags
381 * 'func_offset' is the offset of the Function DVSEC that can found in
382 * the function configuration
384 void ocxl_config_set_actag(struct pci_dev *dev, int func_offset,
385 u32 actag_base, u32 actag_count);
388 * Tell an AFU, by writing in the configuration space, the actags it
391 * 'afu_control_offset' is the offset of the AFU control DVSEC for the
392 * desired AFU. It can be found in the AFU configuration
394 void ocxl_config_set_afu_actag(struct pci_dev *dev,
395 int afu_control_offset,
396 int actag_base, int actag_count);
399 * Enable/disable an AFU, by writing in the configuration space.
401 * 'afu_control_offset' is the offset of the AFU control DVSEC for the
402 * desired AFU. It can be found in the AFU configuration
404 void ocxl_config_set_afu_state(struct pci_dev *dev,
405 int afu_control_offset, int enable);
408 * Set the Transaction Layer configuration in the configuration space.
409 * Only needed for function 0.
411 * It queries the host TL capabilities, find some common ground
412 * between the host and device, and set the Transaction Layer on both
415 int ocxl_config_set_TL(struct pci_dev *dev, int tl_dvsec);
418 * Request an AFU to terminate a PASID.
419 * Will return once the AFU has acked the request, or an error in case
422 * The hardware can only terminate one PASID at a time, so caller must
423 * guarantee some kind of serialization.
425 * 'afu_control_offset' is the offset of the AFU control DVSEC for the
426 * desired AFU. It can be found in the AFU configuration
428 int ocxl_config_terminate_pasid(struct pci_dev *dev,
429 int afu_control_offset, int pasid);
432 * Read the configuration space of a function and fill in a
433 * ocxl_fn_config structure with all the function details
435 int ocxl_config_read_function(struct pci_dev *dev,
436 struct ocxl_fn_config *fn);
439 * Set up the opencapi link for the function.
441 * When called for the first time for a link, it sets up the Shared
442 * Process Area for the link and the interrupt handler to process
443 * translation faults.
445 * Returns a 'link handle' that should be used for further calls for
448 int ocxl_link_setup(struct pci_dev *dev, int PE_mask,
452 * Remove the association between the function and its link.
454 void ocxl_link_release(struct pci_dev *dev, void *link_handle);
457 * Add a Process Element to the Shared Process Area for a link.
458 * The process is defined by its PASID, pid, tid and its mm_struct.
460 * 'xsl_err_cb' is an optional callback if the driver wants to be
461 * notified when the translation fault interrupt handler detects an
463 * 'xsl_err_data' is an argument passed to the above callback, if
466 int ocxl_link_add_pe(void *link_handle, int pasid, u32 pidr, u32 tidr,
467 u64 amr, struct mm_struct *mm,
468 void (*xsl_err_cb)(void *data, u64 addr, u64 dsisr),
472 * Remove a Process Element from the Shared Process Area for a link
474 int ocxl_link_remove_pe(void *link_handle, int pasid);
477 * Allocate an AFU interrupt associated to the link.
479 * 'hw_irq' is the hardware interrupt number
480 * 'obj_handle' is the 64-bit object handle to be passed to the AFU to
481 * trigger the interrupt.
482 * On P9, 'obj_handle' is an address, which, if written, triggers the
483 * interrupt. It is an MMIO address which needs to be remapped (one
486 int ocxl_link_irq_alloc(void *link_handle, int *hw_irq,
490 * Free a previously allocated AFU interrupt
492 void ocxl_link_free_irq(void *link_handle, int hw_irq);
494 #endif /* _MISC_OCXL_H_ */