docs/design/vswitchperf_design.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation, AT&T and others.
   4
   5 ======================
   6 VSPERF Design Document
   7 ======================
   8
   9 Intended Audience
  10 =================
  11
  12 This document is intended to aid those who want to modify the vsperf code. Or
  13 to extend it - for example to add support for new traffic generators,
  14 deployment scenarios and so on.
  15
  16 Usage
  17 =====
  18
  19 Example Connectivity to DUT
  20 ---------------------------
  21
  22 Establish connectivity to the VSPERF DUT Linux host, such as the DUT in Pod 3,
  23 by following the steps in `Testbed POD3
  24 <https://wiki.opnfv.org/get_started/pod_3_-_characterize_vswitch_performance>`__
  25
  26 The steps cover booking the DUT and establishing the VSPERF environment.
  27
  28 Example Command Lines
  29 ---------------------
  30
  31 List all the cli options:
  32
  33 .. code-block:: console
  34
  35    $ ./vsperf -h
  36
  37 Run all tests that have ``tput`` in their name - ``phy2phy_tput``, ``pvp_tput`` etc.:
  38
  39 .. code-block:: console
  40
  41    $ ./vsperf --tests 'tput'
  42
  43 As above but override default configuration with settings in '10_custom.conf'.
  44 This is useful as modifying configuration directly in the configuration files
  45 in ``conf/NN_*.py`` shows up as changes under git source control:
  46
  47 .. code-block:: console
  48
  49    $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests 'tput'
  50
  51 Override specific test parameters. Useful for shortening the duration of tests
  52 for development purposes:
  53
  54 .. code-block:: console
  55
  56    $ ./vsperf --test-params 'duration=10;rfc2544_tests=1;pkt_sizes=64' --tests 'pvp_tput'
  57
  58 Typical Test Sequence
  59 =====================
  60
  61 This is a typical flow of control for a test.
  62
  63 .. image:: vsperf.png
  64
  65
  66 Configuration
  67 =============
  68
  69 The conf package contains the configuration files (``*.conf``) for all system
  70 components, it also provides a ``settings`` object that exposes all of these
  71 settings.
  72
  73 Settings are not passed from component to component. Rather they are available
  74 globally to all components once they import the conf package.
  75
  76 .. code-block:: python
  77
  78    from conf import settings
  79    ...
  80    log_file = settings.getValue('LOG_FILE_DEFAULT')
  81
  82 Settings files (``*.conf``) are valid python code so can be set to complex
  83 types such as lists and dictionaries as well as scalar types:
  84
  85 .. code-block:: python
  86
  87    first_packet_size = settings.getValue('PACKET_SIZE_LIST')[0]
  88
  89 Configuration Procedure and Precedence
  90 --------------------------------------
  91
  92 Configuration files follow a strict naming convention that allows them to be
  93 processed in a specific order. All the .conf files are named ``NN_name.conf``,
  94 where NN is a decimal number. The files are processed in order from 00_name.conf
  95 to 99_name.conf so that if the name setting is given in both a lower and higher
  96 numbered conf file then the higher numbered file is the effective setting as it
  97 is processed after the setting in the lower numbered file.
  98
  99 The values in the file specified by ``--conf-file`` takes precedence over all
 100 the other configuration files and does not have to follow the naming
 101 convention.
 102
 103 Configuration of GUEST options
 104 ------------------------------
 105
 106 VSPERF is able to setup scenarios involving a number of VMs in series or in parallel.
 107 All configuration options related to a particular VM instance are defined as
 108 lists and prefixed with ``GUEST_`` label. It is essential, that there is enough
 109 items in all ``GUEST_`` options to cover all VM instances involved in the test.
 110 In case there is not enough items, then VSPERF will use the first item of
 111 particular ``GUEST_`` option to expand the list to required length.
 112
 113 Example of option expansion for 4 VMs:
 114
 115     .. code-block:: python
 116
 117        """
 118        Original values:
 119        """
 120        GUEST_SMP = ['2']
 121        GUEST_MEMORY = ['2048', '4096']
 122
 123        """
 124        Values after automatic expansion:
 125        """
 126        GUEST_SMP = ['2', '2', '2', '2']
 127        GUEST_MEMORY = ['2048', '4096', '2048', '2048']
 128
 129
 130 First option can contain macros starting with ``#`` to generate VM specific values.
 131 These macros can be used only for options of ``list`` or ``str`` types with ``GUEST_``
 132 prefix.
 133
 134 Example of macros and their expnasion for 2 VMs:
 135
 136     .. code-block:: python
 137
 138        """
 139        Original values:
 140        """
 141        GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
 142        GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
 143
 144        """
 145        Values after automatic expansion:
 146        """
 147        GUEST_SHARE_DIR = ['/tmp/qemu0_share', '/tmp/qemu1_share']
 148        GUEST_BRIDGE_IP = ['1.1.1.5/16', '1.1.1.6/16']
 149
 150 Additional examples are available at ``04_vnf.conf``.
 151
 152 Note: In  case, that macro is detected in the first item of the list, then
 153 all other items are ignored and list content is created automatically.
 154
 155 Multiple macros can be used inside one configuration option definition, but macros
 156 cannot be used inside other macros. The only exception is macro ``#VMINDEX``, which
 157 is expanded first and thus it can be used inside other macros.
 158
 159 Following macros are supported:
 160
 161   * ``#VMINDEX`` - it is replaced by index of VM being executed; This macro
 162     is expanded first, so it can be used inside other macros.
 163
 164     Example:
 165
 166     .. code-block:: python
 167
 168        GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
 169
 170   * ``#MAC(mac_address[, step])`` - it will iterate given ``mac_address``
 171     with optional ``step``. In case that step is not defined, then it is set to 1.
 172     It means, that first VM will use the value of ``mac_address``, second VM
 173     value of ``mac_address`` increased by ``step``, etc.
 174
 175     Example:
 176
 177     .. code-block:: python
 178
 179        GUEST_NICS = [[{'mac' : '#MAC(00:00:00:00:00:01,2)'}]]
 180
 181   * ``#IP(ip_address[, step])`` - it will iterate given ``ip_address``
 182     with optional ``step``. In case that step is not defined, then it is set to 1.
 183     It means, that first VM will use the value of ``ip_address``, second VM
 184     value of ``ip_address`` increased by ``step``, etc.
 185
 186     Example:
 187
 188     .. code-block:: python
 189
 190        GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
 191
 192   * ``#EVAL(expression)`` - it will evaluate given ``expression`` as python code;
 193     Only simple expressions should be used. Call of the functions is not supported.
 194
 195     Example:
 196
 197     .. code-block:: python
 198
 199        GUEST_CORE_BINDING = [('#EVAL(6+2*#VMINDEX)', '#EVAL(7+2*#VMINDEX)')]
 200
 201 Other Configuration
 202 -------------------
 203
 204 ``conf.settings`` also loads configuration from the command line and from the environment.
 205
 206 PXP Deployment
 207 ==============
 208
 209 Every testcase uses one of the supported deployment scenarios to setup test environment.
 210 The controller responsible for a given scenario configures flows in the vswitch to route
 211 traffic among physical interfaces connected to the traffic generator and virtual
 212 machines. VSPERF supports several deployments including PXP deployment, which can
 213 setup various scenarios with multiple VMs.
 214
 215 These scenarios are realized by VswitchControllerPXP class, which can configure and
 216 execute given number of VMs in serial or parallel configurations. Every VM can be
 217 configured with just one or an even number of interfaces. In case that VM has more than
 218 2 interfaces, then traffic is properly routed among pairs of interfaces.
 219
 220 Example of traffic routing for VM with 4 NICs in serial configuration:
 221
 222 .. code-block:: console
 223
 224                  +------------------------------------------+
 225                  |  VM with 4 NICs                          |
 226                  |  +---------------+    +---------------+  |
 227                  |  |  Application  |    |  Application  |  |
 228                  |  +---------------+    +---------------+  |
 229                  |      ^       |            ^       |      |
 230                  |      |       v            |       v      |
 231                  |  +---------------+    +---------------+  |
 232                  |  | logical ports |    | logical ports |  |
 233                  |  |   0       1   |    |   2       3   |  |
 234                  +--+---------------+----+---------------+--+
 235                         ^       :            ^       :
 236                         |       |            |       |
 237                         :       v            :       v
 238         +-----------+---------------+----+---------------+----------+
 239         | vSwitch   |   0       1   |    |   2       3   |          |
 240         |           | logical ports |    | logical ports |          |
 241         | previous  +---------------+    +---------------+   next   |
 242         | VM or PHY     ^       |            ^       |     VM or PHY|
 243         |   port   -----+       +------------+       +--->   port   |
 244         +-----------------------------------------------------------+
 245
 246 It is also possible to define different number of interfaces for each VM to better
 247 simulate real scenarios.
 248
 249 Example of traffic routing for 2 VMs in serial configuration, where 1st VM has
 250 4 NICs and 2nd VM 2 NICs:
 251
 252 .. code-block:: console
 253
 254            +------------------------------------------+  +---------------------+
 255            |  1st VM with 4 NICs                      |  |  2nd VM with 2 NICs |
 256            |  +---------------+    +---------------+  |  |  +---------------+  |
 257            |  |  Application  |    |  Application  |  |  |  |  Application  |  |
 258            |  +---------------+    +---------------+  |  |  +---------------+  |
 259            |      ^       |            ^       |      |  |      ^       |      |
 260            |      |       v            |       v      |  |      |       v      |
 261            |  +---------------+    +---------------+  |  |  +---------------+  |
 262            |  | logical ports |    | logical ports |  |  |  | logical ports |  |
 263            |  |   0       1   |    |   2       3   |  |  |  |   0       1   |  |
 264            +--+---------------+----+---------------+--+  +--+---------------+--+
 265                   ^       :            ^       :               ^       :
 266                   |       |            |       |               |       |
 267                   :       v            :       v               :       v
 268   +-----------+---------------+----+---------------+-------+---------------+----------+
 269   | vSwitch   |   0       1   |    |   2       3   |       |   4       5   |          |
 270   |           | logical ports |    | logical ports |       | logical ports |          |
 271   | previous  +---------------+    +---------------+       +---------------+   next   |
 272   | VM or PHY     ^       |            ^       |               ^       |     VM or PHY|
 273   |   port   -----+       +------------+       +---------------+       +---->  port   |
 274   +-----------------------------------------------------------------------------------+
 275
 276 The number of VMs involved in the test and the type of their connection is defined
 277 by deployment name as follows:
 278
 279   * ``pvvp[number]`` - configures scenario with VMs connected in series with
 280     optional ``number`` of VMs. In case that ``number`` is not specified, then
 281     2 VMs will be used.
 282
 283     Example of 2 VMs in a serial configuration:
 284
 285     .. code-block:: console
 286
 287        +----------------------+  +----------------------+
 288        |   1st VM             |  |   2nd VM             |
 289        |   +---------------+  |  |   +---------------+  |
 290        |   |  Application  |  |  |   |  Application  |  |
 291        |   +---------------+  |  |   +---------------+  |
 292        |       ^       |      |  |       ^       |      |
 293        |       |       v      |  |       |       v      |
 294        |   +---------------+  |  |   +---------------+  |
 295        |   | logical ports |  |  |   | logical ports |  |
 296        |   |   0       1   |  |  |   |   0       1   |  |
 297        +---+---------------+--+  +---+---------------+--+
 298                ^       :                 ^       :
 299                |       |                 |       |
 300                :       v                 :       v
 301        +---+---------------+---------+---------------+--+
 302        |   |   0       1   |         |   3       4   |  |
 303        |   | logical ports | vSwitch | logical ports |  |
 304        |   +---------------+         +---------------+  |
 305        |       ^       |                 ^       |      |
 306        |       |       +-----------------+       v      |
 307        |   +----------------------------------------+   |
 308        |   |              physical ports            |   |
 309        |   |      0                         1       |   |
 310        +---+----------------------------------------+---+
 311                   ^                         :
 312                   |                         |
 313                   :                         v
 314        +------------------------------------------------+
 315        |                                                |
 316        |                traffic generator               |
 317        |                                                |
 318        +------------------------------------------------+
 319
 320   * ``pvpv[number]`` - configures scenario with VMs connected in parallel with
 321     optional ``number`` of VMs. In case that ``number`` is not specified, then
 322     2 VMs will be used. Multistream feature is used to route traffic to particular
 323     VMs (or NIC pairs of every VM). It means, that VSPERF will enable multistream
 324     feaure and sets the number of streams to the number of VMs and their NIC
 325     pairs. Traffic will be dispatched based on Stream Type, i.e. by UDP port,
 326     IP address or MAC address.
 327
 328     Example of 2 VMs in a parallel configuration, where traffic is dispatched
 329         based on the UDP port.
 330
 331     .. code-block:: console
 332
 333        +----------------------+  +----------------------+
 334        |   1st VM             |  |   2nd VM             |
 335        |   +---------------+  |  |   +---------------+  |
 336        |   |  Application  |  |  |   |  Application  |  |
 337        |   +---------------+  |  |   +---------------+  |
 338        |       ^       |      |  |       ^       |      |
 339        |       |       v      |  |       |       v      |
 340        |   +---------------+  |  |   +---------------+  |
 341        |   | logical ports |  |  |   | logical ports |  |
 342        |   |   0       1   |  |  |   |   0       1   |  |
 343        +---+---------------+--+  +---+---------------+--+
 344                ^       :                 ^       :
 345                |       |                 |       |
 346                :       v                 :       v
 347        +---+---------------+---------+---------------+--+
 348        |   |   0       1   |         |   3       4   |  |
 349        |   | logical ports | vSwitch | logical ports |  |
 350        |   +---------------+         +---------------+  |
 351        |      ^         |                 ^       :     |
 352        |      |     ......................:       :     |
 353        |  UDP | UDP :   |                         :     |
 354        |  port| port:   +--------------------+    :     |
 355        |   0  |  1  :                        |    :     |
 356        |      |     :                        v    v     |
 357        |   +----------------------------------------+   |
 358        |   |              physical ports            |   |
 359        |   |    0                               1   |   |
 360        +---+----------------------------------------+---+
 361                 ^                               :
 362                 |                               |
 363                 :                               v
 364        +------------------------------------------------+
 365        |                                                |
 366        |                traffic generator               |
 367        |                                                |
 368        +------------------------------------------------+
 369
 370
 371 PXP deployment is backward compatible with PVP deployment, where ``pvp`` is
 372 an alias for ``pvvp1`` and it executes just one VM.
 373
 374 The number of interfaces used by VMs is defined by configuration option
 375 ``GUEST_NICS_NR``. In case that more than one pair of interfaces is defined
 376 for VM, then:
 377
 378     * for ``pvvp`` (serial) scenario every NIC pair is connected in serial
 379       before connection to next VM is created
 380     * for ``pvpv`` (parallel) scenario every NIC pair is directly connected
 381       to the physical ports and unique traffic stream is assigned to it
 382
 383 Examples:
 384
 385     * Deployment ``pvvp10`` will start 10 VMs and connects them in series
 386     * Deployment ``pvpv4`` will start 4 VMs and connects them in parallel
 387     * Deployment ``pvpv1`` and GUEST_NICS_NR = [4] will start 1 VM with
 388       4 interfaces and every NIC pair is directly connected to the
 389       physical ports
 390     * Deployment ``pvvp`` and GUEST_NICS_NR = [2, 4] will start 2 VMs;
 391       1st VM will have 2 interfaces and 2nd VM 4 interfaces. These interfaces
 392       will be connected in serial, i.e. traffic will flow as follows:
 393       PHY1 -> VM1_1 -> VM1_2 -> VM2_1 -> VM2_2 -> VM2_3 -> VM2_4 -> PHY2
 394
 395 Note: In case that only 1 or more than 2 NICs are configured for VM,
 396 then ``testpmd`` should be used as forwarding application inside the VM.
 397 As it is able to forward traffic between multiple VM NIC pairs.
 398
 399 Note: In case of ``linux_bridge``, all NICs are connected to the same
 400 bridge inside the VM.
 401
 402 VM, vSwitch, Traffic Generator Independence
 403 ===========================================
 404
 405 VSPERF supports different vSwithes, Traffic Generators, VNFs
 406 and Forwarding Applications by using standard object-oriented polymorphism:
 407
 408   * Support for vSwitches is implemented by a class inheriting from IVSwitch.
 409   * Support for Traffic Generators is implemented by a class inheriting from
 410     ITrafficGenerator.
 411   * Support for VNF is implemented by a class inheriting from IVNF.
 412   * Support for Forwarding Applications is implemented by a class inheriting
 413     from IPktFwd.
 414
 415 By dealing only with the abstract interfaces the core framework can support
 416 many implementations of different vSwitches, Traffic Generators, VNFs
 417 and Forwarding Applications.
 418
 419 IVSwitch
 420 --------
 421
 422 .. code-block:: python
 423
 424     class IVSwitch:
 425       start(self)
 426       stop(self)
 427       add_switch(switch_name)
 428       del_switch(switch_name)
 429       add_phy_port(switch_name)
 430       add_vport(switch_name)
 431       get_ports(switch_name)
 432       del_port(switch_name, port_name)
 433       add_flow(switch_name, flow)
 434       del_flow(switch_name, flow=None)
 435
 436 ITrafficGenerator
 437 -----------------
 438
 439 .. code-block:: python
 440
 441     class ITrafficGenerator:
 442       connect()
 443       disconnect()
 444
 445       send_burst_traffic(traffic, numpkts, time, framerate)
 446
 447       send_cont_traffic(traffic, time, framerate)
 448       start_cont_traffic(traffic, time, framerate)
 449       stop_cont_traffic(self):
 450
 451       send_rfc2544_throughput(traffic, tests, duration, lossrate)
 452       start_rfc2544_throughput(traffic, tests, duration, lossrate)
 453       wait_rfc2544_throughput(self)
 454
 455       send_rfc2544_back2back(traffic, tests, duration, lossrate)
 456       start_rfc2544_back2back(traffic, , tests, duration, lossrate)
 457       wait_rfc2544_back2back()
 458
 459 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
 460
 461 IVnf
 462 ----
 463
 464 .. code-block:: python
 465
 466     class IVnf:
 467       start(memory, cpus,
 468             monitor_path, shared_path_host,
 469             shared_path_guest, guest_prompt)
 470       stop()
 471       execute(command)
 472       wait(guest_prompt)
 473       execute_and_wait (command)
 474
 475 IPktFwd
 476 --------
 477
 478   .. code-block:: python
 479
 480     class IPktFwd:
 481         start()
 482         stop()
 483
 484
 485 Controllers
 486 -----------
 487
 488 Controllers are used in conjunction with abstract interfaces as way
 489 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
 490 and Forwarding Applications from other components.
 491
 492 The controlled classes provide basic primitive operations. The Controllers
 493 sequence and co-ordinate these primitive operation in to useful actions. For
 494 instance the vswitch_controller_p2p can be used to bring any vSwitch (that
 495 implements the primitives defined in IVSwitch) into the configuration required
 496 by the Phy-to-Phy  Deployment Scenario.
 497
 498 In order to support a new vSwitch only a new implementation of IVSwitch needs
 499 be created for the new vSwitch to be capable of fulfilling all the Deployment
 500 Scenarios provided for by existing or future vSwitch Controllers.
 501
 502 Similarly if a new Deployment Scenario is required it only needs to be written
 503 once as a new vSwitch Controller and it will immediately be capable of
 504 controlling all existing and future vSwitches in to that Deployment Scenario.
 505
 506 Similarly the Traffic Controllers can be used to co-ordinate basic operations
 507 provided by implementers of ITrafficGenerator to provide useful tests. Though
 508 traffic generators generally already implement full test cases i.e. they both
 509 generate suitable traffic and analyse returned traffic in order to implement a
 510 test which has typically been predefined in an RFC document. However the
 511 Traffic Controller class allows for the possibility of further enhancement -
 512 such as iterating over tests for various packet sizes or creating new tests.
 513
 514 Traffic Controller's Role
 515 -------------------------
 516
 517 .. image:: traffic_controller.png
 518
 519
 520 Loader & Component Factory
 521 --------------------------
 522
 523 The working of the Loader package (which is responsible for *finding* arbitrary
 524 classes based on configuration data) and the Component Factory which is
 525 responsible for *choosing* the correct class for a particular situation - e.g.
 526 Deployment Scenario can be seen in this diagram.
 527
 528 .. image:: factory_and_loader.png
 529
 530 Routing Tables
 531 ==============
 532
 533 Vsperf uses a standard set of routing tables in order to allow tests to easily
 534 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
 535 Frame Modification requirements.
 536
 537 .. code-block:: console
 538
 539       +--------------+
 540       |              |
 541       | Table 0      |  table#0 - Match table. Flows designed to force 5 & 10
 542       |              |  tuple matches go here.
 543       |              |
 544       +--------------+
 545              |
 546              |
 547              v
 548       +--------------+  table#1 - Routing table. Flow entries to forward
 549       |              |  packets between ports goes here.
 550       | Table 1      |  The chosen port is communicated to subsequent tables by
 551       |              |  setting the metadata value to the egress port number.
 552       |              |  Generally this table is set-up by by the
 553       +--------------+  vSwitchController.
 554              |
 555              |
 556              v
 557       +--------------+  table#2 - Frame modification table. Frame modification
 558       |              |  flow rules are isolated in this table so that they can
 559       | Table 2      |  be turned on or off without affecting the routing or
 560       |              |  tuple-matching flow rules. This allows the frame
 561       |              |  modification and tuple matching required by the tests
 562       |              |  in the VSWITCH PERFORMANCE FOR TELCO NFV test
 563       +--------------+  specification to be independent of the Deployment
 564              |          Scenario set up by the vSwitchController.
 565              |
 566              v
 567       +--------------+
 568       |              |
 569       | Table 3      |  table#3 - Egress table. Egress packets on the ports
 570       |              |  setup in Table 1.
 571       +--------------+
 572
 573