metalsvm/documentation/text/compilation.dox

/**
 * @file compilation.dox
 * @page compilation Compiling and Running MetalSVM
 *
 * @section toc Table of Contents
 * - @ref checkout
 * - @ref compiling
 * - @ref runqemu
 * - @ref runscc
 * - @ref runsccmc
 * - @ref msvmuart
 *
 * @section checkout Checking out MetalSVM online
 * 
 * The MetalSVM project is hosted in a Git repository. To check it out, just type:
 *
 * \verbatim$ git clone git://git.lfbs.rwth-aachen.de/metalsvm.git \endverbatim
 *
 * @section compiling Compiling MetalSVM
 *
 * To compile MetalSVM, you will need a proper Makefile and configuration. 
 * To use the example files, just do the following:
 *
 * \verbatim 
$ cd MetalSVM
$ cp Makefile.example Makefile
$ (cd include/metalsvm; cp config.h.example config.h) \endverbatim
 * 
 * The standard configuration works on usual PC hardware configurations as well as in emulators.
 * There are also preconfigured example configs for the Intel SCC: `Makefile.scc` and `config.h.scc`.
 *
 * Compiler settings can be edited in the Makefile, while the kernel configuration can be 
 * found in the configuration header file.
 *
 * @section runqemu Running MetalSVM in Qemu
 *
 * There is a Make-target for running MetalSVM in Qemu:
 * \verbatim$ make qemu \endverbatim
 *
 * The emulator is then started with the following parameters:
 * \verbatim$ qemu -monitor stdio -smp 2 -net nic,model=rtl8139 -net user,hostfwd=tcp::12345-:7 -net dump -kernel metalsvm.elf -initrd tools/initrd.img \endverbatim
 *
 * @section runscc Running MetalSVM on the Intel SCC
 *
 * -# Although Intel provides a special older GCC version for compiling code for the Intel SCC,
 *    the MetalSVM project switched to the current standard GCC. You don't need to source
 *    the cross compiler script which might be installed on your MCPC.
 * -# An important change in the Makefile is disabling the "-fno-stack-protector" option. It occurs several times. This has already been done for you if you use `Makefile.scc`.
 * -# The SCC requires a special configuration for the MetalSVM kernel (Already been done
 *    if you use `config.h.scc`):
 *  \code
//#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 \endcode
 * -# There is only one core per tile, so it is adequate to reduce overhead by disabling SMP in MetalSVM:
 * \code#define MAX_CORES               1 \endcode
 * -# Cache-line size is 32 byte:
 * \code#define CACHE_LINE              32 \endcode
 * -# MetalSVM can now be built using \c make.
 * -# Build the SCC tools:
 *  \verbatim
$ cd tools
$ make SCC \endverbatim
*   
 * -# The \c obj directory was just created, containing the MetalSVM kernel image. It can be loaded into the SCC's memory using \verbatim$ sccBoot -g obj \endverbatim
 * -# The default configuration lets MetalSVM run only on core 0. Its reset pin needs to be released:
 *  \verbatim$ sccReset -r 0x00 \endverbatim
 * -# Although the display driver was deactivated, MetalSVM's kprintf-output is written into the memory, where you can read it with the following command:
 *  \verbatim$ sccDump -d 0x00 0x100000 0x10000 | less \endverbatim
 *
 *
 * @section runsccmc Running MetalSVM on multiple SCC cores
 *
 * -# Build the kernel like described above (items 1-7) and change to the \c tools directory.
 * -# Now the file \c metalsvm.mt can be edited, depending on how many cores you want MetalSVM running. 
 *    Just remove the cores which shall be unaffected. Having a slim \c metalsvm.tm accelerates the build procedure.
 * -# The final image must be generated then with \code$ make SCC CORENUM=48\endcode
 *    where `CORENUM` is set to the actual number of cores which shall work together later.
 * -# A directory \c obj was created, containing the final MetalSVM Image. This image can now be loaded with the following command: \code$ sccBoot -g obj\endcode
 * -# Everything has been placed in the cores' memory. To release the reset pins of the corresponding cores, type \code$ sccReset -r 0 1 2 3 ...\endcode
 *
 * @section msvmuart Enabling UART support
 *
 * MetalSVM is able to reroute terminal output to port \c 0x2F8. This way it can be displayed in \c sccGui. Too much output stresses the network load, therefore it should be used for debugging purposes only.
 *
 * How to enable:
 * -# Enable UART-support in the kernel's config file \c include/metalsvm/config.h:
 *  \code#define CONFIG_UART\endcode
 * -# Rebuild the kernel. Do not launch it with \c sccBoot - In the following \c sccGui will be used.
 * -# Launch \c sccGui.
 * -# Enable UART in the gui by klicking <tt>Enable software RAM and UART</tt> in the Menu <tt>Settings/Debug Settings</tt>.
 * -# Issue a software interrupt by clicking on the wiper symbol.
 * -# Choose the memory image called \c mch_0_0.32.obj from the \c obj folder with <tt>Preload object file</tt>.
 * -# Initialize the LUT with <tt>Preload LUT file</tt>. It is called \c lut_init.dat and is located in the same directory.
 * -# Both L2 cache and MPB can be reset now, if needed.
 * -# Activate the corresponding cores with <tt>Change selected reset(s)</tt>. This opens the following window:
 *    @image html reset.png
 * -# A box being checked means that the reset pin is pulled and the core is \e inactive. The example from the picture will boot MetalSVM only on cores 0 and 1.
 *
 *  After following these steps successfully, a similar image to the following should appear on the gui:
 *  @image html sccGui.png
 *
 *  Another window will be opened automatically as soon as UART output arrives in the gui. This will be similar to the following:
 *  @image html uart.png
 *
 *
 */