linux-user: Add support for btrfs ioctls used to manage quota
[qemu.git] / docs / specs / rocker.txt
1 Rocker Network Switch Register Programming Guide
2 Copyright (c) Scott Feldman <sfeldma@gmail.com>
3 Copyright (c) Neil Horman <nhorman@tuxdriver.com>
4 Version 0.11, 12/29/2014
5
6 LICENSE
7 =======
8
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
18
19 SECTION 1: Introduction
20 =======================
21
22 Overview
23 --------
24
25 This document describes the hardware/software interface for the Rocker switch
26 device.  The intended audience is authors of OS drivers and device emulation
27 software.
28
29 Notations and Conventions
30 -------------------------
31
32 o In register descriptions, [n:m] indicates a range from bit n to bit m,
33 inclusive.
34 o Use of leading 0x indicates a hexadecimal number.
35 o Use of leading 0b indicates a binary number.
36 o The use of RSVD or Reserved indicates that a bit or field is reserved for
37 future use.
38 o Field width is in bytes, unless otherwise noted.
39 o Register are (R) read-only, (R/W) read/write, (W) write-only, or (COR) clear
40 on read
41 o TLV values in network-byte-order are designated with (N).
42
43
44 SECTION 2: PCI Configuration Registers
45 ======================================
46
47 PCI Configuration Space
48 -----------------------
49
50 Each switch instance registers as a PCI device with PCI configuration space:
51
52         offset  width   description             value
53         ---------------------------------------------
54         0x0     2       Vendor ID               0x1b36
55         0x2     2       Device ID               0x0006
56         0x4     4       Command/Status
57         0x8     1       Revision ID             0x01
58         0x9     3       Class code              0x2800
59         0xC     1       Cache line size
60         0xD     1       Latency timer
61         0xE     1       Header type
62         0xF     1       Built-in self test
63         0x10    4       Base address low
64         0x14    4       Base address high
65         0x18-28         Reserved
66         0x2C    2       Subsystem vendor ID     *
67         0x2E    2       Subsystem ID            *
68         0x30-38         Reserved
69         0x3C    1       Interrupt line
70         0x3D    1       Interrupt pin           0x00
71         0x3E    1       Min grant               0x00
72         0x3D    1       Max latency             0x00
73         0x40    1       TRDY timeout
74         0x41    1       Retry count
75         0x42    2       Reserved
76
77
78 * Assigned by sub-system implementation
79
80 SECTION 3: Memory-Mapped Register Space
81 =======================================
82
83 There are two memory-mapped BARs.  BAR0 maps device register space and is
84 0x2000 in size.  BAR1 maps MSI-X vector and PBA tables and is also 0x2000 in
85 size, allowing for 256 MSI-X vectors.
86
87 All registers are 4 or 8 bytes long.  It is assumed host software will access 4
88 byte registers with one 4-byte access, and 8 byte registers with either two
89 4-byte accesses or a single 8-byte access.  In the case of two 4-byte accesses,
90 access must be lower and then upper 4-bytes, in that order.
91
92 BAR0 device register space is organized as follows:
93
94         offset          description
95         ------------------------------------------------------
96         0x0000-0x000f   Bogus registers to catch misbehaving
97                         drivers.  Writes do nothing.  Reads
98                         back as 0xDEADBABE.
99         0x0010-0x00ff   Test registers
100         0x0300-0x03ff   General purpose registers
101         0x1000-0x1fff   Descriptor control
102
103 Holes in register space are reserved.  Writes to reserved registers do nothing.
104 Reads to reserved registers read back as 0.
105
106 No fancy stuff like write-combining is enabled on any of the registers.
107
108 BAR1 MSI-X register space is organized as follows:
109
110         offset          description
111         ------------------------------------------------------
112         0x0000-0x0fff   MSI-X vector table (256 vectors total)
113         0x1000-0x1fff   MSI-X PBA table
114
115
116 SECTION 4: Interrupts, DMA, and Endianness
117 ==========================================
118
119 PCI Interrupts
120 --------------
121
122 The device supports only MSI-X interrupts.  BAR1 memory-mapped region contains
123 the MSI-X vector and PBA tables, with support for up to 256 MSI-X vectors.
124
125 The vector assignment is:
126
127         vector          description
128         -----------------------------------------------------
129         0               Command descriptor ring completion
130         1               Event descriptor ring completion
131         2               Test operation completion
132         3               RSVD
133         4-255           Tx and Rx descriptor ring completion
134                           Tx vector is even
135                           Rx vector is odd
136
137 A MSI-X vector table entry is 16 bytes:
138
139         field           offset  width   description
140         -------------------------------------------------------------
141         lower_addr      0x0     4       [31:2] message address[31:2]
142                                         [1:0] Rsvd (4 byte alignment
143                                                     required)
144         upper_addr      0x4     4       [31:19] Rsvd
145                                         [14:0] message address[46:32]
146         data            0x8     4       message data[31:0]
147         control         0xc     4       [31:1] Rsvd
148                                         [0] mask (0 = enable,
149                                                   1 = masked)
150
151 Software should install the Interrupt Service Routine (ISR) before any ports
152 are enabled or any commands are issued on the command ring.
153
154 DMA Operations
155 --------------
156
157 DMA operations are used for packet DMA to/from the CPU, command and event
158 processing.  Command processing includes statistical counters and table dumps,
159 table insertion/deletion, and more.  Event processing provides an async
160 notification method for device-originating events.  Each DMA operation has a
161 set of control registers to manage a descriptor ring.  The descriptor rings are
162 allocated from contiguous host DMA-able memory and registers specify the rings
163 base address, size and current head and tail indices.  Software always writes
164 the head, and hardware always writes the tail.
165
166 The higher-order bit of DMA_DESC_COMP_ERR is used to mark hardware completion
167 of a descriptor.  Software will clear this bit when posting a descriptor to the
168 ring, and hardware will set this bit when the descriptor is complete.
169
170 Descriptor ring sizes must be a power of 2 and range from 2 to 64K entries.
171 Descriptor rings' base address must be 8-byte aligned.  Descriptors must be
172 packed within ring.  Each descriptor in each ring must also be aligned on an 8
173 byte boundary.  Each descriptor ring will have these registers:
174
175         DMA_DESC_xxx_BASE_ADDR, offset 0x1000 + (x * 32), 64-bit, (R/W)
176         DMA_DESC_xxx_SIZE, offset 0x1008 + (x * 32), 32-bit, (R/W)
177         DMA_DESC_xxx_HEAD, offset 0x100c + (x * 32), 32-bit, (R/W)
178         DMA_DESC_xxx_TAIL, offset 0x1010 + (x * 32), 32-bit, (R)
179         DMA_DESC_xxx_CTRL, offset 0x1014 + (x * 32), 32-bit, (W)
180         DMA_DESC_xxx_CREDITS, offset 0x1018 + (x * 32), 32-bit, (R/W)
181         DMA_DESC_xxx_RSVD1, offset 0x101c + (x * 32), 32-bit, (R/W)
182
183 Where x is descriptor ring index:
184
185         index           ring
186         --------------------
187         0               CMD
188         1               EVENT
189         2               TX (port 0)
190         3               RX (port 0)
191         4               TX (port 1)
192         5               RX (port 1)
193         .
194         .
195         .
196         124             TX (port 61)
197         125             RX (port 61)
198         126             Resv
199         127             Resv
200
201 Writing BASE_ADDR or SIZE will reset HEAD and TAIL to zero.  HEAD cannot be
202 written past TAIL.  To do so would wrap the ring.  An empty ring is when HEAD
203 == TAIL.  A full ring is when HEAD is one position behind TAIL.  Both HEAD and
204 TAIL increment and modulo wrap at the ring size.
205
206 CTRL register bits:
207
208         bit     name            description
209         ------------------------------------------------------------------------
210         [0]     CTRL_RESET      Reset the descriptor ring
211         [1:31]  Reserved
212
213 All descriptor types share some common fields:
214
215         field                   width   description
216         -------------------------------------------------------------------
217         DMA_DESC_BUF_ADDR       8       Phys addr of desc payload, 8-byte
218                                         aligned
219         DMA_DESC_COOKIE         8       Desc cookie for completion matching,
220                                         upper-most bit is reserved
221         DMA_DESC_BUF_SIZE       2       Desc payload size in bytes
222         DMA_DESC_TLV_SIZE       2       Desc payload total size in bytes
223                                         used for TLVs.  Must be <=
224                                         DMA_DESC_BUF_SIZE.
225         DMA_DESC_COMP_ERR       2       Completion status of associated
226                                         desc payload.  High order bit is
227                                         clear on new descs, toggled by
228                                         hw for completed items.
229
230 To support forward- and backward-compatibility, descriptor and completion
231 payloads are specified in TLV format.  Fields are packed with Type=field name,
232 Length=field length, and Value=field value.  Software will ignore unknown fields
233 filled in by the switch.  Likewise, the switch will ignore unknown fields
234 filled in by software.
235
236 Descriptor payload buffer is 8-byte aligned and TLVs are 8-byte aligned.  The
237 value within a TLV is also 8-byte aligned.  The (packed, 8 byte) TLV header is:
238
239         field   width   description
240         -----------------------------
241         type    4       TLV type
242         len     2       TLV value length
243         pad     2       Reserved
244
245 The alignment requirements for descriptors and TLVs are to avoid unaligned
246 access exceptions in software.  Note that the payload for each TLV is also
247 8 byte aligned.
248
249 Figure 1 shows an example descriptor buffer with two TLVs.
250
251                   <------- 8 bytes ------->
252
253   8-byte  +––––+  +–––––––––––+–––––+–––––+                     +–+
254   align           |   type    | len | pad |    TLV#1 hdr          |
255                   +–––––––––––+–––––+–––––+    (len=22)           |
256                   |                       |                       |
257                   |  value                |    TVL#1 value        |
258                   |                       |    (padded to 8-byte  |
259                   |                 +–––––+     alignment)        |
260                   |                 |/////|                       |
261    8-byte +––––+  +–––––––––––+–––––––––––+                       |
262    align          |   type    | len | pad |    TLV#2 hdr    DESC_BUF_SIZE
263                   +–––––+–––––+–––––+–––––+    (len=2)            |
264                   |value|/////////////////|    TLV#2 value        |
265                   +–––––+/////////////////|                       |
266                   |///////////////////////|                       |
267                   |///////////////////////|                       |
268                   |///////////////////////|                       |
269                   |////////unused/////////|                       |
270                   |////////space//////////|                       |
271                   |///////////////////////|                       |
272                   |///////////////////////|                       |
273                   |///////////////////////|                       |
274                   +–––––––––––––––––––––––+                     +–+
275
276                                 fig. 1
277
278 TLVs can be nested within the NEST TLV type.
279
280 Interrupt credits
281 ^^^^^^^^^^^^^^^^^
282
283 MSI-X vectors used for descriptor ring completions use a credit mechanism for
284 efficient device, PCIe bus, OS and driver operations.  Each descriptor ring has
285 a credit count which represents the number of outstanding descriptors to be
286 processed by the driver.  As the device marks descriptors complete, the credit
287 count is incremented.  As the driver processes those outstanding descriptors,
288 it returns credits back to the device.  This way, the device knows the driver's
289 progress and can make decisions about when to fire the next interrupt or not.
290 When the credit count is zero, and the first descriptors are posted for the
291 driver, a single interrupt is fired.  Once the interrupt is fired, the
292 interrupt is disabled (auto-masked*).  In response to the interrupt, the driver
293 will process descriptors and PIO write a returned credit value for that
294 descriptor ring.  If the driver returns all credits (the driver caught up with
295 the device and there is no outstanding work), then the interrupt is unmasked,
296 but not fired.  If only partial credits are returned, the interrupt remains
297 masked but the device generates an interrupt, signaling the driver that more
298 outstanding work is available.
299
300 (* this masking is unrelated to the MSI-X interrupt mask register)
301
302 Endianness
303 ----------
304
305 Device registers are hard-coded to little-endian (LE).  The driver should
306 convert to/from host endianness to LE for device register accesses.
307
308 Descriptors are LE.  Descriptor buffer TLVs will have LE type and length
309 fields, but the value field can either be LE or network-byte-order, depending
310 on context.  TLV values containing network packet data will be in network-byte
311 order.  A TLV value containing a field or mask used to compare against network
312 packet data is network-byte order.  For example, flow match fields (and masks)
313 are network-byte-order since they're matched directly, byte-by-byte, against
314 network packet data.  All non-network-packet TLV multi-byte values will be LE.
315
316 TLV values in network-byte-order are designated with (N).
317
318
319 SECTION 5: Test Registers
320 =========================
321
322 Rocker has several test registers to support troubleshooting register access,
323 interrupt generation, and DMA operations:
324
325         TEST_REG, offset 0x0010, 32-bit (R/W)
326         TEST_REG64, offset 0x0018, 64-bit (R/W)
327         TEST_IRQ, offset 0x0020, 32-bit (R/W)
328         TEST_DMA_ADDR, offset 0x0028, 64-bit (R/W)
329         TEST_DMA_SIZE, offset 0x0030, 32-bit (R/W)
330         TEST_DMA_CTRL, offset 0x0034, 32-bit (R/W)
331
332 Reads to TEST_REG and TEST_REG64 will read a value equal to twice the last
333 value written to the register.  The 32-bit and 64-bit versions are for testing
334 32-bit and 64-bit host accesses.
335
336 A vector can be written to TEST_IRQ and the device will generate an interrupt
337 for that vector.
338
339 To test basic DMA operations, allocate a DMA-able host buffer and put the
340 buffer address into TEST_DMA_ADDR and size into TEST_DMA_SIZE.  Then, write to
341 TEST_DMA_CTRL to manipulate the buffer contents.  TEST_DMA_CTRL operations are:
342
343         operation               value   description
344         -----------------------------------------------------------
345         TEST_DMA_CTRL_CLEAR     1       clear buffer
346         TEST_DMA_CTRL_FILL      2       fill buffer bytes with 0x96
347         TEST_DMA_CTRL_INVERT    4       invert bytes in buffer
348
349 Various buffer address and sizes should be tested to verify no address boundary
350 issue exists.  In particular, buffers that start on odd-8-byte boundary and/or
351 span multiple PAGE sizes should be tested.
352
353
354 SECTION 6: Ports
355 ================
356
357 Physical and Logical Ports
358 ------------------------------------
359
360 The switch supports up to 62 physical (front-panel) ports.  Register
361 PORT_PHYS_COUNT returns the actual number of physical ports available:
362
363         PORT_PHYS_COUNT, offset 0x0304, 32-bit, (R)
364
365 In addition to front-panel ports, the switch supports logical ports for
366 tunnels.
367
368 Front-panel ports and logical tunnel ports are mapped into a single 32-bit port
369 space.  A special CPU port is assigned port 0.  The front-panel ports are
370 mapped to ports 1-62.  A special loopback port is assigned port 63.  Logical
371 tunnel ports are assigned ports 0x0001000-0x0001ffff.
372 To summarize the port assignments:
373
374         port                    mapping
375         -------------------------------------------------------
376         0                       CPU port (for packets to/from host CPU)
377         1-62                    front-panel physical ports
378         63                      loopback port
379         64-0x0000ffff           RSVD
380         0x00010000-0x0001ffff   logical tunnel ports
381         0x00020000-0xffffffff   RSVD
382
383 Physical Port Mode
384 ------------------
385
386 Switch front-panel ports operate in a mode.  Currently, the only mode is
387 OF-DPA.  OF-DPA[1] mode is based on OpenFlow Data Plane Abstraction (OF-DPA)
388 Abstract Switch Specification, Version 1.0, from Broadcom Corporation.  To
389 set/get the mode for front-panel ports, see port settings, below.
390
391 Port Settings
392 -------------
393
394 Link status for all front-panel ports is available via PORT_PHYS_LINK_STATUS:
395
396         PORT_PHYS_LINK_STATUS, offset 0x0310, 64-bit, (R)
397
398         Value is port bitmap.  Bits 0 and 63 always read 0.  Bits 1-62
399         read 1 for link UP and 0 for link DOWN for respective front-panel ports.
400
401 Other properties for front-panel ports are available via DMA CMD descriptors:
402
403         Get PORT_SETTINGS descriptor:
404
405                 field           width   description
406                 ----------------------------------------------
407                 PORT_SETTINGS   2       CMD_GET
408                 PPORT           4       Physical port #
409
410         Get PORT_SETTINGS completion:
411
412                 field           width   description
413                 ----------------------------------------------
414                 PPORT           4       Physical port #
415                 SPEED           4       Current port interface speed, in Mbps
416                 DUPLEX          1       1 = Full, 0 = Half
417                 AUTONEG         1       1 = enabled, 0 = disabled
418                 MACADDR         6       Port MAC address
419                 MODE            1       0 = OF-DPA
420                 LEARNING        1       MAC address learning on port
421                                                 1 = enabled
422                                                 0 = disabled
423                 PHYS_NAME       <var>   Physical port name (string)
424
425         Set PORT_SETTINGS descriptor:
426
427                 field           width   description
428                 ----------------------------------------------
429                 PORT_SETTINGS   2       CMD_SET
430                 PPORT           4       Physical port #
431                 SPEED           4       Port interface speed, in Mbps
432                 DUPLEX          1       1 = Full, 0 = Half
433                 AUTONEG         1       1 = enabled, 0 = disabled
434                 MACADDR         6       Port MAC address
435                 MODE            1       0 = OF-DPA
436
437 Port Enable
438 -----------
439
440 Front-panel ports are initially disabled, which means port ingress and egress
441 packets will be dropped.  To enable or disable a port, use PORT_PHYS_ENABLE:
442
443         PORT_PHYS_ENABLE: offset 0x0318, 64-bit, (R/W)
444
445         Value is bitmap of first 64 ports.  Bits 0 and 63 are ignored
446         and always read as 0.  Write 1 to enable port; write 0 to disable it.
447         Default is 0.
448
449
450 SECTION 7: Switch Control
451 =========================
452
453 This section covers switch-wide register settings.
454
455 Control
456 -------
457
458 This register is used for low level control of the switch.
459
460         CONTROL: offset 0x0300, 32-bit, (W)
461
462         bit     name            description
463         ------------------------------------------------------------------------
464         [0]     CONTROL_RESET   If set, device will perform reset
465         [1:31]  Reserved
466
467 Switch ID
468 ---------
469
470 The switch has a SWITCH_ID to be used by software to uniquely identify the
471 switch:
472
473         SWITCH_ID: offset 0x0320, 64-bit, (R)
474
475         Value is opaque to switch software and no special encoding is implied.
476
477
478 SECTION 8: Events
479 =================
480
481 Non-I/O asynchronous events from the device are notified to the host using the
482 event ring.  The TLV structure for events is:
483
484         field           width   description
485         ---------------------------------------------------
486         TYPE            4       Event type, one of:
487                                         1: LINK_CHANGED
488                                         2: MAC_VLAN_SEEN
489         INFO            <nest>  Event info (details below)
490
491 Link Changed Event
492 ------------------
493
494 When link status changes on a physical port, this event is generated.
495
496         field           width   description
497         ---------------------------------------------------
498         INFO            <nest>
499           PPORT         4       Physical port
500           LINKUP        1       Link status:
501                                         0: down
502                                         1: up
503
504 MAC VLAN Seen Event
505 -------------------
506
507 When a packet ingresses on a port and the source MAC/VLAN isn't known to the
508 device, the device will generate this event.  In response to the event, the
509 driver should install to the device the MAC/VLAN on the port into the bridge
510 table.  Once installed, the MAC/VLAN is known on the port and this event will
511 no longer be generated.
512
513         field           width   description
514         ---------------------------------------------------
515         INFO            <nest>
516           PPORT         4       Physical port
517           MAC           6       MAC address
518           VLAN          2       VLAN ID
519
520
521 SECTION 9: CPU Packet Processing
522 ================================
523
524 Ingress packets directed to the host CPU for further processing are delivered
525 in the DMA RX ring.  Likewise, host CPU originating packets destined to egress
526 on switch ports are scheduled by software using the DMA TX ring.
527
528 Tx Packet Processing
529 --------------------
530
531 Software schedules packets for egress on switch ports using the DMA TX ring.  A
532 TX descriptor buffer describes the packet location and size in host DMA-able
533 memory, the destination port, and any hardware-offload functions (such as L3
534 payload checksum offload).  Software then bumps the descriptor head to signal
535 hardware of new Tx work.  In response, hardware will DMA read Tx descriptors up
536 to head, DMA read descriptor buffer and packet data, perform offloading
537 functions, and finally frame packet on wire (network).  Once packet processing
538 is complete, hardware will writeback status to descriptor(s) to signal to
539 software that Tx is complete and software resources (e.g. skb) backing packet
540 can be released.
541
542 Figure 2 shows an example 3-fragment packet queued with one Tx descriptor.  A
543 TLV is used for each packet fragment.
544
545                                                    pkt frag 1
546                                                    +–––––––+  +–+
547                                                +–––+       |    |
548                                  desc buf      |   |       |    |
549                                 +––––––––+     |   |       |    |
550                 Tx ring     +–––+        +–––––+   |       |    |
551               +–––––––––+   |   |  TLVs  |         +–––––––+    |
552               |         +–––+   +––––––––+         pkt frag 2   |
553               | desc 0  |       |        +–––––+   +–––––––+    |
554               +–––––––––+       |  TLVs  |     +–––+       |    |
555         head+–+         |       +––––––––+         |       |    |
556               | desc 1  |       |        +–––––+   +–––––––+    |pkt
557               +–––––––––+       |  TLVs  |     |                |
558               |         |       +––––––––+     |   pkt frag 3   |
559               |         |                      |   +–––––––+    |
560               +–––––––––+                      +–––+       |    |
561               |         |                          |       |    |
562               |         |                          |       |    |
563               +–––––––––+                          |       |    |
564               |         |                          |       |    |
565               |         |                          |       |    |
566               +–––––––––+                          |       |    |
567               |         |                          +–––––––+  +–+
568               |         |
569               +–––––––––+
570
571                                 fig 2.
572
573 The TLVs for Tx descriptor buffer are:
574
575         field                   width   description
576         ---------------------------------------------------------------------
577         PPORT                   4       Destination physical port #
578         TX_OFFLOAD              1       Hardware offload modes:
579                                           0: no offload
580                                           1: insert IP csum (ipv4 only)
581                                           2: insert TCP/UDP csum
582                                           3: L3 csum calc and insert
583                                              into csum offset (TX_L3_CSUM_OFF)
584                                             16-bit 1's complement csum value.
585                                              IPv4 pseudo-header and IP
586                                              already calculated by OS
587                                            and inserted.
588                                           4: TSO (TCP Segmentation Offload)
589         TX_L3_CSUM_OFF          2       For L3 csum offload mode, the offset,
590                                         from the beginning of the packet,
591                                         of the csum field in the L3 header
592         TX_TSO_MSS              2       For TSO offload mode, the
593                                         Maximum Segment Size in bytes
594         TX_TSO_HDR_LEN          2       For TSO offload mode, the
595                                         length of ethernet, IP, and
596                                         TCP/UDP headers, including IP
597                                         and TCP options.
598         TX_FRAGS                <array> Packet fragments
599           TX_FRAG               <nest>  Packet fragment
600             TX_FRAG_ADDR        8       DMA address of packet fragment
601             TX_FRAG_LEN         2       Packet fragment length
602
603 Possible status return codes in descriptor on completion are:
604
605         DESC_COMP_ERR   reason
606         --------------------------------------------------------------------
607         0               OK
608         -ROCKER_ENXIO   address or data read err on desc buf or packet
609                         fragment
610         -ROCKER_EINVAL  bad pport or TSO or csum offloading error
611         -ROCKER_ENOMEM  no memory for internal staging tx fragment
612
613 Rx Packet Processing
614 --------------------
615
616 For packets ingressing on switch ports that are not forwarded by the switch but
617 rather directed to the host CPU for further processing are delivered in the DMA
618 RX ring.  Rx descriptor buffers are allocated by software and placed on the
619 ring.  Hardware will fill Rx descriptor buffers with packet data, write the
620 completion, and signal to software that a new packet is ready.  Since Rx packet
621 size is not known a-priori, the Rx descriptor buffer must be allocated for
622 worst-case packet size.  A single Rx descriptor will contain the entire Rx
623 packet data in one RX_FRAG.  Other Rx TLVs describe and hardware offloads
624 performed on the packet, such as checksum validation.
625
626 The TLVs for Rx descriptor buffer are:
627
628         field           width   description
629         ---------------------------------------------------
630         PPORT           4       Source physical port #
631         RX_FLAGS        2       Packet parsing flags:
632                                   (1 << 0): IPv4 packet
633                                   (1 << 1): IPv6 packet
634                                   (1 << 2): csum calculated
635                                   (1 << 3): IPv4 csum good
636                                   (1 << 4): IP fragment
637                                   (1 << 5): TCP packet
638                                   (1 << 6): UDP packet
639                                   (1 << 7): TCP/UDP csum good
640                                   (1 << 8): Offload forward
641         RX_CSUM         2       IP calculated checksum:
642                                   IPv4: IP payload csum
643                                   IPv6: header and payload csum
644                                 (Only valid is RX_FLAGS:csum calc is set)
645         RX_FRAG_ADDR    8       DMA address of packet fragment
646         RX_FRAG_MAX_LEN 2       Packet maximum fragment length
647         RX_FRAG_LEN     2       Actual packet fragment length after receive
648
649 Offload forward RX_FLAG indicates the device has already forwarded the packet
650 so the host CPU should not also forward the packet.
651
652 Possible status return codes in descriptor on completion are:
653
654         DESC_COMP_ERR   reason
655         --------------------------------------------------------------------
656         0               OK
657         -ROCKER_ENXIO   address or data read err on desc buf
658         -ROCKER_ENOMEM  no memory for internal staging desc buf
659         -ROCKER_EMSGSIZE Rx descriptor buffer wasn't big enough to contain
660                         packet data TLV and other TLVs.
661
662
663 SECTION 10: OF-DPA Mode
664 ======================
665
666 OF-DPA mode allows the switch to offload flow packet processing functions to
667 hardware.  An OpenFlow controller would communicate with an OpenFlow agent
668 installed on the switch.  The OpenFlow agent would (directly or indirectly)
669 communicate with the Rocker switch driver, which in turn would program switch
670 hardware with flow functionality, as defined in OF-DPA.  The block diagram is:
671
672                 +–––––––––––––––----–––+
673                 |        OF            |
674                 |  Remote Controller   |
675                 +––––––––+––----–––––––+
676                          |
677                          |
678                 +––––––––+–––––––––+
679                 |       OF         |
680                 |   Local Agent    |
681                 +––––––––––––––––––+
682                 |                  |
683                 |   Rocker Driver  |
684                 +––––––––––––––––––+
685                     <this spec>
686                 +––––––––––––––––––+
687                 |                  |
688                 |   Rocker Switch  |
689                 +––––––––––––––––––+
690
691 To participate in flow functions, ports must be configure for OF-DPA mode
692 during switch initialization.
693
694 OF-DPA Flow Table Interface
695 ---------------------------
696
697 There are commands to add, modify, delete, and get stats of flow table entries.
698 The commands are issued using the DMA CMD descriptor ring.  The following
699 commands are defined:
700
701         CMD_ADD:                add an entry to flow table
702         CMD_MOD:                modify an entry in flow table
703         CMD_DEL:                delete an entry from flow table
704         CMD_GET_STATS:          get stats for flow entry
705
706 TLVs for add and modify commands are:
707
708         field                   width   description
709         ----------------------------------------------------
710         OF_DPA_CMD              2       CMD_[ADD|MOD]
711         OF_DPA_TBL              2       Flow table ID
712                                           0: ingress port
713                                           10: vlan
714                                           20: termination mac
715                                           30: unicast routing
716                                           40: multicast routing
717                                           50: bridging
718                                           60: ACL policy
719         OF_DPA_PRIORITY         4       Flow priority
720         OF_DPA_HARDTIME         4       Hard timeout for flow
721         OF_DPA_IDLETIME         4       Idle timeout for flow
722         OF_DPA_COOKIE           8       Cookie
723
724 Additional TLVs based on flow table ID:
725
726 Table ID 0: ingress port
727
728         field                   width   description
729         ----------------------------------------------------
730         OF_DPA_IN_PPORT         4       ingress physical port number
731         OF_DPA_GOTO_TBL         2       goto table ID; zero to drop
732
733 Table ID 10: vlan
734
735         field                   width   description
736         ----------------------------------------------------
737         OF_DPA_IN_PPORT         4       ingress physical port number
738         OF_DPA_VLAN_ID          2 (N)   vlan ID
739         OF_DPA_VLAN_ID_MASK     2 (N)   vlan ID mask
740         OF_DPA_GOTO_TBL         2       goto table ID; zero to drop
741         OF_DPA_NEW_VLAN_ID      2 (N)   new vlan ID
742
743 Table ID 20: termination mac
744
745         field                   width   description
746         ----------------------------------------------------
747         OF_DPA_IN_PPORT         4       ingress physical port number
748         OF_DPA_IN_PPORT_MASK    4       ingress physical port number mask
749         OF_DPA_ETHERTYPE        2 (N)   must be either 0x0800 or 0x86dd
750         OF_DPA_DST_MAC          6 (N)   destination MAC
751         OF_DPA_DST_MAC_MASK     6 (N)   destination MAC mask
752         OF_DPA_VLAN_ID          2 (N)   vlan ID
753         OF_DPA_VLAN_ID_MASK     2 (N)   vlan ID mask
754         OF_DPA_GOTO_TBL         2       only acceptable values are
755                                         unicast or multicast routing
756                                         table IDs
757         OF_DPA_OUT_PPORT        2       if specified, must be
758                                         controller, set zero otherwise
759
760 Table ID 30: unicast routing
761
762         field                   width   description
763         ----------------------------------------------------
764         OF_DPA_ETHERTYPE        2 (N)   must be either 0x0800 or 0x86dd
765         OF_DPA_DST_IP           4 (N)   destination IPv4 address.
766                                         Must be unicast address
767         OF_DPA_DST_IP_MASK      4 (N)   IP mask.  Must be prefix mask
768         OF_DPA_DST_IPV6         16 (N)  destination IPv6 address.
769                                         Must be unicast address
770         OF_DPA_DST_IPV6_MASK    16 (N)  IPv6 mask. Must be prefix mask
771         OF_DPA_GOTO_TBL         2       goto table ID; zero to drop
772         OF_DPA_GROUP_ID         4       data for GROUP action must
773                                         be an L3 Unicast group entry
774
775 Table ID 40: multicast routing
776
777         field                   width   description
778         ----------------------------------------------------
779         OF_DPA_ETHERTYPE        2 (N)   must be either 0x0800 or 0x86dd
780         OF_DPA_VLAN_ID          2 (N)   vlan ID
781         OF_DPA_SRC_IP           4 (N)   source IPv4. Optional,
782                                         can contain IPv4 address,
783                                         must be completely masked
784                                         if not used
785         OF_DPA_SRC_IP_MASK      4 (N)   IP Mask
786         OF_DPA_DST_IP           4 (N)   destination IPv4 address.
787                                         Must be multicast address
788         OF_DPA_SRC_IPV6         16 (N)  source IPv6 Address. Optional.
789                                         Can contain IPv6 address,
790                                         must be completely masked
791                                         if not used
792         OF_DPA_SRC_IPV6_MASK    16 (N)  IPv6 mask.
793         OF_DPA_DST_IPV6         16 (N)  destination IPv6 Address. Must
794                                         be multicast address
795                                         Must be multicast address
796         OF_DPA_GOTO_TBL         2       goto table ID; zero to drop
797         OF_DPA_GROUP_ID         4       data for GROUP action must
798                                         be an L3 multicast group entry
799
800 Table ID 50: bridging
801
802         field                   width   description
803         ----------------------------------------------------
804         OF_DPA_VLAN_ID          2 (N)   vlan ID
805         OF_DPA_TUNNEL_ID        4       tunnel ID
806         OF_DPA_DST_MAC          6 (N)   destination MAC
807         OF_DPA_DST_MAC_MASK     6 (N)   destination MAC mask
808         OF_DPA_GOTO_TBL         2       goto table ID; zero to drop
809         OF_DPA_GROUP_ID         4       data for GROUP action must
810                                         be a L2 Interface, L2
811                                         Multicast, L2 Flood,
812                                         or L2 Overlay group entry
813                                         as appropriate
814         OF_DPA_TUNNEL_LPORT     4       unicast Tenant Bridging
815                                         flows specify a tunnel
816                                         logical port ID
817         OF_DPA_OUT_PPORT        2       data for OUTPUT action,
818                                         restricted to CONTROLLER,
819                                         set to 0 otherwise
820
821 Table ID 60: acl policy
822
823         field                   width   description
824         ----------------------------------------------------
825         OF_DPA_IN_PPORT         4       ingress physical port number
826         OF_DPA_IN_PPORT_MASK    4       ingress physical port number mask
827         OF_DPA_ETHERTYPE        2 (N)   ethertype
828         OF_DPA_VLAN_ID          2 (N)   vlan ID
829         OF_DPA_VLAN_ID_MASK     2 (N)   vlan ID mask
830         OF_DPA_VLAN_PCP         2 (N)   vlan Priority Code Point
831         OF_DPA_VLAN_PCP_MASK    2 (N)   vlan Priority Code Point mask
832         OF_DPA_SRC_MAC          6 (N)   source MAC
833         OF_DPA_SRC_MAC_MASK     6 (N)   source MAC mask
834         OF_DPA_DST_MAC          6 (N)   destination MAC
835         OF_DPA_DST_MAC_MASK     6 (N)   destination MAC mask
836         OF_DPA_TUNNEL_ID        4       tunnel ID
837         OF_DPA_SRC_IP           4 (N)   source IPv4. Optional,
838                                         can contain IPv4 address,
839                                         must be completely masked
840                                         if not used
841         OF_DPA_SRC_IP_MASK      4 (N)   IP Mask
842         OF_DPA_DST_IP           4 (N)   destination IPv4 address.
843                                         Must be multicast address
844         OF_DPA_DST_IP_MASK      4 (N)   IP Mask
845         OF_DPA_SRC_IPV6         16 (N)  source IPv6 Address. Optional.
846                                         Can contain IPv6 address,
847                                         must be completely masked
848                                         if not used
849         OF_DPA_SRC_IPV6_MASK    16 (N)  IPv6 mask
850         OF_DPA_DST_IPV6         16 (N)  destination IPv6 Address. Must
851                                         be multicast address.
852         OF_DPA_DST_IPV6_MASK    16 (N)  IPv6 mask
853         OF_DPA_SRC_ARP_IP       4 (N)   source IPv4 address in the ARP
854                                         payload.  Only used if ethertype
855                                         == 0x0806.
856         OF_DPA_SRC_ARP_IP_MASK  4 (N)   IP Mask
857         OF_DPA_IP_PROTO         1       IP protocol
858         OF_DPA_IP_PROTO_MASK    1       IP protocol mask
859         OF_DPA_IP_DSCP          1       DSCP
860         OF_DPA_IP_DSCP_MASK     1       DSCP mask
861         OF_DPA_IP_ECN           1       ECN
862         OF_DPA_IP_ECN_MASK              1       ECN mask
863         OF_DPA_L4_SRC_PORT      2 (N)   L4 source port, only for
864                                         TCP, UDP, or SCTP
865         OF_DPA_L4_SRC_PORT_MASK 2 (N)   L4 source port mask
866         OF_DPA_L4_DST_PORT      2 (N)   L4 source port, only for
867                                         TCP, UDP, or SCTP
868         OF_DPA_L4_DST_PORT_MASK 2 (N)   L4 source port mask
869         OF_DPA_ICMP_TYPE        1       ICMP type, only if IP
870                                         protocol is 1
871         OF_DPA_ICMP_TYPE_MASK   1       ICMP type mask
872         OF_DPA_ICMP_CODE        1       ICMP code
873         OF_DPA_ICMP_CODE_MASK   1       ICMP code mask
874         OF_DPA_IPV6_LABEL       4 (N)   IPv6 flow label
875         OF_DPA_IPV6_LABEL_MASK  4 (N)   IPv6 flow label mask
876         OF_DPA_GROUP_ID         4       data for GROUP action
877         OF_DPA_QUEUE_ID_ACTION  1       write the queue ID
878         OF_DPA_NEW_QUEUE_ID     1       queue ID
879         OF_DPA_VLAN_PCP_ACTION  1       write the VLAN priority
880         OF_DPA_NEW_VLAN_PCP     1       VLAN priority
881         OF_DPA_IP_DSCP_ACTION   1       write the DSCP
882         OF_DPA_NEW_IP_DSCP      1       new DSCP
883         OF_DPA_TUNNEL_LPORT     4       restrct to valid tunnel
884                                         logical port, set to 0
885                                         otherwise.
886         OF_DPA_OUT_PPORT        2       data for OUTPUT action,
887                                         restricted to CONTROLLER,
888                                         set to 0 otherwise
889         OF_DPA_CLEAR_ACTIONS    4       if 1 packets matching flow are
890                                         dropped (all other instructions
891                                         ignored)
892
893 TLVs for flow delete and get stats command are:
894
895         field                   width   description
896         ---------------------------------------------------
897         OF_DPA_CMD              2       CMD_[DEL|GET_STATS]
898         OF_DPA_COOKIE           8       Cookie
899
900 On completion of get stats command, the descriptor buffer is written back with
901 the following TLVs:
902
903         field                   width   description
904         ---------------------------------------------------
905         OF_DPA_STAT_DURATION    4       Flow duration
906         OF_DPA_STAT_RX_PKTS     8       Received packets
907         OF_DPA_STAT_TX_PKTS     8       Transmit packets
908
909 Possible status return codes in descriptor on completion are:
910
911         DESC_COMP_ERR   command                 reason
912         --------------------------------------------------------------------
913         0               all                     OK
914         -ROCKER_EFAULT  all                     head or tail index outside
915                                                 of ring
916         -ROCKER_ENXIO   all                     address or data read err on
917                                                 desc buf
918         -ROCKER_EMSGSIZE GET_STATS              cmd descriptor buffer wasn't
919                                                 big enough to contain write-back
920                                                 TLVs
921         -ROCKER_EINVAL  all                     invalid parameters passed in
922         -ROCKER_EEXIST  ADD                     entry already exists
923         -ROCKER_ENOSPC  ADD                     no space left in flow table
924         -ROCKER_ENOENT  MOD|DEL|GET_STATS       cookie invalid
925
926 Group Table Interface
927 ---------------------
928
929 There are commands to add, modify, delete, and get stats of group table
930 entries.  The commands are issued using the DMA CMD descriptor ring.  The
931 following commands are defined:
932
933         CMD_ADD:                add an entry to group table
934         CMD_MOD:                modify an entry in group table
935         CMD_DEL:                delete an entry from group table
936         CMD_GET_STATS:          get stats for group entry
937
938 TLVs for add and modify commands are:
939
940         field                   width   description
941         -----------------------------------------------------------
942         FLOW_GROUP_CMD          2       CMD_[ADD|MOD]
943         FLOW_GROUP_ID           2       Flow group ID
944         FLOW_GROUP_TYPE         1       Group type:
945                                           0: L2 interface
946                                           1: L2 rewrite
947                                           2: L3 unicast
948                                           3: L2 multicast
949                                           4: L2 flood
950                                           5: L3 interface
951                                           6: L3 multicast
952                                           7: L3 ECMP
953                                           8: L2 overlay
954         FLOW_VLAN_ID            2       Vlan ID (types 0, 3, 4, 6)
955         FLOW_L2_PORT            2       Port (types 0)
956         FLOW_INDEX              4       Index (all types but 0)
957         FLOW_OVERLAY_TYPE       1       Overlay sub-type (type 8):
958                                           0: Flood unicast tunnel
959                                           1: Flood multicast tunnel
960                                           2: Multicast unicast tunnel
961                                           3: Multicast multicast tunnel
962         FLOW_GROUP_ACTION               nest
963           FLOW_GROUP_ID         2       next group ID in chain (all
964                                         types except 0)
965           FLOW_OUT_PORT         4       egress port (types 0, 8)
966           FLOW_POP_VLAN_TAG     1       strip outer VLAN tag (type 1
967                                         only)
968           FLOW_VLAN_ID          2       (types 1, 5)
969           FLOW_SRC_MAC          6       (types 1, 2, 5)
970           FLOW_DST_MAC          6       (types 1, 2)
971
972 TLVs for flow delete and get stats command are:
973
974         field                   width   description
975         -----------------------------------------------------------
976         FLOW_GROUP_CMD          2       CMD_[DEL|GET_STATS]
977         FLOW_GROUP_ID           2       Flow group ID
978
979 On completion of get stats command, the descriptor buffer is written back with
980 the following TLVs:
981
982         field                   width   description
983         ---------------------------------------------------
984         FLOW_GROUP_ID           2       Flow group ID
985         FLOW_STAT_DURATION      4       Flow duration
986         FLOW_STAT_REF_COUNT     4       Flow reference count
987         FLOW_STAT_BUCKET_COUNT  4       Flow bucket count
988
989 Possible status return codes in descriptor on completion are:
990
991         DESC_COMP_ERR   command                 reason
992         --------------------------------------------------------------------
993         0               all                     OK
994         -ROCKER_EFAULT  all                     head or tail index outside
995                                                 of ring
996         -ROCKER_ENXIO   all                     address or data read err on
997                                                 desc buf
998         -ROCKER_ENOSPC  GET_STATS               cmd descriptor buffer wasn't
999                                                 big enough to contain write-back
1000                                                 TLVs
1001         -ROCKER_EINVAL  ADD|MOD                 invalid parameters passed in
1002         -ROCKER_EEXIST  ADD                     entry already exists
1003         -ROCKER_ENOSPC  ADD                     no space left in flow table
1004         -ROCKER_ENOENT  MOD|DEL|GET_STATS       group ID invalid
1005         -ROCKER_EBUSY   DEL                     group reference count non-zero
1006         -ROCKER_ENODEV  ADD                     next group ID doesn't exist
1007
1008
1009
1010 References
1011 ==========
1012
1013 [1] OpenFlow Data Plane Abstraction (OF-DPA) Abstract Switch Specification,
1014 Version 1.0, from Broadcom Corporation, February 21, 2014.