include/misc/ocxl.h

   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         u8 log_mem_size;
  36         u8 pasid_supported_log;
  37         u16 actag_supported;
  38 };
  39
  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 */
  44         s8 max_pasid_log;
  45         s8 max_afu_index;
  46 };
  47
  48 enum ocxl_endian {
  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 */
  52 };
  53
  54 // These are opaque outside the ocxl driver
  55 struct ocxl_afu;
  56 struct ocxl_fn;
  57 struct ocxl_context;
  58
  59 // Device detection & initialisation
  60
  61 /**
  62  * Open an OpenCAPI function on an OpenCAPI device
  63  *
  64  * @dev: The PCI device that contains the function
  65  *
  66  * Returns an opaque pointer to the function, or an error pointer (check with IS_ERR)
  67  */
  68 struct ocxl_fn *ocxl_function_open(struct pci_dev *dev);
  69
  70 /**
  71  * Get the list of AFUs associated with a PCI function device
  72  *
  73  * Returns a list of struct ocxl_afu *
  74  *
  75  * @fn: The OpenCAPI function containing the AFUs
  76  */
  77 struct list_head *ocxl_function_afu_list(struct ocxl_fn *fn);
  78
  79 /**
  80  * Fetch an AFU instance from an OpenCAPI function
  81  *
  82  * @fn: The OpenCAPI function to get the AFU from
  83  * @afu_idx: The index of the AFU to get
  84  *
  85  * If successful, the AFU should be released with ocxl_afu_put()
  86  *
  87  * Returns a pointer to the AFU, or NULL on error
  88  */
  89 struct ocxl_afu *ocxl_function_fetch_afu(struct ocxl_fn *fn, u8 afu_idx);
  90
  91 /**
  92  * Take a reference to an AFU
  93  *
  94  * @afu: The AFU to increment the reference count on
  95  */
  96 void ocxl_afu_get(struct ocxl_afu *afu);
  97
  98 /**
  99  * Release a reference to an AFU
 100  *
 101  * @afu: The AFU to decrement the reference count on
 102  */
 103 void ocxl_afu_put(struct ocxl_afu *afu);
 104
 105
 106 /**
 107  * Get the configuration information for an OpenCAPI function
 108  *
 109  * @fn: The OpenCAPI function to get the config for
 110  *
 111  * Returns the function config, or NULL on error
 112  */
 113 const struct ocxl_fn_config *ocxl_function_config(struct ocxl_fn *fn);
 114
 115 /**
 116  * Close an OpenCAPI function
 117  *
 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.
 120  *
 121  * @fn: The OpenCAPI function to close
 122  *
 123  */
 124 void ocxl_function_close(struct ocxl_fn *fn);
 125
 126 // Context allocation
 127
 128 /**
 129  * Allocate an OpenCAPI context
 130  *
 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)
 134  */
 135 int ocxl_context_alloc(struct ocxl_context **context, struct ocxl_afu *afu,
 136                         struct address_space *mapping);
 137
 138 /**
 139  * Free an OpenCAPI context
 140  *
 141  * @ctx: The OpenCAPI context to free
 142  */
 143 void ocxl_context_free(struct ocxl_context *ctx);
 144
 145 /**
 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
 150  *
 151  * Returns 0 on success, negative on failure
 152  */
 153 int ocxl_context_attach(struct ocxl_context *ctx, u64 amr,
 154                                 struct mm_struct *mm);
 155
 156 /**
 157  * Detach an MM from an OpenCAPI context
 158  * @ctx: The OpenCAPI context to attach
 159  *
 160  * Returns 0 on success, negative on failure
 161  */
 162 int ocxl_context_detach(struct ocxl_context *ctx);
 163
 164 // AFU IRQs
 165
 166 /**
 167  * Allocate an IRQ associated with an AFU context
 168  * @ctx: the AFU context
 169  * @irq_id: out, the IRQ ID
 170  *
 171  * Returns 0 on success, negative on failure
 172  */
 173 extern int ocxl_afu_irq_alloc(struct ocxl_context *ctx, int *irq_id);
 174
 175 /**
 176  * Frees an IRQ associated with an AFU context
 177  * @ctx: the AFU context
 178  * @irq_id: the IRQ ID
 179  *
 180  * Returns 0 on success, negative on failure
 181  */
 182 extern int ocxl_afu_irq_free(struct ocxl_context *ctx, int irq_id);
 183
 184 /**
 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
 190  *
 191  * returns the trigger page address, or 0 if the IRQ is not valid
 192  */
 193 extern u64 ocxl_afu_irq_get_addr(struct ocxl_context *ctx, int irq_id);
 194
 195 /**
 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
 202  *
 203  * Returns 0 on success, negative on failure
 204  */
 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),
 208                 void *private);
 209
 210 // AFU Metadata
 211
 212 /**
 213  * Get a pointer to the config for an AFU
 214  *
 215  * @afu: a pointer to the AFU to get the config for
 216  *
 217  * Returns a pointer to the AFU config
 218  */
 219 struct ocxl_afu_config *ocxl_afu_config(struct ocxl_afu *afu);
 220
 221 /**
 222  * Assign opaque hardware specific information to an OpenCAPI AFU.
 223  *
 224  * @dev: The PCI device associated with the OpenCAPI device
 225  * @private: the opaque hardware specific information to assign to the driver
 226  */
 227 void ocxl_afu_set_private(struct ocxl_afu *afu, void *private);
 228
 229 /**
 230  * Fetch the hardware specific information associated with an external OpenCAPI
 231  * AFU. This may be consumed by an external OpenCAPI driver.
 232  *
 233  * @afu: The AFU
 234  *
 235  * Returns the opaque pointer associated with the device, or NULL if not set
 236  */
 237 void *ocxl_afu_get_private(struct ocxl_afu *dev);
 238
 239 // Global MMIO
 240 /**
 241  * Read a 32 bit value from global MMIO
 242  *
 243  * @afu: The AFU
 244  * @offset: The Offset from the start of MMIO
 245  * @endian: the endianness that the MMIO data is in
 246  * @val: returns the value
 247  *
 248  * Returns 0 for success, negative on error
 249  */
 250 int ocxl_global_mmio_read32(struct ocxl_afu *afu, size_t offset,
 251                                 enum ocxl_endian endian, u32 *val);
 252
 253 /**
 254  * Read a 64 bit value from global MMIO
 255  *
 256  * @afu: The AFU
 257  * @offset: The Offset from the start of MMIO
 258  * @endian: the endianness that the MMIO data is in
 259  * @val: returns the value
 260  *
 261  * Returns 0 for success, negative on error
 262  */
 263 int ocxl_global_mmio_read64(struct ocxl_afu *afu, size_t offset,
 264                                 enum ocxl_endian endian, u64 *val);
 265
 266 /**
 267  * Write a 32 bit value to global MMIO
 268  *
 269  * @afu: The AFU
 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
 273  *
 274  * Returns 0 for success, negative on error
 275  */
 276 int ocxl_global_mmio_write32(struct ocxl_afu *afu, size_t offset,
 277                                 enum ocxl_endian endian, u32 val);
 278
 279 /**
 280  * Write a 64 bit value to global MMIO
 281  *
 282  * @afu: The AFU
 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
 286  *
 287  * Returns 0 for success, negative on error
 288  */
 289 int ocxl_global_mmio_write64(struct ocxl_afu *afu, size_t offset,
 290                                 enum ocxl_endian endian, u64 val);
 291
 292 /**
 293  * Set bits in a 32 bit global MMIO register
 294  *
 295  * @afu: The AFU
 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
 299  *
 300  * Returns 0 for success, negative on error
 301  */
 302 int ocxl_global_mmio_set32(struct ocxl_afu *afu, size_t offset,
 303                                 enum ocxl_endian endian, u32 mask);
 304
 305 /**
 306  * Set bits in a 64 bit global MMIO register
 307  *
 308  * @afu: The AFU
 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
 312  *
 313  * Returns 0 for success, negative on error
 314  */
 315 int ocxl_global_mmio_set64(struct ocxl_afu *afu, size_t offset,
 316                                 enum ocxl_endian endian, u64 mask);
 317
 318 /**
 319  * Set bits in a 32 bit global MMIO register
 320  *
 321  * @afu: The AFU
 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
 325  *
 326  * Returns 0 for success, negative on error
 327  */
 328 int ocxl_global_mmio_clear32(struct ocxl_afu *afu, size_t offset,
 329                                 enum ocxl_endian endian, u32 mask);
 330
 331 /**
 332  * Set bits in a 64 bit global MMIO register
 333  *
 334  * @afu: The AFU
 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
 338  *
 339  * Returns 0 for success, negative on error
 340  */
 341 int ocxl_global_mmio_clear64(struct ocxl_afu *afu, size_t offset,
 342                                 enum ocxl_endian endian, u64 mask);
 343
 344 // Functions left here are for compatibility with the cxlflash driver
 345
 346 /*
 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
 349  */
 350 int ocxl_config_read_afu(struct pci_dev *dev,
 351                                 struct ocxl_fn_config *fn,
 352                                 struct ocxl_afu_config *afu,
 353                                 u8 afu_idx);
 354
 355 /*
 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
 358  * of 2
 359  *
 360  * 'afu_control_offset' is the offset of the AFU control DVSEC which
 361  * can be found in the function configuration
 362  */
 363 void ocxl_config_set_afu_pasid(struct pci_dev *dev,
 364                                 int afu_control_offset,
 365                                 int pasid_base, u32 pasid_count_log);
 366
 367 /*
 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
 372  *             of the function.
 373  */
 374 int ocxl_config_get_actag_info(struct pci_dev *dev,
 375                                 u16 *base, u16 *enabled, u16 *supported);
 376
 377 /*
 378  * Tell a function, by writing in the configuration space, the actags
 379  * it can use.
 380  *
 381  * 'func_offset' is the offset of the Function DVSEC that can found in
 382  * the function configuration
 383  */
 384 void ocxl_config_set_actag(struct pci_dev *dev, int func_offset,
 385                                 u32 actag_base, u32 actag_count);
 386
 387 /*
 388  * Tell an AFU, by writing in the configuration space, the actags it
 389  * can use.
 390  *
 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
 393  */
 394 void ocxl_config_set_afu_actag(struct pci_dev *dev,
 395                                 int afu_control_offset,
 396                                 int actag_base, int actag_count);
 397
 398 /*
 399  * Enable/disable an AFU, by writing in the configuration space.
 400  *
 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
 403  */
 404 void ocxl_config_set_afu_state(struct pci_dev *dev,
 405                                 int afu_control_offset, int enable);
 406
 407 /*
 408  * Set the Transaction Layer configuration in the configuration space.
 409  * Only needed for function 0.
 410  *
 411  * It queries the host TL capabilities, find some common ground
 412  * between the host and device, and set the Transaction Layer on both
 413  * accordingly.
 414  */
 415 int ocxl_config_set_TL(struct pci_dev *dev, int tl_dvsec);
 416
 417 /*
 418  * Request an AFU to terminate a PASID.
 419  * Will return once the AFU has acked the request, or an error in case
 420  * of timeout.
 421  *
 422  * The hardware can only terminate one PASID at a time, so caller must
 423  * guarantee some kind of serialization.
 424  *
 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
 427  */
 428 int ocxl_config_terminate_pasid(struct pci_dev *dev,
 429                                 int afu_control_offset, int pasid);
 430
 431 /*
 432  * Read the configuration space of a function and fill in a
 433  * ocxl_fn_config structure with all the function details
 434  */
 435 int ocxl_config_read_function(struct pci_dev *dev,
 436                                 struct ocxl_fn_config *fn);
 437
 438 /*
 439  * Set up the opencapi link for the function.
 440  *
 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.
 444  *
 445  * Returns a 'link handle' that should be used for further calls for
 446  * the link
 447  */
 448 int ocxl_link_setup(struct pci_dev *dev, int PE_mask,
 449                         void **link_handle);
 450
 451 /*
 452  * Remove the association between the function and its link.
 453  */
 454 void ocxl_link_release(struct pci_dev *dev, void *link_handle);
 455
 456 /*
 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.
 459  *
 460  * 'xsl_err_cb' is an optional callback if the driver wants to be
 461  * notified when the translation fault interrupt handler detects an
 462  * address error.
 463  * 'xsl_err_data' is an argument passed to the above callback, if
 464  * defined
 465  */
 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),
 469                 void *xsl_err_data);
 470
 471 /*
 472  * Remove a Process Element from the Shared Process Area for a link
 473  */
 474 int ocxl_link_remove_pe(void *link_handle, int pasid);
 475
 476 /*
 477  * Allocate an AFU interrupt associated to the link.
 478  *
 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
 484  * page).
 485  */
 486 int ocxl_link_irq_alloc(void *link_handle, int *hw_irq,
 487                         u64 *obj_handle);
 488
 489 /*
 490  * Free a previously allocated AFU interrupt
 491  */
 492 void ocxl_link_free_irq(void *link_handle, int hw_irq);
 493
 494 #endif /* _MISC_OCXL_H_ */