SFFS/debian_bootstrap.mdwn

   1 # Tutorial for bootstrapping Debian Bookworm (12) from source.
   2
   3 **This project is part of [NLnet NGI0 Entrust](https://nlnet.nl/entrust)
   4 and has received funding from the European Union’s Horizon Europe research and innovation programme under grant agreement No 101069594.**
   5
   6 Useful Links:
   7
   8 * [Read about sbuild and understand how it works](https://wiki.debian.org/sbuild)
   9 * [dpkg-buildflags man page](https://manpages.debian.org/bookworm/dpkg-dev/dpkg-buildflags.1.en.html) (optional, in case some flags need to be changed)
  10 * [apt-ftparchive man page](https://manpages.debian.org/bookworm/apt-utils/apt-ftparchive.1.en.html) (optional, in case you want to customize the repo)
  11 * [debootstrap wiki page](https://wiki.debian.org/Debootstrap) (optional,
  12 in case you want to customize your chroot)
  13 * please note this tarball contains executable binaries and it is 100% your responsibility to check them or take appropriate measures. we take no responsibility and accept no liability <https://ftp.libre-soc.org/sffs/debian-12-sffs.2023sep01.tar.xz>. downloading this file constitutes your agreement to these terms.
  14
  15 Useful links (Libre-SOC):
  16
  17 * bugreport <https://bugs.libre-soc.org/show_bug.cgi?id=1130>
  18 * Devscripts Libre-SOC page: [[HDL_workflow/devscripts]]
  19 * [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
  20
  21 ## Video Tutorial
  22
  23 [todo](todo)
  24
  25 ## Reasoning:
  26
  27 Libre-SOC builds upon the OpenPOWER ISA v3.0 but does not include
  28 many parts of the architecture typically found on production
  29 silicon, like AltiVec, VSX, and 128-bit hardware floating
  30 point. Because of this, we need (at this time, might change
  31 in the future when glibc supports detecting VSX vs SVP64 etc)
  32 to rebuild the full software repository to not include any of
  33 those instructions, making it compliant with [sffs (slides 5 &
  34 6)](https://ics2020.bsc.es/sites/default/files/uploaded/brian_thompto_ICS2020_SLIDES.pdf).
  35
  36 You can approach this in two ways: either build the full base Debian
  37 chroot packages yourself using Debian's build tools, optionally automated
  38 with our [scripts](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree),
  39 or use the [prebuilt rootfs for which you accept full liability and responsibility](https://ftp.libre-soc.org/sffs/debian-12-sffs.2023sep01.tar.xz) in a compressed tar archive.
  40
  41 ## System requirements
  42
  43 - A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
  44 - At least 80GB of hard disk space
  45
  46 Cross compiling will make this process much more complicated and is
  47 generally not recommended.
  48
  49 ## Development Setup Scripts
  50
  51 If you haven't already, clone Libre-SOC's development environment setup
  52 scripts.  These are bash scripts, and greatly simplify the time it takes
  53 to create a:
  54
  55 - Stable environment
  56 - With all software and libraries at specific versions
  57 (which are known to work).
  58
  59 These attributes are absolutely critical, and no support will be provided,
  60 unless you use these scripts to setup a development environment. This
  61 helps us fix any bugs in the scripts, and make sure everyone runs on
  62 the same page.
  63
  64     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
  65
  66 Do *look through* the
  67 [code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
  68 any of those scripts.
  69 This is your own legal responsibility (to not run
  70 arbitrary code off of the internet) and we take no responsibility or accept
  71 any liability whatsoever for your use or misuse of them.
  72
  73 It is expected for you to use Debian for the host OS (anything else is
  74 unsupported: many contributors have repeatedly gotten into trouble by
  75 not following this advice), while all the chroots - which are developed
  76 very specifically for "reproducible builds" - run Debian 10 (Buster).
  77
  78 ## Setting up the build schroot
  79
  80 Scripts we will be using for the setup are:
  81
  82 * `install-sbuild-apt-reqs` for installing sbuild and configuring it to
  83    Debian's defaults
  84 * `mk-schroot-bookworm` for creating the bookworm schroot used by sbuild
  85    and adding our dpkg-buildflags to build for sffs
  86 * `build-glibc-debian` to build glibc, currently has to be standalone because of [this](https://bugs.libre-soc.org/show_bug.cgi?id=1130#c8)
  87 * `add-sffs-flags-debian` to add the SFFS CFLAGS
  88 * `build-bookworm-sffs` to build the packages needed for a debootstrap
  89    chroot directory
  90 * `create-deb-repo` to create a local dpkg repository of the built packages
  91 * `mk-sffs-chroot` to finally create the chroot using the repository of
  92    built packages
  93
  94 Commands to run in terminal to rebuild Debian 12 with sffs compliance:
  95
  96     $ cd dev-env-setup
  97     $ sudo bash
  98     # ./install-sbuild-apt-reqs
  99     # ./mk-schroot-bookworm
 100     # exit
 101     $ ./build-glibc-debian
 102     $ sudo bash
 103     # ./add-sffs-flags-debian
 104     # exit
 105     $ ./build-bookworm-sffs
 106     $ ./create-deb-repo
 107     $ ./mk-sffs-chroot
 108
 109 ## Using prebuilt tarball
 110
 111 If you prefer to use the prebuilt tarball (which will save days of your
 112 time), you could simply download and extract the tarball to a convenient
 113 location and chroot into it. Bear in mind though that it is entirely your
 114 responsibility when downloading arbitrary binaries, and we accept no
 115 liability whatsoever for anything arising by you downloading them.
 116
 117     $ curl -O https://ftp.libre-soc.org/sffs/debian-12-sffs.2023sep01.tar.xz
 118     $ mkdir bookworm-sffs && cd bookworm-sffs
 119     $ tar xpvf bookworm-sffs.tar.xz --xattrs-include='*.*' --numeric-owner
 120     $ cd ..
 121     $ sudo chroot bookworm-sffs
 122
 123 # Testing for VSX in object files
 124
 125 To verify that our buildflags were applied by the build tools and
 126 respected by the build scripts of packages, we need to check for the
 127 inclusion of VSX as well as any other instructions not available in SFFS.
 128
 129 This is not a perfect solution and the proper way would be either to:
 130
 131 - Simulate an SFFS compliant chip running this code such as
 132   [Microwatt](https://libre-soc.org/HDL_workflow/microwatt/)
 133     (very time consuming)
 134 - Use a softcore FPGA core or ASIC of Microwatt /
 135   LibreSOC to run this code (doable, FPGA softcore
 136   [in progress](https://bugs.libre-soc.org/show_bug.cgi?id=1037))
 137 - Use the finalized Libre-SOC chip (doable once it is ready)
 138
 139 Also note that this only tests for a subset of VSX instructions at the
 140 moment, more will be added in the future, this is simply a quick test to
 141 run before attempting to run on simulation and/or a softcore as both can
 142 be somewhat time consuming. In other words, if this test gives any VSX
 143 instructions, don't attempt to run the code in simulation or a softcore
 144 to avoid wasting precious time.
 145
 146 To attempt this test, you will need the scripts from our `dev-env-setup`
 147 repository
 148
 149     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
 150
 151 Again, previous notes about running the scripts apply here, do make sure
 152 to read whatever you run, they are short and human-readable.
 153
 154 Edit the `test-vsx` script to point the `CHROOT` variable to your
 155 respective chroot of Debian, read through the script thoroughly, and run
 156
 157     $ ./test-vsx
 158
 159 If you see any number of instructions in certain binary files, those
 160 files do contain VSX and work needs to be done (patching the build
 161 scripts and/or source code) for these packages. If not, great! Try to
 162 run this in a proper SFFS environment to fully test the code you have.
 163
 164 You can also test specific binaries at any time by running this part of
 165 the script
 166
 167     $ objdump -d $OBJ_FILE | fgrep -of VSX_INSNS.txt | sort | uniq -c \
 168       | awk '{print $2 " " $1}'
 169
 170 Where `$OBJ_FILE` is the binary you need to check.
 171
 172 ## Notes and issues
 173
 174 * Some packages will refuse to build with sffs compliant build flags
 175   and need workarounds, this will be handled in the future.
 176 * The Linux kernel cannot boot without AltiVec and VSX, even though they
 177   are build-time options. The solution for now is to use [microwatt's 5.7
 178   kernel](https://lore.kernel.org/all/CAPweEDw710zFK8KLZY5gsQxEkQKrDiFkNRgABY9HJZ1rxpeVCg@mail.gmail.com/T/)
 179   and to incorporate the needed patches upstream in the future.
 180 * Previous note also means this is purely a chroot environment, this page
 181   will be updated once it becomes possible to boot a full VM of this build.
 182 * glibc *may* have some issues on sffs, the only way to test this is to
 183   run on microwatt  which will be done soon.
 184