stv0g/metalsvm
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity
metalsvm/documentation/text/compilation.dox
Jacek Galowicz 120500b5cb Translated the documentation from the L2P into english and put them into 
the Doxygen documentation.

Documenters can just put *.dox files into the documentation/text/
directory which describe how to do things with MetalSVM.
making_coffee.dox is still missing - anyone?
2011-11-08 13:58:29 +01:00

141 lines
7.3 KiB
Text
Raw Blame History

/**
* @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 gitosis@git.lfbs.rwth-aachen.de:metalsvm.git \endverbatim
*
* 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:
*
* \verbatim
$ cd MetalSVM
$ cp Makefile.example Makefile
$ cp include/metalsvm/config.h.example include/metalsvm/config.h \endverbatim
*
* 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:
* \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
*
* 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:
* \verbatim$ . /opt/compilerSetupFiles/crosscompile.sh \endverbatim
* -# The Makefile needs to be adapted to actually use the cross compiler:
* \verbatim
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 \endverbatim
* -# 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:
* \verbatim
//#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 \endverbatim
* -# There is only one core per tile, so it is adequate to reduce overhead by disabling SMP in MetalSVM:
* \verbatim#define MAX_CORES 1 \endverbatim
* -# Cache-line size is 32 byte:
* \verbatim#define CACHE_LINE 32 \endverbatim
* -# 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.
* -# The \c scc_bootinfo.asm file contains boot-information relevant to the SCC-cores.
* It is generated automatically by the \c bootinfo.sh script.\n
* \n
* The following example generates the \c scc_bootinfo.asm file needed for use of the cores 0 and 1:
* \verbatim$ ./bootinfo.sh 0x01000000 initrd.img 2 533 0 1 > scc_bootinfo.asm \endverbatim
* Parameters describe the following:
* -# First parameter describes the address at which the initrd shall be located at later
* -# Second is path to the initrd image file
* -# The other parameters are analogous to RCCE-App-parameters. This example starts MetalSVM on cores 0 and 1, clocked with 533MHz.
* -# Now the file \c metalsvm.mt has to be edited. It defines the layout of the memory image (Where the kernels will be located in the memory later). For the example from above it looks like the following:
* \verbatim# pid mch-route mch-dest-id mch-offset-base testcase
0x00 0x00 6 0x00 metalsvm.obj
0x01 0x00 6 0x01 metalsvm.obj \endverbatim
* This locates two instances of MetalSVM on core 0 and 1, supplied with memory from memory controller 0. See \c sccMerge \c -h for more information.
* -# The final image must be generated then with \code$ make SCC\endcode
* -# 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 0x00 0x01\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
*
*
*/
Reference in a new issue View git blame Copy permalink