1 // SPDX-License-Identifier: GPL-2.0+
2 // Copyright 2017 IBM Corp.
3 #ifndef _MISC_OCXL_H_
4 #define _MISC_OCXL_H_
5
6 #include <linux/pci.h>
7
8 /*
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...
12 *
13 * The ocxl module provides a kernel API, to allow other drivers to
14 * reuse common code. A bit like a in-kernel library.
15 */
16
17 #define OCXL_AFU_NAME_SZ (24+1) /* add 1 for NULL termination */
18
19
20 struct ocxl_afu_config {
21 u8 idx;
22 int dvsec_afu_control_pos; /* offset of AFU control DVSEC */
23 char name[OCXL_AFU_NAME_SZ];
24 u8 version_major;
25 u8 version_minor;
26 u8 afuc_type;
27 u8 afum_type;
28 u8 profile;
29 u8 global_mmio_bar; /* global MMIO area */
30 u64 global_mmio_offset;
31 u32 global_mmio_size;
32 u8 pp_mmio_bar; /* per-process MMIO area */
33 u64 pp_mmio_offset;
34 u32 pp_mmio_stride;
35 u64 lpc_mem_offset;
36 u64 lpc_mem_size;
37 u64 special_purpose_mem_offset;
38 u64 special_purpose_mem_size;
39 u8 pasid_supported_log;
40 u16 actag_supported;
41 };
42
43 struct ocxl_fn_config {
44 int dvsec_tl_pos; /* offset of the Transaction Layer DVSEC */
45 int dvsec_function_pos; /* offset of the Function DVSEC */
46 int dvsec_afu_info_pos; /* offset of the AFU information DVSEC */
47 s8 max_pasid_log;
48 s8 max_afu_index;
49 };
50
51 enum ocxl_endian {
52 OCXL_BIG_ENDIAN = 0, /**< AFU data is big-endian */
53 OCXL_LITTLE_ENDIAN = 1, /**< AFU data is little-endian */
54 OCXL_HOST_ENDIAN = 2, /**< AFU data is the same endianness as the host */
55 };
56
57 // These are opaque outside the ocxl driver
58 struct ocxl_afu;
59 struct ocxl_fn;
60 struct ocxl_context;
61
62 // Device detection & initialisation
63
64 /**
65 * Open an OpenCAPI function on an OpenCAPI device
66 *
67 * @dev: The PCI device that contains the function
68 *
69 * Returns an opaque pointer to the function, or an error pointer (check with IS_ERR)
70 */
71 struct ocxl_fn *ocxl_function_open(struct pci_dev *dev);
72
73 /**
74 * Get the list of AFUs associated with a PCI function device
75 *
76 * Returns a list of struct ocxl_afu *
77 *
78 * @fn: The OpenCAPI function containing the AFUs
79 */
80 struct list_head *ocxl_function_afu_list(struct ocxl_fn *fn);
81
82 /**
83 * Fetch an AFU instance from an OpenCAPI function
84 *
85 * @fn: The OpenCAPI function to get the AFU from
86 * @afu_idx: The index of the AFU to get
87 *
88 * If successful, the AFU should be released with ocxl_afu_put()
89 *
90 * Returns a pointer to the AFU, or NULL on error
91 */
92 struct ocxl_afu *ocxl_function_fetch_afu(struct ocxl_fn *fn, u8 afu_idx);
93
94 /**
95 * Take a reference to an AFU
96 *
97 * @afu: The AFU to increment the reference count on
98 */
99 void ocxl_afu_get(struct ocxl_afu *afu);
100
101 /**
102 * Release a reference to an AFU
103 *
104 * @afu: The AFU to decrement the reference count on
105 */
106 void ocxl_afu_put(struct ocxl_afu *afu);
107
108
109 /**
110 * Get the configuration information for an OpenCAPI function
111 *
112 * @fn: The OpenCAPI function to get the config for
113 *
114 * Returns the function config, or NULL on error
115 */
116 const struct ocxl_fn_config *ocxl_function_config(struct ocxl_fn *fn);
117
118 /**
119 * Close an OpenCAPI function
120 *
121 * This will free any AFUs previously retrieved from the function, and
122 * detach and associated contexts. The contexts must by freed by the caller.
123 *
124 * @fn: The OpenCAPI function to close
125 *
126 */
127 void ocxl_function_close(struct ocxl_fn *fn);
128
129 // Context allocation
130
131 /**
132 * Allocate an OpenCAPI context
133 *
134 * @context: The OpenCAPI context to allocate, must be freed with ocxl_context_free
135 * @afu: The AFU the context belongs to
136 * @mapping: The mapping to unmap when the context is closed (may be NULL)
137 */
138 int ocxl_context_alloc(struct ocxl_context **context, struct ocxl_afu *afu,
139 struct address_space *mapping);
140
141 /**
142 * Free an OpenCAPI context
143 *
144 * @ctx: The OpenCAPI context to free
145 */
146 void ocxl_context_free(struct ocxl_context *ctx);
147
148 /**
149 * Grant access to an MM to an OpenCAPI context
150 * @ctx: The OpenCAPI context to attach
151 * @amr: The value of the AMR register to restrict access
152 * @mm: The mm to attach to the context
153 *
154 * Returns 0 on success, negative on failure
155 */
156 int ocxl_context_attach(struct ocxl_context *ctx, u64 amr,
157 struct mm_struct *mm);
158
159 /**
160 * Detach an MM from an OpenCAPI context
161 * @ctx: The OpenCAPI context to attach
162 *
163 * Returns 0 on success, negative on failure
164 */
165 int ocxl_context_detach(struct ocxl_context *ctx);
166
167 // AFU IRQs
168
169 /**
170 * Allocate an IRQ associated with an AFU context
171 * @ctx: the AFU context
172 * @irq_id: out, the IRQ ID
173 *
174 * Returns 0 on success, negative on failure
175 */
176 extern int ocxl_afu_irq_alloc(struct ocxl_context *ctx, int *irq_id);
177
178 /**
179 * Frees an IRQ associated with an AFU context
180 * @ctx: the AFU context
181 * @irq_id: the IRQ ID
182 *
183 * Returns 0 on success, negative on failure
184 */
185 extern int ocxl_afu_irq_free(struct ocxl_context *ctx, int irq_id);
186
187 /**
188 * Gets the address of the trigger page for an IRQ
189 * This can then be provided to an AFU which will write to that
190 * page to trigger the IRQ.
191 * @ctx: The AFU context that the IRQ is associated with
192 * @irq_id: The IRQ ID
193 *
194 * returns the trigger page address, or 0 if the IRQ is not valid
195 */
196 extern u64 ocxl_afu_irq_get_addr(struct ocxl_context *ctx, int irq_id);
197
198 /**
199 * Provide a callback to be called when an IRQ is triggered
200 * @ctx: The AFU context that the IRQ is associated with
201 * @irq_id: The IRQ ID
202 * @handler: the callback to be called when the IRQ is triggered
203 * @free_private: the callback to be called when the IRQ is freed (may be NULL)
204 * @private: Private data to be passed to the callbacks
205 *
206 * Returns 0 on success, negative on failure
207 */
208 int ocxl_irq_set_handler(struct ocxl_context *ctx, int irq_id,
209 irqreturn_t (*handler)(void *private),
210 void (*free_private)(void *private),
211 void *private);
212
213 // AFU Metadata
214
215 /**
216 * Get a pointer to the config for an AFU
217 *
218 * @afu: a pointer to the AFU to get the config for
219 *
220 * Returns a pointer to the AFU config
221 */
222 struct ocxl_afu_config *ocxl_afu_config(struct ocxl_afu *afu);
223
224 /**
225 * Assign opaque hardware specific information to an OpenCAPI AFU.
226 *
227 * @dev: The PCI device associated with the OpenCAPI device
228 * @private: the opaque hardware specific information to assign to the driver
229 */
230 void ocxl_afu_set_private(struct ocxl_afu *afu, void *private);
231
232 /**
233 * Fetch the hardware specific information associated with an external OpenCAPI
234 * AFU. This may be consumed by an external OpenCAPI driver.
235 *
236 * @afu: The AFU
237 *
238 * Returns the opaque pointer associated with the device, or NULL if not set
239 */
240 void *ocxl_afu_get_private(struct ocxl_afu *dev);
241
242 // Global MMIO
243 /**
244 * Read a 32 bit value from global MMIO
245 *
246 * @afu: The AFU
247 * @offset: The Offset from the start of MMIO
248 * @endian: the endianness that the MMIO data is in
249 * @val: returns the value
250 *
251 * Returns 0 for success, negative on error
252 */
253 int ocxl_global_mmio_read32(struct ocxl_afu *afu, size_t offset,
254 enum ocxl_endian endian, u32 *val);
255
256 /**
257 * Read a 64 bit value from global MMIO
258 *
259 * @afu: The AFU
260 * @offset: The Offset from the start of MMIO
261 * @endian: the endianness that the MMIO data is in
262 * @val: returns the value
263 *
264 * Returns 0 for success, negative on error
265 */
266 int ocxl_global_mmio_read64(struct ocxl_afu *afu, size_t offset,
267 enum ocxl_endian endian, u64 *val);
268
269 /**
270 * Write a 32 bit value to global MMIO
271 *
272 * @afu: The AFU
273 * @offset: The Offset from the start of MMIO
274 * @endian: the endianness that the MMIO data is in
275 * @val: The value to write
276 *
277 * Returns 0 for success, negative on error
278 */
279 int ocxl_global_mmio_write32(struct ocxl_afu *afu, size_t offset,
280 enum ocxl_endian endian, u32 val);
281
282 /**
283 * Write a 64 bit value to global MMIO
284 *
285 * @afu: The AFU
286 * @offset: The Offset from the start of MMIO
287 * @endian: the endianness that the MMIO data is in
288 * @val: The value to write
289 *
290 * Returns 0 for success, negative on error
291 */
292 int ocxl_global_mmio_write64(struct ocxl_afu *afu, size_t offset,
293 enum ocxl_endian endian, u64 val);
294
295 /**
296 * Set bits in a 32 bit global MMIO register
297 *
298 * @afu: The AFU
299 * @offset: The Offset from the start of MMIO
300 * @endian: the endianness that the MMIO data is in
301 * @mask: a mask of the bits to set
302 *
303 * Returns 0 for success, negative on error
304 */
305 int ocxl_global_mmio_set32(struct ocxl_afu *afu, size_t offset,
306 enum ocxl_endian endian, u32 mask);
307
308 /**
309 * Set bits in a 64 bit global MMIO register
310 *
311 * @afu: The AFU
312 * @offset: The Offset from the start of MMIO
313 * @endian: the endianness that the MMIO data is in
314 * @mask: a mask of the bits to set
315 *
316 * Returns 0 for success, negative on error
317 */
318 int ocxl_global_mmio_set64(struct ocxl_afu *afu, size_t offset,
319 enum ocxl_endian endian, u64 mask);
320
321 /**
322 * Set bits in a 32 bit global MMIO register
323 *
324 * @afu: The AFU
325 * @offset: The Offset from the start of MMIO
326 * @endian: the endianness that the MMIO data is in
327 * @mask: a mask of the bits to set
328 *
329 * Returns 0 for success, negative on error
330 */
331 int ocxl_global_mmio_clear32(struct ocxl_afu *afu, size_t offset,
332 enum ocxl_endian endian, u32 mask);
333
334 /**
335 * Set bits in a 64 bit global MMIO register
336 *
337 * @afu: The AFU
338 * @offset: The Offset from the start of MMIO
339 * @endian: the endianness that the MMIO data is in
340 * @mask: a mask of the bits to set
341 *
342 * Returns 0 for success, negative on error
343 */
344 int ocxl_global_mmio_clear64(struct ocxl_afu *afu, size_t offset,
345 enum ocxl_endian endian, u64 mask);
346
347 // Functions left here are for compatibility with the cxlflash driver
348
349 /*
350 * Read the configuration space of a function for the AFU specified by
351 * the index 'afu_idx'. Fills in a ocxl_afu_config structure
352 */
353 int ocxl_config_read_afu(struct pci_dev *dev,
354 struct ocxl_fn_config *fn,
355 struct ocxl_afu_config *afu,
356 u8 afu_idx);
357
358 /*
359 * Tell an AFU, by writing in the configuration space, the PASIDs that
360 * it can use. Range starts at 'pasid_base' and its size is a multiple
361 * of 2
362 *
363 * 'afu_control_offset' is the offset of the AFU control DVSEC which
364 * can be found in the function configuration
365 */
366 void ocxl_config_set_afu_pasid(struct pci_dev *dev,
367 int afu_control_offset,
368 int pasid_base, u32 pasid_count_log);
369
370 /*
371 * Get the actag configuration for the function:
372 * 'base' is the first actag value that can be used.
373 * 'enabled' it the number of actags available, starting from base.
374 * 'supported' is the total number of actags desired by all the AFUs
375 * of the function.
376 */
377 int ocxl_config_get_actag_info(struct pci_dev *dev,
378 u16 *base, u16 *enabled, u16 *supported);
379
380 /*
381 * Tell a function, by writing in the configuration space, the actags
382 * it can use.
383 *
384 * 'func_offset' is the offset of the Function DVSEC that can found in
385 * the function configuration
386 */
387 void ocxl_config_set_actag(struct pci_dev *dev, int func_offset,
388 u32 actag_base, u32 actag_count);
389
390 /*
391 * Tell an AFU, by writing in the configuration space, the actags it
392 * can use.
393 *
394 * 'afu_control_offset' is the offset of the AFU control DVSEC for the
395 * desired AFU. It can be found in the AFU configuration
396 */
397 void ocxl_config_set_afu_actag(struct pci_dev *dev,
398 int afu_control_offset,
399 int actag_base, int actag_count);
400
401 /*
402 * Enable/disable an AFU, by writing in the configuration space.
403 *
404 * 'afu_control_offset' is the offset of the AFU control DVSEC for the
405 * desired AFU. It can be found in the AFU configuration
406 */
407 void ocxl_config_set_afu_state(struct pci_dev *dev,
408 int afu_control_offset, int enable);
409
410 /*
411 * Set the Transaction Layer configuration in the configuration space.
412 * Only needed for function 0.
413 *
414 * It queries the host TL capabilities, find some common ground
415 * between the host and device, and set the Transaction Layer on both
416 * accordingly.
417 */
418 int ocxl_config_set_TL(struct pci_dev *dev, int tl_dvsec);
419
420 /*
421 * Request an AFU to terminate a PASID.
422 * Will return once the AFU has acked the request, or an error in case
423 * of timeout.
424 *
425 * The hardware can only terminate one PASID at a time, so caller must
426 * guarantee some kind of serialization.
427 *
428 * 'afu_control_offset' is the offset of the AFU control DVSEC for the
429 * desired AFU. It can be found in the AFU configuration
430 */
431 int ocxl_config_terminate_pasid(struct pci_dev *dev,
432 int afu_control_offset, int pasid);
433
434 /*
435 * Read the configuration space of a function and fill in a
436 * ocxl_fn_config structure with all the function details
437 */
438 int ocxl_config_read_function(struct pci_dev *dev,
439 struct ocxl_fn_config *fn);
440
441 /*
442 * Set up the opencapi link for the function.
443 *
444 * When called for the first time for a link, it sets up the Shared
445 * Process Area for the link and the interrupt handler to process
446 * translation faults.
447 *
448 * Returns a 'link handle' that should be used for further calls for
449 * the link
450 */
451 int ocxl_link_setup(struct pci_dev *dev, int PE_mask,
452 void **link_handle);
453
454 /*
455 * Remove the association between the function and its link.
456 */
457 void ocxl_link_release(struct pci_dev *dev, void *link_handle);
458
459 /*
460 * Add a Process Element to the Shared Process Area for a link.
461 * The process is defined by its PASID, pid, tid and its mm_struct.
462 *
463 * 'xsl_err_cb' is an optional callback if the driver wants to be
464 * notified when the translation fault interrupt handler detects an
465 * address error.
466 * 'xsl_err_data' is an argument passed to the above callback, if
467 * defined
468 */
469 int ocxl_link_add_pe(void *link_handle, int pasid, u32 pidr, u32 tidr,
470 u64 amr, struct mm_struct *mm,
471 void (*xsl_err_cb)(void *data, u64 addr, u64 dsisr),
472 void *xsl_err_data);
473
474 /*
475 * Remove a Process Element from the Shared Process Area for a link
476 */
477 int ocxl_link_remove_pe(void *link_handle, int pasid);
478
479 /*
480 * Allocate an AFU interrupt associated to the link.
481 *
482 * 'hw_irq' is the hardware interrupt number
483 * 'obj_handle' is the 64-bit object handle to be passed to the AFU to
484 * trigger the interrupt.
485 * On P9, 'obj_handle' is an address, which, if written, triggers the
486 * interrupt. It is an MMIO address which needs to be remapped (one
487 * page).
488 */
489 int ocxl_link_irq_alloc(void *link_handle, int *hw_irq,
490 u64 *obj_handle);
491
492 /*
493 * Free a previously allocated AFU interrupt
494 */
495 void ocxl_link_free_irq(void *link_handle, int hw_irq);
496
497 #endif /* _MISC_OCXL_H_ */