Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/133913/?format=api
{ "id": 133913, "url": "http://patches.dpdk.org/api/patches/133913/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20231106171601.160749-13-juraj.linkes@pantheon.tech/", "project": { "id": 1, "url": "http://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": "<20231106171601.160749-13-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20231106171601.160749-13-juraj.linkes@pantheon.tech", "date": "2023-11-06T17:15:50", "name": "[v5,12/23] dts: interactive remote session docstring update", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "723b2def8c249289c7076b0e732050cf77a0af4f", "submitter": { "id": 1626, "url": "http://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "delegate": { "id": 2642, "url": "http://patches.dpdk.org/api/users/2642/?format=api", "username": "mcoquelin", "first_name": "Maxime", "last_name": "Coquelin", "email": "maxime.coquelin@redhat.com" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20231106171601.160749-13-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 30173, "url": "http://patches.dpdk.org/api/series/30173/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30173", "date": "2023-11-06T17:15:38", "name": "dts: add dts api docs", "version": 5, "mbox": "http://patches.dpdk.org/series/30173/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/133913/comments/", "check": "warning", "checks": "http://patches.dpdk.org/api/patches/133913/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 C5766432BB;\n\tMon, 6 Nov 2023 18:17:49 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id AE63D427E5;\n\tMon, 6 Nov 2023 18:16:24 +0100 (CET)", "from mail-ed1-f49.google.com (mail-ed1-f49.google.com\n [209.85.208.49]) by mails.dpdk.org (Postfix) with ESMTP id 1B63841149\n for <dev@dpdk.org>; Mon, 6 Nov 2023 18:16:22 +0100 (CET)", "by mail-ed1-f49.google.com with SMTP id\n 4fb4d7f45d1cf-53dd3f169d8so7852470a12.3\n for <dev@dpdk.org>; Mon, 06 Nov 2023 09:16:22 -0800 (PST)", "from jlinkes-PT-Latitude-5530.. (ip-46.34.243.197.o2inet.sk.\n [46.34.243.197]) by smtp.gmail.com with ESMTPSA id\n s10-20020a170906354a00b009b947aacb4bsm47016eja.191.2023.11.06.09.16.20\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Mon, 06 Nov 2023 09:16:21 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1699290982; x=1699895782; 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=DRBT1iCQ3izDtfSEhLlQAS7Wlh56tQtjJbqIRheTJP8=;\n b=h/1kOPsJedJ5gPbv0b+b4v2a2+aa5o1mUGzLsFZMdrC2VyMRtnHU0WZFo8t3B+zp1X\n kUd3HwMQerUxVSmCcoNN3pN2EIL0UZeruFrW3mFLVmJwUIaldf3cxB6vKrpH8eCCCy6C\n JQ9yUfHzPMniKWoJAESqMrJOObA4+DKzaYuzDbsu/8tCmxg1vFkz9z/mL1HbmfEj2v0h\n AOBiEOeQT13+okevFGgFB6anCqU9qPWGD3sj8dmEMayzQvK++MKG8yt6e1IztWSBYGyH\n NYn3pLOkC5nxaUT419A6vMPD2EII9XaYLT/1jHuHDVKB5jqmLOD9q8uXtxTN5FqCXeTo\n BihA==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1699290982; x=1699895782;\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=DRBT1iCQ3izDtfSEhLlQAS7Wlh56tQtjJbqIRheTJP8=;\n b=JNMNsQw30x+B5Vicikbng+RpeAr0JFmveNIQR+NJ000lmG6eF9D+VWyLqGbrvSzExR\n h5eQriNderBGhRuX5bDSusxyKZwE0A7IxJm0NYwXmwQjJWibfXMjV8TKUve756vIHc7f\n uyTt6afE0qYSJvjjZMv06mMDkreq53bBsr8+OUgYLdnZvNuJuVTWsznnK71p/8n6f5nw\n Z2W2z2Z/qWtKICxVy/mNS91LUfX9uiWFkBqig8Zzyg1YIdS+gspaEsW8zIViUY6dOqUf\n Bd+QH1jPIgUX5mdwb663wwn9y+x3AwxYfRAt5bZj7+tuIsFy4ddM8RjD1BJYiyNgJWAe\n 4ZNw==", "X-Gm-Message-State": "AOJu0YyM6kGmVJ7UVCF5DOXLrWDWFH0GodyDQBq1IJ8Cix+GeKaDvMPO\n ymwfEbOpAZd0oxzUc/Fs2JhwYA==", "X-Google-Smtp-Source": "\n AGHT+IEEC4leYqszpjM8yUwhZMMZfVJ0IliLpmErodDILXBYqlrvCWtR6pvXbMZD2SbCBgKcRuN96A==", "X-Received": "by 2002:a17:906:fe05:b0:9d2:5cf8:e61 with SMTP id\n wy5-20020a170906fe0500b009d25cf80e61mr14170321ejb.35.1699290981695;\n Mon, 06 Nov 2023 09:16:21 -0800 (PST)", "From": "=?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "To": "thomas@monjalon.net, Honnappa.Nagarahalli@arm.com,\n bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu,\n paul.szczepanek@arm.com, yoan.picchi@foss.arm.com", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[PATCH v5 12/23] dts: interactive remote session docstring update", "Date": "Mon, 6 Nov 2023 18:15:50 +0100", "Message-Id": "<20231106171601.160749-13-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231106171601.160749-1-juraj.linkes@pantheon.tech>", "References": "<20230831100407.59865-1-juraj.linkes@pantheon.tech>\n <20231106171601.160749-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 .../interactive_remote_session.py | 36 +++----\n .../remote_session/interactive_shell.py | 99 +++++++++++--------\n dts/framework/remote_session/python_shell.py | 26 ++++-\n dts/framework/remote_session/testpmd_shell.py | 61 +++++++++---\n 4 files changed, 150 insertions(+), 72 deletions(-)", "diff": "diff --git a/dts/framework/remote_session/interactive_remote_session.py b/dts/framework/remote_session/interactive_remote_session.py\nindex 9085a668e8..c1bf30ac61 100644\n--- a/dts/framework/remote_session/interactive_remote_session.py\n+++ b/dts/framework/remote_session/interactive_remote_session.py\n@@ -22,27 +22,23 @@\n class InteractiveRemoteSession:\n \"\"\"SSH connection dedicated to interactive applications.\n \n- This connection is created using paramiko and is a persistent connection to the\n- host. This class defines methods for connecting to the node and configures this\n- connection to send \"keep alive\" packets every 30 seconds. Because paramiko attempts\n- to use SSH keys to establish a connection first, providing a password is optional.\n- This session is utilized by InteractiveShells and cannot be interacted with\n- directly.\n-\n- Arguments:\n- node_config: Configuration class for the node you are connecting to.\n- _logger: Desired logger for this session to use.\n+ The connection is created using `paramiko <https://docs.paramiko.org/en/latest/>`_\n+ and is a persistent connection to the host. This class defines the methods for connecting\n+ to the node and configures the connection to send \"keep alive\" packets every 30 seconds.\n+ Because paramiko attempts to use SSH keys to establish a connection first, providing\n+ a password is optional. This session is utilized by InteractiveShells\n+ and cannot be interacted with directly.\n \n Attributes:\n- hostname: Hostname that will be used to initialize a connection to the node.\n- ip: A subsection of hostname that removes the port for the connection if there\n+ hostname: The hostname that will be used to initialize a connection to the node.\n+ ip: A subsection of `hostname` that removes the port for the connection if there\n is one. If there is no port, this will be the same as hostname.\n- port: Port to use for the ssh connection. This will be extracted from the\n- hostname if there is a port included, otherwise it will default to 22.\n+ port: Port to use for the ssh connection. This will be extracted from `hostname`\n+ if there is a port included, otherwise it will default to ``22``.\n username: User to connect to the node with.\n password: Password of the user connecting to the host. This will default to an\n empty string if a password is not provided.\n- session: Underlying paramiko connection.\n+ session: The underlying paramiko connection.\n \n Raises:\n SSHConnectionError: There is an error creating the SSH connection.\n@@ -58,9 +54,15 @@ class InteractiveRemoteSession:\n _node_config: NodeConfiguration\n _transport: Transport | None\n \n- def __init__(self, node_config: NodeConfiguration, _logger: DTSLOG) -> None:\n+ def __init__(self, node_config: NodeConfiguration, logger: DTSLOG) -> None:\n+ \"\"\"Connect to the node during initialization.\n+\n+ Args:\n+ node_config: The test run configuration of the node to connect to.\n+ logger: The logger instance this session will use.\n+ \"\"\"\n self._node_config = node_config\n- self._logger = _logger\n+ self._logger = logger\n self.hostname = node_config.hostname\n self.username = node_config.user\n self.password = node_config.password if node_config.password else \"\"\ndiff --git a/dts/framework/remote_session/interactive_shell.py b/dts/framework/remote_session/interactive_shell.py\nindex c24376b2a8..a98a822e91 100644\n--- a/dts/framework/remote_session/interactive_shell.py\n+++ b/dts/framework/remote_session/interactive_shell.py\n@@ -3,18 +3,20 @@\n \n \"\"\"Common functionality for interactive shell handling.\n \n-This base class, InteractiveShell, is meant to be extended by other classes that\n-contain functionality specific to that shell type. These derived classes will often\n-modify things like the prompt to expect or the arguments to pass into the application,\n-but still utilize the same method for sending a command and collecting output. How\n-this output is handled however is often application specific. If an application needs\n-elevated privileges to start it is expected that the method for gaining those\n-privileges is provided when initializing the class.\n+The base class, :class:`InteractiveShell`, is meant to be extended by subclasses that contain\n+functionality specific to that shell type. These subclasses will often modify things like\n+the prompt to expect or the arguments to pass into the application, but still utilize\n+the same method for sending a command and collecting output. How this output is handled however\n+is often application specific. If an application needs elevated privileges to start it is expected\n+that the method for gaining those privileges is provided when initializing the class.\n+\n+The :option:`--timeout` command line argument and the :envvar:`DTS_TIMEOUT`\n+environment variable configure the timeout of getting the output from command execution.\n \"\"\"\n \n from abc import ABC\n from pathlib import PurePath\n-from typing import Callable\n+from typing import Callable, ClassVar\n \n from paramiko import Channel, SSHClient, channel # type: ignore[import]\n \n@@ -30,28 +32,6 @@ class InteractiveShell(ABC):\n and collecting input until reaching a certain prompt. All interactive applications\n will use the same SSH connection, but each will create their own channel on that\n session.\n-\n- Arguments:\n- interactive_session: The SSH session dedicated to interactive shells.\n- logger: Logger used for displaying information in the console.\n- get_privileged_command: Method for modifying a command to allow it to use\n- elevated privileges. If this is None, the application will not be started\n- with elevated privileges.\n- app_args: Command line arguments to be passed to the application on startup.\n- timeout: Timeout used for the SSH channel that is dedicated to this interactive\n- shell. This timeout is for collecting output, so if reading from the buffer\n- and no output is gathered within the timeout, an exception is thrown.\n-\n- Attributes\n- _default_prompt: Prompt to expect at the end of output when sending a command.\n- This is often overridden by derived classes.\n- _command_extra_chars: Extra characters to add to the end of every command\n- before sending them. This is often overridden by derived classes and is\n- most commonly an additional newline character.\n- path: Path to the executable to start the interactive application.\n- dpdk_app: Whether this application is a DPDK app. If it is, the build\n- directory for DPDK on the node will be prepended to the path to the\n- executable.\n \"\"\"\n \n _interactive_session: SSHClient\n@@ -61,10 +41,22 @@ class InteractiveShell(ABC):\n _logger: DTSLOG\n _timeout: float\n _app_args: str\n- _default_prompt: str = \"\"\n- _command_extra_chars: str = \"\"\n- path: PurePath\n- dpdk_app: bool = False\n+\n+ #: Prompt to expect at the end of output when sending a command.\n+ #: This is often overridden by subclasses.\n+ _default_prompt: ClassVar[str] = \"\"\n+\n+ #: Extra characters to add to the end of every command\n+ #: before sending them. This is often overridden by subclasses and is\n+ #: most commonly an additional newline character.\n+ _command_extra_chars: ClassVar[str] = \"\"\n+\n+ #: Path to the executable to start the interactive application.\n+ path: ClassVar[PurePath]\n+\n+ #: Whether this application is a DPDK app. If it is, the build directory\n+ #: for DPDK on the node will be prepended to the path to the executable.\n+ dpdk_app: ClassVar[bool] = False\n \n def __init__(\n self,\n@@ -74,6 +66,19 @@ def __init__(\n app_args: str = \"\",\n timeout: float = SETTINGS.timeout,\n ) -> None:\n+ \"\"\"Create an SSH channel during initialization.\n+\n+ Args:\n+ interactive_session: The SSH session dedicated to interactive shells.\n+ logger: The logger instance this session will use.\n+ get_privileged_command: A method for modifying a command to allow it to use\n+ elevated privileges. If :data:`None`, the application will not be started\n+ with elevated privileges.\n+ app_args: The command line arguments to be passed to the application on startup.\n+ timeout: The timeout used for the SSH channel that is dedicated to this interactive\n+ shell. This timeout is for collecting output, so if reading from the buffer\n+ and no output is gathered within the timeout, an exception is thrown.\n+ \"\"\"\n self._interactive_session = interactive_session\n self._ssh_channel = self._interactive_session.invoke_shell()\n self._stdin = self._ssh_channel.makefile_stdin(\"w\")\n@@ -92,6 +97,10 @@ def _start_application(\n \n This method is often overridden by subclasses as their process for\n starting may look different.\n+\n+ Args:\n+ get_privileged_command: A function (but could be any callable) that produces\n+ the version of the command with elevated privileges.\n \"\"\"\n start_command = f\"{self.path} {self._app_args}\"\n if get_privileged_command is not None:\n@@ -99,16 +108,24 @@ def _start_application(\n self.send_command(start_command)\n \n def send_command(self, command: str, prompt: str | None = None) -> str:\n- \"\"\"Send a command and get all output before the expected ending string.\n+ \"\"\"Send `command` and get all output before the expected ending string.\n \n Lines that expect input are not included in the stdout buffer, so they cannot\n- be used for expect. For example, if you were prompted to log into something\n- with a username and password, you cannot expect \"username:\" because it won't\n- yet be in the stdout buffer. A workaround for this could be consuming an\n- extra newline character to force the current prompt into the stdout buffer.\n+ be used for expect.\n+\n+ Example:\n+ If you were prompted to log into something with a username and password,\n+ you cannot expect ``username:`` because it won't yet be in the stdout buffer.\n+ A workaround for this could be consuming an extra newline character to force\n+ the current `prompt` into the stdout buffer.\n+\n+ Args:\n+ command: The command to send.\n+ prompt: After sending the command, `send_command` will be expecting this string.\n+ If :data:`None`, will use the class's default prompt.\n \n Returns:\n- All output in the buffer before expected string\n+ All output in the buffer before expected string.\n \"\"\"\n self._logger.info(f\"Sending: '{command}'\")\n if prompt is None:\n@@ -126,8 +143,10 @@ def send_command(self, command: str, prompt: str | None = None) -> str:\n return out\n \n def close(self) -> None:\n+ \"\"\"Properly free all resources.\"\"\"\n self._stdin.close()\n self._ssh_channel.close()\n \n def __del__(self) -> None:\n+ \"\"\"Make sure the session is properly closed before deleting the object.\"\"\"\n self.close()\ndiff --git a/dts/framework/remote_session/python_shell.py b/dts/framework/remote_session/python_shell.py\nindex cc3ad48a68..c8e5957ef7 100644\n--- a/dts/framework/remote_session/python_shell.py\n+++ b/dts/framework/remote_session/python_shell.py\n@@ -1,12 +1,32 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2023 PANTHEON.tech s.r.o.\n \n+\"\"\"Python interactive shell.\n+\n+Typical usage example in a TestSuite::\n+\n+ from framework.remote_session import PythonShell\n+ python_shell = self.tg_node.create_interactive_shell(\n+ PythonShell, timeout=5, privileged=True\n+ )\n+ python_shell.send_command(\"print('Hello World')\")\n+ pytyon_shell.close()\n+\"\"\"\n+\n from pathlib import PurePath\n+from typing import ClassVar\n \n from .interactive_shell import InteractiveShell\n \n \n class PythonShell(InteractiveShell):\n- _default_prompt: str = \">>>\"\n- _command_extra_chars: str = \"\\n\"\n- path: PurePath = PurePath(\"python3\")\n+ \"\"\"Python interactive shell.\"\"\"\n+\n+ #: Python's prompt.\n+ _default_prompt: ClassVar[str] = \">>>\"\n+\n+ #: This forces the prompt to appear after sending a command.\n+ _command_extra_chars: ClassVar[str] = \"\\n\"\n+\n+ #: The Python executable.\n+ path: ClassVar[PurePath] = PurePath(\"python3\")\ndiff --git a/dts/framework/remote_session/testpmd_shell.py b/dts/framework/remote_session/testpmd_shell.py\nindex 1455b5a199..2632515d74 100644\n--- a/dts/framework/remote_session/testpmd_shell.py\n+++ b/dts/framework/remote_session/testpmd_shell.py\n@@ -1,45 +1,82 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2023 University of New Hampshire\n \n+\"\"\"Testpmd interactive shell.\n+\n+Typical usage example in a TestSuite::\n+\n+ testpmd_shell = self.sut_node.create_interactive_shell(\n+ TestPmdShell, privileged=True\n+ )\n+ devices = testpmd_shell.get_devices()\n+ for device in devices:\n+ print(device)\n+ testpmd_shell.close()\n+\"\"\"\n+\n from pathlib import PurePath\n-from typing import Callable\n+from typing import Callable, ClassVar\n \n from .interactive_shell import InteractiveShell\n \n \n class TestPmdDevice(object):\n+ \"\"\"The data of a device that testpmd can recognize.\n+\n+ Attributes:\n+ pci_address: The PCI address of the device.\n+ \"\"\"\n+\n pci_address: str\n \n def __init__(self, pci_address_line: str):\n+ \"\"\"Initialize the device from the testpmd output line string.\n+\n+ Args:\n+ pci_address_line: A line of testpmd output that contains a device.\n+ \"\"\"\n self.pci_address = pci_address_line.strip().split(\": \")[1].strip()\n \n def __str__(self) -> str:\n+ \"\"\"The PCI address captures what the device is.\"\"\"\n return self.pci_address\n \n \n class TestPmdShell(InteractiveShell):\n- path: PurePath = PurePath(\"app\", \"dpdk-testpmd\")\n- dpdk_app: bool = True\n- _default_prompt: str = \"testpmd>\"\n- _command_extra_chars: str = (\n- \"\\n\" # We want to append an extra newline to every command\n- )\n+ \"\"\"Testpmd interactive shell.\n+\n+ The testpmd shell users should never use\n+ the :meth:`~framework.remote_session.interactive_shell.InteractiveShell.send_command` method\n+ directly, but rather call specialized methods. If there isn't one that satisfies a need,\n+ it should be added.\n+ \"\"\"\n+\n+ #: The path to the testpmd executable.\n+ path: ClassVar[PurePath] = PurePath(\"app\", \"dpdk-testpmd\")\n+\n+ #: Flag this as a DPDK app so that it's clear this is not a system app and\n+ #: needs to be looked in a specific path.\n+ dpdk_app: ClassVar[bool] = True\n+\n+ #: The testpmd's prompt.\n+ _default_prompt: ClassVar[str] = \"testpmd>\"\n+\n+ #: This forces the prompt to appear after sending a command.\n+ _command_extra_chars: ClassVar[str] = \"\\n\"\n \n def _start_application(\n self, get_privileged_command: Callable[[str], str] | None\n ) -> None:\n- \"\"\"See \"_start_application\" in InteractiveShell.\"\"\"\n self._app_args += \" -- -i\"\n super()._start_application(get_privileged_command)\n \n def get_devices(self) -> list[TestPmdDevice]:\n- \"\"\"Get a list of device names that are known to testpmd\n+ \"\"\"Get a list of device names that are known to testpmd.\n \n- Uses the device info listed in testpmd and then parses the output to\n- return only the names of the devices.\n+ Uses the device info listed in testpmd and then parses the output.\n \n Returns:\n- A list of strings representing device names (e.g. 0000:14:00.1)\n+ A list of devices.\n \"\"\"\n dev_info: str = self.send_command(\"show device info all\")\n dev_list: list[TestPmdDevice] = []\n", "prefixes": [ "v5", "12/23" ] }