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,
  83                            time=20, framerate=100):
  84         """Send a burst of traffic.
  85
  86         Send a ``numpkts`` packets of traffic, using ``traffic``
  87         configuration, with a timeout of ``time``.
  88
  89         Attributes:
  90         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN tags
  91         :param numpkts: Number of packets to send
  92         :param framerate: Expected framerate
  93         :param time: Time to wait to receive packets
  94
  95         :returns: dictionary of strings with following data:
  96             - List of Tx Frames,
  97             - List of Rx Frames,
  98             - List of Tx Bytes,
  99             - List of List of Rx Bytes,
 100             - Payload Errors and Sequence Errors.
 101         """
 102         raise NotImplementedError('Please call an implementation.')
 103
 104     def send_cont_traffic(self, traffic=None, time=20, framerate=0,
 105                           multistream=False):
 106         """Send a continuous flow of traffic.
 107
 108         Send packets at ``framerate``, using ``traffic`` configuration,
 109         until timeout ``time`` occurs.
 110
 111         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN tags
 112         :param time: Time to wait to receive packets (secs)
 113         :param framerate: Expected framerate
 114         :param multistream: Enable multistream output by overriding the
 115                         UDP port number in ``traffic`` with values
 116                         from 1 to 64,000
 117         :returns: dictionary of strings with following data:
 118             - Tx Throughput (fps),
 119             - Rx Throughput (fps),
 120             - Tx Throughput (mbps),
 121             - Rx Throughput (mbps),
 122             - Tx Throughput (% linerate),
 123             - Rx Throughput (% linerate),
 124             - Min Latency (ns),
 125             - Max Latency (ns),
 126             - Avg Latency (ns)
 127         """
 128         raise NotImplementedError('Please call an implementation.')
 129
 130     def start_cont_traffic(self, traffic=None, time=20, framerate=0,
 131                            multistream=False):
 132         """Non-blocking version of 'send_cont_traffic'.
 133
 134         Start transmission and immediately return. Do not wait for
 135         results.
 136         """
 137         raise NotImplementedError('Please call an implementation.')
 138
 139     def stop_cont_traffic(self):
 140         """Stop continuous transmission and return results.
 141         """
 142         raise NotImplementedError('Please call an implementation.')
 143
 144     def send_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 145                                 lossrate=0.0, multistream=False):
 146         """Send traffic per RFC2544 throughput test specifications.
 147
 148         Send packets at a variable rate, using ``traffic``
 149         configuration, until minimum rate at which no packet loss is
 150         detected is found.
 151
 152         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN tags
 153         :param trials: Number of trials to execute
 154         :param duration: Per iteration duration
 155         :param lossrate: Acceptable lossrate percentage
 156         :param multistream: Enable multistream output by overriding the
 157                         UDP port number in ``traffic`` with values
 158                         from 1 to 64,000
 159         :returns: dictionary of strings with following data:
 160             - Tx Throughput (fps),
 161             - Rx Throughput (fps),
 162             - Tx Throughput (mbps),
 163             - Rx Throughput (mbps),
 164             - Tx Throughput (% linerate),
 165             - Rx Throughput (% linerate),
 166             - Min Latency (ns),
 167             - Max Latency (ns),
 168             - Avg Latency (ns)
 169         """
 170         raise NotImplementedError('Please call an implementation.')
 171
 172     def start_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 173                                  lossrate=0.0, multistream=False):
 174         """Non-blocking version of 'send_rfc2544_throughput'.
 175
 176         Start transmission and immediately return. Do not wait for
 177         results.
 178         """
 179         raise NotImplementedError('Please call an implementation.')
 180
 181     def wait_rfc2544_throughput(self):
 182         """Wait for and return results of RFC2544 test.
 183         """
 184         raise NotImplementedError('Please call an implementation.')
 185
 186     def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 187                                lossrate=0.0, multistream=False):
 188         """Send traffic per RFC2544 back2back test specifications.
 189
 190         Send packets at a fixed rate, using ``traffic``
 191         configuration, until minimum time at which no packet loss is
 192         detected is found.
 193
 194         :param traffic: Detailed "traffic" spec, i.e. IP address, VLAN
 195             tags
 196         :param trials: Number of trials to execute
 197         :param duration: Per iteration duration
 198         :param lossrate: Acceptable loss percentage
 199         :param multistream: Enable multistream output by overriding the
 200             UDP port number in ``traffic`` with values from 1 to 64,000
 201
 202         :returns: Named tuple of Rx Throughput (fps), Rx Throughput (mbps),
 203             Tx Rate (% linerate), Rx Rate (% linerate), Tx Count (frames),
 204             Back to Back Count (frames), Frame Loss (frames), Frame Loss (%)
 205         :rtype: :class:`Back2BackResult`
 206         """
 207         raise NotImplementedError('Please call an implementation.')
 208
 209     def start_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 210                                 lossrate=0.0, multistream=False):
 211         """Non-blocking version of 'send_rfc2544_back2back'.
 212
 213         Start transmission and immediately return. Do not wait for
 214         results.
 215         """
 216         raise NotImplementedError('Please call an implementation.')
 217
 218     def wait_rfc2544_back2back(self):
 219         """Wait and set results of RFC2544 test.
 220         """
 221         raise NotImplementedError('Please call an implementation.')