add readme

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..c219e16
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+# Utilities for Jacob Lifshay's build server for Libre-SOC
+
+## Programming the FPGA from your `.gitlab-ci.yml` file
+
+Add the gitlab-build-utils branch of utils.git to your repo:
+
+```
+git submodule add -b gitlab-build-utils https://git.libre-soc.org/git/utils.git gitlab-build-utils
+```
+
+Add the environment variable override to the `build` `before_script` section of your `.gitlab-ci.yml` file:
+
+```yaml
+build:
+    stage: build
+    before_script:
+        - export XC3SPROG="$PWD/gitlab-build-utils/program-fpga.py"
+```
+
+Use the `ArtyA7_100Platform` from `nmigen_boards`:
+
+```python
+from nmigen_boards.arty_a7 import ArtyA7_100Platform
+from nmigen_boards.test.blinky import Blinky
+
+platform = ArtyA7_100Platform(toolchain="yosys_nextpnr")
+platform.build(Blinky(), do_program=True)
+```
+
+## Setting up the build server
+
+Switch to the root user:
+```sh
+sudo -H -u root bash
+```
+
+Install `xc3sprog`:
+```sh
+apt update
+apt install xc3sprog
+```
+
+Clone https://git.libre-soc.org/git/utils.git and checkout the
+gitlab-build-utils branch:
+```sh
+git clone -b gitlab-build-utils https://git.libre-soc.org/git/utils.git gitlab-build-utils
+```
+
+Install `program-fpga.py`:
+```sh
+cd gitlab-build-utils
+install program-fpga.py /usr/local/bin/
+```
+
+Install the systemd service:
+```sh
+systemctl enable `realpath program-fpga.socket program-fpga.service`
+```
+
+Start the systemd socket (only needed right after installation,
+it should start automatically on next reboot):
+```sh
+systemctl start program-fpga.socket
+```
+
+Add it to the `runners.runners.docker.volumes` key in `gitlab-runner`'s
+config file `/etc/gitlab-runner/config.toml`:
+```toml
+[[runners]]
+  ...
+  [runners.docker]
+    ...
+    volumes = ["/cache", "/run/program-fpga.sock:/arty-prog-socket"]
+```
+
+Press Ctrl+D to exit the root shell.
+
+Test it locally:
+```sh
+touch empty.bit
+ARTY_PROG_SOCKET=/run/program-fpga.sock program-fpga.py -c nexys4 empty.bit
+```
+
+It should output something like this (error because an empty file isn't
+something it can program to the fpga):
+```
+xc3sprog -c nexys4 last.bit
+XC3SPROG (c) 2004-2011 xc3sprog project $Rev$ OS: Linux
+Free software: If you contribute nothing, expect nothing!
+Feedback on success/failure/enhancement requests:
+        http://sourceforge.net/mail/?group_id=170565 
+Check Sourceforge for updates:
+        http://sourceforge.net/projects/xc3sprog/develop
+
+Using Libftdi, 
+Unknown error
+```
+
+Test it through gitlab-ci:
+Go to https://salsa.debian.org/Kazan-team/mirrors/utils/-/tree/gitlab-build-utils
+
+Go to the latest commit, click on the link to the pipeline, click on the retry button on the build button, it looks like:
+
+![gitlab-rerun-job.png](gitlab-rerun-job.png)
+
+Wait until the job completes, it should be successful, with the last few lines being where the fpga is programmed:
+
+```
+...
+xc3sprog -c nexys4 last.bit
+XC3SPROG (c) 2004-2011 xc3sprog project $Rev$ OS: Linux
+Free software: If you contribute nothing, expect nothing!
+Feedback on success/failure/enhancement requests:
+       http://sourceforge.net/mail/?group_id=170565 
+Check Sourceforge for updates:
+       http://sourceforge.net/projects/xc3sprog/develop
+Using Libftdi, 
+Saving cache for successful job
+...
+```
\ No newline at end of file

diff --git a/gitlab-rerun-job.png b/gitlab-rerun-job.png
new file mode 100644 (file)
index 0000000..755f260
Binary files /dev/null and b/gitlab-rerun-job.png differ