Document uboot driver

Author: NickCao

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-uboot/jumpstarter_driver_uboot/client.py

@@ -11,6 +11,10 @@
 class UbootConsoleClient(CompositeClient):
     @cached_property
     def prompt(self) -> str:
+        """
+        U-Boot prompt to expect
+        """
+
         return self.call("get_prompt")
 
     @contextmanager
@@ -19,6 +23,14 @@ 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...")
@@ -48,6 +60,10 @@ def reboot_to_console(self, *, debug=False) -> 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"):
@@ -59,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()
@@ -77,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)
@@ -120,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:
@@ -131,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)