[v4,3/4] dts: add methods for modifying MTU to testpmd shell

Message ID 20240613181510.30135-4-jspewock@iol.unh.edu (mailing list archive)
State Superseded
Delegated to: Thomas Monjalon
Headers
Series Add second scatter test case |

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Jeremy Spewock June 13, 2024, 6:15 p.m. UTC
  From: Jeremy Spewock <jspewock@iol.unh.edu>

There are methods within DTS currently that support updating the MTU of
ports on a node, but the methods for doing this in a linux session rely
on the ip command and the port being bound to the kernel driver. Since
test suites are run while bound to the driver for DPDK, there needs to
be a way to modify the value while bound to said driver as well. This is
done by using testpmd to modify the MTU.

Signed-off-by: Jeremy Spewock <jspewock@iol.unh.edu>
---
 dts/framework/remote_session/testpmd_shell.py | 102 +++++++++++++++++-
 1 file changed, 101 insertions(+), 1 deletion(-)
  

Comments

Juraj Linkeš June 19, 2024, 8:16 a.m. UTC | #1
> +def stop_then_start_port_decorator(

The name shouldn't contain "decorator". Just the docstring should 
mention it's a decorator.

> +    func: Callable[["TestPmdShell", int, Any, bool], None]

I'm thinking about this type. Sounds like there are too many conditions 
that need to be satisfied. The problem is with the verify parameter. Do 
we actually need it? If we're decorating a function, that may imply we 
always want to verify the port stop/start. In which circumstance we 
wouldn't want to verify that (the decorated function would need to not 
verify what it's doing, but what function would that be and would we 
actually want to not verify the port stop/start even then)?

The requirement of port_id is fine, as this only work with ports (so 
port_id must be somewhere among the parameters) and it being the first 
is also fine, but we should document it. A good place seems to be the 
class docstring, somewhere around "If there isn't one that satisfies a 
need, it should be added.".

> +) -> Callable[["TestPmdShell", int, Any, bool], None]:
> +    """Decorator that stops a port, runs decorated function, then starts the port.
> +
> +    The function being decorated must be a method defined in :class:`TestPmdShell` that takes a
> +    port ID (as an int) as its first parameter and has a "verify" parameter (as a bool) as its last
> +    parameter. The port ID and verify parameters will be passed into
> +    :meth:`TestPmdShell._stop_port` so that the correct port is stopped/started and verification
> +    takes place if desired.
> +
> +    Args:
> +        func: The function to run while the port is stopped.

The description of required argument should probably be here (maybe just 
here, but could also be above).

> +
> +    Returns:
> +        Wrapper function that stops a port, runs the decorated function, then starts the port.

This would be the function that's already been wrapped, right?


> +    def _start_port(self, port_id: int, verify: bool = True) -> None:
> +        """Start port `port_id` in testpmd.

with `port_id`

> +
> +        Because the port may need to be stopped to make some configuration changes, it naturally
> +        follows that it will need to be started again once those changes have been made.
> +
> +        Args:
> +            port_id: ID of the port to start.
> +            verify: If :data:`True` the output will be scanned in an attempt to verify that the
> +                port came back up without error. Defaults to True.

The second True is not marked as :data: (also in the other method).
A note on docstrings of private members: we don't need to be as detailed 
as these are not rendered. We should still provide some docs if those 
would be helpful for developers (but don't need to document everything 
for people using the API).
  
Jeremy Spewock June 20, 2024, 7:23 p.m. UTC | #2
On Wed, Jun 19, 2024 at 4:16 AM Juraj Linkeš <juraj.linkes@pantheon.tech> wrote:
>
>
> > +def stop_then_start_port_decorator(
>
> The name shouldn't contain "decorator". Just the docstring should
> mention it's a decorator.

Ack.

>
> > +    func: Callable[["TestPmdShell", int, Any, bool], None]
>
> I'm thinking about this type. Sounds like there are too many conditions
> that need to be satisfied. The problem is with the verify parameter. Do
> we actually need it? If we're decorating a function, that may imply we
> always want to verify the port stop/start. In which circumstance we
> wouldn't want to verify that (the decorated function would need to not
> verify what it's doing, but what function would that be and would we
> actually want to not verify the port stop/start even then)?

I agree the parameter requirements are a little clunky and I played
with them for a while, but this one seemed the most "correct" to me.
We could create a policy that any method that is decorated with this
function must verify the port stopping and starting worked, but if we
did that I think you would have to also add to the policy that the
method being decorated must also always verify it was successful. I
don't think it makes sense to call a function and specify that you
don't want to verify success, and then still verify some component of
what the function is doing (starting and stopping ports in this case).
I think it would be fine to have this as a policy, but it's slightly
more limiting for users than other methods that testpmd shell offers.

I don't really know of an example when you wouldn't want to verify any
of the methods in TestpmdShell other than in case the developer is
expecting it to fail or it might not matter to the test if it was
successful or not for some reason. Considering we are already
following the path of optionally verifying all methods that can be
verified in the testpmd shell anyway, I didn't see the verify boolean
as anything extra for the methods to really have. We could instead
change to always verifying everything, but a change like that probably
doesn't fit the scope of this patch.

>
> The requirement of port_id is fine, as this only work with ports (so
> port_id must be somewhere among the parameters) and it being the first
> is also fine, but we should document it. A good place seems to be the
> class docstring, somewhere around "If there isn't one that satisfies a
> need, it should be added.".

That's a good point, I'll add some more notes about it.

>
> > +) -> Callable[["TestPmdShell", int, Any, bool], None]:
> > +    """Decorator that stops a port, runs decorated function, then starts the port.
> > +
> > +    The function being decorated must be a method defined in :class:`TestPmdShell` that takes a
> > +    port ID (as an int) as its first parameter and has a "verify" parameter (as a bool) as its last
> > +    parameter. The port ID and verify parameters will be passed into
> > +    :meth:`TestPmdShell._stop_port` so that the correct port is stopped/started and verification
> > +    takes place if desired.
> > +
> > +    Args:
> > +        func: The function to run while the port is stopped.
>
> The description of required argument should probably be here (maybe just
> here, but could also be above).

Ack.

>
> > +
> > +    Returns:
> > +        Wrapper function that stops a port, runs the decorated function, then starts the port.
>
> This would be the function that's already been wrapped, right?

I was trying to convey that this returns the function that wraps the
decorated function so I called it the "wrapper function", but maybe my
wording was a little confusing.

>
>
> > +    def _start_port(self, port_id: int, verify: bool = True) -> None:
> > +        """Start port `port_id` in testpmd.
>
> with `port_id`

Ack.

>
> > +
> > +        Because the port may need to be stopped to make some configuration changes, it naturally
> > +        follows that it will need to be started again once those changes have been made.
> > +
> > +        Args:
> > +            port_id: ID of the port to start.
> > +            verify: If :data:`True` the output will be scanned in an attempt to verify that the
> > +                port came back up without error. Defaults to True.
>
> The second True is not marked as :data: (also in the other method).
> A note on docstrings of private members: we don't need to be as detailed
> as these are not rendered. We should still provide some docs if those
> would be helpful for developers (but don't need to document everything
> for people using the API).

Right, I noticed that in some places they were less formal than others
and figured it was because they were private. I was sticking with the
general API layout regardless just as I felt it would be better to
have more information than necessary rather than less, but I'll keep
this in mind and not include some of the more redundant things like
the args in this case.

>
  
Juraj Linkeš June 21, 2024, 8:08 a.m. UTC | #3
>>> +    func: Callable[["TestPmdShell", int, Any, bool], None]
>>
>> I'm thinking about this type. Sounds like there are too many conditions
>> that need to be satisfied. The problem is with the verify parameter. Do
>> we actually need it? If we're decorating a function, that may imply we
>> always want to verify the port stop/start. In which circumstance we
>> wouldn't want to verify that (the decorated function would need to not
>> verify what it's doing, but what function would that be and would we
>> actually want to not verify the port stop/start even then)?
> 
> I agree the parameter requirements are a little clunky and I played
> with them for a while, but this one seemed the most "correct" to me.
> We could create a policy that any method that is decorated with this
> function must verify the port stopping and starting worked, but if we
> did that I think you would have to also add to the policy that the
> method being decorated must also always verify it was successful. I
> don't think it makes sense to call a function and specify that you
> don't want to verify success, and then still verify some component of
> what the function is doing (starting and stopping ports in this case).
> I think it would be fine to have this as a policy, but it's slightly
> more limiting for users than other methods that testpmd shell offers.
> 
> I don't really know of an example when you wouldn't want to verify any
> of the methods in TestpmdShell other than in case the developer is
> expecting it to fail or it might not matter to the test if it was
> successful or not for some reason. Considering we are already
> following the path of optionally verifying all methods that can be
> verified in the testpmd shell anyway, I didn't see the verify boolean
> as anything extra for the methods to really have. We could instead
> change to always verifying everything, but a change like that probably
> doesn't fit the scope of this patch.
> 

One more thing I've thought of which could be the best of both world is 
to add the optional verify parameter to the decorator itself. That way 
we could disable verification independently of whether the decorated 
function does verification if need be. And the decorator would be less 
coupled with the functions.
  

Patch

diff --git a/dts/framework/remote_session/testpmd_shell.py b/dts/framework/remote_session/testpmd_shell.py
index 805bb3a77d..09f80cb250 100644
--- a/dts/framework/remote_session/testpmd_shell.py
+++ b/dts/framework/remote_session/testpmd_shell.py
@@ -20,7 +20,7 @@ 
 from enum import Enum, auto
 from functools import partial
 from pathlib import PurePath
-from typing import Callable, ClassVar
+from typing import Any, Callable, ClassVar
 
 from framework.exception import InteractiveCommandExecutionError
 from framework.settings import SETTINGS
@@ -82,6 +82,39 @@  class TestPmdForwardingModes(StrEnum):
     recycle_mbufs = auto()
 
 
+def stop_then_start_port_decorator(
+    func: Callable[["TestPmdShell", int, Any, bool], None]
+) -> Callable[["TestPmdShell", int, Any, bool], None]:
+    """Decorator that stops a port, runs decorated function, then starts the port.
+
+    The function being decorated must be a method defined in :class:`TestPmdShell` that takes a
+    port ID (as an int) as its first parameter and has a "verify" parameter (as a bool) as its last
+    parameter. The port ID and verify parameters will be passed into
+    :meth:`TestPmdShell._stop_port` so that the correct port is stopped/started and verification
+    takes place if desired.
+
+    Args:
+        func: The function to run while the port is stopped.
+
+    Returns:
+        Wrapper function that stops a port, runs the decorated function, then starts the port.
+    """
+
+    def wrapper(shell: "TestPmdShell", port_id: int, *args, **kwargs) -> None:
+        """Function that wraps the instance method of :class:`TestPmdShell`.
+
+        Args:
+            shell: Instance of the shell containing the method to decorate.
+            port_id: ID of the port to stop/start.
+        """
+        verify_value = kwargs["verify"] if "verify" in kwargs else args[-1]
+        shell._stop_port(port_id, verify_value)
+        func(shell, port_id, *args, **kwargs)
+        shell._start_port(port_id, verify_value)
+
+    return wrapper
+
+
 class TestPmdShell(SingleActiveInteractiveShell):
     """Testpmd interactive shell.
 
@@ -227,6 +260,73 @@  def set_forward_mode(self, mode: TestPmdForwardingModes, verify: bool = True):
                 f"Test pmd failed to set fwd mode to {mode.value}"
             )
 
+    def _stop_port(self, port_id: int, verify: bool = True) -> None:
+        """Stop port with `port_id` in testpmd.
+
+        Depending on the PMD, the port may need to be stopped before configuration can take place.
+        This method wraps the command needed to properly stop ports and take their link down.
+
+        Args:
+            port_id: ID of the port to take down.
+            verify: If :data:`True` the output will be scanned in an attempt to verify that the
+                stopping of ports was successful. Defaults to True.
+
+        Raises:
+            InteractiveCommandExecutionError: If `verify` is :data:`True` and the port did not
+                successfully stop.
+        """
+        stop_port_output = self.send_command(f"port stop {port_id}")
+        if verify and ("Done" not in stop_port_output):
+            self._logger.debug(f"Failed to stop port {port_id}. Output was:\n{stop_port_output}")
+            raise InteractiveCommandExecutionError(f"Test pmd failed to stop port {port_id}.")
+
+    def _start_port(self, port_id: int, verify: bool = True) -> None:
+        """Start port `port_id` in testpmd.
+
+        Because the port may need to be stopped to make some configuration changes, it naturally
+        follows that it will need to be started again once those changes have been made.
+
+        Args:
+            port_id: ID of the port to start.
+            verify: If :data:`True` the output will be scanned in an attempt to verify that the
+                port came back up without error. Defaults to True.
+
+        Raises:
+            InteractiveCommandExecutionError: If `verify` is :data:`True` and the port did not come
+                back up.
+        """
+        start_port_output = self.send_command(f"port start {port_id}")
+        if verify and ("Done" not in start_port_output):
+            self._logger.debug(f"Failed to start port {port_id}. Output was:\n{start_port_output}")
+            raise InteractiveCommandExecutionError(f"Test pmd failed to start port {port_id}.")
+
+    @stop_then_start_port_decorator
+    def set_port_mtu(self, port_id: int, mtu: int, verify: bool = True) -> None:
+        """Change the MTU of a port using testpmd.
+
+        Some PMDs require that the port be stopped before changing the MTU, and it does no harm to
+        stop the port before configuring in cases where it isn't required, so we first stop ports,
+        then update the MTU, then start the ports again afterwards.
+
+        Args:
+            port_id: ID of the port to adjust the MTU on.
+            mtu: Desired value for the MTU to be set to.
+            verify: If `verify` is :data:`True` then the output will be scanned in an attempt to
+                verify that the mtu was properly set on the port. Defaults to :data:`True`.
+
+        Raises:
+            InteractiveCommandExecutionError: If `verify` is :data:`True` and the MTU was not
+                properly updated on the port matching `port_id`.
+        """
+        set_mtu_output = self.send_command(f"port config mtu {port_id} {mtu}")
+        if verify and (f"MTU: {mtu}" not in self.send_command(f"show port info {port_id}")):
+            self._logger.debug(
+                f"Failed to set mtu to {mtu} on port {port_id}." f" Output was:\n{set_mtu_output}"
+            )
+            raise InteractiveCommandExecutionError(
+                f"Test pmd failed to update mtu of port {port_id} to {mtu}"
+            )
+
     def _close(self) -> None:
         """Overrides :meth:`~.interactive_shell.close`."""
         self.stop()