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:

build-userland

@@ -23,6 +23,17 @@ Build our compiled userland examples.
         self._add_argument('--ccflags')
         self._add_argument('--force-rebuild')
         self._add_argument('--optimization-level')
+        self.add_argument(
+            '--out-rootfs-overlay-dir-prefix',
+            default='',
+            help='''\
+Place the output files inside the image within this additional prefix.
+This is mostly useful to place different versions of binaries with different
+build parameters inside image to compare them. See:
+* https://cirosantilli.com/linux-kernel-module-cheat#update-the-toolchain
+* https://cirosantilli.com/linux-kernel-module-cheat#out_rootfs_overlay_dir
+'''
+        )
         self.add_argument(
             'targets',
             default=[],
@@ -88,7 +99,10 @@ Default: build all examples that have their package dependencies met, e.g.:
         if not self.env['in_tree']:
             self.sh.copy_dir_if_update(
                 srcdir=build_dir,
-                destdir=self.env['out_rootfs_overlay_lkmc_dir'],
+                destdir=os.path.join(
+                    self.env['out_rootfs_overlay_lkmc_dir'],
+                    self.env['out_rootfs_overlay_dir_prefix']
+                ),
                 filter_ext=self.env['userland_executable_ext'],
             )
         return exit_status

common.py

@@ -702,14 +702,16 @@ Incompatible archs are skipped.
             env['crosstool_ng_toolchain_prefix'] = 'arm-unknown-eabi'
             env['ubuntu_toolchain_prefix'] = 'arm-linux-gnueabihf'
             env['is_arm'] = True
-            env['march'] = 'armv8-a'
+            if not env['_args_given']['march']:
+                env['march'] = 'armv8-a'
         elif env['arch'] == 'aarch64':
             env['armv'] = 8
             env['buildroot_toolchain_prefix'] = 'aarch64-buildroot-linux-gnu'
             env['crosstool_ng_toolchain_prefix'] = 'aarch64-unknown-elf'
             env['ubuntu_toolchain_prefix'] = 'aarch64-linux-gnu'
             env['is_arm'] = True
-            env['march'] = 'armv8-a+lse'
+            if not env['_args_given']['march']:
+                env['march'] = 'armv8-a+lse'
         elif env['arch'] == 'x86_64':
             env['crosstool_ng_toolchain_prefix'] = 'x86_64-unknown-elf'
             env['gem5_arch'] = 'X86'
@@ -931,6 +933,7 @@ Incompatible archs are skipped.
         env['kernel_modules_build_host_subdir'] = join(env['kernel_modules_build_host_dir'], env['kernel_modules_subdir'])
 
         # Overlay.
+        # https://cirosantilli.com/linux-kernel-module-cheat#buildroot_packages-directory
         env['out_rootfs_overlay_dir'] = join(env['out_dir'], 'rootfs_overlay', env['arch'])
         env['out_rootfs_overlay_lkmc_dir'] = join(env['out_rootfs_overlay_dir'], env['repo_short_id'])
         env['out_rootfs_overlay_bin_dir'] = join(env['out_rootfs_overlay_dir'], 'bin')

run

@@ -75,8 +75,8 @@ https://cirosantilli.com/linux-kernel-module-cheat#lkmc_home
             '--eval-after',
             help='''\
 Similar to --eval, but the string gets evaled at the last init script,
-after the normal init finished.
+after the normal init finished. After this string is evaled, you are left
-See: https://cirosantilli.com/linux-kernel-module-cheat#init-busybox
+inside a shell. See: https://cirosantilli.com/linux-kernel-module-cheat#init-busybox
 '''
         )
         self.add_argument(