3rd-party/linux-kernel-module-cheat
1
0
Fork 0
mirror of https://github.com/cirosantilli/linux-kernel-module-cheat.git synced 2026-01-25 11:11:35 +01:00
Code Issues Releases Wiki Activity

a06672a20d

Browse Source
This commit is contained in:
Ciro Santilli 六四事件 法轮功
2019-11-08 00:00:00 +00:00
parent b0485c96db
commit 650a0bfd72
1 changed files with 168 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

317
index.html
View File

@@ -1771,122 +1771,123 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
</ul>
</li>
<li><a href="#xephyr">30. Xephyr</a></li>
<li><a href="#about-this-repo">31. About this repo</a>
<li><a href="#compilers">31. Compilers</a></li>
<li><a href="#about-this-repo">32. About this repo</a>
<ul class="sectlevel2">
<li><a href="#supported-hosts">31.1. Supported hosts</a></li>
<li><a href="#common-build-issues">31.2. Common build issues</a>
<li><a href="#supported-hosts">32.1. Supported hosts</a></li>
<li><a href="#common-build-issues">32.2. Common build issues</a>
<ul class="sectlevel3">
<li><a href="#put-source-uris-in-sources">31.2.1. You must put some 'source' URIs in your sources.list</a></li>
<li><a href="#build-from-downloaded-source-zip-files">31.2.2. Build from downloaded source zip files</a></li>
<li><a href="#put-source-uris-in-sources">32.2.1. You must put some 'source' URIs in your sources.list</a></li>
<li><a href="#build-from-downloaded-source-zip-files">32.2.2. Build from downloaded source zip files</a></li>
</ul>
</li>
<li><a href="#run-command-after-boot">31.3. Run command after boot</a></li>
<li><a href="#default-command-line-arguments">31.4. Default command line arguments</a></li>
<li><a href="#documentation">31.5. Documentation</a>
<li><a href="#run-command-after-boot">32.3. Run command after boot</a></li>
<li><a href="#default-command-line-arguments">32.4. Default command line arguments</a></li>
<li><a href="#documentation">32.5. Documentation</a>
<ul class="sectlevel3">
<li><a href="#documentation-verification">31.5.1. Documentation verification</a>
<li><a href="#documentation-verification">32.5.1. Documentation verification</a>
<ul class="sectlevel4">
<li><a href="#asciidoctor-extract-link-targets">31.5.1.1. asciidoctor/extract-link-targets</a></li>
<li><a href="#asciidoctor-extract-header-ids">31.5.1.2. asciidoctor/extract-header-ids</a></li>
<li><a href="#asciidoctor-extract-link-targets">32.5.1.1. asciidoctor/extract-link-targets</a></li>
<li><a href="#asciidoctor-extract-header-ids">32.5.1.2. asciidoctor/extract-header-ids</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#asciidoctor-link-target-up-rb">31.6. asciidoctor/link-target-up.rb</a>
<li><a href="#asciidoctor-link-target-up-rb">32.6. asciidoctor/link-target-up.rb</a>
<ul class="sectlevel3">
<li><a href="#github-pages">31.6.1. GitHub pages</a></li>
<li><a href="#github-pages">32.6.1. GitHub pages</a></li>
</ul>
</li>
<li><a href="#clean-the-build">31.7. Clean the build</a></li>
<li><a href="#ccache">31.8. ccache</a></li>
<li><a href="#rebuild-buildroot-while-running">31.9. Rebuild Buildroot while running</a></li>
<li><a href="#simultaneous-runs">31.10. Simultaneous runs</a></li>
<li><a href="#build-variants">31.11. Build variants</a>
<li><a href="#clean-the-build">32.7. Clean the build</a></li>
<li><a href="#ccache">32.8. ccache</a></li>
<li><a href="#rebuild-buildroot-while-running">32.9. Rebuild Buildroot while running</a></li>
<li><a href="#simultaneous-runs">32.10. Simultaneous runs</a></li>
<li><a href="#build-variants">32.11. Build variants</a>
<ul class="sectlevel3">
<li><a href="#linux-kernel-build-variants">31.11.1. Linux kernel build variants</a></li>
<li><a href="#qemu-build-variants">31.11.2. QEMU build variants</a></li>
<li><a href="#gem5-build-variants">31.11.3. gem5 build variants</a>
<li><a href="#linux-kernel-build-variants">32.11.1. Linux kernel build variants</a></li>
<li><a href="#qemu-build-variants">32.11.2. QEMU build variants</a></li>
<li><a href="#gem5-build-variants">32.11.3. gem5 build variants</a>
<ul class="sectlevel4">
<li><a href="#gem5-worktree">31.11.3.1. gem5 worktree</a></li>
<li><a href="#gem5-private-source-trees">31.11.3.2. gem5 private source trees</a></li>
<li><a href="#gem5-worktree">32.11.3.1. gem5 worktree</a></li>
<li><a href="#gem5-private-source-trees">32.11.3.2. gem5 private source trees</a></li>
</ul>
</li>
<li><a href="#buildroot-build-variants">31.11.4. Buildroot build variants</a></li>
<li><a href="#buildroot-build-variants">32.11.4. Buildroot build variants</a></li>
</ul>
</li>
<li><a href="#directory-structure">31.12. Directory structure</a>
<li><a href="#directory-structure">32.12. Directory structure</a>
<ul class="sectlevel3">
<li><a href="#lkmc-directory">31.12.1. lkmc directory</a>
<li><a href="#lkmc-directory">32.12.1. lkmc directory</a>
<ul class="sectlevel4">
<li><a href="#userland-objects-vs-header-only">31.12.1.1. Userland objects vs header-only</a></li>
<li><a href="#userland-objects-vs-header-only">32.12.1.1. Userland objects vs header-only</a></li>
</ul>
</li>
<li><a href="#buildroot_packages-directory">31.12.2. buildroot_packages directory</a>
<li><a href="#buildroot_packages-directory">32.12.2. buildroot_packages directory</a>
<ul class="sectlevel4">
<li><a href="#kernel_modules-buildroot-package">31.12.2.1. kernel_modules buildroot package</a></li>
<li><a href="#kernel_modules-buildroot-package">32.12.2.1. kernel_modules buildroot package</a></li>
</ul>
</li>
<li><a href="#patches-directory">31.12.3. patches directory</a>
<li><a href="#patches-directory">32.12.3. patches directory</a>
<ul class="sectlevel4">
<li><a href="#patches-global-directory">31.12.3.1. patches/global directory</a></li>
<li><a href="#patches-manual-directory">31.12.3.2. patches/manual directory</a></li>
<li><a href="#patches-global-directory">32.12.3.1. patches/global directory</a></li>
<li><a href="#patches-manual-directory">32.12.3.2. patches/manual directory</a></li>
</ul>
</li>
<li><a href="#rootfs_overlay">31.12.4. rootfs_overlay</a>
<li><a href="#rootfs_overlay">32.12.4. rootfs_overlay</a>
<ul class="sectlevel4">
<li><a href="#out_rootfs_overlay_dir">31.12.4.1. out_rootfs_overlay_dir</a></li>
<li><a href="#out_rootfs_overlay_dir">32.12.4.1. out_rootfs_overlay_dir</a></li>
</ul>
</li>
<li><a href="#lkmc-c">31.12.5. lkmc.c</a></li>
<li><a href="#rand_check-out">31.12.6. rand_check.out</a></li>
<li><a href="#lkmc_home">31.12.7. lkmc_home</a></li>
<li><a href="#lkmc-c">32.12.5. lkmc.c</a></li>
<li><a href="#rand_check-out">32.12.6. rand_check.out</a></li>
<li><a href="#lkmc_home">32.12.7. lkmc_home</a></li>
</ul>
</li>
<li><a href="#test-this-repo">31.13. Test this repo</a>
<li><a href="#test-this-repo">32.13. Test this repo</a>
<ul class="sectlevel3">
<li><a href="#automated-tests">31.13.1. Automated tests</a>
<li><a href="#automated-tests">32.13.1. Automated tests</a>
<ul class="sectlevel4">
<li><a href="#test-arch-and-emulator-selection">31.13.1.1. Test arch and emulator selection</a></li>
<li><a href="#quit-on-fail">31.13.1.2. Quit on fail</a></li>
<li><a href="#test-userland-in-full-system">31.13.1.3. Test userland in full system</a></li>
<li><a href="#gdb-tests">31.13.1.4. GDB tests</a></li>
<li><a href="#magic-failure-string">31.13.1.5. Magic failure string</a></li>
<li><a href="#test-arch-and-emulator-selection">32.13.1.1. Test arch and emulator selection</a></li>
<li><a href="#quit-on-fail">32.13.1.2. Quit on fail</a></li>
<li><a href="#test-userland-in-full-system">32.13.1.3. Test userland in full system</a></li>
<li><a href="#gdb-tests">32.13.1.4. GDB tests</a></li>
<li><a href="#magic-failure-string">32.13.1.5. Magic failure string</a></li>
</ul>
</li>
<li><a href="#non-automated-tests">31.13.2. Non-automated tests</a>
<li><a href="#non-automated-tests">32.13.2. Non-automated tests</a>
<ul class="sectlevel4">
<li><a href="#test-gdb-linux-kernel">31.13.2.1. Test GDB Linux kernel</a></li>
<li><a href="#test-the-internet">31.13.2.2. Test the Internet</a></li>
<li><a href="#cli-script-tests">31.13.2.3. CLI script tests</a></li>
<li><a href="#test-gdb-linux-kernel">32.13.2.1. Test GDB Linux kernel</a></li>
<li><a href="#test-the-internet">32.13.2.2. Test the Internet</a></li>
<li><a href="#cli-script-tests">32.13.2.3. CLI script tests</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#bisection">31.14. Bisection</a></li>
<li><a href="#path-properties">31.15. path_properties</a></li>
<li><a href="#update-a-forked-submodule">31.16. Update a forked submodule</a></li>
<li><a href="#release">31.17. Release</a>
<li><a href="#bisection">32.14. Bisection</a></li>
<li><a href="#path-properties">32.15. path_properties</a></li>
<li><a href="#update-a-forked-submodule">32.16. Update a forked submodule</a></li>
<li><a href="#release">32.17. Release</a>
<ul class="sectlevel3">
<li><a href="#release-procedure">31.17.1. Release procedure</a></li>
<li><a href="#release-zip">31.17.2. release-zip</a></li>
<li><a href="#release-upload">31.17.3. release-upload</a></li>
<li><a href="#release-procedure">32.17.1. Release procedure</a></li>
<li><a href="#release-zip">32.17.2. release-zip</a></li>
<li><a href="#release-upload">32.17.3. release-upload</a></li>
</ul>
</li>
<li><a href="#design-rationale">31.18. Design rationale</a>
<li><a href="#design-rationale">32.18. Design rationale</a>
<ul class="sectlevel3">
<li><a href="#design-goals">31.18.1. Design goals</a></li>
<li><a href="#setup-trade-offs">31.18.2. Setup trade-offs</a></li>
<li><a href="#resource-tradeoff-guidelines">31.18.3. Resource tradeoff guidelines</a></li>
<li><a href="#linux-distro-choice">31.18.4. Linux distro choice</a></li>
<li><a href="#design-goals">32.18.1. Design goals</a></li>
<li><a href="#setup-trade-offs">32.18.2. Setup trade-offs</a></li>
<li><a href="#resource-tradeoff-guidelines">32.18.3. Resource tradeoff guidelines</a></li>
<li><a href="#linux-distro-choice">32.18.4. Linux distro choice</a></li>
</ul>
</li>
<li><a href="#soft-topics">31.19. Soft topics</a>
<li><a href="#soft-topics">32.19. Soft topics</a>
<ul class="sectlevel3">
<li><a href="#fairy-tale">31.19.1. Fairy tale</a></li>
<li><a href="#should-you-waste-your-life-with-systems-programming">31.19.2. Should you waste your life with systems programming?</a></li>
<li><a href="#fairy-tale">32.19.1. Fairy tale</a></li>
<li><a href="#should-you-waste-your-life-with-systems-programming">32.19.2. Should you waste your life with systems programming?</a></li>
</ul>
</li>
<li><a href="#bibliography">31.20. Bibliography</a></li>
<li><a href="#bibliography">32.20. Bibliography</a></li>
</ul>
</li>
</ul>
@@ -1903,14 +1904,14 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
<p>If you don&#8217;t know which one to go for, start with <a href="#qemu-buildroot-setup-getting-started">QEMU Buildroot setup getting started</a>.</p>
</div>
<div class="paragraph">
<p>Design goals of this project are documented at: <a href="#design-goals">Section 31.18.1, &#8220;Design goals&#8221;</a>.</p>
<p>Design goals of this project are documented at: <a href="#design-goals">Section 32.18.1, &#8220;Design goals&#8221;</a>.</p>
</div>
<div class="sect2">
<h3 id="qemu-buildroot-setup"><a class="anchor" href="#qemu-buildroot-setup"></a><a class="link" href="#qemu-buildroot-setup">1.1. QEMU Buildroot setup</a></h3>
<div class="sect3">
<h4 id="qemu-buildroot-setup-getting-started"><a class="anchor" href="#qemu-buildroot-setup-getting-started"></a><a class="link" href="#qemu-buildroot-setup-getting-started">1.1.1. QEMU Buildroot setup getting started</a></h4>
<div class="paragraph">
<p>This setup has been mostly tested on Ubuntu. For other host operating systems see: <a href="#supported-hosts">Section 31.1, &#8220;Supported hosts&#8221;</a>. For greater stability, consider using the <a href="#release-procedure">latest release</a> instead of master: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/releases" class="bare">https://github.com/cirosantilli/linux-kernel-module-cheat/releases</a></p>
<p>This setup has been mostly tested on Ubuntu. For other host operating systems see: <a href="#supported-hosts">Section 32.1, &#8220;Supported hosts&#8221;</a>. For greater stability, consider using the <a href="#release-procedure">latest release</a> instead of master: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/releases" class="bare">https://github.com/cirosantilli/linux-kernel-module-cheat/releases</a></p>
</div>
<div class="paragraph">
<p>Reserve 12Gb of disk and run:</p>
@@ -1927,7 +1928,7 @@ cd linux-kernel-module-cheat
<p>You don&#8217;t need to clone recursively even though we have <code>.git</code> submodules: <code>download-dependencies</code> fetches just the submodules that you need for this build to save time.</p>
</div>
<div class="paragraph">
<p>If something goes wrong, see: <a href="#common-build-issues">Section 31.2, &#8220;Common build issues&#8221;</a> and use our issue tracker: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/issues" class="bare">https://github.com/cirosantilli/linux-kernel-module-cheat/issues</a></p>
<p>If something goes wrong, see: <a href="#common-build-issues">Section 32.2, &#8220;Common build issues&#8221;</a> and use our issue tracker: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/issues" class="bare">https://github.com/cirosantilli/linux-kernel-module-cheat/issues</a></p>
</div>
<div class="paragraph">
<p>The initial build will take a while (30 minutes to 2 hours) to clone and build, see <a href="#benchmark-builds">Benchmark builds</a> for more details.</p>
@@ -2010,7 +2011,7 @@ hello2 cleanup</pre>
</div>
</div>
<div class="paragraph">
<p>To avoid typing <code>--arch aarch64</code> many times, you can set the default arch as explained at: <a href="#default-command-line-arguments">Section 31.4, &#8220;Default command line arguments&#8221;</a></p>
<p>To avoid typing <code>--arch aarch64</code> many times, you can set the default arch as explained at: <a href="#default-command-line-arguments">Section 32.4, &#8220;Default command line arguments&#8221;</a></p>
</div>
<div class="paragraph">
<p>I now urge you to read the following sections which contain widely applicable information:</p>
@@ -2314,7 +2315,7 @@ hello /root/.profile
<p>If you really want to develop semiconductors, your only choice is to join an university or a semiconductor company that has the EDA licenses.</p>
</div>
<div class="paragraph">
<p>See also: <a href="#should-you-waste-your-life-with-systems-programming">Section 31.19.2, &#8220;Should you waste your life with systems programming?&#8221;</a>.</p>
<p>See also: <a href="#should-you-waste-your-life-with-systems-programming">Section 32.19.2, &#8220;Should you waste your life with systems programming?&#8221;</a>.</p>
</div>
<div class="paragraph">
<p>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: <a href="#debug-the-emulator">Section 18.7, &#8220;Debug the emulator&#8221;</a>.</p>
@@ -2753,7 +2754,7 @@ j = 0</pre>
<p>This repository has been tested inside clean <a href="https://en.wikipedia.org/wiki/Docker_(software)">Docker</a> containers.</p>
</div>
<div class="paragraph">
<p>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: <a href="#supported-hosts">Section 31.1, &#8220;Supported hosts&#8221;</a>.</p>
<p>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: <a href="#supported-hosts">Section 32.1, &#8220;Supported hosts&#8221;</a>.</p>
</div>
<div class="paragraph">
<p>For example, to do a <a href="#qemu-buildroot-setup">QEMU Buildroot setup</a> inside Docker, run:</p>
@@ -3831,7 +3832,7 @@ xdg-open README.html</pre>
</div>
</div>
<div class="paragraph">
<p>More information about our documentation internals can be found at: <a href="#documentation">Section 31.5, &#8220;Documentation&#8221;</a></p>
<p>More information about our documentation internals can be found at: <a href="#documentation">Section 32.5, &#8220;Documentation&#8221;</a></p>
</div>
</div>
</div>
@@ -7218,7 +7219,7 @@ qw er</pre>
<p>The gem5 tests require building statically with build id <code>static</code>, see also: <a href="#gem5-syscall-emulation-mode">Section 10.6, &#8220;gem5 syscall emulation mode&#8221;</a>. TODO automate this better.</p>
</div>
<div class="paragraph">
<p>See: <a href="#test-this-repo">Section 31.13, &#8220;Test this repo&#8221;</a> for more useful testing tips.</p>
<p>See: <a href="#test-this-repo">Section 32.13, &#8220;Test this repo&#8221;</a> for more useful testing tips.</p>
</div>
</div>
<div class="sect2">
@@ -7899,7 +7900,7 @@ hello
<div class="ulist">
<ul>
<li>
<p>modules built with Buildroot, see: <a href="#kernel_modules-buildroot-package">Section 31.12.2.1, &#8220;kernel_modules buildroot package&#8221;</a></p>
<p>modules built with Buildroot, see: <a href="#kernel_modules-buildroot-package">Section 32.12.2.1, &#8220;kernel_modules buildroot package&#8221;</a></p>
</li>
<li>
<p>modules built from the kernel tree itself, see: <a href="#dummy-irq">Section 15.12.2, &#8220;dummy-irq&#8221;</a></p>
@@ -8806,7 +8807,7 @@ xeyes</pre>
<div class="sect2">
<h3 id="enable-networking"><a class="anchor" href="#enable-networking"></a><a class="link" href="#enable-networking">14.1. Enable networking</a></h3>
<div class="paragraph">
<p>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: <a href="#resource-tradeoff-guidelines">Section 31.18.3, &#8220;Resource tradeoff guidelines&#8221;</a></p>
<p>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: <a href="#resource-tradeoff-guidelines">Section 32.18.3, &#8220;Resource tradeoff guidelines&#8221;</a></p>
</div>
<div class="paragraph">
<p>To enable networking on Buildroot, simply run:</p>
@@ -9655,15 +9656,15 @@ git log | grep -E ' Linux [0-9]+\.' | head</pre>
<p>This also makes this repo the perfect setup to develop the Linux kernel.</p>
</div>
<div class="paragraph">
<p>In case something breaks while updating the Linux kernel, you can try to bisect it to understand the root cause, see: <a href="#bisection">Section 31.14, &#8220;Bisection&#8221;</a>.</p>
<p>In case something breaks while updating the Linux kernel, you can try to bisect it to understand the root cause, see: <a href="#bisection">Section 32.14, &#8220;Bisection&#8221;</a>.</p>
</div>
<div class="sect4">
<h5 id="update-the-linux-kernel-lkmc-procedure"><a class="anchor" href="#update-the-linux-kernel-lkmc-procedure"></a><a class="link" href="#update-the-linux-kernel-lkmc-procedure">15.2.2.1. Update the Linux kernel LKMC procedure</a></h5>
<div class="paragraph">
<p>First, use use the branching procedure described at: <a href="#update-a-forked-submodule">Section 31.16, &#8220;Update a forked submodule&#8221;</a></p>
<p>First, use use the branching procedure described at: <a href="#update-a-forked-submodule">Section 32.16, &#8220;Update a forked submodule&#8221;</a></p>
</div>
<div class="paragraph">
<p>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: <a href="#test-this-repo">Section 31.13, &#8220;Test this repo&#8221;</a>. The only tests that can be skipped are essentially the <a href="#baremetal">Baremetal</a> tests.</p>
<p>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: <a href="#test-this-repo">Section 32.13, &#8220;Test this repo&#8221;</a>. The only tests that can be skipped are essentially the <a href="#baremetal">Baremetal</a> tests.</p>
</div>
<div class="paragraph">
<p>Before comitting, don&#8217;t forget to update:</p>
@@ -21507,7 +21508,7 @@ build/ARM/config/the_isa.hh
<p>The clean is necessary because the source files didn&#8217;t change, so <code>make</code> would just check the timestamps and not build anything.</p>
</div>
<div class="paragraph">
<p>You will then likely want to make those more permanent as explained at: <a href="#default-command-line-arguments">Section 31.4, &#8220;Default command line arguments&#8221;</a>.</p>
<p>You will then likely want to make those more permanent as explained at: <a href="#default-command-line-arguments">Section 32.4, &#8220;Default command line arguments&#8221;</a>.</p>
</div>
<div class="sect3">
<h4 id="enable-buildroot-compiler-optimizations"><a class="anchor" href="#enable-buildroot-compiler-optimizations"></a><a class="link" href="#enable-buildroot-compiler-optimizations">20.2.1. Enable Buildroot compiler optimizations</a></h4>
@@ -21682,7 +21683,7 @@ make menuconfig</pre>
<p>If none of those methods are flexible enough for you, you can just fork or hack up <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/buildroot_packages/sample_package">buildroot_packages/sample_package</a> the sample package to do what you want.</p>
</div>
<div class="paragraph">
<p>For how to use that package, see: <a href="#buildroot_packages-directory">Section 31.12.2, &#8220;buildroot_packages directory&#8221;</a>.</p>
<p>For how to use that package, see: <a href="#buildroot_packages-directory">Section 32.12.2, &#8220;buildroot_packages directory&#8221;</a>.</p>
</div>
<div class="paragraph">
<p>Then iterate trying to do what you want and reading the manual until it works: <a href="https://buildroot.org/downloads/manual/manual.html" class="bare">https://buildroot.org/downloads/manual/manual.html</a></p>
@@ -21867,7 +21868,7 @@ git -C "$(./getvar qemu_source_dir)" checkout -
<p>Then, you will also want to do a <a href="#bisection">Bisection</a> to pinpoint the exact commit to blame, and CC that developer.</p>
</div>
<div class="paragraph">
<p>Finally, give the images you used save upstream developers' time as shown at: <a href="#release-zip">Section 31.17.2, &#8220;release-zip&#8221;</a>.</p>
<p>Finally, give the images you used save upstream developers' time as shown at: <a href="#release-zip">Section 32.17.2, &#8220;release-zip&#8221;</a>.</p>
</div>
<div class="paragraph">
<p>For Buildroot problems, you should wither provide the config you have:</p>
@@ -29794,7 +29795,7 @@ ISB</pre>
<p>In baremetal, we detect if tests failed by parsing logs for the <a href="#magic-failure-string">Magic failure string</a>.</p>
</div>
<div class="paragraph">
<p>See: <a href="#test-this-repo">Section 31.13, &#8220;Test this repo&#8221;</a> for more useful testing tips.</p>
<p>See: <a href="#test-this-repo">Section 32.13, &#8220;Test this repo&#8221;</a> for more useful testing tips.</p>
</div>
</div>
</div>
@@ -30693,10 +30694,28 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect1">
<h2 id="about-this-repo"><a class="anchor" href="#about-this-repo"></a><a class="link" href="#about-this-repo">31. About this repo</a></h2>
<h2 id="compilers"><a class="anchor" href="#compilers"></a><a class="link" href="#compilers">31. Compilers</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Argh, compilers are boring, let&#8217;s learn a bit about them.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/userland/gcc/busy_loop.c">userland/gcc/busy_loop.c</a>: <a href="https://stackoverflow.com/questions/7083482/how-to-prevent-gcc-from-optimizing-out-a-busy-wait-loop/58758133#58758133" class="bare">https://stackoverflow.com/questions/7083482/how-to-prevent-gcc-from-optimizing-out-a-busy-wait-loop/58758133#58758133</a></p>
</li>
<li>
<p><a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/userland/gcc/prevent_reorder.cpp">userland/gcc/prevent_reorder.cpp</a>: <a href="https://stackoverflow.com/questions/37786547/enforcing-statement-order-in-c/56865717#56865717" class="bare">https://stackoverflow.com/questions/37786547/enforcing-statement-order-in-c/56865717#56865717</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="about-this-repo"><a class="anchor" href="#about-this-repo"></a><a class="link" href="#about-this-repo">32. About this repo</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="supported-hosts"><a class="anchor" href="#supported-hosts"></a><a class="link" href="#supported-hosts">31.1. Supported hosts</a></h3>
<h3 id="supported-hosts"><a class="anchor" href="#supported-hosts"></a><a class="link" href="#supported-hosts">32.1. Supported hosts</a></h3>
<div class="paragraph">
<p>The host requirements depend a lot on which examples you want to run.</p>
</div>
@@ -30745,9 +30764,9 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect2">
<h3 id="common-build-issues"><a class="anchor" href="#common-build-issues"></a><a class="link" href="#common-build-issues">31.2. Common build issues</a></h3>
<h3 id="common-build-issues"><a class="anchor" href="#common-build-issues"></a><a class="link" href="#common-build-issues">32.2. Common build issues</a></h3>
<div class="sect3">
<h4 id="put-source-uris-in-sources"><a class="anchor" href="#put-source-uris-in-sources"></a><a class="link" href="#put-source-uris-in-sources">31.2.1. You must put some 'source' URIs in your sources.list</a></h4>
<h4 id="put-source-uris-in-sources"><a class="anchor" href="#put-source-uris-in-sources"></a><a class="link" href="#put-source-uris-in-sources">32.2.1. You must put some 'source' URIs in your sources.list</a></h4>
<div class="paragraph">
<p>If <code>./build --download-dependencies</code> fails with:</p>
</div>
@@ -30761,7 +30780,7 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect3">
<h4 id="build-from-downloaded-source-zip-files"><a class="anchor" href="#build-from-downloaded-source-zip-files"></a><a class="link" href="#build-from-downloaded-source-zip-files">31.2.2. Build from downloaded source zip files</a></h4>
<h4 id="build-from-downloaded-source-zip-files"><a class="anchor" href="#build-from-downloaded-source-zip-files"></a><a class="link" href="#build-from-downloaded-source-zip-files">32.2.2. Build from downloaded source zip files</a></h4>
<div class="paragraph">
<p>It does not work if you just download the <code>.zip</code> with the sources for this repository from GitHub because we use <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/.gitmodules">Git submodules</a>, you must clone this repo.</p>
</div>
@@ -30771,7 +30790,7 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect2">
<h3 id="run-command-after-boot"><a class="anchor" href="#run-command-after-boot"></a><a class="link" href="#run-command-after-boot">31.3. Run command after boot</a></h3>
<h3 id="run-command-after-boot"><a class="anchor" href="#run-command-after-boot"></a><a class="link" href="#run-command-after-boot">32.3. Run command after boot</a></h3>
<div class="paragraph">
<p>If you just want to run a command after boot ends without thinking much about it, just use the <code>--eval-after</code> option, e.g.:</p>
</div>
@@ -30788,7 +30807,7 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect2">
<h3 id="default-command-line-arguments"><a class="anchor" href="#default-command-line-arguments"></a><a class="link" href="#default-command-line-arguments">31.4. Default command line arguments</a></h3>
<h3 id="default-command-line-arguments"><a class="anchor" href="#default-command-line-arguments"></a><a class="link" href="#default-command-line-arguments">32.4. Default command line arguments</a></h3>
<div class="paragraph">
<p>It gets annoying to retype <code>--arch aarch64</code> for every single command, or to remember <code>--config</code> setups.</p>
</div>
@@ -30833,12 +30852,12 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect2">
<h3 id="documentation"><a class="anchor" href="#documentation"></a><a class="link" href="#documentation">31.5. Documentation</a></h3>
<h3 id="documentation"><a class="anchor" href="#documentation"></a><a class="link" href="#documentation">32.5. Documentation</a></h3>
<div class="paragraph">
<p>To learn how to build the documentation see: <a href="#build-the-documentation">Section 1.8, &#8220;Build the documentation&#8221;</a>.</p>
</div>
<div class="sect3">
<h4 id="documentation-verification"><a class="anchor" href="#documentation-verification"></a><a class="link" href="#documentation-verification">31.5.1. Documentation verification</a></h4>
<h4 id="documentation-verification"><a class="anchor" href="#documentation-verification"></a><a class="link" href="#documentation-verification">32.5.1. Documentation verification</a></h4>
<div class="paragraph">
<p>When running <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/build-doc">build-doc</a>, we do the following checks:</p>
</div>
@@ -30859,7 +30878,7 @@ west build -b qemu_aarch64 samples/hello_world</pre>
<p>The scripts prints what you have to fix and exits with an error status if there are any errors.</p>
</div>
<div class="sect4">
<h5 id="asciidoctor-extract-link-targets"><a class="anchor" href="#asciidoctor-extract-link-targets"></a><a class="link" href="#asciidoctor-extract-link-targets">31.5.1.1. asciidoctor/extract-link-targets</a></h5>
<h5 id="asciidoctor-extract-link-targets"><a class="anchor" href="#asciidoctor-extract-link-targets"></a><a class="link" href="#asciidoctor-extract-link-targets">32.5.1.1. asciidoctor/extract-link-targets</a></h5>
<div class="paragraph">
<p>Documentation for <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/asciidoctor/extract-link-targets">asciidoctor/extract-link-targets</a></p>
</div>
@@ -30882,7 +30901,7 @@ west build -b qemu_aarch64 samples/hello_world</pre>
</div>
</div>
<div class="sect4">
<h5 id="asciidoctor-extract-header-ids"><a class="anchor" href="#asciidoctor-extract-header-ids"></a><a class="link" href="#asciidoctor-extract-header-ids">31.5.1.2. asciidoctor/extract-header-ids</a></h5>
<h5 id="asciidoctor-extract-header-ids"><a class="anchor" href="#asciidoctor-extract-header-ids"></a><a class="link" href="#asciidoctor-extract-header-ids">32.5.1.2. asciidoctor/extract-header-ids</a></h5>
<div class="paragraph">
<p>Documentation for <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/asciidoctor/extract-header-ids">asciidoctor/extract-header-ids</a></p>
</div>
@@ -30927,7 +30946,7 @@ explicitly-given</pre>
</div>
</div>
<div class="sect2">
<h3 id="asciidoctor-link-target-up-rb"><a class="anchor" href="#asciidoctor-link-target-up-rb"></a><a class="link" href="#asciidoctor-link-target-up-rb">31.6. asciidoctor/link-target-up.rb</a></h3>
<h3 id="asciidoctor-link-target-up-rb"><a class="anchor" href="#asciidoctor-link-target-up-rb"></a><a class="link" href="#asciidoctor-link-target-up-rb">32.6. asciidoctor/link-target-up.rb</a></h3>
<div class="paragraph">
<p>The Asciidoctor extension scripts:</p>
</div>
@@ -30955,7 +30974,7 @@ explicitly-given</pre>
</ul>
</div>
<div class="sect3">
<h4 id="github-pages"><a class="anchor" href="#github-pages"></a><a class="link" href="#github-pages">31.6.1. GitHub pages</a></h4>
<h4 id="github-pages"><a class="anchor" href="#github-pages"></a><a class="link" href="#github-pages">32.6.1. GitHub pages</a></h4>
<div class="paragraph">
<p>As mentioned before the TOC, we have to push this README to GitHub pages due to: <a href="https://github.com/isaacs/github/issues/1610" class="bare">https://github.com/isaacs/github/issues/1610</a></p>
</div>
@@ -31005,7 +31024,7 @@ explicitly-given</pre>
</div>
</div>
<div class="sect2">
<h3 id="clean-the-build"><a class="anchor" href="#clean-the-build"></a><a class="link" href="#clean-the-build">31.7. Clean the build</a></h3>
<h3 id="clean-the-build"><a class="anchor" href="#clean-the-build"></a><a class="link" href="#clean-the-build">32.7. Clean the build</a></h3>
<div class="paragraph">
<p>You did something crazy, and nothing seems to work anymore?</p>
</div>
@@ -31069,7 +31088,7 @@ ls "$(./getvar buildroot_build_dir)"</pre>
</div>
</div>
<div class="sect2">
<h3 id="ccache"><a class="anchor" href="#ccache"></a><a class="link" href="#ccache">31.8. ccache</a></h3>
<h3 id="ccache"><a class="anchor" href="#ccache"></a><a class="link" href="#ccache">32.8. ccache</a></h3>
<div class="paragraph">
<p><a href="https://en.wikipedia.org/wiki/Ccache">ccache</a> <a href="#benchmark-builds">might</a> save you a lot of re-build when you decide to <a href="#clean-the-build">Clean the build</a> or create a new <a href="#build-variants">build variant</a>.</p>
</div>
@@ -31138,7 +31157,7 @@ export CCACHE_MAXSIZE="20G"</pre>
</div>
</div>
<div class="sect2">
<h3 id="rebuild-buildroot-while-running"><a class="anchor" href="#rebuild-buildroot-while-running"></a><a class="link" href="#rebuild-buildroot-while-running">31.9. Rebuild Buildroot while running</a></h3>
<h3 id="rebuild-buildroot-while-running"><a class="anchor" href="#rebuild-buildroot-while-running"></a><a class="link" href="#rebuild-buildroot-while-running">32.9. Rebuild Buildroot while running</a></h3>
<div class="paragraph">
<p>It is not possible to rebuild the root filesystem while running QEMU because QEMU holds the file qcow2 file:</p>
</div>
@@ -31149,7 +31168,7 @@ export CCACHE_MAXSIZE="20G"</pre>
</div>
</div>
<div class="sect2">
<h3 id="simultaneous-runs"><a class="anchor" href="#simultaneous-runs"></a><a class="link" href="#simultaneous-runs">31.10. Simultaneous runs</a></h3>
<h3 id="simultaneous-runs"><a class="anchor" href="#simultaneous-runs"></a><a class="link" href="#simultaneous-runs">32.10. Simultaneous runs</a></h3>
<div class="paragraph">
<p>When doing long simulations sweeping across multiple system parameters, it becomes fundamental to do multiple simulations in parallel.</p>
</div>
@@ -31245,7 +31264,7 @@ less "$(./getvar --arch aarch64 --emulator gem5 --run-id 1 termout_file)"</pre>
</div>
</div>
<div class="paragraph">
<p>To run multiple gem5 checkouts, see: <a href="#gem5-worktree">Section 31.11.3.1, &#8220;gem5 worktree&#8221;</a>.</p>
<p>To run multiple gem5 checkouts, see: <a href="#gem5-worktree">Section 32.11.3.1, &#8220;gem5 worktree&#8221;</a>.</p>
</div>
<div class="paragraph">
<p>Implementation note: we create multiple namespaces for two things:</p>
@@ -31284,7 +31303,7 @@ less "$(./getvar --arch aarch64 --emulator gem5 --run-id 1 termout_file)"</pre>
</div>
</div>
<div class="sect2">
<h3 id="build-variants"><a class="anchor" href="#build-variants"></a><a class="link" href="#build-variants">31.11. Build variants</a></h3>
<h3 id="build-variants"><a class="anchor" href="#build-variants"></a><a class="link" href="#build-variants">32.11. Build variants</a></h3>
<div class="paragraph">
<p>It often happens that you are comparing two versions of the build, a good and a bad one, and trying to figure out why the bad one is bad.</p>
</div>
@@ -31292,7 +31311,7 @@ less "$(./getvar --arch aarch64 --emulator gem5 --run-id 1 termout_file)"</pre>
<p>Our build variants system allows you to keep multiple built versions of all major components, so that you can easily switching between running one or the other.</p>
</div>
<div class="sect3">
<h4 id="linux-kernel-build-variants"><a class="anchor" href="#linux-kernel-build-variants"></a><a class="link" href="#linux-kernel-build-variants">31.11.1. Linux kernel build variants</a></h4>
<h4 id="linux-kernel-build-variants"><a class="anchor" href="#linux-kernel-build-variants"></a><a class="link" href="#linux-kernel-build-variants">32.11.1. Linux kernel build variants</a></h4>
<div class="paragraph">
<p>If you want to keep two builds around, one for the latest Linux version, and the other for Linux <code>v4.16</code>:</p>
</div>
@@ -31328,11 +31347,11 @@ git -C "$(./getvar linux_source_dir)" checkout -
</div>
</div>
<div class="paragraph">
<p>To run both kernels simultaneously, one on each QEMU instance, see: <a href="#simultaneous-runs">Section 31.10, &#8220;Simultaneous runs&#8221;</a>.</p>
<p>To run both kernels simultaneously, one on each QEMU instance, see: <a href="#simultaneous-runs">Section 32.10, &#8220;Simultaneous runs&#8221;</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="qemu-build-variants"><a class="anchor" href="#qemu-build-variants"></a><a class="link" href="#qemu-build-variants">31.11.2. QEMU build variants</a></h4>
<h4 id="qemu-build-variants"><a class="anchor" href="#qemu-build-variants"></a><a class="link" href="#qemu-build-variants">32.11.2. QEMU build variants</a></h4>
<div class="paragraph">
<p>Analogous to the <a href="#linux-kernel-build-variants">Linux kernel build variants</a> but with the <code>--qemu-build-id</code> option instead:</p>
</div>
@@ -31348,7 +31367,7 @@ git -C "$(./getvar qemu_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="gem5-build-variants"><a class="anchor" href="#gem5-build-variants"></a><a class="link" href="#gem5-build-variants">31.11.3. gem5 build variants</a></h4>
<h4 id="gem5-build-variants"><a class="anchor" href="#gem5-build-variants"></a><a class="link" href="#gem5-build-variants">32.11.3. gem5 build variants</a></h4>
<div class="paragraph">
<p>Analogous to the <a href="#linux-kernel-build-variants">Linux kernel build variants</a> but with the <code>--gem5-build-id</code> option instead:</p>
</div>
@@ -31379,7 +31398,7 @@ git -C "$(./getvar gem5_source_dir)" checkout some-branch
<p>Therefore, you can&#8217;t forget to checkout to the sources to that of the corresponding build before running, unless you explicitly tell gem5 to use a non-default source tree with <a href="#gem5-worktree">gem5 worktree</a>. This becomes inevitable when you want to launch multiple simultaneous runs at different checkouts.</p>
</div>
<div class="sect4">
<h5 id="gem5-worktree"><a class="anchor" href="#gem5-worktree"></a><a class="link" href="#gem5-worktree">31.11.3.1. gem5 worktree</a></h5>
<h5 id="gem5-worktree"><a class="anchor" href="#gem5-worktree"></a><a class="link" href="#gem5-worktree">32.11.3.1. gem5 worktree</a></h5>
<div class="paragraph">
<p><a href="#gem5-build-variants"><code>--gem5-build-id</code></a> goes a long way, but if you want to seamlessly switch between two gem5 tress without checking out multiple times, then <code>--gem5-worktree</code> is for you.</p>
</div>
@@ -31432,7 +31451,7 @@ cd -
</div>
</div>
<div class="sect4">
<h5 id="gem5-private-source-trees"><a class="anchor" href="#gem5-private-source-trees"></a><a class="link" href="#gem5-private-source-trees">31.11.3.2. gem5 private source trees</a></h5>
<h5 id="gem5-private-source-trees"><a class="anchor" href="#gem5-private-source-trees"></a><a class="link" href="#gem5-private-source-trees">32.11.3.2. gem5 private source trees</a></h5>
<div class="paragraph">
<p>Suppose that you are working on a private fork of gem5, but you want to use this repository to develop it as well.</p>
</div>
@@ -31476,7 +31495,7 @@ gem5_internal="$(pwd)/gem5-internal"</pre>
</div>
</div>
<div class="sect3">
<h4 id="buildroot-build-variants"><a class="anchor" href="#buildroot-build-variants"></a><a class="link" href="#buildroot-build-variants">31.11.4. Buildroot build variants</a></h4>
<h4 id="buildroot-build-variants"><a class="anchor" href="#buildroot-build-variants"></a><a class="link" href="#buildroot-build-variants">32.11.4. Buildroot build variants</a></h4>
<div class="paragraph">
<p>Allows you to have multiple versions of the GCC toolchain or root filesystem.</p>
</div>
@@ -31496,9 +31515,9 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect2">
<h3 id="directory-structure"><a class="anchor" href="#directory-structure"></a><a class="link" href="#directory-structure">31.12. Directory structure</a></h3>
<h3 id="directory-structure"><a class="anchor" href="#directory-structure"></a><a class="link" href="#directory-structure">32.12. Directory structure</a></h3>
<div class="sect3">
<h4 id="lkmc-directory"><a class="anchor" href="#lkmc-directory"></a><a class="link" href="#lkmc-directory">31.12.1. lkmc directory</a></h4>
<h4 id="lkmc-directory"><a class="anchor" href="#lkmc-directory"></a><a class="link" href="#lkmc-directory">32.12.1. lkmc directory</a></h4>
<div class="paragraph">
<p><a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/lkmc/">lkmc/</a> contains sources and headers that are shared across kernel modules, userland and baremetal examples.</p>
</div>
@@ -31509,7 +31528,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
<p>Another option would have been to name it as <code>includes/lkmc</code>, but that would make paths longer, and we might want to store source code in that directory as well in the future.</p>
</div>
<div class="sect4">
<h5 id="userland-objects-vs-header-only"><a class="anchor" href="#userland-objects-vs-header-only"></a><a class="link" href="#userland-objects-vs-header-only">31.12.1.1. Userland objects vs header-only</a></h5>
<h5 id="userland-objects-vs-header-only"><a class="anchor" href="#userland-objects-vs-header-only"></a><a class="link" href="#userland-objects-vs-header-only">32.12.1.1. Userland objects vs header-only</a></h5>
<div class="paragraph">
<p>When factoring out functionality across userland examples, there are two main options:</p>
</div>
@@ -31568,7 +31587,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="buildroot_packages-directory"><a class="anchor" href="#buildroot_packages-directory"></a><a class="link" href="#buildroot_packages-directory">31.12.2. buildroot_packages directory</a></h4>
<h4 id="buildroot_packages-directory"><a class="anchor" href="#buildroot_packages-directory"></a><a class="link" href="#buildroot_packages-directory">32.12.2. buildroot_packages directory</a></h4>
<div class="paragraph">
<p>Source: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/buildroot_packages/">buildroot_packages/</a>.</p>
</div>
@@ -31617,7 +31636,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
<p>A custom build script can give you more flexibility: e.g. the package can be made work with other root filesystems more easily, have better <a href="#9p">9P</a> support, and rebuild faster as it evades some Buildroot boilerplate.</p>
</div>
<div class="sect4">
<h5 id="kernel_modules-buildroot-package"><a class="anchor" href="#kernel_modules-buildroot-package"></a><a class="link" href="#kernel_modules-buildroot-package">31.12.2.1. kernel_modules buildroot package</a></h5>
<h5 id="kernel_modules-buildroot-package"><a class="anchor" href="#kernel_modules-buildroot-package"></a><a class="link" href="#kernel_modules-buildroot-package">32.12.2.1. kernel_modules buildroot package</a></h5>
<div class="paragraph">
<p>Source: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/buildroot_packages/kernel_modules/">buildroot_packages/kernel_modules/</a></p>
</div>
@@ -31664,9 +31683,9 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="patches-directory"><a class="anchor" href="#patches-directory"></a><a class="link" href="#patches-directory">31.12.3. patches directory</a></h4>
<h4 id="patches-directory"><a class="anchor" href="#patches-directory"></a><a class="link" href="#patches-directory">32.12.3. patches directory</a></h4>
<div class="sect4">
<h5 id="patches-global-directory"><a class="anchor" href="#patches-global-directory"></a><a class="link" href="#patches-global-directory">31.12.3.1. patches/global directory</a></h5>
<h5 id="patches-global-directory"><a class="anchor" href="#patches-global-directory"></a><a class="link" href="#patches-global-directory">32.12.3.1. patches/global directory</a></h5>
<div class="paragraph">
<p>Has the following structure:</p>
</div>
@@ -31683,7 +31702,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect4">
<h5 id="patches-manual-directory"><a class="anchor" href="#patches-manual-directory"></a><a class="link" href="#patches-manual-directory">31.12.3.2. patches/manual directory</a></h5>
<h5 id="patches-manual-directory"><a class="anchor" href="#patches-manual-directory"></a><a class="link" href="#patches-manual-directory">32.12.3.2. patches/manual directory</a></h5>
<div class="paragraph">
<p>Patches in this directory are never applied automatically: it is up to users to manually apply them before usage following the instructions in this documentation.</p>
</div>
@@ -31693,7 +31712,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="rootfs_overlay"><a class="anchor" href="#rootfs_overlay"></a><a class="link" href="#rootfs_overlay">31.12.4. rootfs_overlay</a></h4>
<h4 id="rootfs_overlay"><a class="anchor" href="#rootfs_overlay"></a><a class="link" href="#rootfs_overlay">32.12.4. rootfs_overlay</a></h4>
<div class="paragraph">
<p>Source: <a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/rootfs_overlay">rootfs_overlay</a>.</p>
</div>
@@ -31740,7 +31759,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
<p>This way you can just hack away the scripts and try them out immediately without any further operations.</p>
</div>
<div class="sect4">
<h5 id="out_rootfs_overlay_dir"><a class="anchor" href="#out_rootfs_overlay_dir"></a><a class="link" href="#out_rootfs_overlay_dir">31.12.4.1. out_rootfs_overlay_dir</a></h5>
<h5 id="out_rootfs_overlay_dir"><a class="anchor" href="#out_rootfs_overlay_dir"></a><a class="link" href="#out_rootfs_overlay_dir">32.12.4.1. out_rootfs_overlay_dir</a></h5>
<div class="paragraph">
<p>This path can be found with:</p>
</div>
@@ -31774,7 +31793,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="lkmc-c"><a class="anchor" href="#lkmc-c"></a><a class="link" href="#lkmc-c">31.12.5. lkmc.c</a></h4>
<h4 id="lkmc-c"><a class="anchor" href="#lkmc-c"></a><a class="link" href="#lkmc-c">32.12.5. lkmc.c</a></h4>
<div class="paragraph">
<p>The files:</p>
</div>
@@ -31804,7 +31823,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="rand_check-out"><a class="anchor" href="#rand_check-out"></a><a class="link" href="#rand_check-out">31.12.6. rand_check.out</a></h4>
<h4 id="rand_check-out"><a class="anchor" href="#rand_check-out"></a><a class="link" href="#rand_check-out">32.12.6. rand_check.out</a></h4>
<div class="paragraph">
<p>Print out several parameters that normally change randomly from boot to boot:</p>
</div>
@@ -31831,7 +31850,7 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect3">
<h4 id="lkmc_home"><a class="anchor" href="#lkmc_home"></a><a class="link" href="#lkmc_home">31.12.7. lkmc_home</a></h4>
<h4 id="lkmc_home"><a class="anchor" href="#lkmc_home"></a><a class="link" href="#lkmc_home">32.12.7. lkmc_home</a></h4>
<div class="paragraph">
<p><code>lkmc_home</code> refers to the target base directory in which we put all our custom built stuff, such as <a href="#userland-setup">userland executables</a> and <a href="#your-first-kernel-module-hack">kernel modules</a>.</p>
</div>
@@ -31865,9 +31884,9 @@ git -C "$(./getvar buildroot_source_dir)" checkout -
</div>
</div>
<div class="sect2">
<h3 id="test-this-repo"><a class="anchor" href="#test-this-repo"></a><a class="link" href="#test-this-repo">31.13. Test this repo</a></h3>
<h3 id="test-this-repo"><a class="anchor" href="#test-this-repo"></a><a class="link" href="#test-this-repo">32.13. Test this repo</a></h3>
<div class="sect3">
<h4 id="automated-tests"><a class="anchor" href="#automated-tests"></a><a class="link" href="#automated-tests">31.13.1. Automated tests</a></h4>
<h4 id="automated-tests"><a class="anchor" href="#automated-tests"></a><a class="link" href="#automated-tests">32.13.1. Automated tests</a></h4>
<div class="paragraph">
<p>Run almost all tests:</p>
</div>
@@ -31923,7 +31942,7 @@ echo $?</pre>
<p><a href="https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/test">test</a> does not all possible tests, because there are too many possible variations and that would take forever. The rationale is the same as for <code>./build all</code> and is explained in <code>./build --help</code>.</p>
</div>
<div class="sect4">
<h5 id="test-arch-and-emulator-selection"><a class="anchor" href="#test-arch-and-emulator-selection"></a><a class="link" href="#test-arch-and-emulator-selection">31.13.1.1. Test arch and emulator selection</a></h5>
<h5 id="test-arch-and-emulator-selection"><a class="anchor" href="#test-arch-and-emulator-selection"></a><a class="link" href="#test-arch-and-emulator-selection">32.13.1.1. Test arch and emulator selection</a></h5>
<div class="paragraph">
<p>You can select multiple archs and emulators of interest, as for an other command, with:</p>
</div>
@@ -31956,7 +31975,7 @@ echo $?</pre>
</div>
</div>
<div class="sect4">
<h5 id="quit-on-fail"><a class="anchor" href="#quit-on-fail"></a><a class="link" href="#quit-on-fail">31.13.1.2. Quit on fail</a></h5>
<h5 id="quit-on-fail"><a class="anchor" href="#quit-on-fail"></a><a class="link" href="#quit-on-fail">32.13.1.2. Quit on fail</a></h5>
<div class="paragraph">
<p>By default, continue running even after the first failure happens, and they show a summary at the end.</p>
</div>
@@ -31970,7 +31989,7 @@ echo $?</pre>
</div>
</div>
<div class="sect4">
<h5 id="test-userland-in-full-system"><a class="anchor" href="#test-userland-in-full-system"></a><a class="link" href="#test-userland-in-full-system">31.13.1.3. Test userland in full system</a></h5>
<h5 id="test-userland-in-full-system"><a class="anchor" href="#test-userland-in-full-system"></a><a class="link" href="#test-userland-in-full-system">32.13.1.3. Test userland in full system</a></h5>
<div class="paragraph">
<p>TODO: we really need a mechanism to automatically generate the test list automatically e.g. based on <a href="#path-properties">path_properties</a>, currently there are many tests missing, and we have to add everything manually which is very annoying.</p>
</div>
@@ -31999,7 +32018,7 @@ echo $?</pre>
</div>
</div>
<div class="sect4">
<h5 id="gdb-tests"><a class="anchor" href="#gdb-tests"></a><a class="link" href="#gdb-tests">31.13.1.4. GDB tests</a></h5>
<h5 id="gdb-tests"><a class="anchor" href="#gdb-tests"></a><a class="link" href="#gdb-tests">32.13.1.4. GDB tests</a></h5>
<div class="paragraph">
<p>We have some <a href="https://github.com/pexpect/pexpect">pexpect</a> automated tests for GDB for both userland and baremetal programs!</p>
</div>
@@ -32072,7 +32091,7 @@ echo $?</pre>
</div>
</div>
<div class="sect4">
<h5 id="magic-failure-string"><a class="anchor" href="#magic-failure-string"></a><a class="link" href="#magic-failure-string">31.13.1.5. Magic failure string</a></h5>
<h5 id="magic-failure-string"><a class="anchor" href="#magic-failure-string"></a><a class="link" href="#magic-failure-string">32.13.1.5. Magic failure string</a></h5>
<div class="paragraph">
<p>We do not know of any way to set the emulator exit status in QEMU arm full system.</p>
</div>
@@ -32175,9 +32194,9 @@ echo $?</pre>
</div>
</div>
<div class="sect3">
<h4 id="non-automated-tests"><a class="anchor" href="#non-automated-tests"></a><a class="link" href="#non-automated-tests">31.13.2. Non-automated tests</a></h4>
<h4 id="non-automated-tests"><a class="anchor" href="#non-automated-tests"></a><a class="link" href="#non-automated-tests">32.13.2. Non-automated tests</a></h4>
<div class="sect4">
<h5 id="test-gdb-linux-kernel"><a class="anchor" href="#test-gdb-linux-kernel"></a><a class="link" href="#test-gdb-linux-kernel">31.13.2.1. Test GDB Linux kernel</a></h5>
<h5 id="test-gdb-linux-kernel"><a class="anchor" href="#test-gdb-linux-kernel"></a><a class="link" href="#test-gdb-linux-kernel">32.13.2.1. Test GDB Linux kernel</a></h5>
<div class="paragraph">
<p>For the Linux kernel, do the following manual tests for now.</p>
</div>
@@ -32215,7 +32234,7 @@ echo $?</pre>
</div>
</div>
<div class="sect4">
<h5 id="test-the-internet"><a class="anchor" href="#test-the-internet"></a><a class="link" href="#test-the-internet">31.13.2.2. Test the Internet</a></h5>
<h5 id="test-the-internet"><a class="anchor" href="#test-the-internet"></a><a class="link" href="#test-the-internet">32.13.2.2. Test the Internet</a></h5>
<div class="paragraph">
<p>You should also test that the Internet works:</p>
</div>
@@ -32226,7 +32245,7 @@ echo $?</pre>
</div>
</div>
<div class="sect4">
<h5 id="cli-script-tests"><a class="anchor" href="#cli-script-tests"></a><a class="link" href="#cli-script-tests">31.13.2.3. CLI script tests</a></h5>
<h5 id="cli-script-tests"><a class="anchor" href="#cli-script-tests"></a><a class="link" href="#cli-script-tests">32.13.2.3. CLI script tests</a></h5>
<div class="paragraph">
<p><code>build-userland</code> and <code>test-executables</code> have a wide variety of target selection modes, and it was hard to keep them all working without some tests:</p>
</div>
@@ -32244,7 +32263,7 @@ echo $?</pre>
</div>
</div>
<div class="sect2">
<h3 id="bisection"><a class="anchor" href="#bisection"></a><a class="link" href="#bisection">31.14. Bisection</a></h3>
<h3 id="bisection"><a class="anchor" href="#bisection"></a><a class="link" href="#bisection">32.14. Bisection</a></h3>
<div class="paragraph">
<p>When updating the Linux kernel, QEMU and gem5, things sometimes break.</p>
</div>
@@ -32300,7 +32319,7 @@ git submodule update
</div>
</div>
<div class="sect2">
<h3 id="path-properties"><a class="anchor" href="#path-properties"></a><a class="link" href="#path-properties">31.15. path_properties</a></h3>
<h3 id="path-properties"><a class="anchor" href="#path-properties"></a><a class="link" href="#path-properties">32.15. path_properties</a></h3>
<div class="paragraph">
<p>In order to build and run each userland and <a href="#baremetal-setup">baremetal</a> example properly, we need per-file metadata such as compiler flags and required number of cores.</p>
</div>
@@ -32343,7 +32362,7 @@ git submodule update
</div>
</div>
<div class="sect2">
<h3 id="update-a-forked-submodule"><a class="anchor" href="#update-a-forked-submodule"></a><a class="link" href="#update-a-forked-submodule">31.16. Update a forked submodule</a></h3>
<h3 id="update-a-forked-submodule"><a class="anchor" href="#update-a-forked-submodule"></a><a class="link" href="#update-a-forked-submodule">32.16. Update a forked submodule</a></h3>
<div class="paragraph">
<p>This is a template update procedure for submodules for which we have some patches on on top of mainline.</p>
</div>
@@ -32372,9 +32391,9 @@ git commit -m "linux: update to ${next_mainline_revision}"</pre>
</div>
</div>
<div class="sect2">
<h3 id="release"><a class="anchor" href="#release"></a><a class="link" href="#release">31.17. Release</a></h3>
<h3 id="release"><a class="anchor" href="#release"></a><a class="link" href="#release">32.17. Release</a></h3>
<div class="sect3">
<h4 id="release-procedure"><a class="anchor" href="#release-procedure"></a><a class="link" href="#release-procedure">31.17.1. Release procedure</a></h4>
<h4 id="release-procedure"><a class="anchor" href="#release-procedure"></a><a class="link" href="#release-procedure">32.17.1. Release procedure</a></h4>
<div class="paragraph">
<p>Ensure that the <a href="#automated-tests">Automated tests</a> are passing on a clean build:</p>
</div>
@@ -32385,7 +32404,7 @@ git commit -m "linux: update to ${next_mainline_revision}"</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>./build-test</code> 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: <a href="#release-zip">Section 31.17.2, &#8220;release-zip&#8221;</a></p>
<p>The <code>./build-test</code> 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: <a href="#release-zip">Section 32.17.2, &#8220;release-zip&#8221;</a></p>
</div>
<div class="paragraph">
<p>The clean build is necessary as it generates clean images since <a href="#remove-buildroot-packages">it is not possible to remove Buildroot packages</a></p>
@@ -32455,7 +32474,7 @@ git push --follow-tags
</div>
</div>
<div class="sect3">
<h4 id="release-zip"><a class="anchor" href="#release-zip"></a><a class="link" href="#release-zip">31.17.2. release-zip</a></h4>
<h4 id="release-zip"><a class="anchor" href="#release-zip"></a><a class="link" href="#release-zip">32.17.2. release-zip</a></h4>
<div class="paragraph">
<p>Create a zip containing all files required for <a href="#prebuilt">Prebuilt setup</a>:</p>
</div>
@@ -32480,7 +32499,7 @@ git push --follow-tags
</div>
</div>
<div class="sect3">
<h4 id="release-upload"><a class="anchor" href="#release-upload"></a><a class="link" href="#release-upload">31.17.3. release-upload</a></h4>
<h4 id="release-upload"><a class="anchor" href="#release-upload"></a><a class="link" href="#release-upload">32.17.3. release-upload</a></h4>
<div class="paragraph">
<p>After:</p>
</div>
@@ -32528,9 +32547,9 @@ git push --follow-tags
</div>
</div>
<div class="sect2">
<h3 id="design-rationale"><a class="anchor" href="#design-rationale"></a><a class="link" href="#design-rationale">31.18. Design rationale</a></h3>
<h3 id="design-rationale"><a class="anchor" href="#design-rationale"></a><a class="link" href="#design-rationale">32.18. Design rationale</a></h3>
<div class="sect3">
<h4 id="design-goals"><a class="anchor" href="#design-goals"></a><a class="link" href="#design-goals">31.18.1. Design goals</a></h4>
<h4 id="design-goals"><a class="anchor" href="#design-goals"></a><a class="link" href="#design-goals">32.18.1. Design goals</a></h4>
<div class="paragraph">
<p>This project was created to help me understand, modify and test low level system components by using system simulators.</p>
</div>
@@ -32606,7 +32625,7 @@ git push --follow-tags
</div>
</div>
<div class="sect3">
<h4 id="setup-trade-offs"><a class="anchor" href="#setup-trade-offs"></a><a class="link" href="#setup-trade-offs">31.18.2. Setup trade-offs</a></h4>
<h4 id="setup-trade-offs"><a class="anchor" href="#setup-trade-offs"></a><a class="link" href="#setup-trade-offs">32.18.2. Setup trade-offs</a></h4>
<div class="paragraph">
<p>The trade-offs between the different <a href="#getting-started">setups</a> are basically a balance between:</p>
</div>
@@ -32631,13 +32650,13 @@ git push --follow-tags
<p>compatibility: how likely is is that all the components will work well together: emulator, compiler, kernel, standard library, &#8230;&#8203;</p>
</li>
<li>
<p>guest software availability: how wide is your choice of easily installed guest software packages? See also: <a href="#linux-distro-choice">Section 31.18.4, &#8220;Linux distro choice&#8221;</a></p>
<p>guest software availability: how wide is your choice of easily installed guest software packages? See also: <a href="#linux-distro-choice">Section 32.18.4, &#8220;Linux distro choice&#8221;</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="resource-tradeoff-guidelines"><a class="anchor" href="#resource-tradeoff-guidelines"></a><a class="link" href="#resource-tradeoff-guidelines">31.18.3. Resource tradeoff guidelines</a></h4>
<h4 id="resource-tradeoff-guidelines"><a class="anchor" href="#resource-tradeoff-guidelines"></a><a class="link" href="#resource-tradeoff-guidelines">32.18.3. Resource tradeoff guidelines</a></h4>
<div class="paragraph">
<p>Choosing which features go into our default builds means making tradeoffs, here are our guidelines:</p>
</div>
@@ -32682,7 +32701,7 @@ git push --follow-tags
</div>
</div>
<div class="sect3">
<h4 id="linux-distro-choice"><a class="anchor" href="#linux-distro-choice"></a><a class="link" href="#linux-distro-choice">31.18.4. Linux distro choice</a></h4>
<h4 id="linux-distro-choice"><a class="anchor" href="#linux-distro-choice"></a><a class="link" href="#linux-distro-choice">32.18.4. Linux distro choice</a></h4>
<div class="paragraph">
<p>We haven&#8217;t found the ultimate distro yet, here is a summary table of trade-offs that we care about: <a href="#table-lkmc-linux-distro-comparison">Table 7, &#8220;Comparison of Linux distros for usage in this repository&#8221;</a>.</p>
</div>
@@ -32785,9 +32804,9 @@ git push --follow-tags
</div>
</div>
<div class="sect2">
<h3 id="soft-topics"><a class="anchor" href="#soft-topics"></a><a class="link" href="#soft-topics">31.19. Soft topics</a></h3>
<h3 id="soft-topics"><a class="anchor" href="#soft-topics"></a><a class="link" href="#soft-topics">32.19. Soft topics</a></h3>
<div class="sect3">
<h4 id="fairy-tale"><a class="anchor" href="#fairy-tale"></a><a class="link" href="#fairy-tale">31.19.1. Fairy tale</a></h4>
<h4 id="fairy-tale"><a class="anchor" href="#fairy-tale"></a><a class="link" href="#fairy-tale">32.19.1. Fairy tale</a></h4>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
@@ -32824,7 +32843,7 @@ git push --follow-tags
</div>
</div>
<div class="sect3">
<h4 id="should-you-waste-your-life-with-systems-programming"><a class="anchor" href="#should-you-waste-your-life-with-systems-programming"></a><a class="link" href="#should-you-waste-your-life-with-systems-programming">31.19.2. Should you waste your life with systems programming?</a></h4>
<h4 id="should-you-waste-your-life-with-systems-programming"><a class="anchor" href="#should-you-waste-your-life-with-systems-programming"></a><a class="link" href="#should-you-waste-your-life-with-systems-programming">32.19.2. Should you waste your life with systems programming?</a></h4>
<div class="paragraph">
<p>Being the hardcore person who fully understands an important complex system such as a computer, it does have a nice ring to it doesn&#8217;t it?</p>
</div>
@@ -32909,7 +32928,7 @@ git push --follow-tags
</div>
</div>
<div class="sect2">
<h3 id="bibliography"><a class="anchor" href="#bibliography"></a><a class="link" href="#bibliography">31.20. Bibliography</a></h3>
<h3 id="bibliography"><a class="anchor" href="#bibliography"></a><a class="link" href="#bibliography">32.20. Bibliography</a></h3>
<div class="paragraph">
<p>Runnable stuff:</p>
</div>