Format according to the Google format and PEP257, with slight
deviations.
Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
---
dts/framework/testbed_model/__init__.py | 16 ++++--
dts/framework/testbed_model/port.py | 53 +++++++++++++++----
dts/framework/testbed_model/virtual_device.py | 17 +++++-
3 files changed, 71 insertions(+), 15 deletions(-)
@@ -2,9 +2,19 @@
# Copyright(c) 2022-2023 University of New Hampshire
# Copyright(c) 2023 PANTHEON.tech s.r.o.
-"""
-This package contains the classes used to model the physical traffic generator,
-system under test and any other components that need to be interacted with.
+"""Testbed modelling.
+
+This package defines the testbed elements DTS works with:
+
+ * A system under test node: :class:`SutNode`,
+ * A traffic generator node: :class:`TGNode`,
+ * The ports of network interface cards (NICs) present on nodes: :class:`Port`,
+ * The logical cores of CPUs present on nodes: :class:`LogicalCore`,
+ * The virtual devices that can be created on nodes: :class:`VirtualDevice`,
+ * The operating systems running on nodes: :class:`LinuxSession` and :class:`PosixSession`.
+
+DTS needs to be able to connect to nodes and understand some of the hardware present on these nodes
+to properly build and test DPDK.
"""
# pylama:ignore=W0611
@@ -2,6 +2,13 @@
# Copyright(c) 2022 University of New Hampshire
# Copyright(c) 2023 PANTHEON.tech s.r.o.
+"""NIC port model.
+
+Basic port information, such as location (the port are identified by their PCI address on a node),
+drivers and address.
+"""
+
+
from dataclasses import dataclass
from framework.config import PortConfig
@@ -9,24 +16,35 @@
@dataclass(slots=True, frozen=True)
class PortIdentifier:
+ """The port identifier.
+
+ Attributes:
+ node: The node where the port resides.
+ pci: The PCI address of the port on `node`.
+ """
+
node: str
pci: str
@dataclass(slots=True)
class Port:
- """
- identifier: The PCI address of the port on a node.
-
- os_driver: The driver used by this port when the OS is controlling it.
- Example: i40e
- os_driver_for_dpdk: The driver the device must be bound to for DPDK to use it,
- Example: vfio-pci.
+ """Physical port on a node.
- Note: os_driver and os_driver_for_dpdk may be the same thing.
- Example: mlx5_core
+ The ports are identified by the node they're on and their PCI addresses. The port on the other
+ side of the connection is also captured here.
+ Each port is serviced by a driver, which may be different for the operating system (`os_driver`)
+ and for DPDK (`os_driver_for_dpdk`). For some devices, they are the same, e.g.: ``mlx5_core``.
- peer: The identifier of a port this port is connected with.
+ Attributes:
+ identifier: The PCI address of the port on a node.
+ os_driver: The operating system driver name when the operating system controls the port,
+ e.g.: ``i40e``.
+ os_driver_for_dpdk: The operating system driver name for use with DPDK, e.g.: ``vfio-pci``.
+ peer: The identifier of a port this port is connected with.
+ The `peer` is on a different node.
+ mac_address: The MAC address of the port.
+ logical_name: The logical name of the port. Must be discovered.
"""
identifier: PortIdentifier
@@ -37,6 +55,12 @@ class Port:
logical_name: str = ""
def __init__(self, node_name: str, config: PortConfig):
+ """Initialize the port from `node_name` and `config`.
+
+ Args:
+ node_name: The name of the port's node.
+ config: The test run configuration of the port.
+ """
self.identifier = PortIdentifier(
node=node_name,
pci=config.pci,
@@ -47,14 +71,23 @@ def __init__(self, node_name: str, config: PortConfig):
@property
def node(self) -> str:
+ """The node where the port resides."""
return self.identifier.node
@property
def pci(self) -> str:
+ """The PCI address of the port."""
return self.identifier.pci
@dataclass(slots=True, frozen=True)
class PortLink:
+ """The physical, cabled connection between the ports.
+
+ Attributes:
+ sut_port: The port on the SUT node connected to `tg_port`.
+ tg_port: The port on the TG node connected to `sut_port`.
+ """
+
sut_port: Port
tg_port: Port
@@ -1,16 +1,29 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright(c) 2023 PANTHEON.tech s.r.o.
+"""Virtual devices model.
+
+Alongside support for physical hardware, DPDK can create various virtual devices.
+"""
+
class VirtualDevice(object):
- """
- Base class for virtual devices used by DPDK.
+ """Base class for virtual devices used by DPDK.
+
+ Attributes:
+ name: The name of the virtual device.
"""
name: str
def __init__(self, name: str):
+ """Initialize the virtual device.
+
+ Args:
+ name: The name of the virtual device.
+ """
self.name = name
def __str__(self) -> str:
+ """This corresponds to the name used for DPDK devices."""
return self.name