From ffc7064baaf75a48dae639b244046a819a613a52 Mon Sep 17 00:00:00 2001
From: Jacek Galowicz <jacek.galowicz@rwth-aachen.de>
Date: Mon, 24 Oct 2011 23:55:53 +0200
Subject: [PATCH] Enabled the Doxygen configuration to greedily take any
 documentation page it finds to embedd it into the HTMl-documentation.

Started to adopt the compiling tutorial from L2P.
---
 Doxyfile                           |  2 +-
 documentation/text/compilation.dox | 94 ++++++++++++++++++++++++++++--
 2 files changed, 90 insertions(+), 6 deletions(-)

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.
+ * <pre>$ git clone gitosis\@git.lfbs.rwth-aachen.de:metalsvm.git</pre>
  *
- * @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:
+ *
+ * <pre>
+ * $ cd MetalSVM
+ * $ cp Makefile.example Makefile
+ * $ cp include/metalsvm/config.h.example include/metalsvm/config.h
+ * </pre>
+ * 
+ * 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:
+ * <pre>make qemu</pre>
+ *
+ * The emulator is then started with the following parameters:
+ * <pre>qemu -monitor stdio -smp 2 -net nic,model=rtl8139 -net user,hostfwd=tcp::12345-:7 -net dump -kernel metalsvm.elf -initrd tools/initrd.img</pre>
+ *
+ * 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:
+ *  <pre>. /opt/compilerSetupFiles/crosscompile.sh</pre>
+ * -# The Makefile needs to be adapted to actually use the cross compiler:
+ *  <pre>
+ *  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
+ *  </pre>
+ * -# 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:
+ *  <pre>
+ *  //\#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
+ *  </pre>
+ * -# There is only one core per tile, so it is adequate to reduce overhead by disabling SMP in MetalSVM:
+ *  <pre>
+ *  \#define MAX_CORES               1
+ *  </pre>
+ * -# Cache-line size is 32 byte:
+ *  <pre>
+ *  \#define CACHE_LINE              32
+ *  </pre>
+ * -# MetalSVM can now be built using <span style="font-family:courier new">make</span>.
+ * -# Build the SCC tools:
+ *  <pre>
+ *  $ cd tools
+ *  $ make SCC
+ *  </pre>
+ * -# The <span style="font-family:courier new">obj</span> directory was just created, containing the MetalSVM kernel image. It can be loaded into the SCC's memory using <pre>sccBoot -g obj</pre>
+ * -# The default configuration lets MetalSVM run only on core 0. Its reset pin needs to be released:
+ *  <pre>sccReset -r 0x00</pre>
+ * -# Although the display driver was deactivated, MetalSVM's kprintf-output is written into the memory, where you can read it with the following command:
+ *  <pre>sccDump -d 0x00 0x100000 0x10000 | less</pre>
+ *  There is also a script called <i>prettydump</i> in the /shared/shared folder.
+ *  
  *
  */