docs/ci: Add docs for using a POE switch to control boards, like nouveau.

Reviewed-by: Christian Gmeiner <christian.gmeiner@gmail.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/15201>

docs/ci/bare-metal.rst

@@ -3,7 +3,7 @@ Bare-metal CI
 
 The bare-metal scripts run on a system with gitlab-runner and Docker,
 connected to potentially multiple bare-metal boards that run tests of
-Mesa.  Currently only "fastboot" and "ChromeOS Servo" devices are
+Mesa.  Currently "fastboot", "ChromeOS Servo", and POE-powered devices are
 supported.
 
 In comparison with LAVA, this doesn't involve maintaining a separate
@@ -77,6 +77,61 @@ call "servo"::
 See `src/freedreno/ci/gitlab-ci.yml` for an example of servo on cheza.  Note
 that other servo boards in CI are managed using LAVA.
 
+Requirements (POE)
+------------------
+
+For boards with 30W or less power consumption, POE can be used for the power
+control.  The parts list ends up looking something like (for example):
+
+- x86-64 gitlab-runner machine with a mid-range CPU, and 3+ GB of SSD storage
+  per board.  This can host at least 15 boards in our experience.
+- Cisco 2960S gigabit ethernet switch with POE. (Cisco 3750G, 3560G, or 2960G
+  were also recommended as reasonable-priced HW, but make sure the name ends in
+  G, X, or S)
+- POE splitters to power the boards (you can find ones that go to micro USB,
+  USBC, and 5V barrel jacks at least)
+- USB serial cables (Adafruit sells pretty reliable ones)
+- A large powered USB hub for all the serial cables
+- A pile of ethernet cables
+
+You'll talk to the Cisco for configuration using its USB port, which provides a
+serial terminal at 9600 baud.  You need to enable SNMP control, which we'll do
+using a "mesaci" community name that the gitlab runner can access as its
+authentication (no password) to configure.  To talk to the SNMP on the router,
+you need to put an ip address on the default vlan (vlan 1).
+
+Setting that up looks something like:
+
+.. code-block: console
+
+  Switch>
+  Password:
+  Switch#configure terminal
+  Switch(config)#interface Vlan 1
+  Switch(config-if)#ip address 10.42.0.2 255.255.0.0
+  Switch(config-if)#end
+  Switch(config)#snmp-server community mesaci RW
+  Switch(config)#end
+  Switch#copy running-config startup-config
+
+With that set up, you should be able to power on/off a port with something like:
+
+.. code-block: console
+
+  % snmpset -v2c -r 3 -t 30 -cmesaci 10.42.0.2 1.3.6.1.4.1.9.9.402.1.2.1.1.1.1 i 1
+  % snmpset -v2c -r 3 -t 30 -cmesaci 10.42.0.2 1.3.6.1.4.1.9.9.402.1.2.1.1.1.1 i 4
+
+Note that the "1.3.6..." SNMP OID changes between switches.  The last digit
+above is the interface id (port number).  You can probably find the right OID by
+google, that was easier than figuring it out from finding the switch's MIB
+database.  You can query the POE status from the switch serial using the `show
+power inline` command.
+
+Other than that, find the dnsmasq/tftp/nfs setup for your boards "servo" above.
+
+See `src/broadcom/ci/gitlab-ci.yml` and `src/nouveau/ci/gitlab-ci.yml` for an
+examples of POE for Raspberry Pi 3/4, and Jetson Nano.
+
 Setup
 -----