From edc7ef3bb95188a8b4d711087904fdf385e1c209 Mon Sep 17 00:00:00 2001 From: Simon Pickartz Date: Wed, 7 Sep 2016 11:04:28 +0200 Subject: [PATCH] one line per sentence in README --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f8238731a..2135dcd07 100644 --- a/README.md +++ b/README.md @@ -30,27 +30,50 @@ On Debian-based systems the packets can be installed by executing: 0. Please make sure that you cloned this repository and all its submodules. 1. The build process works currently only on x86-based Linux systems. -2. To configure the system, run the *configure* script in the directory, which contains this *README*. Fine tuning of the installation directories, e.g., with the flag `--prefix` is currently not supported. HermitCore, the cross-compiler and the demo applications will be installed in subdirectories of this repository. At the end of this *README* in section *Tips* you find hints to enable optimization for the target. +2. To configure the system, run the *configure* script in the directory, which contains this *README*. + Fine tuning of the installation directories, e.g., with the flag `--prefix` is currently not supported. + HermitCore, the cross-compiler and the demo applications will be installed in subdirectories of this repository. + At the end of this *README* in section *Tips* you find hints to enable optimization for the target. 3. The command `make` build the Linux kernel, the HermitCore kernel, the cross-compiler, and the demo applications. -4. To start a virtual machine and to boot a small Linux version use the command `make qemu`. Per default, the virtual machine has 10 cores, 2 NUMA nodes, and 8 GiB RAM. To increase or to decrease the machine size, the label `qemu` in the Makefile has to be modified accordingly. -5. Inside the VM runs a small Linux system, which already includes the patches for HermitCore. Per NUMA node (= HermitCore isle) there is a directory called `isleX` under `/sys/hermit` , where `X` represents the NUMA node ID. The demo applications are located in the directories `/hermit/usr/{tests,benchmarks}`. A HermitCore loader is already registered. By starting a HermitCore application, a proxy will be executed on the Linux system, while the HermitCore binary will be started on isle 0 with cpu 1. To change the default behavior, the environment variable `HERMIT_ISLE` is used to specify the (memory) location of the isle, while the environment variable `HERMIT_CPUS` is used to specify the cores. For instance, `HERMIT_ISLE=1 HERMIT_CPUS="3-5" /hermit/usr/tests/hello` starts a HelloWorld demo on the HermitCore isle 1, which uses the cores 3 to 5. The output messages are forwarded to the Linux proxy and printed on the Linux system. +4. To start a virtual machine and to boot a small Linux version use the command `make qemu`. + Per default, the virtual machine has 10 cores, 2 NUMA nodes, and 8 GiB RAM. + To increase or to decrease the machine size, the label `qemu` in the Makefile has to be modified accordingly. +5. Inside the VM runs a small Linux system, which already includes the patches for HermitCore. + Per NUMA node (= HermitCore isle) there is a directory called `isleX` under `/sys/hermit` , where `X` represents the NUMA node ID. + The demo applications are located in the directories `/hermit/usr/{tests,benchmarks}`. + A HermitCore loader is already registered. + By starting a HermitCore application, a proxy will be executed on the Linux system, while the HermitCore binary will be started on isle 0 with cpu 1. + To change the default behavior, the environment variable `HERMIT_ISLE` is used to specify the (memory) location of the isle, while the environment variable `HERMIT_CPUS` is used to specify the cores. + For instance, `HERMIT_ISLE=1 HERMIT_CPUS="3-5" /hermit/usr/tests/hello` starts a HelloWorld demo on the HermitCore isle 1, which uses the cores 3 to 5. + The output messages are forwarded to the Linux proxy and printed on the Linux system. 6. HermitCore's kernel messages of `isleX` are available via `cat /sys/hermit/isleX/log`. -7. There is a virtual IP device for the communication between the HermitCore isles and the Linux system (see output of `ifconfig`). Per default, the Linux system has the IP address `192.168.28.1`. The HermitCore isles starts with the IP address `192.168.28.2` for isle 0 and is increased by one for every isle. +7. There is a virtual IP device for the communication between the HermitCore isles and the Linux system (see output of `ifconfig`). + Per default, the Linux system has the IP address `192.168.28.1`. + The HermitCore isles starts with the IP address `192.168.28.2` for isle 0 and is increased by one for every isle. 8. More HermitCore applications are available at `/hermit/usr/{tests,benchmarks}` which is a shared directory between the host and QEmu. ## Building and testing HermitCore on a real machine *Note*: to launch HermitCore applications, root privileges are required. -1. In principle you have to follow the tutorial above. After the configuration (Step 2 in the [above tutorial](#building-and-testing-hermitcore-within-a-virtual-machine)) go to the subdirectory `linux`, which contains the source code of the Linux kernel. Configure the kernel with `make menuconfig` for your system. Be sure, that the option `CONFIG_HERMIT_CORE` in `Processor type and features` is enabled. +1. In principle you have to follow the tutorial above. + After the configuration (Step 2 in the [above tutorial](#building-and-testing-hermitcore-within-a-virtual-machine)) go to the subdirectory `linux`, which contains the source code of the Linux kernel. + Configure the kernel with `make menuconfig` for your system. + Be sure, that the option `CONFIG_HERMIT_CORE` in `Processor type and features` is enabled. 2. Go back to the root directory of this repository and build with `make` the Linux kernel, the HermitCore kernel, the cross-compiler, and the demo applications. -3. Install the Linux kernel and its initial ramdisk on your system (see descriptions of your Linux distribution). We recommend to disable Linux NO_HZ feature by setting the kernel parameter `no_hz=off`. This feature reduces partly the OS noise, but noise sensitive applications should now run on HermitCore. +3. Install the Linux kernel and its initial ramdisk on your system (see descriptions of your Linux distribution). + We recommend to disable Linux NO_HZ feature by setting the kernel parameter `no_hz=off`. + This feature reduces partly the OS noise, but noise sensitive applications should now run on HermitCore. -4. Register the HermitCore loader at your system with following command: `echo ":hermit:M:7:\\x42::/path2proyxy/proxy:" > /proc/sys/fs/binfmt_misc/register`, in which `path2proxy` defines the path to the loader. You find the loader `proxy` after building the HermiCore sources in the subdirectory `hermit/tools` of the directory, which contains this *README*. -5. The IP device between HermitCore and Linux currently does not support IPv6. Consequently, disable IPv6 by adding following line to `/etc/sysctl.conf`: `net.ipv6.conf.mmnif.disable_ipv6 = 1`. -6. Per default, the IP device uses a static IP address range. Linux has to use `162.168.28.1`, where HermitCore isles start with `192.168.28.2` (isle 0). The network manager must be configured accordingly and therefore the file `/etc/sysconfig/network-scripts/ifcfg-mmnif` must be created with the following content: +4. Register the HermitCore loader at your system with following command: `echo ":hermit:M:7:\\x42::/path2proyxy/proxy:" > /proc/sys/fs/binfmt_misc/register`, in which `path2proxy` defines the path to the loader. + You find the loader `proxy` after building the HermiCore sources in the subdirectory `hermit/tools` of the directory, which contains this *README*. +5. The IP device between HermitCore and Linux currently does not support IPv6. + Consequently, disable IPv6 by adding following line to `/etc/sysctl.conf`: `net.ipv6.conf.mmnif.disable_ipv6 = 1`. +6. Per default, the IP device uses a static IP address range. + Linux has to use `162.168.28.1`, where HermitCore isles start with `192.168.28.2` (isle 0). + The network manager must be configured accordingly and therefore the file `/etc/sysconfig/network-scripts/ifcfg-mmnif` must be created with the following content: ``` DEVICE=mmnif BOOTPROTO=none @@ -70,7 +93,8 @@ HermitCore applications can be directly started as standalone kernel within a vi In this case, [iRCCE](http://www.lfbs.rwth-aachen.de/publications/files/iRCCE.pdf) is not supported. Please register the loader the same way as done for the multi-kernel version of HermitCore (see Step 4 in [*Building and testing HermitCore on a real machine*](#building-and-testing-hermitcore-on-a-real-machine)). If the environment variable `HERMIT_ISLE` is set to `qemu`, the application will be started within a VM. -Please note that the loader requires QEMU and uses per default *KVM*. Furthermore, it expects that the executable is called `qemu-system-x86_64`. +Please note that the loader requires QEMU and uses per default *KVM*. +Furthermore, it expects that the executable is called `qemu-system-x86_64`. You can adapt the name by setting the environment variable `HERMIT_QEMU`. In this context, the environment variable `HERMIT_CPUS` specifies the number of cpus (and no longer a range of core ids). @@ -91,6 +115,11 @@ HERMIT_ISLE=qemu HERMIT_CPUS=4 HERMIT_MEM=6G hermit/usr/benchmarks/stream ## Tips -1. The configuration flag `--with-mtune=name` specifies the name of the target processor for which GCC should tune the performance of the code. You can use any architecture name, which is supported by GCC. For instance, `--with-mtune=native` optimzes the code for the host system. Please note, if the applications is started within a VM, the hypervisor has to support the specified architecture name. If KVM is started by our proxy, per default the host architecture will be used as target processor. -2. If KVM is started by our proxy and the environment variable `HERMIT_KVM` is set to `0`, the virtual machine will be not accelerated by KVM. In this case, the configuration flag `--with-mtune=name` should be avoided. +1. The configuration flag `--with-mtune=name` specifies the name of the target processor for which GCC should tune the performance of the code. + You can use any architecture name, which is supported by GCC. + For instance, `--with-mtune=native` optimzes the code for the host system. + Please note, if the applications is started within a VM, the hypervisor has to support the specified architecture name. + If KVM is started by our proxy, per default the host architecture will be used as target processor. +2. If KVM is started by our proxy and the environment variable `HERMIT_KVM` is set to `0`, the virtual machine will be not accelerated by KVM. + In this case, the configuration flag `--with-mtune=name` should be avoided. 3. By setting the environment variable `HERMIT_VERBOSE` to `1`, the proxy prints at termination the kernel log messages onto the screen.