From: sadoon <sadoon@web>
Date: Fri, 25 Aug 2023 11:29:12 +0000 (+0100)
Subject: Added VSX testing of binaries
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=a80ddd9631eda3ff161ed23496ce56cb8491ceff;p=libreriscv.git

Added VSX testing of binaries
---

diff --git a/SFFS/gentoo_bootstrap.mdwn b/SFFS/gentoo_bootstrap.mdwn
index 31f5f4f8c..1fd890097 100644
--- a/SFFS/gentoo_bootstrap.mdwn
+++ b/SFFS/gentoo_bootstrap.mdwn
@@ -86,6 +86,47 @@ The other way is to create a new Gentoo chroot or virtual machine under POWER us
 
 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.
+
+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 [link to bug](link))
+- 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.
+
+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.
+
+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
+
+$ ./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.
+
+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}'
+
+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)