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 'TRAFFICGEN_DURATION=10;TRAFFICGEN_RFC2544_TESTS=1;' \
  57                             'TRAFFICGEN_PKT_SIZES=(64,)' pvp_tput
  58
  59 Typical Test Sequence
  60 =====================
  61
  62 This is a typical flow of control for a test.
  63
  64 .. image:: vsperf.png
  65
  66
  67 Configuration
  68 =============
  69
  70 The conf package contains the configuration files (``*.conf``) for all system
  71 components, it also provides a ``settings`` object that exposes all of these
  72 settings.
  73
  74 Settings are not passed from component to component. Rather they are available
  75 globally to all components once they import the conf package.
  76
  77 .. code-block:: python
  78
  79    from conf import settings
  80    ...
  81    log_file = settings.getValue('LOG_FILE_DEFAULT')
  82
  83 Settings files (``*.conf``) are valid python code so can be set to complex
  84 types such as lists and dictionaries as well as scalar types:
  85
  86 .. code-block:: python
  87
  88    first_packet_size = settings.getValue('PACKET_SIZE_LIST')[0]
  89
  90 Configuration Procedure and Precedence
  91 --------------------------------------
  92
  93 Configuration files follow a strict naming convention that allows them to be
  94 processed in a specific order. All the .conf files are named ``NN_name.conf``,
  95 where NN is a decimal number. The files are processed in order from 00_name.conf
  96 to 99_name.conf so that if the name setting is given in both a lower and higher
  97 numbered conf file then the higher numbered file is the effective setting as it
  98 is processed after the setting in the lower numbered file.
  99
 100 The values in the file specified by ``--conf-file`` takes precedence over all
 101 the other configuration files and does not have to follow the naming
 102 convention.
 103
 104 Configuration of PATHS dictionary
 105 ---------------------------------
 106
 107 VSPERF uses external tools like Open vSwitch and Qemu for execution of testcases. These
 108 tools may be downloaded and built automatically by `VSPERF installation scripts`_
 109 or installed manually by user from binary packages. It is also possible to use a combination
 110 of both approaches, but it is essential to correctly set paths to all required tools.
 111 These paths are stored within a PATHS dictionary, which is evaluated before execution
 112 of each testcase, in order to setup testcase specific environment. Values selected for testcase
 113 execution are internally stored inside TOOLS dictionary, which is used by VSPERF to execute
 114 external tools, load kernel modules, etc.
 115
 116 The default configuration of PATHS dictionary is spread among three different configuration files
 117 to follow logical grouping of configuration options. Basic description of PATHS dictionary
 118 is placed inside ``conf/00_common.conf``. The configuration specific to DPDK and vswitches
 119 is located at ``conf/02_vswitch.conf``. The last part related to the Qemu is defined inside
 120 ``conf/04_vnf.conf``. Default configuration values can be used in case, that all required
 121 tools were downloaded and built automatically by vsperf itself. In case, that some of
 122 tools were installed manually from binary packages, then it will be necessary to modify
 123 the content of PATHS dictionary accordingly.
 124
 125 Dictionary has a specific section of configuration options for every tool type, it means:
 126
 127     * ``PATHS['vswitch']`` - contains a separete dictionary for each of vswitches supported by VSPEF
 128
 129       Example:
 130
 131       .. code-block:: python
 132
 133          PATHS['vswitch'] = {
 134             'OvsDpdkVhost': { ... },
 135             'OvsVanilla' : { ... },
 136             ...
 137          }
 138
 139     * ``PATHS['dpdk']`` - contains paths to the dpdk sources, kernel modules and tools (e.g. testpmd)
 140
 141       Example:
 142
 143       .. code-block:: python
 144
 145          PATHS['dpdk'] = {
 146             'type' : 'src',
 147             'src': {
 148                 'path': os.path.join(ROOT_DIR, 'src/dpdk/dpdk/'),
 149                 'modules' : ['uio', os.path.join(RTE_TARGET, 'kmod/igb_uio.ko')],
 150                 'bind-tool': 'tools/dpdk*bind.py',
 151                 'testpmd': os.path.join(RTE_TARGET, 'app', 'testpmd'),
 152             },
 153             ...
 154          }
 155
 156     * ``PATHS['qemu']`` - contains paths to the qemu sources and executable file
 157
 158       Example:
 159
 160       .. code-block:: python
 161
 162          PATHS['qemu'] = {
 163              'type' : 'bin',
 164              'bin': {
 165                  'qemu-system': 'qemu-system-x86_64'
 166              },
 167              ...
 168          }
 169
 170 Every section specific to the particular vswitch, dpdk or qemu may contain following types
 171 of configuration options:
 172
 173     * option ``type`` - is a string, which defines the type of configured paths ('src' or 'bin')
 174       to be selected for a given section:
 175
 176         * value ``src`` means, that VSPERF will use vswitch, DPDK or QEMU built from sources
 177           e.g. by execution of ``systems/build_base_machine.sh`` script during VSPERF
 178           installation
 179
 180         * value ``bin`` means, that VSPERF will use vswitch, DPDK or QEMU binaries installed
 181           directly in the operating system, e.g. via OS specific packaging system
 182
 183     * option ``path`` - is a string with a valid system path; Its content is checked for
 184       existence, prefixed with section name and stored into TOOLS for later use
 185       e.g. ``TOOLS['dpdk_src']`` or ``TOOLS['vswitch_src']``
 186
 187     * option ``modules`` - is list of strings with names of kernel modules; Every module name
 188       from given list is checked for a '.ko' suffix. In case that it matches and if it is not
 189       an absolute path to the module, then module name is prefixed with value of ``path``
 190       option defined for the same section
 191
 192       Example:
 193
 194       .. code-block:: python
 195
 196          """
 197          snippet of PATHS definition from the configuration file:
 198          """
 199          PATHS['vswitch'] = {
 200              'OvsVanilla' = {
 201                  'type' : 'src',
 202                  'src': {
 203                      'path': '/tmp/vsperf/src_vanilla/ovs/ovs/',
 204                      'modules' : ['datapath/linux/openvswitch.ko'],
 205                      ...
 206                  },
 207                  ...
 208              }
 209              ...
 210          }
 211
 212          """
 213          Final content of TOOLS dictionary used during runtime:
 214          """
 215          TOOLS['vswitch_modules'] = ['/tmp/vsperf/src_vanilla/ovs/ovs/datapath/linux/openvswitch.ko']
 216
 217     * all other options are strings with names and paths to specific tools; If a given string
 218       contains a relative path and option ``path`` is defined for a given section, then string
 219       content will be prefixed with content of the ``path``. Otherwise the name of the tool will be
 220       searched within standard system directories. In case that filename contains OS specific
 221       wildcards, then they will be expanded to the real path. At the end of the processing, every
 222       absolute path will be checked for its existence. In case that temporary path (i.e. path with
 223       a ``_tmp`` suffix) does not exist, then log will be written and vsperf will continue. If any
 224       other path will not exist, then vsperf execution will be terminated with a runtime error.
 225
 226       Example:
 227
 228       .. code-block:: python
 229
 230          """
 231          snippet of PATHS definition from the configuration file:
 232          """
 233          PATHS['vswitch'] = {
 234              'OvsDpdkVhost': {
 235                  'type' : 'src',
 236                  'src': {
 237                      'path': '/tmp/vsperf/src_vanilla/ovs/ovs/',
 238                      'ovs-vswitchd': 'vswitchd/ovs-vswitchd',
 239                      'ovsdb-server': 'ovsdb/ovsdb-server',
 240                      ...
 241                  }
 242                  ...
 243              }
 244              ...
 245          }
 246
 247          """
 248          Final content of TOOLS dictionary used during runtime:
 249          """
 250          TOOLS['ovs-vswitchd'] = '/tmp/vsperf/src_vanilla/ovs/ovs/vswitchd/ovs-vswitchd'
 251          TOOLS['ovsdb-server'] = '/tmp/vsperf/src_vanilla/ovs/ovs/ovsdb/ovsdb-server'
 252
 253 Note: In case that ``bin`` type is set for DPDK, then ``TOOLS['dpdk_src']`` will be set to
 254 the value of ``PATHS['dpdk']['src']['path']``. The reason is, that VSPERF uses downloaded
 255 DPDK sources to copy DPDK and testpmd into the GUEST, where testpmd is built. In case,
 256 that DPDK sources are not available, then vsperf will continue with test execution,
 257 but testpmd can't be used as a guest loopback. This is useful in case, that other guest
 258 loopback applications (e.g. buildin or l2fwd) are used.
 259
 260 .. _VSPERF installation scripts: http://artifacts.opnfv.org/vswitchperf/docs/configguide/installation.html#other-requirements
 261
 262 Configuration of GUEST options
 263 ------------------------------
 264
 265 VSPERF is able to setup scenarios involving a number of VMs in series or in parallel.
 266 All configuration options related to a particular VM instance are defined as
 267 lists and prefixed with ``GUEST_`` label. It is essential, that there is enough
 268 items in all ``GUEST_`` options to cover all VM instances involved in the test.
 269 In case there is not enough items, then VSPERF will use the first item of
 270 particular ``GUEST_`` option to expand the list to required length.
 271
 272 Example of option expansion for 4 VMs:
 273
 274     .. code-block:: python
 275
 276        """
 277        Original values:
 278        """
 279        GUEST_SMP = ['2']
 280        GUEST_MEMORY = ['2048', '4096']
 281
 282        """
 283        Values after automatic expansion:
 284        """
 285        GUEST_SMP = ['2', '2', '2', '2']
 286        GUEST_MEMORY = ['2048', '4096', '2048', '2048']
 287
 288
 289 First option can contain macros starting with ``#`` to generate VM specific values.
 290 These macros can be used only for options of ``list`` or ``str`` types with ``GUEST_``
 291 prefix.
 292
 293 Example of macros and their expnasion for 2 VMs:
 294
 295     .. code-block:: python
 296
 297        """
 298        Original values:
 299        """
 300        GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
 301        GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
 302
 303        """
 304        Values after automatic expansion:
 305        """
 306        GUEST_SHARE_DIR = ['/tmp/qemu0_share', '/tmp/qemu1_share']
 307        GUEST_BRIDGE_IP = ['1.1.1.5/16', '1.1.1.6/16']
 308
 309 Additional examples are available at ``04_vnf.conf``.
 310
 311 Note: In  case, that macro is detected in the first item of the list, then
 312 all other items are ignored and list content is created automatically.
 313
 314 Multiple macros can be used inside one configuration option definition, but macros
 315 cannot be used inside other macros. The only exception is macro ``#VMINDEX``, which
 316 is expanded first and thus it can be used inside other macros.
 317
 318 Following macros are supported:
 319
 320   * ``#VMINDEX`` - it is replaced by index of VM being executed; This macro
 321     is expanded first, so it can be used inside other macros.
 322
 323     Example:
 324
 325     .. code-block:: python
 326
 327        GUEST_SHARE_DIR = ['/tmp/qemu#VMINDEX_share']
 328
 329   * ``#MAC(mac_address[, step])`` - it will iterate given ``mac_address``
 330     with optional ``step``. In case that step is not defined, then it is set to 1.
 331     It means, that first VM will use the value of ``mac_address``, second VM
 332     value of ``mac_address`` increased by ``step``, etc.
 333
 334     Example:
 335
 336     .. code-block:: python
 337
 338        GUEST_NICS = [[{'mac' : '#MAC(00:00:00:00:00:01,2)'}]]
 339
 340   * ``#IP(ip_address[, step])`` - it will iterate given ``ip_address``
 341     with optional ``step``. In case that step is not defined, then it is set to 1.
 342     It means, that first VM will use the value of ``ip_address``, second VM
 343     value of ``ip_address`` increased by ``step``, etc.
 344
 345     Example:
 346
 347     .. code-block:: python
 348
 349        GUEST_BRIDGE_IP = ['#IP(1.1.1.5)/16']
 350
 351   * ``#EVAL(expression)`` - it will evaluate given ``expression`` as python code;
 352     Only simple expressions should be used. Call of the functions is not supported.
 353
 354     Example:
 355
 356     .. code-block:: python
 357
 358        GUEST_CORE_BINDING = [('#EVAL(6+2*#VMINDEX)', '#EVAL(7+2*#VMINDEX)')]
 359
 360 Other Configuration
 361 -------------------
 362
 363 ``conf.settings`` also loads configuration from the command line and from the environment.
 364
 365 PXP Deployment
 366 ==============
 367
 368 Every testcase uses one of the supported deployment scenarios to setup test environment.
 369 The controller responsible for a given scenario configures flows in the vswitch to route
 370 traffic among physical interfaces connected to the traffic generator and virtual
 371 machines. VSPERF supports several deployments including PXP deployment, which can
 372 setup various scenarios with multiple VMs.
 373
 374 These scenarios are realized by VswitchControllerPXP class, which can configure and
 375 execute given number of VMs in serial or parallel configurations. Every VM can be
 376 configured with just one or an even number of interfaces. In case that VM has more than
 377 2 interfaces, then traffic is properly routed among pairs of interfaces.
 378
 379 Example of traffic routing for VM with 4 NICs in serial configuration:
 380
 381 .. code-block:: console
 382
 383                  +------------------------------------------+
 384                  |  VM with 4 NICs                          |
 385                  |  +---------------+    +---------------+  |
 386                  |  |  Application  |    |  Application  |  |
 387                  |  +---------------+    +---------------+  |
 388                  |      ^       |            ^       |      |
 389                  |      |       v            |       v      |
 390                  |  +---------------+    +---------------+  |
 391                  |  | logical ports |    | logical ports |  |
 392                  |  |   0       1   |    |   2       3   |  |
 393                  +--+---------------+----+---------------+--+
 394                         ^       :            ^       :
 395                         |       |            |       |
 396                         :       v            :       v
 397         +-----------+---------------+----+---------------+----------+
 398         | vSwitch   |   0       1   |    |   2       3   |          |
 399         |           | logical ports |    | logical ports |          |
 400         | previous  +---------------+    +---------------+   next   |
 401         | VM or PHY     ^       |            ^       |     VM or PHY|
 402         |   port   -----+       +------------+       +--->   port   |
 403         +-----------------------------------------------------------+
 404
 405 It is also possible to define different number of interfaces for each VM to better
 406 simulate real scenarios.
 407
 408 Example of traffic routing for 2 VMs in serial configuration, where 1st VM has
 409 4 NICs and 2nd VM 2 NICs:
 410
 411 .. code-block:: console
 412
 413            +------------------------------------------+  +---------------------+
 414            |  1st VM with 4 NICs                      |  |  2nd VM with 2 NICs |
 415            |  +---------------+    +---------------+  |  |  +---------------+  |
 416            |  |  Application  |    |  Application  |  |  |  |  Application  |  |
 417            |  +---------------+    +---------------+  |  |  +---------------+  |
 418            |      ^       |            ^       |      |  |      ^       |      |
 419            |      |       v            |       v      |  |      |       v      |
 420            |  +---------------+    +---------------+  |  |  +---------------+  |
 421            |  | logical ports |    | logical ports |  |  |  | logical ports |  |
 422            |  |   0       1   |    |   2       3   |  |  |  |   0       1   |  |
 423            +--+---------------+----+---------------+--+  +--+---------------+--+
 424                   ^       :            ^       :               ^       :
 425                   |       |            |       |               |       |
 426                   :       v            :       v               :       v
 427   +-----------+---------------+----+---------------+-------+---------------+----------+
 428   | vSwitch   |   0       1   |    |   2       3   |       |   4       5   |          |
 429   |           | logical ports |    | logical ports |       | logical ports |          |
 430   | previous  +---------------+    +---------------+       +---------------+   next   |
 431   | VM or PHY     ^       |            ^       |               ^       |     VM or PHY|
 432   |   port   -----+       +------------+       +---------------+       +---->  port   |
 433   +-----------------------------------------------------------------------------------+
 434
 435 The number of VMs involved in the test and the type of their connection is defined
 436 by deployment name as follows:
 437
 438   * ``pvvp[number]`` - configures scenario with VMs connected in series with
 439     optional ``number`` of VMs. In case that ``number`` is not specified, then
 440     2 VMs will be used.
 441
 442     Example of 2 VMs in a serial configuration:
 443
 444     .. code-block:: console
 445
 446        +----------------------+  +----------------------+
 447        |   1st VM             |  |   2nd VM             |
 448        |   +---------------+  |  |   +---------------+  |
 449        |   |  Application  |  |  |   |  Application  |  |
 450        |   +---------------+  |  |   +---------------+  |
 451        |       ^       |      |  |       ^       |      |
 452        |       |       v      |  |       |       v      |
 453        |   +---------------+  |  |   +---------------+  |
 454        |   | logical ports |  |  |   | logical ports |  |
 455        |   |   0       1   |  |  |   |   0       1   |  |
 456        +---+---------------+--+  +---+---------------+--+
 457                ^       :                 ^       :
 458                |       |                 |       |
 459                :       v                 :       v
 460        +---+---------------+---------+---------------+--+
 461        |   |   0       1   |         |   3       4   |  |
 462        |   | logical ports | vSwitch | logical ports |  |
 463        |   +---------------+         +---------------+  |
 464        |       ^       |                 ^       |      |
 465        |       |       +-----------------+       v      |
 466        |   +----------------------------------------+   |
 467        |   |              physical ports            |   |
 468        |   |      0                         1       |   |
 469        +---+----------------------------------------+---+
 470                   ^                         :
 471                   |                         |
 472                   :                         v
 473        +------------------------------------------------+
 474        |                                                |
 475        |                traffic generator               |
 476        |                                                |
 477        +------------------------------------------------+
 478
 479   * ``pvpv[number]`` - configures scenario with VMs connected in parallel with
 480     optional ``number`` of VMs. In case that ``number`` is not specified, then
 481     2 VMs will be used. Multistream feature is used to route traffic to particular
 482     VMs (or NIC pairs of every VM). It means, that VSPERF will enable multistream
 483     feaure and sets the number of streams to the number of VMs and their NIC
 484     pairs. Traffic will be dispatched based on Stream Type, i.e. by UDP port,
 485     IP address or MAC address.
 486
 487     Example of 2 VMs in a parallel configuration, where traffic is dispatched
 488         based on the UDP port.
 489
 490     .. code-block:: console
 491
 492        +----------------------+  +----------------------+
 493        |   1st VM             |  |   2nd VM             |
 494        |   +---------------+  |  |   +---------------+  |
 495        |   |  Application  |  |  |   |  Application  |  |
 496        |   +---------------+  |  |   +---------------+  |
 497        |       ^       |      |  |       ^       |      |
 498        |       |       v      |  |       |       v      |
 499        |   +---------------+  |  |   +---------------+  |
 500        |   | logical ports |  |  |   | logical ports |  |
 501        |   |   0       1   |  |  |   |   0       1   |  |
 502        +---+---------------+--+  +---+---------------+--+
 503                ^       :                 ^       :
 504                |       |                 |       |
 505                :       v                 :       v
 506        +---+---------------+---------+---------------+--+
 507        |   |   0       1   |         |   3       4   |  |
 508        |   | logical ports | vSwitch | logical ports |  |
 509        |   +---------------+         +---------------+  |
 510        |      ^         |                 ^       :     |
 511        |      |     ......................:       :     |
 512        |  UDP | UDP :   |                         :     |
 513        |  port| port:   +--------------------+    :     |
 514        |   0  |  1  :                        |    :     |
 515        |      |     :                        v    v     |
 516        |   +----------------------------------------+   |
 517        |   |              physical ports            |   |
 518        |   |    0                               1   |   |
 519        +---+----------------------------------------+---+
 520                 ^                               :
 521                 |                               |
 522                 :                               v
 523        +------------------------------------------------+
 524        |                                                |
 525        |                traffic generator               |
 526        |                                                |
 527        +------------------------------------------------+
 528
 529
 530 PXP deployment is backward compatible with PVP deployment, where ``pvp`` is
 531 an alias for ``pvvp1`` and it executes just one VM.
 532
 533 The number of interfaces used by VMs is defined by configuration option
 534 ``GUEST_NICS_NR``. In case that more than one pair of interfaces is defined
 535 for VM, then:
 536
 537     * for ``pvvp`` (serial) scenario every NIC pair is connected in serial
 538       before connection to next VM is created
 539     * for ``pvpv`` (parallel) scenario every NIC pair is directly connected
 540       to the physical ports and unique traffic stream is assigned to it
 541
 542 Examples:
 543
 544     * Deployment ``pvvp10`` will start 10 VMs and connects them in series
 545     * Deployment ``pvpv4`` will start 4 VMs and connects them in parallel
 546     * Deployment ``pvpv1`` and GUEST_NICS_NR = [4] will start 1 VM with
 547       4 interfaces and every NIC pair is directly connected to the
 548       physical ports
 549     * Deployment ``pvvp`` and GUEST_NICS_NR = [2, 4] will start 2 VMs;
 550       1st VM will have 2 interfaces and 2nd VM 4 interfaces. These interfaces
 551       will be connected in serial, i.e. traffic will flow as follows:
 552       PHY1 -> VM1_1 -> VM1_2 -> VM2_1 -> VM2_2 -> VM2_3 -> VM2_4 -> PHY2
 553
 554 Note: In case that only 1 or more than 2 NICs are configured for VM,
 555 then ``testpmd`` should be used as forwarding application inside the VM.
 556 As it is able to forward traffic between multiple VM NIC pairs.
 557
 558 Note: In case of ``linux_bridge``, all NICs are connected to the same
 559 bridge inside the VM.
 560
 561 VM, vSwitch, Traffic Generator Independence
 562 ===========================================
 563
 564 VSPERF supports different vSwithes, Traffic Generators, VNFs
 565 and Forwarding Applications by using standard object-oriented polymorphism:
 566
 567   * Support for vSwitches is implemented by a class inheriting from IVSwitch.
 568   * Support for Traffic Generators is implemented by a class inheriting from
 569     ITrafficGenerator.
 570   * Support for VNF is implemented by a class inheriting from IVNF.
 571   * Support for Forwarding Applications is implemented by a class inheriting
 572     from IPktFwd.
 573
 574 By dealing only with the abstract interfaces the core framework can support
 575 many implementations of different vSwitches, Traffic Generators, VNFs
 576 and Forwarding Applications.
 577
 578 IVSwitch
 579 --------
 580
 581 .. code-block:: python
 582
 583     class IVSwitch:
 584       start(self)
 585       stop(self)
 586       add_switch(switch_name)
 587       del_switch(switch_name)
 588       add_phy_port(switch_name)
 589       add_vport(switch_name)
 590       get_ports(switch_name)
 591       del_port(switch_name, port_name)
 592       add_flow(switch_name, flow)
 593       del_flow(switch_name, flow=None)
 594
 595 ITrafficGenerator
 596 -----------------
 597
 598 .. code-block:: python
 599
 600     class ITrafficGenerator:
 601       connect()
 602       disconnect()
 603
 604       send_burst_traffic(traffic, numpkts, time, framerate)
 605
 606       send_cont_traffic(traffic, time, framerate)
 607       start_cont_traffic(traffic, time, framerate)
 608       stop_cont_traffic(self):
 609
 610       send_rfc2544_throughput(traffic, tests, duration, lossrate)
 611       start_rfc2544_throughput(traffic, tests, duration, lossrate)
 612       wait_rfc2544_throughput(self)
 613
 614       send_rfc2544_back2back(traffic, tests, duration, lossrate)
 615       start_rfc2544_back2back(traffic, , tests, duration, lossrate)
 616       wait_rfc2544_back2back()
 617
 618 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
 619
 620 IVnf
 621 ----
 622
 623 .. code-block:: python
 624
 625     class IVnf:
 626       start(memory, cpus,
 627             monitor_path, shared_path_host,
 628             shared_path_guest, guest_prompt)
 629       stop()
 630       execute(command)
 631       wait(guest_prompt)
 632       execute_and_wait (command)
 633
 634 IPktFwd
 635 --------
 636
 637   .. code-block:: python
 638
 639     class IPktFwd:
 640         start()
 641         stop()
 642
 643
 644 Controllers
 645 -----------
 646
 647 Controllers are used in conjunction with abstract interfaces as way
 648 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
 649 and Forwarding Applications from other components.
 650
 651 The controlled classes provide basic primitive operations. The Controllers
 652 sequence and co-ordinate these primitive operation in to useful actions. For
 653 instance the vswitch_controller_p2p can be used to bring any vSwitch (that
 654 implements the primitives defined in IVSwitch) into the configuration required
 655 by the Phy-to-Phy  Deployment Scenario.
 656
 657 In order to support a new vSwitch only a new implementation of IVSwitch needs
 658 be created for the new vSwitch to be capable of fulfilling all the Deployment
 659 Scenarios provided for by existing or future vSwitch Controllers.
 660
 661 Similarly if a new Deployment Scenario is required it only needs to be written
 662 once as a new vSwitch Controller and it will immediately be capable of
 663 controlling all existing and future vSwitches in to that Deployment Scenario.
 664
 665 Similarly the Traffic Controllers can be used to co-ordinate basic operations
 666 provided by implementers of ITrafficGenerator to provide useful tests. Though
 667 traffic generators generally already implement full test cases i.e. they both
 668 generate suitable traffic and analyse returned traffic in order to implement a
 669 test which has typically been predefined in an RFC document. However the
 670 Traffic Controller class allows for the possibility of further enhancement -
 671 such as iterating over tests for various packet sizes or creating new tests.
 672
 673 Traffic Controller's Role
 674 -------------------------
 675
 676 .. image:: traffic_controller.png
 677
 678
 679 Loader & Component Factory
 680 --------------------------
 681
 682 The working of the Loader package (which is responsible for *finding* arbitrary
 683 classes based on configuration data) and the Component Factory which is
 684 responsible for *choosing* the correct class for a particular situation - e.g.
 685 Deployment Scenario can be seen in this diagram.
 686
 687 .. image:: factory_and_loader.png
 688
 689 Routing Tables
 690 ==============
 691
 692 Vsperf uses a standard set of routing tables in order to allow tests to easily
 693 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
 694 Frame Modification requirements.
 695
 696 .. code-block:: console
 697
 698       +--------------+
 699       |              |
 700       | Table 0      |  table#0 - Match table. Flows designed to force 5 & 10
 701       |              |  tuple matches go here.
 702       |              |
 703       +--------------+
 704              |
 705              |
 706              v
 707       +--------------+  table#1 - Routing table. Flow entries to forward
 708       |              |  packets between ports goes here.
 709       | Table 1      |  The chosen port is communicated to subsequent tables by
 710       |              |  setting the metadata value to the egress port number.
 711       |              |  Generally this table is set-up by by the
 712       +--------------+  vSwitchController.
 713              |
 714              |
 715              v
 716       +--------------+  table#2 - Frame modification table. Frame modification
 717       |              |  flow rules are isolated in this table so that they can
 718       | Table 2      |  be turned on or off without affecting the routing or
 719       |              |  tuple-matching flow rules. This allows the frame
 720       |              |  modification and tuple matching required by the tests
 721       |              |  in the VSWITCH PERFORMANCE FOR TELCO NFV test
 722       +--------------+  specification to be independent of the Deployment
 723              |          Scenario set up by the vSwitchController.
 724              |
 725              v
 726       +--------------+
 727       |              |
 728       | Table 3      |  table#3 - Egress table. Egress packets on the ports
 729       |              |  setup in Table 1.
 730       +--------------+
 731
 732