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