adoc

README.adoc

@@ -0,0 +1,83 @@
+[[linux-kernel-module-cheat]]
+= Linux Kernel Module Cheat
+
+Run one command, get a QEMU Buildroot BusyBox virtual machine built from
+source with several minimal Linux kernel 4.15 module development example
+tutorials with GDB and KGDB step debugging and minimal educational
+hardware models. Limited GEM5 full system support. "Tested" in x86, ARM
+and MIPS guests, Ubuntu 17.10 host.
+
+image:screenshot.png[image]
+
+Reserve 12Gb of disk and run:
+
+....
+git clone https://github.com/cirosantilli/linux-kernel-module-cheat
+cd linux-kernel-module-cheat
+./configure && ./build && ./run
+....
+
+The first build will take a while
+(https://stackoverflow.com/questions/10833672/buildroot-environment-with-host-toolchain[GCC],
+Linux kernel), e.g.:
+
+* 2 hours on a mid end 2012 laptop
+* 30 minutes on a high end 2017 desktop
+
+If you don't want to wait, you could also try to compile the examples
+and run them on your host computer as explained on the
+link:run-on-host.md["Run on host" section], but as explained on that
+section, that is dangerous, limited, and will likely not work.
+
+After QEMU opens up, you can start playing with the kernel modules:
+
+....
+root
+insmod /hello.ko
+insmod /hello2.ko
+rmmod hello
+rmmod hello2
+....
+
+This should print to the screen:
+
+....
+hello init
+hello2 init
+hello cleanup
+hello2 cleanup
+....
+
+which are `printk` messages from `init` and `cleanup` methods of those
+modules.
+
+All available modules can be found in the
+link:kernel_module/[`kernel_module` directory].
+
+See the link:getting-started.md[getting started section] for further
+details.
+
+1.  link:getting-started.md[*Getting started*]
+2.  Action
+1.  Step debugging
+1.  link:gdb-step-debugging.md[GDB step debugging]
+2.  link:kgdb.md[KGDB]
+3.  link:gdbserver.md[gdbserver]
+2.  link:other-architectures.md[Other architectures]
+3.  link:init.md[init]
+4.  link:modprobe.md[modprobe]
+5.  link:x11.md[X11]
+6.  link:count-boot-instructions.md[Count boot instructions]
+7.  link:gem5.md[GEM5]
+8.  link:ftrace.md[ftrace]
+9.  link:qemu-user-mode.md[QEMU user mode]
+3.  Failed action
+1.  link:record-and-replay.md[Record and replay]
+4.  Insane action
+1.  link:run-on-host.md[Run on host]
+2.  link:hello_host/[Hello host]
+5.  Conversation
+1.  link:kmod.md[kmod]
+2.  link:device-tree.md[Device tree]
+3.  link:maintainers.md[Maintainers]
+4.  link:bibliography.md[Bibliography]