Changes between Initial Version and Version 1 of Arch/Soclib/Tutorial

Timestamp:

Dec 3, 2009, 12:57:49 PM (16 years ago)

Author:

Nicolas Pouillon

Comment:

--

Arch/Soclib/Tutorial

@@ +1 @@
+= MutekH tutorial for SoCLib platform =
+
+This guide explain how to run MutekH on a [wiki:Arch/Soclib SoCLib] hardware simulator.
+This is allow easy experimentation with advanced multi-processor programming.
+
+You are '''highly encouraged''' to first follow the [wiki:QuickStartUnix MutekH as Unix process quick start guide]
+which introduces more basic concepts.
+
+MutekH for SoCLib can be compiled for Mips, Arm, PowerPC processors.
+Other processors are available with different platforms.
+
+== The SoCLib platform ==
+
+The MutekH kernel source code is fully configurable and can be tweaked to adapt hardware platform
+and application needs. Configuration is handled by a dedicated tool which check dependencies and
+other relationships between the large set of available configuration tokens.
+
+The example below explains how to setup a SoCLib hardware simulator with 4 RISC processor (Mips, Arm or PowerPC).
+
+[[BR]][[BR]][[Image(arch.png,nolink)]][[BR]][[BR]]
+
+=== Getting SoCLib ===
+
+We now need to have a working SoCLib install. SoCLib installation is explained here: https://www.soclib.fr/trac/dev/wiki/InstallationNotes
+
+=== SoCLib platform description ===
+
+The SoCLib source tree contains a platform dedicated to this tutorial:
+{{{soclib/soclib/platform/topcells/caba-vgmn-mutekh_soclib_tutorial/}}}
+
+=== Getting the cross-compilers ===
+
+SoCLib installation nodes already provides a way to get cross-compiler, if you don't already have them, MutekH holds a tool
+to build a complete cross-compilation toolchain:
+
+The script is in [source:trunk/mutekh/tools/crossgen.mk@1183 tools/crossgen.mk]:
+{{{
+ $ tools/crossgen.mk
+[prints some help]
+ $ tools/crossgen.mk all TARGET=mipsel-unknown-elf
+}}}
+
+== The MutekH part ==
+
+=== Getting the sources ===
+
+{{{
+svn co -r 1183 https://www-asim.lip6.fr/svn/mutekh/trunk/mutekh
+}}}
+
+=== Writing the example source code ===
+
+Note: This example is available directly from [source:trunk/mutekh/examples/hello@1183 examples/hello] directory in source tree.
+
+ * Writing the source code in `hello.c`
+{{{
+#include <pthread.h>
+
+pthread_mutex_t m;
+pthread_t a, b;
+
+void *f(void *param)
+{
+  while (1)
+    { 
+      pthread_mutex_lock(&m);
+      printf("(%i) %s", cpu_id(), param);
+      pthread_mutex_unlock(&m);
+      pthread_yield();
+    }
+}
+int main()
+{
+  pthread_mutex_init(&m, NULL);
+  pthread_create(&a, NULL, f, "Hello ");
+  pthread_create(&b, NULL, f, "World\n");
+}
+}}}
+
+ * Writing the `Makefile`
+{{{
+objs = hello.o
+}}}
+
+
+=== Writing the MutekH configuration ===
+
+The MutekH configuration for the 4 Mips processors platform is in the [source:trunk/mutekh/examples/hello/config examples/hello/config] file.
+
+This file only holds information about the application (here a simple pthread application) and relies upon files in the [source:trunk/mutekh/examples/common@1183 examples/common] directory for the platform definitions.
+
+Have a look to the BuildSystem page for more information about configuration system and configuration file format.
+
+The [http://www.mutek.fr/www/mutekh_api/ MutekH API reference manual] describes all available configuration tokens.
+
+=== Platform description ===
+
+The MutekH software uses hardware enumeration to get details about available hardware in the platform, so the `CONFIG_ARCH_DEVICE_TREE` token is defined in the [source:trunk/mutekh/examples/common/platforms-soclib.conf@1183 examples/common/platforms-soclib.conf] configuration file. It will let the kernel get the platform layout description from a FlattenedDeviceTree which will be built into the kernel.
+
+Therefore, the build also compiles the correct FlattenedDeviceTree from the platform name.
+
+The current FlattenedDeviceTree source file is
+[source:trunk/mutekh/examples/common/pf_soclib_tutorial_ppc.dts examples/common/pf_soclib_tutorial_ppc.dts],
+[source:trunk/mutekh/examples/common/pf_soclib_tutorial_arm.dts (for arm)],
+[source:trunk/mutekh/examples/common/pf_soclib_tutorial_mips.dts (for mips)].
+
+=== Compiling the application along with MutekH ===
+
+The MutekH kernel and the application may be built out of the source tree.
+
+Change to the SoCLib platform directory and apply the following steps to experiment
+with out of tree compilation. You have to setup the following variables:
+
+ `MUTEKH_DIR`::
+   Path to MutekH source tree
+ `APP`::
+   Path to application source
+ `CONFIG`::
+   MutekH configuration file name
+ `BUILD`::
+   MutekH build option list (target architecture, cpu type, …)
+
+See the `config.mk` file in the tutorial platform directory for more information.
+
+{{{
+$ cd soclib/soclib/platform/topcells/caba-vgmn-mutekh_soclib_tutorial
+$ make MUTEKH_DIR=/path/to/mutekh
+}}}
+
+This will build the MutekH kernel along with the application.
+You can still build MutekH separately as explained in the first part. The simulator can then be built using:
+
+{{{
+$ cd soclib/soclib/platform/topcells/caba-vgmn-mutekh_tutorial
+$ make system.x
+}}}
+
+== Execution ==
+
+You can optionally pass an alternative kernel to the simulator, but this defaults to the correct kernel name if you followed the tutorial until here.
+{{{
+$ ./system.x mutekh/kernel-soclib-ppc.out
+}}}
+
+You may want to refer to other articles and documents available from the main page to go further with MutekH.
+
+The [soclib:wiki: SoCLib] home page provides a livecd image with more advanced examples ready to compile and run. These examples are using older MutekH revisions though.
+
+Other more advanced topics and guides are available from the [wiki: Main page].