~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/arch/tile/include/gxio/mpipe.h

Version: ~ [ linux-5.11 ] ~ [ linux-5.10.17 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.99 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.176 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.221 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.257 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.257 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.85 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  1 /*
  2  * Copyright 2012 Tilera Corporation. All Rights Reserved.
  3  *
  4  *   This program is free software; you can redistribute it and/or
  5  *   modify it under the terms of the GNU General Public License
  6  *   as published by the Free Software Foundation, version 2.
  7  *
  8  *   This program is distributed in the hope that it will be useful, but
  9  *   WITHOUT ANY WARRANTY; without even the implied warranty of
 10  *   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
 11  *   NON INFRINGEMENT.  See the GNU General Public License for
 12  *   more details.
 13  */
 14 
 15 #ifndef _GXIO_MPIPE_H_
 16 #define _GXIO_MPIPE_H_
 17 
 18 /*
 19  *
 20  * An API for allocating, configuring, and manipulating mPIPE hardware
 21  * resources.
 22  */
 23 
 24 #include <gxio/common.h>
 25 #include <gxio/dma_queue.h>
 26 
 27 #include <linux/time.h>
 28 
 29 #include <arch/mpipe_def.h>
 30 #include <arch/mpipe_shm.h>
 31 
 32 #include <hv/drv_mpipe_intf.h>
 33 #include <hv/iorpc.h>
 34 
 35 /*
 36  *
 37  * The TILE-Gx mPIPE&tm; shim provides Ethernet connectivity, packet
 38  * classification, and packet load balancing services.  The
 39  * gxio_mpipe_ API, declared in <gxio/mpipe.h>, allows applications to
 40  * allocate mPIPE IO channels, configure packet distribution
 41  * parameters, and send and receive Ethernet packets.  The API is
 42  * designed to be a minimal wrapper around the mPIPE hardware, making
 43  * system calls only where necessary to preserve inter-process
 44  * protection guarantees.
 45  *
 46  * The APIs described below allow the programmer to allocate and
 47  * configure mPIPE resources.  As described below, the mPIPE is a
 48  * single shared hardware device that provides partitionable resources
 49  * that are shared between all applications in the system.  The
 50  * gxio_mpipe_ API allows userspace code to make resource request
 51  * calls to the hypervisor, which in turns keeps track of the
 52  * resources in use by all applications, maintains protection
 53  * guarantees, and resets resources upon application shutdown.
 54  *
 55  * We strongly recommend reading the mPIPE section of the IO Device
 56  * Guide (UG404) before working with this API.  Most functions in the
 57  * gxio_mpipe_ API are directly analogous to hardware interfaces and
 58  * the documentation assumes that the reader understands those
 59  * hardware interfaces.
 60  *
 61  * @section mpipe__ingress mPIPE Ingress Hardware Resources
 62  *
 63  * The mPIPE ingress hardware provides extensive hardware offload for
 64  * tasks like packet header parsing, load balancing, and memory
 65  * management.  This section provides a brief introduction to the
 66  * hardware components and the gxio_mpipe_ calls used to manage them;
 67  * see the IO Device Guide for a much more detailed description of the
 68  * mPIPE's capabilities.
 69  *
 70  * When a packet arrives at one of the mPIPE's Ethernet MACs, it is
 71  * assigned a channel number indicating which MAC received it.  It
 72  * then proceeds through the following hardware pipeline:
 73  *
 74  * @subsection mpipe__classification Classification
 75  *
 76  * A set of classification processors run header parsing code on each
 77  * incoming packet, extracting information including the destination
 78  * MAC address, VLAN, Ethernet type, and five-tuple hash.  Some of
 79  * this information is then used to choose which buffer stack will be
 80  * used to hold the packet, and which bucket will be used by the load
 81  * balancer to determine which application will receive the packet.
 82  *
 83  * The rules by which the buffer stack and bucket are chosen can be
 84  * configured via the @ref gxio_mpipe_classifier API.  A given app can
 85  * specify multiple rules, each one specifying a bucket range, and a
 86  * set of buffer stacks, to be used for packets matching the rule.
 87  * Each rule can optionally specify a restricted set of channels,
 88  * VLANs, and/or dMACs, in which it is interested.  By default, a
 89  * given rule starts out matching all channels associated with the
 90  * mPIPE context's set of open links; all VLANs; and all dMACs.
 91  * Subsequent restrictions can then be added.
 92  *
 93  * @subsection mpipe__load_balancing Load Balancing
 94  *
 95  * The mPIPE load balancer is responsible for choosing the NotifRing
 96  * to which the packet will be delivered.  This decision is based on
 97  * the bucket number indicated by the classification program.  In
 98  * general, the bucket number is based on some number of low bits of
 99  * the packet's flow hash (applications that aren't interested in flow
100  * hashing use a single bucket).  Each load balancer bucket keeps a
101  * record of the NotifRing to which packets directed to that bucket
102  * are currently being delivered.  Based on the bucket's load
103  * balancing mode (@ref gxio_mpipe_bucket_mode_t), the load balancer
104  * either forwards the packet to the previously assigned NotifRing or
105  * decides to choose a new NotifRing.  If a new NotifRing is required,
106  * the load balancer chooses the least loaded ring in the NotifGroup
107  * associated with the bucket.
108  *
109  * The load balancer is a shared resource.  Each application needs to
110  * explicitly allocate NotifRings, NotifGroups, and buckets, using
111  * gxio_mpipe_alloc_notif_rings(), gxio_mpipe_alloc_notif_groups(),
112  * and gxio_mpipe_alloc_buckets().  Then the application needs to
113  * configure them using gxio_mpipe_init_notif_ring() and
114  * gxio_mpipe_init_notif_group_and_buckets().
115  *
116  * @subsection mpipe__buffers Buffer Selection and Packet Delivery
117  *
118  * Once the load balancer has chosen the destination NotifRing, the
119  * mPIPE DMA engine pops at least one buffer off of the 'buffer stack'
120  * chosen by the classification program and DMAs the packet data into
121  * that buffer.  Each buffer stack provides a hardware-accelerated
122  * stack of data buffers with the same size.  If the packet data is
123  * larger than the buffers provided by the chosen buffer stack, the
124  * mPIPE hardware pops off multiple buffers and chains the packet data
125  * through a multi-buffer linked list.  Once the packet data is
126  * delivered to the buffer(s), the mPIPE hardware writes the
127  * ::gxio_mpipe_idesc_t metadata object (calculated by the classifier)
128  * into the NotifRing and increments the number of packets delivered
129  * to that ring.
130  *
131  * Applications can push buffers onto a buffer stack by calling
132  * gxio_mpipe_push_buffer() or by egressing a packet with the
133  * ::gxio_mpipe_edesc_t::hwb bit set, indicating that the egressed
134  * buffers should be returned to the stack.
135  *
136  * Applications can allocate and initialize buffer stacks with the
137  * gxio_mpipe_alloc_buffer_stacks() and gxio_mpipe_init_buffer_stack()
138  * APIs.
139  *
140  * The application must also register the memory pages that will hold
141  * packets.  This requires calling gxio_mpipe_register_page() for each
142  * memory page that will hold packets allocated by the application for
143  * a given buffer stack.  Since each buffer stack is limited to 16
144  * registered pages, it may be necessary to use huge pages, or even
145  * extremely huge pages, to hold all the buffers.
146  *
147  * @subsection mpipe__iqueue NotifRings
148  *
149  * Each NotifRing is a region of shared memory, allocated by the
150  * application, to which the mPIPE delivers packet descriptors
151  * (::gxio_mpipe_idesc_t).  The application can allocate them via
152  * gxio_mpipe_alloc_notif_rings().  The application can then either
153  * explicitly initialize them with gxio_mpipe_init_notif_ring() and
154  * then read from them manually, or can make use of the convenience
155  * wrappers provided by @ref gxio_mpipe_wrappers.
156  *
157  * @section mpipe__egress mPIPE Egress Hardware
158  *
159  * Applications use eDMA rings to queue packets for egress.  The
160  * application can allocate them via gxio_mpipe_alloc_edma_rings().
161  * The application can then either explicitly initialize them with
162  * gxio_mpipe_init_edma_ring() and then write to them manually, or
163  * can make use of the convenience wrappers provided by
164  * @ref gxio_mpipe_wrappers.
165  *
166  * @section gxio__shortcomings Plans for Future API Revisions
167  *
168  * The API defined here is only an initial version of the mPIPE API.
169  * Future plans include:
170  *
171  * - Higher level wrapper functions to provide common initialization
172  * patterns.  This should help users start writing mPIPE programs
173  * without having to learn the details of the hardware.
174  *
175  * - Support for reset and deallocation of resources, including
176  * cleanup upon application shutdown.
177  *
178  * - Support for calling these APIs in the BME.
179  *
180  * - Support for IO interrupts.
181  *
182  * - Clearer definitions of thread safety guarantees.
183  *
184  * @section gxio__mpipe_examples Examples
185  *
186  * See the following mPIPE example programs for more information about
187  * allocating mPIPE resources and using them in real applications:
188  *
189  * - @ref mpipe/ingress/app.c : Receiving packets.
190  *
191  * - @ref mpipe/forward/app.c : Forwarding packets.
192  *
193  * Note that there are several more examples.
194  */
195 
196 /* Flags that can be passed to resource allocation functions. */
197 enum gxio_mpipe_alloc_flags_e {
198         /* Require an allocation to start at a specified resource index. */
199         GXIO_MPIPE_ALLOC_FIXED = HV_MPIPE_ALLOC_FIXED,
200 };
201 
202 /* Flags that can be passed to memory registration functions. */
203 enum gxio_mpipe_mem_flags_e {
204         /* Do not fill L3 when writing, and invalidate lines upon egress. */
205         GXIO_MPIPE_MEM_FLAG_NT_HINT = IORPC_MEM_BUFFER_FLAG_NT_HINT,
206 
207         /* L3 cache fills should only populate IO cache ways. */
208         GXIO_MPIPE_MEM_FLAG_IO_PIN = IORPC_MEM_BUFFER_FLAG_IO_PIN,
209 };
210 
211 /* An ingress packet descriptor.  When a packet arrives, the mPIPE
212  * hardware generates this structure and writes it into a NotifRing.
213  */
214 typedef MPIPE_PDESC_t gxio_mpipe_idesc_t;
215 
216 /* An egress command descriptor.  Applications write this structure
217  * into eDMA rings and the hardware performs the indicated operation
218  * (normally involving egressing some bytes).  Note that egressing a
219  * single packet may involve multiple egress command descriptors.
220  */
221 typedef MPIPE_EDMA_DESC_t gxio_mpipe_edesc_t;
222 
223 /*
224  * Max # of mpipe instances. 2 currently.
225  */
226 #define GXIO_MPIPE_INSTANCE_MAX  HV_MPIPE_INSTANCE_MAX
227 
228 #define NR_MPIPE_MAX   GXIO_MPIPE_INSTANCE_MAX
229 
230 /* Get the "va" field from an "idesc".
231  *
232  * This is the address at which the ingress hardware copied the first
233  * byte of the packet.
234  *
235  * If the classifier detected a custom header, then this will point to
236  * the custom header, and gxio_mpipe_idesc_get_l2_start() will point
237  * to the actual L2 header.
238  *
239  * Note that this value may be misleading if "idesc->be" is set.
240  *
241  * @param idesc An ingress packet descriptor.
242  */
243 static inline unsigned char *gxio_mpipe_idesc_get_va(gxio_mpipe_idesc_t *idesc)
244 {
245         return (unsigned char *)(long)idesc->va;
246 }
247 
248 /* Get the "xfer_size" from an "idesc".
249  *
250  * This is the actual number of packet bytes transferred into memory
251  * by the hardware.
252  *
253  * Note that this value may be misleading if "idesc->be" is set.
254  *
255  * @param idesc An ingress packet descriptor.
256  *
257  * ISSUE: Is this the best name for this?
258  * FIXME: Add more docs about chaining, clipping, etc.
259  */
260 static inline unsigned int gxio_mpipe_idesc_get_xfer_size(gxio_mpipe_idesc_t
261                                                           *idesc)
262 {
263         return idesc->l2_size;
264 }
265 
266 /* Get the "l2_offset" from an "idesc".
267  *
268  * Extremely customized classifiers might not support this function.
269  *
270  * This is the number of bytes between the "va" and the L2 header.
271  *
272  * The L2 header consists of a destination mac address, a source mac
273  * address, and an initial ethertype.  Various initial ethertypes
274  * allow encoding extra information in the L2 header, often including
275  * a vlan, and/or a new ethertype.
276  *
277  * Note that the "l2_offset" will be non-zero if (and only if) the
278  * classifier processed a custom header for the packet.
279  *
280  * @param idesc An ingress packet descriptor.
281  */
282 static inline uint8_t gxio_mpipe_idesc_get_l2_offset(gxio_mpipe_idesc_t *idesc)
283 {
284         return (idesc->custom1 >> 32) & 0xFF;
285 }
286 
287 /* Get the "l2_start" from an "idesc".
288  *
289  * This is simply gxio_mpipe_idesc_get_va() plus
290  * gxio_mpipe_idesc_get_l2_offset().
291  *
292  * @param idesc An ingress packet descriptor.
293  */
294 static inline unsigned char *gxio_mpipe_idesc_get_l2_start(gxio_mpipe_idesc_t
295                                                            *idesc)
296 {
297         unsigned char *va = gxio_mpipe_idesc_get_va(idesc);
298         return va + gxio_mpipe_idesc_get_l2_offset(idesc);
299 }
300 
301 /* Get the "l2_length" from an "idesc".
302  *
303  * This is simply gxio_mpipe_idesc_get_xfer_size() minus
304  * gxio_mpipe_idesc_get_l2_offset().
305  *
306  * @param idesc An ingress packet descriptor.
307  */
308 static inline unsigned int gxio_mpipe_idesc_get_l2_length(gxio_mpipe_idesc_t
309                                                           *idesc)
310 {
311         unsigned int xfer_size = idesc->l2_size;
312         return xfer_size - gxio_mpipe_idesc_get_l2_offset(idesc);
313 }
314 
315 /* A context object used to manage mPIPE hardware resources. */
316 typedef struct {
317 
318         /* File descriptor for calling up to Linux (and thus the HV). */
319         int fd;
320 
321         /* Corresponding mpipe instance #. */
322         int instance;
323 
324         /* The VA at which configuration registers are mapped. */
325         char *mmio_cfg_base;
326 
327         /* The VA at which IDMA, EDMA, and buffer manager are mapped. */
328         char *mmio_fast_base;
329 
330         /* The "initialized" buffer stacks. */
331         gxio_mpipe_rules_stacks_t __stacks;
332 
333 } gxio_mpipe_context_t;
334 
335 /* This is only used internally, but it's most easily made visible here. */
336 typedef gxio_mpipe_context_t gxio_mpipe_info_context_t;
337 
338 /* Initialize an mPIPE context.
339  *
340  * This function allocates an mPIPE "service domain" and maps the MMIO
341  * registers into the caller's VA space.
342  *
343  * @param context Context object to be initialized.
344  * @param mpipe_instance Instance number of mPIPE shim to be controlled via
345  *  context.
346  */
347 extern int gxio_mpipe_init(gxio_mpipe_context_t *context,
348                            unsigned int mpipe_instance);
349 
350 /* Destroy an mPIPE context.
351  *
352  * This function frees the mPIPE "service domain" and unmaps the MMIO
353  * registers from the caller's VA space.
354  *
355  * If a user process exits without calling this routine, the kernel
356  * will destroy the mPIPE context as part of process teardown.
357  *
358  * @param context Context object to be destroyed.
359  */
360 extern int gxio_mpipe_destroy(gxio_mpipe_context_t *context);
361 
362 /*****************************************************************
363  *                         Buffer Stacks                          *
364  ******************************************************************/
365 
366 /* Allocate a set of buffer stacks.
367  *
368  * The return value is NOT interesting if count is zero.
369  *
370  * @param context An initialized mPIPE context.
371  * @param count Number of stacks required.
372  * @param first Index of first stack if ::GXIO_MPIPE_ALLOC_FIXED flag is set,
373  *   otherwise ignored.
374  * @param flags Flag bits from ::gxio_mpipe_alloc_flags_e.
375  * @return Index of first allocated buffer stack, or
376  * ::GXIO_MPIPE_ERR_NO_BUFFER_STACK if allocation failed.
377  */
378 extern int gxio_mpipe_alloc_buffer_stacks(gxio_mpipe_context_t *context,
379                                           unsigned int count,
380                                           unsigned int first,
381                                           unsigned int flags);
382 
383 /* Enum codes for buffer sizes supported by mPIPE. */
384 typedef enum {
385         /* 128 byte packet data buffer. */
386         GXIO_MPIPE_BUFFER_SIZE_128 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_128,
387         /* 256 byte packet data buffer. */
388         GXIO_MPIPE_BUFFER_SIZE_256 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_256,
389         /* 512 byte packet data buffer. */
390         GXIO_MPIPE_BUFFER_SIZE_512 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_512,
391         /* 1024 byte packet data buffer. */
392         GXIO_MPIPE_BUFFER_SIZE_1024 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_1024,
393         /* 1664 byte packet data buffer. */
394         GXIO_MPIPE_BUFFER_SIZE_1664 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_1664,
395         /* 4096 byte packet data buffer. */
396         GXIO_MPIPE_BUFFER_SIZE_4096 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_4096,
397         /* 10368 byte packet data buffer. */
398         GXIO_MPIPE_BUFFER_SIZE_10368 =
399                 MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_10368,
400         /* 16384 byte packet data buffer. */
401         GXIO_MPIPE_BUFFER_SIZE_16384 = MPIPE_BSM_INIT_DAT_1__SIZE_VAL_BSZ_16384
402 } gxio_mpipe_buffer_size_enum_t;
403 
404 /* Convert a buffer size in bytes into a buffer size enum. */
405 extern gxio_mpipe_buffer_size_enum_t
406 gxio_mpipe_buffer_size_to_buffer_size_enum(size_t size);
407 
408 /* Convert a buffer size enum into a buffer size in bytes. */
409 extern size_t
410 gxio_mpipe_buffer_size_enum_to_buffer_size(gxio_mpipe_buffer_size_enum_t
411                                            buffer_size_enum);
412 
413 /* Calculate the number of bytes required to store a given number of
414  * buffers in the memory registered with a buffer stack via
415  * gxio_mpipe_init_buffer_stack().
416  */
417 extern size_t gxio_mpipe_calc_buffer_stack_bytes(unsigned long buffers);
418 
419 /* Initialize a buffer stack.  This function binds a region of memory
420  * to be used by the hardware for storing buffer addresses pushed via
421  * gxio_mpipe_push_buffer() or as the result of sending a buffer out
422  * the egress with the 'push to stack when done' bit set.  Once this
423  * function returns, the memory region's contents may be arbitrarily
424  * modified by the hardware at any time and software should not access
425  * the memory region again.
426  *
427  * @param context An initialized mPIPE context.
428  * @param stack The buffer stack index.
429  * @param buffer_size_enum The size of each buffer in the buffer stack,
430  * as an enum.
431  * @param mem The address of the buffer stack.  This memory must be
432  * physically contiguous and aligned to a 64kB boundary.
433  * @param mem_size The size of the buffer stack, in bytes.
434  * @param mem_flags ::gxio_mpipe_mem_flags_e memory flags.
435  * @return Zero on success, ::GXIO_MPIPE_ERR_INVAL_BUFFER_SIZE if
436  * buffer_size_enum is invalid, ::GXIO_MPIPE_ERR_BAD_BUFFER_STACK if
437  * stack has not been allocated.
438  */
439 extern int gxio_mpipe_init_buffer_stack(gxio_mpipe_context_t *context,
440                                         unsigned int stack,
441                                         gxio_mpipe_buffer_size_enum_t
442                                         buffer_size_enum, void *mem,
443                                         size_t mem_size,
444                                         unsigned int mem_flags);
445 
446 /* Push a buffer onto a previously initialized buffer stack.
447  *
448  * The size of the buffer being pushed must match the size that was
449  * registered with gxio_mpipe_init_buffer_stack().  All packet buffer
450  * addresses are 128-byte aligned; the low 7 bits of the specified
451  * buffer address will be ignored.
452  *
453  * @param context An initialized mPIPE context.
454  * @param stack The buffer stack index.
455  * @param buffer The buffer (the low seven bits are ignored).
456  */
457 static inline void gxio_mpipe_push_buffer(gxio_mpipe_context_t *context,
458                                           unsigned int stack, void *buffer)
459 {
460         MPIPE_BSM_REGION_ADDR_t offset = { {0} };
461         MPIPE_BSM_REGION_VAL_t val = { {0} };
462 
463         /*
464          * The mmio_fast_base region starts at the IDMA region, so subtract
465          * off that initial offset.
466          */
467         offset.region =
468                 MPIPE_MMIO_ADDR__REGION_VAL_BSM -
469                 MPIPE_MMIO_ADDR__REGION_VAL_IDMA;
470         offset.stack = stack;
471 
472 #if __SIZEOF_POINTER__ == 4
473         val.va = ((ulong) buffer) >> MPIPE_BSM_REGION_VAL__VA_SHIFT;
474 #else
475         val.va = ((long)buffer) >> MPIPE_BSM_REGION_VAL__VA_SHIFT;
476 #endif
477 
478         __gxio_mmio_write(context->mmio_fast_base + offset.word, val.word);
479 }
480 
481 /* Pop a buffer off of a previously initialized buffer stack.
482  *
483  * @param context An initialized mPIPE context.
484  * @param stack The buffer stack index.
485  * @return The buffer, or NULL if the stack is empty.
486  */
487 static inline void *gxio_mpipe_pop_buffer(gxio_mpipe_context_t *context,
488                                           unsigned int stack)
489 {
490         MPIPE_BSM_REGION_ADDR_t offset = { {0} };
491 
492         /*
493          * The mmio_fast_base region starts at the IDMA region, so subtract
494          * off that initial offset.
495          */
496         offset.region =
497                 MPIPE_MMIO_ADDR__REGION_VAL_BSM -
498                 MPIPE_MMIO_ADDR__REGION_VAL_IDMA;
499         offset.stack = stack;
500 
501         while (1) {
502                 /*
503                  * Case 1: val.c == ..._UNCHAINED, va is non-zero.
504                  * Case 2: val.c == ..._INVALID, va is zero.
505                  * Case 3: val.c == ..._NOT_RDY, va is zero.
506                  */
507                 MPIPE_BSM_REGION_VAL_t val;
508                 val.word =
509                         __gxio_mmio_read(context->mmio_fast_base +
510                                          offset.word);
511 
512                 /*
513                  * Handle case 1 and 2 by returning the buffer (or NULL).
514                  * Handle case 3 by waiting for the prefetch buffer to refill.
515                  */
516                 if (val.c != MPIPE_EDMA_DESC_WORD1__C_VAL_NOT_RDY)
517                         return (void *)((unsigned long)val.
518                                         va << MPIPE_BSM_REGION_VAL__VA_SHIFT);
519         }
520 }
521 
522 /*****************************************************************
523  *                          NotifRings                            *
524  ******************************************************************/
525 
526 /* Allocate a set of NotifRings.
527  *
528  * The return value is NOT interesting if count is zero.
529  *
530  * Note that NotifRings are allocated in chunks, so allocating one at
531  * a time is much less efficient than allocating several at once.
532  *
533  * @param context An initialized mPIPE context.
534  * @param count Number of NotifRings required.
535  * @param first Index of first NotifRing if ::GXIO_MPIPE_ALLOC_FIXED flag
536  *   is set, otherwise ignored.
537  * @param flags Flag bits from ::gxio_mpipe_alloc_flags_e.
538  * @return Index of first allocated buffer NotifRing, or
539  * ::GXIO_MPIPE_ERR_NO_NOTIF_RING if allocation failed.
540  */
541 extern int gxio_mpipe_alloc_notif_rings(gxio_mpipe_context_t *context,
542                                         unsigned int count, unsigned int first,
543                                         unsigned int flags);
544 
545 /* Initialize a NotifRing, using the given memory and size.
546  *
547  * @param context An initialized mPIPE context.
548  * @param ring The NotifRing index.
549  * @param mem A physically contiguous region of memory to be filled
550  * with a ring of ::gxio_mpipe_idesc_t structures.
551  * @param mem_size Number of bytes in the ring.  Must be 128, 512,
552  * 2048, or 65536 * sizeof(gxio_mpipe_idesc_t).
553  * @param mem_flags ::gxio_mpipe_mem_flags_e memory flags.
554  *
555  * @return 0 on success, ::GXIO_MPIPE_ERR_BAD_NOTIF_RING or
556  * ::GXIO_ERR_INVAL_MEMORY_SIZE on failure.
557  */
558 extern int gxio_mpipe_init_notif_ring(gxio_mpipe_context_t *context,
559                                       unsigned int ring,
560                                       void *mem, size_t mem_size,
561                                       unsigned int mem_flags);
562 
563 /* Configure an interrupt to be sent to a tile on incoming NotifRing
564  *  traffic.  Once an interrupt is sent for a particular ring, no more
565  *  will be sent until gxio_mica_enable_notif_ring_interrupt() is called.
566  *
567  * @param context An initialized mPIPE context.
568  * @param x X coordinate of interrupt target tile.
569  * @param y Y coordinate of interrupt target tile.
570  * @param i Index of the IPI register which will receive the interrupt.
571  * @param e Specific event which will be set in the target IPI register when
572  * the interrupt occurs.
573  * @param ring The NotifRing index.
574  * @return Zero on success, GXIO_ERR_INVAL if params are out of range.
575  */
576 extern int gxio_mpipe_request_notif_ring_interrupt(gxio_mpipe_context_t
577                                                    *context, int x, int y,
578                                                    int i, int e,
579                                                    unsigned int ring);
580 
581 /* Enable an interrupt on incoming NotifRing traffic.
582  *
583  * @param context An initialized mPIPE context.
584  * @param ring The NotifRing index.
585  * @return Zero on success, GXIO_ERR_INVAL if params are out of range.
586  */
587 extern int gxio_mpipe_enable_notif_ring_interrupt(gxio_mpipe_context_t
588                                                   *context, unsigned int ring);
589 
590 /* Map all of a client's memory via the given IOTLB.
591  * @param context An initialized mPIPE context.
592  * @param iotlb IOTLB index.
593  * @param pte Page table entry.
594  * @param flags Flags.
595  * @return Zero on success, or a negative error code.
596  */
597 extern int gxio_mpipe_register_client_memory(gxio_mpipe_context_t *context,
598                                              unsigned int iotlb, HV_PTE pte,
599                                              unsigned int flags);
600 
601 /*****************************************************************
602  *                        Notif Groups                            *
603  ******************************************************************/
604 
605 /* Allocate a set of NotifGroups.
606  *
607  * The return value is NOT interesting if count is zero.
608  *
609  * @param context An initialized mPIPE context.
610  * @param count Number of NotifGroups required.
611  * @param first Index of first NotifGroup if ::GXIO_MPIPE_ALLOC_FIXED flag
612  *   is set, otherwise ignored.
613  * @param flags Flag bits from ::gxio_mpipe_alloc_flags_e.
614  * @return Index of first allocated buffer NotifGroup, or
615  * ::GXIO_MPIPE_ERR_NO_NOTIF_GROUP if allocation failed.
616  */
617 extern int gxio_mpipe_alloc_notif_groups(gxio_mpipe_context_t *context,
618                                          unsigned int count,
619                                          unsigned int first,
620                                          unsigned int flags);
621 
622 /* Add a NotifRing to a NotifGroup.  This only sets a bit in the
623  * application's 'group' object; the hardware NotifGroup can be
624  * initialized by passing 'group' to gxio_mpipe_init_notif_group() or
625  * gxio_mpipe_init_notif_group_and_buckets().
626  */
627 static inline void
628 gxio_mpipe_notif_group_add_ring(gxio_mpipe_notif_group_bits_t *bits, int ring)
629 {
630         bits->ring_mask[ring / 64] |= (1ull << (ring % 64));
631 }
632 
633 /* Set a particular NotifGroup bitmask.  Since the load balancer
634  * makes decisions based on both bucket and NotifGroup state, most
635  * applications should use gxio_mpipe_init_notif_group_and_buckets()
636  * rather than using this function to configure just a NotifGroup.
637  */
638 extern int gxio_mpipe_init_notif_group(gxio_mpipe_context_t *context,
639                                        unsigned int group,
640                                        gxio_mpipe_notif_group_bits_t bits);
641 
642 /*****************************************************************
643  *                         Load Balancer                          *
644  ******************************************************************/
645 
646 /* Allocate a set of load balancer buckets.
647  *
648  * The return value is NOT interesting if count is zero.
649  *
650  * Note that buckets are allocated in chunks, so allocating one at
651  * a time is much less efficient than allocating several at once.
652  *
653  * Note that the buckets are actually divided into two sub-ranges, of
654  * different sizes, and different chunk sizes, and the range you get
655  * by default is determined by the size of the request.  Allocations
656  * cannot span the two sub-ranges.
657  *
658  * @param context An initialized mPIPE context.
659  * @param count Number of buckets required.
660  * @param first Index of first bucket if ::GXIO_MPIPE_ALLOC_FIXED flag is set,
661  *   otherwise ignored.
662  * @param flags Flag bits from ::gxio_mpipe_alloc_flags_e.
663  * @return Index of first allocated buffer bucket, or
664  * ::GXIO_MPIPE_ERR_NO_BUCKET if allocation failed.
665  */
666 extern int gxio_mpipe_alloc_buckets(gxio_mpipe_context_t *context,
667                                     unsigned int count, unsigned int first,
668                                     unsigned int flags);
669 
670 /* The legal modes for gxio_mpipe_bucket_info_t and
671  * gxio_mpipe_init_notif_group_and_buckets().
672  *
673  * All modes except ::GXIO_MPIPE_BUCKET_ROUND_ROBIN expect that the user
674  * will allocate a power-of-two number of buckets and initialize them
675  * to the same mode.  The classifier program then uses the appropriate
676  * number of low bits from the incoming packet's flow hash to choose a
677  * load balancer bucket.  Based on that bucket's load balancing mode,
678  * reference count, and currently active NotifRing, the load balancer
679  * chooses the NotifRing to which the packet will be delivered.
680  */
681 typedef enum {
682         /* All packets for a bucket go to the same NotifRing unless the
683          * NotifRing gets full, in which case packets will be dropped.  If
684          * the bucket reference count ever reaches zero, a new NotifRing may
685          * be chosen.
686          */
687         GXIO_MPIPE_BUCKET_DYNAMIC_FLOW_AFFINITY =
688                 MPIPE_LBL_INIT_DAT_BSTS_TBL__MODE_VAL_DFA,
689 
690         /* All packets for a bucket always go to the same NotifRing.
691          */
692         GXIO_MPIPE_BUCKET_STATIC_FLOW_AFFINITY =
693                 MPIPE_LBL_INIT_DAT_BSTS_TBL__MODE_VAL_FIXED,
694 
695         /* All packets for a bucket go to the least full NotifRing in the
696          * group, providing load balancing round robin behavior.
697          */
698         GXIO_MPIPE_BUCKET_ROUND_ROBIN =
699                 MPIPE_LBL_INIT_DAT_BSTS_TBL__MODE_VAL_ALWAYS_PICK,
700 
701         /* All packets for a bucket go to the same NotifRing unless the
702          * NotifRing gets full, at which point the bucket starts using the
703          * least full NotifRing in the group.  If all NotifRings in the
704          * group are full, packets will be dropped.
705          */
706         GXIO_MPIPE_BUCKET_STICKY_FLOW_LOCALITY =
707                 MPIPE_LBL_INIT_DAT_BSTS_TBL__MODE_VAL_STICKY,
708 
709         /* All packets for a bucket go to the same NotifRing unless the
710          * NotifRing gets full, or a random timer fires, at which point the
711          * bucket starts using the least full NotifRing in the group.  If
712          * all NotifRings in the group are full, packets will be dropped.
713          * WARNING: This mode is BROKEN on chips with fewer than 64 tiles.
714          */
715         GXIO_MPIPE_BUCKET_PREFER_FLOW_LOCALITY =
716                 MPIPE_LBL_INIT_DAT_BSTS_TBL__MODE_VAL_STICKY_RAND,
717 
718 } gxio_mpipe_bucket_mode_t;
719 
720 /* Copy a set of bucket initialization values into the mPIPE
721  * hardware.  Since the load balancer makes decisions based on both
722  * bucket and NotifGroup state, most applications should use
723  * gxio_mpipe_init_notif_group_and_buckets() rather than using this
724  * function to configure a single bucket.
725  *
726  * @param context An initialized mPIPE context.
727  * @param bucket Bucket index to be initialized.
728  * @param bucket_info Initial reference count, NotifRing index, and mode.
729  * @return 0 on success, ::GXIO_MPIPE_ERR_BAD_BUCKET on failure.
730  */
731 extern int gxio_mpipe_init_bucket(gxio_mpipe_context_t *context,
732                                   unsigned int bucket,
733                                   gxio_mpipe_bucket_info_t bucket_info);
734 
735 /* Initializes a group and range of buckets and range of rings such
736  * that the load balancer runs a particular load balancing function.
737  *
738  * First, the group is initialized with the given rings.
739  *
740  * Second, each bucket is initialized with the mode and group, and a
741  * ring chosen round-robin from the given rings.
742  *
743  * Normally, the classifier picks a bucket, and then the load balancer
744  * picks a ring, based on the bucket's mode, group, and current ring,
745  * possibly updating the bucket's ring.
746  *
747  * @param context An initialized mPIPE context.
748  * @param group The group.
749  * @param ring The first ring.
750  * @param num_rings The number of rings.
751  * @param bucket The first bucket.
752  * @param num_buckets The number of buckets.
753  * @param mode The load balancing mode.
754  *
755  * @return 0 on success, ::GXIO_MPIPE_ERR_BAD_BUCKET,
756  * ::GXIO_MPIPE_ERR_BAD_NOTIF_GROUP, or
757  * ::GXIO_MPIPE_ERR_BAD_NOTIF_RING on failure.
758  */
759 extern int gxio_mpipe_init_notif_group_and_buckets(gxio_mpipe_context_t
760                                                    *context,
761                                                    unsigned int group,
762                                                    unsigned int ring,
763                                                    unsigned int num_rings,
764                                                    unsigned int bucket,
765                                                    unsigned int num_buckets,
766                                                    gxio_mpipe_bucket_mode_t
767                                                    mode);
768 
769 /* Return credits to a NotifRing and/or bucket.
770  *
771  * @param context An initialized mPIPE context.
772  * @param ring The NotifRing index, or -1.
773  * @param bucket The bucket, or -1.
774  * @param count The number of credits to return.
775  */
776 static inline void gxio_mpipe_credit(gxio_mpipe_context_t *context,
777                                      int ring, int bucket, unsigned int count)
778 {
779         /* NOTE: Fancy struct initialization would break "C89" header test. */
780 
781         MPIPE_IDMA_RELEASE_REGION_ADDR_t offset = { {0} };
782         MPIPE_IDMA_RELEASE_REGION_VAL_t val = { {0} };
783 
784         /*
785          * The mmio_fast_base region starts at the IDMA region, so subtract
786          * off that initial offset.
787          */
788         offset.region =
789                 MPIPE_MMIO_ADDR__REGION_VAL_IDMA -
790                 MPIPE_MMIO_ADDR__REGION_VAL_IDMA;
791         offset.ring = ring;
792         offset.bucket = bucket;
793         offset.ring_enable = (ring >= 0);
794         offset.bucket_enable = (bucket >= 0);
795         val.count = count;
796 
797         __gxio_mmio_write(context->mmio_fast_base + offset.word, val.word);
798 }
799 
800 /*****************************************************************
801  *                         Egress Rings                           *
802  ******************************************************************/
803 
804 /* Allocate a set of eDMA rings.
805  *
806  * The return value is NOT interesting if count is zero.
807  *
808  * @param context An initialized mPIPE context.
809  * @param count Number of eDMA rings required.
810  * @param first Index of first eDMA ring if ::GXIO_MPIPE_ALLOC_FIXED flag
811  *   is set, otherwise ignored.
812  * @param flags Flag bits from ::gxio_mpipe_alloc_flags_e.
813  * @return Index of first allocated buffer eDMA ring, or
814  * ::GXIO_MPIPE_ERR_NO_EDMA_RING if allocation failed.
815  */
816 extern int gxio_mpipe_alloc_edma_rings(gxio_mpipe_context_t *context,
817                                        unsigned int count, unsigned int first,
818                                        unsigned int flags);
819 
820 /* Initialize an eDMA ring, using the given memory and size.
821  *
822  * @param context An initialized mPIPE context.
823  * @param ering The eDMA ring index.
824  * @param channel The channel to use.  This must be one of the channels
825  * associated with the context's set of open links.
826  * @param mem A physically contiguous region of memory to be filled
827  * with a ring of ::gxio_mpipe_edesc_t structures.
828  * @param mem_size Number of bytes in the ring.  Must be 512, 2048,
829  * 8192 or 65536, times 16 (i.e. sizeof(gxio_mpipe_edesc_t)).
830  * @param mem_flags ::gxio_mpipe_mem_flags_e memory flags.
831  *
832  * @return 0 on success, ::GXIO_MPIPE_ERR_BAD_EDMA_RING or
833  * ::GXIO_ERR_INVAL_MEMORY_SIZE on failure.
834  */
835 extern int gxio_mpipe_init_edma_ring(gxio_mpipe_context_t *context,
836                                      unsigned int ering, unsigned int channel,
837                                      void *mem, size_t mem_size,
838                                      unsigned int mem_flags);
839 
840 /* Set the "max_blks", "min_snf_blks", and "db" fields of
841  * ::MPIPE_EDMA_RG_INIT_DAT_THRESH_t for a given edma ring.
842  *
843  * The global pool of dynamic blocks will be automatically adjusted.
844  *
845  * This function should not be called after any egress has been done
846  * on the edma ring.
847  *
848  * Most applications should just use gxio_mpipe_equeue_set_snf_size().
849  *
850  * @param context An initialized mPIPE context.
851  * @param ering The eDMA ring index.
852  * @param max_blks The number of blocks to dedicate to the ring
853  * (normally min_snf_blks + 1).  Must be greater than min_snf_blocks.
854  * @param min_snf_blks The number of blocks which must be stored
855  * prior to starting to send the packet (normally 12).
856  * @param db Whether to allow use of dynamic blocks by the ring
857  * (normally 1).
858  *
859  * @return 0 on success, negative on error.
860  */
861 extern int gxio_mpipe_config_edma_ring_blks(gxio_mpipe_context_t *context,
862                                             unsigned int ering,
863                                             unsigned int max_blks,
864                                             unsigned int min_snf_blks,
865                                             unsigned int db);
866 
867 /*****************************************************************
868  *                      Classifier Program                        *
869  ******************************************************************/
870 
871 /*
872  *
873  * Functions for loading or configuring the mPIPE classifier program.
874  *
875  * The mPIPE classification processors all run a special "classifier"
876  * program which, for each incoming packet, parses the packet headers,
877  * encodes some packet metadata in the "idesc", and either drops the
878  * packet, or picks a notif ring to handle the packet, and a buffer
879  * stack to contain the packet, usually based on the channel, VLAN,
880  * dMAC, flow hash, and packet size, under the guidance of the "rules"
881  * API described below.
882  *
883  * @section gxio_mpipe_classifier_default Default Classifier
884  *
885  * The MDE provides a simple "default" classifier program.  It is
886  * shipped as source in "$TILERA_ROOT/src/sys/mpipe/classifier.c",
887  * which serves as its official documentation.  It is shipped as a
888  * binary program in "$TILERA_ROOT/tile/boot/classifier", which is
889  * automatically included in bootroms created by "tile-monitor", and
890  * is automatically loaded by the hypervisor at boot time.
891  *
892  * The L2 analysis handles LLC packets, SNAP packets, and "VLAN
893  * wrappers" (keeping the outer VLAN).
894  *
895  * The L3 analysis handles IPv4 and IPv6, dropping packets with bad
896  * IPv4 header checksums, requesting computation of a TCP/UDP checksum
897  * if appropriate, and hashing the dest and src IP addresses, plus the
898  * ports for TCP/UDP packets, into the flow hash.  No special analysis
899  * is done for "fragmented" packets or "tunneling" protocols.  Thus,
900  * the first fragment of a fragmented TCP/UDP packet is hashed using
901  * src/dest IP address and ports and all subsequent fragments are only
902  * hashed according to src/dest IP address.
903  *
904  * The L3 analysis handles other packets too, hashing the dMAC
905  * smac into a flow hash.
906  *
907  * The channel, VLAN, and dMAC used to pick a "rule" (see the
908  * "rules" APIs below), which in turn is used to pick a buffer stack
909  * (based on the packet size) and a bucket (based on the flow hash).
910  *
911  * To receive traffic matching a particular (channel/VLAN/dMAC
912  * pattern, an application should allocate its own buffer stacks and
913  * load balancer buckets, and map traffic to those stacks and buckets,
914  * as decribed by the "rules" API below.
915  *
916  * Various packet metadata is encoded in the idesc.  The flow hash is
917  * four bytes at 0x0C.  The VLAN is two bytes at 0x10.  The ethtype is
918  * two bytes at 0x12.  The l3 start is one byte at 0x14.  The l4 start
919  * is one byte at 0x15 for IPv4 and IPv6 packets, and otherwise zero.
920  * The protocol is one byte at 0x16 for IPv4 and IPv6 packets, and
921  * otherwise zero.
922  *
923  * @section gxio_mpipe_classifier_custom Custom Classifiers.
924  *
925  * A custom classifier may be created using "tile-mpipe-cc" with a
926  * customized version of the default classifier sources.
927  *
928  * The custom classifier may be included in bootroms using the
929  * "--classifier" option to "tile-monitor", or loaded dynamically
930  * using gxio_mpipe_classifier_load_from_file().
931  *
932  * Be aware that "extreme" customizations may break the assumptions of
933  * the "rules" APIs described below, but simple customizations, such
934  * as adding new packet metadata, should be fine.
935  */
936 
937 /* A set of classifier rules, plus a context. */
938 typedef struct {
939 
940         /* The context. */
941         gxio_mpipe_context_t *context;
942 
943         /* The actual rules. */
944         gxio_mpipe_rules_list_t list;
945 
946 } gxio_mpipe_rules_t;
947 
948 /* Initialize a classifier program rules list.
949  *
950  * This function can be called on a previously initialized rules list
951  * to discard any previously added rules.
952  *
953  * @param rules Rules list to initialize.
954  * @param context An initialized mPIPE context.
955  */
956 extern void gxio_mpipe_rules_init(gxio_mpipe_rules_t *rules,
957                                   gxio_mpipe_context_t *context);
958 
959 /* Begin a new rule on the indicated rules list.
960  *
961  * Note that an empty rule matches all packets, but an empty rule list
962  * matches no packets.
963  *
964  * @param rules Rules list to which new rule is appended.
965  * @param bucket First load balancer bucket to which packets will be
966  * delivered.
967  * @param num_buckets Number of buckets (must be a power of two) across
968  * which packets will be distributed based on the "flow hash".
969  * @param stacks Either NULL, to assign each packet to the smallest
970  * initialized buffer stack which does not induce chaining (and to
971  * drop packets which exceed the largest initialized buffer stack
972  * buffer size), or an array, with each entry indicating which buffer
973  * stack should be used for packets up to that size (with 255
974  * indicating that those packets should be dropped).
975  * @return 0 on success, or a negative error code on failure.
976  */
977 extern int gxio_mpipe_rules_begin(gxio_mpipe_rules_t *rules,
978                                   unsigned int bucket,
979                                   unsigned int num_buckets,
980                                   gxio_mpipe_rules_stacks_t *stacks);
981 
982 /* Set the headroom of the current rule.
983  *
984  * @param rules Rules list whose current rule will be modified.
985  * @param headroom The headroom.
986  * @return 0 on success, or a negative error code on failure.
987  */
988 extern int gxio_mpipe_rules_set_headroom(gxio_mpipe_rules_t *rules,
989                                          uint8_t headroom);
990 
991 /* Indicate that packets from a particular channel can be delivered
992  * to the buckets and buffer stacks associated with the current rule.
993  *
994  * Channels added must be associated with links opened by the mPIPE context
995  * used in gxio_mpipe_rules_init().  A rule with no channels is equivalent
996  * to a rule naming all such associated channels.
997  *
998  * @param rules Rules list whose current rule will be modified.
999  * @param channel The channel to add.
1000  * @return 0 on success, or a negative error code on failure.
1001  */
1002 extern int gxio_mpipe_rules_add_channel(gxio_mpipe_rules_t *rules,
1003                                         unsigned int channel);
1004 
1005 /* Commit rules.
1006  *
1007  * The rules are sent to the hypervisor, where they are combined with
1008  * the rules from other apps, and used to program the hardware classifier.
1009  *
1010  * Note that if this function returns an error, then the rules will NOT
1011  * have been committed, even if the error is due to interactions with
1012  * rules from another app.
1013  *
1014  * @param rules Rules list to commit.
1015  * @return 0 on success, or a negative error code on failure.
1016  */
1017 extern int gxio_mpipe_rules_commit(gxio_mpipe_rules_t *rules);
1018 
1019 /*****************************************************************
1020  *                     Ingress Queue Wrapper                      *
1021  ******************************************************************/
1022 
1023 /*
1024  *
1025  * Convenience functions for receiving packets from a NotifRing and
1026  * sending packets via an eDMA ring.
1027  *
1028  * The mpipe ingress and egress hardware uses shared memory packet
1029  * descriptors to describe packets that have arrived on ingress or
1030  * are destined for egress.  These descriptors are stored in shared
1031  * memory ring buffers and written or read by hardware as necessary.
1032  * The gxio library provides wrapper functions that manage the head and
1033  * tail pointers for these rings, allowing the user to easily read or
1034  * write packet descriptors.
1035  *
1036  * The initialization interface for ingress and egress rings is quite
1037  * similar.  For example, to create an ingress queue, the user passes
1038  * a ::gxio_mpipe_iqueue_t state object, a ring number from
1039  * gxio_mpipe_alloc_notif_rings(), and the address of memory to hold a
1040  * ring buffer to the gxio_mpipe_iqueue_init() function.  The function
1041  * returns success when the state object has been initialized and the
1042  * hardware configured to deliver packets to the specified ring
1043  * buffer.  Similarly, gxio_mpipe_equeue_init() takes a
1044  * ::gxio_mpipe_equeue_t state object, a ring number from
1045  * gxio_mpipe_alloc_edma_rings(), and a shared memory buffer.
1046  *
1047  * @section gxio_mpipe_iqueue Working with Ingress Queues
1048  *
1049  * Once initialized, the gxio_mpipe_iqueue_t API provides two flows
1050  * for getting the ::gxio_mpipe_idesc_t packet descriptor associated
1051  * with incoming packets.  The simplest is to call
1052  * gxio_mpipe_iqueue_get() or gxio_mpipe_iqueue_try_get().  These
1053  * functions copy the oldest packet descriptor out of the NotifRing and
1054  * into a descriptor provided by the caller.  They also immediately
1055  * inform the hardware that a descriptor has been processed.
1056  *
1057  * For applications with stringent performance requirements, higher
1058  * efficiency can be achieved by avoiding the packet descriptor copy
1059  * and processing multiple descriptors at once.  The
1060  * gxio_mpipe_iqueue_peek() and gxio_mpipe_iqueue_try_peek() functions
1061  * allow such optimizations.  These functions provide a pointer to the
1062  * next valid ingress descriptor in the NotifRing's shared memory ring
1063  * buffer, and a count of how many contiguous descriptors are ready to
1064  * be processed.  The application can then process any number of those
1065  * descriptors in place, calling gxio_mpipe_iqueue_consume() to inform
1066  * the hardware after each one has been processed.
1067  *
1068  * @section gxio_mpipe_equeue Working with Egress Queues
1069  *
1070  * Similarly, the egress queue API provides a high-performance
1071  * interface plus a simple wrapper for use in posting
1072  * ::gxio_mpipe_edesc_t egress packet descriptors.  The simple
1073  * version, gxio_mpipe_equeue_put(), allows the programmer to wait for
1074  * an eDMA ring slot to become available and write a single descriptor
1075  * into the ring.
1076  *
1077  * Alternatively, you can reserve slots in the eDMA ring using
1078  * gxio_mpipe_equeue_reserve() or gxio_mpipe_equeue_try_reserve(), and
1079  * then fill in each slot using gxio_mpipe_equeue_put_at().  This
1080  * capability can be used to amortize the cost of reserving slots
1081  * across several packets.  It also allows gather operations to be
1082  * performed on a shared equeue, by ensuring that the edescs for all
1083  * the fragments are all contiguous in the eDMA ring.
1084  *
1085  * The gxio_mpipe_equeue_reserve() and gxio_mpipe_equeue_try_reserve()
1086  * functions return a 63-bit "completion slot", which is actually a
1087  * sequence number, the low bits of which indicate the ring buffer
1088  * index and the high bits the number of times the application has
1089  * gone around the egress ring buffer.  The extra bits allow an
1090  * application to check for egress completion by calling
1091  * gxio_mpipe_equeue_is_complete() to see whether a particular 'slot'
1092  * number has finished.  Given the maximum packet rates of the Gx
1093  * processor, the 63-bit slot number will never wrap.
1094  *
1095  * In practice, most applications use the ::gxio_mpipe_edesc_t::hwb
1096  * bit to indicate that the buffers containing egress packet data
1097  * should be pushed onto a buffer stack when egress is complete.  Such
1098  * applications generally do not need to know when an egress operation
1099  * completes (since there is no need to free a buffer post-egress),
1100  * and thus can use the optimized gxio_mpipe_equeue_reserve_fast() or
1101  * gxio_mpipe_equeue_try_reserve_fast() functions, which return a 24
1102  * bit "slot", instead of a 63-bit "completion slot".
1103  *
1104  * Once a slot has been "reserved", it MUST be filled.  If the
1105  * application reserves a slot and then decides that it does not
1106  * actually need it, it can set the ::gxio_mpipe_edesc_t::ns (no send)
1107  * bit on the descriptor passed to gxio_mpipe_equeue_put_at() to
1108  * indicate that no data should be sent.  This technique can also be
1109  * used to drop an incoming packet, instead of forwarding it, since
1110  * any buffer will still be pushed onto the buffer stack when the
1111  * egress descriptor is processed.
1112  */
1113 
1114 /* A convenient interface to a NotifRing, for use by a single thread.
1115  */
1116 typedef struct {
1117 
1118         /* The context. */
1119         gxio_mpipe_context_t *context;
1120 
1121         /* The actual NotifRing. */
1122         gxio_mpipe_idesc_t *idescs;
1123 
1124         /* The number of entries. */
1125         unsigned long num_entries;
1126 
1127         /* The number of entries minus one. */
1128         unsigned long mask_num_entries;
1129 
1130         /* The log2() of the number of entries. */
1131         unsigned long log2_num_entries;
1132 
1133         /* The next entry. */
1134         unsigned int head;
1135 
1136         /* The NotifRing id. */
1137         unsigned int ring;
1138 
1139 #ifdef __BIG_ENDIAN__
1140         /* The number of byteswapped entries. */
1141         unsigned int swapped;
1142 #endif
1143 
1144 } gxio_mpipe_iqueue_t;
1145 
1146 /* Initialize an "iqueue".
1147  *
1148  * Takes the iqueue plus the same args as gxio_mpipe_init_notif_ring().
1149  */
1150 extern int gxio_mpipe_iqueue_init(gxio_mpipe_iqueue_t *iqueue,
1151                                   gxio_mpipe_context_t *context,
1152                                   unsigned int ring,
1153                                   void *mem, size_t mem_size,
1154                                   unsigned int mem_flags);
1155 
1156 /* Advance over some old entries in an iqueue.
1157  *
1158  * Please see the documentation for gxio_mpipe_iqueue_consume().
1159  *
1160  * @param iqueue An ingress queue initialized via gxio_mpipe_iqueue_init().
1161  * @param count The number of entries to advance over.
1162  */
1163 static inline void gxio_mpipe_iqueue_advance(gxio_mpipe_iqueue_t *iqueue,
1164                                              int count)
1165 {
1166         /* Advance with proper wrap. */
1167         int head = iqueue->head + count;
1168         iqueue->head =
1169                 (head & iqueue->mask_num_entries) +
1170                 (head >> iqueue->log2_num_entries);
1171 
1172 #ifdef __BIG_ENDIAN__
1173         /* HACK: Track swapped entries. */
1174         iqueue->swapped -= count;
1175 #endif
1176 }
1177 
1178 /* Release the ring and bucket for an old entry in an iqueue.
1179  *
1180  * Releasing the ring allows more packets to be delivered to the ring.
1181  *
1182  * Releasing the bucket allows flows using the bucket to be moved to a
1183  * new ring when using GXIO_MPIPE_BUCKET_DYNAMIC_FLOW_AFFINITY.
1184  *
1185  * This function is shorthand for "gxio_mpipe_credit(iqueue->context,
1186  * iqueue->ring, idesc->bucket_id, 1)", and it may be more convenient
1187  * to make that underlying call, using those values, instead of
1188  * tracking the entire "idesc".
1189  *
1190  * If packet processing is deferred, optimal performance requires that
1191  * the releasing be deferred as well.
1192  *
1193  * Please see the documentation for gxio_mpipe_iqueue_consume().
1194  *
1195  * @param iqueue An ingress queue initialized via gxio_mpipe_iqueue_init().
1196  * @param idesc The descriptor which was processed.
1197  */
1198 static inline void gxio_mpipe_iqueue_release(gxio_mpipe_iqueue_t *iqueue,
1199                                              gxio_mpipe_idesc_t *idesc)
1200 {
1201         gxio_mpipe_credit(iqueue->context, iqueue->ring, idesc->bucket_id, 1);
1202 }
1203 
1204 /* Consume a packet from an "iqueue".
1205  *
1206  * After processing packets peeked at via gxio_mpipe_iqueue_peek()
1207  * or gxio_mpipe_iqueue_try_peek(), you must call this function, or
1208  * gxio_mpipe_iqueue_advance() plus gxio_mpipe_iqueue_release(), to
1209  * advance over those entries, and release their rings and buckets.
1210  *
1211  * You may call this function as each packet is processed, or you can
1212  * wait until several packets have been processed.
1213  *
1214  * Note that if you are using a single bucket, and you are handling
1215  * batches of N packets, then you can replace several calls to this
1216  * function with calls to "gxio_mpipe_iqueue_advance(iqueue, N)" and
1217  * "gxio_mpipe_credit(iqueue->context, iqueue->ring, bucket, N)".
1218  *
1219  * Note that if your classifier sets "idesc->nr", then you should
1220  * explicitly call "gxio_mpipe_iqueue_advance(iqueue, idesc)" plus
1221  * "gxio_mpipe_credit(iqueue->context, iqueue->ring, -1, 1)", to
1222  * avoid incorrectly crediting the (unused) bucket.
1223  *
1224  * @param iqueue An ingress queue initialized via gxio_mpipe_iqueue_init().
1225  * @param idesc The descriptor which was processed.
1226  */
1227 static inline void gxio_mpipe_iqueue_consume(gxio_mpipe_iqueue_t *iqueue,
1228                                              gxio_mpipe_idesc_t *idesc)
1229 {
1230         gxio_mpipe_iqueue_advance(iqueue, 1);
1231         gxio_mpipe_iqueue_release(iqueue, idesc);
1232 }
1233 
1234 /* Peek at the next packet(s) in an "iqueue", without waiting.
1235  *
1236  * If no packets are available, fills idesc_ref with NULL, and then
1237  * returns ::GXIO_MPIPE_ERR_IQUEUE_EMPTY.  Otherwise, fills idesc_ref
1238  * with the address of the next valid packet descriptor, and returns
1239  * the maximum number of valid descriptors which can be processed.
1240  * You may process fewer descriptors if desired.
1241  *
1242  * Call gxio_mpipe_iqueue_consume() on each packet once it has been
1243  * processed (or dropped), to allow more packets to be delivered.
1244  *
1245  * @param iqueue An ingress queue initialized via gxio_mpipe_iqueue_init().
1246  * @param idesc_ref A pointer to a packet descriptor pointer.
1247  * @return The (positive) number of packets which can be processed,
1248  * or ::GXIO_MPIPE_ERR_IQUEUE_EMPTY if no packets are available.
1249  */
1250 static inline int gxio_mpipe_iqueue_try_peek(gxio_mpipe_iqueue_t *iqueue,
1251                                              gxio_mpipe_idesc_t **idesc_ref)
1252 {
1253         gxio_mpipe_idesc_t *next;
1254 
1255         uint64_t head = iqueue->head;
1256         uint64_t tail = __gxio_mmio_read(iqueue->idescs);
1257 
1258         /* Available entries. */
1259         uint64_t avail =
1260                 (tail >= head) ? (tail - head) : (iqueue->num_entries - head);
1261 
1262         if (avail == 0) {
1263                 *idesc_ref = NULL;
1264                 return GXIO_MPIPE_ERR_IQUEUE_EMPTY;
1265         }
1266 
1267         next = &iqueue->idescs[head];
1268 
1269         /* ISSUE: Is this helpful? */
1270         __insn_prefetch(next);
1271 
1272 #ifdef __BIG_ENDIAN__
1273         /* HACK: Swap new entries directly in memory. */
1274         {
1275                 int i, j;
1276                 for (i = iqueue->swapped; i < avail; i++) {
1277                         for (j = 0; j < 8; j++)
1278                                 next[i].words[j] =
1279                                         __builtin_bswap64(next[i].words[j]);
1280                 }
1281                 iqueue->swapped = avail;
1282         }
1283 #endif
1284 
1285         *idesc_ref = next;
1286 
1287         return avail;
1288 }
1289 
1290 /* Drop a packet by pushing its buffer (if appropriate).
1291  *
1292  * NOTE: The caller must still call gxio_mpipe_iqueue_consume() if idesc
1293  * came from gxio_mpipe_iqueue_try_peek() or gxio_mpipe_iqueue_peek().
1294  *
1295  * @param iqueue An ingress queue initialized via gxio_mpipe_iqueue_init().
1296  * @param idesc A packet descriptor.
1297  */
1298 static inline void gxio_mpipe_iqueue_drop(gxio_mpipe_iqueue_t *iqueue,
1299                                           gxio_mpipe_idesc_t *idesc)
1300 {
1301         /* FIXME: Handle "chaining" properly. */
1302 
1303         if (!idesc->be) {
1304                 unsigned char *va = gxio_mpipe_idesc_get_va(idesc);
1305                 gxio_mpipe_push_buffer(iqueue->context, idesc->stack_idx, va);
1306         }
1307 }
1308 
1309 /*****************************************************************
1310  *                      Egress Queue Wrapper                      *
1311  ******************************************************************/
1312 
1313 /* A convenient, thread-safe interface to an eDMA ring. */
1314 typedef struct {
1315 
1316         /* State object for tracking head and tail pointers. */
1317         __gxio_dma_queue_t dma_queue;
1318 
1319         /* The ring entries. */
1320         gxio_mpipe_edesc_t *edescs;
1321 
1322         /* The number of entries minus one. */
1323         unsigned long mask_num_entries;
1324 
1325         /* The log2() of the number of entries. */
1326         unsigned long log2_num_entries;
1327 
1328         /* The context. */
1329         gxio_mpipe_context_t *context;
1330 
1331         /* The ering. */
1332         unsigned int ering;
1333 
1334         /* The channel. */
1335         unsigned int channel;
1336 
1337 } gxio_mpipe_equeue_t;
1338 
1339 /* Initialize an "equeue".
1340  *
1341  * This function uses gxio_mpipe_init_edma_ring() to initialize the
1342  * underlying edma_ring using the provided arguments.
1343  *
1344  * @param equeue An egress queue to be initialized.
1345  * @param context An initialized mPIPE context.
1346  * @param ering The eDMA ring index.
1347  * @param channel The channel to use.  This must be one of the channels
1348  * associated with the context's set of open links.
1349  * @param mem A physically contiguous region of memory to be filled
1350  * with a ring of ::gxio_mpipe_edesc_t structures.
1351  * @param mem_size Number of bytes in the ring.  Must be 512, 2048,
1352  * 8192 or 65536, times 16 (i.e. sizeof(gxio_mpipe_edesc_t)).
1353  * @param mem_flags ::gxio_mpipe_mem_flags_e memory flags.
1354  *
1355  * @return 0 on success, ::GXIO_MPIPE_ERR_BAD_EDMA_RING or
1356  * ::GXIO_ERR_INVAL_MEMORY_SIZE on failure.
1357  */
1358 extern int gxio_mpipe_equeue_init(gxio_mpipe_equeue_t *equeue,
1359                                   gxio_mpipe_context_t *context,
1360                                   unsigned int ering,
1361                                   unsigned int channel,
1362                                   void *mem, unsigned int mem_size,
1363                                   unsigned int mem_flags);
1364 
1365 /* Reserve completion slots for edescs.
1366  *
1367  * Use gxio_mpipe_equeue_put_at() to actually populate the slots.
1368  *
1369  * This function is slower than gxio_mpipe_equeue_reserve_fast(), but
1370  * returns a full 64 bit completion slot, which can be used with
1371  * gxio_mpipe_equeue_is_complete().
1372  *
1373  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1374  * @param num Number of slots to reserve (must be non-zero).
1375  * @return The first reserved completion slot, or a negative error code.
1376  */
1377 static inline int64_t gxio_mpipe_equeue_reserve(gxio_mpipe_equeue_t *equeue,
1378                                                 unsigned int num)
1379 {
1380         return __gxio_dma_queue_reserve_aux(&equeue->dma_queue, num, true);
1381 }
1382 
1383 /* Reserve completion slots for edescs, if possible.
1384  *
1385  * Use gxio_mpipe_equeue_put_at() to actually populate the slots.
1386  *
1387  * This function is slower than gxio_mpipe_equeue_try_reserve_fast(),
1388  * but returns a full 64 bit completion slot, which can be used with
1389  * gxio_mpipe_equeue_is_complete().
1390  *
1391  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1392  * @param num Number of slots to reserve (must be non-zero).
1393  * @return The first reserved completion slot, or a negative error code.
1394  */
1395 static inline int64_t gxio_mpipe_equeue_try_reserve(gxio_mpipe_equeue_t
1396                                                     *equeue, unsigned int num)
1397 {
1398         return __gxio_dma_queue_reserve_aux(&equeue->dma_queue, num, false);
1399 }
1400 
1401 /* Reserve slots for edescs.
1402  *
1403  * Use gxio_mpipe_equeue_put_at() to actually populate the slots.
1404  *
1405  * This function is faster than gxio_mpipe_equeue_reserve(), but
1406  * returns a 24 bit slot (instead of a 64 bit completion slot), which
1407  * thus cannot be used with gxio_mpipe_equeue_is_complete().
1408  *
1409  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1410  * @param num Number of slots to reserve (should be non-zero).
1411  * @return The first reserved slot, or a negative error code.
1412  */
1413 static inline int64_t gxio_mpipe_equeue_reserve_fast(gxio_mpipe_equeue_t
1414                                                      *equeue, unsigned int num)
1415 {
1416         return __gxio_dma_queue_reserve(&equeue->dma_queue, num, true, false);
1417 }
1418 
1419 /* Reserve slots for edescs, if possible.
1420  *
1421  * Use gxio_mpipe_equeue_put_at() to actually populate the slots.
1422  *
1423  * This function is faster than gxio_mpipe_equeue_try_reserve(), but
1424  * returns a 24 bit slot (instead of a 64 bit completion slot), which
1425  * thus cannot be used with gxio_mpipe_equeue_is_complete().
1426  *
1427  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1428  * @param num Number of slots to reserve (should be non-zero).
1429  * @return The first reserved slot, or a negative error code.
1430  */
1431 static inline int64_t gxio_mpipe_equeue_try_reserve_fast(gxio_mpipe_equeue_t
1432                                                          *equeue,
1433                                                          unsigned int num)
1434 {
1435         return __gxio_dma_queue_reserve(&equeue->dma_queue, num, false, false);
1436 }
1437 
1438 /*
1439  * HACK: This helper function tricks gcc 4.6 into avoiding saving
1440  * a copy of "edesc->words[0]" on the stack for no obvious reason.
1441  */
1442 
1443 static inline void gxio_mpipe_equeue_put_at_aux(gxio_mpipe_equeue_t *equeue,
1444                                                 uint_reg_t ew[2],
1445                                                 unsigned long slot)
1446 {
1447         unsigned long edma_slot = slot & equeue->mask_num_entries;
1448         gxio_mpipe_edesc_t *edesc_p = &equeue->edescs[edma_slot];
1449 
1450         /*
1451          * ISSUE: Could set eDMA ring to be on generation 1 at start, which
1452          * would avoid the negation here, perhaps allowing "__insn_bfins()".
1453          */
1454         ew[0] |= !((slot >> equeue->log2_num_entries) & 1);
1455 
1456         /*
1457          * NOTE: We use "__gxio_mpipe_write()", plus the fact that the eDMA
1458          * queue alignment restrictions ensure that these two words are on
1459          * the same cacheline, to force proper ordering between the stores.
1460          */
1461         __gxio_mmio_write64(&edesc_p->words[1], ew[1]);
1462         __gxio_mmio_write64(&edesc_p->words[0], ew[0]);
1463 }
1464 
1465 /* Post an edesc to a given slot in an equeue.
1466  *
1467  * This function copies the supplied edesc into entry "slot mod N" in
1468  * the underlying ring, setting the "gen" bit to the appropriate value
1469  * based on "(slot mod N*2)", where "N" is the size of the ring.  Note
1470  * that the higher bits of slot are unused, and thus, this function
1471  * can handle "slots" as well as "completion slots".
1472  *
1473  * Normally this function is used to fill in slots reserved by
1474  * gxio_mpipe_equeue_try_reserve(), gxio_mpipe_equeue_reserve(),
1475  * gxio_mpipe_equeue_try_reserve_fast(), or
1476  * gxio_mpipe_equeue_reserve_fast(),
1477  *
1478  * This function can also be used without "reserving" slots, if the
1479  * application KNOWS that the ring can never overflow, for example, by
1480  * pushing fewer buffers into the buffer stacks than there are total
1481  * slots in the equeue, but this is NOT recommended.
1482  *
1483  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1484  * @param edesc The egress descriptor to be posted.
1485  * @param slot An egress slot (only the low bits are actually used).
1486  */
1487 static inline void gxio_mpipe_equeue_put_at(gxio_mpipe_equeue_t *equeue,
1488                                             gxio_mpipe_edesc_t edesc,
1489                                             unsigned long slot)
1490 {
1491         gxio_mpipe_equeue_put_at_aux(equeue, edesc.words, slot);
1492 }
1493 
1494 /* Post an edesc to the next slot in an equeue.
1495  *
1496  * This is a convenience wrapper around
1497  * gxio_mpipe_equeue_reserve_fast() and gxio_mpipe_equeue_put_at().
1498  *
1499  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1500  * @param edesc The egress descriptor to be posted.
1501  * @return 0 on success.
1502  */
1503 static inline int gxio_mpipe_equeue_put(gxio_mpipe_equeue_t *equeue,
1504                                         gxio_mpipe_edesc_t edesc)
1505 {
1506         int64_t slot = gxio_mpipe_equeue_reserve_fast(equeue, 1);
1507         if (slot < 0)
1508                 return (int)slot;
1509 
1510         gxio_mpipe_equeue_put_at(equeue, edesc, slot);
1511 
1512         return 0;
1513 }
1514 
1515 /* Ask the mPIPE hardware to egress outstanding packets immediately.
1516  *
1517  * This call is not necessary, but may slightly reduce overall latency.
1518  *
1519  * Technically, you should flush all gxio_mpipe_equeue_put_at() writes
1520  * to memory before calling this function, to ensure the descriptors
1521  * are visible in memory before the mPIPE hardware actually looks for
1522  * them.  But this should be very rare, and the only side effect would
1523  * be increased latency, so it is up to the caller to decide whether
1524  * or not to flush memory.
1525  *
1526  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1527  */
1528 static inline void gxio_mpipe_equeue_flush(gxio_mpipe_equeue_t *equeue)
1529 {
1530         /* Use "ring_idx = 0" and "count = 0" to "wake up" the eDMA ring. */
1531         MPIPE_EDMA_POST_REGION_VAL_t val = { {0} };
1532         /* Flush the write buffers. */
1533         __insn_flushwb();
1534         __gxio_mmio_write(equeue->dma_queue.post_region_addr, val.word);
1535 }
1536 
1537 /* Determine if a given edesc has been completed.
1538  *
1539  * Note that this function requires a "completion slot", and thus may
1540  * NOT be used with a "slot" from gxio_mpipe_equeue_reserve_fast() or
1541  * gxio_mpipe_equeue_try_reserve_fast().
1542  *
1543  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1544  * @param completion_slot The completion slot used by the edesc.
1545  * @param update If true, and the desc does not appear to have completed
1546  * yet, then update any software cache of the hardware completion counter,
1547  * and check again.  This should normally be true.
1548  * @return True iff the given edesc has been completed.
1549  */
1550 static inline int gxio_mpipe_equeue_is_complete(gxio_mpipe_equeue_t *equeue,
1551                                                 int64_t completion_slot,
1552                                                 int update)
1553 {
1554         return __gxio_dma_queue_is_complete(&equeue->dma_queue,
1555                                             completion_slot, update);
1556 }
1557 
1558 /* Set the snf (store and forward) size for an equeue.
1559  *
1560  * The snf size for an equeue defaults to 1536, and encodes the size
1561  * of the largest packet for which egress is guaranteed to avoid
1562  * transmission underruns and/or corrupt checksums under heavy load.
1563  *
1564  * The snf size affects a global resource pool which cannot support,
1565  * for example, all 24 equeues each requesting an snf size of 8K.
1566  *
1567  * To ensure that jumbo packets can be egressed properly, the snf size
1568  * should be set to the size of the largest possible packet, which
1569  * will usually be limited by the size of the app's largest buffer.
1570  *
1571  * This is a convenience wrapper around
1572  * gxio_mpipe_config_edma_ring_blks().
1573  *
1574  * This function should not be called after any egress has been done
1575  * on the equeue.
1576  *
1577  * @param equeue An egress queue initialized via gxio_mpipe_equeue_init().
1578  * @param size The snf size, in bytes.
1579  * @return Zero on success, negative error otherwise.
1580  */
1581 static inline int gxio_mpipe_equeue_set_snf_size(gxio_mpipe_equeue_t *equeue,
1582                                                  size_t size)
1583 {
1584         int blks = (size + 127) / 128;
1585         return gxio_mpipe_config_edma_ring_blks(equeue->context, equeue->ering,
1586                                                 blks + 1, blks, 1);
1587 }
1588 
1589 /*****************************************************************
1590  *                        Link Management                         *
1591  ******************************************************************/
1592 
1593 /*
1594  *
1595  * Functions for manipulating and sensing the state and configuration
1596  * of physical network links.
1597  *
1598  * @section gxio_mpipe_link_perm Link Permissions
1599  *
1600  * Opening a link (with gxio_mpipe_link_open()) requests a set of link
1601  * permissions, which control what may be done with the link, and potentially
1602  * what permissions may be granted to other processes.
1603  *
1604  * Data permission allows the process to receive packets from the link by
1605  * specifying the link's channel number in mPIPE packet distribution rules,
1606  * and to send packets to the link by using the link's channel number as
1607  * the target for an eDMA ring.
1608  *
1609  * Stats permission allows the process to retrieve link attributes (such as
1610  * the speeds it is capable of running at, or whether it is currently up), and
1611  * to read and write certain statistics-related registers in the link's MAC.
1612  *
1613  * Control permission allows the process to retrieve and modify link attributes
1614  * (so that it may, for example, bring the link up and take it down), and
1615  * read and write many registers in the link's MAC and PHY.
1616  *
1617  * Any permission may be requested as shared, which allows other processes
1618  * to also request shared permission, or exclusive, which prevents other
1619  * processes from requesting it.  In keeping with GXIO's typical usage in
1620  * an embedded environment, the defaults for all permissions are shared.
1621  *
1622  * Permissions are granted on a first-come, first-served basis, so if two
1623  * applications request an exclusive permission on the same link, the one
1624  * to run first will win.  Note, however, that some system components, like
1625  * the kernel Ethernet driver, may get an opportunity to open links before
1626  * any applications run.
1627  *
1628  * @section gxio_mpipe_link_names Link Names
1629  *
1630  * Link names are of the form gbe<em>number</em> (for Gigabit Ethernet),
1631  * xgbe<em>number</em> (for 10 Gigabit Ethernet), loop<em>number</em> (for
1632  * internal mPIPE loopback), or ilk<em>number</em>/<em>channel</em>
1633  * (for Interlaken links); for instance, gbe0, xgbe1, loop3, and
1634  * ilk0/12 are all possible link names.  The correspondence between
1635  * the link name and an mPIPE instance number or mPIPE channel number is
1636  * system-dependent; all links will not exist on all systems, and the set
1637  * of numbers used for a particular link type may not start at zero and may
1638  * not be contiguous.  Use gxio_mpipe_link_enumerate() to retrieve the set of
1639  * links which exist on a system, and always use gxio_mpipe_link_instance()
1640  * to determine which mPIPE controls a particular link.
1641  *
1642  * Note that in some cases, links may share hardware, such as PHYs, or
1643  * internal mPIPE buffers; in these cases, only one of the links may be
1644  * opened at a time.  This is especially common with xgbe and gbe ports,
1645  * since each xgbe port uses 4 SERDES lanes, each of which may also be
1646  * configured as one gbe port.
1647  *
1648  * @section gxio_mpipe_link_states Link States
1649  *
1650  * The mPIPE link management model revolves around three different states,
1651  * which are maintained for each link:
1652  *
1653  * 1. The <em>current</em> link state: is the link up now, and if so, at
1654  *    what speed?
1655  *
1656  * 2. The <em>desired</em> link state: what do we want the link state to be?
1657  *    The system is always working to make this state the current state;
1658  *    thus, if the desired state is up, and the link is down, we'll be
1659  *    constantly trying to bring it up, automatically.
1660  *
1661  * 3. The <em>possible</em> link state: what speeds are valid for this
1662  *    particular link?  Or, in other words, what are the capabilities of
1663  *    the link hardware?
1664  *
1665  * These link states are not, strictly speaking, related to application
1666  * state; they may be manipulated at any time, whether or not the link
1667  * is currently being used for data transfer.  However, for convenience,
1668  * gxio_mpipe_link_open() and gxio_mpipe_link_close() (or application exit)
1669  * can affect the link state.  These implicit link management operations
1670  * may be modified or disabled by the use of link open flags.
1671  *
1672  * From an application, you can use gxio_mpipe_link_get_attr()
1673  * and gxio_mpipe_link_set_attr() to manipulate the link states.
1674  * gxio_mpipe_link_get_attr() with ::GXIO_MPIPE_LINK_POSSIBLE_STATE
1675  * gets you the possible link state.  gxio_mpipe_link_get_attr() with
1676  * ::GXIO_MPIPE_LINK_CURRENT_STATE gets you the current link state.
1677  * Finally, gxio_mpipe_link_set_attr() and gxio_mpipe_link_get_attr()
1678  * with ::GXIO_MPIPE_LINK_DESIRED_STATE allow you to modify or retrieve
1679  * the desired link state.
1680  *
1681  * If you want to manage a link from a part of your application which isn't
1682  * involved in packet processing, you can use the ::GXIO_MPIPE_LINK_NO_DATA
1683  * flags on a gxio_mpipe_link_open() call.  This opens the link, but does
1684  * not request data permission, so it does not conflict with any exclusive
1685  * permissions which may be held by other processes.  You can then can use
1686  * gxio_mpipe_link_get_attr() and gxio_mpipe_link_set_attr() on this link
1687  * object to bring up or take down the link.
1688  *
1689  * Some links support link state bits which support various loopback
1690  * modes. ::GXIO_MPIPE_LINK_LOOP_MAC tests datapaths within the Tile
1691  * Processor itself; ::GXIO_MPIPE_LINK_LOOP_PHY tests the datapath between
1692  * the Tile Processor and the external physical layer interface chip; and
1693  * ::GXIO_MPIPE_LINK_LOOP_EXT tests the entire network datapath with the
1694  * aid of an external loopback connector.  In addition to enabling hardware
1695  * testing, such configuration can be useful for software testing, as well.
1696  *
1697  * When LOOP_MAC or LOOP_PHY is enabled, packets transmitted on a channel
1698  * will be received by that channel, instead of being emitted on the
1699  * physical link, and packets received on the physical link will be ignored.
1700  * Other than that, all standard GXIO operations work as you might expect.
1701  * Note that loopback operation requires that the link be brought up using
1702  * one or more of the GXIO_MPIPE_LINK_SPEED_xxx link state bits.
1703  *
1704  * Those familiar with previous versions of the MDE on TILEPro hardware
1705  * will notice significant similarities between the NetIO link management
1706  * model and the mPIPE link management model.  However, the NetIO model
1707  * was developed in stages, and some of its features -- for instance,
1708  * the default setting of certain flags -- were shaped by the need to be
1709  * compatible with previous versions of NetIO.  Since the features provided
1710  * by the mPIPE hardware and the mPIPE GXIO library are significantly
1711  * different than those provided by NetIO, in some cases, we have made
1712  * different choices in the mPIPE link management API.  Thus, please read
1713  * this documentation carefully before assuming that mPIPE link management
1714  * operations are exactly equivalent to their NetIO counterparts.
1715  */
1716 
1717 /* An object used to manage mPIPE link state and resources. */
1718 typedef struct {
1719         /* The overall mPIPE context. */
1720         gxio_mpipe_context_t *context;
1721 
1722         /* The channel number used by this link. */
1723         uint8_t channel;
1724 
1725         /* The MAC index used by this link. */
1726         uint8_t mac;
1727 } gxio_mpipe_link_t;
1728 
1729 /* Translate a link name to the instance number of the mPIPE shim which is
1730  *  connected to that link.  This call does not verify whether the link is
1731  *  currently available, and does not reserve any link resources;
1732  *  gxio_mpipe_link_open() must be called to perform those functions.
1733  *
1734  *  Typically applications will call this function to translate a link name
1735  *  to an mPIPE instance number; call gxio_mpipe_init(), passing it that
1736  *  instance number, to initialize the mPIPE shim; and then call
1737  *  gxio_mpipe_link_open(), passing it the same link name plus the mPIPE
1738  *  context, to configure the link.
1739  *
1740  * @param link_name Name of the link; see @ref gxio_mpipe_link_names.
1741  * @return The mPIPE instance number which is associated with the named
1742  *  link, or a negative error code (::GXIO_ERR_NO_DEVICE) if the link does
1743  *  not exist.
1744  */
1745 extern int gxio_mpipe_link_instance(const char *link_name);
1746 
1747 /* Retrieve one of this system's legal link names, and its MAC address.
1748  *
1749  * @param index Link name index.  If a system supports N legal link names,
1750  *  then indices between 0 and N - 1, inclusive, each correspond to one of
1751  *  those names.  Thus, to retrieve all of a system's legal link names,
1752  *  call this function in a loop, starting with an index of zero, and
1753  *  incrementing it once per iteration until -1 is returned.
1754  * @param link_name Pointer to the buffer which will receive the retrieved
1755  *  link name.  The buffer should contain space for at least
1756  *  ::GXIO_MPIPE_LINK_NAME_LEN bytes; the returned name, including the
1757  *  terminating null byte, will be no longer than that.
1758  * @param link_name Pointer to the buffer which will receive the retrieved
1759  *  MAC address.  The buffer should contain space for at least 6 bytes.
1760  * @return Zero if a link name was successfully retrieved; -1 if one was
1761  *  not.
1762  */
1763 extern int gxio_mpipe_link_enumerate_mac(int index, char *link_name,
1764                                          uint8_t *mac_addr);
1765 
1766 /* Open an mPIPE link.
1767  *
1768  *  A link must be opened before it may be used to send or receive packets,
1769  *  and before its state may be examined or changed.  Depending up on the
1770  *  link's intended use, one or more link permissions may be requested via
1771  *  the flags parameter; see @ref gxio_mpipe_link_perm.  In addition, flags
1772  *  may request that the link's state be modified at open time.  See @ref
1773  *  gxio_mpipe_link_states and @ref gxio_mpipe_link_open_flags for more detail.
1774  *
1775  * @param link A link state object, which will be initialized if this
1776  *  function completes successfully.
1777  * @param context An initialized mPIPE context.
1778  * @param link_name Name of the link.
1779  * @param flags Zero or more @ref gxio_mpipe_link_open_flags, ORed together.
1780  * @return 0 if the link was successfully opened, or a negative error code.
1781  *
1782  */
1783 extern int gxio_mpipe_link_open(gxio_mpipe_link_t *link,
1784                                 gxio_mpipe_context_t *context,
1785                                 const char *link_name, unsigned int flags);
1786 
1787 /* Close an mPIPE link.
1788  *
1789  *  Closing a link makes it available for use by other processes.  Once
1790  *  a link has been closed, packets may no longer be sent on or received
1791  *  from the link, and its state may not be examined or changed.
1792  *
1793  * @param link A link state object, which will no longer be initialized
1794  *  if this function completes successfully.
1795  * @return 0 if the link was successfully closed, or a negative error code.
1796  *
1797  */
1798 extern int gxio_mpipe_link_close(gxio_mpipe_link_t *link);
1799 
1800 /* Return a link's channel number.
1801  *
1802  * @param link A properly initialized link state object.
1803  * @return The channel number for the link.
1804  */
1805 static inline int gxio_mpipe_link_channel(gxio_mpipe_link_t *link)
1806 {
1807         return link->channel;
1808 }
1809 
1810 /* Set a link attribute.
1811  *
1812  * @param link A properly initialized link state object.
1813  * @param attr An attribute from the set of @ref gxio_mpipe_link_attrs.
1814  * @param val New value of the attribute.
1815  * @return 0 if the attribute was successfully set, or a negative error
1816  *  code.
1817  */
1818 extern int gxio_mpipe_link_set_attr(gxio_mpipe_link_t *link, uint32_t attr,
1819                                     int64_t val);
1820 
1821 ///////////////////////////////////////////////////////////////////
1822 //                             Timestamp                         //
1823 ///////////////////////////////////////////////////////////////////
1824 
1825 /* Get the timestamp of mPIPE when this routine is called.
1826  *
1827  * @param context An initialized mPIPE context.
1828  * @param ts A timespec structure to store the current clock.
1829  * @return If the call was successful, zero; otherwise, a negative error
1830  *  code.
1831  */
1832 extern int gxio_mpipe_get_timestamp(gxio_mpipe_context_t *context,
1833                                     struct timespec64 *ts);
1834 
1835 /* Set the timestamp of mPIPE.
1836  *
1837  * @param context An initialized mPIPE context.
1838  * @param ts A timespec structure to store the requested clock.
1839  * @return If the call was successful, zero; otherwise, a negative error
1840  *  code.
1841  */
1842 extern int gxio_mpipe_set_timestamp(gxio_mpipe_context_t *context,
1843                                     const struct timespec64 *ts);
1844 
1845 /* Adjust the timestamp of mPIPE.
1846  *
1847  * @param context An initialized mPIPE context.
1848  * @param delta A signed time offset to adjust, in nanoseconds.
1849  * The absolute value of this parameter must be less than or
1850  * equal to 1000000000.
1851  * @return If the call was successful, zero; otherwise, a negative error
1852  *  code.
1853  */
1854 extern int gxio_mpipe_adjust_timestamp(gxio_mpipe_context_t *context,
1855                                        int64_t delta);
1856 
1857 /** Adjust the mPIPE timestamp clock frequency.
1858  *
1859  * @param context An initialized mPIPE context.
1860  * @param ppb A 32-bit signed PPB (Parts Per Billion) value to adjust.
1861  * The absolute value of ppb must be less than or equal to 1000000000.
1862  * Values less than about 30000 will generally cause a GXIO_ERR_INVAL
1863  * return due to the granularity of the hardware that converts reference
1864  * clock cycles into seconds and nanoseconds.
1865  * @return If the call was successful, zero; otherwise, a negative error
1866  *  code.
1867  */
1868 extern int gxio_mpipe_adjust_timestamp_freq(gxio_mpipe_context_t* context,
1869                                             int32_t ppb);
1870 
1871 #endif /* !_GXIO_MPIPE_H_ */
1872 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp