HDL_workflow/gentoo-sffs.mdwn

   1 # Tutorial for bootstrapping Gentoo with sffs compliance from source.
   2
   3 Useful Links (External):
   4
   5 * [Read the Gentoo handbook thoroughly, it's all you need](https://wiki.gentoo.org/wiki/Handbook:PPC64)
   6
   7 Useful links (Libre-SOC):
   8
   9 * Devscripts Libre-SOC page: [[devscripts]]
  10 * [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
  11
  12 ## Video Tutorial
  13
  14 [todo](todo)
  15
  16 ## Reasoning:
  17
  18 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 stage 3 system 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).
  19
  20 You can approach this in two ways: either build the full base Gentoo stage3 packages yourself using the [handbook](https://wiki.gentoo.org/wiki/Handbook:PPC64), 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.
  21
  22 Do note that given the rolling release nature of Gentoo, it is almost impossible to get the same system with the specific package versions we have without using our tarball. If you still want to do a full rebuild but guarantee that the software versions stay the same, this guide will also explain how it can be done using our tarball.
  23
  24 ## System requirements
  25
  26 - A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
  27 - At least 80GB of hard disk space
  28
  29 Cross compiling will make this process much more complicated and is generally not recommended.
  30
  31 ## Development Setup Scripts
  32
  33 If you haven't already, clone Libre-SOC's development environment setup scripts.
  34 These are bash scripts, and greatly simplify the time it takes to create a:
  35
  36 - Stable environment
  37 - With all software and libraries at specific versions
  38 (which are known to work).
  39
  40 These attributes are absolutely critical, and no support will be
  41 provided, unless you use these scripts to setup a development environment. This
  42 helps us fix any bugs in the scripts, and make sure everyone runs on the same
  43 page.
  44
  45     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
  46
  47 Do *look through* the
  48 [code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
  49 any of those scripts.
  50 This is your own legal responsibility (to not run
  51 arbitrary code off of the internet) and we take no responsibility or accept
  52 any liability whatsoever for your use or misuse of them.
  53
  54 It is expected for you to use Debian for the host OS (anything else
  55 is unsupported: many contributors have repeatedly gotten into trouble by not
  56 following this advice), while all the chroots - which are developed
  57 very specifically for "reproducible builds" - run Debian 10 (Buster).
  58
  59 ## Setting up Gentoo from tarball (recommended method)
  60
  61 You will need to run these commands:
  62
  63     $ curl -O [link to tarball]
  64     # sudo bash
  65     # mkdir gentoo-sffs && cd gentoo-sffs
  66     # tar xpvf gentoo-sffs.tar.xz --xattrs-include='*.*' --numeric-owner
  67     # cd ..
  68     # chroot gentoo-sffs
  69
  70 # (Optional) Rebuilding Gentoo from source without upgrading
  71
  72 We conveniently keep the sources of all the packages on the system in the tarball as well, in case they become unavailable online at any point in time.
  73
  74     # chroot gentoo-sffs
  75     # source /etc/profile
  76     # emerge -e --ask --keep-going @world
  77
  78 # (Optional) Building an updated Gentoo SFFS
  79
  80 This is highly not recommended unless you specifically want to explore how newer versions of software will behave when built with the SFFS flags.
  81
  82 One way of doing this is to just set up Gentoo SFFS from the provided tarball and then upgrade everything, that is much simpler and easier to roll-back if need be.
  83
  84 After having a working chroot using our tarball as outlined earlier, run these commands in the chroot:
  85
  86     # emerge-webrsync
  87     # emerge --ask --verbose --update --deep --newuse @world
  88
  89 The other way is to create a new Gentoo chroot or virtual machine under POWER using the [handbook](https://wiki.gentoo.org/wiki/Handbook:PPC64), and once you reach the [stage3 tarball](https://wiki.gentoo.org/wiki/Handbook:PPC64/Installation/Stage#Unpacking_the_stage_tarball) step, download our [make.conf](link) and copy it to
  90  `/etc/portage/make.conf`, replacing the provided one, and run:
  91
  92     # emerge -e --ask --keep-going @world
  93     # emerge-webrsync
  94     # emerge --ask --verbose --update --deep --newuse @world
  95
  96 To first rebuild Gentoo for SFFS, and then update the repositories, and finally to upgrade the software you have.
  97
  98 ## Notes and issues
  99
 100 * Gentoo's base system packages will not complain when building for SFFS (as of July 2023, can change depending on updates)
 101 * 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.
 102 * 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.
 103 * glibc *may* have some issues on sffs, the only way to test this is to run on microwatt which will be done soon.