From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by dpdk.space (Postfix) with ESMTP id 5654BA0AB5 for ; Sun, 28 Apr 2019 04:45:39 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 99E101B505; Sun, 28 Apr 2019 04:45:37 +0200 (CEST) Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 140931B4A0 for ; Sun, 28 Apr 2019 04:45:34 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga007.fm.intel.com ([10.253.24.52]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 27 Apr 2019 19:45:34 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.60,403,1549958400"; d="scan'208";a="146438584" Received: from itecstvdts01.sh.intel.com ([10.67.111.114]) by fmsmga007.fm.intel.com with ESMTP; 27 Apr 2019 19:45:34 -0700 From: yufengmx To: dts@dpdk.org Cc: yufengmx Date: Sun, 28 Apr 2019 10:49:02 +0800 Message-Id: <1556419751-41723-6-git-send-email-yufengx.mo@intel.com> X-Mailer: git-send-email 1.9.3 In-Reply-To: <1556419751-41723-1-git-send-email-yufengx.mo@intel.com> References: <1556419751-41723-1-git-send-email-yufengx.mo@intel.com> Subject: [dts] [next][PATCH V1 5/14] doc/pktgen: pktgen api program guide document X-BeenThere: dts@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: test suite reviews and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dts-bounces@dpdk.org Sender: "dts" pktgen api program guide document The document describes input parameter and return value definition of pktgen api. These api includes add stream --> config stream --> measure. The document has an example source code of a complex application scenario for program reference. Signed-off-by: yufengmx --- doc/dts_gsg/pktgen_prog_guide.rst | 518 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 doc/dts_gsg/pktgen_prog_guide.rst diff --git a/doc/dts_gsg/pktgen_prog_guide.rst b/doc/dts_gsg/pktgen_prog_guide.rst new file mode 100644 index 0000000..32d2082 --- /dev/null +++ b/doc/dts_gsg/pktgen_prog_guide.rst @@ -0,0 +1,518 @@ + +================= +how to use pktgen +================= +these definition and usage pattern come from doc `pktgen-API-1.1.docx` and etgen +usage in dts. For trex(CISCO) rapid iterative development speed, we lack of +adequate manpower to keep up with it. Here we recommend to use trex v2.41/v2.42/v2.43 +to run pktgen/trex. + +add stream +========== +add stream in pktgen streams table. + +one stream content including:: + + tx_port: transmit port idx in tester.ports_info. + rx_port: receive port idx in tester.ports_info. + pcap: pcap file or Packet instance, Only support one packet in it. + +.. code-block:: python + + tx_port = self.tester.get_local_port(dut_port_index1) + rx_port = self.tester.get_local_port(dut_port_index2) + + stream_id = hPktgen.add_stream(tx_port, rx_port, pcap) + +config stream +============= +configure a stream option. + +definition +---------- +Currently pktgen support ethernet/ipv4/vlan protocol layer some field vary with +increase/decrease/random value. + +stream option contain:: + + 'pcap': network packet format + 'fields_config': protocol layer field behavior(optional) + 'stream_config': stream transmit behavior + 'flow_control': port flow control(optional) + +pcap +++++ +It is a network packet format. It can be a absolute path of pcap file or +an instance of scapy Packet. It should only contain one packet format. + +.. code-block:: python + + Example 1: + + pcap = >>> + + Example 2: + + pcap = "/root/xxx.pcap" + +field option +++++++++++++ +define every layer's field behavior. + +'mac' +````` +'mac' is ethernet protocol layer name. + +.. code-block:: python + + # field name + 'src': { + # action: inc/dec/random + 'action':'inc', + # field end value should be bigger than field start value + 'end': '00:00:00:00:00:FF', + # field start value + 'start': '00:00:00:00:00:02', + # field value vary step + 'step': 1}, + 'dst': { + # action: inc/dec/random + 'action':'inc', + # field end value should be bigger than field start value + 'end': 'ff:00:00:00:00:FF', + # field start value + 'start': 'ff:00:00:00:00:02', + # field value vary step + 'step': 1}, + +'ip' +```` +'ip' is ip protocol layer name. + +.. code-block:: python + + # field name + 'src': { + # action: inc/dec/random + 'action': 'inc', + # field end value should be bigger than field start value + 'end': '16.0.0.16', + # field start value + 'start': '16.0.0.1', + # field value vary step + 'step': 1}, + # field name + 'dst': { + # action: inc/dec/random + 'action': 'inc', + # field end value should be bigger than field start value + 'end': '48.0.0.255', + # field start value + 'start': '48.0.0.1', + # field value vary step + 'step': 1}, + +'vlan' +`````` +'vlan' is vlan protocol layer name. + +.. code-block:: python + + # internal vlan + 0: { + # action: inc/dec/random + 'action': 'inc', + # field end value should be bigger than field start value + 'end': 52, + # field start value + 'start': 50, + # field value vary step + 'step': 1}, + # external vlan + 1: { + # action: inc/dec/random + 'action': 'inc', + # field end value should be bigger than field start value + 'end': 52, + # field start value + 'start': 50, + # field value vary step + 'step': 1}, + +'stream_config' ++++++++++++++++ +define a stream transmit behavior. + +basic content including:: + + 'rate': 0 ~ 100 int type + 'transmit_mode': TRANSMIT_CONT/TRANSMIT_S_BURST + TRANSMIT_CONT define a continuous transmit. + TRANSMIT_S_BURST define a burst transmit with custom number of packets. + +.. code-block:: python + + from pktgen_base import TRANSMIT_CONT, TRANSMIT_S_BURST + + stream_config = { + 'rate': 100, + # TRANSMIT_CONT define a continuous transmit. + # TRANSMIT_S_BURST define a burst transmit with custom number of packets. + 'transmit_mode': TRANSMIT_CONT + } + +stream option examples +---------------------- + +normal stream option +++++++++++++++++++++ +normal stream ignore `fields_config` configuration option. + +.. code-block:: python + + Example 1: + option = { + 'pcap': "/root/xxx.pcap", + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT}} + + Example 2: + option = { + 'pcap': >>>, + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT}} + +stream option with mac increase/decrease/random ++++++++++++++++++++++++++++++++++++++++++++++++ + +.. code-block:: python + + action = 'inc' or 'dec' or 'random' + option = { + 'pcap': "/root/xxx.pcap", + 'fields_config': { + 'mac': { + 'dst': { + 'action': action, + 'end': '00:00:00:00:20:00', + 'start': '00:00:00:00:00:FF', + 'step': 1}, + 'src': { + 'action': action, + 'end': '00:00:00:00:00:FF', + 'start': '00:00:00:00:00:02', + 'step': 1}}}, + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT + } + } + +stream option with ip increase/decrease/random +++++++++++++++++++++++++++++++++++++++++++++++ + +.. code-block:: python + + action = 'inc' or 'dec' or 'random' + option = { + 'pcap': "/root/xxx.pcap", + 'fields_config': { + 'ip': { + 'dst': { + 'action': action, + 'end': '48.0.0.255', + 'start': '48.0.0.1', + 'step': 1}, + 'src': { + 'action': action, + 'end': '16.0.0.16', + 'start': '16.0.0.1', + 'step': 1}}}, + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT, + } + } + +stream option with vlan increase/decrease/random +++++++++++++++++++++++++++++++++++++++++++++++++ + +.. code-block:: python + + action = 'inc' or 'dec' or 'random' + option = { + 'pcap': "/root/xxx.pcap", + 'fields_config': { + 'ip': { + 0: { + 'action': action, + 'end': 55, + 'start': 50, + 'step': 1}, + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT, + } + } + +burst stream option ++++++++++++++++++++ + +.. code-block:: python + + option = { + 'pcap': "/root/xxx.pcap", + 'stream_config': { + 'rate': 100, + # set stream transmit mode + 'transmit_mode': TRANSMIT_S_BURST, + 'txmode' : { + # total packets + 'total_pkts': 1000}, + } + } + +stream option with flow control ++++++++++++++++++++++++++++++++ +flow control open (trex not supported) + +.. code-block:: python + + option = { + 'flow_control': { + # 0: disable flow control + # 1: enable flow control + 'flag': 1}, + 'pcap': "/root/xxx.pcap", + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT}} + +measure +======= +pktgen measure_xxxx return value is the same as etgen, `measure_xxxx` and +`measure` are both supported. If traffic option is not set, use default values. + +two usage examples of pktgen measure method +------------------------------------------- + +.. code-block:: python + + Example 1: + + from pktgen import getPacketGenerator, PKTGEN_TREX + + hPktgen = getPacketGenerator(tester, PKTGEN_TREX) + + traffic_option = {'rate': 100} + hPktgen.measure_throughput(stream_ids, traffic_opt) + + Example 2: + + from pktgen import getPacketGenerator, PKTGEN_TREX + + hPktgen = getPacketGenerator(tester, PKTGEN_TREX) + + traffic_option = { + 'method': 'throughput', + 'rate': 100 + } + hPktgen.measure(stream_ids, traffic_opt) + +throughput +---------- +throughput testing scenario. + +option +++++++ +.. code-block:: python + + traffic_option = { + # test method name, if use `measure_throughput`, ignore this key + 'method': 'throughput', + # port rate percent + 'rate': 100, + # transmit lasting time second + 'duration': 5} + +return value +++++++++++++ +bps_rx_total: Received bits per second +pps_rx_total: Received packets per second + +.. code-block:: python + + return_value = (bps_rx_total, pps_rx_total) + +loss +---- +loss rate testing scenario. + +option +++++++ + +.. code-block:: python + + traffic_option = { + # test method name, if use `measure_loss`, ignore this key + 'method': 'loss', + # port rate percent + 'rate': 100, + # transmit lasting time second + 'duration': 5} + +return value +++++++++++++ + +.. code-block:: python + + loss_stats = (loss_rate, tx_pkts, rx_pkts) + +latency +------- +latency testing scenario. + +option +++++++ + +.. code-block:: python + + traffic_option = { + # test method name, if use `measure_latency`, ignore this key + 'method': 'latency', + # port rate percent + 'rate': 100, + # transmit lasting time second + 'duration': 5} + +return value +++++++++++++ + +.. code-block:: python + + latency_stats = { 'min': 15, + 'max': 15, + 'average': 15,} + +rfc2544 option +-------------- +single stream & rfc2544 + +option +++++++ + +.. code-block:: python + + traffic_option = { + # test method name, if use `measure_rfc2544`, ignore this key + 'method': 'rfc2544', + # port rate percent at first round testing, 0 ~ 100, default is 100 + 'rate': 100, + # permit packet drop rate + 'pdr': 0.001, + # port rate percent drop step, 0 ~ 100 , default is 1 + 'drop_step': 1, + # transmit lasting time second + 'duration': 5} + +return value +++++++++++++ + +.. code-block:: python + + loss_stats = (loss_rate, tx_pkts, rx_pkts) + +reference example +================= +This example show how to use pktgen in suite script. In fact, most scenario are +more simpler than this. Part of code is pseudo code and it can't be ran directly. + +testing scenario:: + + create four streams on two links, each link attach two streams. On one link, + one stream set mac src increase and packet format is a pcap file, the other + stream set ip src random / dst decrease and packet format is a scapy Packet + instance. All streams use continuous transmit and run rfc2544 scenario using + trex packet generator. + +.. code-block:: python + + # import pktgen lib + from pktgen import getPacketGenerator, PKTGEN_TREX, TRANSMIT_CONT + + # create a pktgen instance + hPktgen = getPacketGenerator(tester, PKTGEN_TREX) + + # create packet + pcap1 = >>> + pcap2 = "/root/xxx.pcap" + + # attach stream to pktgen + stream_ids = [] + tx_port1 = self.tester.get_local_port(dut_port_index1) + rx_port1 = self.tester.get_local_port(dut_port_index2) + stream_id_1 = hPktgen.add_stream(tx_port1, rx_port1, pcap1) + stream_id_2 = hPktgen.add_stream(tx_port1, rx_port1, pcap2) + stream_ids.append(stream_id_1) + stream_ids.append(stream_id_2) + + tx_port2 = self.tester.get_local_port(dut_port_index2) + rx_port2 = self.tester.get_local_port(dut_port_index1) + stream_id_3 = hPktgen.add_stream(tx_port2, rx_port2, pcap1) + stream_id_4 = hPktgen.add_stream(tx_port2, rx_port2, pcap2) + stream_ids.append(stream_id_3) + stream_ids.append(stream_id_4) + + # set pcap1 with mac protocol layer field vary configuration + stream_option1 = { + 'pcap': pcap1, + 'fields_config': { + 'mac': { + 'src': { + 'action': 'inc', + 'end': '00:00:00:00:00:FF', + 'start': '00:00:00:00:00:00', + 'step': 1}}}, + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT + } + } + # set stream option + hPktgen.config_stream(stream_id_1, stream_option1) + hPktgen.config_stream(stream_id_3, stream_option1) + + # set pcap2 with ip protocol layer field vary configuration + stream_option2 = { + 'pcap': pcap2, + 'fields_config': { + 'ip': { + 'dst': { + 'action': 'dec', + 'end': '0.0.0.255', + 'start': '0.0.0.1', + 'step': 1}, + 'src': { + 'action': 'random', + 'end': '0.0.0.64', + 'start': '0.0.0.1', + 'step': 1}}}, + 'stream_config': { + 'rate': 100, + 'transmit_mode': TRANSMIT_CONT + } + } + # set stream option + hPktgen.config_stream(stream_id_2, stream_option2) + hPktgen.config_stream(stream_id_4, stream_option2) + + # run testing scenario + traffic_option = { + 'method': 'rfc2544', + 'rate': 100, + 'pdr': 0.001, + 'drop_step': 1} + + hPktgen.measure(stream_ids, traffic_opt) \ No newline at end of file -- 1.9.3