tools/pkt_gen/trafficgen/trafficgen.py

   1 # Copyright 2015 Intel Corporation.
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #   http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14 """Abstract "traffic generator" model.
  15
  16 This is an abstract class for traffic generators.
  17 """
  18
  19 #TODO update Back2Back method description when Result implementation will
  20 #be ready.
  21
  22 from tools.pkt_gen.trafficgen.trafficgenhelper import TRAFFIC_DEFAULTS
  23
  24 class ITrafficGenerator(object):
  25     """Model of a traffic generator device.
  26     """
  27     _traffic_defaults = TRAFFIC_DEFAULTS.copy()
  28
  29     @property
  30     def traffic_defaults(self):
  31         """Default traffic values.
  32
  33         These can be expected to be constant across traffic generators,
  34         so no setter is provided. Changes to the structure or contents
  35         will likely break traffic generator implementations or tests
  36         respectively.
  37         """
  38         return self._traffic_defaults
  39
  40     def __enter__(self):
  41         """Connect to the traffic generator.
  42
  43         Provide a context manager interface to the traffic generators.
  44         This simply calls the :func:`connect` function.
  45         """
  46         return self.connect()
  47
  48     def __exit__(self, type_, value, traceback):
  49         """Disconnect from the traffic generator.
  50
  51         Provide a context manager interface to the traffic generators.
  52         This simply calls the :func:`disconnect` function.
  53         """
  54         self.disconnect()
  55
  56     def connect(self):
  57         """Connect to the traffic generator.
  58
  59         This is an optional function, designed for traffic generators
  60         which must be "connected to" (i.e. via SSH or an API) before
  61         they can be used. If not required, simply do nothing here.
  62
  63         Where implemented, this function should raise an exception on
  64         failure.
  65
  66         :returns: None
  67         """
  68         raise NotImplementedError('Please call an implementation.')
  69
  70     def disconnect(self):
  71         """Disconnect from the traffic generator.
  72
  73         As with :func:`connect`, this function is optional.
  74
  75         Where implemented, this function should raise an exception on
  76         failure.
  77
  78         :returns: None
  79         """
  80         raise NotImplementedError('Please call an implementation.')
  81
  82     def send_burst_traffic(self, traffic=None, numpkts=100, duration=20):
  83         """Send a burst of traffic.
  84
  85         Send a ``numpkts`` packets of traffic, using ``traffic``
  86         configuration, for ``duration`` seconds.
  87
  88         Attributes:
  89         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN tags
  90         :param numpkts: Number of packets to send
  91         :param duration: Time to wait to receive packets
  92
  93         :returns: dictionary of strings with following data:
  94             - List of Tx Frames,
  95             - List of Rx Frames,
  96             - List of Tx Bytes,
  97             - List of List of Rx Bytes,
  98             - Payload Errors and Sequence Errors.
  99         """
 100         raise NotImplementedError('Please call an implementation.')
 101
 102     def send_cont_traffic(self, traffic=None, duration=20, multistream=False):
 103         """Send a continuous flow of traffic.
 104
 105         Send packets at given framerate, using ``traffic`` configuration,
 106         for ``duration`` seconds..
 107
 108         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN tags
 109                         from 1 to 64,000
 110         :param duration: Duration to transmit traffic.
 111         :param multistream: Enable multistream output by overriding the
 112                         from 1 to 64,000
 113         :returns: dictionary of strings with following data:
 114             - Tx Throughput (fps),
 115             - Rx Throughput (fps),
 116             - Tx Throughput (mbps),
 117             - Rx Throughput (mbps),
 118             - Tx Throughput (% linerate),
 119             - Rx Throughput (% linerate),
 120             - Min Latency (ns),
 121             - Max Latency (ns),
 122             - Avg Latency (ns)
 123         """
 124         raise NotImplementedError('Please call an implementation.')
 125
 126     def start_cont_traffic(self, traffic=None, duration=30):
 127         """Non-blocking version of 'send_cont_traffic'.
 128
 129         Start transmission and immediately return. Do not wait for
 130         results.
 131         """
 132         raise NotImplementedError('Please call an implementation.')
 133
 134     def stop_cont_traffic(self):
 135         """Stop continuous transmission and return results.
 136         """
 137         raise NotImplementedError('Please call an implementation.')
 138
 139     def send_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 140                                 lossrate=0.0, multistream=False):
 141         """Send traffic per RFC2544 throughput test specifications.
 142
 143         Send packets at a variable rate, using ``traffic``
 144         configuration, until minimum rate at which no packet loss is
 145         detected is found.
 146
 147         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN tags
 148         :param trials: Number of trials to execute
 149         :param duration: Per iteration duration
 150         :param lossrate: Acceptable lossrate percentage
 151         :param multistream: Enable multistream output by overriding the
 152                         UDP port number in ``traffic`` with values
 153                         from 1 to 64,000
 154         :returns: dictionary of strings with following data:
 155             - Tx Throughput (fps),
 156             - Rx Throughput (fps),
 157             - Tx Throughput (mbps),
 158             - Rx Throughput (mbps),
 159             - Tx Throughput (% linerate),
 160             - Rx Throughput (% linerate),
 161             - Min Latency (ns),
 162             - Max Latency (ns),
 163             - Avg Latency (ns)
 164         """
 165         raise NotImplementedError('Please call an implementation.')
 166
 167     def start_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 168                                  lossrate=0.0):
 169         """Non-blocking version of 'send_rfc2544_throughput'.
 170
 171         Start transmission and immediately return. Do not wait for
 172         results.
 173         """
 174         raise NotImplementedError('Please call an implementation.')
 175
 176     def wait_rfc2544_throughput(self):
 177         """Wait for and return results of RFC2544 test.
 178         """
 179         raise NotImplementedError('Please call an implementation.')
 180
 181     def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 182                                lossrate=0.0):
 183         """Send traffic per RFC2544 back2back test specifications.
 184
 185         Send packets at a fixed rate, using ``traffic``
 186         configuration, for duration seconds.
 187
 188         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN
 189             tags
 190         :param trials: Number of trials to execute
 191         :param duration: Per iteration duration
 192         :param lossrate: Acceptable loss percentage
 193         :param multistream: Enable multistream output by overriding the
 194             UDP port number in ``traffic`` with values from 1 to 64,000
 195
 196         :returns: Named tuple of Rx Throughput (fps), Rx Throughput (mbps),
 197             Tx Rate (% linerate), Rx Rate (% linerate), Tx Count (frames),
 198             Back to Back Count (frames), Frame Loss (frames), Frame Loss (%)
 199         :rtype: :class:`Back2BackResult`
 200         """
 201         raise NotImplementedError('Please call an implementation.')
 202
 203     def start_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 204                                 lossrate=0.0):
 205         """Non-blocking version of 'send_rfc2544_back2back'.
 206
 207         Start transmission and immediately return. Do not wait for
 208         results.
 209         """
 210         raise NotImplementedError('Please call an implementation.')
 211
 212     def wait_rfc2544_back2back(self):
 213         """Wait and set results of RFC2544 test.
 214         """
 215         raise NotImplementedError('Please call an implementation.')