how to update gcc

README.adoc

@@ -13508,9 +13508,95 @@ Here are some good working commands for several ISAs:
 
 These can come in handy if you want to debug something in Buildroot itself and possibly report an upstream bug.
 
+=== Update the toolchain
+
+Users of this repo will often want to update the compilation toolchain to the latest version to get fresh new features like new ISA instructions.
+
+Because the toolchain is so complex and tightly knitted with the rest of the system, this is more of an art than a science.
+
+However, it is not something to be feared, and you will get there without help in most cases.
+
+In this section we cover the most common cases.
+
+==== Update GCC: GCC supported by Buildroot
+
+This is of course the simplest case.
+
+You can quickly determine all the GCC versions supported by Buildroot by looking at:
+
+....
+submodules/buildroot/package/gcc/Config.in.host
+....
+
+For example, in Buildroot 2018.08, which was used at LKMC 5cdbd57de09b64f48d06351b065dc8949493d7e8, the default toolchain was 7.3.0, and the latest supported one was 8.2.0.
+
+So, if we just wanted to upgrade the toolchain to 8.2.0, and rebuild some userland executables to later run them, we could do:
+
+....
+cd submodules/gcc
+git fetch up
+git checkout -b lkmc-gcc-8_2_0-release gcc-8_2_0-release
+git am ../buildroot/package/gcc/8.2.0/*
+cd ../..
+./build-buildroot \
+  --arch aarch64 \
+  --buildroot-build-id gcc-8-2 \
+  --config 'BR2_GCC_VERSION_8_X=y' \
+  --config 'BR2_GCC_VERSION="8.2.0"' \
+  --no-all \
+  -- \
+  toolchain \
+;
+./build-userland \
+  --arch aarch64 \
+  --buildroot-build-id gcc-8-2 \
+  --out-rootfs-overlay-dir-prefix gcc-8-2 \
+  --userland-build-id gcc-8-2 \
+;
+./build-buildroot --arch aarch64
+....
+
+where the `toolchain` Buildroot target builds only Buildroot: https://stackoverflow.com/questions/44521150/buildroot-install-and-build-the-toolchain-only
+
+Note that this setup did not overwrite any of our default Buildroot due to careful namespacing with our `gcc-8-2` prefix!
+
+Now you can either run the executables on <<user-mode-simulation>> with:
+
+....
+./run --arch aarch64 --userland userland/c/hello.c --userland-build-id gcc-8-2
+....
+
+or in full system with:
+
+....
+./run --arch aarch64 --eval-after './gcc-8-2/c/hello.out'
+....
+
+where the `gcc-8-2` prefix was added by `--out-rootfs-overlay-dir-prefix`.
+
+==== Update GCC: GCC not supported by Buildroot
+
+Now it gets fun, but well, guess what, we will try to do the same as xref:update-gcc-gcc-supported-by-buildroot[xrefstyle=full] but:
+
+* pick the Buildroot version that comes closest to the GCC you want
+* if any `git am` patches don't apply, skip them
+
+Now, if things fail, you can try:
+
+* if the GCC version is supported by a newer Buildroot version:
+** quick and dirty: see what they are doing differently there, and patch it in here
+** golden star: upgrade our default Buildroot, <<test-this-repo,test it well>>, and send a pull request!
+* otherwise: OK, go and patch Buildroot, time to become a Buildroot dev
+
+Known setups:
+
+* Buildroot 2018.08:
+** GCC 8.3.0: OK
+** GCC 9.2.0: KO https://github.com/cirosantilli/linux-kernel-module-cheat/issues/97
+
 == Userland content
 
-This section contains userland content, such as <<c>>, <<cpp>> and <<posix>> examples.
+This section documents our test and educational userland content, such as <<c>>, <<cpp>> and <<posix>> examples, present mostly under link:userland/[].
 
 Getting started at: xref:userland-setup[xrefstyle=full]
 
@@ -18874,7 +18960,7 @@ Also we don't have a choice in the case of C++ template, which must stay in head
 
 ==== buildroot_packages directory
 
-Source: link:buildroot_packages/[]
+Source: link:buildroot_packages/[].
 
 Every directory inside it is a Buildroot package.
 
@@ -18966,6 +19052,8 @@ These are typically patches that don't contain fundamental functionality, so we
 
 ==== rootfs_overlay
 
+Source: link:rootfs_overlay[].
+
 We use this directory for:
 
 * customized configuration files
@@ -18992,6 +19080,25 @@ ls /mnt/9p/rootfs_overlay
 
 This way you can just hack away the scripts and try them out immediately without any further operations.
 
+===== out_rootfs_overlay_dir
+
+This path can be found with:
+
+....
+./getvar out_rootfs_overlay_dir
+....
+
+This output directory contains all the files that LKMC will put inside the final image, including for example:
+
+* <<userland-content>> that needs to be compiled
+* <<rootfs_overlay>> content that gets put inside the image as is
+
+LKMC first collects all the files that it will dump into the guest there, and then in the very last step dumps everything into the final image.
+
+In Buildroot, this is done by pointing `BR2_ROOTFS_OVERLAY` to that directory.
+
+This does not include native image modification mechanisms such as <<buildroot_packages-directory,Buildroot packages>>, which we let Buildroot itself manage.
+
 ==== lkmc.c
 
 The files: