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