* bugreport: <https://bugs.libre-soc.org/show_bug.cgi?id=1131>
* (External) [Read the Gentoo handbook thoroughly, it's all you need](https://wiki.gentoo.org/wiki/Handbook:PPC64)
-* 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>
+* 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>
* 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/>
- more recent snapshot: all stage3-ppc64le-openrc-20230823T030134Z.tar.xz* files:
+ more recent snapshot: all stage3-ppc64le-openrc-20230823T030134Z.tar.xz
+ files:
<https://web.archive.org/web/20230823160828/https://distfiles.gentoo.org/releases/ppc/autobuilds/20230823T030134Z/>
## Video Tutorial
## Reasoning:
-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).
+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).
-To do this, you need to rebuild Gentoo from a known working stage3 archive, which we will guide you through.
+To do this, you need to rebuild Gentoo from a known working stage3
+archive, which we will guide you through.
-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.
+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.
## System requirements
- A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
- At least 80GB of hard disk space
-Cross compiling will make this process much more complicated and is generally not recommended.
+Cross compiling will make this process much more complicated and is
+generally not recommended.
-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)
+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)
## Setting up Gentoo from stage3 and rebuilding (recommended method)
# sudo bash
# mkdir gentoo-sffs && cd gentoo-sffs
- # tar xpvf ../stage3-ppc64le-openrc-20230720T024654Z.tar.xz --xattrs-include='*.*' --numeric-owner
+ # tar xpvf ../stage3-ppc64le-openrc-20230720T024654Z.tar.xz \
+ --xattrs-include='*.*' --numeric-owner
# cd ..
Follow these steps from the Gentoo handbook:
* [Enter the chroot environment](https://wiki.gentoo.org/wiki/Handbook:PPC64/Installation/Base#Entering_the_new_environment)
-After which you need to add our build flags replacing the default ones in `/etc/portage/make.conf`
+After which you need to add our build flags replacing the default ones in
+`/etc/portage/make.conf`
-`COMMON_FLAGS="-O2 -pipe -mcpu=power9 -mno-altivec -mno-vsx -mno-crypto -mno-htm -mlong-double-64"`
+ `COMMON_FLAGS="-O2 -pipe -mcpu=power9 -mno-altivec -mno-vsx -mno-crypto -mno-htm -mlong-double-64"`
-`CPU_FLAGS_PPC=""`
+ `CPU_FLAGS_PPC=""`
Finally, rebuild everything on the system:
# (Optional) Building an updated Gentoo SFFS
-This is highly not recommended unless you specifically want to explore how newer versions of software will behave when built with the SFFS flags.
+This is highly not recommended unless you specifically want to explore
+how newer versions of software will behave when built with the SFFS flags.
-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.
+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.
-After having a working chroot using the stage3 as outlined earlier, run these commands in the chroot:
+After having a working chroot using the stage3 as outlined earlier,
+run these commands in the chroot:
# emerge-webrsync
# emerge --ask --verbose --update --deep --newuse @world
-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
+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
`/etc/portage/make.conf`, replacing the provided one, and run:
# emerge -e --ask --keep-going @world
# emerge-webrsync
# emerge --ask --verbose --update --deep --newuse @world
-To first rebuild Gentoo for SFFS, and then update the repositories, and finally to upgrade the software you have.
+To first rebuild Gentoo for SFFS, and then update the repositories,
+and finally to upgrade the software you have.
# Testing for VSX in object files
-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.
+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.
This is not a perfect solution and the proper way would be either to:
-- Simulate an SFFS compliant chip running this code such as [Microwatt](https://libre-soc.org/HDL_workflow/microwatt/) (very time consuming)
-- Use a softcore FPGA core or ASIC of Microwatt / LibreSOC to run this code (doable, FPGA softcore in progress [in progress](https://bugs.libre-soc.org/show_bug.cgi?id=1037))
+- Simulate an SFFS compliant chip running this code such as
+ [Microwatt](https://libre-soc.org/HDL_workflow/microwatt/)
+ (very time consuming)
+- Use a softcore FPGA core or ASIC of Microwatt / LibreSOC
+ to run this code (doable, FPGA softcore in progress
+ [in progress](https://bugs.libre-soc.org/show_bug.cgi?id=1037))
- Use the finalized Libre-SOC chip (doable once it is ready)
-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.
+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.
-To attempt this test, you will need the scripts from our `dev-env-setup` repository
-
-$ git clone https://git.libre-soc.org/git/dev-env-setup.git
+To attempt this test, you will need the scripts from our `dev-env-setup`
+repository
+ $ git clone https://git.libre-soc.org/git/dev-env-setup.git
Do *look through* the
[code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
any of those scripts.
-This is your own legal responsibility (to not run
-arbitrary code off of the internet) and we take no responsibility or accept
-any liability whatsoever for your use or misuse of them.
+This is your own legal responsibility (to not run arbitrary code off
+of the internet) and we take no responsibility or accept any liability
+whatsoever for your use or misuse of them.
-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
+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).
-Edit the `test-vsx` script to point the `CHROOT` variable to your respective chroot of Gentoo, read through the script thoroughly, and run
+Edit the `test-vsx` script to point the `CHROOT` variable to your
+respective chroot of Gentoo, read through the script thoroughly, and run
-$ ./test-vsx
+ $ ./test-vsx
-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.
+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.
-You can also test specific binaries at any time by running this part of the script
+You can also test specific binaries at any time by running this part of
+the script
-$ objdump -d $OBJ_FILE | fgrep -of VSX_INSNS.txt | sort | uniq -c | awk '{print $2 " " $1}'
+ $ objdump -d $OBJ_FILE | fgrep -of VSX_INSNS.txt | sort | uniq -c \
+ | awk '{print $2 " " $1}'
-Where $OBJ_FILE is the binary you need to check.
+Where `$OBJ_FILE` is the binary you need to check.
## Notes and issues
-* Gentoo's base system packages will not complain when building for SFFS (as of July 2023, can change depending on updates)
-* 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.
-* 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.
-* glibc *may* have some issues on sffs, the only way to test this is to run on microwatt which will be done soon.
+* Gentoo's base system packages will not complain when building for SFFS
+ (as of July 2023, can change depending on updates)
+* 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.
+* 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.
+* glibc *may* have some issues on sffs, the only way to test this is to
+ run on microwatt which will be done soon.
+
projects / libreriscv.git / commitdiff