[xen master] docs: hardware runners setup

[patchbot@xxxxxxx]

commit 55e2d86baaaecfa18cc8cfd3b1bb9eafafd9d61a
Author:     Stefano Stabellini <stefano.stabellini@xxxxxxx>
AuthorDate: Fri Mar 7 16:57:44 2025 -0800
Commit:     Stefano Stabellini <stefano.stabellini@xxxxxxx>
CommitDate: Fri Mar 7 16:57:44 2025 -0800

    docs: hardware runners setup
    
    Document how to setup a new hardware runner
    
    Signed-off-by: Victor Lira <VictorM.Lira@xxxxxxx>
    Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxx>
    Reviewed-by: Marek Marczykowski-Górecki <marmarek@xxxxxxxxxxxxxxxxxxxxxx>
---
 docs/misc/ci.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/docs/misc/ci.rst b/docs/misc/ci.rst
index 7aee55c5d2..8d9ebfb39d 100644
--- a/docs/misc/ci.rst
+++ b/docs/misc/ci.rst
@@ -19,6 +19,55 @@ After getting access to relevant runners, few extra changes 
are necessary in set
 2. Expand "Variables" section and add ``QUBES_JOBS=true`` variable for Qubes 
runners.
 3. Go to Settings -> Repository, expand "Branch rules" section and add a rule 
for protected branches - only those branches will get tests on the hardware 
runners. It's okay to use a pattern for branch name, and it's okay to allow 
force push.
 
+How to Set Up a New Hardware Runner
+***********************************
+
+A hardware runner is a GitLab runner designed to execute Xen tests on real 
hardware, such as an embedded board or a laptop. The GitLab runner runs on a 
controller PC, which is connected to the target board used for Xen testing. The 
controller PC can be any system, from a workstation to a Raspberry Pi.
+
+Steps to Set Up the Controller PC:
+
+1. Install the Docker service
+   - Follow the instructions at: [Docker Installation 
Guide](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository)
+
+2. Install the GitLab Runner service
+   - Follow the instructions at: [GitLab Runner Installation 
Guide](https://docs.gitlab.com/runner/install/linux-repository/#install-gitlab-runner)
+
+3. Register the runner with GitLab
+   - Generate a runner token with a specific tag to identify it.
+   - Run `gitlab-runner register` and enter the token. Accepting the default 
settings is sufficient.
+
+These steps are common for setting up any GitLab runner. However, for hardware 
runners, additional configurations are required to enable the controller PC to:
+
+- Power on and off the target board.
+- Connect to the serial interface of the target board.
+- Establish an Ethernet connection with the target board.
+- Run a TFTP server with a TFTP root directory accessible by GitLab container 
tests.
+  - This allows the test script to place binaries, such as Xen, in the TFTP 
root before powering on the target board.
+
+To enable the required capabilities, edit the GitLab Runner configuration file 
located at `/etc/gitlab-runner/config.toml`:
+
+- Map the TFTP boot directory.
+- Map the serial device of the target board.
+
+Example Configuration:
+
+    volumes = ["/scratch/gitlab-runner:/scratch/gitlab-runner"]
+    devices = ["/dev/ttyUSB0:/dev/ttyUSB0"]
+
+After making these changes, restart the GitLab Runner service:
+
+    gitlab-runner restart
+
+This completes the setup of the hardware runner. The system is now ready for 
executing Xen tests on real hardware. As an example, to execute tests on an AMD 
x86 embedded board, we currently use the following script:
+
+    automation/scripts/xilinx-smoke-dom0-x86_64.sh
+
+Other examples are available under automation/scripts, such as
+automation/scripts/qubes-x86-64.sh, and at external locations:
+`<https://www.qubes-os.org/news/2022/05/05/automated-os-testing-on-physical-laptops>`_,
+`<https://github.com/QubesOS/tests-hw-setup/blob/28aa8b86208a54fc2ac986f06c66c92230bf771e/states/gitlab-runner-conf.toml>`_.
+
+
 Selecting individual tests
 **************************
 
--
generated by git-patchbot for /home/xen/git/xen.git#master