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