[PATCH 5/5] Documentation: add OpenBSD booting guide

[Ahmad Fatoum <a.fatoum@barebox.org>]

Covers the EFI boot flow, the simplefb stdout-path requirement for
framebuffer console, and the specific steps needed on systems with no
serial port where the framebuffer is the only console available.

Signed-off-by: Ahmad Fatoum <a.fatoum@barebox.org>
---
 Documentation/user/booting-openbsd.rst | 72 ++++++++++++++++++++++++++
 Documentation/user/user-manual.rst     |  1 +
 2 files changed, 73 insertions(+)
 create mode 100644 Documentation/user/booting-openbsd.rst

diff --git a/Documentation/user/booting-openbsd.rst b/Documentation/user/booting-openbsd.rst
new file mode 100644
index 000000000000..539e552d40d5
--- /dev/null
+++ b/Documentation/user/booting-openbsd.rst
@@ -0,0 +1,72 @@
+.. _booting_openbsd:
+
+Booting OpenBSD
+===============
+
+barebox can boot OpenBSD on EFI-capable ARM64 systems.  It acts as an EFI
+loader, exposing EFI protocols (block devices, GOP framebuffer, RNG, …) to
+subsequently loaded EFI binaries before handing off to the OS.
+
+Basic boot
+----------
+
+When ``CONFIG_EFI_LOADER_BOOTMGR`` is enabled, barebox's default boot order
+includes the ``efibootmgr`` target, which scans all storage devices for an
+ESP partition and boots ``EFI/BOOT/BOOTAA64.EFI`` from it.  If the OpenBSD
+installer placed its EFI bootloader on the ESP in the standard location, a
+plain ``boot`` invocation should find and start it without any additional
+configuration.
+
+To boot from a specific disk explicitly:
+
+.. code-block:: sh
+
+  boot virtioblk0
+
+or to persist:
+
+.. code-block:: sh
+
+  #!/bin/sh
+  nv boot.default=virtioblk0
+
+Framebuffer console
+-------------------
+
+OpenBSD's kernel discovers its framebuffer console by reading
+``/chosen/stdout-path`` from the device tree.  If that property points at a
+``simple-framebuffer`` node, the framebuffer is attached as the system console
+before the kernel's driver subsystem starts.
+
+barebox sets this up when the ``register_simplefb`` parameter on the
+framebuffer device is set to ``stdout-path``:
+
+.. code-block:: sh
+
+  fb0.register_simplefb=stdout-path
+
+The three valid values are:
+
+``disabled``
+  No simplefb DT node is created (default).
+
+``enabled``
+  A simplefb DT node is created but ``stdout-path`` is not set.
+
+``stdout-path``
+  A simplefb DT node is created and ``/chosen/stdout-path`` is pointed at
+  it, directing the OpenBSD kernel to use the framebuffer as its boot console.
+
+Systems without a serial console
+---------------------------------
+
+On laptops and desktops without an accessible serial port, ``stdout-path``
+mode is required, not optional.  Without it the kernel has no console after
+``ExitBootServices()`` and the screen stays black.
+
+Enable the framebuffer before booting and persist both settings:
+
+.. code-block:: sh
+
+  nv dev.fb0.enable=1
+  nv dev.fb0.register_simplefb=stdout-path
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index aa55017c69d7..b312f60e8187 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -26,6 +26,7 @@ Contents:
    usb
    ubi
    booting-linux
+   booting-openbsd
    devboot
    bootchooser
    remote-control
-- 
2.47.3