From 128612f7bb60f65d237621f9aed641b332bd1907 Mon Sep 17 00:00:00 2001 From: Ciro Santilli Date: Sat, 2 Dec 2017 09:09:45 +0000 Subject: [PATCH] Move some getting started to readme --- README.md | 38 +++++++++++++++++++++++- getting-started.md | 74 ++-------------------------------------------- run-on-host.md | 41 +++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 73 deletions(-) create mode 100644 run-on-host.md diff --git a/README.md b/README.md index ee0aa3b..92c0e2c 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,40 @@ Run one command, get a QEMU Buildroot BusyBox virtual machine built from source with several minimal Linux kernel 4.14 module development example tutorials with GDB and KGDB debug and minimal QEMU educational models. "Tested" in x86, ARM and MIPS guests, Ubuntu 17.10 host. +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 ([GCC](https://stackoverflow.com/questions/10833672/buildroot-environment-with-host-toolchain), 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 as explained on the [run on host section](run-on-host.md), but as explained on that section, that is dangerous 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. + +See the [getting started section](getting-started.md) for further details. + ![](screenshot.png) 1. [**Getting started**](getting-started.md) @@ -12,13 +46,15 @@ Run one command, get a QEMU Buildroot BusyBox virtual machine built from source 1. [X11](x11.md) 1. [gdbserver](gdbserver.md) 1. [Count boot instructions](count-boot-instructions.md) - 1. [Hello host](hello_host/) 1. [ftrace](ftrace.md) 1. [Device tree](device-tree.md) 1. [modprobe](modprobe.md) 1. Failed action 1. [Record and replay](record-and-replay.md) 1. [GEM5](gem5.md) +1. Insane action + 1. [Run on host](run-on-host.md) + 1. [Hello host](hello_host/) 1. Conversation 1. [kmod](kmod.md) 1. [Maintainers](maintainers.md) diff --git a/getting-started.md b/getting-started.md index 86020a3..8dddaf4 100644 --- a/getting-started.md +++ b/getting-started.md @@ -1,78 +1,8 @@ # Getting started -## Insane unsafe host super fast quickstart +## Where the modules come from - cd kernel_module - ./make-host.sh - -If the compilation of any of the C files fails, e.g. because of kernel or toolchain differences that we don't control on the host, just rename it to remove the `.c` extension and try again: - - mv broken.c broken.c~ - ./build_host - -Once you manage to compile, try it out with: - - sudo insmod hello.ko - - # Our module is there. - sudo lsmod | grep hello - - # Last message should be: hello init - dmest -T - - sudo rmmod hello - - # Last message should be: hello exit - dmesg -T - - # Not present anymore - sudo lsmod | grep hello - -Why this is very bad and you should be ashamed: - -- bugs can easily break you system. E.g.: - - segfaults can trivially lead to a kernel crash, and require a reboot - - your disk could get erased. Yes, this can also happen with `sudo` from userland. But you should not use `sudo` when developing newbie programs. And for the kernel you don't have the choice not to use `sudo` - - even more subtle system corruption such as [not being able to rmmod](https://unix.stackexchange.com/questions/78858/cannot-remove-or-reinsert-kernel-module-after-error-while-inserting-it-without-r) -- can't control which kernel version and build options to use. So some of the modules may simply not compile because of kernel API changes, since [the Linux kernel does not have a stable kernel module API](https://stackoverflow.com/questions/37098482/how-to-build-a-linux-kernel-module-so-that-it-is-compatible-with-all-kernel-rele/45429681#45429681). -- can't control which hardware is used, notably the CPU architecture -- can't step debug it with GDB easily - -The only advantage of using your host machine is that you don't have to wait some minutes / hours for the first build and waste a few Gigs of disk space. But you will soon find out that this is a very reasonable price to pay. - -## Do the right thing and use a virtual machine - -Reserve 12Gb of disk: - - 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 ([GCC](https://stackoverflow.com/questions/10833672/buildroot-environment-with-host-toolchain), Linux kernel), e.g.: - -- 2 hours on a mid end 2012 laptop -- 30 minutes on a high end 2017 desktop - -QEMU opens up, and you can run: - - 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. - -Each module comes from a C file under `kernel_module/`. For module usage see: +Each module comes from a C file under the [`kernel_module` directory]((kernel_module/). For module usage see: head kernel_module/modulename.c diff --git a/run-on-host.md b/run-on-host.md new file mode 100644 index 0000000..0385bf5 --- /dev/null +++ b/run-on-host.md @@ -0,0 +1,41 @@ +# Run on host + +This method runs the kernel modules directly on your host computer without a VM, and saves you the compilation time and disk usage of the virtual machine method. + +It has however severe limitations, and you will soon see that the time and disk usage are well worth it: + +- can't control which kernel version and build options to use. So some of the modules will likely not compile because of kernel API changes, since [the Linux kernel does not have a stable kernel module API](https://stackoverflow.com/questions/37098482/how-to-build-a-linux-kernel-module-so-that-it-is-compatible-with-all-kernel-rele/45429681#45429681). +- bugs can easily break you system. E.g.: + - segfaults can trivially lead to a kernel crash, and require a reboot + - your disk could get erased. Yes, this can also happen with `sudo` from userland. But you should not use `sudo` when developing newbie programs. And for the kernel you don't have the choice not to use `sudo` + - even more subtle system corruption such as [not being able to rmmod](https://unix.stackexchange.com/questions/78858/cannot-remove-or-reinsert-kernel-module-after-error-while-inserting-it-without-r) +- can't control which hardware is used, notably the CPU architecture +- can't step debug it with GDB easily + +Still interested? + + cd kernel_module + ./make-host.sh + +If the compilation of any of the C files fails because of kernel or toolchain differences that we don't control on the host, just rename it to remove the `.c` extension and try again: + + mv broken.c broken.c~ + ./build_host + +Once you manage to compile, and have come to terms with the fact that this may blow up your host, try it out with: + + sudo insmod hello.ko + + # Our module is there. + sudo lsmod | grep hello + + # Last message should be: hello init + dmest -T + + sudo rmmod hello + + # Last message should be: hello exit + dmesg -T + + # Not present anymore + sudo lsmod | grep hello