1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 6WIND S.A. 3 4.. _switch_representation: 5 6Switch Representation within DPDK Applications 7============================================== 8 9.. contents:: :local: 10 11Introduction 12------------ 13 14Network adapters with multiple physical ports and/or SR-IOV capabilities 15usually support the offload of traffic steering rules between their virtual 16functions (VFs), physical functions (PFs) and ports. 17 18Like for standard Ethernet switches, this involves a combination of 19automatic MAC learning and manual configuration. For most purposes it is 20managed by the host system and fully transparent to users and applications. 21 22On the other hand, applications typically found on hypervisors that process 23layer 2 (L2) traffic (such as OVS) need to steer traffic themselves 24according on their own criteria. 25 26Without a standard software interface to manage traffic steering rules 27between VFs, PFs and the various physical ports of a given device, 28applications cannot take advantage of these offloads; software processing is 29mandatory even for traffic which ends up re-injected into the device it 30originates from. 31 32This document describes how such steering rules can be configured through 33the DPDK flow API (**rte_flow**), with emphasis on the SR-IOV use case 34(PF/VF steering) using a single physical port for clarity, however the same 35logic applies to any number of ports without necessarily involving SR-IOV. 36 37Port Representors 38----------------- 39 40In many cases, traffic steering rules cannot be determined in advance; 41applications usually have to process a bit of traffic in software before 42thinking about offloading specific flows to hardware. 43 44Applications therefore need the ability to receive and inject traffic to 45various device endpoints (other VFs, PFs or physical ports) before 46connecting them together. Device drivers must provide means to hook the 47"other end" of these endpoints and to refer them when configuring flow 48rules. 49 50This role is left to so-called "port representors" (also known as "VF 51representors" in the specific context of VFs), which are to DPDK what the 52Ethernet switch device driver model (**switchdev**) [1]_ is to Linux, and 53which can be thought as a software "patch panel" front-end for applications. 54 55- DPDK port representors are implemented as additional virtual Ethernet 56 device (**ethdev**) instances, spawned on an as needed basis through 57 configuration parameters passed to the driver of the underlying 58 device using devargs. 59 60:: 61 62 -w pci:dbdf,representor=0 63 -w pci:dbdf,representor=[0-3] 64 -w pci:dbdf,representor=[0,5-11] 65 66- As virtual devices, they may be more limited than their physical 67 counterparts, for instance by exposing only a subset of device 68 configuration callbacks and/or by not necessarily having Rx/Tx capability. 69 70- Among other things, they can be used to assign MAC addresses to the 71 resource they represent. 72 73- Applications can tell port representors apart from other physical of virtual 74 port by checking the dev_flags field within their device information 75 structure for the RTE_ETH_DEV_REPRESENTOR bit-field. 76 77.. code-block:: c 78 79 struct rte_eth_dev_info { 80 ... 81 uint32_t dev_flags; /**< Device flags */ 82 ... 83 }; 84 85- The device or group relationship of ports can be discovered using the 86 switch ``domain_id`` field within the devices switch information structure. By 87 default the switch ``domain_id`` of a port will be 88 ``RTE_ETH_DEV_SWITCH_DOMAIN_ID_INVALID`` to indicate that the port doesn't 89 support the concept of a switch domain, but ports which do support the concept 90 will be allocated a unique switch ``domain_id``, ports within the same switch 91 domain will share the same ``domain_id``. The switch ``port_id`` is used to 92 specify the port_id in terms of the switch, so in the case of SR-IOV devices 93 the switch ``port_id`` would represent the virtual function identifier of the 94 port. 95 96.. code-block:: c 97 98 /** 99 * Ethernet device associated switch information 100 */ 101 struct rte_eth_switch_info { 102 const char *name; /**< switch name */ 103 uint16_t domain_id; /**< switch domain id */ 104 uint16_t port_id; /**< switch port id */ 105 }; 106 107 108.. [1] `Ethernet switch device driver model (switchdev) 109 <https://www.kernel.org/doc/Documentation/networking/switchdev.txt>`_ 110 111Basic SR-IOV 112------------ 113 114"Basic" in the sense that it is not managed by applications, which 115nonetheless expect traffic to flow between the various endpoints and the 116outside as if everything was linked by an Ethernet hub. 117 118The following diagram pictures a setup involving a device with one PF, two 119VFs and one shared physical port 120 121:: 122 123 .-------------. .-------------. .-------------. 124 | hypervisor | | VM 1 | | VM 2 | 125 | application | | application | | application | 126 `--+----------' `----------+--' `--+----------' 127 | | | 128 .-----+-----. | | 129 | port_id 3 | | | 130 `-----+-----' | | 131 | | | 132 .-+--. .---+--. .--+---. 133 | PF | | VF 1 | | VF 2 | 134 `-+--' `---+--' `--+---' 135 | | | 136 `---------. .-----------------------' | 137 | | .-------------------------' 138 | | | 139 .--+-----+-----+--. 140 | interconnection | 141 `--------+--------' 142 | 143 .----+-----. 144 | physical | 145 | port 0 | 146 `----------' 147 148- A DPDK application running on the hypervisor owns the PF device, which is 149 arbitrarily assigned port index 3. 150 151- Both VFs are assigned to VMs and used by unknown applications; they may be 152 DPDK-based or anything else. 153 154- Interconnection is not necessarily done through a true Ethernet switch and 155 may not even exist as a separate entity. The role of this block is to show 156 that something brings PF, VFs and physical ports together and enables 157 communication between them, with a number of built-in restrictions. 158 159Subsequent sections in this document describe means for DPDK applications 160running on the hypervisor to freely assign specific flows between PF, VFs 161and physical ports based on traffic properties, by managing this 162interconnection. 163 164Controlled SR-IOV 165----------------- 166 167Initialization 168~~~~~~~~~~~~~~ 169 170When a DPDK application gets assigned a PF device and is deliberately not 171started in `basic SR-IOV`_ mode, any traffic coming from physical ports is 172received by PF according to default rules, while VFs remain isolated. 173 174:: 175 176 .-------------. .-------------. .-------------. 177 | hypervisor | | VM 1 | | VM 2 | 178 | application | | application | | application | 179 `--+----------' `----------+--' `--+----------' 180 | | | 181 .-----+-----. | | 182 | port_id 3 | | | 183 `-----+-----' | | 184 | | | 185 .-+--. .---+--. .--+---. 186 | PF | | VF 1 | | VF 2 | 187 `-+--' `------' `------' 188 | 189 `-----. 190 | 191 .--+----------------------. 192 | managed interconnection | 193 `------------+------------' 194 | 195 .----+-----. 196 | physical | 197 | port 0 | 198 `----------' 199 200In this mode, interconnection must be configured by the application to 201enable VF communication, for instance by explicitly directing traffic with a 202given destination MAC address to VF 1 and allowing that with the same source 203MAC address to come out of it. 204 205For this to work, hypervisor applications need a way to refer to either VF 1 206or VF 2 in addition to the PF. This is addressed by `VF representors`_. 207 208VF Representors 209~~~~~~~~~~~~~~~ 210 211VF representors are virtual but standard DPDK network devices (albeit with 212limited capabilities) created by PMDs when managing a PF device. 213 214Since they represent VF instances used by other applications, configuring 215them (e.g. assigning a MAC address or setting up promiscuous mode) affects 216interconnection accordingly. If supported, they may also be used as two-way 217communication ports with VFs (assuming **switchdev** topology) 218 219 220:: 221 222 .-------------. .-------------. .-------------. 223 | hypervisor | | VM 1 | | VM 2 | 224 | application | | application | | application | 225 `--+---+---+--' `----------+--' `--+----------' 226 | | | | | 227 | | `-------------------. | | 228 | `---------. | | | 229 | | | | | 230 .-----+-----. .-----+-----. .-----+-----. | | 231 | port_id 3 | | port_id 4 | | port_id 5 | | | 232 `-----+-----' `-----+-----' `-----+-----' | | 233 | | | | | 234 .-+--. .-----+-----. .-----+-----. .---+--. .--+---. 235 | PF | | VF 1 rep. | | VF 2 rep. | | VF 1 | | VF 2 | 236 `-+--' `-----+-----' `-----+-----' `---+--' `--+---' 237 | | | | | 238 | | .---------' | | 239 `-----. | | .-----------------' | 240 | | | | .---------------------' 241 | | | | | 242 .--+-------+---+---+---+--. 243 | managed interconnection | 244 `------------+------------' 245 | 246 .----+-----. 247 | physical | 248 | port 0 | 249 `----------' 250 251- VF representors are assigned arbitrary port indices 4 and 5 in the 252 hypervisor application and are respectively associated with VF 1 and VF 2. 253 254- They can't be dissociated; even if VF 1 and VF 2 were not connected, 255 representors could still be used for configuration. 256 257- In this context, port index 3 can be thought as a representor for physical 258 port 0. 259 260As previously described, the "interconnection" block represents a logical 261concept. Interconnection occurs when hardware configuration enables traffic 262flows from one place to another (e.g. physical port 0 to VF 1) according to 263some criteria. 264 265This is discussed in more detail in `traffic steering`_. 266 267Traffic Steering 268~~~~~~~~~~~~~~~~ 269 270In the following diagram, each meaningful traffic origin or endpoint as seen 271by the hypervisor application is tagged with a unique letter from A to F. 272 273:: 274 275 .-------------. .-------------. .-------------. 276 | hypervisor | | VM 1 | | VM 2 | 277 | application | | application | | application | 278 `--+---+---+--' `----------+--' `--+----------' 279 | | | | | 280 | | `-------------------. | | 281 | `---------. | | | 282 | | | | | 283 .----(A)----. .----(B)----. .----(C)----. | | 284 | port_id 3 | | port_id 4 | | port_id 5 | | | 285 `-----+-----' `-----+-----' `-----+-----' | | 286 | | | | | 287 .-+--. .-----+-----. .-----+-----. .---+--. .--+---. 288 | PF | | VF 1 rep. | | VF 2 rep. | | VF 1 | | VF 2 | 289 `-+--' `-----+-----' `-----+-----' `--(D)-' `-(E)--' 290 | | | | | 291 | | .---------' | | 292 `-----. | | .-----------------' | 293 | | | | .---------------------' 294 | | | | | 295 .--+-------+---+---+---+--. 296 | managed interconnection | 297 `------------+------------' 298 | 299 .---(F)----. 300 | physical | 301 | port 0 | 302 `----------' 303 304- **A**: PF device. 305- **B**: port representor for VF 1. 306- **C**: port representor for VF 2. 307- **D**: VF 1 proper. 308- **E**: VF 2 proper. 309- **F**: physical port. 310 311Although uncommon, some devices do not enforce a one to one mapping between 312PF and physical ports. For instance, by default all ports of **mlx4** 313adapters are available to all their PF/VF instances, in which case 314additional ports appear next to **F** in the above diagram. 315 316Assuming no interconnection is provided by default in this mode, setting up 317a `basic SR-IOV`_ configuration involving physical port 0 could be broken 318down as: 319 320PF: 321 322- **A to F**: let everything through. 323- **F to A**: PF MAC as destination. 324 325VF 1: 326 327- **A to D**, **E to D** and **F to D**: VF 1 MAC as destination. 328- **D to A**: VF 1 MAC as source and PF MAC as destination. 329- **D to E**: VF 1 MAC as source and VF 2 MAC as destination. 330- **D to F**: VF 1 MAC as source. 331 332VF 2: 333 334- **A to E**, **D to E** and **F to E**: VF 2 MAC as destination. 335- **E to A**: VF 2 MAC as source and PF MAC as destination. 336- **E to D**: VF 2 MAC as source and VF 1 MAC as destination. 337- **E to F**: VF 2 MAC as source. 338 339Devices may additionally support advanced matching criteria such as 340IPv4/IPv6 addresses or TCP/UDP ports. 341 342The combination of matching criteria with target endpoints fits well with 343**rte_flow** [6]_, which expresses flow rules as combinations of patterns 344and actions. 345 346Enhancing **rte_flow** with the ability to make flow rules match and target 347these endpoints provides a standard interface to manage their 348interconnection without introducing new concepts and whole new API to 349implement them. This is described in `flow API (rte_flow)`_. 350 351.. [6] `Generic flow API (rte_flow) 352 <http://doc.dpdk.org/guides/prog_guide/rte_flow.html>`_ 353 354Flow API (rte_flow) 355------------------- 356 357Extensions 358~~~~~~~~~~ 359 360Compared to creating a brand new dedicated interface, **rte_flow** was 361deemed flexible enough to manage representor traffic only with minor 362extensions: 363 364- Using physical ports, PF, VF or port representors as targets. 365 366- Affecting traffic that is not necessarily addressed to the DPDK port ID a 367 flow rule is associated with (e.g. forcing VF traffic redirection to PF). 368 369For advanced uses: 370 371- Rule-based packet counters. 372 373- The ability to combine several identical actions for traffic duplication 374 (e.g. VF representor in addition to a physical port). 375 376- Dedicated actions for traffic encapsulation / decapsulation before 377 reaching an endpoint. 378 379Traffic Direction 380~~~~~~~~~~~~~~~~~ 381 382From an application standpoint, "ingress" and "egress" flow rule attributes 383apply to the DPDK port ID they are associated with. They select a traffic 384direction for matching patterns, but have no impact on actions. 385 386When matching traffic coming from or going to a different place than the 387immediate port ID a flow rule is associated with, these attributes keep 388their meaning while applying to the chosen origin, as highlighted by the 389following diagram 390 391:: 392 393 .-------------. .-------------. .-------------. 394 | hypervisor | | VM 1 | | VM 2 | 395 | application | | application | | application | 396 `--+---+---+--' `----------+--' `--+----------' 397 | | | | | 398 | | `-------------------. | | 399 | `---------. | | | 400 | ^ | ^ | ^ | | 401 | | ingress | | ingress | | ingress | | 402 | | egress | | egress | | egress | | 403 | v | v | v | | 404 .----(A)----. .----(B)----. .----(C)----. | | 405 | port_id 3 | | port_id 4 | | port_id 5 | | | 406 `-----+-----' `-----+-----' `-----+-----' | | 407 | | | | | 408 .-+--. .-----+-----. .-----+-----. .---+--. .--+---. 409 | PF | | VF 1 rep. | | VF 2 rep. | | VF 1 | | VF 2 | 410 `-+--' `-----+-----' `-----+-----' `--(D)-' `-(E)--' 411 | | | ^ | | ^ 412 | | | egress | | | | egress 413 | | | ingress | | | | ingress 414 | | .---------' v | | v 415 `-----. | | .-----------------' | 416 | | | | .---------------------' 417 | | | | | 418 .--+-------+---+---+---+--. 419 | managed interconnection | 420 `------------+------------' 421 ^ | 422 ingress | | 423 egress | | 424 v | 425 .---(F)----. 426 | physical | 427 | port 0 | 428 `----------' 429 430Ingress and egress are defined as relative to the application creating the 431flow rule. 432 433For instance, matching traffic sent by VM 2 would be done through an ingress 434flow rule on VF 2 (**E**). Likewise for incoming traffic on physical port 435(**F**). This also applies to **C** and **A** respectively. 436 437Transferring Traffic 438~~~~~~~~~~~~~~~~~~~~ 439 440Without Port Representors 441^^^^^^^^^^^^^^^^^^^^^^^^^ 442 443`Traffic direction`_ describes how an application could match traffic coming 444from or going to a specific place reachable from a DPDK port ID. This makes 445sense when the traffic in question is normally seen (i.e. sent or received) 446by the application creating the flow rule (e.g. as in "redirect all traffic 447coming from VF 1 to local queue 6"). 448 449However this does not force such traffic to take a specific route. Creating 450a flow rule on **A** matching traffic coming from **D** is only meaningful 451if it can be received by **A** in the first place, otherwise doing so simply 452has no effect. 453 454A new flow rule attribute named "transfer" is necessary for that. Combining 455it with "ingress" or "egress" and a specific origin requests a flow rule to 456be applied at the lowest level 457 458:: 459 460 ingress only : ingress + transfer 461 : 462 .-------------. .-------------. : .-------------. .-------------. 463 | hypervisor | | VM 1 | : | hypervisor | | VM 1 | 464 | application | | application | : | application | | application | 465 `------+------' `--+----------' : `------+------' `--+----------' 466 | | | traffic : | | | traffic 467 .----(A)----. | v : .----(A)----. | v 468 | port_id 3 | | : | port_id 3 | | 469 `-----+-----' | : `-----+-----' | 470 | | : | ^ | 471 | | : | | traffic | 472 .-+--. .---+--. : .-+--. .---+--. 473 | PF | | VF 1 | : | PF | | VF 1 | 474 `-+--' `--(D)-' : `-+--' `--(D)-' 475 | | | traffic : | ^ | | traffic 476 | | v : | | traffic | v 477 .--+-----------+--. : .--+-----------+--. 478 | interconnection | : | interconnection | 479 `--------+--------' : `--------+--------' 480 | | traffic : | 481 | v : | 482 .---(F)----. : .---(F)----. 483 | physical | : | physical | 484 | port 0 | : | port 0 | 485 `----------' : `----------' 486 487With "ingress" only, traffic is matched on **A** thus still goes to physical 488port **F** by default 489 490 491:: 492 493 testpmd> flow create 3 ingress pattern vf id is 1 / end 494 actions queue index 6 / end 495 496With "ingress + transfer", traffic is matched on **D** and is therefore 497successfully assigned to queue 6 on **A** 498 499 500:: 501 502 testpmd> flow create 3 ingress transfer pattern vf id is 1 / end 503 actions queue index 6 / end 504 505 506With Port Representors 507^^^^^^^^^^^^^^^^^^^^^^ 508 509When port representors exist, implicit flow rules with the "transfer" 510attribute (described in `without port representors`_) are be assumed to 511exist between them and their represented resources. These may be immutable. 512 513In this case, traffic is received by default through the representor and 514neither the "transfer" attribute nor traffic origin in flow rule patterns 515are necessary. They simply have to be created on the representor port 516directly and may target a different representor as described in `PORT_ID 517action`_. 518 519Implicit traffic flow with port representor 520 521:: 522 523 .-------------. .-------------. 524 | hypervisor | | VM 1 | 525 | application | | application | 526 `--+-------+--' `----------+--' 527 | | ^ | | traffic 528 | | | traffic | v 529 | `-----. | 530 | | | 531 .----(A)----. .----(B)----. | 532 | port_id 3 | | port_id 4 | | 533 `-----+-----' `-----+-----' | 534 | | | 535 .-+--. .-----+-----. .---+--. 536 | PF | | VF 1 rep. | | VF 1 | 537 `-+--' `-----+-----' `--(D)-' 538 | | | 539 .--|-------------|-----------|--. 540 | | | | | 541 | | `-----------' | 542 | | <-- traffic | 543 `--|----------------------------' 544 | 545 .---(F)----. 546 | physical | 547 | port 0 | 548 `----------' 549 550Pattern Items And Actions 551~~~~~~~~~~~~~~~~~~~~~~~~~ 552 553PORT Pattern Item 554^^^^^^^^^^^^^^^^^ 555 556Matches traffic originating from (ingress) or going to (egress) a physical 557port of the underlying device. 558 559Using this pattern item without specifying a port index matches the physical 560port associated with the current DPDK port ID by default. As described in 561`traffic steering`_, specifying it should be rarely needed. 562 563- Matches **F** in `traffic steering`_. 564 565PORT Action 566^^^^^^^^^^^ 567 568Directs matching traffic to a given physical port index. 569 570- Targets **F** in `traffic steering`_. 571 572PORT_ID Pattern Item 573^^^^^^^^^^^^^^^^^^^^ 574 575Matches traffic originating from (ingress) or going to (egress) a given DPDK 576port ID. 577 578Normally only supported if the port ID in question is known by the 579underlying PMD and related to the device the flow rule is created against. 580 581This must not be confused with the `PORT pattern item`_ which refers to the 582physical port of a device. ``PORT_ID`` refers to a ``struct rte_eth_dev`` 583object on the application side (also known as "port representor" depending 584on the kind of underlying device). 585 586- Matches **A**, **B** or **C** in `traffic steering`_. 587 588PORT_ID Action 589^^^^^^^^^^^^^^ 590 591Directs matching traffic to a given DPDK port ID. 592 593Same restrictions as `PORT_ID pattern item`_. 594 595- Targets **A**, **B** or **C** in `traffic steering`_. 596 597PF Pattern Item 598^^^^^^^^^^^^^^^ 599 600Matches traffic originating from (ingress) or going to (egress) the physical 601function of the current device. 602 603If supported, should work even if the physical function is not managed by 604the application and thus not associated with a DPDK port ID. Its behavior is 605otherwise similar to `PORT_ID pattern item`_ using PF port ID. 606 607- Matches **A** in `traffic steering`_. 608 609PF Action 610^^^^^^^^^ 611 612Directs matching traffic to the physical function of the current device. 613 614Same restrictions as `PF pattern item`_. 615 616- Targets **A** in `traffic steering`_. 617 618VF Pattern Item 619^^^^^^^^^^^^^^^ 620 621Matches traffic originating from (ingress) or going to (egress) a given 622virtual function of the current device. 623 624If supported, should work even if the virtual function is not managed by 625the application and thus not associated with a DPDK port ID. Its behavior is 626otherwise similar to `PORT_ID pattern item`_ using VF port ID. 627 628Note this pattern item does not match VF representors traffic which, as 629separate entities, should be addressed through their own port IDs. 630 631- Matches **D** or **E** in `traffic steering`_. 632 633VF Action 634^^^^^^^^^ 635 636Directs matching traffic to a given virtual function of the current device. 637 638Same restrictions as `VF pattern item`_. 639 640- Targets **D** or **E** in `traffic steering`_. 641 642\*_ENCAP actions 643^^^^^^^^^^^^^^^^ 644 645These actions are named according to the protocol they encapsulate traffic 646with (e.g. ``VXLAN_ENCAP``) and using specific parameters (e.g. VNI for 647VXLAN). 648 649While they modify traffic and can be used multiple times (order matters), 650unlike `PORT_ID action`_ and friends, they have no impact on steering. 651 652As described in `actions order and repetition`_ this means they are useless 653if used alone in an action list, the resulting traffic gets dropped unless 654combined with either ``PASSTHRU`` or other endpoint-targeting actions. 655 656\*_DECAP actions 657^^^^^^^^^^^^^^^^ 658 659They perform the reverse of `\*_ENCAP actions`_ by popping protocol headers 660from traffic instead of pushing them. They can be used multiple times as 661well. 662 663Note that using these actions on non-matching traffic results in undefined 664behavior. It is recommended to match the protocol headers to decapsulate on 665the pattern side of a flow rule in order to use these actions or otherwise 666make sure only matching traffic goes through. 667 668Actions Order and Repetition 669~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 670 671Flow rules are currently restricted to at most a single action of each 672supported type, performed in an unpredictable order (or all at once). To 673repeat actions in a predictable fashion, applications have to make rules 674pass-through and use priority levels. 675 676It's now clear that PMD support for chaining multiple non-terminating flow 677rules of varying priority levels is prohibitively difficult to implement 678compared to simply allowing multiple identical actions performed in a 679defined order by a single flow rule. 680 681- This change is required to support protocol encapsulation offloads and the 682 ability to perform them multiple times (e.g. VLAN then VXLAN). 683 684- It makes the ``DUP`` action redundant since multiple ``QUEUE`` actions can 685 be combined for duplication. 686 687- The (non-)terminating property of actions must be discarded. Instead, flow 688 rules themselves must be considered terminating by default (i.e. dropping 689 traffic if there is no specific target) unless a ``PASSTHRU`` action is 690 also specified. 691 692Switching Examples 693------------------ 694 695This section provides practical examples based on the established testpmd 696flow command syntax [2]_, in the context described in `traffic steering`_ 697 698:: 699 700 .-------------. .-------------. .-------------. 701 | hypervisor | | VM 1 | | VM 2 | 702 | application | | application | | application | 703 `--+---+---+--' `----------+--' `--+----------' 704 | | | | | 705 | | `-------------------. | | 706 | `---------. | | | 707 | | | | | 708 .----(A)----. .----(B)----. .----(C)----. | | 709 | port_id 3 | | port_id 4 | | port_id 5 | | | 710 `-----+-----' `-----+-----' `-----+-----' | | 711 | | | | | 712 .-+--. .-----+-----. .-----+-----. .---+--. .--+---. 713 | PF | | VF 1 rep. | | VF 2 rep. | | VF 1 | | VF 2 | 714 `-+--' `-----+-----' `-----+-----' `--(D)-' `-(E)--' 715 | | | | | 716 | | .---------' | | 717 `-----. | | .-----------------' | 718 | | | | .---------------------' 719 | | | | | 720 .--|-------|---|---|---|--. 721 | | | `---|---' | 722 | | `-------' | 723 | `---------. | 724 `------------|------------' 725 | 726 .---(F)----. 727 | physical | 728 | port 0 | 729 `----------' 730 731By default, PF (**A**) can communicate with the physical port it is 732associated with (**F**), while VF 1 (**D**) and VF 2 (**E**) are isolated 733and restricted to communicate with the hypervisor application through their 734respective representors (**B** and **C**) if supported. 735 736Examples in subsequent sections apply to hypervisor applications only and 737are based on port representors **A**, **B** and **C**. 738 739.. [2] `Flow syntax 740 <http://doc.dpdk.org/guides/testpmd_app_ug/testpmd_funcs.html#flow-syntax>`_ 741 742Associating VF 1 with Physical Port 0 743~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 744 745Assign all port traffic (**F**) to VF 1 (**D**) indiscriminately through 746their representors 747 748:: 749 750 flow create 3 ingress pattern / end actions port_id id 4 / end 751 flow create 4 ingress pattern / end actions port_id id 3 / end 752 753More practical example with MAC address restrictions 754 755:: 756 757 flow create 3 ingress 758 pattern eth dst is {VF 1 MAC} / end 759 actions port_id id 4 / end 760 761:: 762 763 flow create 4 ingress 764 pattern eth src is {VF 1 MAC} / end 765 actions port_id id 3 / end 766 767 768Sharing Broadcasts 769~~~~~~~~~~~~~~~~~~ 770 771From outside to PF and VFs 772 773:: 774 775 flow create 3 ingress 776 pattern eth dst is ff:ff:ff:ff:ff:ff / end 777 actions port_id id 3 / port_id id 4 / port_id id 5 / end 778 779Note ``port_id id 3`` is necessary otherwise only VFs would receive matching 780traffic. 781 782From PF to outside and VFs 783 784:: 785 786 flow create 3 egress 787 pattern eth dst is ff:ff:ff:ff:ff:ff / end 788 actions port / port_id id 4 / port_id id 5 / end 789 790From VFs to outside and PF 791 792:: 793 794 flow create 4 ingress 795 pattern eth dst is ff:ff:ff:ff:ff:ff src is {VF 1 MAC} / end 796 actions port_id id 3 / port_id id 5 / end 797 798 flow create 5 ingress 799 pattern eth dst is ff:ff:ff:ff:ff:ff src is {VF 2 MAC} / end 800 actions port_id id 4 / port_id id 4 / end 801 802Similar ``33:33:*`` rules based on known MAC addresses should be added for 803IPv6 traffic. 804 805Encapsulating VF 2 Traffic in VXLAN 806~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 807 808Assuming pass-through flow rules are supported 809 810:: 811 812 flow create 5 ingress 813 pattern eth / end 814 actions vxlan_encap vni 42 / passthru / end 815 816:: 817 818 flow create 5 egress 819 pattern vxlan vni is 42 / end 820 actions vxlan_decap / passthru / end 821 822Here ``passthru`` is needed since as described in `actions order and 823repetition`_, flow rules are otherwise terminating; if supported, a rule 824without a target endpoint will drop traffic. 825 826Without pass-through support, ingress encapsulation on the destination 827endpoint might not be supported and action list must provide one 828 829:: 830 831 flow create 5 ingress 832 pattern eth src is {VF 2 MAC} / end 833 actions vxlan_encap vni 42 / port_id id 3 / end 834 835 flow create 3 ingress 836 pattern vxlan vni is 42 / end 837 actions vxlan_decap / port_id id 5 / end 838