run: --linux-exec to override the Linux image used

Explain about gem5 upstream prebuilts.

README.adoc

@@ -12356,6 +12356,35 @@ TODO: describe the main characteristics of each platform, as of gem5 5e83d703522
 * `VExpress_GEM5_V2`: VExpress_GEM5_V1 with GICv3, uses a different bootloader `arm/aarch64_bootloader/boot_emm_v2.arm64` TODO is it because of GICv3?
 * anything that does not start with: `VExpress_GEM5_`: old and bad, don't use them
 
+=== gem5 upstream images
+
+Present at:
+
+* http://www.gem5.org/dist/current/arm/
+* http://www.gem5.org/dist/current/x86/
+
+Depending on which archive you download from there, you can find some of:
+
+* Ubuntu based images
+* precompiled Linux kernels, with the <<gem5-arm-linux-kernel-patches>> for arm
+* precompiled <<gem5-bootloaders>> for ISAs that have them, e.g. ARM
+* precompiled DTBs if you don't want to use autogeneration for some crazy reason
+
+Some of those images are also used on the <<gem5-unit-tests>> continuous integration.
+
+Could be used as an alternative to this repository. But why would you do that? :-)
+
+E.g. to use a precompiled ARM kernel:
+
+....
+mkdir aarch-system-201901106
+cd aarch-system-201901106
+wget http://www.gem5.org/dist/current/arm/aarch-system-201901106.tar.bz2
+tar xvf aarch-system-201901106.tar.bz2
+cd ..
+./run --arch aarch64 --emulator gem5 --linux-exec aarch-system-201901106/binaries/vmlinux.arm64
+....
+
 === gem5 internals
 
 Internals under other sections:
@@ -13304,6 +13333,26 @@ The horrendous downsides of this are:
 * when <<debug-the-emulator,debugging the emulator>>, it shows you directories inside the build directory rather than in the source tree
 * it is harder to separate which files are <<gem5-code-generation,generated>> and which are in-tree when grepping for code generated definitions
 
+=== gem5 bootloaders
+
+Certain ISAs like ARM have bootloaders that are automatically run before the main image to setup basic system state.
+
+We cross compile those bootloaders from source automatically during `./build-gem5`.
+
+As of gem5 bcf041f257623e5c9e77d35b7531bae59edc0423, the source code of the bootloaderes can be found under:
+
+....
+system/arm/
+....
+
+and their selection can be seen under: `src/dev/arm/RealView.py`, e.g.:
+
+....
+    def setupBootLoader(self, cur_sys, loc):
+        if not cur_sys.boot_loader:
+            cur_sys.boot_loader = [ loc('boot_emm.arm64'), loc('boot_emm.arm') ]
+....
+
 == Buildroot
 
 === Introduction to Buildroot

common.py

@@ -373,6 +373,14 @@ Use the given directory as the Linux build directory. Ignore --linux-build-id.
             help='''\
 Linux build ID. Allows you to keep multiple separate Linux builds.
 '''
+        )
+        self.add_argument(
+            '--linux-exec',
+            help='''\
+Use the given executable Linux kernel image. Ignored in userland and baremetal modes,
+Remember that different emulators may take different types of image, see:
+https://cirosantilli.com/linux-kernel-module-cheat#vmlinux-vs-bzimage-vs-zimage-vs-image
+''',
         )
         self.add_argument(
             '--linux-source-dir',
@@ -1071,14 +1079,18 @@ Incompatible archs are skipped.
                     break
         else:
             if env['emulator'] == 'gem5':
-                env['image'] = env['vmlinux']
+                if not env['_args_given']['linux_exec']:
+                    env['image'] = env['vmlinux']
                 if env['ramfs']:
                     env['disk_image'] = env['gem5_fake_iso']
                 else:
                     env['disk_image'] = env['rootfs_raw_file']
             else:
-                env['image'] = env['linux_image']
+                if not env['_args_given']['linux_exec']:
+                    env['image'] = env['linux_image']
                 env['disk_image'] = env['qcow2_file']
+            if env['_args_given']['linux_exec']:
+                env['image'] = env['linux_exec']
 
         # Android
         if not env['_args_given']['android_base_dir']: