docs/ecpri_ddp_profile.rst

   1 ..    Copyright (c) 2019-2022 Intel
   2 ..
   3 ..  Licensed under the Apache License, Version 2.0 (the "License");
   4 ..  you may not use this file except in compliance with the License.
   5 ..  You may obtain a copy of the License at
   6 ..
   7 ..      http://www.apache.org/licenses/LICENSE-2.0
   8 ..
   9 ..  Unless required by applicable law or agreed to in writing, software
  10 ..  distributed under the License is distributed on an "AS IS" BASIS,
  11 ..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 ..  See the License for the specific language governing permissions and
  13 ..  limitations under the License.
  14
  15
  16 eCPRI DDP Profile for Columbiaville (Experimental Feature)
  17 ==========================================================
  18
  19 .. _introduction-3:
  20
  21 Introduction
  22 ============
  23
  24 The Intel® Ethernet 800 Series is the next generation of Intel® Ethernet
  25 Controllers and Network Adapters. The Intel® Ethernet 800 Series is
  26 designed with an enhanced programmable pipeline, allowing deeper and
  27 more diverse protocol header processing. This on-chip capability is
  28 called Dynamic Device Personalization (DDP). In the Intel® Ethernet 800
  29 Series, a DDP profile is loaded dynamically on driver load per device.
  30
  31 A general-purpose DDP package is automatically installed with all
  32 supported Intel® Ethernet 800 Series drivers on Windows*, ESX*,
  33 FreeBSD*, and Linux\* operating systems, including those provided by the
  34 Data Plane Development Kit (DPDK). This general-purpose DDP package is
  35 known as the OS-default package.
  36
  37 For more information on DDP technology in the Intel® Ethernet 800 Series
  38 products and the OS-default package, refer to the Intel® Ethernet
  39 Controller E810 Dynamic Device Personalization (DDP) Technology Guide,
  40 published here: https://cdrdv2.intel.com/v1/dl/getContent/617015.
  41
  42 This document describes an optional DDP package targeted towards the
  43 needs of Wireless and Edge (Wireless Edge) customers. This Wireless Edge
  44 DDP package (v1.3.22.101) adds support for eCPRI protocols in addition
  45 to the protocols in the OS-default package. The Wireless Edge DDP
  46 package is supported by DPDK.
  47
  48 Starting from DPDK 21.02 drivers and in the future will also be
  49 supported by the Intel® Ethernet 800 Series ice driver. on Linux
  50 operating systems. The Wireless DDP Package can be loaded on all Intel®
  51 Ethernet 800 Series devices, or different packages can be selected via
  52 serial number per device.
  53
  54 Software/Firmware Requirements
  55 ==============================
  56
  57 The specific DDP package requires certain firmware and DPDK versions and
  58 Intel® Ethernet 800 Series firmware/NVM versions. Support for eCPRI DDP
  59 profile included starting from Columbiaville (CVL)release 2.4 or later.
  60 This section is for general information purposes as the binaries provided
  61 for this FlexRan release in github.com are built with DPDK 20.11.3 and the
  62 mix and match of binaries is not supported.
  63 The required DPDK version contains the support of loading the specific
  64 Wireless Edge DDP package.
  65
  66 -  Intel® Ethernet 800 Series Linux Driver (ice) — 1.4.0 (or later)
  67
  68 -  Wireless Edge DDP Package version (ice_wireless_edge) — 1.3.22.101
  69
  70 -  Intel® Ethernet 800 Series firmware version — 1.5.4.2 (or later)
  71
  72 -  Intel® Ethernet 800 Series NVM version — 2.4 (or later)
  73
  74 -  DPDK version— 21.02 (or later)
  75
  76 -  For FlexRAN release oran_f_release_v1.0, corresponding support
  77    of CVL 2.4 driver pack and DPDK 21.02 is “experimental” and subject
  78    to additional testing and potential changes.
  79
  80 DDP Package Setup
  81 =================
  82
  83 The Intel® Ethernet 800 Series Comms DDP package supports only
  84 Linux-based operating systems currently.
  85
  86 Currently, the eCPRI is fully supported only by DPDK 21.02. It can be
  87 loaded either by DPDK or the Intel® Ethernet 800 Series Linux base
  88 driver.
  89
  90 Wireless Edge DDP Package
  91 =========================
  92
  93 For details on how to set up DPDK, refer to Intel® Ethernet Controller
  94 E810 Data Plane Development Kit (DPDK) Configuration Guide (Doc ID:
  95 633514).
  96
  97 There are two methods where DDP package can be loaded and used under
  98 DPDK (see Section C.3.2  and
  99 Section C.3.2 ). For both methods, the
 100 user must obtain the ice_wireless_edge-1.3.22.101.pkg or later from
 101 Intel (please contact your Intel representative for more information)
 102
 103 Option 1: *ice* Linux Base Driver
 104 =================================
 105
 106 The first option is to have the ice Linux base driver load the package.
 107
 108 The *ice* Linux base driver looks for the symbolic link
 109 *intel/ice/ddp/ice.pkg* under the default firmware search path, checking
 110 the following folders in order:
 111
 112 -  */lib/firmware/updates/*
 113
 114 -  */lib/firmware/*
 115
 116 To install the Comms package, copy the extracted .pkg file and its
 117 symbolic link to */lib/firmware/updates/intel/ice/ddp* as follows, and
 118 reload the ice driver::
 119
 120   # cp /usr/tmp/ice_wireless_edge-1.3.22.101.pkg /lib/firmware/updates/intel/ice/ddp/
 121   # ln -sf /lib/firmware/updates/intel/ice/ddp/ice_wireless_edge-1.3.22.101.pkg /lib/firmware/updates/intel/ice/ddp/ice.pkg
 122   # modprobe -r irdma
 123   # modprobe -r ice
 124   # modprobe ice
 125
 126
 127 The kernel message log (*dmesg*) indicates status of package loading in
 128 the system. If the driver successfully finds and loads the DDP package,
 129 *dmesg* indicates that the DDP package successfully loaded. If not, the
 130 driver transitions to safe mode.
 131
 132 Once the driver loads the package, the user can unbind the *ice* driver
 133 from a desired port on the device so that DPDK can utilize the port.
 134
 135 The following example unbinds Port 0 and Port 1 of device on Bus 6,
 136 Device 0. Then, the port is bound to either igb_uio or vfio-pci. ::
 137
 138   # ifdown <interface>
 139   # dpdk-devbind -u 06:00.0
 140   # dpdk-devbind -u 06:00.1
 141   # dpdk-devbind -b igb_uio 06:00.0 06:00.1
 142
 143 Option 2: DPDK Driver Only
 144 ==========================
 145
 146 The second method is if the system does not have the *ice* driver
 147 installed. In this case, the user can download the DDP package from the
 148 Intel download center and extract the zip file to obtain the package
 149 (*.pkg*) file. Similar to the Linux base driver, the DPDK driver looks
 150 for the *intel/ddp/ice.pkg* symbolic link in the kernel default firmware
 151 search path */lib/firmware/updates and /lib/firmware/*.
 152
 153 Copy the extracted DDP *.pkg* file and its symbolic link to
 154 */lib/firmware/intel/ice/ddp*, as follows. ::
 155
 156   # cp /usr/tmp/ice_wireless_edge-1.3.22.101 /lib/firmware/intel/ice/ddp/
 157   # cp /usr/tmp/ice.pkg /lib/firmware/intel/ice/ddp/
 158
 159 When DPDK driver loads, it looks for *ice.pkg* to load. If the file
 160 exists, the driver downloads it into the device. If not, the driver
 161 transitions into safe mode.
 162
 163 Loading DDP Package to a Specific Intel® Ethernet 800 Series Device
 164 ===================================================================
 165
 166 On a host system running with multiple Intel® Ethernet 800 Series
 167 devices, there is sometimes a need to load a specific DDP package on a
 168 selected device while loading a different package on the remaining
 169 devices.
 170
 171 The Intel® Ethernet 800 Series Linux base driver and DPDK driver can
 172 both load a specific DDP package to a selected adapter based on the
 173 device's serial number. The driver does this by looking for a specific
 174 symbolic link package filename containing the selected device's serial
 175 number.
 176
 177 The following example illustrates how a user can load a specific package
 178 (e.g., *ice_wireless_edge-1.3.22.101*) on the device of Bus 6.
 179
 180 1. Find device serial number.
 181
 182 ..
 183
 184 To view bus, device, and function of all Intel® Ethernet 800 Series
 185 Network Adapters in the system:::
 186
 187   # lspci | grep -i Ethernet | grep -i Intel
 188   06:00.0 Ethernet controller: Intel Corporation Ethernet Controller E810-C for QSFP (rev 01)
 189   06:00.1 Ethernet controller: Intel Corporation Ethernet Controller E810-C for QSFP (rev 01)
 190   82:00.0 Ethernet controller: Intel Corporation Ethernet Controller E810-C for SFP (rev 01)
 191   82:00.1 Ethernet controller: Intel Corporation Ethernet Controller E810-C for SFP (rev 01)
 192   82:00.2 Ethernet controller: Intel Corporation Ethernet Controller E810-C for SFP (rev 01)
 193   82:00.3 Ethernet controller: Intel Corporation Ethernet Controller E810-C for SFP (rev 01)
 194
 195 Use the **lspci** command to obtain the selected device serial
 196 number::
 197
 198   # lspci -vv -s 06:00.0 \| grep -i Serial
 199   Capabilities: [150 v1] Device Serial Number 35-11-a0-ff-ff-ca-05-68
 200
 201 Or, fully parsed without punctuation::
 202
 203   # lspci -vv -s 06:00.0 \|grep Serial \|awk '{print $7}'|sed s/-//g
 204   3511a0ffffca0568
 205
 206 2. Rename the package file with the device serial number in the name.
 207
 208 ..
 209
 210 Copy the specific package over to /lib/firmware/updates/intel/ice/ddp
 211 (or /lib/firmware/intel/ice/ ddp) and create a symbolic link with the
 212 serial number linking to the package, as shown. The specific symbolic
 213 link filename starts with “ice-” followed by the device serial in
 214 lower case without dash ('-'). ::
 215
 216   # ln -s
 217   /lib/firmware/updates/intel/ice/ddp/ice_wireless_edge-1.3.22.101.pkg
 218   /lib/firmware/updates/intel/ice/ddp/ice-3511a0ffffca0568.pkg
 219
 220 3. If using Linux kernel driver (*ice*), reload the base driver (not
 221 required if using only DPDK driver). ::
 222
 223   # rmmod ice
 224   # modprobe ice
 225
 226 The driver loads the specific package to the selected device and the
 227 OS-default package to the remaining Intel® Ethernet 800 Series
 228 devices in the system.
 229
 230 4. Verify.
 231
 232 For kernel driver:
 233 ==================
 234
 235 Example of output of successful load of Wireless Edge Package to all
 236 devices::
 237
 238   # dmesg | grep -i "ddp \| safe"
 239   [606960.921404] ice 0000:18:00.0: The DDP package was successfully loaded: ICE Wireless Edge Package version 1.3.22.101
 240   [606961.672999] ice 0000:18:00.1: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 241   [606962.439067] ice 0000:18:00.2: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 242   [606963.198305] ice 0000:18:00.3: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 243   [606964.252076] ice 0000:51:00.0: The DDP package was successfully loaded: ICE Wireless Edge Package version 1.3.22.101
 244   [606965.017082] ice 0000:51:00.1: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 245   [606965.802115] ice 0000:51:00.2: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 246   [606966.576517] ice 0000:51:00.3: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 247   [606960.921404] ice 0000:18:00.0: The DDP package was successfully loaded: ICE Wireless Edge Package version 1.3.22.101
 248   [606961.672999] ice 0000:18:00.1: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 249   [606962.439067] ice 0000:18:00.2: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 250   [606963.198305] ice 0000:18:00.3: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 251   [606964.252076] ice 0000:51:00.0: The DDP package was successfully loaded: ICE Wireless Edge Package version 1.3.22.101
 252   [606965.017082] ice 0000:51:00.1: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 253   [606965.802115] ice 0000:51:00.2: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 254   [606966.576517] ice 0000:51:00.3: DDP package already present on device: ICE Wireless Edge Package version 1.3.22.101
 255
 256 If using only DPDK driver:
 257 ==========================
 258
 259 Verify using DPDK's **testpmd** application to indicate the status
 260 and version of the loaded DDP package.
 261
 262 Example of eCPRI config with dpdk-testpmd
 263 -----------------------------------------
 264
 265 16 O-RAN eCPRI IQ streams mapped to 16 independent HW queues each.::
 266
 267   #./dpdk-testpmd -l 22-25 -n 4 -a 0000:af:01.0 -- -i  --rxq=16 --txq=16 --cmdline-file=/home/flexran_xran/ddp.txt
 268
 269   cat /home/flexran_xran/ddp.txt
 270   port stop 0
 271   port config mtu 0 9600
 272   port config 0 rx_offload vlan_strip on
 273   port start 0
 274   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0000 / end actions queue index 0 / mark / end
 275   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0001 / end actions queue index 1 / mark / end
 276   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0002 / end actions queue index 2 / mark / end
 277   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0003 / end actions queue index 3 / mark / end
 278   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0004 / end actions queue index 4 / mark / end
 279   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0005 / end actions queue index 5 / mark / end
 280   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0006 / end actions queue index 6 / mark / end
 281   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0007 / end actions queue index 7 / mark / end
 282   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0008 / end actions queue index 8 / mark / end
 283   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x0009 / end actions queue index 9 / mark / end
 284   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x000a / end actions queue index 10 / mark / end
 285   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x000b / end actions queue index 11 / mark / end
 286   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x000c / end actions queue index 12 / mark / end
 287   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x000d / end actions queue index 13 / mark / end
 288   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x000e / end actions queue index 14 / mark / end
 289   flow create 0 ingress pattern eth / ecpri common type iq_data pc_id is 0x000f / end actions queue index 15 / mark / end
 290   set fwd rxonly
 291   start
 292   show fwd stats all
 293
 294
 295 O-RAN Front haul eCPRI
 296 ======================
 297
 298 Intel® Ethernet 800 Series DDP capabilities support several
 299 functionalities important for the O-RAN FH.
 300
 301 -  RSS for packet steering based on ecpriMessage
 302
 303 -  RSS for packet steering based on ecpriRtcid/ecpriPcid
 304
 305 -  Queue mapping based on ecpriRtcid/ecpriPcid
 306
 307 -  Queue mapping based on ecpriMessage
 308
 309 .. image:: images/O-RAN-FH-VNF.jpg
 310   :width: 400
 311   :alt: Figure . O-RAN FH VNF
 312
 313 Figure 30. O-RAN FH VNF
 314
 315 Table 13. Patterns & Input Sets for Flow Director and RSS (DPDK 21.02)
 316
 317 ============================= ========================================
 318 Pattern                       Input Set
 319 ============================= ========================================
 320 ETH / VLAN / eCPRI            ecpriMessage \| ecpriRtcid/ecpriPcid
 321 ETH / VLAN /IPv4(6)/UDP/eCPRI ecpriMessage \| ecpriRtcid/ecpriPcid (*)
 322 ============================= ========================================
 323
 324 *Note:* \* IP/UDP is not used with FlexRAN
 325
 326 Limitations
 327 ===========
 328
 329 DPDK 21.02 allows up to 1024 queues per VF and RSS across up to 64
 330 receive queues.
 331
 332 RTE Flow API
 333 ============
 334
 335 The DPDK Generic flow API (rte_flow) will be used to the configure the
 336 Intel® Ethernet 800 Series to match specific ingress traffic and forward
 337 it to specified queues.
 338
 339 For further information, please refer to section 11 of the DPDK
 340 Programmers
 341 guide <https://doc.dpdk.org/guides/prog_guide/rte_flow.html>.
 342
 343 The specific ingress traffic is identified by a matching pattern which
 344 is composed of one or more Pattern items (represented by struct
 345 rte_flow_item). Once a match has been determined one or more associated
 346 Actions (represented by struct rte_flow_action) will be performed.
 347
 348 A number of flow rules can be combined such that one rule directs
 349 traffic to a queue group based on *ecpriMessage/ ecpriRtcid/ecpriPcid*
 350 etc. and a second rule distributes matching packets within that queue
 351 group using RSS.
 352
 353 The following subset of the RTE Flow API functions can be used to
 354 validate, create and destroy RTE Flow rules.
 355
 356 RTE Flow Rule Validation
 357 ========================
 358
 359 A RTE Flow rule is created via a call to the function
 360 *rte_flow_validate*. This can be used to check the rule for correctness
 361 and whether it would be accepted by the device given sufficient
 362 resources.::
 363
 364   int   rte_flow_validate(uint16_t port_id,
 365         const struct rte_flow_attr *attr,
 366         const struct rte_flow_item pattern[],
 367         const struct rte_flow_action *actions[]
 368         struct rte_flow_error *error);
 369
 370
 371 port_id : port identifier of Ethernet device
 372
 373 attr : flow rule attributes(ingress/egress)
 374
 375 pattern : pattern specification (list terminated by the END pattern
 376 item).
 377
 378 action : associated actions (list terminated by the END action).
 379
 380 error : perform verbose error reporting if not NULL.
 381
 382 0 is returned upon success, negative errno otherwise.
 383
 384 RTE Flow Rule Creation
 385 ======================
 386
 387 A RTE Flow rule is created via a call to the function *rte_flow_create*.::
 388
 389   struct rte_flow * rte_flow_create(uint16_t port_id,
 390           const struct rte_flow_attr *attr,
 391           const struct rte_flow_item pattern[],
 392           const struct rte_flow_action *actions[]
 393           struct rte_flow_error *error);
 394
 395 port_id : port identifier of Ethernet device
 396
 397 attr : flow rule attributes(ingress/egress)
 398
 399 pattern : pattern specification (list terminated by the END pattern
 400 item).
 401
 402 action : associated actions (list terminated by the END action).
 403
 404 error : perform verbose error reporting if not NULL.
 405
 406 A valid handle is returned upon success, NULL otherwise.
 407
 408 RTE Flow Rule Destruction
 409 =========================
 410
 411 A RTE Flow rule is destroyed via a call to the function
 412 *rte_flow_destroy*.::
 413
 414   int rte_flow_destroy(uint16_t port_id,
 415     struct rte_flow \*flow,
 416     struct rte_flow_error \*error);
 417
 418 port_id : port identifier of Ethernet device
 419
 420 flow : flow rule handle to destroy.
 421
 422 error : perform verbose error reporting if not NULL.
 423
 424 0 is returned upon success, negative errno otherwise.
 425
 426 RTE Flow Flush
 427 ==============
 428
 429 All flow rule handles associated with a port can be released using
 430 *rte_flow_flush*. They are released as with successive calls to function
 431 *rte_flow_destroy*.::
 432
 433   int rte_flow_flush(uint16_t port_id,
 434     struct rte_flow_error \*error);
 435
 436 port_id : port identifier of Ethernet device
 437
 438 error : perform verbose error reporting if not NULL.
 439
 440 0 is returned upon success, negative errno otherwise.
 441
 442 RTE Flow Query
 443 ==============
 444
 445 A RTE Flow rule is queried via a call to the function *rte_flow_query*.::
 446
 447   int rte_flow_query(uint16_t port_id,
 448                   struct rte_flow *flow,
 449                   const struct rte_flow_action *action,
 450                   void *data,
 451                   struct rte_flow_error *error);
 452
 453 port_id : port identifier of Ethernet device
 454
 455 flow : flow rule handle to query
 456
 457 action : action to query, this must match prototype from flow rule.
 458
 459 data : pointer to storage for the associated query data type
 460
 461 error : perform verbose error reporting if not NULL.
 462
 463 0 is returned upon success, negative errno otherwise.
 464
 465 RTE Flow Rules
 466 ==============
 467
 468 A flow rule is the combination of attributes with a matching pattern and
 469 a list of actions. Each flow rules consists of:
 470
 471 -  **Attributes (represented by struct rte_flow_attr):** properties of a flow rule such as its direction (ingress or egress) and priority.
 472
 473 -  **Pattern Items (represented by struct rte_flow_item):** is part of a matching pattern that either matches specific packet data or traffic properties.
 474
 475 -  **Matching pattern:** traffic properties to look for, a combination of any number of items.
 476
 477 -  **Actions (represented by struct rte_flow_action):** operations to perform whenever a packet is matched by a pattern.
 478
 479 Attributes
 480 ==========
 481
 482 Flow rule patterns apply to inbound and/or outbound traffic. For the
 483 purposes described in later sections the rules apply to ingress only.
 484 For further information, please refer to section 11 of the DPDK
 485 Programmers guide <https://doc.dpdk.org/guides/prog_guide/rte_flow.html>.::
 486
 487   *struct*\ rte_flow_attr <https://doc.dpdk.org/api/structrte__flow__attr.html>\ *{*
 488   *uint32_t*\ group <https://doc.dpdk.org/api/structrte__flow__attr.html#a0d20c78ce80e301ed514bd4b4dec9ec0>\ *;*
 489   *uint32_t*\ priority <https://doc.dpdk.org/api/structrte__flow__attr.html#a90249de64da5ae5d7acd34da7ea1b857>\ *;*
 490   *uint32_t*\ ingress <https://doc.dpdk.org/api/structrte__flow__attr.html#ae4d19341d5298a2bc61f9eb941b1179c>\ *:1;*
 491   *uint32_t*\ egress <https://doc.dpdk.org/api/structrte__flow__attr.html#a33bdc3cfc314d71f3187a8186bc570a9>\ *:1;*
 492   *uint32_t*\ transfer <https://doc.dpdk.org/api/structrte__flow__attr.html#a9371183486f590ef35fef41dec806fef>\ *:1;*
 493   *uint32_t*\ reserved <https://doc.dpdk.org/api/structrte__flow__attr.html#aa43c4c21b173ada1b6b7568956f0d650>\ *:29;*
 494   *};*
 495
 496 Pattern items
 497 =============
 498
 499 For the purposes described in later sections Pattern items are primarily
 500 for matching protocol headers and packet data, usually associated with a
 501 specification structure. These must be stacked in the same order as the
 502 protocol layers to match inside packets, starting from the lowest.
 503
 504 Item specification structures are used to match specific values among
 505 protocol fields (or item properties).
 506
 507 Up to three structures of the same type can be set for a given item:
 508
 509 -  **spec:** values to match (e.g. a given IPv4 address).
 510
 511 -  **last:** upper bound for an inclusive range with corresponding fields in spec.
 512
 513 -  **mask:** bit-mask applied to both spec and last whose purpose is to distinguish the values to take into account and/or partially mask them out (e.g. in order to match an IPv4 address prefix).
 514
 515 Table 14. Example RTE FLOW Item Types
 516
 517 +-------------+---------------------------------------+-------------------------+
 518 | Item Type\* | Description                           | Specification Structure |
 519 +=============+=======================================+=========================+
 520 | END         | End marker for item lists             | None                    |
 521 +-------------+---------------------------------------+-------------------------+
 522 | VOID        | Used as a placeholder for convenience | None                    |
 523 +-------------+---------------------------------------+-------------------------+
 524 | ETH         | Matches an Ethernet header            | rte_flow_item_eth       |
 525 +-------------+---------------------------------------+-------------------------+
 526 | VLAN        | Matches an 802.1Q/ad VLAN tag.        | rte_flow_item_vlan      |
 527 +-------------+---------------------------------------+-------------------------+
 528 | IPV4        | Matches an IPv4 header                | rte_flow_item_ipv4      |
 529 +-------------+---------------------------------------+-------------------------+
 530 | IPV6        | Matches an IPv6 header                | rte_flow_item_ipv6      |
 531 +-------------+---------------------------------------+-------------------------+
 532 | ICMP        | Matches an ICMP header.               | rte_flow_item_icmp      |
 533 +-------------+---------------------------------------+-------------------------+
 534 | UDP         | Matches an UDP header.                | rte_flow_item_udp       |
 535 +-------------+---------------------------------------+-------------------------+
 536 | TCP         | Matches a TCP header.                 | rte_flow_item_tcp       |
 537 +-------------+---------------------------------------+-------------------------+
 538 | SCTP        | Matches a SCTP header.                | rte_flow_item_sctp      |
 539 +-------------+---------------------------------------+-------------------------+
 540 | VXLAN       | Matches a VXLAN header.               | rte_flow_item_vxlan     |
 541 +-------------+---------------------------------------+-------------------------+
 542 | NVGRE       | Matches a NVGRE header.               | rte_flow_item_nvgre     |
 543 +-------------+---------------------------------------+-------------------------+
 544 | ECPRI       | Matches ECPRI Header                  | rte_flow_item_ecpri     |
 545 +-------------+---------------------------------------+-------------------------+
 546
 547 ::
 548
 549   RTE_FLOW_ITEM_TYPE_ETH
 550
 551   struct rte_flow_item_eth {
 552           struct rte_ether_addr dst; /**< Destination MAC. */
 553           struct rte_ether_addr src; /**< Source MAC. > */
 554           rte_be16_t type; /**< EtherType or TPID.> */
 555   };
 556
 557   struct rte_ether_addr {
 558           uint8_t addr_bytes[RTE_ETHER_ADDR_LEN]; /**< Addr bytes in tx order */
 559   }
 560
 561 ::
 562
 563   RTE_FLOW_ITEM_TYPE_IPV4
 564
 565   struct rte_flow_item_ipv4 {
 566           struct rte_ipv4_hdr hdr; /**< IPv4 header definition. */
 567   };
 568
 569   struct rte_ipv4_hdr {
 570           uint8_t  version_ihl;           /**< version and header length */
 571           uint8_t  type_of_service;       /**< type of service */
 572           rte_be16_t total_length;        /**< length of packet */
 573           rte_be16_t packet_id;           /**< packet ID */
 574           rte_be16_t fragment_offset;     /**< fragmentation offset */
 575           uint8_t  time_to_live;          /**< time to live */
 576           uint8_t  next_proto_id;         /**< protocol ID */
 577           rte_be16_t hdr_checksum;        /**< header checksum */
 578           rte_be32_t src_addr;            /**< source address */
 579           rte_be32_t dst_addr;            /**< destination address */
 580   }
 581
 582   RTE_FLOW_ITEM_TYPE_UDP
 583
 584   struct rte_flow_item_udp {
 585           struct rte_udp_hdr hdr; /**< UDP header definition. */
 586   };
 587
 588   struct rte_udp_hdr {
 589           rte_be16_t src_port;    /**< UDP source port. */
 590           rte_be16_t dst_port;    /**< UDP destination port. */
 591           rte_be16_t dgram_len;   /**< UDP datagram length */
 592           rte_be16_t dgram_cksum; /**< UDP datagram checksum */
 593   }
 594
 595   RTE_FLOW_ITEM_TYPE_ECPRI
 596
 597   struct rte_flow_item_ecpri {
 598     struct rte_ecpri_combined_msg_hdr hdr;
 599   };
 600
 601   struct rte_ecpri_combined_msg_hdr {
 602     struct rte_ecpri_common_hdr common;
 603     union {
 604       struct rte_ecpri_msg_iq_data type0;
 605       struct rte_ecpri_msg_bit_seq type1;
 606       struct rte_ecpri_msg_rtc_ctrl type2;
 607       struct rte_ecpri_msg_bit_seq type3;
 608       struct rte_ecpri_msg_rm_access type4;
 609       struct rte_ecpri_msg_delay_measure type5;
 610       struct rte_ecpri_msg_remote_reset type6;
 611       struct rte_ecpri_msg_event_ind type7;
 612       rte_be32_t dummy[3];
 613     };
 614   };
 615   struct rte_ecpri_common_hdr {
 616     union {
 617       rte_be32_t u32;   /**< 4B common header in BE */
 618       struct {
 619   #if RTE_BYTE_ORDER == RTE_LITTLE_ENDIAN
 620         uint32_t size:16; /**< Payload Size */
 621         uint32_t type:8; /**< Message Type */
 622         uint32_t c:1; /**< Concatenation Indicator */
 623         uint32_t res:3; /**< Reserved */
 624         uint32_t revision:4; /**< Protocol Revision */
 625   #elif RTE_BYTE_ORDER == RTE_BIG_ENDIAN
 626         uint32_t revision:4; /**< Protocol Revision */
 627         uint32_t res:3; /**< Reserved */
 628         uint32_t c:1;  /**< Concatenation Indicator */
 629         uint32_t type:8; /**< Message Type */
 630         uint32_t size:16; /**< Payload Size */
 631   #endif
 632       };
 633     };
 634   };
 635   /**
 636   * eCPRI Message Header of Type #0: IQ Data
 637   */
 638   struct rte_ecpri_msg_iq_data {
 639     rte_be16_t pc_id;           /**< Physical channel ID */
 640     rte_be16_t seq_id;          /**< Sequence ID */
 641   };
 642
 643   /**
 644   * eCPRI Message Header of Type #1: Bit Sequence
 645   */
 646   struct rte_ecpri_msg_bit_seq {
 647     rte_be16_t pc_id;           /**< Physical channel ID */
 648     rte_be16_t seq_id;          /**< Sequence ID */
 649   };
 650
 651   /**
 652   * eCPRI Message Header of Type #2: Real-Time Control Data
 653   */
 654   struct rte_ecpri_msg_rtc_ctrl {
 655     rte_be16_t rtc_id;          /**< Real-Time Control Data ID */
 656     rte_be16_t seq_id;          /**< Sequence ID */
 657   };
 658
 659   /**
 660   * eCPRI Message Header of Type #3: Generic Data Transfer
 661   */
 662   struct rte_ecpri_msg_gen_data {
 663     rte_be32_t pc_id;           /**< Physical channel ID */
 664     rte_be32_t seq_id;          /**< Sequence ID */
 665   };
 666
 667   /**
 668   * eCPRI Message Header of Type #4: Remote Memory Access
 669   */
 670   RTE_STD_C11
 671   struct rte_ecpri_msg_rm_access {
 672   #if RTE_BYTE_ORDER == RTE_LITTLE_ENDIAN
 673     uint32_t ele_id:16;         /**< Element ID */
 674     uint32_t rr:4;                      /**< Req/Resp */
 675     uint32_t rw:4;                      /**< Read/Write */
 676     uint32_t rma_id:8;          /**< Remote Memory Access ID */
 677   #elif RTE_BYTE_ORDER == RTE_BIG_ENDIAN
 678     uint32_t rma_id:8;          /**< Remote Memory Access ID */
 679     uint32_t rw:4;                      /**< Read/Write */
 680     uint32_t rr:4;                      /**< Req/Resp */
 681     uint32_t ele_id:16;         /**< Element ID */
 682   #endif
 683     uint8_t addr[6];            /**< 48-bits address */
 684     rte_be16_t length;          /**< number of bytes */
 685   };
 686
 687   /**
 688   * eCPRI Message Header of Type #5: One-Way Delay Measurement
 689   */
 690   struct rte_ecpri_msg_delay_measure {
 691     uint8_t msr_id;                     /**< Measurement ID */
 692     uint8_t act_type;           /**< Action Type */
 693   };
 694
 695   /**
 696   * eCPRI Message Header of Type #6: Remote Reset
 697   */
 698   struct rte_ecpri_msg_remote_reset {
 699     rte_be16_t rst_id;          /**< Reset ID */
 700     uint8_t rst_op;                     /**< Reset Code Op */
 701   };
 702
 703   /**
 704   * eCPRI Message Header of Type #7: Event Indication
 705   */
 706   struct rte_ecpri_msg_event_ind {
 707     uint8_t evt_id;                     /**< Event ID */
 708     uint8_t evt_type;           /**< Event Type */
 709     uint8_t seq;                        /**< Sequence Number */
 710     uint8_t number;                     /**< Number of Faults/Notif */
 711   };
 712
 713
 714 Matching Patterns
 715 =================
 716
 717 A matching pattern is formed by stacking items starting from the lowest
 718 protocol layer to match. Patterns are terminated by END pattern item.
 719
 720 Actions
 721 -------
 722
 723 Each possible action is represented by a type. An action can have an
 724 associated configuration object. Actions are terminated by the END
 725 action.
 726
 727 Table 15. RTE FLOW Actions
 728
 729 +----------+----------------------------+-------------------------+
 730 | Action\* | Description                | Configuration Structure |
 731 +==========+============================+=========================+
 732 | END      || End marker for action     | none                    |
 733 |          || lists                     |                         |
 734 +----------+----------------------------+-------------------------+
 735 | VOID     || Used as a placeholder for | none                    |
 736 |          || convenience               |                         |
 737 +----------+----------------------------+-------------------------+
 738 | PASSTHRU || Leaves traffic up for     | none                    |
 739 |          || additional processing by  |                         |
 740 |          || subsequent flow rules;    |                         |
 741 |          || makes a flow rule         |                         |
 742 |          || non-terminating.          |                         |
 743 +----------+----------------------------+-------------------------+
 744 | MARK     || Attaches an integer value | rte_flow_action_mark    |
 745 |          || to packets and sets       |                         |
 746 |          || PKT_RX_FDIR and           |                         |
 747 |          || PKT_RX_FDIR_ID mbuf flags |                         |
 748 +----------+----------------------------+-------------------------+
 749 | QUEUE    || Assigns packets to a given| rte_flow_action_queue   |
 750 |          || queue index               |                         |
 751 +----------+----------------------------+-------------------------+
 752 | DROP     || Drops packets             | none                    |
 753 +----------+----------------------------+-------------------------+
 754 | COUNT    || Enables Counters for this | rte_flow_action_count   |
 755 |          || flow rule                 |                         |
 756 +----------+----------------------------+-------------------------+
 757 | RSS      || Similar to QUEUE, except  | rte_flow_action_rss     |
 758 |          || RSS is additionally       |                         |
 759 |          || performed on packets to   |                         |
 760 |          || spread them among several |                         |
 761 |          || queues according to the   |                         |
 762 |          || provided parameters.      |                         |
 763 +----------+----------------------------+-------------------------+
 764 | VF       || Directs matching traffic  | rte_flow_action_vf      |
 765 |          || to a given virtual        |                         |
 766 |          || function of the current   |                         |
 767 |          || device                    |                         |
 768 +----------+----------------------------+-------------------------+
 769
 770 Route to specific Queue id based on ecpriRtcid/ecpriPcid
 771 ========================================================
 772
 773 An RTE Flow Rule will be created to match an eCPRI packet with a
 774 specific pc_id value and route it to specified queues.
 775
 776 .. _pattern-items-1:
 777
 778 Pattern Items
 779 -------------
 780
 781 Table 16. Pattern Items to match eCPRI packet with a Specific Physical
 782 Channel ID (pc_id)
 783
 784 +-------+----------+-----------------------+-----------------------+
 785 | Index | Item     | Spec                  | Mask                  |
 786 +=======+==========+=======================+=======================+
 787 | 0     | Ethernet | 0                     | 0                     |
 788 +-------+----------+-----------------------+-----------------------+
 789 | 1     | eCPRI    || hdr.common.type =    || hdr.common.type =    |
 790 |       |          || RTE_EC               || 0xff;                |
 791 |       |          || PRI_MSG_TYPE_IQ_DATA;|                       |
 792 |       |          |                       || hdr.type0.pc_id =    |
 793 |       |          || hdr.type0.pc_id =    || 0xffff;              |
 794 |       |          || pc_id;               |                       |
 795 +-------+----------+-----------------------+-----------------------+
 796 | 2     | END      | 0                     | 0                     |
 797 +-------+----------+-----------------------+-----------------------+
 798
 799 The following code sets up the *RTE_FLOW_ITEM_TYPE_ETH* and
 800 *RTE_FLOW_ITEM_TYPE_ECPRI* Pattern Items.
 801
 802 The *RTE_FLOW_ITEM_TYPE_ECPRI* Pattern is configured to match on the
 803 pc_id value (in this case 8 converted to Big Endian byte order).
 804
 805 +--------------------------------------------------------------------------+
 806 | uint8_t pc_id_be = 0x0800;                                               |
 807 |                                                                          |
 808 | #define MAX_PATTERN_NUM 3                                                |
 809 |                                                                          |
 810 | struct rte_flow_item pattern[MAX_PATTERN_NUM];                           |
 811 |                                                                          |
 812 | struct rte_flow_action action[MAX_ACTION_NUM];                           |
 813 |                                                                          |
 814 | struct rte_flow_item_ecpri ecpri_spec;                                   |
 815 |                                                                          |
 816 | struct rte_flow_item_ecpri ecpri_mask;                                   |
 817 |                                                                          |
 818 | /\* Ethernet \*/                                                         |
 819 |                                                                          |
 820 | patterns[0].type = RTE_FLOW_ITEM_TYPE_ETH;                               |
 821 |                                                                          |
 822 | patterns[0].spec = 0;                                                    |
 823 |                                                                          |
 824 | patterns[0].mask = 0;                                                    |
 825 |                                                                          |
 826 | /\* ECPRI \*/                                                            |
 827 |                                                                          |
 828 | ecpri_spec.hdr.common.type = RTE_ECPRI_MSG_TYPE_IQ_DATA;                 |
 829 |                                                                          |
 830 | ecpri_spec.hdr.type0.pc_id = pc_id_be;                                   |
 831 |                                                                          |
 832 | ecpri_mask.hdr.common.type = 0xff;                                       |
 833 |                                                                          |
 834 | ecpri_mask.hdr.type0.pc_id = 0xffff;                                     |
 835 |                                                                          |
 836 | ecpri_spec.hdr.common.u32 = rte_cpu_to_be_32(ecpri_spec.hdr.common.u32); |
 837 |                                                                          |
 838 | pattern[1].type = RTE_FLOW_ITEM_TYPE_ECPRI;                              |
 839 |                                                                          |
 840 | pattern[1].spec = &ecpri_spec;                                           |
 841 |                                                                          |
 842 | pattern[1].mask = &ecpri_mask;                                           |
 843 |                                                                          |
 844 | /\* END the pattern array \*/                                            |
 845 |                                                                          |
 846 | patterns[2].type = RTE_FLOW_ITEM_TYPE_END                                |
 847 +--------------------------------------------------------------------------+
 848
 849 Action
 850 ------
 851
 852 Table 17. QUEUE action for given queue id
 853
 854 ===== ====== ====== ==================== ====================
 855 Index Action Fields Description          Value
 856 ===== ====== ====== ==================== ====================
 857 0     QUEUE  index  queue indices to use Must be 0,1,2,3, etc
 858 1     END
 859 ===== ====== ====== ==================== ====================
 860
 861 The following code sets up the action *RTE_FLOW_ACTION_TYPE_QUEUE* and
 862 calls the *rte_flow_create* function to create the RTE Flow rule.
 863
 864 +----------------------------------------------------------------------+
 865 | *#define MAX_ACTION_NUM 2*                                           |
 866 |                                                                      |
 867 | *uint16_t rx_q = 4;*                                                 |
 868 |                                                                      |
 869 | *struct rte_flow_action_queue queue = { .index = rx_q };*            |
 870 |                                                                      |
 871 | *struct rte_flow \*handle;*                                          |
 872 |                                                                      |
 873 | *struct rte_flow_error err;*                                         |
 874 |                                                                      |
 875 | *struct rte_flow_action actions[MAX_ACTION_NUM];*                    |
 876 |                                                                      |
 877 | *struct rte_flow_attr attributes = {.ingress = 1 };*                 |
 878 |                                                                      |
 879 | *action[0].type = RTE_FLOW_ACTION_TYPE_QUEUE;*                       |
 880 |                                                                      |
 881 | *action[0].conf = &queue;*                                           |
 882 |                                                                      |
 883 | *action[1].type = RTE_FLOW_ACTION_TYPE_END;*                         |
 884 |                                                                      |
 885 | *handle = rte_flow_create (port_id, &attributes, patterns, actions,  |
 886 | &err);*                                                              |
 887 +----------------------------------------------------------------------+