docs/design/vswitchperf_design.rst

   1 ======================
   2 VSPERF Design Document
   3 ======================
   4
   5 Intended Audience
   6 =================
   7
   8 This document is intended to aid those who want to modify the vsperf code. Or
   9 to extend it - for example to add support for new traffic generators,
  10 deployment scenarios and so on.
  11
  12 Usage
  13 =====
  14
  15 Example Connectivity to DUT
  16 ---------------------------
  17
  18 Establish connectivity to the VSPERF DUT Linux host, such as the DUT in Pod 3,
  19 by following the steps in `Testbed POD3
  20 <https://wiki.opnfv.org/get_started/pod_3_-_characterize_vswitch_performance>`__
  21
  22 The steps cover booking the DUT and establishing the VSPERF environment.
  23
  24 Example Command Lines
  25 ---------------------
  26
  27 List all the cli options:
  28
  29 .. code-block:: console
  30
  31    $ ./vsperf -h
  32
  33 Run all tests that have ``tput`` in their name - ``p2p_tput``, ``pvp_tput`` etc.:
  34
  35 .. code-block:: console
  36
  37    $ ./vsperf --tests 'tput'
  38
  39 As above but override default configuration with settings in '10_custom.conf'.
  40 This is useful as modifying configuration directly in the configuration files
  41 in ``conf/NN_*.py`` shows up as changes under git source control:
  42
  43 .. code-block:: console
  44
  45    $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf --tests 'tput'
  46
  47 Override specific test parameters. Useful for shortening the duration of tests
  48 for development purposes:
  49
  50 .. code-block:: console
  51
  52    $ ./vsperf --test-params 'duration=10;rfc2544_trials=1;pkt_sizes=64' --tests 'pvp_tput'
  53
  54 Typical Test Sequence
  55 =====================
  56
  57 This is a typical flow of control for a test.
  58
  59 .. image:: vsperf.png
  60
  61
  62 Configuration
  63 =============
  64
  65 The conf package contains the configuration files (``*.conf``) for all system
  66 components, it also provides a ``settings`` object that exposes all of these
  67 settings.
  68
  69 Settings are not passed from component to component. Rather they are available
  70 globally to all components once they import the conf package.
  71
  72 .. code-block:: python
  73
  74    from conf import settings
  75    ...
  76    log_file = settings.getValue('LOG_FILE_DEFAULT')
  77
  78 Settings files (``*.conf``) are valid python code so can be set to complex
  79 types such as lists and dictionaries as well as scalar types:
  80
  81 .. code-block:: python
  82
  83    first_packet_size = settings.getValue('PACKET_SIZE_LIST')[0]
  84
  85 Configuration Procedure and Precedence
  86 --------------------------------------
  87
  88 Configuration files follow a strict naming convention that allows them to be
  89 processed in a specific order. All the .conf files are named ``NN_name.conf``,
  90 where NN is a decimal number. The files are processed in order from 00_name.conf
  91 to 99_name.conf so that if the name setting is given in both a lower and higher
  92 numbered conf file then the higher numbered file is the effective setting as it
  93 is processed after the setting in the lower numbered file.
  94
  95 The values in the file specified by ``--conf-file`` takes precedence over all
  96 the other configuration files and does not have to follow the naming
  97 convention.
  98
  99
 100 Other Configuration
 101 -------------------
 102
 103 ``conf.settings`` also loads configuration from the command line and from the environment.
 104
 105 VM, vSwitch, Traffic Generator Independence
 106 ===========================================
 107
 108 VSPERF supports different vSwithes, Traffic Generators, VNFs
 109 and Forwarding Applications by using standard object-oriented polymorphism:
 110
 111   * Support for vSwitches is implemented by a class inheriting from IVSwitch.
 112   * Support for Traffic Generators is implemented by a class inheriting from
 113     ITrafficGenerator.
 114   * Support for VNF is implemented by a class inheriting from IVNF.
 115   * Support for Forwarding Applications is implemented by a class inheriting
 116     from IPktFwd.
 117
 118 By dealing only with the abstract interfaces the core framework can support
 119 many implementations of different vSwitches, Traffic Generators, VNFs
 120 and Forwarding Applications.
 121
 122 IVSwitch
 123 --------
 124
 125 .. code-block:: python
 126
 127     class IVSwitch:
 128       start(self)
 129       stop(self)
 130       add_switch(switch_name)
 131       del_switch(switch_name)
 132       add_phy_port(switch_name)
 133       add_vport(switch_name)
 134       get_ports(switch_name)
 135       del_port(switch_name, port_name)
 136       add_flow(switch_name, flow)
 137       del_flow(switch_name, flow=None)
 138
 139 ITrafficGenerator
 140 -----------------
 141
 142 .. code-block:: python
 143
 144     class ITrafficGenerator:
 145       connect()
 146       disconnect()
 147
 148       send_burst_traffic(traffic, numpkts, time, framerate)
 149
 150       send_cont_traffic(traffic, time, framerate)
 151       start_cont_traffic(traffic, time, framerate)
 152       stop_cont_traffic(self):
 153
 154       send_rfc2544_throughput(traffic, trials, duration, lossrate)
 155       start_rfc2544_throughput(traffic, trials, duration, lossrate)
 156       wait_rfc2544_throughput(self)
 157
 158       send_rfc2544_back2back(traffic, trials, duration, lossrate)
 159       start_rfc2544_back2back(traffic, , trials, duration, lossrate)
 160       wait_rfc2544_back2back()
 161
 162 Note ``send_xxx()`` blocks whereas ``start_xxx()`` does not and must be followed by a subsequent call to ``wait_xxx()``.
 163
 164 IVnf
 165 ----
 166
 167 .. code-block:: python
 168
 169     class IVnf:
 170       start(memory, cpus,
 171             monitor_path, shared_path_host,
 172             shared_path_guest, guest_prompt)
 173       stop()
 174       execute(command)
 175       wait(guest_prompt)
 176       execute_and_wait (command)
 177
 178 IPktFwd
 179 --------
 180
 181   .. code-block:: python
 182
 183     class IPktFwd:
 184         start()
 185         stop()
 186
 187
 188 Controllers
 189 -----------
 190
 191 Controllers are used in conjunction with abstract interfaces as way
 192 of decoupling the control of vSwtiches, VNFs, TrafficGenerators
 193 and Forwarding Applications from other components.
 194
 195 The controlled classes provide basic primitive operations. The Controllers
 196 sequence and co-ordinate these primitive operation in to useful actions. For
 197 instance the vswitch_controller_PVP can be used to bring any vSwitch (that
 198 implements the primitives defined in IVSwitch) into the configuration required
 199 by the Phy-to-Phy  Deployment Scenario.
 200
 201 In order to support a new vSwitch only a new implementation of IVSwitch needs
 202 be created for the new vSwitch to be capable of fulfilling all the Deployment
 203 Scenarios provided for by existing or future vSwitch Controllers.
 204
 205 Similarly if a new Deployment Scenario is required it only needs to be written
 206 once as a new vSwitch Controller and it will immediately be capable of
 207 controlling all existing and future vSwitches in to that Deployment Scenario.
 208
 209 Similarly the Traffic Controllers can be used to co-ordinate basic operations
 210 provided by implementers of ITrafficGenerator to provide useful tests. Though
 211 traffic generators generally already implement full test cases i.e. they both
 212 generate suitable traffic and analyse returned traffic in order to implement a
 213 test which has typically been predefined in an RFC document. However the
 214 Traffic Controller class allows for the possibility of further enhancement -
 215 such as iterating over tests for various packet sizes or creating new tests.
 216
 217 Traffic Controller's Role
 218 -------------------------
 219
 220 .. image:: traffic_controller.png
 221
 222
 223 Loader & Component Factory
 224 --------------------------
 225
 226 The working of the Loader package (which is responsible for *finding* arbitrary
 227 classes based on configuration data) and the Component Factory which is
 228 responsible for *choosing* the correct class for a particular situation - e.g.
 229 Deployment Scenario can be seen in this diagram.
 230
 231 .. image:: factory_and_loader.png
 232
 233 Routing Tables
 234 ==============
 235
 236 Vsperf uses a standard set of routing tables in order to allow tests to easily
 237 mix and match Deployment Scenarios (PVP, P2P topology), Tuple Matching and
 238 Frame Modification requirements.
 239
 240 .. code-block:: console
 241
 242       +--------------+
 243       |              |
 244       | Table 0      |  table#0 - Match table. Flows designed to force 5 & 10
 245       |              |  tuple matches go here.
 246       |              |
 247       +--------------+
 248              |
 249              |
 250              v
 251       +--------------+  table#1 - Routing table. Flow entries to forward
 252       |              |  packets between ports goes here.
 253       | Table 1      |  The chosen port is communicated to subsequent tables by
 254       |              |  setting the metadata value to the egress port number.
 255       |              |  Generally this table is set-up by by the
 256       +--------------+  vSwitchController.
 257              |
 258              |
 259              v
 260       +--------------+  table#2 - Frame modification table. Frame modification
 261       |              |  flow rules are isolated in this table so that they can
 262       | Table 2      |  be turned on or off without affecting the routing or
 263       |              |  tuple-matching flow rules. This allows the frame
 264       |              |  modification and tuple matching required by the tests
 265       |              |  in the VSWITCH PERFORMANCE FOR TELCO NFV test
 266       +--------------+  specification to be independent of the Deployment
 267              |          Scenario set up by the vSwitchController.
 268              |
 269              v
 270       +--------------+
 271       |              |
 272       | Table 3      |  table#3 - Egress table. Egress packets on the ports
 273       |              |  setup in Table 1.
 274       +--------------+
 275
 276