drivers/net/nfp/nfpcore/nfp_cpp.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018 Netronome Systems, Inc.
   3  * All rights reserved.
   4  */
   5
   6 #ifndef __NFP_CPP_H__
   7 #define __NFP_CPP_H__
   8
   9 #include "nfp-common/nfp_platform.h"
  10 #include "nfp-common/nfp_resid.h"
  11
  12 struct nfp_cpp_mutex;
  13
  14 /*
  15  * NFP CPP handle
  16  */
  17 struct nfp_cpp {
  18         uint32_t model;
  19         uint32_t interface;
  20         uint8_t *serial;
  21         int serial_len;
  22         void *priv;
  23
  24         /* Mutex cache */
  25         struct nfp_cpp_mutex *mutex_cache;
  26         const struct nfp_cpp_operations *op;
  27
  28         /*
  29          * NFP-6xxx originating island IMB CPP Address Translation. CPP Target
  30          * ID is index into array. Values are obtained at runtime from local
  31          * island XPB CSRs.
  32          */
  33         uint32_t imb_cat_table[16];
  34 };
  35
  36 /*
  37  * NFP CPP device area handle
  38  */
  39 struct nfp_cpp_area {
  40         struct nfp_cpp *cpp;
  41         char *name;
  42         unsigned long long offset;
  43         unsigned long size;
  44         /* Here follows the 'priv' part of nfp_cpp_area. */
  45 };
  46
  47 /*
  48  * NFP CPP operations structure
  49  */
  50 struct nfp_cpp_operations {
  51         /* Size of priv area in struct nfp_cpp_area */
  52         size_t area_priv_size;
  53
  54         /* Instance an NFP CPP */
  55         int (*init)(struct nfp_cpp *cpp, const char *devname);
  56
  57         /*
  58          * Free the bus.
  59          * Called only once, during nfp_cpp_unregister()
  60          */
  61         void (*free)(struct nfp_cpp *cpp);
  62
  63         /*
  64          * Initialize a new NFP CPP area
  65          * NOTE: This is _not_ serialized
  66          */
  67         int (*area_init)(struct nfp_cpp_area *area,
  68                          uint32_t dest,
  69                          unsigned long long address,
  70                          unsigned long size);
  71         /*
  72          * Clean up a NFP CPP area before it is freed
  73          * NOTE: This is _not_ serialized
  74          */
  75         void (*area_cleanup)(struct nfp_cpp_area *area);
  76
  77         /*
  78          * Acquire resources for a NFP CPP area
  79          * Serialized
  80          */
  81         int (*area_acquire)(struct nfp_cpp_area *area);
  82         /*
  83          * Release resources for a NFP CPP area
  84          * Serialized
  85          */
  86         void (*area_release)(struct nfp_cpp_area *area);
  87         /*
  88          * Return a void IO pointer to a NFP CPP area
  89          * NOTE: This is _not_ serialized
  90          */
  91
  92         void *(*area_iomem)(struct nfp_cpp_area *area);
  93
  94         void *(*area_mapped)(struct nfp_cpp_area *area);
  95         /*
  96          * Perform a read from a NFP CPP area
  97          * Serialized
  98          */
  99         int (*area_read)(struct nfp_cpp_area *area,
 100                          void *kernel_vaddr,
 101                          unsigned long offset,
 102                          unsigned int length);
 103         /*
 104          * Perform a write to a NFP CPP area
 105          * Serialized
 106          */
 107         int (*area_write)(struct nfp_cpp_area *area,
 108                           const void *kernel_vaddr,
 109                           unsigned long offset,
 110                           unsigned int length);
 111 };
 112
 113 /*
 114  * This should be the only external function the transport
 115  * module supplies
 116  */
 117 const struct nfp_cpp_operations *nfp_cpp_transport_operations(void);
 118
 119 /*
 120  * Set the model id
 121  *
 122  * @param   cpp     NFP CPP operations structure
 123  * @param   model   Model ID
 124  */
 125 void nfp_cpp_model_set(struct nfp_cpp *cpp, uint32_t model);
 126
 127 /*
 128  * Set the private instance owned data of a nfp_cpp struct
 129  *
 130  * @param   cpp     NFP CPP operations structure
 131  * @param   interface Interface ID
 132  */
 133 void nfp_cpp_interface_set(struct nfp_cpp *cpp, uint32_t interface);
 134
 135 /*
 136  * Set the private instance owned data of a nfp_cpp struct
 137  *
 138  * @param   cpp     NFP CPP operations structure
 139  * @param   serial  NFP serial byte array
 140  * @param   len     Length of the serial byte array
 141  */
 142 int nfp_cpp_serial_set(struct nfp_cpp *cpp, const uint8_t *serial,
 143                        size_t serial_len);
 144
 145 /*
 146  * Set the private data of the nfp_cpp instance
 147  *
 148  * @param   cpp NFP CPP operations structure
 149  * @return      Opaque device pointer
 150  */
 151 void nfp_cpp_priv_set(struct nfp_cpp *cpp, void *priv);
 152
 153 /*
 154  * Return the private data of the nfp_cpp instance
 155  *
 156  * @param   cpp NFP CPP operations structure
 157  * @return      Opaque device pointer
 158  */
 159 void *nfp_cpp_priv(struct nfp_cpp *cpp);
 160
 161 /*
 162  * Get the privately allocated portion of a NFP CPP area handle
 163  *
 164  * @param   cpp_area    NFP CPP area handle
 165  * @return          Pointer to the private area, or NULL on failure
 166  */
 167 void *nfp_cpp_area_priv(struct nfp_cpp_area *cpp_area);
 168
 169 uint32_t __nfp_cpp_model_autodetect(struct nfp_cpp *cpp);
 170
 171 /*
 172  * NFP CPP core interface for CPP clients.
 173  */
 174
 175 /*
 176  * Open a NFP CPP handle to a CPP device
 177  *
 178  * @param[in]   id      0-based ID for the CPP interface to use
 179  *
 180  * @return NFP CPP handle, or NULL on failure (and set errno accordingly).
 181  */
 182 struct nfp_cpp *nfp_cpp_from_device_name(const char *devname);
 183
 184 /*
 185  * Free a NFP CPP handle
 186  *
 187  * @param[in]   cpp     NFP CPP handle
 188  */
 189 void nfp_cpp_free(struct nfp_cpp *cpp);
 190
 191 #define NFP_CPP_MODEL_INVALID   0xffffffff
 192
 193 /*
 194  * NFP_CPP_MODEL_CHIP_of - retrieve the chip ID from the model ID
 195  *
 196  * The chip ID is a 16-bit BCD+A-F encoding for the chip type.
 197  *
 198  * @param[in]   model   NFP CPP model id
 199  * @return      NFP CPP chip id
 200  */
 201 #define NFP_CPP_MODEL_CHIP_of(model)        (((model) >> 16) & 0xffff)
 202
 203 /*
 204  * NFP_CPP_MODEL_IS_6000 - Check for the NFP6000 family of devices
 205  *
 206  * NOTE: The NFP4000 series is considered as a NFP6000 series variant.
 207  *
 208  * @param[in]   model   NFP CPP model id
 209  * @return              true if model is in the NFP6000 family, false otherwise.
 210  */
 211 #define NFP_CPP_MODEL_IS_6000(model)                 \
 212                 ((NFP_CPP_MODEL_CHIP_of(model) >= 0x4000) && \
 213                 (NFP_CPP_MODEL_CHIP_of(model) < 0x7000))
 214
 215 /*
 216  * nfp_cpp_model - Retrieve the Model ID of the NFP
 217  *
 218  * @param[in]   cpp     NFP CPP handle
 219  * @return              NFP CPP Model ID
 220  */
 221 uint32_t nfp_cpp_model(struct nfp_cpp *cpp);
 222
 223 /*
 224  * NFP Interface types - logical interface for this CPP connection 4 bits are
 225  * reserved for interface type.
 226  */
 227 #define NFP_CPP_INTERFACE_TYPE_INVALID          0x0
 228 #define NFP_CPP_INTERFACE_TYPE_PCI              0x1
 229 #define NFP_CPP_INTERFACE_TYPE_ARM              0x2
 230 #define NFP_CPP_INTERFACE_TYPE_RPC              0x3
 231 #define NFP_CPP_INTERFACE_TYPE_ILA              0x4
 232
 233 /*
 234  * Construct a 16-bit NFP Interface ID
 235  *
 236  * Interface IDs consists of 4 bits of interface type, 4 bits of unit
 237  * identifier, and 8 bits of channel identifier.
 238  *
 239  * The NFP Interface ID is used in the implementation of NFP CPP API mutexes,
 240  * which use the MU Atomic CompareAndWrite operation - hence the limit to 16
 241  * bits to be able to use the NFP Interface ID as a lock owner.
 242  *
 243  * @param[in]   type    NFP Interface Type
 244  * @param[in]   unit    Unit identifier for the interface type
 245  * @param[in]   channel Channel identifier for the interface unit
 246  * @return              Interface ID
 247  */
 248 #define NFP_CPP_INTERFACE(type, unit, channel)  \
 249         ((((type) & 0xf) << 12) | \
 250          (((unit) & 0xf) <<  8) | \
 251          (((channel) & 0xff) << 0))
 252
 253 /*
 254  * Get the interface type of a NFP Interface ID
 255  * @param[in]   interface       NFP Interface ID
 256  * @return                      NFP Interface ID's type
 257  */
 258 #define NFP_CPP_INTERFACE_TYPE_of(interface)    (((interface) >> 12) & 0xf)
 259
 260 /*
 261  * Get the interface unit of a NFP Interface ID
 262  * @param[in]   interface       NFP Interface ID
 263  * @return                      NFP Interface ID's unit
 264  */
 265 #define NFP_CPP_INTERFACE_UNIT_of(interface)    (((interface) >>  8) & 0xf)
 266
 267 /*
 268  * Get the interface channel of a NFP Interface ID
 269  * @param[in]   interface       NFP Interface ID
 270  * @return                      NFP Interface ID's channel
 271  */
 272 #define NFP_CPP_INTERFACE_CHANNEL_of(interface) (((interface) >>  0) & 0xff)
 273
 274 /*
 275  * Retrieve the Interface ID of the NFP
 276  * @param[in]   cpp     NFP CPP handle
 277  * @return              NFP CPP Interface ID
 278  */
 279 uint16_t nfp_cpp_interface(struct nfp_cpp *cpp);
 280
 281 /*
 282  * Retrieve the NFP Serial Number (unique per NFP)
 283  * @param[in]   cpp     NFP CPP handle
 284  * @param[out]  serial  Pointer to reference the serial number array
 285  *
 286  * @return      size of the NFP6000 serial number, in bytes
 287  */
 288 int nfp_cpp_serial(struct nfp_cpp *cpp, const uint8_t **serial);
 289
 290 /*
 291  * Allocate a NFP CPP area handle, as an offset into a CPP ID
 292  * @param[in]   cpp     NFP CPP handle
 293  * @param[in]   cpp_id  NFP CPP ID
 294  * @param[in]   address Offset into the NFP CPP ID address space
 295  * @param[in]   size    Size of the area to reserve
 296  *
 297  * @return NFP CPP handle, or NULL on failure (and set errno accordingly).
 298  */
 299 struct nfp_cpp_area *nfp_cpp_area_alloc(struct nfp_cpp *cpp, uint32_t cpp_id,
 300                                         unsigned long long address,
 301                                         unsigned long size);
 302
 303 /*
 304  * Allocate a NFP CPP area handle, as an offset into a CPP ID, by a named owner
 305  * @param[in]   cpp     NFP CPP handle
 306  * @param[in]   cpp_id  NFP CPP ID
 307  * @param[in]   name    Name of owner of the area
 308  * @param[in]   address Offset into the NFP CPP ID address space
 309  * @param[in]   size    Size of the area to reserve
 310  *
 311  * @return NFP CPP handle, or NULL on failure (and set errno accordingly).
 312  */
 313 struct nfp_cpp_area *nfp_cpp_area_alloc_with_name(struct nfp_cpp *cpp,
 314                                                   uint32_t cpp_id,
 315                                                   const char *name,
 316                                                   unsigned long long address,
 317                                                   unsigned long size);
 318
 319 /*
 320  * Free an allocated NFP CPP area handle
 321  * @param[in]   area    NFP CPP area handle
 322  */
 323 void nfp_cpp_area_free(struct nfp_cpp_area *area);
 324
 325 /*
 326  * Acquire the resources needed to access the NFP CPP area handle
 327  *
 328  * @param[in]   area    NFP CPP area handle
 329  *
 330  * @return 0 on success, -1 on failure (and set errno accordingly).
 331  */
 332 int nfp_cpp_area_acquire(struct nfp_cpp_area *area);
 333
 334 /*
 335  * Release the resources needed to access the NFP CPP area handle
 336  *
 337  * @param[in]   area    NFP CPP area handle
 338  */
 339 void nfp_cpp_area_release(struct nfp_cpp_area *area);
 340
 341 /*
 342  * Allocate, then acquire the resources needed to access the NFP CPP area handle
 343  * @param[in]   cpp     NFP CPP handle
 344  * @param[in]   cpp_id  NFP CPP ID
 345  * @param[in]   address Offset into the NFP CPP ID address space
 346  * @param[in]   size    Size of the area to reserve
 347  *
 348  * @return NFP CPP handle, or NULL on failure (and set errno accordingly).
 349  */
 350 struct nfp_cpp_area *nfp_cpp_area_alloc_acquire(struct nfp_cpp *cpp,
 351                                                 uint32_t cpp_id,
 352                                                 unsigned long long address,
 353                                                 unsigned long size);
 354
 355 /*
 356  * Release the resources, then free the NFP CPP area handle
 357  * @param[in]   area    NFP CPP area handle
 358  */
 359 void nfp_cpp_area_release_free(struct nfp_cpp_area *area);
 360
 361 uint8_t *nfp_cpp_map_area(struct nfp_cpp *cpp, int domain, int target,
 362                            uint64_t addr, unsigned long size,
 363                            struct nfp_cpp_area **area);
 364 /*
 365  * Return an IO pointer to the beginning of the NFP CPP area handle. The area
 366  * must be acquired with 'nfp_cpp_area_acquire()' before calling this operation.
 367  *
 368  * @param[in]   area    NFP CPP area handle
 369  *
 370  * @return Pointer to IO memory, or NULL on failure (and set errno accordingly).
 371  */
 372 void *nfp_cpp_area_mapped(struct nfp_cpp_area *area);
 373
 374 /*
 375  * Read from a NFP CPP area handle into a buffer. The area must be acquired with
 376  * 'nfp_cpp_area_acquire()' before calling this operation.
 377  *
 378  * @param[in]   area    NFP CPP area handle
 379  * @param[in]   offset  Offset into the area
 380  * @param[in]   buffer  Location of buffer to receive the data
 381  * @param[in]   length  Length of the data to read
 382  *
 383  * @return bytes read on success, -1 on failure (and set errno accordingly).
 384  *
 385  */
 386 int nfp_cpp_area_read(struct nfp_cpp_area *area, unsigned long offset,
 387                       void *buffer, size_t length);
 388
 389 /*
 390  * Write to a NFP CPP area handle from a buffer. The area must be acquired with
 391  * 'nfp_cpp_area_acquire()' before calling this operation.
 392  *
 393  * @param[in]   area    NFP CPP area handle
 394  * @param[in]   offset  Offset into the area
 395  * @param[in]   buffer  Location of buffer that holds the data
 396  * @param[in]   length  Length of the data to read
 397  *
 398  * @return bytes written on success, -1 on failure (and set errno accordingly).
 399  */
 400 int nfp_cpp_area_write(struct nfp_cpp_area *area, unsigned long offset,
 401                        const void *buffer, size_t length);
 402
 403 /*
 404  * nfp_cpp_area_iomem() - get IOMEM region for CPP area
 405  * @area:       CPP area handle
 406  *
 407  * Returns an iomem pointer for use with readl()/writel() style operations.
 408  *
 409  * NOTE: Area must have been locked down with an 'acquire'.
 410  *
 411  * Return: pointer to the area, or NULL
 412  */
 413 void *nfp_cpp_area_iomem(struct nfp_cpp_area *area);
 414
 415 /*
 416  * Verify that IO can be performed on an offset in an area
 417  *
 418  * @param[in]   area    NFP CPP area handle
 419  * @param[in]   offset  Offset into the area
 420  * @param[in]   size    Size of region to validate
 421  *
 422  * @return 0 on success, -1 on failure (and set errno accordingly).
 423  */
 424 int nfp_cpp_area_check_range(struct nfp_cpp_area *area,
 425                              unsigned long long offset, unsigned long size);
 426
 427 /*
 428  * Get the NFP CPP handle that is the parent of a NFP CPP area handle
 429  *
 430  * @param       cpp_area        NFP CPP area handle
 431  * @return                      NFP CPP handle
 432  */
 433 struct nfp_cpp *nfp_cpp_area_cpp(struct nfp_cpp_area *cpp_area);
 434
 435 /*
 436  * Get the name passed during allocation of the NFP CPP area handle
 437  *
 438  * @param       cpp_area        NFP CPP area handle
 439  * @return                      Pointer to the area's name
 440  */
 441 const char *nfp_cpp_area_name(struct nfp_cpp_area *cpp_area);
 442
 443 /*
 444  * Read a block of data from a NFP CPP ID
 445  *
 446  * @param[in]   cpp     NFP CPP handle
 447  * @param[in]   cpp_id  NFP CPP ID
 448  * @param[in]   address Offset into the NFP CPP ID address space
 449  * @param[in]   kernel_vaddr    Buffer to copy read data to
 450  * @param[in]   length  Size of the area to reserve
 451  *
 452  * @return bytes read on success, -1 on failure (and set errno accordingly).
 453  */
 454 int nfp_cpp_read(struct nfp_cpp *cpp, uint32_t cpp_id,
 455                  unsigned long long address, void *kernel_vaddr, size_t length);
 456
 457 /*
 458  * Write a block of data to a NFP CPP ID
 459  *
 460  * @param[in]   cpp     NFP CPP handle
 461  * @param[in]   cpp_id  NFP CPP ID
 462  * @param[in]   address Offset into the NFP CPP ID address space
 463  * @param[in]   kernel_vaddr    Buffer to copy write data from
 464  * @param[in]   length  Size of the area to reserve
 465  *
 466  * @return bytes written on success, -1 on failure (and set errno accordingly).
 467  */
 468 int nfp_cpp_write(struct nfp_cpp *cpp, uint32_t cpp_id,
 469                   unsigned long long address, const void *kernel_vaddr,
 470                   size_t length);
 471
 472
 473
 474 /*
 475  * Fill a NFP CPP area handle and offset with a value
 476  *
 477  * @param[in]   area    NFP CPP area handle
 478  * @param[in]   offset  Offset into the NFP CPP ID address space
 479  * @param[in]   value   32-bit value to fill area with
 480  * @param[in]   length  Size of the area to reserve
 481  *
 482  * @return bytes written on success, -1 on failure (and set errno accordingly).
 483  */
 484 int nfp_cpp_area_fill(struct nfp_cpp_area *area, unsigned long offset,
 485                       uint32_t value, size_t length);
 486
 487 /*
 488  * Read a single 32-bit value from a NFP CPP area handle
 489  *
 490  * @param area          NFP CPP area handle
 491  * @param offset        offset into NFP CPP area handle
 492  * @param value         output value
 493  *
 494  * The area must be acquired with 'nfp_cpp_area_acquire()' before calling this
 495  * operation.
 496  *
 497  * NOTE: offset must be 32-bit aligned.
 498  *
 499  * @return 0 on success, or -1 on error (and set errno accordingly).
 500  */
 501 int nfp_cpp_area_readl(struct nfp_cpp_area *area, unsigned long offset,
 502                        uint32_t *value);
 503
 504 /*
 505  * Write a single 32-bit value to a NFP CPP area handle
 506  *
 507  * @param area          NFP CPP area handle
 508  * @param offset        offset into NFP CPP area handle
 509  * @param value         value to write
 510  *
 511  * The area must be acquired with 'nfp_cpp_area_acquire()' before calling this
 512  * operation.
 513  *
 514  * NOTE: offset must be 32-bit aligned.
 515  *
 516  * @return 0 on success, or -1 on error (and set errno accordingly).
 517  */
 518 int nfp_cpp_area_writel(struct nfp_cpp_area *area, unsigned long offset,
 519                         uint32_t value);
 520
 521 /*
 522  * Read a single 64-bit value from a NFP CPP area handle
 523  *
 524  * @param area          NFP CPP area handle
 525  * @param offset        offset into NFP CPP area handle
 526  * @param value         output value
 527  *
 528  * The area must be acquired with 'nfp_cpp_area_acquire()' before calling this
 529  * operation.
 530  *
 531  * NOTE: offset must be 64-bit aligned.
 532  *
 533  * @return 0 on success, or -1 on error (and set errno accordingly).
 534  */
 535 int nfp_cpp_area_readq(struct nfp_cpp_area *area, unsigned long offset,
 536                        uint64_t *value);
 537
 538 /*
 539  * Write a single 64-bit value to a NFP CPP area handle
 540  *
 541  * @param area          NFP CPP area handle
 542  * @param offset        offset into NFP CPP area handle
 543  * @param value         value to write
 544  *
 545  * The area must be acquired with 'nfp_cpp_area_acquire()' before calling this
 546  * operation.
 547  *
 548  * NOTE: offset must be 64-bit aligned.
 549  *
 550  * @return 0 on success, or -1 on error (and set errno accordingly).
 551  */
 552 int nfp_cpp_area_writeq(struct nfp_cpp_area *area, unsigned long offset,
 553                         uint64_t value);
 554
 555 /*
 556  * Write a single 32-bit value on the XPB bus
 557  *
 558  * @param cpp           NFP CPP device handle
 559  * @param xpb_tgt       XPB target and address
 560  * @param value         value to write
 561  *
 562  * @return 0 on success, or -1 on failure (and set errno accordingly).
 563  */
 564 int nfp_xpb_writel(struct nfp_cpp *cpp, uint32_t xpb_tgt, uint32_t value);
 565
 566 /*
 567  * Read a single 32-bit value from the XPB bus
 568  *
 569  * @param cpp           NFP CPP device handle
 570  * @param xpb_tgt       XPB target and address
 571  * @param value         output value
 572  *
 573  * @return 0 on success, or -1 on failure (and set errno accordingly).
 574  */
 575 int nfp_xpb_readl(struct nfp_cpp *cpp, uint32_t xpb_tgt, uint32_t *value);
 576
 577 /*
 578  * Modify bits of a 32-bit value from the XPB bus
 579  *
 580  * @param cpp           NFP CPP device handle
 581  * @param xpb_tgt       XPB target and address
 582  * @param mask          mask of bits to alter
 583  * @param value         value to modify
 584  *
 585  * @return 0 on success, or -1 on failure (and set errno accordingly).
 586  */
 587 int nfp_xpb_writelm(struct nfp_cpp *cpp, uint32_t xpb_tgt, uint32_t mask,
 588                     uint32_t value);
 589
 590 /*
 591  * Modify bits of a 32-bit value from the XPB bus
 592  *
 593  * @param cpp           NFP CPP device handle
 594  * @param xpb_tgt       XPB target and address
 595  * @param mask          mask of bits to alter
 596  * @param value         value to monitor for
 597  * @param timeout_us    maximum number of us to wait (-1 for forever)
 598  *
 599  * @return >= 0 on success, or -1 on failure (and set errno accordingly).
 600  */
 601 int nfp_xpb_waitlm(struct nfp_cpp *cpp, uint32_t xpb_tgt, uint32_t mask,
 602                    uint32_t value, int timeout_us);
 603
 604 /*
 605  * Read a 32-bit word from a NFP CPP ID
 606  *
 607  * @param cpp           NFP CPP handle
 608  * @param cpp_id        NFP CPP ID
 609  * @param address       offset into the NFP CPP ID address space
 610  * @param value         output value
 611  *
 612  * @return 0 on success, or -1 on failure (and set errno accordingly).
 613  */
 614 int nfp_cpp_readl(struct nfp_cpp *cpp, uint32_t cpp_id,
 615                   unsigned long long address, uint32_t *value);
 616
 617 /*
 618  * Write a 32-bit value to a NFP CPP ID
 619  *
 620  * @param cpp           NFP CPP handle
 621  * @param cpp_id        NFP CPP ID
 622  * @param address       offset into the NFP CPP ID address space
 623  * @param value         value to write
 624  *
 625  * @return 0 on success, or -1 on failure (and set errno accordingly).
 626  *
 627  */
 628 int nfp_cpp_writel(struct nfp_cpp *cpp, uint32_t cpp_id,
 629                    unsigned long long address, uint32_t value);
 630
 631 /*
 632  * Read a 64-bit work from a NFP CPP ID
 633  *
 634  * @param cpp           NFP CPP handle
 635  * @param cpp_id        NFP CPP ID
 636  * @param address       offset into the NFP CPP ID address space
 637  * @param value         output value
 638  *
 639  * @return 0 on success, or -1 on failure (and set errno accordingly).
 640  */
 641 int nfp_cpp_readq(struct nfp_cpp *cpp, uint32_t cpp_id,
 642                   unsigned long long address, uint64_t *value);
 643
 644 /*
 645  * Write a 64-bit value to a NFP CPP ID
 646  *
 647  * @param cpp           NFP CPP handle
 648  * @param cpp_id        NFP CPP ID
 649  * @param address       offset into the NFP CPP ID address space
 650  * @param value         value to write
 651  *
 652  * @return 0 on success, or -1 on failure (and set errno accordingly).
 653  */
 654 int nfp_cpp_writeq(struct nfp_cpp *cpp, uint32_t cpp_id,
 655                    unsigned long long address, uint64_t value);
 656
 657 /*
 658  * Initialize a mutex location
 659
 660  * The CPP target:address must point to a 64-bit aligned location, and will
 661  * initialize 64 bits of data at the location.
 662  *
 663  * This creates the initial mutex state, as locked by this nfp_cpp_interface().
 664  *
 665  * This function should only be called when setting up the initial lock state
 666  * upon boot-up of the system.
 667  *
 668  * @param cpp           NFP CPP handle
 669  * @param target        NFP CPP target ID
 670  * @param address       Offset into the address space of the NFP CPP target ID
 671  * @param key_id        Unique 32-bit value for this mutex
 672  *
 673  * @return 0 on success, or -1 on failure (and set errno accordingly).
 674  */
 675 int nfp_cpp_mutex_init(struct nfp_cpp *cpp, int target,
 676                        unsigned long long address, uint32_t key_id);
 677
 678 /*
 679  * Create a mutex handle from an address controlled by a MU Atomic engine
 680  *
 681  * The CPP target:address must point to a 64-bit aligned location, and reserve
 682  * 64 bits of data at the location for use by the handle.
 683  *
 684  * Only target/address pairs that point to entities that support the MU Atomic
 685  * Engine's CmpAndSwap32 command are supported.
 686  *
 687  * @param cpp           NFP CPP handle
 688  * @param target        NFP CPP target ID
 689  * @param address       Offset into the address space of the NFP CPP target ID
 690  * @param key_id        32-bit unique key (must match the key at this location)
 691  *
 692  * @return              A non-NULL struct nfp_cpp_mutex * on success, NULL on
 693  *                      failure.
 694  */
 695 struct nfp_cpp_mutex *nfp_cpp_mutex_alloc(struct nfp_cpp *cpp, int target,
 696                                           unsigned long long address,
 697                                           uint32_t key_id);
 698
 699 /*
 700  * Get the NFP CPP handle the mutex was created with
 701  *
 702  * @param   mutex   NFP mutex handle
 703  * @return          NFP CPP handle
 704  */
 705 struct nfp_cpp *nfp_cpp_mutex_cpp(struct nfp_cpp_mutex *mutex);
 706
 707 /*
 708  * Get the mutex key
 709  *
 710  * @param   mutex   NFP mutex handle
 711  * @return          Mutex key
 712  */
 713 uint32_t nfp_cpp_mutex_key(struct nfp_cpp_mutex *mutex);
 714
 715 /*
 716  * Get the mutex owner
 717  *
 718  * @param   mutex   NFP mutex handle
 719  * @return          Interface ID of the mutex owner
 720  *
 721  * NOTE: This is for debug purposes ONLY - the owner may change at any time,
 722  * unless it has been locked by this NFP CPP handle.
 723  */
 724 uint16_t nfp_cpp_mutex_owner(struct nfp_cpp_mutex *mutex);
 725
 726 /*
 727  * Get the mutex target
 728  *
 729  * @param   mutex   NFP mutex handle
 730  * @return          Mutex CPP target (ie NFP_CPP_TARGET_MU)
 731  */
 732 int nfp_cpp_mutex_target(struct nfp_cpp_mutex *mutex);
 733
 734 /*
 735  * Get the mutex address
 736  *
 737  * @param   mutex   NFP mutex handle
 738  * @return          Mutex CPP address
 739  */
 740 uint64_t nfp_cpp_mutex_address(struct nfp_cpp_mutex *mutex);
 741
 742 /*
 743  * Free a mutex handle - does not alter the lock state
 744  *
 745  * @param mutex         NFP CPP Mutex handle
 746  */
 747 void nfp_cpp_mutex_free(struct nfp_cpp_mutex *mutex);
 748
 749 /*
 750  * Lock a mutex handle, using the NFP MU Atomic Engine
 751  *
 752  * @param mutex         NFP CPP Mutex handle
 753  *
 754  * @return 0 on success, or -1 on failure (and set errno accordingly).
 755  */
 756 int nfp_cpp_mutex_lock(struct nfp_cpp_mutex *mutex);
 757
 758 /*
 759  * Unlock a mutex handle, using the NFP MU Atomic Engine
 760  *
 761  * @param mutex         NFP CPP Mutex handle
 762  *
 763  * @return 0 on success, or -1 on failure (and set errno accordingly).
 764  */
 765 int nfp_cpp_mutex_unlock(struct nfp_cpp_mutex *mutex);
 766
 767 /*
 768  * Attempt to lock a mutex handle, using the NFP MU Atomic Engine
 769  *
 770  * @param mutex         NFP CPP Mutex handle
 771  * @return              0 if the lock succeeded, -1 on failure (and errno set
 772  *                      appropriately).
 773  */
 774 int nfp_cpp_mutex_trylock(struct nfp_cpp_mutex *mutex);
 775
 776 #endif /* !__NFP_CPP_H__ */