docs: fix a bunch of typos
[mesa.git] / docs / ci / bare-metal.rst
1 Bare-metal CI
2 =============
4 The bare-metal scripts run on a system with gitlab-runner and docker,
5 connected to potentially multiple bare-metal boards that run tests of
6 Mesa. Currently only "fastboot" and "ChromeOS Servo" devices are
7 supported.
9 In comparison with LAVA, this doesn't involve maintaining a separate
10 webservice with its own job scheduler and replicating jobs between the
11 two. It also places more of the board support in git, instead of
12 webservice configuration. On the other hand, the serial interactions
13 and bootloader support are more primitive.
15 Requirements (fastboot)
16 -----------------------
18 This testing requires power control of the DUTs by the gitlab-runner
19 machine, since this is what we use to reset the system and get back to
20 a pristine state at the start of testing.
22 We require access to the console output from the gitlab-runner system,
23 since that is how we get the final results back from the tests. You
24 should probably have the console on a serial connection, so that you
25 can see bootloader progress.
27 The boards need to be able to have a kernel/initramfs supplied by the
28 gitlab-runner system, since the initramfs is what contains the Mesa
29 testing payload.
31 The boards should have networking, so that (in a future iteration of
32 this code) we can extract the dEQP .xml results to artifacts on
33 gitlab.
35 Requirements (servo)
36 --------------------
38 For servo-connected boards, we can use the EC connection for power
39 control to reboot the board. However, loading a kernel is not as easy
40 as fastboot, so we assume your bootloader can do TFTP, and that your
41 gitlab-runner mounts the runner's tftp directory specific to the board
42 at /tftp in the container.
44 Since we're going the TFTP route, we also use NFS root. This avoids
45 packing the rootfs and sending it to the board as a ramdisk, which
46 means we can support larger rootfses (for piglit or tracie testing),
47 at the cost of needing more storage on the runner.
49 Telling the board about where its TFTP and NFS should come from is
50 done using dnsmasq on the runner host. For example, this snippet in
51 the dnsmasq.conf.d in the google farm, with the gitlab-runner host we
52 call "servo"::
54 dhcp-host=1c:69:7a:0d:a3:d3,,set:servo
56 # Fixed dhcp addresses for my sanity, and setting a tag for
57 # specializing other DHCP options
58 dhcp-host=a0:ce:c8:c8:d9:5d,,set:cheza1
59 dhcp-host=a0:ce:c8:c8:d8:81,,set:cheza2
61 # Specify the next server, watch out for the double ',,'. The
62 # filename didn't seem to get picked up by the bootloader, so we use
63 # tftp-unique-root and mount directories like
64 # /srv/tftp/ as /tftp in the job containers.
65 tftp-unique-root
66 dhcp-boot=tag:cheza1,cheza1/vmlinuz,,
67 dhcp-boot=tag:cheza2,cheza2/vmlinuz,,
69 dhcp-option=tag:cheza1,option:root-path,/srv/nfs/cheza1
70 dhcp-option=tag:cheza2,option:root-path,/srv/nfs/cheza2
72 Setup
73 -----
75 Each board will be registered in fd.o gitlab. You'll want something
76 like this to register a fastboot board:
78 .. code-block:: console
80 sudo gitlab-runner register \
81 --url \
82 --registration-token $1 \
83 --name MY_BOARD_NAME \
84 --tag-list MY_BOARD_TAG \
85 --executor docker \
86 --docker-image "alpine:latest" \
87 --docker-volumes "/dev:/dev" \
88 --docker-network-mode "host" \
89 --docker-privileged \
90 --non-interactive
92 For a servo board, you'll need to also volume mount the board's NFS
93 root dir at /nfs and TFTP kernel directory at /tftp.
95 The registration token has to come from a fd.o gitlab admin going to
98 The name scheme for Google's lab is google-freedreno-boardname-n, and
99 our tag is something like google-freedreno-db410c. The tag is what
100 identifies a board type so that board-specific jobs can be dispatched
101 into that pool.
103 We need privileged mode and the /dev bind mount in order to get at the
104 serial console and fastboot USB devices (--device arguments don't
105 apply to devices that show up after container start, which is the case
106 with fastboot, and the servo serial devices are actually links to
107 /dev/pts). We use host network mode so that we can (in the future)
108 spin up a server to collect XML results for fastboot.
110 Once you've added your boards, you're going to need to add a little
111 more customization in ``/etc/gitlab-runner/config.toml``. First, add
112 ``concurrent = <number of boards>`` at the top ("we should have up to
113 this many jobs running managed by this gitlab-runner"). Then for each
114 board's runner, set ``limit = 1`` ("only 1 job served by this board at a
115 time"). Finally, add the board-specific environment variables
116 required by your bare-metal script, something like::
118 [[runners]]
119 name = "google-freedreno-db410c-1"
120 environment = ["BM_SERIAL=/dev/ttyDB410c8", " 8", "BM_FASTBOOT_SERIAL=15e9e390"]
122 Once you've updated your runners' configs, restart with ``sudo service
123 gitlab-runner restart``