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 - ``p2p_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_trials=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
 104 Other Configuration
 105 -------------------
 106
 107 ``conf.settings`` also loads configuration from the command line and from the environment.
 108
 109 VM, vSwitch, Traffic Generator Independence
 110 ===========================================
 111
 112 VSPERF supports different vSwithes, Traffic Generators, VNFs
 113 and Forwarding Applications by using standard object-oriented polymorphism:
 114
 115   * Support for vSwitches is implemented by a class inheriting from IVSwitch.
 116   * Support for Traffic Generators is implemented by a class inheriting from
 117     ITrafficGenerator.
 118   * Support for VNF is implemented by a class inheriting from IVNF.
 119   * Support for Forwarding Applications is implemented by a class inheriting
 120     from IPktFwd.
 121
 122 By dealing only with the abstract interfaces the core framework can support
 123 many implementations of different vSwitches, Traffic Generators, VNFs
 124 and Forwarding Applications.
 125
 126 IVSwitch
 127 --------
 128
 129 .. code-block:: python
 130
 131     class IVSwitch:
 132       start(self)
 133       stop(self)
 134       add_switch(switch_name)
 135       del_switch(switch_name)
 136       add_phy_port(switch_name)
 137       add_vport(switch_name)
 138       get_ports(switch_name)
 139       del_port(switch_name, port_name)
 140       add_flow(switch_name, flow)
 141       del_flow(switch_name, flow=None)
 142
 143 ITrafficGenerator
 144 -----------------
 145
 146 .. code-block:: python
 147
 148     class ITrafficGenerator:
 149       connect()
 150       disconnect()
 151
 152       send_burst_traffic(traffic, numpkts, time, framerate)
 153
 154       send_cont_traffic(traffic, time, framerate)
 155       start_cont_traffic(traffic, time, framerate)
 156       stop_cont_traffic(self):
 157
 158       send_rfc2544_throughput(traffic, trials, duration, lossrate)
 159       start_rfc2544_throughput(traffic, trials, duration, lossrate)
 160       wait_rfc2544_throughput(self)
 161
 162       send_rfc2544_back2back(traffic, trials, duration, lossrate)
 163       start_rfc2544_back2back(traffic, , trials, duration, lossrate)
 164       wait_rfc2544_back2back()
 165
 166 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
 167
 168 IVnf
 169 ----
 170
 171 .. code-block:: python
 172
 173     class IVnf:
 174       start(memory, cpus,
 175             monitor_path, shared_path_host,
 176             shared_path_guest, guest_prompt)
 177       stop()
 178       execute(command)
 179       wait(guest_prompt)
 180       execute_and_wait (command)
 181
 182 IPktFwd
 183 --------
 184
 185   .. code-block:: python
 186
 187     class IPktFwd:
 188         start()
 189         stop()
 190
 191
 192 Controllers
 193 -----------
 194
 195 Controllers are used in conjunction with abstract interfaces as way
 196 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
 197 and Forwarding Applications from other components.
 198
 199 The controlled classes provide basic primitive operations. The Controllers
 200 sequence and co-ordinate these primitive operation in to useful actions. For
 201 instance the vswitch_controller_PVP can be used to bring any vSwitch (that
 202 implements the primitives defined in IVSwitch) into the configuration required
 203 by the Phy-to-Phy  Deployment Scenario.
 204
 205 In order to support a new vSwitch only a new implementation of IVSwitch needs
 206 be created for the new vSwitch to be capable of fulfilling all the Deployment
 207 Scenarios provided for by existing or future vSwitch Controllers.
 208
 209 Similarly if a new Deployment Scenario is required it only needs to be written
 210 once as a new vSwitch Controller and it will immediately be capable of
 211 controlling all existing and future vSwitches in to that Deployment Scenario.
 212
 213 Similarly the Traffic Controllers can be used to co-ordinate basic operations
 214 provided by implementers of ITrafficGenerator to provide useful tests. Though
 215 traffic generators generally already implement full test cases i.e. they both
 216 generate suitable traffic and analyse returned traffic in order to implement a
 217 test which has typically been predefined in an RFC document. However the
 218 Traffic Controller class allows for the possibility of further enhancement -
 219 such as iterating over tests for various packet sizes or creating new tests.
 220
 221 Traffic Controller's Role
 222 -------------------------
 223
 224 .. image:: traffic_controller.png
 225
 226
 227 Loader & Component Factory
 228 --------------------------
 229
 230 The working of the Loader package (which is responsible for *finding* arbitrary
 231 classes based on configuration data) and the Component Factory which is
 232 responsible for *choosing* the correct class for a particular situation - e.g.
 233 Deployment Scenario can be seen in this diagram.
 234
 235 .. image:: factory_and_loader.png
 236
 237 Routing Tables
 238 ==============
 239
 240 Vsperf uses a standard set of routing tables in order to allow tests to easily
 241 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
 242 Frame Modification requirements.
 243
 244 .. code-block:: console
 245
 246       +--------------+
 247       |              |
 248       | Table 0      |  table#0 - Match table. Flows designed to force 5 & 10
 249       |              |  tuple matches go here.
 250       |              |
 251       +--------------+
 252              |
 253              |
 254              v
 255       +--------------+  table#1 - Routing table. Flow entries to forward
 256       |              |  packets between ports goes here.
 257       | Table 1      |  The chosen port is communicated to subsequent tables by
 258       |              |  setting the metadata value to the egress port number.
 259       |              |  Generally this table is set-up by by the
 260       +--------------+  vSwitchController.
 261              |
 262              |
 263              v
 264       +--------------+  table#2 - Frame modification table. Frame modification
 265       |              |  flow rules are isolated in this table so that they can
 266       | Table 2      |  be turned on or off without affecting the routing or
 267       |              |  tuple-matching flow rules. This allows the frame
 268       |              |  modification and tuple matching required by the tests
 269       |              |  in the VSWITCH PERFORMANCE FOR TELCO NFV test
 270       +--------------+  specification to be independent of the Deployment
 271              |          Scenario set up by the vSwitchController.
 272              |
 273              v
 274       +--------------+
 275       |              |
 276       | Table 3      |  table#3 - Egress table. Egress packets on the ports
 277       |              |  setup in Table 1.
 278       +--------------+
 279
 280