libre: linux-libre-64: Add rationale for the package

While the package is well documented for potential users (the pkgdesc
field is clear enough), it has almost zero documentation for potential
contributors, and the fact that pkgdesc is generated doesn't help
making it use clear.

This adds some documentation to help maintenance, and also documents
some use cases, as a potential user can easily understand why to use
or not use such kernel, but this can be less clear to contributors
wanting to modify/remove/replace the package in ways that could break
these use cases.

Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org>

1 files changed, 50 insertions, 0 deletions

diff --git a/libre/linux-libre-64/PKGBUILD b/libre/linux-libre-64/PKGBUILD
index 689197916..f93d67f01 100644
--- a/libre/linux-libre-64/PKGBUILD
+++ b/libre/linux-libre-64/PKGBUILD
@@ -1,5 +1,55 @@
 # Maintainers: Parabola hackers <dev@lists.parabola.nu>
 
+# Rationale: This package enables to run 64bit kernels with 32bit rootfs.
+#
+# For armv7k/aarch64, we have no aarch64 port yet, and the 32bit
+# kernels don't work for 64bit computers (for instance the dtb for
+# 64bit computers are not shipped).
+#
+# In turn if we can boot Parabola on these computers, it enables
+# people to work on an aarch64 port more easily as chrooting in 64bit
+# rootfs from 32bit rootfs work when we have a 64bit kernel (tested on
+# an x86_64 computer with a Parabola i686 rootfs and a Parabola x86_64
+# chroot).
+#
+# This enable to make rootfs that work on both 64bit and 32bit
+# computers. In that case the user will still need to select the right
+# kernel at boot.
+#
+# Generally speaking it also enable users to benefit from many of the
+# improvements of 64bit kernels (ability to chroot in 64bit rootfs,
+# better security, 4GiB address space per process instead of 3GiB for
+# 32bit rootfs, etc) without having to reinstall everything. In
+# addition, there was and is still no conversion guide to convert a
+# 32bit Parabola installation to 64bit), and in some cases (lot of
+# self-built software in /usr/local, PostgreSQL database, etc) the
+# migration to 64bit requires some work.
+#
+# As for using i686 for new installation on x86_64 computers, it can
+# enable people doing that to find and fix bugs on Parabola i686 to
+# enable people with 32bit-only computers (like Libreboot compatible
+# I945 Thinkpads) to still be able to use Parabola.
+#
+# Having both architectures (arm and x86) in the same PKGBUILD enables
+# to more widely test this package (if we find issues on x86, they'll
+# most likely apply to arm as well). Though it can become a problem if
+# we need different kernel versions for both architectures.
+#
+# Status:
+# - Tested on both arm and x86.
+# - The build is currently broken on ARM due to a missing cross
+#   compiler for armv7h (it was accidentally removed and it doesn't
+#   build anymore).
+# - External modules (like Wireguard or tp_smapi) also need to be
+#   cross compiled. So modules for linux-libre-64 need to be added
+#   (like tp_smapi-64) and dkms packages need to be adapted to also
+#   work for this kernel.
+# - Some software (like building Guix) break with 32bit rootfs and
+#   64bit kernels due to wrong assumption about the number of bits,
+#   through other software (like building rust with mrustc) work
+#   better (here because we have 3GiB instead of 3GiB of memory per
+#   process). Most software is not affected though.
+
 # Based on the linux-libre package
 
 _replacesarchkernel=('linux%') # '%' gets replaced with kernel suffix