README.mdwn

   1 # Libre-SOC Reproducible Build Scripts
   2
   3 This repository contains the Libre-SOC "reproducible builds" scripts.
   4 Initially begun as a way to ensure that coriolis2 VLSI ASIC layouts
   5 were reproducible, they've turned into an easy way for developers to
   6 get started.
   7
   8 All packages are installed within a baseline debian/10 debootstrapped
   9 schroot.  For reproducible builds, you have to pick an OS, and debian/10
  10 is good enough.  Note, obviously, that adding security updates would
  11 completely defeat the purpose and object of being "reproducible", so
  12 it is *strongly recommended* that you do **not** make these chrooted
  13 installs internet-facing.
  14
  15 Prerequisites:
  16
  17 * Strongly recommended that you install a Host OS of Debian.
  18 * Confirmed working but not supported: ubuntu
  19 * Also confirmed working with a caveat on X11: archlinux,
  20   (which happens to have a port of debootstrap)
  21
  22 Installs (at recent but usually specific - reproducible - versions):
  23
  24 * coriolis2
  25 * yosys
  26 * symbiyosys, z3 solver, yices, sby
  27 * ghdl
  28 * yosys-ghdl
  29 * nextpnr-ecp5
  30 * nextpnr-xilinx
  31 * symbiflow
  32 * nmigen (a Registered Trademark of M-Labs)
  33 * verilator
  34 * icarus verilog
  35 * cocotb
  36 * a ton of FPGA loader tools, dfu-util, openFPGALoader, ecpprog,
  37   fujprog, and associated udev.d rules files.
  38
  39 Note: we don't use conda.  we don't use docker.
  40
  41 # Why reproducible?
  42
  43 Imagine that you are about to drop USD 16 million on 7nm mask charges.
  44 Two - or more - engineers run the VLSI build scripts, to create the
  45 Multi-Terabyte GDS-II Files.  You have a week before the deadline: it
  46 takes 48 hours to run the VLSI build.  You find that, after 48 hours,
  47 a comparison of all the engineer's GDS-II files show differences.
  48
  49 More than a week's worth of investigation - long after the deadline
  50 has been missed to submit the Masks to the Foundry (which you paid for
  51 up-front and now cannot recover) - you discover that one developer
  52 used Ubuntu and had a PRNG library that created a different Place-and-Route
  53 sequence, another used BSD which had an older library with a bug, and yet
  54 another had installed security updates which changed memory-allocation.
  55
  56 The "perfect" reproducible build system uses absolutely identical hardware,
  57 installs on bare-metal (no Virtual Machines), does a complete and full
  58 OS wipe and automated install, and, after running, if two *Drives* are
  59 compared, they should be bit-level identical.  This is of course a little
  60 extreme (but hey, you're spending USD 16 million on 7nm masks then you're
  61 entitled to a little paranoia) so the closest we can get is:
  62
  63 * (a) pick an OS
  64 * (b) don't add updates and
  65 * (c) pin as many packages with explicit versions and git tags as possible.
  66
  67 It works. don't knock it.
  68
  69 # Installation Notes
  70
  71 During their development, each install script had notes taken which,
  72 if followed carefully, should result in the replication of the script.
  73 These notes can be found here:
  74
  75 * <https://libre-soc.org/HDL_workflow/>
  76 * <https://libre-soc.org/HDL_workflow/coriolis2/>
  77 * <https://libre-soc.org/HDL_workflow/nextpnr/>
  78 * <https://libre-soc.org/HDL_workflow/nextpnr-xilinx/>
  79 * <https://libre-soc.org/HDL_workflow/verilator/>
  80 * <https://libre-soc.org/HDL_workflow/ghdl/>
  81 * <https://libre-soc.org/HDL_workflow/iverilog/>
  82 * <https://libre-soc.org/HDL_workflow/cocotb/>
  83 * <https://libre-soc.org/HDL_workflow/symbiflow/>
  84 * <https://libre-soc.org/HDL_workflow/fpga-boot-loaders-progs/>
  85
  86 # Contact details
  87
  88 Any questions, improvements, bug-fixes or patches, most welcome:
  89 please join Libera.Chat IRC #libre-soc, or join the mailing list:
  90 <https://lists.libre-soc.org/mailman/listinfo/libre-soc-dev>
  91
  92 # Charter
  93
  94 Covered by the Libre-SOC Charter <https://libre-soc.org/charter/discussion/>
  95 we particularly welcome appropriate Dilbert Cartoons illustrating the
  96 antithetical polar opposite of the points that make up the fundamental
  97 existential existence of the Charter. y'ken.