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