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  * 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_ */