Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/134807/?format=api
{ "id": 134807, "url": "https://patches.dpdk.org/api/patches/134807/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20231204102429.106709-20-juraj.linkes@pantheon.tech/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20231204102429.106709-20-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20231204102429.106709-20-juraj.linkes@pantheon.tech", "date": "2023-12-04T10:24:27", "name": "[v9,19/21] dts: base traffic generators docstring update", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": true, "hash": "c93c6c1313b4ecf00d1af8746965367a3c2b3983", "submitter": { "id": 1626, "url": "https://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20231204102429.106709-20-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 30441, "url": "https://patches.dpdk.org/api/series/30441/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=30441", "date": "2023-12-04T10:24:08", "name": "dts: docstrings update", "version": 9, "mbox": "https://patches.dpdk.org/series/30441/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/134807/comments/", "check": "success", "checks": "https://patches.dpdk.org/api/patches/134807/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id B55DA4366A;\n\tMon, 4 Dec 2023 11:26:51 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 959F542D95;\n\tMon, 4 Dec 2023 11:24:58 +0100 (CET)", "from mail-wm1-f43.google.com (mail-wm1-f43.google.com\n [209.85.128.43]) by mails.dpdk.org (Postfix) with ESMTP id 6572E427E9\n for <dev@dpdk.org>; Mon, 4 Dec 2023 11:24:50 +0100 (CET)", "by mail-wm1-f43.google.com with SMTP id\n 5b1f17b1804b1-40c0a03eb87so10660925e9.3\n for <dev@dpdk.org>; Mon, 04 Dec 2023 02:24:50 -0800 (PST)", "from jlinkes-PT-Latitude-5530.pantheon.local ([81.89.53.154])\n by smtp.gmail.com with ESMTPSA id\n m28-20020a05600c3b1c00b0040b2b38a1fasm14255415wms.4.2023.12.04.02.24.49\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Mon, 04 Dec 2023 02:24:49 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1701685490; x=1702290290; darn=dpdk.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=GWyA4bZUAswyb84d4bT9GWkMZ5M49NrE4Df0L5kkviM=;\n b=EGHwBjYkQ2JXMq3n45C1Cl9DKa0IYs6LgPD+CteCZsCIp0gvFbGCuUeunyXfrCQ/+b\n +ZvVJHHizUrq02nmG9cf4uZLDMIaAdAFw7+uK+tZxQQqRF7Jlhg1j6IKBpXP8dhshxDM\n FnTbjfZG0f202HNAd/UTxVYZQuEPo7SfygelYABe25t/H+Hte8AJ3tEKSorWa2JJa6Hh\n LMmoXOEpiFF8IKD3LZT9iCdFLg2Y7hR4cT00EbWU2dFV5Xlbkrn+709Kt8KGjhsq8SZU\n E9smPkoI0ws6zy0AYfcEclVvvDGdANbeFTLX6yhTZe2dUcCrjwPFIHYUxjr+2RL8qgtL\n aeHQ==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1701685490; x=1702290290;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc\n :subject:date:message-id:reply-to;\n bh=GWyA4bZUAswyb84d4bT9GWkMZ5M49NrE4Df0L5kkviM=;\n b=LWOJjXN4CaQhmaQOAzckxAzJmRdJ8i46WcANpMxLY7bQZWav7BeCuxNugqzQb1zqR8\n GmL13to0lQh+4jsvIFc/Xw91KKx7PVcpCsDYPrj3Q9cGEIgJr8JlK8FB0S0me87zhEek\n kfF2/JsFVLzW1fssLgZb2wbIYT/1NLlaafTvUbZ4I4eOPfPTIE3EXwvlNf6IPB+9CXt3\n VV7aDpdCDpwMSGlpv5lNkmcGCnX/xjjcIuFl3dyi33uVdTtqmq81xRPbqtGimr1YI7n9\n Dq0ldtX9ciNmpOj/gews6z0YHXh9AlUvCTSQDuWoeTholEy7RIaiAChVVWz2EY4HHKTI\n LkHA==", "X-Gm-Message-State": "AOJu0YwYY0W7xPJUp0p58ZqyYQfmm1EDq6hH82mSv31Q3HCuz55EkqAr\n xcUv+82icDaXKJkzdzr9PCkrvA==", "X-Google-Smtp-Source": "\n AGHT+IHvIatc95chZVqAnRbi2lw4mFWpu32crFq0kmoYmTX5paXsrRuApgjpTnGJa3CByioutzFgaQ==", "X-Received": "by 2002:a1c:7210:0:b0:40c:c00:b49 with SMTP id\n n16-20020a1c7210000000b0040c0c000b49mr230345wmc.56.1701685490093;\n Mon, 04 Dec 2023 02:24:50 -0800 (PST)", "From": "=?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "To": "thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu,\n probb@iol.unh.edu, paul.szczepanek@arm.com, yoan.picchi@foss.arm.com,\n Luca.Vizzarro@arm.com", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[PATCH v9 19/21] dts: base traffic generators docstring update", "Date": "Mon, 4 Dec 2023 11:24:27 +0100", "Message-Id": "<20231204102429.106709-20-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231204102429.106709-1-juraj.linkes@pantheon.tech>", "References": "<20231123151344.162812-1-juraj.linkes@pantheon.tech>\n <20231204102429.106709-1-juraj.linkes@pantheon.tech>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "Format according to the Google format and PEP257, with slight\ndeviations.\n\nSigned-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>\n---\n .../traffic_generator/__init__.py | 22 ++++++++-\n .../capturing_traffic_generator.py | 45 +++++++++++--------\n .../traffic_generator/traffic_generator.py | 33 ++++++++------\n 3 files changed, 67 insertions(+), 33 deletions(-)", "diff": "diff --git a/dts/framework/testbed_model/traffic_generator/__init__.py b/dts/framework/testbed_model/traffic_generator/__init__.py\nindex 52888d03fa..11e2bd7d97 100644\n--- a/dts/framework/testbed_model/traffic_generator/__init__.py\n+++ b/dts/framework/testbed_model/traffic_generator/__init__.py\n@@ -1,6 +1,19 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2023 PANTHEON.tech s.r.o.\n \n+\"\"\"DTS traffic generators.\n+\n+A traffic generator is capable of generating traffic and then monitor returning traffic.\n+All traffic generators must count the number of received packets. Some may additionally capture\n+individual packets.\n+\n+A traffic generator may be software running on generic hardware or it could be specialized hardware.\n+\n+The traffic generators that only count the number of received packets are suitable only for\n+performance testing. In functional testing, we need to be able to dissect each arrived packet\n+and a capturing traffic generator is required.\n+\"\"\"\n+\n from framework.config import ScapyTrafficGeneratorConfig, TrafficGeneratorType\n from framework.exception import ConfigurationError\n from framework.testbed_model.node import Node\n@@ -12,8 +25,15 @@\n def create_traffic_generator(\n tg_node: Node, traffic_generator_config: ScapyTrafficGeneratorConfig\n ) -> CapturingTrafficGenerator:\n- \"\"\"A factory function for creating traffic generator object from user config.\"\"\"\n+ \"\"\"The factory function for creating traffic generator objects from the test run configuration.\n+\n+ Args:\n+ tg_node: The traffic generator node where the created traffic generator will be running.\n+ traffic_generator_config: The traffic generator config.\n \n+ Returns:\n+ A traffic generator capable of capturing received packets.\n+ \"\"\"\n match traffic_generator_config.traffic_generator_type:\n case TrafficGeneratorType.SCAPY:\n return ScapyTrafficGenerator(tg_node, traffic_generator_config)\ndiff --git a/dts/framework/testbed_model/traffic_generator/capturing_traffic_generator.py b/dts/framework/testbed_model/traffic_generator/capturing_traffic_generator.py\nindex 1fc7f98c05..0246590333 100644\n--- a/dts/framework/testbed_model/traffic_generator/capturing_traffic_generator.py\n+++ b/dts/framework/testbed_model/traffic_generator/capturing_traffic_generator.py\n@@ -23,19 +23,21 @@\n \n \n def _get_default_capture_name() -> str:\n- \"\"\"\n- This is the function used for the default implementation of capture names.\n- \"\"\"\n return str(uuid.uuid4())\n \n \n class CapturingTrafficGenerator(TrafficGenerator):\n \"\"\"Capture packets after sending traffic.\n \n- A mixin interface which enables a packet generator to declare that it can capture\n+ The intermediary interface which enables a packet generator to declare that it can capture\n packets and return them to the user.\n \n+ Similarly to :class:`~.traffic_generator.TrafficGenerator`, this class exposes\n+ the public methods specific to capturing traffic generators and defines a private method\n+ that must implement the traffic generation and capturing logic in subclasses.\n+\n The methods of capturing traffic generators obey the following workflow:\n+\n 1. send packets\n 2. capture packets\n 3. write the capture to a .pcap file\n@@ -44,6 +46,7 @@ class CapturingTrafficGenerator(TrafficGenerator):\n \n @property\n def is_capturing(self) -> bool:\n+ \"\"\"This traffic generator can capture traffic.\"\"\"\n return True\n \n def send_packet_and_capture(\n@@ -54,11 +57,12 @@ def send_packet_and_capture(\n duration: float,\n capture_name: str = _get_default_capture_name(),\n ) -> list[Packet]:\n- \"\"\"Send a packet, return received traffic.\n+ \"\"\"Send `packet` and capture received traffic.\n+\n+ Send `packet` on `send_port` and then return all traffic captured\n+ on `receive_port` for the given `duration`.\n \n- Send a packet on the send_port and then return all traffic captured\n- on the receive_port for the given duration. Also record the captured traffic\n- in a pcap file.\n+ The captured traffic is recorded in the `capture_name`.pcap file.\n \n Args:\n packet: The packet to send.\n@@ -68,7 +72,7 @@ def send_packet_and_capture(\n capture_name: The name of the .pcap file where to store the capture.\n \n Returns:\n- A list of received packets. May be empty if no packets are captured.\n+ The received packets. May be empty if no packets are captured.\n \"\"\"\n return self.send_packets_and_capture(\n [packet], send_port, receive_port, duration, capture_name\n@@ -82,11 +86,14 @@ def send_packets_and_capture(\n duration: float,\n capture_name: str = _get_default_capture_name(),\n ) -> list[Packet]:\n- \"\"\"Send packets, return received traffic.\n+ \"\"\"Send `packets` and capture received traffic.\n \n- Send packets on the send_port and then return all traffic captured\n- on the receive_port for the given duration. Also record the captured traffic\n- in a pcap file.\n+ Send `packets` on `send_port` and then return all traffic captured\n+ on `receive_port` for the given `duration`.\n+\n+ The captured traffic is recorded in the `capture_name`.pcap file. The target directory\n+ can be configured with the :option:`--output-dir` command line argument or\n+ the :envvar:`DTS_OUTPUT_DIR` environment variable.\n \n Args:\n packets: The packets to send.\n@@ -96,7 +103,7 @@ def send_packets_and_capture(\n capture_name: The name of the .pcap file where to store the capture.\n \n Returns:\n- A list of received packets. May be empty if no packets are captured.\n+ The received packets. May be empty if no packets are captured.\n \"\"\"\n self._logger.debug(get_packet_summaries(packets))\n self._logger.debug(\n@@ -121,10 +128,12 @@ def _send_packets_and_capture(\n receive_port: Port,\n duration: float,\n ) -> list[Packet]:\n- \"\"\"\n- The extended classes must implement this method which\n- sends packets on send_port and receives packets on the receive_port\n- for the specified duration. It must be able to handle no received packets.\n+ \"\"\"The implementation of :method:`send_packets_and_capture`.\n+\n+ The subclasses must implement this method which sends `packets` on `send_port`\n+ and receives packets on `receive_port` for the specified `duration`.\n+\n+ It must be able to handle receiving no packets.\n \"\"\"\n \n def _write_capture_from_packets(self, capture_name: str, packets: list[Packet]) -> None:\ndiff --git a/dts/framework/testbed_model/traffic_generator/traffic_generator.py b/dts/framework/testbed_model/traffic_generator/traffic_generator.py\nindex 0d9902ddb7..c49fbff488 100644\n--- a/dts/framework/testbed_model/traffic_generator/traffic_generator.py\n+++ b/dts/framework/testbed_model/traffic_generator/traffic_generator.py\n@@ -22,7 +22,8 @@\n class TrafficGenerator(ABC):\n \"\"\"The base traffic generator.\n \n- Defines the few basic methods that each traffic generator must implement.\n+ Exposes the common public methods of all traffic generators and defines private methods\n+ that must implement the traffic generation logic in subclasses.\n \"\"\"\n \n _config: TrafficGeneratorConfig\n@@ -30,14 +31,20 @@ class TrafficGenerator(ABC):\n _logger: DTSLOG\n \n def __init__(self, tg_node: Node, config: TrafficGeneratorConfig):\n+ \"\"\"Initialize the traffic generator.\n+\n+ Args:\n+ tg_node: The traffic generator node where the created traffic generator will be running.\n+ config: The traffic generator's test run configuration.\n+ \"\"\"\n self._config = config\n self._tg_node = tg_node\n self._logger = getLogger(f\"{self._tg_node.name} {self._config.traffic_generator_type}\")\n \n def send_packet(self, packet: Packet, port: Port) -> None:\n- \"\"\"Send a packet and block until it is fully sent.\n+ \"\"\"Send `packet` and block until it is fully sent.\n \n- What fully sent means is defined by the traffic generator.\n+ Send `packet` on `port`, then wait until `packet` is fully sent.\n \n Args:\n packet: The packet to send.\n@@ -46,9 +53,9 @@ def send_packet(self, packet: Packet, port: Port) -> None:\n self.send_packets([packet], port)\n \n def send_packets(self, packets: list[Packet], port: Port) -> None:\n- \"\"\"Send packets and block until they are fully sent.\n+ \"\"\"Send `packets` and block until they are fully sent.\n \n- What fully sent means is defined by the traffic generator.\n+ Send `packets` on `port`, then wait until `packets` are fully sent.\n \n Args:\n packets: The packets to send.\n@@ -60,19 +67,17 @@ def send_packets(self, packets: list[Packet], port: Port) -> None:\n \n @abstractmethod\n def _send_packets(self, packets: list[Packet], port: Port) -> None:\n- \"\"\"\n- The extended classes must implement this method which\n- sends packets on send_port. The method should block until all packets\n- are fully sent.\n+ \"\"\"The implementation of :method:`send_packets`.\n+\n+ The subclasses must implement this method which sends `packets` on `port`.\n+ The method should block until all `packets` are fully sent.\n+\n+ What fully sent means is defined by the traffic generator.\n \"\"\"\n \n @property\n def is_capturing(self) -> bool:\n- \"\"\"Whether this traffic generator can capture traffic.\n-\n- Returns:\n- True if the traffic generator can capture traffic, False otherwise.\n- \"\"\"\n+ \"\"\"This traffic generator can't capture traffic.\"\"\"\n return False\n \n @abstractmethod\n", "prefixes": [ "v9", "19/21" ] }