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         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  * ocxl_function_open() - Open an OpenCAPI function on an OpenCAPI device
  66  * @dev: The PCI device that contains the function
  67  *
  68  * Returns an opaque pointer to the function, or an error pointer (check with IS_ERR)
  69  */
  70 struct ocxl_fn *ocxl_function_open(struct pci_dev *dev);
  71
  72 /**
  73  * ocxl_function_afu_list() - Get the list of AFUs associated with a PCI function device
  74  * Returns a list of struct ocxl_afu *
  75  *
  76  * @fn: The OpenCAPI function containing the AFUs
  77  */
  78 struct list_head *ocxl_function_afu_list(struct ocxl_fn *fn);
  79
  80 /**
  81  * ocxl_function_fetch_afu() - 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
  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  * ocxl_afu_get() - Take a reference to an AFU
  93  * @afu: The AFU to increment the reference count on
  94  */
  95 void ocxl_afu_get(struct ocxl_afu *afu);
  96
  97 /**
  98  * ocxl_afu_put() - Release a reference to an AFU
  99  * @afu: The AFU to decrement the reference count on
 100  */
 101 void ocxl_afu_put(struct ocxl_afu *afu);
 102
 103
 104 /**
 105  * ocxl_function_config() - Get the configuration information for an OpenCAPI function
 106  * @fn: The OpenCAPI function to get the config for
 107  *
 108  * Returns the function config, or NULL on error
 109  */
 110 const struct ocxl_fn_config *ocxl_function_config(struct ocxl_fn *fn);
 111
 112 /**
 113  * ocxl_function_close() - Close an OpenCAPI function
 114  * This will free any AFUs previously retrieved from the function, and
 115  * detach and associated contexts. The contexts must by freed by the caller.
 116  *
 117  * @fn: The OpenCAPI function to close
 118  *
 119  */
 120 void ocxl_function_close(struct ocxl_fn *fn);
 121
 122 // Context allocation
 123
 124 /**
 125  * ocxl_context_alloc() - Allocate an OpenCAPI context
 126  * @context: The OpenCAPI context to allocate, must be freed with ocxl_context_free
 127  * @afu: The AFU the context belongs to
 128  * @mapping: The mapping to unmap when the context is closed (may be NULL)
 129  */
 130 int ocxl_context_alloc(struct ocxl_context **context, struct ocxl_afu *afu,
 131                         struct address_space *mapping);
 132
 133 /**
 134  * ocxl_context_free() - Free an OpenCAPI context
 135  * @ctx: The OpenCAPI context to free
 136  */
 137 void ocxl_context_free(struct ocxl_context *ctx);
 138
 139 /**
 140  * ocxl_context_attach() - Grant access to an MM to an OpenCAPI context
 141  * @ctx: The OpenCAPI context to attach
 142  * @amr: The value of the AMR register to restrict access
 143  * @mm: The mm to attach to the context
 144  *
 145  * Returns 0 on success, negative on failure
 146  */
 147 int ocxl_context_attach(struct ocxl_context *ctx, u64 amr,
 148                                 struct mm_struct *mm);
 149
 150 /**
 151  * ocxl_context_detach() - Detach an MM from an OpenCAPI context
 152  * @ctx: The OpenCAPI context to attach
 153  *
 154  * Returns 0 on success, negative on failure
 155  */
 156 int ocxl_context_detach(struct ocxl_context *ctx);
 157
 158 // AFU IRQs
 159
 160 /**
 161  * ocxl_afu_irq_alloc() - Allocate an IRQ associated with an AFU context
 162  * @ctx: the AFU context
 163  * @irq_id: out, the IRQ ID
 164  *
 165  * Returns 0 on success, negative on failure
 166  */
 167 int ocxl_afu_irq_alloc(struct ocxl_context *ctx, int *irq_id);
 168
 169 /**
 170  * ocxl_afu_irq_free() - Frees an IRQ associated with an AFU context
 171  * @ctx: the AFU context
 172  * @irq_id: the IRQ ID
 173  *
 174  * Returns 0 on success, negative on failure
 175  */
 176 int ocxl_afu_irq_free(struct ocxl_context *ctx, int irq_id);
 177
 178 /**
 179  * ocxl_afu_irq_get_addr() - Gets the address of the trigger page for an IRQ
 180  * This can then be provided to an AFU which will write to that
 181  * page to trigger the IRQ.
 182  * @ctx: The AFU context that the IRQ is associated with
 183  * @irq_id: The IRQ ID
 184  *
 185  * returns the trigger page address, or 0 if the IRQ is not valid
 186  */
 187 u64 ocxl_afu_irq_get_addr(struct ocxl_context *ctx, int irq_id);
 188
 189 /**
 190  * ocxl_irq_set_handler() - Provide a callback to be called when an IRQ is triggered
 191  * @ctx: The AFU context that the IRQ is associated with
 192  * @irq_id: The IRQ ID
 193  * @handler: the callback to be called when the IRQ is triggered
 194  * @free_private: the callback to be called when the IRQ is freed (may be NULL)
 195  * @private: Private data to be passed to the callbacks
 196  *
 197  * Returns 0 on success, negative on failure
 198  */
 199 int ocxl_irq_set_handler(struct ocxl_context *ctx, int irq_id,
 200                 irqreturn_t (*handler)(void *private),
 201                 void (*free_private)(void *private),
 202                 void *private);
 203
 204 // AFU Metadata
 205
 206 /**
 207  * ocxl_afu_config() - Get a pointer to the config for an AFU
 208  * @afu: a pointer to the AFU to get the config for
 209  *
 210  * Returns a pointer to the AFU config
 211  */
 212 struct ocxl_afu_config *ocxl_afu_config(struct ocxl_afu *afu);
 213
 214 /**
 215  * ocxl_afu_set_private() - Assign opaque hardware specific information to an OpenCAPI AFU.
 216  * @afu: The OpenCAPI AFU
 217  * @private: the opaque hardware specific information to assign to the driver
 218  */
 219 void ocxl_afu_set_private(struct ocxl_afu *afu, void *private);
 220
 221 /**
 222  * ocxl_afu_get_private() - Fetch the hardware specific information associated with
 223  * an external OpenCAPI AFU. This may be consumed by an external OpenCAPI driver.
 224  * @afu: The OpenCAPI AFU
 225  *
 226  * Returns the opaque pointer associated with the device, or NULL if not set
 227  */
 228 void *ocxl_afu_get_private(struct ocxl_afu *afu);
 229
 230 // Global MMIO
 231 /**
 232  * ocxl_global_mmio_read32() - Read a 32 bit value from global MMIO
 233  * @afu: The AFU
 234  * @offset: The Offset from the start of MMIO
 235  * @endian: the endianness that the MMIO data is in
 236  * @val: returns the value
 237  *
 238  * Returns 0 for success, negative on error
 239  */
 240 int ocxl_global_mmio_read32(struct ocxl_afu *afu, size_t offset,
 241                             enum ocxl_endian endian, u32 *val);
 242
 243 /**
 244  * ocxl_global_mmio_read64() - Read a 64 bit value from global MMIO
 245  * @afu: The AFU
 246  * @offset: The Offset from the start of MMIO
 247  * @endian: the endianness that the MMIO data is in
 248  * @val: returns the value
 249  *
 250  * Returns 0 for success, negative on error
 251  */
 252 int ocxl_global_mmio_read64(struct ocxl_afu *afu, size_t offset,
 253                             enum ocxl_endian endian, u64 *val);
 254
 255 /**
 256  * ocxl_global_mmio_write32() - Write a 32 bit value to global MMIO
 257  * @afu: The AFU
 258  * @offset: The Offset from the start of MMIO
 259  * @endian: the endianness that the MMIO data is in
 260  * @val: The value to write
 261  *
 262  * Returns 0 for success, negative on error
 263  */
 264 int ocxl_global_mmio_write32(struct ocxl_afu *afu, size_t offset,
 265                              enum ocxl_endian endian, u32 val);
 266
 267 /**
 268  * ocxl_global_mmio_write64() - Write a 64 bit value to global MMIO
 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_write64(struct ocxl_afu *afu, size_t offset,
 277                              enum ocxl_endian endian, u64 val);
 278
 279 /**
 280  * ocxl_global_mmio_set32() - Set bits in a 32 bit global MMIO register
 281  * @afu: The AFU
 282  * @offset: The Offset from the start of MMIO
 283  * @endian: the endianness that the MMIO data is in
 284  * @mask: a mask of the bits to set
 285  *
 286  * Returns 0 for success, negative on error
 287  */
 288 int ocxl_global_mmio_set32(struct ocxl_afu *afu, size_t offset,
 289                            enum ocxl_endian endian, u32 mask);
 290
 291 /**
 292  * ocxl_global_mmio_set64() - Set bits in a 64 bit global MMIO register
 293  * @afu: The AFU
 294  * @offset: The Offset from the start of MMIO
 295  * @endian: the endianness that the MMIO data is in
 296  * @mask: a mask of the bits to set
 297  *
 298  * Returns 0 for success, negative on error
 299  */
 300 int ocxl_global_mmio_set64(struct ocxl_afu *afu, size_t offset,
 301                            enum ocxl_endian endian, u64 mask);
 302
 303 /**
 304  * ocxl_global_mmio_clear32() - Set bits in a 32 bit global MMIO register
 305  * @afu: The AFU
 306  * @offset: The Offset from the start of MMIO
 307  * @endian: the endianness that the MMIO data is in
 308  * @mask: a mask of the bits to set
 309  *
 310  * Returns 0 for success, negative on error
 311  */
 312 int ocxl_global_mmio_clear32(struct ocxl_afu *afu, size_t offset,
 313                              enum ocxl_endian endian, u32 mask);
 314
 315 /**
 316  * ocxl_global_mmio_clear64() - Set bits in a 64 bit global MMIO register
 317  * @afu: The AFU
 318  * @offset: The Offset from the start of MMIO
 319  * @endian: the endianness that the MMIO data is in
 320  * @mask: a mask of the bits to set
 321  *
 322  * Returns 0 for success, negative on error
 323  */
 324 int ocxl_global_mmio_clear64(struct ocxl_afu *afu, size_t offset,
 325                              enum ocxl_endian endian, u64 mask);
 326
 327 // Functions left here are for compatibility with the cxlflash driver
 328
 329 /*
 330  * Read the configuration space of a function for the AFU specified by
 331  * the index 'afu_idx'. Fills in a ocxl_afu_config structure
 332  */
 333 int ocxl_config_read_afu(struct pci_dev *dev,
 334                                 struct ocxl_fn_config *fn,
 335                                 struct ocxl_afu_config *afu,
 336                                 u8 afu_idx);
 337
 338 /*
 339  * Tell an AFU, by writing in the configuration space, the PASIDs that
 340  * it can use. Range starts at 'pasid_base' and its size is a multiple
 341  * of 2
 342  *
 343  * 'afu_control_offset' is the offset of the AFU control DVSEC which
 344  * can be found in the function configuration
 345  */
 346 void ocxl_config_set_afu_pasid(struct pci_dev *dev,
 347                                 int afu_control_offset,
 348                                 int pasid_base, u32 pasid_count_log);
 349
 350 /*
 351  * Get the actag configuration for the function:
 352  * 'base' is the first actag value that can be used.
 353  * 'enabled' it the number of actags available, starting from base.
 354  * 'supported' is the total number of actags desired by all the AFUs
 355  *             of the function.
 356  */
 357 int ocxl_config_get_actag_info(struct pci_dev *dev,
 358                                 u16 *base, u16 *enabled, u16 *supported);
 359
 360 /*
 361  * Tell a function, by writing in the configuration space, the actags
 362  * it can use.
 363  *
 364  * 'func_offset' is the offset of the Function DVSEC that can found in
 365  * the function configuration
 366  */
 367 void ocxl_config_set_actag(struct pci_dev *dev, int func_offset,
 368                                 u32 actag_base, u32 actag_count);
 369
 370 /*
 371  * Tell an AFU, by writing in the configuration space, the actags it
 372  * can use.
 373  *
 374  * 'afu_control_offset' is the offset of the AFU control DVSEC for the
 375  * desired AFU. It can be found in the AFU configuration
 376  */
 377 void ocxl_config_set_afu_actag(struct pci_dev *dev,
 378                                 int afu_control_offset,
 379                                 int actag_base, int actag_count);
 380
 381 /*
 382  * Enable/disable an AFU, by writing in the configuration space.
 383  *
 384  * 'afu_control_offset' is the offset of the AFU control DVSEC for the
 385  * desired AFU. It can be found in the AFU configuration
 386  */
 387 void ocxl_config_set_afu_state(struct pci_dev *dev,
 388                                 int afu_control_offset, int enable);
 389
 390 /*
 391  * Set the Transaction Layer configuration in the configuration space.
 392  * Only needed for function 0.
 393  *
 394  * It queries the host TL capabilities, find some common ground
 395  * between the host and device, and set the Transaction Layer on both
 396  * accordingly.
 397  */
 398 int ocxl_config_set_TL(struct pci_dev *dev, int tl_dvsec);
 399
 400 /*
 401  * Request an AFU to terminate a PASID.
 402  * Will return once the AFU has acked the request, or an error in case
 403  * of timeout.
 404  *
 405  * The hardware can only terminate one PASID at a time, so caller must
 406  * guarantee some kind of serialization.
 407  *
 408  * 'afu_control_offset' is the offset of the AFU control DVSEC for the
 409  * desired AFU. It can be found in the AFU configuration
 410  */
 411 int ocxl_config_terminate_pasid(struct pci_dev *dev,
 412                                 int afu_control_offset, int pasid);
 413
 414 /*
 415  * Read the configuration space of a function and fill in a
 416  * ocxl_fn_config structure with all the function details
 417  */
 418 int ocxl_config_read_function(struct pci_dev *dev,
 419                                 struct ocxl_fn_config *fn);
 420
 421 /*
 422  * Set up the opencapi link for the function.
 423  *
 424  * When called for the first time for a link, it sets up the Shared
 425  * Process Area for the link and the interrupt handler to process
 426  * translation faults.
 427  *
 428  * Returns a 'link handle' that should be used for further calls for
 429  * the link
 430  */
 431 int ocxl_link_setup(struct pci_dev *dev, int PE_mask,
 432                         void **link_handle);
 433
 434 /*
 435  * Remove the association between the function and its link.
 436  */
 437 void ocxl_link_release(struct pci_dev *dev, void *link_handle);
 438
 439 /*
 440  * Add a Process Element to the Shared Process Area for a link.
 441  * The process is defined by its PASID, pid, tid and its mm_struct.
 442  *
 443  * 'xsl_err_cb' is an optional callback if the driver wants to be
 444  * notified when the translation fault interrupt handler detects an
 445  * address error.
 446  * 'xsl_err_data' is an argument passed to the above callback, if
 447  * defined
 448  */
 449 int ocxl_link_add_pe(void *link_handle, int pasid, u32 pidr, u32 tidr,
 450                 u64 amr, u16 bdf, struct mm_struct *mm,
 451                 void (*xsl_err_cb)(void *data, u64 addr, u64 dsisr),
 452                 void *xsl_err_data);
 453
 454 /*
 455  * Remove a Process Element from the Shared Process Area for a link
 456  */
 457 int ocxl_link_remove_pe(void *link_handle, int pasid);
 458
 459 /*
 460  * Allocate an AFU interrupt associated to the link.
 461  *
 462  * 'hw_irq' is the hardware interrupt number
 463  */
 464 int ocxl_link_irq_alloc(void *link_handle, int *hw_irq);
 465
 466 /*
 467  * Free a previously allocated AFU interrupt
 468  */
 469 void ocxl_link_free_irq(void *link_handle, int hw_irq);
 470
 471 #endif /* _MISC_OCXL_H_ */