-= SOCLIB =-
Plate-forme de prototypage virtuel pour
Applications logicielles embarquées sur puce
Règles de structuration
SOCLIB/XXXX/RAPPORT/D2.2
Date de soumission 15/11/2007
Table des matières
==================
1 Introduction
2 Règles et recommandation de codage de modèle SystemC SOCLIB
2.1 Module
2.2 Template et constructeur
2.3 Interface
2.4 Définition des fichiers à inclure dans le top
2.5 Netlist SystemC générée
3 Structure de répertoire pour modèle SystemC Soclib
1 Introduction
==============
Ce document a pour but de définir des règles et des recommandations de
structuration des modèles SystemC SOCLIB qui permettront de faciliter
la génération de documentations ou de façon plus large l’exploitation
des métas données par des générateurs de code, tels que des netlisters
ainsi que la génération automatique de ces méta données à partir des
modèles SystemC existants. Ce document définit en particulier les
règles de codage d’un modèle SystemC de la librairie SOCLIB, afin de
pouvoir le packager correctement en SPIRIT IP-XACT (créer une
documentation XML référençant les modèles)d’une part, l’instancier et
pouvoir générer une netlist SystemC facilement d’autre part à partir
des ces descriptions SPIRIT. Il impose également une structure de
répertoire pour stocker les fichiers sources des modèles.
Ce document propose des règles et des recommandations:
* Une règle (Rn) devra être respectée absolument afin d’éviter les
erreurs liées à l’intégration et l’utilisation d’un composant.
* Une recommandation (ou proposition Pn) permet de pointer sur des
problèmes de packaging ou d’utilisation liés à un codage à priori non
interdit.
Avertissement: la rédaction de ce document et des règles de codage
qu’il contient a été faite en alignement avec les autres livrables
décrivant les règles d’écriture CABA et TLMT (D2.1, D2.3, D2.5,
D2.6). Des évolutions seront possibles selon des résultats
d’expérience ou des alignement nécessaires avec des changements sur
les règles de modélisation issues des documents que nous venons de
citer. La rédaction de ce document a été faite en gardant à l’esprit
de faciliter le packaging, la réutilisation et la documentation des
composants de la bibliothèque SOCLIB. Un livrable supplémentaire
(D6.7) sera disponible à T0+24 (et probablement avant en version de
travail) pour guider et illustrer au travers d’exemples concrets le
packaging des composants de la bibliothèque SOCLIB.
2 Règles et recommandation de codage de modèle SystemC SOCLIB
==============================================================
2.1 Module
----------
Règle 2.1.1 : Déclaration d’un module SystemC
---------------------------------------------
Libellé : Il faut déclarer le module SystemC comme une classe héritant
de sc_module
Justification : Le fait que les données membres d’une classe soient
privées (mot clé private en C) par défaut permet d’assurer une bonne
encapsulation des données ce qui n’est pas forcément le cas avec une
struct dans laquelle les données sont publiques par défaut.
Règle 2.1.2 : Fichiers SystemC
------------------------------
Libellé : Deux fichiers (ou plus) doivent être présents pour définir
un modèle : [module].h dans lequel sont faites uniquement les
déclarations et [module].cpp dans lequel se trouvent définis les
constructeurs et toutes les méthodes.
Justification : Evite la présence de code d’implémentation dans les
fichiers en-tête
Proposition 2.1.3 : Fichiers template
-------------------------------------
Libellé : Il est conseillée l'utilisation de fichiers [module].tcc
pour écrire les méthodes des classes templatés, ainsi les fichiers
[module].h contiennent simplement les déclaration.
Justification : Facilite la lecture des fichiers d'en-tête. Permet
plus facilement la compilation séparée des templates.
Proposition 2.1.4 : Espace de nom « soclib »
--------------------------------------------
Libellé : Utiliser le namespace « soclib »
Justification : permet d'éviter les préfixes « soclib_ » et simplifie
les noms de fichiers et de fonctions.
Proposition 2.1.5 : Espaces de nom pour catégories de composants
----------------------------------------------------------------
Libellé : Utiliser les namespaces suivants pour définir la catégorie
d’un composant. Ces namespaces respectent les noms dans la struccture
de répertoires définie en R3.3.
network_component bridges, tunnels, adapters, buses, ...
connectivity_component off-chip interface: UART, USB, I2C, GPIO,
streaming_component video data processor, ...
infrastructure_component clock and reset generator, interrupt controller
clock_infrastructure clock generator
reset_infrastructure reset generator
interrupt_infrastructure interrupt controller
dma_infrastructure DMA controller
configuration_infrastructure configuration register
power_infrastructure power switch controller
event_infrastructure event controller
trigger_infrastructure cross-trigger matrix
pad_mux_infrastructure IC pad multiplexer
undefined_infrastructure Other cases
processor_component CPU, DSP: ARM, MIPS, TriMedia, …
internal_component peripheral without off-chip interface, e.g.mem.
test_controlComponent dedicated DfT component
stub_component testbench component connected to off-chip interface
verification_component verification monitor, or other testbench component
undefined_component to capture all other components
Justification : Permet d'éviter les préfixes et simplifie les noms de
fichiers et de fonctions. Ces labels sont les mêmes que ceux utilisés
dans SPIRIT (extension en cours).
2.2 Template et constructeur
----------------------------
Proposition 2.2.1 : Paramètres de contructeur
---------------------------------------------
Libellé : Utiliser le plus possible des paramètres de constructeurs
plutôt que des paramètres de template (sauf cas cités en P2.2.2), afin
d'éviter d'avoir à décrire du comportement dans le fichier d’en-tête
(.h) (voir P2.1.3 pour gestion de fichiers séparés contenant les
résolutions de template)
Justification : Pour éviter des problèmes liés à la compilation et à
la fourniture de librairies
Proposition 2.2.2 : Parmètres de template
-----------------------------------------
Libellé : Utiliser au maximum les paramètres de template pour des
tailles (de données, tableaux internes, etc.), plutôt que des
paramètres de constructeur
Justification : Pour faciliter, en plus du packaging SPIRIT, la
compilation, car la précision des messages gcc d’erreur est moindre
avec les paramètres de constructeur
Remarque : utiliser les templates que pour tailles variables dans les
types
Règle 2.2.3 : Position du paramètre nom dans le constructeur
------------------------------------------------------------
Libellé : Le paramètre de construction « sc_module_name » doit
apparaître en première position
Justification : Facilite l’échange et la réutilisation Exemple :
SC_MODULE(adder){
sc_in<bool> clk;
sc_in<sc_uint<8> > input;
sc_out<sc_uint<8> > output;
void add();
SC_HAS_PROCESS(add);
adder(sc_module_name name_, int addval_) : sc_module(name_), addval(addval_){
SC_THREAD(add); sensitive wwclk.pos();
}
private:
int addval;
}
Règle 2.2.4 : Valeur par défaut pour les paramètres de constructeur ou de template
----------------------------------------------------------------------------------
Libellé : Il faut définir des valeurs par défaut pour tous les
paramètres de construction ou de template. Excepté le nom du module
(qui doit recevoir une valeur spécifique à chaque instance)
Justification : Facilite la génération de la netlist et empêche les
erreurs de compilation dues aux paramètres manquants
Proposition 2.2.5 : Un seul constructeur par module
---------------------------------------------------
Libellé : Eviter de définir plusieurs constructeurs par module et
préférer l’utilisation de deux modules séparés.
Justification : Facilite le packaging et la netlist
Proposition 2.2.6 : Utilisation conditionnelle de paramètres de constructeur
----------------------------------------------------------------------------
Libellé : Eviter l’utilisation de #IFDEF pour rendre conditionnelle
certains paramètres de constructeur
Justification : Pas encore standardisé SPIRIT et difficilement
packageable : il faut alors soit faire appel à un configurateur, soit
packager les différents constructeurs sous la forme d’autant de
components SPIRIT (pouvant éventuellement pointer sur le même fichier
source)
2.3 Interface
-------------
Règle 2.3.1 : Casse des noms de port
------------------------------------
Libellé : Tous les ports doivent être déclarés avec des noms en
minuscule.
Justification : Homogénéisation et évite les erreurs dans le cas de
sensibilité à la casse.
Règle 2.3.2 : Nom des ports clock et reset
------------------------------------------
Libellé : Le(les) port(s) clock d’un module doit(doivent) toujours
être préfixé(s) par « clk » ; le(les) port(s) reset doit(doivent)
toujours être préfixé(s) par « reset », ou « resetn » dans le cas d’un
reset sur front descendant.
Justification : Homogénéisation et facilité de packaging.
Règle 2.3.3 : Utilisation du type sc_in_clk
-------------------------------------------
Libellé : Les ports clock doivent être déclarés de type sc_in_clk.
Justification : Exploite la distinction des ports horloge proposée par SystemC et éventuellement exploitée par un simulateur.
Règle 2.3.4 : Utilisation des pointeurs pour la déclaration des ports
---------------------------------------------------------------------
Libellé : Tous les ports doivent être déclaré avec un pointeur.
Justification : L’initialisation par tableau de variable de classe ne
permet pas de nommer chaque port (ce qui pose un problème d’analyse
d’erreur si le port n’a pas été connecté car dans ce cas SystemC
reporte uniquement la référence interne du port, son numéro de
position dans la déclaration des ports, ce qui n’est pas très
explicite) .
Proposition 2.3.5 : Type de ports et interface à privilégier
------------------------------------------------------------
Libellé : Les types suivants sont à privilégier car supportés
directement par le schéma IP-XACT.
* sc_in/sc_out/sc_inout
* sc_export<protocol<ADDR,DATA> > (ici ADDR et DATA ne sont pas des
templates)
* sc_port<protocol<ADDR,DATA> > (ici ADDR et DATA ne sont pas des
templates)
* type de port utilisateur : supporté avec une utilisation dans
IP-XACT d’une vendor extension
* tableaux de ports
Justification : Facilitent le packaging IP-XACT.
Proposition 2.3.6 : Type de ports et interface à éviter
-------------------------------------------------------
Libellé : Les types suivants sont à éviter:
* sc_port<protocol<ADDR,DATA> > utilisant des templates de templates
car cela devient assez lourd à décrire en SPIRIT (ici ADDR et DATA
sont des templates)
* Matrices de ports : assez difficilement supportées sauf avec un
configurateur donc à éviter
* Eviter la définition conditionnelle de port (P2.2.6)
Justification : Compliquent le packaging IP-XACT et nécessitent le
recours à des configurateurs. Néanmoins, le contournement peut être
d’utiliser autant de « component » SPIRIT que de configurations et de
faire pointer ceux-ci vers le même fichier source SystemC
2.4 Définition des fichiers à inclure dans le top
-------------------------------------------------
Règle 2.4.1 : Emplacement des fichiers d’inclusion
--------------------------------------------------
Libellé : Dans le fichier XML IP-XACT d’un module, ses fichiers
d’inclusion devront être définis par leur chemin d’accès. Ce chemin
d’accès sera indiqué en relatif par rapport à l’emplacement du fichier
IP-XACT
Justification : Dans le top généré : utiliser #include "module.h"
(sans répertoire par exemple), ce qui signifie que la connaissance de
la structure est reportée dans les Makefiles utilisés pour la
compilation.
2.5 Netlist SystemC générée
---------------------------
Règle 2.5.1 : Instanciation statique des composants
---------------------------------------------------
Libellé : Chaque module doit pouvoir être instancié statiquement dans
un top.
Justification : Eviter la gestion des deux types d’instanciation par
les netlisters et d’alourdir le packaging.
Règle 2.5.1 : Appel de fonctions d’initialisation
-------------------------------------------------
Libellé : Le recours à l’appel de fonction d’initialisation est
interdit et l’on doit passer par l’utilisation du constructeur.
Justification : Facilite le packaging et l’instanciation de composants
dans une netlist 3 Structure de répertoire pour modèle SystemC SOCLIB
3 Structure de répertoire pour modèle SystemC Soclib
====================================================
Règle 3.0 : Casse des noms de répertoires et fichiers
-----------------------------------------------------
Libellé : L’utilisation des majuscules est interdite, de même que
l’usage des espaces, dans les noms de répertoires et de
fichiers. Utiliser « _ » (underscore) pour les transitions minuscule
vers majuscule.
Règle 3.1 : Répertoire racine
-----------------------------
Libellé : Le répertoire racine s'appelle « soclib », il contient les
répertoires suivants distinguant les familles d’éléments hardware de
la bibliothèque:
* communication : Ce répertoire contient les éléments SystemC
permettant la définition des interfaces des modules.
* module : Ce répertoire contient tous les modules de la
bibliothèque.
* platform : Ce répertoire contient des exemples de plate-formes
utilisant les éléments de la bibliothèque.
* lib : Ce répertoire contient les librairies de fonctions pouvant
être utilisées en commun par certains modules.
Remarque : Ce répertoire racine, concernant uniquement les composants
hard de la bibliothèque, prendra sa place dans un autre répertoire, au
même niveau que des répertoires contenant des éléments soft (OS,
drivers, outils, etc.). Un document décrivant cette partie de la
structure de la bibliothèque SOCLIB sera élaboré ultérieurement
Règle 3.2 : Répertoire des définitions d’interface (communication)
------------------------------------------------------------------
Libellé : Ce répertoire contient les éléments SystemC permettant la
définition des interfaces des modules (pour la définition des
ensembles de signaux spécifiques Soclib, vci, cache, et fifo à l'heure
actuelle). Leur utilisation homogène dans les modules assure le
respect des définitions d’interfaces standardisées. Chaque élément
doit respecter la structure suivante :
* nom_element
* variante
* tlmt
* doc
* source
* include
* src
* metadata (fichier XML IP-XACT : busdef)
* caba
* doc
* source
* include
* src
* metadata (fichier XML IP-XACT : busdef)
Règle 3.3 : Répertoire contenant les composants (module)
--------------------------------------------------------
Libellé : Ce répertoire contient tous les modules de la bibliothèque,
qui sont classés dans des répertoires par catégories, et portant les
noms suivants :
network_component bridges, tunnels, adapters, buses, …
connectivity_component off-chip interface: UART, USB, I2C, GPIO,
streaming_component video data processor, …
infrastructure component clock and reset generator, interrupt controller,
clock_infrastructure clock generator
reset_infrastructure reset generator
interrupt_infrastructure interrupt controller
dma_infrastructure DMA controller
configuration_infrastructure configuration register
power_infrastructure power switch controller
event_infrastructure event controller
trigger_infrastructure cross-trigger matrix
pad_mux_infrastructure IC pad multiplexer
undefined_infrastructure Other cases
processor_component CPU, DSP: ARM, MIPS, TriMedia, …
internal_component peripheral without off-chip interface, e.g.mem.
test_control_component dedicated DfT component
stub_component testbench component connected to off-chip interface
verification_component verification monitor, or other testbench component
undefined_component to capture all other components
Remarque: ces répertoires correspondent aux définitions de namespace
décrits en P2.1.5
Règle 3.4 : Répertoires par catégories, contenant les éléments de la bibliothèque
---------------------------------------------------------------------------------
Libellé : Ces répertoires (dont la liste est donnée en R3.3)
contiennent les éléments de la bibliothèque. A chaque élément est
associé un répertoire avec la structure suivante :
* nom_element
* variante
* tlmt
* doc
* source
* include
* src
* metadata (fichier XML IP-XACT : component)
* caba
* doc
* source
* include
* src
* metadata (fichier XML IP-XACT : component)
Règle 3.5 : Répertoire contenant des plateformes (platform)
-----------------------------------------------------------
Libellé : Ce répertoire contient des exemples de plate-formes
utilisant les éléments de la bibliothèque. Sa structure hiérarchique,
simplifiée au maximum ici, devra être décidée dans un autre document
(cf remarque de l’introduction) : • nom_element
Règle 3.6 : Répertoire « build »
---------------------------------
Libellé : Aucun répertoire build ne doit être présent dans la
bibliothèque.
Justification : Le répertoire build cible est spécifié au moment de la
compilation.
Règle 3.7 : Gestion des versions des éléments
---------------------------------------------
Libellé : La gestion des différentes versions d’un même élément de la
bibliothèque sera assurée par un outil de gestion de version (ex CVS).
Justification : Evite de faire apparaître toutes les versions d’un
élément dans l’arborescence SOCLIB et permet de conserver l’historique
des modifications.
| Name | Last commit | Last update |
|---|---|---|
| .. | ||
| benchmarks | ||
| binary/module/streaming_component | ||
| doc | ||
| soclib | ||
| utils | ||
| COPYING.gpl | ||
| COPYING.lgpl | ||
| COPYING_tc.bsd | ||
| README | ||
| global.conf | ||