Changes between Version 20 and Version 21 of QuickStartSoclib


Ignore:
Timestamp:
Nov 25, 2009, 2:48:32 PM (14 years ago)
Author:
becoulet
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • QuickStartSoclib

    v20 v21  
    11= MutekH quick start guide for SoCLib platform =
    2 ----
    32
    4 This quickstart guide only present 2 target plaforms among those supported by MutekH.
    5 These platforms are linux/darwin user process and the SoCLib hardware simulator.
    6 Other supported platforms are multiprocessors IBMPC/x86 and some micro-controllers.
     3This guide explain how to run MutekH on a [wiki:Arch/Soclib SoCLib] hardware simulator. This is allow easy experimentation with advanced multi-processor programming.
    74
    8 [[Image(mutekh_overview.gif,nolink)]]
     5You are '''highly encouraged''' to first follow the [wiki:QuickStartUnix MutekH as Unix process quick start guide] which introduce more basic concepts.
    96
    10 MutekH can be compiled for Mips, Arm, PowerPC, x86 and Avr porcessors.
     7MutekH for SoCLib can be compiled for Mips, Arm, PowerPC processors. Other processors are available with different platforms.
    118
    12 = MutekH configurations =
     9== The SoCLib platform ==
    1310
    1411The MutekH kernel source code is fully configurable and can be tweaked to adapt hardware platform
     
    1613other relationships between the large set of available configuration tokens.
    1714
    18 This document present two source code configurations:
     15The example below explains how to setup a SoCLib hardware simulator with 4 RISC processor (Mips, Arm or PowerPC).
    1916
    20  1. A first MutekH build designed to run embedded in a unix process.
    21     [[BR]][[BR]][[Image(mutekh_overview_emu.gif,nolink)]][[BR]][[BR]]
    22     This is the simplest way to have MutekH running as it does not need extra hardware or simulator.
    23     It enables running MutekH natively on the host processor. This configuration suffer from several
    24     limitations regarding available peripheral, but it is usefull to test and debug algorithms.
    25     [[BR]][[BR]][[Image(arch_emu.gif,nolink)]][[BR]][[BR]]
    26     The first example below show how to run MutekH using this configuration.
     17[[BR]][[BR]][[Image(arch_4proc.gif,nolink)]][[BR]][[BR]]
    2718
    28  2. The second example below explain how to setup a SoCLib hardware simulator with 4 RISC processor (Mips, Arm or PowerPC).
    29     [[BR]][[BR]][[Image(arch_4proc.gif,nolink)]][[BR]][[BR]]
     19=== Getting SoCLib ===
    3020
    31 = Part 1 : Running MutekH in a UNIX process =
     21We now need to have a working SoCLib install. SoCLib installation is explained here: https://www.soclib.fr/trac/dev/wiki/InstallationNotes
    3222
    33 This first example only require to get the MutekH source code.
     23=== SoCLib platform description ===
    3424
    35 == Getting the sources ==
    36 
    37 {{{
    38 svn co -r 1024 https://www-asim.lip6.fr/svn/mutekh/trunk/mutekh
    39 }}}
    40 Source tree is organized this way:
    41 {{{
    42 mutekh
    43 |-- arch            contains hardware platforms modules for hexo
    44 |-- cpu             contains processors modules for hexo
    45 |-- doc             documentation
    46 |-- drivers         device and filesystem drivers
    47 |-- examples        Test and example programs
    48 |-- gpct            container library, available as a separate project
    49 |-- hexo            Hexo hardware abstraction layer
    50 |-- libc            standard C library
    51 |-- libm            standard math library
    52 |-- libnetwork      netwotk stack
    53 |-- libpthread      posix thread library
    54 |-- libvfs          virtual File System
    55 |-- mutek           hardware independant kernel code
    56 |-- scripts         build system scripts
    57 `-- tools           some usefull tools
    58 }}}
    59 
    60 More directories are actually available with other libraries and features.
     25The SoCLib source tree contains a platform dedicated to this tutorial:
     26{{{soclib/soclib/platform/topcells/caba-vgmn-mutekh_tutorial/}}}.
    6127
    6228== Writing the example source code ==
    6329
    64 Note: This example is available directly from {{{examples/hello}}} in source tree.
    65 
    66  - Creating a new modules directory
    67 {{{
    68 mkdir hello
    69 cd hello
    70 }}}
     30Note: This example is available directly from {{{examples/hello}}} directory in source tree: [source:trunk/mutekh/examples/hello]
    7131
    7232 - Writing the source code in `hello.c`
     
    10060}}}
    10161
    102 == Writing the MutekH configuration file ==
    103 
    104 Our configuration file is named `hello/config_emu`.
    105 Details about configuration file is explained later.
    106 This configuration file describe the following things:
    107  - The application license, used to check license consistency for modules in use,
    108  - The target hardware platform and processor
    109  - Use of the POSIX threads library
    110  - Use of terminal output
    111  - Declaration of a new "hello" modules
    112 
    113 The MutekH source code is split in modules. We now have to declare our new module to have it compiled along with the kernel by the build system. As modules may be located out of the source tree, we have to specify the module directory.
    114 
    115 {{{
    116 # Application license
    117   CONFIG_LICENSE_APP_LGPL
    118 
    119 # Platform types
    120   CONFIG_ARCH_EMU
    121 
    122 # Processor types
    123   CONFIG_CPU_X86_EMU
    124 
    125 # Mutek features
    126   CONFIG_PTHREAD
    127   CONFIG_MUTEK_CONSOLE
    128 
    129 # Device drivers
    130   CONFIG_DRIVER_CHAR_EMUTTY
    131 
    132 # Code compilation options
    133   CONFIG_COMPILE_DEBUG
    134 
    135 # New source code module to be compiled
    136   CONFIG_MODULES hello:%CONFIGPATH
    137 }}}
    138 
    139 == Compiling the application along with MutekH ==
    140 
    141 Simply type:
    142 {{{
    143 make CONF=hello/config_emu
    144 }}}
    145 
    146 Once the compilation process has finished, the executable binary is available:
    147 {{{
    148 kernel-emu-x86-emu.out
    149 }}}
    150 
    151 == Execution ==
    152 
    153 Simply execute the program as a normal unix executable:
    154 {{{
    155 $ ./kernel-emu-x86-emu.out
    156 (0) Hello (0) World
    157 (0) Hello (0) World
    158 (0) Hello (0) World
    159 (0) Hello (0) World
    160 ...
    161 }}}
    162 
    163 = Part2 : Running MutekH in a multiprocessor SoCLib simulator =
    164 
    165 == Getting SoCLib ==
    166 
    167 We now need to have a working SoCLib install. SoCLib installation is explained here: https://www.soclib.fr/trac/dev/wiki/InstallationNotes
    168 
    169 == SoCLib platform description ==
    170 
    171 The SoCLib source tree contains a platform dedicated to this tutorial:
    172 {{{soclib/soclib/platform/topcells/caba-vgmn-mutekh_tutorial/}}}.
    173 
    174 == Getting the cross-compilers ==
     62=== Getting the cross-compilers ===
    17563
    17664You can rely on the {{{tools/crossgen.mk}}} script which comes along with MutekH to build some GNU cross-toolchains:
     
    18068}}}
    18169
    182 == MutekH Configuration ==
    183 
    184 Note: This example is readily available in the `examples/hello` directory in the MutekH source tree.
     70=== Writing the MutekH configuration ===
    18571
    18672The MutekH configuration for the 4 Mips processors platform is in the [source:trunk/mutekh/examples/hello/config_soclib_mipsel] file.
    187 
    188 You may have noticed the processor definition change:
    189 we are now building for a 4 little-endian Mips processors platform.
    19073
    19174Have a look to the BuildSystem page for more information about configuration system and configuration file format.
    19275The [http://www.mutek.fr/www/mutekh_api/ MutekH API reference manual] describes all available configuration tokens.
    19376
    194 == Platform description ==
     77=== Platform description ===
    19578
    196 This hardware platform uses now hardware enumeration (plug and play), so the `CONFIG_ARCH_DEVICE_TREE` token is defined in the configuration file. It will let the kernel get the platform layout description from a FlattenedDeviceTree which will be built-in.
     79The 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 configuration file. It will let the kernel get the platform layout description from a FlattenedDeviceTree which will be built-in.
    19780
    19881Therefore, we have to provide the platform description FlattenedDeviceTree and add it to the Makefile to have it compiled in.
     
    20588The current FlattenedDeviceTree source file is [source:trunk/mutekh/examples/hello/platform-mips.dts].
    20689
    207 == Compiling the application along with MutekH ==
     90=== Compiling the application along with MutekH ===
    20891
    20992The MutekH kernel and the application may be built out of the source tree.
     
    242125
    243126The [https://www.soclib.fr/trac/dev/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.
     127
     128Other more advanced topics and guides are available from the [wiki: Main page].
     129