SFFS/gentoo_bootstrap.mdwn

   1 # Tutorial for bootstrapping Gentoo with sffs compliance from source.
   2
   3 Useful Links:
   4
   5 * bugreport: <https://bugs.libre-soc.org/show_bug.cgi?id=1131>
   6 * (External) [Read the Gentoo handbook thoroughly, it's all you need](https://wiki.gentoo.org/wiki/Handbook:PPC64)
   7 * 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/stage3-ppc64le-openrc-20230720T024654Z.tar.xz>
   8 * TODO investigate: a mirror of stage3 snapshots is available at archive.org <https://web.archive.org/web/20221218010734/https://distfiles.gentoo.org/releases/ppc/autobuilds/20221217T033210Z/>
   9
  10 ## Video Tutorial
  11
  12 [todo](todo)
  13
  14 ## Reasoning:
  15
  16 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).
  17
  18 To do this, you need to rebuild Gentoo from a known working stage3 archive, which we will guide you through.
  19
  20 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 the same stage3 version we used.
  21
  22 ## System requirements
  23
  24 - A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
  25 - At least 80GB of hard disk space
  26
  27 Cross compiling will make this process much more complicated and is generally not recommended.
  28
  29 It is expected for you to use Debian for the host OS (anything else
  30 is unsupported: many contributors have repeatedly gotten into trouble by not following this advice)
  31
  32 ## Setting up Gentoo from stage3 and rebuilding (recommended method)
  33
  34 You will need to run these commands:
  35
  36     $ curl -O https://ftp.libre-soc.org/sffs/stage3-ppc64le-openrc-20230720T024654Z.tar.xz
  37     $ sha256sum stage3-ppc64le-openrc-20230720T024654Z.tar.xz
  38
  39 The SHA256 checksum should be
  40
  41 `2c97446d09f2790ee6cc3e4cbff0d204f6f0914083fc36998d0b08fcb28f8e90`
  42
  43     # sudo bash
  44     # mkdir gentoo-sffs && cd gentoo-sffs
  45     # tar xpvf ../stage3-ppc64le-openrc-20230720T024654Z.tar.xz --xattrs-include='*.*' --numeric-owner
  46     # cd ..
  47
  48 Follow these steps from the Gentoo handbook:
  49
  50 * [Copy DNS info](https://wiki.gentoo.org/wiki/Handbook:PPC64/Installation/Base#Copy_DNS_info)
  51
  52 * [Mount necessary filesystems](https://wiki.gentoo.org/wiki/Handbook:PPC64/Installation/Base#Mounting_the_necessary_filesystems)
  53
  54 * [Enter the chroot environment](https://wiki.gentoo.org/wiki/Handbook:PPC64/Installation/Base#Entering_the_new_environment)
  55
  56 After which you need to add our build flags replacing the default ones in `/etc/portage/make.conf`
  57
  58 `COMMON_FLAGS="-O2 -pipe -mcpu=power9 -mno-altivec -mno-vsx -mno-crypto -mno-htm -mlong-double-64"`
  59
  60 `CPU_FLAGS_PPC=""`
  61
  62 Finally, rebuild everything on the system:
  63
  64     # emerge -e --ask --keep-going @world
  65
  66 # (Optional) Building an updated Gentoo SFFS
  67
  68 This is highly not recommended unless you specifically want to explore how newer versions of software will behave when built with the SFFS flags.
  69
  70 One way of doing this is to just set up Gentoo SFFS from the provided stage3, add out `make.conf` options and then upgrade everything, that is much simpler and easier to roll-back if need be.
  71
  72 After having a working chroot using the stage3 as outlined earlier, run these commands in the chroot:
  73
  74     # emerge-webrsync
  75     # emerge --ask --verbose --update --deep --newuse @world
  76
  77 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
  78  `/etc/portage/make.conf`, replacing the provided one, and run:
  79
  80     # emerge -e --ask --keep-going @world
  81     # emerge-webrsync
  82     # emerge --ask --verbose --update --deep --newuse @world
  83
  84 To first rebuild Gentoo for SFFS, and then update the repositories, and finally to upgrade the software you have.
  85
  86 ## Notes and issues
  87
  88 * Gentoo's base system packages will not complain when building for SFFS (as of July 2023, can change depending on updates)
  89 * 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.
  90 * 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.
  91 * glibc *may* have some issues on sffs, the only way to test this is to run on microwatt which will be done soon.