Re: [PATCH] docs: hardware runners setup

[Marek Marczykowski-Górecki <marmarek@xxxxxxxxxxxxxxxxxxxxxx>]

On Thu, Mar 06, 2025 at 01:54:48PM -0800, Stefano Stabellini wrote:
> Document how to setup a new hardware runner
> 
> Signed-off-by: Victor Lira <VictorM.Lira@xxxxxxx>
> Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxx>

I have some minor minor hints about pointing at more examples, but
regardless:
Reviewed-by: Marek Marczykowski-Górecki <marmarek@xxxxxxxxxxxxxxxxxxxxxx>

> 
> diff --git a/docs/misc/ci.rst b/docs/misc/ci.rst
> index 7aee55c5d2..ef3f183153 100644
> --- a/docs/misc/ci.rst
> +++ b/docs/misc/ci.rst
> @@ -19,6 +19,49 @@ 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.

Maybe hint also to look at scripts in automation/scripts for some of the
above? Especially, it isn't clear how power on/off control relates to
the other settings below.
I have also an article with details of some of the above, especially
power control and network boot: 
https://www.qubes-os.org/news/2022/05/05/automated-os-testing-on-physical-laptops/

> +
> +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"]

FWIW qubes configs are public:
https://github.com/QubesOS/tests-hw-setup/blob/28aa8b86208a54fc2ac986f06c66c92230bf771e/states/gitlab-runner-conf.toml
(this is template to be filled with the values by salt)

> +
> +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
> +
>  Selecting individual tests
>  **************************
>  

-- 
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab

Attachment: signature.asc
Description: PGP signature