diff --git a/Doxyfile b/Doxyfile index b9126c9c..b7514d3d 100644 --- a/Doxyfile +++ b/Doxyfile @@ -606,7 +606,7 @@ INPUT = ./fs \ ./libkern \ ./mm \ ./tools \ - ./documentation/text/mainpage.dox + ./documentation/text # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/documentation/text/compilation.dox b/documentation/text/compilation.dox index 833cbf20..1c485a68 100644 --- a/documentation/text/compilation.dox +++ b/documentation/text/compilation.dox @@ -1,12 +1,96 @@ /** - * @file manual.dox - * @page manual Manual Contents + * @file compilation.dox + * @page compilation Compiling and Running MetalSVM * - * @section Readme + * @section checkout Checking out MetalSVM online + * + * The MetalSVM project is hosted in a Git repository. To check it out, just type: * - * This document contains some explanations about stuff. + *
$ git clone gitosis\@git.lfbs.rwth-aachen.de:metalsvm.git* - * @subsection Compiling + * If you are asked for a password you are not authorized to clone the repository. In this case you will need to get your public SSH key authorized. * + * @section Compiling Compiling MetalSVM + * + * To compile MetalSVM, you will need a proper Makefile and configuration. To use the example files, just do the following: + * + *
+ * $ cd MetalSVM + * $ cp Makefile.example Makefile + * $ cp include/metalsvm/config.h.example include/metalsvm/config.h + *+ * + * The standard configuration works on usual PC hardware configurations as well as in emulators. + * + * Compiler-settings can be edited in the Makefile, while the kernel configuration can be found in the just copied configuration file. + * + * @section runqemu Running MetalSVM in Qemu + * + * There is a Make-target for running MetalSVM in Qemu: + *
make qemu+ * + * The emulator is then started with the following parameters: + *
qemu -monitor stdio -smp 2 -net nic,model=rtl8139 -net user,hostfwd=tcp::12345-:7 -net dump -kernel metalsvm.elf -initrd tools/initrd.img+ * + * Please note that qemu versions 0.13 and 0.14 have a bug which keeps MetalSVM from booting properly. Used qemu-0.12.5 instead. + * + * @section runscc Running MetalSVM on the Intel SCC + * + * -# Intel recommends to use their cross-compiler for generating code which is guaranteed to be SCC-compatible. Just set the environment variables with the following command: + *
. /opt/compilerSetupFiles/crosscompile.sh+ * -# The Makefile needs to be adapted to actually use the cross compiler: + *
+ * CC_FOR_TARGET=i386-unknown-linux-gnu-gcc + * CXX_FOR_TARGET=i386-unknown-linux-gnu-g++ + * GCC_FOR_TARGET=i386-unknown-linux-gnu-gcc + * AR_FOR_TARGET=i386-unknown-linux-gnu-ar + * AS_FOR_TARGET=i386-unknown-linux-gnu-as + * LD_FOR_TARGET=i386-unknown-linux-gnu-ld + * NM_FOR_TARGET=i386-unknown-linux-gnu-nm + * OBJDUMP_FOR_TARGET=i386-unknown-linux-gnu-objdump + * OBJCOPY_FOR_TARGET=i386-unknown-linux-gnu-objcopy + * RANLIB_FOR_TARGET=i386-unknown-linux-gnu-ranlib + * STRIP_FOR_TARGET=i386-unknown-linux-gnu-strip + * READELF_FOR_TARGET=i386-unknown-linux-gnu-readelf + *+ * -# Another important change in the Makefile is disabling the "-fno-stack-protector" option. It occurs several times. + * -# The SCC requires a special configuration for the MetalSVM kernel: + *
+ * //\#define CONFIG_PCI + * //\#define CONFIG_VGA + * //\#define CONFIG_UART + * //\#define CONFIG_KEYBOARD + * //\#define CONFIG_MULTIBOOT + * \#define CONFIG_ROCKCREEK + * // RCCE specific flags + * \#define SCC + * \#define COPPERRIDGE + * \#define MS_BAREMETAL + * //\#define GORY + * \#define SHMADD + * \#define SHMDBG + * //\#define SHMADD_CACHEABLE + *+ * -# There is only one core per tile, so it is adequate to reduce overhead by disabling SMP in MetalSVM: + *
+ * \#define MAX_CORES 1 + *+ * -# Cache-line size is 32 byte: + *
+ * \#define CACHE_LINE 32 + *+ * -# MetalSVM can now be built using make. + * -# Build the SCC tools: + *
+ * $ cd tools + * $ make SCC + *+ * -# The obj directory was just created, containing the MetalSVM kernel image. It can be loaded into the SCC's memory using
sccBoot -g obj+ * -# The default configuration lets MetalSVM run only on core 0. Its reset pin needs to be released: + *
sccReset -r 0x00+ * -# Although the display driver was deactivated, MetalSVM's kprintf-output is written into the memory, where you can read it with the following command: + *
sccDump -d 0x00 0x100000 0x10000 | less+ * There is also a script called prettydump in the /shared/shared folder. + * * */