From 3d0cc6014baa6dddb4dfa25b656ba37c5e1540d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciro=20Santilli=20=E5=85=AD=E5=9B=9B=E4=BA=8B=E4=BB=B6=20?= =?UTF-8?q?=E6=B3=95=E8=BD=AE=E5=8A=9F?= Date: Sun, 21 Jul 2019 00:00:03 +0000 Subject: [PATCH] readme: use xrefstyle=full on many links where it makes sense Searched for links that matched ": <<" --- README.adoc | 329 ++++++++++++++++++++++++++-------------------------- 1 file changed, 166 insertions(+), 163 deletions(-) diff --git a/README.adoc b/README.adoc index a3af9eb..5ceadd6 100644 --- a/README.adoc +++ b/README.adoc @@ -15,7 +15,7 @@ https://zenodo.org/badge/latestdoi/64534859[image:https://zenodo.org/badge/64534 {description} -TL;DR: <> +TL;DR: xref:qemu-buildroot-setup-getting-started[xrefstyle=full] The source code for this page is located at: https://github.com/cirosantilli/linux-kernel-module-cheat[]. Due to https://github.com/isaacs/github/issues/1610[a GitHub limitation], this README is too long and not fully rendered on github.com. Either use: link:README.adoc[], https://cirosantilli.com/linux-kernel-module-cheat or <>. @@ -27,13 +27,13 @@ Each child section describes a possible different setup for this repo. If you don't know which one to go for, start with <>. -Design goals of this project are documented at: <>. +Design goals of this project are documented at: xref:design-goals[xrefstyle=full]. === QEMU Buildroot setup ==== QEMU Buildroot setup getting started -This setup has been mostly tested on Ubuntu. For other host operating systems see: <>. For greater stability, consider using the <> instead of master: https://github.com/cirosantilli/linux-kernel-module-cheat/releases +This setup has been mostly tested on Ubuntu. For other host operating systems see: xref:supported-hosts[xrefstyle=full]. For greater stability, consider using the <> instead of master: https://github.com/cirosantilli/linux-kernel-module-cheat/releases Reserve 12Gb of disk and run: @@ -46,7 +46,7 @@ cd linux-kernel-module-cheat You don't need to clone recursively even though we have `.git` submodules: `download-dependencies` fetches just the submodules that you need for this build to save time. -If something goes wrong, see: <> and use our issue tracker: https://github.com/cirosantilli/linux-kernel-module-cheat/issues +If something goes wrong, see: xref:common-build-issues[xrefstyle=full] and use our issue tracker: https://github.com/cirosantilli/linux-kernel-module-cheat/issues The initial build will take a while (30 minutes to 2 hours) to clone and build, see <> for more details. @@ -88,7 +88,7 @@ Quit QEMU with: Ctrl-A X .... -See also: <>. +See also: xref:quit-qemu-from-text-mode[xrefstyle=full]. All available modules can be found in the link:kernel_modules[] directory. @@ -99,7 +99,7 @@ It is super easy to build for different <>, ./run --arch aarch64 .... -To avoid typing `--arch aarch64` many times, you can set the default arch as explained at: <> +To avoid typing `--arch aarch64` many times, you can set the default arch as explained at: xref:default-command-line-arguments[xrefstyle=full] I now urge you to read the following sections which contain widely applicable information: @@ -201,7 +201,7 @@ The link:build[] script is just a lightweight wrapper that calls the smaller bui ./build --dry-run .... -When you reach difficulties, QEMU makes it possible to easily GDB step debug the Linux kernel source code, see: <>. +When you reach difficulties, QEMU makes it possible to easily GDB step debug the Linux kernel source code, see: xref:gdb[xrefstyle=full]. ===== Your first kernel module hack @@ -263,7 +263,7 @@ If the guest and host are the same arch, typically x86_64, you can speed up boot All of this put together makes the safe procedure acceptably fast for regular development as well. -It is also easy to GDB step debug kernel modules with our setup, see: <>. +It is also easy to GDB step debug kernel modules with our setup, see: xref:gdb-step-debug-kernel-module[xrefstyle=full]. ===== Your first QEMU hack @@ -307,9 +307,9 @@ The only thing you can do with open source is purely functional designs with htt If you really want to develop semiconductors, your only choice is to join an university or a semiconductor company that has the EDA licenses. -See also: <>. +See also: xref:should-you-waste-your-life-with-systems-programming[xrefstyle=full]. -While hacking QEMU, you will likely want to GDB step its source. That is trivial since QEMU is just another userland program like any other, but our setup has a shortcut to make it even more convenient, see: <>. +While hacking QEMU, you will likely want to GDB step its source. That is trivial since QEMU is just another userland program like any other, but our setup has a shortcut to make it even more convenient, see: xref:debug-the-emulator[xrefstyle=full]. ===== Your first glibc hack @@ -546,7 +546,7 @@ gem5 on the other hand, can simulate the system in more detail than QEMU, includ * caches * DRAM timing -and can therefore be used to estimate system performance, see: <> for an example. +and can therefore be used to estimate system performance, see: xref:gem5-run-benchmark[xrefstyle=full] for an example. The downside of gem5 much slower than QEMU because of the greater simulation detail. @@ -585,7 +585,7 @@ If you are inside <>, which I highly recommend, you can both run gem5 stdo ./run --emulator gem5 --tmux .... -See also: <>. +See also: xref:tmux-gem5[xrefstyle=full]. At the end of boot, it might not be very clear that you have the shell since some <> messages may appear in front of the prompt like this: @@ -602,7 +602,7 @@ If you forgot to open the shell and gem5 exit, you can inspect the terminal outp less "$(./getvar --emulator gem5 m5out_dir)/system.pc.com_1.device" .... -More gem5 information is present at: <> +More gem5 information is present at: xref:gem5[xrefstyle=full] Good next steps are: @@ -615,7 +615,7 @@ Good next steps are: This repository has been tested inside clean https://en.wikipedia.org/wiki/Docker_(software)[Docker] containers. -This is a good option if you are on a Linux host, but the native setup failed due to your weird host distribution, and you have better things to do with your life than to debug it. See also: <>. +This is a good option if you are on a Linux host, but the native setup failed due to your weird host distribution, and you have better things to do with your life than to debug it. See also: xref:supported-hosts[xrefstyle=full]. For example, to do a <> inside Docker, run: @@ -730,7 +730,7 @@ Advantage of this setup: saves time and disk space on the initial install, which The limitations are severe however: -* can't <>, since the source and cross toolchain with GDB are not available. Buildroot cannot easily use a host toolchain: <>. +* can't <>, since the source and cross toolchain with GDB are not available. Buildroot cannot easily use a host toolchain: xref:prebuilt-toolchain[xrefstyle=full]. + Maybe we could work around this by just downloading the kernel source somehow, and using a host prebuilt GDB, but we felt that it would be too messy and unreliable. * you won't get the latest version of this repository. Our <> attempt to automate builds failed, and storing a release for every commit would likely make GitHub mad at us anyways. @@ -825,7 +825,7 @@ The Linux kernel is required for `extract-vmlinux` to convert the compressed ker This setup is similar to <>, but instead of using Buildroot for the root filesystem, it downloads an Ubuntu image with Docker, and uses that as the root filesystem. -The rationale for choice of Ubuntu as a second distribution in addition to Buildroot can be found at: <> +The rationale for choice of Ubuntu as a second distribution in addition to Buildroot can be found at: xref:linux-distro-choice[xrefstyle=full] Advantages over Buildroot: @@ -969,14 +969,14 @@ Notable userland content included / moving into this repository includes: There are several ways to run our <>, notably: -* natively on the host as shown at: <> +* natively on the host as shown at: xref:userland-setup-getting-started-natively[xrefstyle=full] + Can only run examples compatible with your host CPU architecture and OS, but has the fastest setup and runtimes. * from user mode simulation with: + -- -** the host prebuilt toolchain: <> -** the Buildroot toolchain you built yourself: <> +** the host prebuilt toolchain: xref:userland-setup-getting-started-with-prebuilt-toolchain-and-qemu-user-mode[xrefstyle=full] +** the Buildroot toolchain you built yourself: xref:qemu-user-mode-getting-started[xrefstyle=full] -- + This setup: @@ -985,7 +985,7 @@ This setup: ** can run most examples, including those for other CPU architectures, with the notable exception of examples that rely on kernel modules ** can run reproducible approximate performance experiments with gem5, see e.g. <> -- -* from full system simulation as shown at: <>. +* from full system simulation as shown at: xref:qemu-buildroot-setup-getting-started[xrefstyle=full]. + This is the most reproducible and controlled environment, and all examples work there. But also the slower one to setup. @@ -1071,7 +1071,7 @@ The `build` scripts inside link:userland/[] are just symlinks to link:build-user So you can use any option supported by `build-userland` script freely with `build-userland-in-tree` and `build`. -The situation is analogous for link:userland/test[], link:test-executables-in-tree[] and link:test-executables[], which are further documented at: <>. +The situation is analogous for link:userland/test[], link:test-executables-in-tree[] and link:test-executables[], which are further documented at: xref:user-mode-tests[xrefstyle=full]. Do a more clean out-of-tree build instead and run the program: @@ -1091,7 +1091,7 @@ In this case you can debub the program with: ./run --debug-vm --emulator native --userland userland/c/hello.c --userland-build-id host .... -as shown at: <>, although direct GDB host usage works as well of course. +as shown at: xref:debug-the-emulator[xrefstyle=full], although direct GDB host usage works as well of course. ===== Userland setup getting started with prebuilt toolchain and QEMU user mode @@ -1117,10 +1117,10 @@ where: * `--gcc-which host`: use the host toolchain. + -We must pass this to `./run` as well because QEMU must know which dynamic libraries to use. See also: <>. +We must pass this to `./run` as well because QEMU must know which dynamic libraries to use. See also: xref:user-mode-static-executables[xrefstyle=full]. * `--userland-build-id host`: put the host built into a <> -This present the usual trade-offs of using prebuilts as mentioned at: <>. +This present the usual trade-offs of using prebuilts as mentioned at: xref:prebuilt[xrefstyle=full]. Other functionality are analogous, e.g. testing: @@ -1153,7 +1153,7 @@ First ensure that <> is working. After doing that setup, you can already execute your userland programs from inside QEMU: the only missing step is how to rebuild executables and run them. -And the answer is exactly analogous to what is shown at: <> +And the answer is exactly analogous to what is shown at: xref:your-first-kernel-module-hack[xrefstyle=full] For example, if we modify link:userland/c/hello.c[] to print out something different, we can just rebuild it with: @@ -1303,7 +1303,7 @@ Or as usual, <> users can do both in one go with: ./run --arch aarch64 --baremetal userland/c/hello.c --emulator gem5 --tmux .... -TODO: the carriage returns are a bit different than in QEMU, see: <>. +TODO: the carriage returns are a bit different than in QEMU, see: xref:gem5-baremetal-carriage-return[xrefstyle=full]. Note that `./build-baremetal` requires the `--emulator gem5` option, and generates separate executable images for both, as can be seen from: @@ -1337,9 +1337,9 @@ echo "$(./getvar --arch aarch64 --baremetal userland/c/hello.c --emulator gem5 - But just stick to newer and better `VExpress_GEM5_V1` unless you have a good reason to use `RealViewPBX`. -When doing baremetal programming, it is likely that you will want to learn userland assembly first, see: <>. +When doing baremetal programming, it is likely that you will want to learn userland assembly first, see: xref:userland-assembly[xrefstyle=full]. -For more information on baremetal, see the section: <>. +For more information on baremetal, see the section: xref:baremetal[xrefstyle=full]. The following subjects are particularly important: @@ -1932,7 +1932,7 @@ See also: https://stackoverflow.com/questions/2589845/what-are-the-first-operati <> with `--debug-flags=Exec` does show the right symbols however! So in the worst case, we can just read their source. Amazing. -v4.19 also added a `CONFIG_HAVE_KERNEL_UNCOMPRESSED=y` option for having the kernel uncompressed which could make following the startup easier, but it is only available on s390. `aarch64` however is already uncompressed by default, so might be the easiest one. See also: <>. +v4.19 also added a `CONFIG_HAVE_KERNEL_UNCOMPRESSED=y` option for having the kernel uncompressed which could make following the startup easier, but it is only available on s390. `aarch64` however is already uncompressed by default, so might be the easiest one. See also: xref:vmlinux-vs-bzimage-vs-zimage-vs-image[xrefstyle=full]. ==== GDB step debug early boot by address @@ -1982,7 +1982,7 @@ QEMU's `-gdb` GDB breakpoints are set on virtual addresses, so you can in theory You will generally want to use <> for this as it is more reliable, but this method can overcome the following limitations of `gdbserver`: -* the emulator does not support host to guest networking. This seems to be the case for gem5: <> +* the emulator does not support host to guest networking. This seems to be the case for gem5 as explained at: xref:gem5-host-to-guest-networking[xrefstyle=full] * cannot see the start of the `init` process easily * `gdbserver` alters the working of the kernel, and makes your run less representative @@ -1990,7 +1990,7 @@ Known limitations of direct userland debugging: * the kernel might switch context to another process or to the kernel itself e.g. on a system call, and then TODO confirm the PIC would go to weird places and source code would be missing. + -Solutions to this are being researched at: <>. +Solutions to this are being researched at: xref:lx-ps[xrefstyle=full]. * TODO step into shared libraries. If I attempt to load them explicitly: + .... @@ -2192,7 +2192,7 @@ The implementation is described at: https://stackoverflow.com/questions/46415059 === GDB step debug multicore userland -For a more minimal baremetal multicore setup, see: <>. +For a more minimal baremetal multicore setup, see: xref:arm-multicore[xrefstyle=full]. We can set and get which cores the Linux kernel allows a program to run on with `sched_getaffinity` and `sched_setaffinity`: @@ -2218,7 +2218,7 @@ Which shows us that: ** the process was randomly assigned to run on core 1 (the second one) as shown by `sched_getcpu = 1`. If we run this several times, it will also run on core 0 sometimes. * then we restrict the affinity to just core 0, and we see that the program was actually moved to core 0 -The number of cores is modified as explained at: <> +The number of cores is modified as explained at: xref:number-of-cores[xrefstyle=full] `taskset` from the util-linux package sets the initial core affinity of a program: @@ -2456,7 +2456,7 @@ Entering kdb (current=0x(____ptrval____), pid 1) on processor 0 due to Keyboard KGDB expects the connection at `ttyS1`, our second serial port after `ttyS0` which contains the terminal. -The last line is the KDB prompt, and is covered at: <>. Typing now shows nothing because that prompt is expecting input from `ttyS1`. +The last line is the KDB prompt, and is covered at: xref:kdb[xrefstyle=full]. Typing now shows nothing because that prompt is expecting input from `ttyS1`. Instead, we connect to the serial port `ttyS1` with GDB: @@ -2842,7 +2842,7 @@ BusyBox provides its own minimalistic init implementation which Buildroot, and t The `init` program can be either an executable shell text file, or a compiled ELF file. It becomes easy to accept this once you see that the `exec` system call handles both cases equally: https://unix.stackexchange.com/questions/174062/can-the-init-process-be-a-shell-script-in-linux/395375#395375 -The `init` executable is searched for in a list of paths in the root filesystem, including `/init`, `/sbin/init` and a few others. For more details see: <> +The `init` executable is searched for in a list of paths in the root filesystem, including `/init`, `/sbin/init` and a few others. For more details see: xref:path-to-init[xrefstyle=full] === Replace init @@ -2856,7 +2856,7 @@ The most direct way to replace `init` with our own is to just use the `init=` << This just counts every second forever and does not give you a shell. -This method is not very flexible however, as it is hard to reliably pass multiple commands and command line arguments to the init with it, as explained at: <>. +This method is not very flexible however, as it is hard to reliably pass multiple commands and command line arguments to the init with it, as explained at: xref:init-environment[xrefstyle=full]. For this reason, we have created a more robust helper method with the `--eval` option: @@ -2872,9 +2872,9 @@ It is basically a shortcut for: Source: link:rootfs_overlay/lkmc/eval_base64.sh[]. -This allows quoting and newlines by base64 encoding on host, and decoding on guest, see: <>. +This allows quoting and newlines by base64 encoding on host, and decoding on guest, see: xref:kernel-command-line-parameters-escaping[xrefstyle=full]. -It also automatically chooses between `init=` and `rcinit=` for you, see: <> +It also automatically chooses between `init=` and `rcinit=` for you, see: xref:path-to-init[xrefstyle=full] `--eval` replaces BusyBox' init completely, which makes things more minimal, but also has has the following consequences: @@ -2889,7 +2889,7 @@ It also automatically chooses between `init=` and `rcinit=` for you, see: <> +The best way to overcome those limitations is to use: xref:init-busybox[xrefstyle=full] If the script is large, you can add it to a gitignored file and pass that to `--eval` as in: @@ -3188,7 +3188,7 @@ cat f which can be good for automated tests, as it ensures that you are using a pristine unmodified system image every time. -Not however that we already disable disk persistency by default on ext2 filesystems even without `--initrd`: <>. +Not however that we already disable disk persistency by default on ext2 filesystems even without `--initrd`: xref:disk-persistency[xrefstyle=full]. One downside of this method is that it has to put the entire filesystem into memory, and could lead to a panic: @@ -3292,7 +3292,7 @@ TODO: understand `/dev/root` better: ==== /dev/root -See: <> +See: xref:rootfs[xrefstyle=full] === gem5 initrd @@ -3316,7 +3316,7 @@ However, it didn't: boot fails at the end because it does not see the initramfs, VFS: Cannot open root device "sda" or unknown-block(8,0): error -5 .... -We think that this might be because gem5 boots directly `vmlinux`, and not from the final compressed images that contain the attached rootfs such as `bzImage`, which is what QEMU does, see also: <>. +We think that this might be because gem5 boots directly `vmlinux`, and not from the final compressed images that contain the attached rootfs such as `bzImage`, which is what QEMU does, see also: xref:vmlinux-vs-bzimage-vs-zimage-vs-image[xrefstyle=full]. To do this failed test, we automatically pass a dummy disk image as of gem5 7fa4c946386e7207ad5859e8ade0bbfc14000d91 since the scripts don't handle a missing `--disk-image` well, much like is currently done for <>. @@ -3577,7 +3577,7 @@ It may still work even if that is not the case, but could fail is a missing syst The target Linux kernel of the executable is a GCC toolchain build-time configuration. ** emulator implementers have to keep up with libc changes, some of which break even a C hello world due setup code executed before main. + -See also: <> +See also: xref:user-mode-simulation-with-glibc[xrefstyle=full] * cannot be used to test the Linux kernel or any devices, and results are less representative of a real system since we are faking more === QEMU user mode getting started @@ -3602,7 +3602,7 @@ qw er `./run --userland` path resolution is analogous to <>. -`./build user-mode-qemu` first builds Buildroot, and then runs `./build-userland`, which is further documented at: <>. It also builds QEMU. If you ahve already done a <> previously, this will be very fast. +`./build user-mode-qemu` first builds Buildroot, and then runs `./build-userland`, which is further documented at: xref:userland-setup[xrefstyle=full]. It also builds QEMU. If you ahve already done a <> previously, this will be very fast. If you modify the userland programs, rebuild simply with: @@ -3644,7 +3644,7 @@ Or alternatively, if you are using <>, do everything in one go with: ; .... -To stop at the very first instruction of a freestanding program, just use `--no-continue`. A good example of this is shown at: <>. +To stop at the very first instruction of a freestanding program, just use `--no-continue`. A good example of this is shown at: xref:freestanding-programs[xrefstyle=full]. === User mode tests @@ -3673,9 +3673,9 @@ This script skips a manually configured list of tests, notably: Tests under link:userland/libs/[] depend on certain libraries being available on the target, e.g. <> for link:userland/libs/openblas[]. They are not run by default, but can be enabled with `--package` and `--package-all`. -The gem5 tests require building statically with build id `static`, see also: <>. TODO automate this better. +The gem5 tests require building statically with build id `static`, see also: xref:gem5-syscall-emulation-mode[xrefstyle=full]. TODO automate this better. -See: <> for more useful testing tips. +See: xref:test-this-repo[xrefstyle=full] for more useful testing tips. === User mode Buildroot executables @@ -3708,7 +3708,7 @@ or: ; .... -Here is an interesting examples of this: <> +Here is an interesting examples of this: xref:linux-test-project[xrefstyle=full] === User mode simulation with glibc @@ -3802,7 +3802,7 @@ We pass `-L` by default, so everything just works. However, in case something goes wrong, you can also try statically linked executables, since this mechanism tends to be a bit more stable, for example: -* gem5 user mode currently only supports static executables: <> +* gem5 user mode currently only supports static executables as mentioned at: xref:gem5-syscall-emulation-mode[xrefstyle=full] * QEMU x86_64 guest on x86_64 host was failing with <>, but we found a workaround ==== User mode static executables with dynamic libraries @@ -3930,7 +3930,7 @@ Source: link:userland/c/getchar.c[] Let's see if user mode runs considerably faster than full system or not. -First we build Dhrystone manually statically since dynamic linking is broken in gem5: <>. +First we build Dhrystone manually statically since dynamic linking is broken in gem5 as explained at: xref:gem5-syscall-emulation-mode[xrefstyle=full]. gem5 user mode: @@ -4088,15 +4088,15 @@ This is the default install path for `CONFIG_SOME_MOD=m` modules built with `mak Currently, there are only two kinds of kernel modules that you can try out with `modprobe`: -* modules built with Buildroot, see: <> -* modules built from the kernel tree itself, see: <> +* modules built with Buildroot, see: xref:kernel_modules-buildroot-package[xrefstyle=full] +* modules built from the kernel tree itself, see: xref:dummy-irq[xrefstyle=full] We are not installing out custom `./build-modules` modules there, because: * we don't know the right way. Why is there no `install` or `install_modules` target for kernel modules? + This can of course be solved by running Buildroot in verbose mode, and copying whatever it is doing, initial exploration at: https://stackoverflow.com/questions/22783793/how-to-install-kernel-modules-from-source-code-error-while-make-process/53169078#53169078 -* we would have to think how to not have to include the kernel modules twice in the root filesystem, but still have <<9p>> working for fast development as described at: <> +* we would have to think how to not have to include the kernel modules twice in the root filesystem, but still have <<9p>> working for fast development as described at: xref:your-first-kernel-module-hack[xrefstyle=full] === kmod @@ -4158,7 +4158,7 @@ This would have several advantages: * makes it faster to test modified guest programs ** not rebooting is fundamental for <>, where the reboot is very costly. ** no need to regenerate the root filesystem at all and reboot -** overcomes the `check_bin_arch` problem: <> +** overcomes the `check_bin_arch` problem as shown at: xref:rpath[xrefstyle=full] * we could keep the base root filesystem very small, which implies: ** less host disk usage, no need to copy the entire `./getvar out_rootfs_overlay_dir` to the image again ** no need to worry about <> @@ -4224,7 +4224,7 @@ In text mode, we just show the serial console directly on the current terminal, You cannot see any graphics from text mode, but text operations in this mode, including: -* scrolling up: <> +* scrolling up: xref:scroll-up-in-graphic-mode[xrefstyle=full] * copy paste to and from the terminal making this a good default, unless you really need to use with graphics. @@ -4279,7 +4279,7 @@ Enable graphic mode with: Outcome: you see a penguin due to <>. -For a more exciting GUI experience, see: <> +For a more exciting GUI experience, see: xref:x11[xrefstyle=full] Text mode is the default due to the following considerable advantages: @@ -4675,7 +4675,7 @@ A friend told me this but I haven't tried it yet: === Enable networking -We disable networking by default because it starts an userland process, and we want to keep the number of userland processes to a minimum to make the system more understandable: <> +We disable networking by default because it starts an userland process, and we want to keep the number of userland processes to a minimum to make the system more understandable as explained at: xref:resource-tradeoff-guidelines[xrefstyle=full] To enable networking on Buildroot, simply run: @@ -4720,7 +4720,7 @@ https://unix.stackexchange.com/questions/473448/how-to-ping-from-the-qemu-guest- In this section we discuss how to interact between the guest and the host through networking. -First ensure that you can access the external network since that is easier to get working: <>. +First ensure that you can access the external network since that is easier to get working, see: xref:networking[xrefstyle=full]. ==== Host to guest networking @@ -4897,7 +4897,7 @@ TODO: get working. <<9p>> is better with emulation, but let's just get this working for fun. -First make sure that this works: <>. +First make sure that this works: xref:guest-to-host-networking[xrefstyle=full]. Then, build the kernel with NFS support: @@ -5012,7 +5012,7 @@ cp "$(./getvar linux_build_dir)/defconfig" data/myconfig ./build-linux --custom-config-file data/myconfig .... -You can also use other config generating targets such as `defconfig` with the same method as shown at: <>. +You can also use other config generating targets such as `defconfig` with the same method as shown at: xref:linux-kernel-defconfig[xrefstyle=full]. ==== Find the kernel config @@ -5062,7 +5062,7 @@ although this can be useful when someone gives you a random image. By default, link:build-linux[] generates a `.config` that is a mixture of: -* a base config extracted from Buildroot's minimal per machine `.config`, which has the minimal options needed to boot: <>. +* a base config extracted from Buildroot's minimal per machine `.config`, which has the minimal options needed to boot as explained at: xref:buildroot-kernel-config[xrefstyle=full]. * small overlays put top of that To find out which kernel configs are being used exactly, simply run: @@ -5087,10 +5087,10 @@ Note that Buildroot can `sed` override some of the configurations, e.g. it force On top of those, we add the following by default: -* link:linux_config/min[]: see: <> +* link:linux_config/min[]: see: xref:linux-kernel-min-config[xrefstyle=full] * link:linux_config/default[]: other optional configs that we enable by default because they increase visibility, or expose some cool feature, and don't significantly increase build time nor add significant runtime overhead + -We have since observed that the kernel size itself is very bloated compared to `defconfig`: <>. +We have since observed that the kernel size itself is very bloated compared to `defconfig` as shown at: xref:linux-kernel-defconfig[xrefstyle=full]. [[buildroot-kernel-config]] ===== About Buildroot's kernel configs @@ -5178,7 +5178,7 @@ Tested on 1e2b7f1e5e9e3073863dc17e25b2455c8ebdeadd + 1. link:linux_config/min[] contains minimal tweaks required to boot gem5 or for using our slightly different QEMU command line options than Buildroot on all archs. -It is one of the default config fragments we use, as explained at: <>>. +It is one of the default config fragments we use, as explained at: xref:kernel-configs-about[xrefstyle=full]>. Having the same config working for both QEMU and gem5 (oh, the hours of bisection) means that you can deal with functional matters in QEMU, which runs much faster, and switch to gem5 only for performance issues. @@ -5201,7 +5201,7 @@ Tested on 649d06d6758cefd080d04dc47fd6a5a26a620874 + 1. Other configs which we had previously tested at 4e0d9af81fcce2ce4e777cb82a1990d7c2ca7c1e are: -* `arm` and `aarch64` configs present in the official ARM gem5 Linux kernel fork: <>. Some of the configs present there are added by the patches. +* `arm` and `aarch64` configs present in the official ARM gem5 Linux kernel fork as described at: xref:gem5-arm-linux-kernel-patches[xrefstyle=full]. Some of the configs present there are added by the patches. * Jason's magic `x86_64` config: http://web.archive.org/web/20171229121642/http://www.lowepower.com/jason/files/config which is referenced at: http://web.archive.org/web/20171229121525/http://www.lowepower.com/jason/setting-up-gem5-full-system.html[]. QEMU boots with that by removing `# CONFIG_VIRTIO_PCI is not set`. === Kernel version @@ -5235,13 +5235,13 @@ This backwards compatibility is just awesome, it makes getting and running the l This also makes this repo the perfect setup to develop the Linux kernel. -In case something breaks while updating the Linux kernel, you can try to bisect it to understand the root cause: <>. +In case something breaks while updating the Linux kernel, you can try to bisect it to understand the root cause, see: xref:bisection[xrefstyle=full]. ===== Update the Linux kernel LKMC procedure -First, use use the branching procedure described at: <> +First, use use the branching procedure described at: xref:update-a-forked-submodule[xrefstyle=full] -Because the kernel is so central to this repository, almost all tests must be re-run, so basically just follow the full testing procedure described at: <>. The only tests that can be skipped are essentially the <> tests. +Because the kernel is so central to this repository, almost all tests must be re-run, so basically just follow the full testing procedure described at: xref:test-this-repo[xrefstyle=full]. The only tests that can be skipped are essentially the <> tests. Before comitting, don't forget to update: @@ -5484,7 +5484,7 @@ This format is selected by the following boot options: * `console_msg_format=syslog`: add the `` part. Added in v4.16. * `printk.time=y`: add the `[TIMESTAMP]` part -The debug highest level is a bit more magic, see: <> for more info. +The debug highest level is a bit more magic, see: xref:pr_debug[xrefstyle=full] for more info. ==== ignore_loglevel @@ -6170,7 +6170,7 @@ For testing purposes, it is very useful to quit the emulator automatically with Enabled by default with: -* `panic=-1` command line option which reboots the kernel immediately on panic, see: <> +* `panic=-1` command line option which reboots the kernel immediately on panic, see: xref:reboot-on-panic[xrefstyle=full] * QEMU `-no-reboot`, which makes QEMU exit when the guest tries to reboot Also asked at https://unix.stackexchange.com/questions/443017/can-i-make-qemu-exit-with-failure-on-kernel-panic which also mentions the x86_64 `-device pvpanic`, but I don't see much advantage to it. @@ -6897,7 +6897,7 @@ The count stops when we `rmmod`: rmmod kthread .... -The sleep is done with `usleep_range`, see: <>. +The sleep is done with `usleep_range`, see: xref:sleep[xrefstyle=full]. Bibliography: @@ -7805,7 +7805,7 @@ TODO: didn't port during refactor after 3b0a343647bed577586989fb702b760bd280844a * `qemu/docs/tracing.txt` and `qemu/docs/replay.txt` * https://stackoverflow.com/questions/39149446/how-to-use-qemus-simple-trace-backend/46497873#46497873 -Results (boot not excluded): <> +Results (boot not excluded) are shown at: xref:table-boot-instruction-counts[xrefstyle=full] [[table-boot-instruction-counts]] .Boot instruction counts for various setups @@ -8018,7 +8018,7 @@ it does not work and outputs: setenforce: SELinux is disabled .... -SELinux requires glibc: <>. +SELinux requires glibc as mentioned at: xref:libc-choice[xrefstyle=full]. === User mode Linux @@ -8148,7 +8148,7 @@ Enabled from our link:rootfs_overlay/etc/inittab[]: ::ctrlaltdel:/sbin/reboot .... -Linux tries to reboot, and QEMU shutdowns due to the `-no-reboot` option which we set by default for: <>. +Linux tries to reboot, and QEMU shutdowns due to the `-no-reboot` option which we set by default for, see: xref:exit-emulator-on-panic[xrefstyle=full]. Under the hood, behaviour is controlled by the `reboot` syscall: @@ -8607,7 +8607,7 @@ TODO get working. Implements a console for <>. -The Linux kernel has a built-in fbdev console: <> but not for <> it seems. +The Linux kernel has a built-in fbdev console called <> but not for <> it seems. The upstream project seems dead with last commit in 2014: https://www.freedesktop.org/wiki/Software/kmscon/ @@ -8683,7 +8683,7 @@ Tested at: 287c83f3f99db8c1ff9bbc85a79576da6a78e986 + 1. ; .... -`STRESS_NG` is likely the best, but it requires glibc: <>. +`STRESS_NG` is likely the best, but it requires glibc, see: xref:libc-choice[xrefstyle=full]. Websites: @@ -8758,7 +8758,7 @@ Maybe it is also possible to run Xen directly like this: QEMU can already load m -kernel file1.elf -device loader,file=file2.elf .... -so as long as we craft the correct DTB and feed it into Xen so that it can see the kernel, it should work. TODO does QEMU support patching the auto-generated DTB with pre-generated options? In the worst case we can just dump it hand hack it up though with `-machine dumpdtb`: <>. +so as long as we craft the correct DTB and feed it into Xen so that it can see the kernel, it should work. TODO does QEMU support patching the auto-generated DTB with pre-generated options? In the worst case we can just dump it hand hack it up though with `-machine dumpdtb`, see: xref:device-tree-emulator-generation[xrefstyle=full]. Bibliography: @@ -9671,7 +9671,7 @@ Seems impossible due to optimizations that QEMU does: PANDA can list memory addresses, so I bet it can also decode the instructions: https://github.com/panda-re/panda/blob/883c85fa35f35e84a323ed3d464ff40030f06bd6/panda/docs/LINE_Censorship.md I wonder why they don't just upstream those things to QEMU's tracing: https://github.com/panda-re/panda/issues/290 -gem5 can do it: <>. +gem5 can do it as shown at: xref:gem5-tracing[xrefstyle=full]. ==== Trace source lines @@ -9934,7 +9934,7 @@ Using text mode is another workaround if you don't need GUI features. == gem5 -Getting started at: <>. +Getting started at: xref:gem5-buildroot-setup[xrefstyle=full]. === gem5 vs QEMU @@ -9961,8 +9961,8 @@ but the approximation is reasonable. + It is used mostly for microarchitecture research purposes: when you are making a new chip technology, you don't really need to specialize enormously to an existing microarchitecture, but rather develop something that will work with a wide range of future architectures. ** runs are deterministic by default, unlike QEMU which has a special <> mode, that requires first playing the content once and then replaying -** gem5 ARM at least appears to implement more low level CPU functionality than QEMU, e.g. QEMU only added EL2 in 2018: https://stackoverflow.com/questions/42824706/qemu-system-aarch64-entering-el1-when-emulating-a53-power-up See also: <> -* disadvantage of gem5: slower than QEMU, see: <> +** gem5 ARM at least appears to implement more low level CPU functionality than QEMU, e.g. QEMU only added EL2 in 2018: https://stackoverflow.com/questions/42824706/qemu-system-aarch64-entering-el1-when-emulating-a53-power-up See also: xref:arm-exception-levels[xrefstyle=full] +* disadvantage of gem5: slower than QEMU, see: xref:benchmark-linux-kernel-boot[xrefstyle=full] + This implies that the user base is much smaller, since no Android devs. + @@ -10072,7 +10072,7 @@ A more naive and simpler to understand approach would be a direct: ./run --arch aarch64 --emulator gem5 --eval 'm5 checkpoint;m5 resetstats;dhrystone 10000;m5 exit' .... -but the problem is that this method does not allow to easily run a different script without running the boot again. The `./gem5.sh` script works around that by using <> as explained further at: <>. +but the problem is that this method does not allow to easily run a different script without running the boot again. The `./gem5.sh` script works around that by using <> as explained further at: xref:gem5-restore-new-script[xrefstyle=full]. Now you can play a fun little game with your friends: @@ -10217,7 +10217,7 @@ A quick `+./run --emulator gem5 -- -h+` leads us to the options: --l3_size=1024 .... -But keep in mind that it only affects benchmark performance of the most detailed CPU types: <> +But keep in mind that it only affects benchmark performance of the most detailed CPU types as shown at: xref:table-gem5-cache-cpu-type[xrefstyle=full]. [[table-gem5-cache-cpu-type]] .gem5 cache support in function of CPU type @@ -10395,7 +10395,7 @@ Buildroot built-in libraries, mostly under Libraries > Other: * libtommath * qhull -There are not yet enabled, but it should be easy to so, see: <> +There are not yet enabled, but it should be easy to so, see: xref:add-new-buildroot-packages[xrefstyle=full] ===== BST vs heap vs hashmap @@ -10463,9 +10463,9 @@ xdg-open bst_vs_heap_vs_hashmap_gem5.tmp.png TODO: the gem5 simulation blows up on a tcmalloc allocation somewhere near 25k elements as of 3fdd83c2c58327d9714fa2347c724b78d7c05e2b + 1, likely linked to the extreme inefficiency of the stats collection? -The cache sizes were chosen to match the host <> to improve the comparison. Ideally we sould also use the same standard library. +The cache sizes were chosen to match the host <> to improve the comparison. Ideally we should also use the same standard library. -Note that this will take a long time, and will produce a humongous ~40Gb stats file due to: <> +Note that this will take a long time, and will produce a humongous ~40Gb stats file as explained at: xref:gem5-only-dump-selected-stats[xrefstyle=full] Sources: @@ -10658,7 +10658,7 @@ parsecmgmt -a run -p splash2x.fmm -i test ====== PARSEC uninstall -If you want to remove PARSEC later, Buildroot doesn't provide an automated package removal mechanism: <>, but the following procedure should be satisfactory: +If you want to remove PARSEC later, Buildroot doesn't provide an automated package removal mechanism as mentioned at: xref:remove-buildroot-packages[xrefstyle=full], but the following procedure should be satisfactory: .... rm -rf \ @@ -10752,11 +10752,11 @@ On a third shell: When you want to break, just do a `Ctrl-C` on GDB shell, and then `continue`. -And we now see the boot messages, and then get a shell. Now try the `./count.sh` procedure described for QEMU: <>. +And we now see the boot messages, and then get a shell. Now try the `./count.sh` procedure described for QEMU at: xref:gdb-step-debug-kernel-post-boot[xrefstyle=full]. ==== gem5 GDB step debug userland process -We are unable to use `gdbserver` because of networking: <> +We are unable to use `gdbserver` because of networking as mentioned at: xref:gem5-host-to-guest-networking[xrefstyle=full] The alternative is to do as in <>. @@ -11301,7 +11301,7 @@ but glibc kernel version checks make init fail with: FATAL: kernel too old .... -because glibc was built to expect a newer Linux kernel: <>. Your choices to sole this are: +because glibc was built to expect a newer Linux kernel as shown at: xref:fatal-kernel-too-old[xrefstyle=full]. Your choices to sole this are: * see if there is a more recent gem5 kernel available, or port your patch of interest to the newest kernel * modify this repo to use <>, which is not hard because of Buildroot @@ -11309,8 +11309,8 @@ because glibc was built to expect a newer Linux kernel: <> It is obviously not possible to understand what they actually do from their commit message, so let's explain them one by one here as we understand them: -* `drm: Add component-aware simple encoder` allows you to see images through VNC: <> -* `gem5: Add support for gem5's extended GIC mode` adds support for more than 8 cores: <> +* `drm: Add component-aware simple encoder` allows you to see images through VNC, see: xref:gem5-graphic-mode[xrefstyle=full] +* `gem5: Add support for gem5's extended GIC mode` adds support for more than 8 cores, see: xref:gem5-arm-full-system-with-more-than-8-cores[xrefstyle=full] Tested on 649d06d6758cefd080d04dc47fd6a5a26a620874 + 1. @@ -11577,7 +11577,7 @@ The price to pay for debuggability is high however: a Linux kernel boot was abou ./run --arch aarch64 --eval 'm5 exit' --emulator gem5 --linux-build-id v4.16 --gem5-build-type debug .... -so you will likely only use this when it is unavoidable. This is also benchmarked at: <> +so you will likely only use this when it is unavoidable. This is also benchmarked at: xref:benchmark-linux-kernel-boot[xrefstyle=full] ==== gem5 clang build @@ -11651,7 +11651,7 @@ https://en.wikipedia.org/wiki/Buildroot[Buildroot] is a set of Make scripts that * GCC * Linux kernel -* C standard library: Buildroot supports several implementations, see: <> +* C standard library: Buildroot supports several implementations, see: xref:libc-choice[xrefstyle=full] * https://en.wikipedia.org/wiki/BusyBox[BusyBox]: provides the shell and basic command line utilities It therefore produces a pristine, blob-less, debuggable setup, where all moving parts are configured to work perfectly together. @@ -11702,7 +11702,7 @@ as explained at: https://buildroot.org/downloads/manual/manual.html#rebuild-pkg The clean is necessary because the source files didn't change, so `make` would just check the timestamps and not build anything. -You will then likely want to make those more permanent with: <> +You will then likely want to make those more permanent as explained at: xref:default-command-line-arguments[xrefstyle=full]. ==== Enable Buildroot compiler optimizations @@ -11726,7 +11726,7 @@ Don't forget to do that if you are <> +* if you already have a full `-O0` build, you can choose to rebuild just your package of interest to save some time as described at: xref:custom-buildroot-configs[xrefstyle=full] + .... ./build-buildroot \ @@ -11742,7 +11742,7 @@ However, this approach might not be representative since calls to an unoptimized + Maybe you can get away with rebuilding libc, but I'm not sure that it will work properly. + -Kernel-wise it should be fine though due to: <> +Kernel-wise it should be fine though as mentioned at: xref:kernel-o0[xrefstyle=full] * <> and rebuild from scratch: + .... @@ -11818,11 +11818,11 @@ with: First, see if you can't get away without actually adding a new package, for example: * if you have a standalone C file with no dependencies besides the C standard library to be compiled with GCC, just add a new file under link:buildroot_packages/sample_package[] and you are done -* if you have a dependency on a library, first check if Buildroot doesn't have a package for it already with `ls buildroot/package`. If yes, just enable that package as explained at: <> +* if you have a dependency on a library, first check if Buildroot doesn't have a package for it already with `ls buildroot/package`. If yes, just enable that package as explained at: xref:custom-buildroot-configs[xrefstyle=full] If none of those methods are flexible enough for you, you can just fork or hack up link:buildroot_packages/sample_package[] the sample package to do what you want. -For how to use that package, see: <>. +For how to use that package, see: xref:buildroot_packages-directory[xrefstyle=full]. Then iterate trying to do what you want and reading the manual until it works: https://buildroot.org/downloads/manual/manual.html @@ -11834,7 +11834,7 @@ Documented at: https://github.com/buildroot/buildroot/blob/2017.08/docs/manual/r Also mentioned at: https://stackoverflow.com/questions/47320800/how-to-clean-only-target-in-buildroot -See this for a sample manual workaround: <>. +See this for a sample manual workaround: xref:parsec-uninstall[xrefstyle=full]. === BR2_TARGET_ROOTFS_EXT2_SIZE @@ -11865,7 +11865,7 @@ Some promising ways to overcome this problem include: * <> TODO benchmark: would gem5 suffer a considerable disk read performance hit due to decompressing SquashFS? * libguestfs: https://serverfault.com/questions/246835/convert-directory-to-qemu-kvm-virtual-disk-image/916697#916697[], in particular http://libguestfs.org/guestfish.1.html#vfs-minimum-size[`vfs-minimum-size`] -* use methods described at: <> instead of putting builds on the root filesystem +* use methods described at: xref:gem5-restore-new-script[xrefstyle=full] instead of putting builds on the root filesystem Bibliography: https://stackoverflow.com/questions/49211241/is-there-a-way-to-automatically-detect-the-minimum-required-br2-target-rootfs-ex @@ -11952,7 +11952,7 @@ git -C "$(./getvar qemu_source_dir)" checkout - Then, you will also want to do a <> to pinpoint the exact commit to blame, and CC that developer. -Finally, give the images you used save upstream developpers time: <>. +Finally, give the images you used save upstream developers' time as shown at: xref:release-zip[xrefstyle=full]. For Buildroot problems, you should wither provide the config you have: @@ -11986,19 +11986,19 @@ The full list of unsupported packages can be found by grepping the Buildroot sou git -C "$(./getvar buildroot_source_dir)" grep 'depends on BR2_TOOLCHAIN_USES_GLIBC' .... -One "downside" of glibc is that it exercises much more kernel functionality on its more bloated pre-main init, which breaks user mode C hello worlds more often, see: <>. I quote "downside" because glibc is actually exposing emulator bugs which we should actually go and fix. +One "downside" of glibc is that it exercises much more kernel functionality on its more bloated pre-main init, which breaks user mode C hello worlds more often, see: xref:user-mode-simulation-with-glibc[xrefstyle=full]. I quote "downside" because glibc is actually exposing emulator bugs which we should actually go and fix. == Userland content This section contains userland content, such as <>, <> and <> examples. -Getting started at: <> +Getting started at: xref:userland-setup[xrefstyle=full] -Userland assembly content is located at: <>. It was split from this section basically becase we were hitting the HTML `h6` limit, stupid web :-) +Userland assembly content is located at: xref:userland-assembly[xrefstyle=full]. It was split from this section basically because we were hitting the HTML `h6` limit, stupid web :-) This content makes up the bulk of the link:userland/[] directory. -The quickest way to run the arch agnostic examples, which comprise the majority of the examples, is natively with: <> +The quickest way to run the arch agnostic examples, which comprise the majority of the examples, is natively as shown at: xref:userland-setup-getting-started-natively[xrefstyle=full] This section was originally moved in here from: https://github.com/cirosantilli/cpp-cheat @@ -12153,14 +12153,14 @@ ISA specifics are covered at: ** link:userland/arch/arm/[] ** link:userland/arch/aarch64/[] -Like other userland programs, these programs can be run as explained at: <>. +Like other userland programs, these programs can be run as explained at: xref:userland-setup[xrefstyle=full]. As a quick reminder, the fastest setups to get started are: * <> if your host can run the examples, e.g. x86 example on an x86 host: * <> otherwise -However, as usual, it is saner to build your toolchain as explained at: <>. +However, as usual, it is saner to build your toolchain as explained at: xref:qemu-user-mode-getting-started[xrefstyle=full]. The first examples you should look into are: @@ -12175,7 +12175,7 @@ The first examples you should look into are: * addressing modes ** <> ** <> -* registers: <> +* registers, see: xref:assembly-registers[xrefstyle=full] * jumping: ** <> ** <> @@ -12237,7 +12237,7 @@ Other infrastructure sanity checks that you might want to look into include: After seeing an <>, you need to learn the general registers: -* x86: <> +* x86, see: xref:x86-registers[xrefstyle=full] * arm ** link:userland/arch/arm/registers.S[] * aarch64 @@ -12353,7 +12353,7 @@ Bibliography: https://stackoverflow.com/questions/1389712/getting-started-with-i Fused multiply add: -* x86: <> +* x86: xref:x86-fma[xrefstyle=full] Bibliography: @@ -12379,11 +12379,11 @@ Most ISAs are divided into a system and userland part, and to running the system One big difference between both is that we can run userland assembly on <>, which is easier to get running and debug. -In particular, most userland assembly examples link to the C standard library: <>. +In particular, most userland assembly examples link to the C standard library, see: xref:userland-assembly-c-standard-library[xrefstyle=full]. Userland assembly is generally simpler, and a pre-requisite for <>. -System-land assembly cheats will be put under: <>. +System-land assembly cheats will be put under: xref:baremetal-setup[xrefstyle=full]. === Userland assembly C standard library @@ -12405,7 +12405,7 @@ The C standard library infrastructure is implemented in the common userland / ba Unlike most our other assembly examples, which use the C standard library for portability, examples under `freestanding/` directories don't link to the C standard library. -As a result, those examples cannot do IO portably, and so they make raw system calls and only be run on one given OS, e.g. Linux: <>. +As a result, those examples cannot do IO portably, and so they make raw system calls and only be run on one given OS, e.g. <>. Such executables are called freestanding because they don't execute the glibc initialization code, but rather start directly on our custom hand written assembly. @@ -12448,7 +12448,7 @@ In x86, makes it possible to access variables not exposed with the one letter re In arm, it is the only way to achieve this effect: https://stackoverflow.com/questions/10831792/how-to-use-specific-register-in-arm-inline-assembler -This feature notably useful for making system calls from C, see: <>. +This feature notably useful for making system calls from C, see: xref:linux-system-calls[xrefstyle=full]. Documentation: https://gcc.gnu.org/onlinedocs/gcc-4.4.2/gcc/Explicit-Reg-Vars.html @@ -12577,7 +12577,7 @@ Questions about the C inline assembly examples: === Linux calling conventions -Summary: <> +A summary of results is shown at: xref:table-linux-calling-conventions[xrefstyle=full]. [[table-linux-calling-conventions]] .Summary of Linux calling conventions for several architectures @@ -12680,7 +12680,7 @@ Let's see how many bytes go into each data type: * link:userland/arch/arm/gas_data_sizes.S[] * link:userland/arch/aarch64/gas_data_sizes.S[] -Conclusion: <> +The results are shown at: xref:table-gas-data-sizes[xrefstyle=full]. [[table-gas-data-sizes]] .Summary of GNU GAS assembler data sizes @@ -12743,7 +12743,7 @@ Some of the differences include: * many mnemonics changed: ** most of them are condition code position changes, e.g. ANDSEQ vs ANDEQS: https://stackoverflow.com/questions/51184921/wierd-gcc-behaviour-with-arm-assembler-andseq-instruction ** but there are some more drastic ones, e.g. SWI vs <>: https://stackoverflow.com/questions/8459279/are-arm-instructuons-swi-and-svc-exactly-same-thing/54078731#54078731 -* cannot have implicit destination with shift, see: <> +* cannot have implicit destination with shift, see: xref:arm-shift-suffixes[xrefstyle=full] ===== GNU GAS assembler ARM .n and .w suffixes @@ -12770,7 +12770,7 @@ fails because cpp treats string and char literals magically. === NOP instructions * x86: link:userland/arch/x86_64/nop.S[NOP] -* ARM: <> +* ARM: xref:arm-nop-instruction[xrefstyle=full] No OPeration. @@ -12780,7 +12780,7 @@ Applications: https://stackoverflow.com/questions/234906/whats-the-purpose-of-th == x86 userland assembly -Arch agnostic infrastructure getting started at: <>. +Arch agnostic infrastructure getting started at: xref:userland-assembly[xrefstyle=full]. === x86 registers @@ -12939,7 +12939,7 @@ Has some Intel vs AT&T name overload hell: * https://stackoverflow.com/questions/17170388/trying-to-understand-the-assembly-instruction-cltd-on-x86/50315201#50315201 * https://sourceware.org/binutils/docs/as/i386_002dMnemonics.html -GNU GAS accepts both syntaxes: <> +GNU GAS accepts both syntaxes, see: xref:table-cqto-cltq[xrefstyle=full]. [[table-cqto-cltq]] .CQTO and CLTQ family Intel vs AT&T @@ -13008,7 +13008,7 @@ Not necessarily faster because of branch prediction. This is partly why the ternary `?` C operator exists: https://stackoverflow.com/questions/3565368/ternary-operator-vs-if-else -It is interesting to compare this with ARMv7 conditional executaion: which is available for all instructions: <> +It is interesting to compare this with ARMv7 conditional execution: which is available for all instructions, as shown at: xref:arm-conditional-execution[xrefstyle=full]. === x86 binary arithmetic instructions @@ -13214,7 +13214,7 @@ which restores RSP and RBP to the values they had before the prologue. <> 5.1.13 "Miscellaneous Instructions" -NOP: <> +NOP: xref:nop-instructions[xrefstyle=full] === x86 random number generator instructions @@ -13324,7 +13324,7 @@ In GCC, you can choose between them with `-mfpmath=`. === x86 SIMD -Parent section: <> +Parent section: xref:simd-assembly[xrefstyle=full] History: @@ -13353,7 +13353,7 @@ History: <> 5.5.1.2 "SSE Packed Arithmetic Instructions" -* link:userland/arch/x86_64/addpd.S[]: ADDPS, ADDPD: good first instruction to learn SIMD: <> +* link:userland/arch/x86_64/addpd.S[]: ADDPS, ADDPD: good first instruction to learn <>. ===== x86 SSE conversion instructions @@ -13369,7 +13369,7 @@ History: link:userland/arch/x86_64/paddq.S[]: PADDQ, PADDL, PADDW, PADDB -Good first instruction to learn SIMD: <> +Good first instruction to learn <>. [[x86-fma]] ==== x86 fused multiply add (FMA) @@ -13516,7 +13516,7 @@ Model specific extensions: http://web.archive.org/web/20190606075325/https://sof == ARM userland assembly -Arch general getting started at: <>. +Arch general getting started at: xref:userland-assembly[xrefstyle=full]. Instructions here loosely grouped based on that of the <> Chapter A4 "The Instruction Sets". @@ -13579,8 +13579,8 @@ A great summary of differences can be found at: https://en.wikipedia.org/wiki/AR Some random ones: -* aarch32 has two encodings: Thumb and ARM: <> -* in ARMv8, the stack can be enforced to 16-byte alignment: <> +* aarch32 has two encodings: Thumb and ARM: xref:arm-instruction-encodings[xrefstyle=full] +* in ARMv8, the stack can be enforced to 16-byte alignment: xref:armv8-aarch64-stack-alignment[xrefstyle=full] ==== Free ARM implementations @@ -13799,7 +13799,7 @@ The current ARM / Thumb mode is encoded in the least significant bit of lr. ===== ARM BX instruction -See: <> +See: xref:arm-thumb-encoding[xrefstyle=full] ===== ARMv8 aarch64 ret instruction @@ -13836,7 +13836,10 @@ The list of all extensions is documented at <> "A8.3 Conditional execut === ARM load and store instructions -In ARM, there are only two instruction families that do memory access: <> to load and <> to store. +In ARM, there are only two instruction families that do memory access: + +* <> to load from memory to registers +* <> to store from registers to memory Everything else works on register and immediates. @@ -14087,7 +14090,7 @@ Move the lower bits of source register into any position in the destination: Move an immediate to a register, or a register to another register. -Cannot load from or to memory, since only the LDR and STR instruction families can do that in ARM: <> +Cannot load from or to memory, since only the LDR and STR instruction families can do that in ARM as mentioned at: xref:arm-load-and-store-instructions[xrefstyle=full]. Example: link:userland/arch/arm/mov.S[] @@ -14179,13 +14182,13 @@ More details: https://stackoverflow.com/questions/41906688/what-are-the-semantic ===== ARM ADRL instruction -See: <>. +See: xref:arm-adr-instruction[xrefstyle=full]. === ARM miscellaneous instructions ==== ARM NOP instruction -Parent section: <> +Parent section: xref:nop-instructions[xrefstyle=full] There are a few different ways to encode NOP, notably MOV a register into itself, and a dedicated miscellaneous instruction. @@ -14210,7 +14213,7 @@ Why GNU GAS 2.29 does not have a mnemonic for it in A64 because it is very recen === ARM SIMD -Parent section: <> +Parent section: xref:simd-assembly[xrefstyle=full] ==== ARM VFP @@ -14267,8 +14270,8 @@ And you can't access the higher bytes at D16 or greater with Sn. ===== ARM VADD instruction -* link:userland/arch/arm/vadd_scalar.S[]: see also: <> -* link:userland/arch/arm/vadd_vector.S[]: see also: <> +* link:userland/arch/arm/vadd_scalar.S[]: see also: xref:floating-point-assembly[xrefstyle=full] +* link:userland/arch/arm/vadd_vector.S[]: see also: xref:simd-assembly[xrefstyle=full] ===== ARM VCVT instruction @@ -14320,7 +14323,7 @@ The <> specifies floating point and SIMD support in the main architectu The feature is often refered to simply as "SIMD&FP" throughout the manual. -The Linux kernel shows `/proc/cpuinfo` compatibility as `neon`, which is yet another intermediate name that came up at some point: <> +The Linux kernel shows `/proc/cpuinfo` compatibility as `neon`, which is yet another intermediate name that came up at some point, see: xref:arm-neon[xrefstyle=full]. Vs <>: https://stackoverflow.com/questions/4097034/arm-cortex-a8-whats-the-difference-between-vfp-and-neon @@ -14382,16 +14385,16 @@ Notice how Sn is very different between v7 and v8! In v7 it goes across Dn, and link:userland/arch/aarch64/add_vector.S[] -Good first instruction to learn SIMD: <> +Good first instruction to learn SIMD: <>. ===== ARMv8 aarch64 FADD instruction -* link:userland/arch/aarch64/fadd_vector.S[]: see also: <> -* link:userland/arch/aarch64/fadd_scalar.S[]: see also: <> +* link:userland/arch/aarch64/fadd_vector.S[]: see also: xref:simd-assembly[xrefstyle=full] +* link:userland/arch/aarch64/fadd_scalar.S[]: see also: xref:floating-point-assembly[xrefstyle=full] ====== ARM FADD vs VADD -It is very confusing, but FADDS and FADDD in Aarch32 are <> for `vadd.f32` and `vadd.f64` which we use in this tutorial: <> +It is very confusing, but FADDS and FADDD in Aarch32 are <> for `vadd.f32` and `vadd.f64` which we use in this tutorial, see: xref:arm-vadd-instruction[xrefstyle=full] The same goes for most ARMv7 mnemonics: `f*` is old, and `v*` is the newer better syntax. @@ -14399,7 +14402,7 @@ But then, in ARMv8, they decided to use <> as th Also keep in mind that fused multiply add is FMADD. -Examples at: <> +Examples at: xref:simd-assembly[xrefstyle=full] ===== ARMv8 aarch64 ld2 instruction @@ -14590,11 +14593,11 @@ Examples: == Baremetal -Getting started at: <> +Getting started at: xref:baremetal-setup[xrefstyle=full] === Baremetal GDB step debug -GDB step debug works on baremetal exactly as it does on the Linux kernel: <>. +GDB step debug works on baremetal exactly as it does on the Linux kernel, which is described at: xref:gdb[xrefstyle=full]. Except that is is even cooler here since we can easily control and understand every single instruction that is being run! @@ -14657,7 +14660,7 @@ Out simplistic bootloaders basically setup up just enough system state to allow The most important things that we setup in the bootloaders are: * the stack pointer -* NEON: <> +* NEON: xref:aarch64-baremetal-neon-setup[xrefstyle=full] * TODO: we don't do this currently but maybe we should setup BSS The C functions that become available as a result are: @@ -15131,7 +15134,7 @@ The vector table format is described on <> Table D1-7 "Vector offsets f A good representation of the format of the vector table can also be found at <> Table 10-2 "Vector table offsets from vector table base address". -The first part of the table contains: <> +The first part of the table contains: xref:table-armv8-vector-handlers[xrefstyle=full]. [[table-armv8-vector-handlers]] .Summary of ARMv8 vector handlers @@ -15185,7 +15188,7 @@ Bibliography: Exception Syndrome Register. -See example at: <> +See example at: xref:arm-svc-instruction[xrefstyle=full] Documentation: <> D12.2.36 "ESR_EL1, Exception Syndrome Register (EL1)". @@ -15193,7 +15196,7 @@ Documentation: <> D12.2.36 "ESR_EL1, Exception Syndrome Register (EL Exception Link Register. -See example at: <> +See the example at: xref:arm-svc-instruction[xrefstyle=full] ==== ARM multicore @@ -15241,7 +15244,7 @@ Exiting @ tick 36500 because m5_exit instruction encountered since gem5 is able to detect when nothing will ever happen, and exits. -When GDB step debugging, switch between cores with the usual `thread` commands, see also: <>. +When GDB step debugging, switch between cores with the usual `thread` commands, see also: xref:gdb-step-debug-multicore-userland[xrefstyle=full]. Bibliography: https://stackoverflow.com/questions/980999/what-does-multicore-assembly-language-look-like/33651438#33651438 @@ -15373,7 +15376,7 @@ Page table formats are described at <> D5.3.1 "VMSAv8-64 translation ==== ARM baremetal bibliography -First, also consider the userland bibliography: <>. +First, also consider the userland bibliography: xref:arm-assembly-bibliography[xrefstyle=full]. The most useful ARM baremetal example sets we've seen so far are: @@ -15583,7 +15586,7 @@ Baremetal tests work exactly like <>, except that you have to a In baremetal, we detect if tests failed by parsing logs for the <>. -See: <> for more useful testing tips. +See: xref:test-this-repo[xrefstyle=full] for more useful testing tips. == Android @@ -15808,7 +15811,7 @@ Tested on: `8.1.0_r60`. === Android init -For Linux in general, see: <>. +For Linux in general, see: xref:init[xrefstyle=full]. The `/init` executable interprets the `/init.rc` files, which is in a custom Android init system language: https://android.googlesource.com/platform/system/core/+/ee0e63f71d90537bb0570e77aa8a699cc222cfaf/init/README.md @@ -16507,7 +16510,7 @@ Like <>, you will need to pass the `-n` option to anything tha ./run-gdb --run-id 1 .... -To run multiple gem5 checkouts, see: <>. +To run multiple gem5 checkouts, see: xref:gem5-worktree[xrefstyle=full]. Implementation note: we create multiple namespaces for two things: @@ -16561,7 +16564,7 @@ The `--linux-build-id` option should be passed to all scripts that support it, m ./run-gdb --linux-build-id v4.16 ..... -To run both kernels simultaneously, one on each QEMU instance, see: <>. +To run both kernels simultaneously, one on each QEMU instance, see: xref:simultaneous-runs[xrefstyle=full]. ==== QEMU build variants @@ -16834,7 +16837,7 @@ This directory is copied into the target filesystem by: Source: link:copy-overlay[] -Build Buildroot is required for the same reason as described at: <>. +Build Buildroot is required for the same reason as described at: xref:your-first-kernel-module-hack[xrefstyle=full]. However, since the link:rootfs_overlay[] directory does not require compilation, unlike say <>, we also make it <<9p>> available to the guest directly even without `./copy-overlay` at: @@ -16979,7 +16982,7 @@ Basically just boots and runs: link:rootfs_overlay/lkmc/test_all.sh[] Failure is detected by looking for the <> -Most userland programs that don't rely on kernel modules can also be tested in user mode simulation as explained at: <>. +Most userland programs that don't rely on kernel modules can also be tested in user mode simulation as explained at: xref:user-mode-tests[xrefstyle=full]. ===== GDB tests @@ -17038,7 +17041,7 @@ For other arch / emulator combinations, we know how to do it: * aarch64: aarch64 semihosting supports exit status * gem5: <> works on all archs -* user mode: QEMU forwards exit status, gem5 we do some log parsing: <> +* user mode: QEMU forwards exit status, for gem5 we do some log parsing as described at: xref:gem5-syscall-emulation-exit-status[xrefstyle=full] Since we can't do it for QEMU arm, the only reliable solution is to just parse the guest serial output for a magic failure string to check if tests failed. @@ -17129,7 +17132,7 @@ You should also test that the Internet works: When updating the Linux kernel, QEMU and gem5, things sometimes break. -However, for many types of crashes, it is trivial to bisect down to the offending commit, in particular because we can make QEMU and gem5 exit with status 1 on kernel panic: <>. +However, for many types of crashes, it is trivial to bisect down to the offending commit, in particular because we can make QEMU and gem5 exit with status 1 on kernel panic as mentioned at: xref:exit-emulator-on-panic[xrefstyle=full]. For example, when updating from QEMU `v2.12.0` to `v3.0.0-rc3`, the Linux kernel boot started to panic for `arm`. @@ -17238,7 +17241,7 @@ mv out out.bak ./build-test --size 3 && ./test --size 3 .... -The `./build-test` command builds a superset of what will be downloaded which also tests other things we would like to be working on the release. For the minimal build to generate the files to be uploaded, see: <> +The `./build-test` command builds a superset of what will be downloaded which also tests other things we would like to be working on the release. For the minimal build to generate the files to be uploaded, see: xref:release-zip[xrefstyle=full] The clean build is necessary as it generates clean images since <> @@ -17379,7 +17382,7 @@ The trade-offs between the different <> are basically a * portability: does it work on a Windows host? Could it ever? * accuracy: how accurate does the simulation represent real hardware? * compatibility: how likely is is that all the components will work well together: emulator, compiler, kernel, standard library, ... -* guest software availability: how wide is your choice of easily installed guest software packages? See also: <> +* guest software availability: how wide is your choice of easily installed guest software packages? See also: xref:linux-distro-choice[xrefstyle=full] ==== Resource tradeoff guidelines @@ -17400,11 +17403,11 @@ Runtime basically just comes down to how we configure the Linux kernel, since in + One possibility we could play with is to build loadable modules instead of built-in modules to reduce runtime, but make it easier to get started with the modules. -In order to learn how to measure some of those aspects, see: <> +In order to learn how to measure some of those aspects, see: xref:benchmark-this-repo[xrefstyle=full]. ==== Linux distro choice -We haven't found the ultimate distro yet, here is a summary table of trade-offs that we care about: <> +We haven't found the ultimate distro yet, here is a summary table of trade-offs that we care about: xref:table-lkmc-linux-distro-comparison[xrefstyle=full]. [[table-lkmc-linux-distro-comparison]] .Comparison of Linux distros for usage in this repository