diff --git a/README.adoc b/README.adoc index 5ebb3ff..6d930f8 100644 --- a/README.adoc +++ b/README.adoc @@ -9,31 +9,35 @@ :toclevels: 6 :toc-title: -Run one command, get a QEMU or gem5 Buildroot BusyBox virtual machine built from source with several minimal Linux kernel 4.18 module development example tutorials with <> and <> step debugging and minimal educational hardware device models. "Tested" in x86, ARM, Ubuntu 18.04 host. +Run one command, get a QEMU or gem5 Buildroot BusyBox virtual machine built from source with several minimal Linux kernel 4.18 module development example tutorials with <> and <> step debugging and minimal educational hardware device models. "Tested" in Ubuntu 18.04 host, x86 and ARM guests. + +TLDR: <> toc::[] == About -This project is made to help me study, modify and test low level system components by using system simulators. +This project was created to help me understand, modify and test low level system components by using system simulators. -The current focuses are: +System simulators are cool because they are free, make everything highly reproducible, and give full visibility to the system. + +The current components we focus the most on are: * Linux kernel and Linux kernel modules -* full systems emulators, currently <> and <> +* full systems emulators, currently <> and <> * <>. We use and therefore document, a large part of its feature set. -This setup could also be easily extended to cover: +but this setup could be of great benefit for: * C standard libraries * compilers -This provides setups that are: +The design goal is to provide setups that are: * highly automated: "just works" * thoroughly documented: you know what "just works" means * can be fully built from source: to give visibility and allow modifications -* can also use prebuilt binaries: in case you are lazy or unable to build from source +* can also use prebuilt binaries as much as possible: in case you are lazy or unable to build from source === Fairy tale @@ -65,11 +69,11 @@ There are several different possible setups to use this repo. Each child section of this section describes one of those setups, and the trade-offs of each. -If you don't know which one to go for, start with <> +If you don't know which one to go for, start with <>. The trade-offs are basically a balance between: -* how long and how much disk space does the build and run take +* speed ans size; how long and how much disk space do the build and run take? * visibility: can you GDB step debug everything and read source code? * modifiability: can you modify the source code and rebuild a modified version? * portability: does it work on a Windows host? Could it ever? @@ -79,9 +83,9 @@ The trade-offs are basically a balance between: === QEMU Buildroot setup -This is the best setup if you are on one of the supported systems: Ubuntu 16.04 or Ubuntu 18.04. +This is the best setup if you are on Ubuntu. We tend to test this repo the most on the latest Ubuntu, and on the latest Ubuntu LTS. -Everything will likely also work on other Linux distros if you install the analogous required packages for your distro from link:configure[], but this is not currently well tested. Compatibility patches are welcome. You can also try <> if you are on other Linux distros. +Everything will likely also work on other Linux distros if you install the analogous required packages for your distro from link:configure[], but this is not currently well tested. Compatibility patches are welcome. You can also try <> if you are on other Linux distros. Native Windows is unlikely feasible because Buildroot is a huge set of GNU Make scripts + host tools, just use an Ubuntu VM in that case. Reserve 12Gb of disk and run: @@ -196,11 +200,6 @@ hello /root/.profile │(gdb) .... -We tend to support the following Ubuntu host versions at least: - -* if the latest release is an LTS, support both the latest LTS and the previous one -* otherwise, support both latest LTS and the latest non-LTS - ==== About the QEMU Buildroot setup link:https://en.wikipedia.org/wiki/Buildroot[Buildroot] is a set of `make` scripts that downloads from source and compiles compatible versions of: