Changes between Version 16 and Version 17 of QuickStartSoclib


Ignore:
Timestamp:
Nov 14, 2009, 7:11:36 AM (14 years ago)
Author:
becoulet
Comment:

My taylor is rich

Legend:

Unmodified
Added
Removed
Modified

  • QuickStartSoclib

    v16 v17  
    22----
    33
    4 Dans le cadre du projet SoCLib/ANR seules ces deux types de configuration sont documentées.
    5 D'autres configurations sont possibles dont, par exemple, celle adaptée aux cartes mères de PC/x86.
    6 Elles ne sont pas documentées ici, mais sont présentent dans le dépot svn de MutekH.
     4This quickstart guide only present 2 target plaforms among those supported by MutekH.
     5These platforms are linux/darwin user process and the SoCLib hardware simulator.
     6Other supported platforms are multiprocessors IBMPC/x86 and some micro-controllers.
    77
    88[[Image(mutekh_overview.gif,nolink)]]
    99
    10 MutekH est compilable sur plusieurs processeurs de la bibliothèque SoCLib comme
    11 le Mips et le PowerPC. Il est également compilable sur intel X86 en natif ou en
    12 émulation dans un processus Unix.
    13 
    14 = Les configurations de MutekH =
    15 
    16 MutekH est entièrement configurable pour s'adapter à la fois au matériel sur lequel il s'exécute mais aussi aux besoins de
    17 l'application.
    18 Il existe une centaine de paramètres permettant de définir une configuraion.
    19 Chaque paramètre peut prendre plusieurs valeurs.
    20 Les paramètres ne sont pas indépandants les uns vis à vis des autres, deux paramètres peuvent s'exclure ou dépendre l'un de
    21 l'autre.
    22 MutekH facilite la définition d'une configuration en vérifiant les règles de dépendances et la cohérences des valeurs.
    23 
    24 Dans ce document nous allons voir deux configurations.
    25 
    26  1. Une configuration pour une plateforme x86 émulée dans un processus unix.
     10MutekH can be compiled for Mips, Arm, PowerPC, x86 and Avr porcessors.
     11
     12= MutekH configurations =
     13
     14The MutekH kernel source code is fully configurable and can be tweaked to adapt hardware platform
     15and application needs. Configuration is handled by a dedicated tool which check dependencies and
     16other relationships between the large set of available configuration tokens.
     17
     18This document present two source code configurations:
     19
     20 1. A first MutekH build designed to run embedded in a unix process.
    2721    [[BR]][[BR]][[Image(mutekh_overview_emu.gif,nolink)]][[BR]][[BR]]
    28     L'intérêt de cette plateforme est qu'elle permet de mettre au point une application en bénéficiant des performances de
    29     la machine hôte. Elle permet également d'exécuter une application sans que l'installation de SoCLib ne soit nécessaire.
    30     L'inconvénient est que le seul périphérique disponible est le terminal.
     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.
    3125    [[BR]][[BR]][[Image(arch_emu.gif,nolink)]][[BR]][[BR]]
    32     Les premières applications de ce document utilisent cette configuration. Au delà de son aspect jouet, cette configuration est utile à chaque fois que l'on
    33     s'intéresse à la mise au point d'un algorithme et que l'on a pas besoin de coprocesseurs, ni d'interruption.
    34 
    35  2. Une configuration pour un cluster à 4 processeurs (Mips ou PowerPC) autour d'un NoC/VCI.
    36     Cette configuration permet de créer une application pour un simulateur de SoC en systemC/SoCLib.
     26    The first example below show how to run MutekH using this configuration.
     27
     28 2. The second example below explain how to setup a SoCLib hardware simulator with 4 RISC processor (Mips, Arm or PowerPC).
    3729    [[BR]][[BR]][[Image(arch_4proc.gif,nolink)]][[BR]][[BR]]
    3830
    39 = Premiers pas sur une plateforme émulée =
    40 
    41 Pour ce premier essai seules les sources de MutekH sont nécessaires.
    42 
    43 == Récuperation des sources ==
    44 
    45 {{{
    46 svn co -r 997 https://www-asim.lip6.fr/svn/mutekh/trunk/mutekh
    47 }}}
    48 crée un répertoire mutekh contenant les sources et les documentations de MutekH.
    49 L'organisation des sources suit celle des bibliothèques.
     31= Part 1 : Running MutekH in a UNIX process =
     32
     33This first example only require to get the MutekH source code.
     34
     35== Getting the sources ==
     36
     37{{{
     38svn co -r 1024 https://www-asim.lip6.fr/svn/mutekh/trunk/mutekh
     39}}}
     40Source tree is organized this way:
    5041{{{
    5142mutekh
    52 |-- arch            code dépendant des plateformes
    53 |-- cpu             code dépendant des processeurs
     43|-- arch            contains hardware platforms modules for hexo
     44|-- cpu             contains processors modules for hexo
    5445|-- doc             documentation
    55 |-- drivers         pilotes des périphériques
     46|-- drivers         device and filesystem drivers
    5647|-- examples        Test and example programs
    57 |-- gpct            API de gestion des ensembles
    58 |-- hexo            API d'Hexo
    59 |-- libc            API standard C
    60 |-- libnetwork      API de la pile de protocole réseau
    61 |-- libpthread      API des threads Posix
    62 |-- libsrl         
    63 |-- libunix         API des appels système Unix
    64 |-- libvfs          API Virtual File System
    65 |-- mutek           
    66 |-- scripts         
    67 `-- tools
    68 }}}
    69 
    70 == Ecriture du premier programme ==
    71 
    72 Le programme de test va être placé dans un sous-répertoire du répertoire de mutekh.
    73 
    74 Note: Cet exemple est disponible directement dans le sous repertoire `examples/hello`.
    75 
    76  1. Création du répertoire de test, dans le répertoire mutekh
     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
     60More directories are actually available with other libraries and features.
     61
     62== Writing the example source code ==
     63
     64Note: This example is available directly from {{{examples/hello}}} in source tree.
     65
     66 - Creating a new modules directory
    7767{{{
    7868mkdir hello
    7969cd hello
    8070}}}
    81  2. Ecriture du programme suivant dans le fichier `hello.c`
     71
     72 - Writing the source code in `hello.c`
    8273{{{
    8374#include <pthread.h>
    … …  
    10394}
    10495}}}
    105  3. Ecriture d'un `Makefile`
     96
     97 - Writing the `Makefile`
    10698{{{
    10799objs = hello.o
    108100}}}
    109101
    110 == Configuration de MutekH ==
    111 
    112 Tapez le fichier de configuration suivant dans le fichier `hello/config_emu`
    113 Nous verrons plus loin la signification des configurations.
    114 Disons rapidement que cette configuration indique:
    115  - la licence de l'application (et la vérification que les composants sont compatibles avec ce choix),
    116  - que la plateforme cible s'exécute dans un processus Unix sur une plateforme X86
    117  - que l'application utilise les Pthreads.
    118  - que les affichages se font sur le terminal.
    119  - que l'on déclare un nouveau module nommé "hello".
    120 
    121 Le code source de MutekH est découpé en modules. Nous devons declarer un noveau module que nous appelerons "hello" pour que notre application soit compilée en même temps que le reste du système. Le chemin de ce module doit être spécifié, dans notre cas ce chemin est identique à celui du fichier de configuration que nous écrivons.
     102== Writing the MutekH configuration file ==
     103
     104Our configuration file is named `hello/config_emu`.
     105Details about configuration file is explained later.
     106This 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
     113The 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.
    122114
    123115{{{
    … …  
    145137}}}
    146138
    147 == 4. Compilation de l'application et de MutekH ==
    148 
    149 La compilation se fait depuis le répertoire de MutekH en tapant:
     139== Compiling the application along with MutekH ==
     140
     141Simply type:
    150142{{{
    151143make CONF=hello/config_emu
    152144}}}
    153 Le Makefile compile les sources du système et de l'application en tenant compte du fichier de configuration.
    154 Le résultat de cette compilation est:
     145
     146Once the compilation process has finished, the executable binary is available:
    155147{{{
    156148kernel-emu-x86-emu.out
    157149}}}
    158150
    159 == 5. Exécution ==
    160 
    161 L'exécution du programmme ``kernel-emu-x86-emu.out`` rend normalement:
    162 {{{
     151== Execution ==
     152
     153Simply execute the program as a normal unix executable:
     154{{{
     155$ ./kernel-emu-x86-emu.out
    163156(0) Hello (0) World
    164157(0) Hello (0) World
    … …  
    168161}}}
    169162
    170 = Aller plus loin avec une plateforme SoCLib =
    171 
    172 
    173 == Récupération des sources de SoCLib ==
    174 
    175 Il faut disposer d'une installation fonctionnelle de SoCLib, on vous renvoie au site de soclib à la page d'installation: https://www.soclib.fr/trac/dev/wiki/InstallationNotes
    176 
    177 == Description de la plafeforme SoCLib ==
    178 
    179 Pour ce premier contact avec MutekH, nous avons préparé un plateforme à 4 processeurs.
    180 Cette plateforme se trouve dans les plateformes de démo de SoCLib dans le répertoire
     163= Part2 : Running MutekH in a multiprocessor SoCLib simulator =
     164
     165== Getting SoCLib ==
     166
     167We 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
     171The SoCLib source tree contains a platform dedicated to this tutorial:
    181172{{{soclib/soclib/platform/topcells/caba-vgmn-mutekh_tutorial/}}}.
    182173
    183 == Obtenir les compilateurs criosés ==
    184 
    185 Il est possible d'installer facilement les outils de compilation pour les différents processeurs en utilisant le script {{{tools/crossgen.mk}}} fourni avec mutek:
     174== Getting the cross-compilers ==
     175
     176You can rely on the {{{tools/crossgen.mk}}} script which comes along with MutekH to build some GNU cross-compilers:
    186177{{{
    187178 $ tools/crossgen.mk
    188179 $ tools/crossgen.mk all TARGET=mipsel-unknown-elf
    189  $ tools/crossgen.mk all TARGET=arm-unknown-elf
    190180}}}
    191181
    192182== Configuration de MutekH ==
    193183
    194 Note: Cet exemple est disponible directement dans le sous repertoire `examples/hello`.
    195 
    196 La configuration de MutekH pour une plateforme simulée de 4 processeurs va etre placée dans le fichier `hello/config_soclib_mipsel`:
     184Note: This example is readily available in the `examples/hello` directory in the MutekH source tree.
     185
     186The MutekH configuration for the 4 Mips processors platform is in the `hello/config_soclib_mipsel` file:
    197187{{{
    198188
    … …  
    236226}}}
    237227
    238 On note que la définition des processeurs change. On indique qu'il s'agit de 4 mips de type little-endian.
    239 Le systeme peut donner des informations sur les options en tapant la commande:
    240 
    241 {{{
    242 make CONF=hello/config_mips showconfig TOKEN=CONFIG_SMP
    243 }}}
    244 L'ensemble des configurations possibles (une centaine) peut être obtenu par la commande ci-après:
    245 {{{
    246 make CONF=hello/config_mips listconfig
    247 }}}
    248 
    249 Voir BuildSystem pour plus d'informations
    250 
    251 == Description de la plateforme ==
    252 
    253 On voit qu'on a ajouté un token `CONFIG_ARCH_DEVICE_TREE` dans le fichier de configuration, celui-ci sert à
    254 dire qu'on a une définition de la plateforme sous forme d'un FlattenedDeviceTree qui accompagne le kernel.
    255 
    256 Il faut en fait compiler cette description dans le kernel, en l'ajoutant dans la Makefile. Le fichier `hello/Makefile` contient alors:
     228You may have noticed the processor definition change:
     229we are now building for a 4 little-endian Mips processor platform.
     230
     231Have a look to the BuildSystem page for more information about configuration system.
     232
     233== Platform description ==
     234
     235As this hardware platform use now hardware enumeration (plug and play),  the `CONFIG_ARCH_DEVICE_TREE`
     236token in the configuration file let the kernel get the platform layout description from a
     237FlattenedDeviceTree which will be built-in.
     238
     239We have to provided the platform description FlattenedDeviceTree and add it to the Makefile to have it compiled in.
     240The `hello/Makefile` file must contain:
    257241
    258242{{{
    … …  
    260244}}}
    261245
    262 Il faut ensuite ajouter un fichier `platform-mips.dts`, au format accepté par l'utilitaire `dtc`, contenant la définition de la plateforme. Ce format est issu de l'IEEE1275 (Open Firmware).
     246The actual FlattenedDeviceTree source file `platform-mips.dts` contains:
    263247
    264248{{{
    … …  
    347331
    348332
    349 == Compilation de l'application et de MutekH ==
    350 
    351 La plateforme mutek_tutorial s'adapte automatique à la configuration des sources de MutekH (type de cpu, ...).
    352 De plus, on peut compiler le noyau depuis le répertoire de la plateforme, donc en dehors de l'arborescence de MutekH.
    353 
    354 La Makefile fournie contient tout le code nécessaire. Elle a besoin de 3 variables:
     333== Compiling the application along with MutekH ==
     334
     335The MutekH kernel and th application may be built out of the source tree.
     336
     337Change to the SoCLib platform directory and apply the following steps to experiment
     338with out of tree compilation. You have to setup the following variables:
     339
    355340 `MUTEKH_DIR`::
    356    Le répertoire contenant les sources de MutekH
     341   Path to MutekH source tree
    357342 `APP`::
    358    Le répertoire contenant les sources de l'application (ici le répertoire de hello)
     343   Path to application source
    359344 `CONFIG`::
    360    Le fichier de configuration, dans le répertoire de la plateforme
    361 
    362 La compilation de MutekH impose que les cross tools suivants soient disponibles:
    363  - mipsel-unknown-elf-gcc
    364  - mipsel-unknown-elf-ld
    365  - …
     345   MutekH configuration file name
    366346
    367347{{{
    … …  
    370350}}}
    371351
    372 Cette commande compile successivement le noyau, puis la plateforme.
    373 
    374 == Exécution ==
    375 
    376 Le simulateur prend en argument le kernel à charger ainsi que le type et le nombre de processeurs. Dans notre cas, il est dans `mutekh/kernel-soclib-mips.out` et s'exécute sur une plateforme avec 4 processeurs mips32:
    377 
     352This will build the MutekH kernel allong with the application.
     353You can still build MutekH separately as explained in the first part. The simulator can then be built using:
     354
     355{{{
     356$ cd soclib/soclib/platform/topcells/caba-vgmn-mutekh_tutorial
     357$ make system.x
     358}}}
     359
     360== Execution ==
     361
     362The simulator needs the MutekH executable file name and the processor type and count:
    378363{{{
    379364$ ./system.x mutekh/kernel-soclib-mips.out:mips32:4
    380365}}}
     366
     367You may want to refer to other articles available from the main page to go further with MutekH.