Merge pull request #350 from jumpstarter-dev/uboot-console-debug

UbootConsole: implement debug mode and document

Author: mangelajo

docs/source/api-reference/drivers/index.md

@@ -20,6 +20,7 @@ sdwire.md
 shell.md
 snmp.md
 tftp.md
+uboot.md
 ustreamer.md
 yepkit.md
 ```

docs/source/api-reference/drivers/uboot.md

@@ -0,0 +1,25 @@
+# U-Boot driver
+
+The U-Boot driver is a driver for interacting with the U-Boot bootloader.
+This driver does not interact with the DUT directly, instead it should be
+configured with backing power and serial drivers.
+
+## Driver configuration
+
+```{literalinclude} uboot.yaml
+:language: yaml
+```
+
+```{doctest}
+:hide:
+>>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance
+>>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/uboot.yaml").instantiate()
+UbootConsole(...)
+```
+
+## Client API
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_uboot.client.UbootConsoleClient()
+    :members:
+```

docs/source/api-reference/drivers/uboot.yaml

@@ -0,0 +1,17 @@
+type: "jumpstarter_driver_uboot.driver.UbootConsole"
+children:
+  power:
+    type: "jumpstarter_driver_power.driver.MockPower"
+    config: {} # omitted, power driver configuration
+  serial:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config: # omitted, serial driver configuration
+      url: "loop://"
+      # instead of configuring the power and serial driver inline
+      # other drivers configured on the exporter can also be referenced
+      # power:
+      #   ref: "dutlink.power"
+      # serial:
+      #   ref: "dutlink.console"
+config:
+  prompt: "=>" # the u-boot command prompt to expect, defaults to "=>"

packages/jumpstarter-driver-flashers/jumpstarter_driver_flashers/client.py

@@ -61,7 +61,7 @@ def bootloader_shell(self):
         self.logger.info("Setting up flasher bundle files in exporter")
         self.call("setup_flasher_bundle")
         with self._services_up():
-            with self.uboot.reboot_to_console():
+            with self.uboot.reboot_to_console(debug=self._console_debug):
                 pass
             yield self.serial
 
@@ -375,7 +375,7 @@ def _busybox(self):
         """
 
         # make sure that the device is booted into the uboot console
-        with self.uboot.reboot_to_console():
+        with self.uboot.reboot_to_console(debug=self._console_debug):
             # run dhcp discovery and gather details useful for later
             self._dhcp_details = self.uboot.setup_dhcp()
             self.logger.info(f"discovered dhcp details: {self._dhcp_details}")

packages/jumpstarter-driver-uboot/jumpstarter_driver_uboot/client.py

@@ -1,3 +1,4 @@
+import sys
 from contextlib import contextmanager
 from functools import cached_property
 
@@ -10,14 +11,26 @@
 class UbootConsoleClient(CompositeClient):
     @cached_property
     def prompt(self) -> str:
+        """
+        U-Boot prompt to expect
+        """
+
         return self.call("get_prompt")
 
     @contextmanager
-    def reboot_to_console(self) -> None:
+    def reboot_to_console(self, *, debug=False) -> None:
         """
         Reboot to U-Boot console
 
         Power cycle the target and wait for the U-Boot prompt
+
+        Must be used as a context manager, other methods can only be
+        used within the reboot_to_console context
+
+        >>> with uboot.reboot_to_console(debug=True): # doctest: +SKIP
+        ...     uboot.set_env("foo", "bar")
+        ...     uboot.setup_dhcp()
+        >>> # uboot.set_env("foo", "baz") # invalid use
         """
 
         self.logger.info("Power cycling target...")
@@ -26,6 +39,9 @@ def reboot_to_console(self) -> None:
         self.logger.info("Waiting for U-Boot prompt...")
 
         with self.serial.pexpect() as p:
+            if debug:
+                p.logfile_read = sys.stdout.buffer
+
             for _ in range(100):  # TODO: configurable retries
                 try:
                     p.send(ESC)
@@ -44,6 +60,10 @@ def reboot_to_console(self) -> None:
                 delattr(self, "p")
 
     def run_command(self, cmd: str, timeout: int = 60, *, _internal_log=True) -> bytes:
+        """
+        Run raw command in the U-Boot console
+        """
+
         if _internal_log:
             self.logger.info(f"Running command: {cmd}")
         if not hasattr(self, "p"):
@@ -55,6 +75,10 @@ def run_command(self, cmd: str, timeout: int = 60, *, _internal_log=True) -> byt
         return self.p.before
 
     def run_command_checked(self, cmd: str, timeout: int = 60, check=True) -> list[str]:
+        """
+        Run command in the U-Boot console and check the exit code
+        """
+
         self.logger.info(f"Running command checked: {cmd}")
         output = self.run_command("{}; echo $?".format(cmd), _internal_log=False)
         parsed = output.strip().decode().splitlines()
@@ -73,6 +97,10 @@ def run_command_checked(self, cmd: str, timeout: int = 60, check=True) -> list[s
         return parsed[1:-1]
 
     def setup_dhcp(self, timeout: int = 60) -> DhcpInfo:
+        """
+        Setup dhcp in U-Boot
+        """
+
         self.logger.info("Running DHCP to obtain network configuration...")
 
         autoload = self.get_env("autoload", timeout=timeout)
@@ -116,6 +144,10 @@ def get_env(self, key: str, timeout: int = 5) -> str | None:
             raise TimeoutError(f"Timed out getting var {key}") from err
 
     def set_env(self, key: str, value: str | None, timeout: int = 5) -> None:
+        """
+        Set U-Boot environment variable value
+        """
+
         if value is not None:
             cmd = "setenv {} '{}'".format(key, value)
         else:
@@ -127,5 +159,9 @@ def set_env(self, key: str, value: str | None, timeout: int = 5) -> None:
             raise TimeoutError(f"Timed out setting var {key}") from err
 
     def set_env_dict(self, env: dict[str, str | None]) -> None:
+        """
+        Set multiple U-Boot environment variable value
+        """
+
         for key, value in env.items():
             self.set_env(key, value)

packages/jumpstarter-driver-uboot/jumpstarter_driver_uboot/driver_test.py

@@ -47,7 +47,7 @@ def test_driver_uboot_console(uboot_image):
 
         uboot = root.uboot
 
-        with uboot.reboot_to_console():
+        with uboot.reboot_to_console(debug=True):
             assert uboot.run_command_checked("version") == [
                 "U-Boot 2024.10 (Oct 11 2024 - 00:00:00 +0000)",
                 "",