SFFS/debian_bootstrap.mdwn

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