net/nfp: support CPP
[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 "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__ */