docs: Document AskfirstInitializer

Signed-off-by: Harald Seiler <hws@denx.de>
Rahix · Aug 24, 2023 · b561037 · b561037
1 parent 07f7612
commit b561037
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 0 deletions.
diff --git a/Documentation/modules/machine_board.rst b/Documentation/modules/machine_board.rst
@@ -205,3 +205,6 @@ and login.
 
 .. autoclass:: tbot.machine.board.LinuxBootLogin
    :members:
+
+.. autoclass:: tbot.machine.board.AskfirstInitializer
+   :members:
diff --git a/tbot/machine/board/linux.py b/tbot/machine/board/linux.py
@@ -202,8 +202,41 @@ def _init_machine(self) -> typing.Iterator:
 
 
 class AskfirstInitializer(machine.Initializer, LinuxBoot):
+    """
+    Initializer to deal with ``askfirst`` TTYs.
+
+    On some boards, the console is configured with ``askfirst`` which means that
+    the getty for logging in is only spawned after an initial ENTER is sent.
+    This initializer takes care of that by first waiting for the ``askfirst``
+    prompt and then sending ENTER.
+
+    The ``askfirst`` prompt can be customized with the ``askfirst_prompt`` attribute.
+
+    **Example**:
+
+    .. code-block:: python
+
+        from tbot.machine import board, linux
+
+        class StandaloneLinux(
+            board.Connector,
+            board.AskfirstInitializer,
+            board.LinuxBootLogin,
+            linux.Bash,
+        ):
+            # board.LinuxBootLogin config:
+            username = "root"
+            password = "hunter2"
+
+    .. versionadded:: UNRELEASED
+    """
+
     askfirst_prompt = "Please press Enter to activate this console."
+    """
+    Prompt that indicates the board is waiting for ``askfirst`` confirmation.
+    """
 
+    # For proper integration with LinuxBootLogin
     boot_timeout: typing.Optional[float] = None
     _boot_start: typing.Optional[float] = None
     bootlog: str