README.md

   1 # Utilities for Jacob Lifshay's build server for Libre-SOC
   2
   3 ## Programming the FPGA from your `.gitlab-ci.yml` file
   4
   5 Add the gitlab-build-utils branch of utils.git to your repo:
   6
   7 ```
   8 git submodule add -b gitlab-build-utils https://git.libre-soc.org/git/utils.git gitlab-build-utils
   9 ```
  10
  11 Add the environment variable override to the `build` `before_script` section of your `.gitlab-ci.yml` file:
  12
  13 ```yaml
  14 build:
  15     stage: build
  16     before_script:
  17         - export XC3SPROG="$PWD/gitlab-build-utils/program-fpga.py"
  18 ```
  19
  20 Use the `ArtyA7_100Platform` from `nmigen_boards`:
  21
  22 ```python
  23 from nmigen_boards.arty_a7 import ArtyA7_100Platform
  24 from nmigen_boards.test.blinky import Blinky
  25
  26 platform = ArtyA7_100Platform(toolchain="yosys_nextpnr")
  27 platform.build(Blinky(), do_program=True)
  28 ```
  29
  30 ## Setting up the build server
  31
  32 Switch to the root user:
  33 ```sh
  34 sudo -H -u root bash
  35 ```
  36
  37 Install `xc3sprog`:
  38 ```sh
  39 apt update
  40 apt install xc3sprog
  41 ```
  42
  43 Clone https://git.libre-soc.org/git/utils.git and checkout the
  44 gitlab-build-utils branch:
  45 ```sh
  46 git clone -b gitlab-build-utils https://git.libre-soc.org/git/utils.git gitlab-build-utils
  47 ```
  48
  49 Install `program-fpga.py`:
  50 ```sh
  51 cd gitlab-build-utils
  52 install program-fpga.py /usr/local/bin/
  53 ```
  54
  55 Install the systemd service:
  56 ```sh
  57 systemctl enable `realpath program-fpga.socket program-fpga.service`
  58 ```
  59
  60 Start the systemd socket (only needed right after installation,
  61 it should start automatically on next reboot):
  62 ```sh
  63 systemctl start program-fpga.socket
  64 ```
  65
  66 Add it to the `runners.runners.docker.volumes` key in `gitlab-runner`'s
  67 config file `/etc/gitlab-runner/config.toml`:
  68 ```toml
  69 [[runners]]
  70   ...
  71   [runners.docker]
  72     ...
  73     volumes = ["/cache", "/run/program-fpga.sock:/arty-prog-socket"]
  74 ```
  75
  76 Press Ctrl+D to exit the root shell.
  77
  78 Test it locally:
  79 ```sh
  80 touch empty.bit
  81 ARTY_PROG_SOCKET=/run/program-fpga.sock program-fpga.py -c nexys4 empty.bit
  82 ```
  83
  84 It should output something like this (error because an empty file isn't
  85 something it can program to the fpga):
  86 ```
  87 xc3sprog -c nexys4 last.bit
  88 XC3SPROG (c) 2004-2011 xc3sprog project $Rev$ OS: Linux
  89 Free software: If you contribute nothing, expect nothing!
  90 Feedback on success/failure/enhancement requests:
  91         http://sourceforge.net/mail/?group_id=170565
  92 Check Sourceforge for updates:
  93         http://sourceforge.net/projects/xc3sprog/develop
  94
  95 Using Libftdi,
  96 Unknown error
  97 ```
  98
  99 Test it through gitlab-ci:
 100 Go to https://salsa.debian.org/Kazan-team/mirrors/utils/-/tree/gitlab-build-utils
 101
 102 Go to the latest commit, click on the link to the pipeline, click on the retry button on the build button, it looks like:
 103
 104 ![gitlab-rerun-job.png](gitlab-rerun-job.png)
 105
 106 Wait until the job completes, it should be successful, with the last few lines being where the fpga is programmed:
 107
 108 ```
 109 ...
 110 xc3sprog -c nexys4 last.bit
 111 XC3SPROG (c) 2004-2011 xc3sprog project $Rev$ OS: Linux
 112 Free software: If you contribute nothing, expect nothing!
 113 Feedback on success/failure/enhancement requests:
 114         http://sourceforge.net/mail/?group_id=170565
 115 Check Sourceforge for updates:
 116         http://sourceforge.net/projects/xc3sprog/develop
 117 Using Libftdi,
 118 Saving cache for successful job
 119 ...
 120 ```