tools/pkt_gen/trafficgen/trafficgen.py

   1 # Copyright 2015-2016 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, see design docs for details
  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):
 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, see design docs for details
 109         :param duration: Duration to transmit traffic.
 110         :returns: dictionary of strings with following data:
 111             - Tx Throughput (fps),
 112             - Rx Throughput (fps),
 113             - Tx Throughput (mbps),
 114             - Rx Throughput (mbps),
 115             - Tx Throughput (% linerate),
 116             - Rx Throughput (% linerate),
 117             - Min Latency (ns),
 118             - Max Latency (ns),
 119             - Avg Latency (ns)
 120         """
 121         raise NotImplementedError('Please call an implementation.')
 122
 123     def start_cont_traffic(self, traffic=None, duration=30):
 124         """Non-blocking version of 'send_cont_traffic'.
 125
 126         Start transmission and immediately return. Do not wait for
 127         results.
 128         """
 129         raise NotImplementedError('Please call an implementation.')
 130
 131     def stop_cont_traffic(self):
 132         """Stop continuous transmission and return results.
 133         """
 134         raise NotImplementedError('Please call an implementation.')
 135
 136     def send_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 137                                 lossrate=0.0):
 138         """Send traffic per RFC2544 throughput test specifications.
 139
 140         Send packets at a variable rate, using ``traffic``
 141         configuration, until minimum rate at which no packet loss is
 142         detected is found.
 143
 144         :param traffic: Detailed "traffic" spec, see design docs for details
 145         :param trials: Number of trials to execute
 146         :param duration: Per iteration duration
 147         :param lossrate: Acceptable lossrate percentage
 148         :returns: dictionary of strings with following data:
 149             - Tx Throughput (fps),
 150             - Rx Throughput (fps),
 151             - Tx Throughput (mbps),
 152             - Rx Throughput (mbps),
 153             - Tx Throughput (% linerate),
 154             - Rx Throughput (% linerate),
 155             - Min Latency (ns),
 156             - Max Latency (ns),
 157             - Avg Latency (ns)
 158         """
 159         raise NotImplementedError('Please call an implementation.')
 160
 161     def start_rfc2544_throughput(self, traffic=None, trials=3, duration=20,
 162                                  lossrate=0.0):
 163         """Non-blocking version of 'send_rfc2544_throughput'.
 164
 165         Start transmission and immediately return. Do not wait for
 166         results.
 167         """
 168         raise NotImplementedError('Please call an implementation.')
 169
 170     def wait_rfc2544_throughput(self):
 171         """Wait for and return results of RFC2544 test.
 172         """
 173         raise NotImplementedError('Please call an implementation.')
 174
 175     def send_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 176                                lossrate=0.0):
 177         """Send traffic per RFC2544 back2back test specifications.
 178
 179         Send packets at a fixed rate, using ``traffic``
 180         configuration, for duration seconds.
 181
 182         :param traffic: Detailed "traffic" spec, see design docs for details
 183         :param trials: Number of trials to execute
 184         :param duration: Per iteration duration
 185         :param lossrate: Acceptable loss percentage
 186
 187         :returns: Named tuple of Rx Throughput (fps), Rx Throughput (mbps),
 188             Tx Rate (% linerate), Rx Rate (% linerate), Tx Count (frames),
 189             Back to Back Count (frames), Frame Loss (frames), Frame Loss (%)
 190         :rtype: :class:`Back2BackResult`
 191         """
 192         raise NotImplementedError('Please call an implementation.')
 193
 194     def start_rfc2544_back2back(self, traffic=None, trials=1, duration=20,
 195                                 lossrate=0.0):
 196         """Non-blocking version of 'send_rfc2544_back2back'.
 197
 198         Start transmission and immediately return. Do not wait for
 199         results.
 200         """
 201         raise NotImplementedError('Please call an implementation.')
 202
 203     def wait_rfc2544_back2back(self):
 204         """Wait and set results of RFC2544 test.
 205         """
 206         raise NotImplementedError('Please call an implementation.')