Návody / Překladový systém

1. Úvod

Z důvodu sjednocení překladu pod systémem Windows a Linux byl vytvořen jednoduchý překladový systém založený na XML souborech. XML soubor (typicky projekt.xml) popisuje projekt, závislosti na dalších zdrojových souborech a umožňuje definovat specifická nastavení. Kromě překladu slouží XML pro generování seznamu aplikací a zjišťování informací o konkrétní aplikaci.

Schema překladového systému je zobrazeno na obrázku 1.1. XML soubor slouží jako vstup programu fcmake, který na základě obsahu vygeneruje skripty pro XILINX ISE a Modelsim a Makefile soubor, se kterým je možné již pracovat pomocí standardních nástrojů. XML soubor obsahuje seznam všech zdrojových souborů a knihoven, které projekt pro překlad potřebuje, parametrů apod. Vygenerovaný Makefile soubor obsahuje pouze informace týkající se překladu konkrétního projektu a dále se odkazuje na sadu překladových pravidel umístěnou v adresáři base.

2. Popis projektu (soubor project.xml)

XML soubor tvoří tři části:

• popis projektu,

• část obsahující informace pro generování kódu pro mikrokontroler (MCU),

• část s informacemi potřebnými pro vygenerování konfigurace pro FPGA.

Nejjednodušší projekt může vypadat např. následovně:

<?xml version="1.0" encoding="utf-8"?>
<project outputprefix="project">

    <!--  Popis projektu -->
    <name>Název projektu</name>
    <author>Jan Novák</author>
    <authoremail>xnovak99@stud.fit.vutbr.cz</authoremail>
    <revision>20081020</revision>
    <description>Popis aplikace, co dělá, případně jak se ovládá apod.</description>

    <!--  Zdrojové kódy pro MCU -->
    <mcu>
        <file>main.c</file>
    </mcu>

    <!-- Zdrojové kódy pro FPGA -->
    <fpga>
        <file>top.vhd</file>
    </fpga>

</project>

XML značka <project> obsahuje pouze jedinný volitelný atribut outputprefix, který definuje prefix názvu vygenerovaných souborů (v našem případě vznikne trojice project.bin, project_f1xx.hex a project_f2xx.hex). Výchozí hodnota je "output".

Část popisující projekt obsahuje stručný název projektu, popis projektu, jméno autora, email a aktuální verzi (revizi), která obsahuje datum poslední modifikace.

2.1. MCU sekce

MCU část slouží ke specifikaci souborů, které jsou zapotřebí pro překlad kódu pro mikrokontroler a případných dalších parametrů. Soubory je možné definovat libovolnou kombinací následujících značek:

• <file>nazev_souboru</file> - značka definující název konkrétního souboru

• <files>nazev_souboru1 nazev_souboru2 ...</files> - tato značka umožňuje definovat seznam souborů. Soubory jsou odděleny mezerou.

• <include>cesta_k_balicku/package.xml</include> - pomocí této značky je možné vložit seznam souborů, který je definován v balíčku (např. package.xml). Tím je možné definovat závislosti na jiných komponentách. Např. je možné vložit všechny soubory používané k obsluze řadiče LCD displeje, aniž bychom se museli zabývat tím, které to jsou.

• <headerfile>nazev_souboru.h</headerfile> - pomocí této značky je možné k projektu/knihovně/balíčku definovat závislost na konkrétním hlavičkovém souboru. Dojde-li ke změně v tomto souboru, přeloží se automaticky všechny zdrojové soubory vložené pomocí <file> či <files>. Tato značka také způsobí přidání cesty k hlavičkovému souboru do cest, které má GCC automaticky prohledávat.

Element <mcu> má pouze jediný nepovinný atribut mathlibrary jehož hodnota může být pouze yes nebo no (výchozí). Tento atribut určuje, zda-li k projektu linkovat knihovnu matematických funkcí (překladači je předán parametr -lm).

Cesty k souborům mohou být relativní nebo absolutní. Při zadávání relativních cest platí následující pravidlo: Nejprve se prohledává vzhledem k adresáři s projektem, poté vzhledem k podadresáři mcu a nakonec vzhledem ke kořenovému adresáři SVN stromu (tzn. adresáři obsahujícímu podadresáře base, mcu, fpga, apps). Tento způsob procházení cest velmi usnadní případné přesuny projektů do jiných podadresářů.

Dále každá značka může mít definován atribut location="project", který určuje, že se má daný soubor vyhledávát vzhledem k adresáři s projektem. Toto chování lze použít např. pro deklaraci konfiguračního hlavičkového souboru, na němž je závislý překlad zdrojových kódů v rámci balíčku, ale který je umístěn ve složce konkrétního projektu.

Ukázka použití (předpokládáme, že projekt obsahuje podadresář mcu obsahující soubor main.c):

<mcu>
  <include>mcu/libs/lcd/package.xml</include>
  <include>mcu/libs/thermometer/package.xml</include>

  <file>main.c</files>
</mcu>

Ze souboru mcu/libs/lcd/package.xml (vzhledem ke kořenovému adresáři SVN) je vložen seznam souborů potřebných k obsluze LCD displeje. Totéž je provedeno pro knihovnu obsluhující teplotní snímač. Dále je k seznamu připojen soubor, který je umístěn v podadresáři mcu mcu/main.c.

Následující zápis vloží zcela stejný seznam souborů:

<mcu>
  <include>../../../mcu/libs/lcd/package.xml</include>
  <include>../../../mcu/libs/thermometer/package.xml</include>
  <file>mcu/main.c</files>
</mcu>

Ukázka použití značky headerfile (předpokládáme, že projekt obsahuje podadresář mcu obsahující soubor main.c, test1.h a test2.h):

<mcu>
  <include>mcu/libs/lcd/package.xml</include>
  <file>main.c</files>
  <headerfile>test1.h</headerfile>
  <headerfile>test2.h</headerfile>
</mcu>

Značka <headerfile> způsobí, že v případě změní-li se obsah souboru test1.h nebo test2.h, dojde k znovupřeložení zdrojového kódu v souboru main.c. Dále se přídají relativní cesty k souborům test*.h, tedy ./mcu/, do seznamu cest v kterých může překladač hledat hlavičkové soubory; výsledkem je parametr -Imcu, který je předán překladači GCC.

Balíčky

Balíčky jsou XML soubory s velmi podobnou strukturou. Kořenovým elementem však musí být značka <package> jejíž tělo obsahuje v závislosti na typu balíčku pouze MCU nebo FPGA část.

2.2. FPGA sekce

FPGA sekce používá zcela stejný princip definice zdrojových souborů a závislostí jako MCU sekce, tzn. elementy <file>, <files> a <include>. Na rozdíl od MCU je zapotřebí brát ohled na pořadí vkládání souborů, neboť ModelSIM není schopen řešit automaticky závislosti.

Element <fpga> může obsahovat tyto atributy:

• architecture - volba architektury (top-level entity). K dispozici jsou následující možnosti: "bare" - základní entita bez X portu (výchozí hodnota), "pc" - entita obsahující periferie PC, "gp" - entita obsahující X port a "none". Detaily o volbě entity je možné nalézt v dokumentu Volba TOP level entity.

  Dle zvolené architektury se automaticky načte a přidá seznam VHDL souborů definovaný v balíku fpga/chips/architecure_xx/package.xml, kde xx je zvolená možnost. Vyjímku tvoří hodnota "none", která se používá v případě, kdy si nepřejeme použít žádnou z výchozích entit (většinou v souvislosti se změnou atributu toplevelentity).

• dcmfrequency - určuje frekvenci hodin CLK, které jsou generovány DCM bloky uvnitř FPGA z hodinového signálu SMCLK. Výchozí nastavení je 25MHz, další podporované frekvence: 20MHz. 40MHz, 50MHz.

• toplevelentity - atribut definuje název top-level entity. Název je nutný změnit pouze v případě, kdy si nepřejeme použít předem definované entity. Výchozí hodnota je nastavena na "fpga".

• ucffile - definuje název ucf souboru, standardně se používá soubor umístěný v fpga/chips/fpga_xc3s50.ucf

• fpgachip - určuje typ FPGA obvodu, výchozí hodnota je xc3s50-4-pq208 (FPGA Spartan 3, který je běžně umístěn na FITkitu). Pro FITkity osazené větším FPGA lze použít hodnotu xc3s400-4-pq208.

• optimization - určuje cíl a úsilí optimalizátoru, výchozí hodnota je speed:1. Hodnota se skládá z cíle (speed nebo area) a poté stupně optimalizace (1 nebo 2).

• ngcpath - cesta pro příkaz NGDBUILD, ve které se budou hledat binární verze komponent (soubory ngc)

• library - název knihovny, do které se soubory přeloží (výchozí hodnota je work)

Specifickým atributem je atribut use, který se používá v případech, kdy si přejeme použít FPGA konfiguraci z jiného projektu např: <fpga use="apps/demo/display/project.xml" />. Důvody k tomuto kroku mohou být dva 1) používáme pouze mikrokontroler a FPGA nepotřebujeme (FPGA musí být pro správnou činnost vždy naprogramováno) nebo 2) naše aplikace sestává převážně z kódu v mikrokontroleru a tak může využít již existující projekt, např. LCD řadič.

Ukázka použití:

<fpga architecture="pc">
  <include>fpga/ctrls/spi/package.xml</include>
  <include>fpga/ctrls/vga/package.xml</include>
  <include>fpga/ctrls/lcd/package.xml</include>
  <include>fpga/ctrls/keyboard/package.xml</include>

  <file context="sim">fpga/models/keyboard/keyboard.vhd</file>
  <file context="sim">fpga/models/lcd/lcd.vhd</file>

  <file>snake_top.vhd</file>
</fpga>

FPGA sekce umožňuje u elementů <file>, <files> použít následující atributy

• context - odlišuje zdrojové soubory sloužící pouze pro účely simulace (context="sim"),

• library - do které knihovny se zdrojový soubor přeloží. Není-li specifikováno, použije se hodnota atributu library elementu <fpga>.

3. Překlad projektu

Pro překlad se používá GNU make a Makefile soubory, které jsou vygenerovány z XML popisu pomocí nástoje fcmake, který je součástí balíku QDevKit.

Nejjednodušší možností je využít pro překlad aplikace a programování FITkitu aplikaci QDevKit. Mnohem rychlejší je však využít pro překladu, programování a komunikaci s kitem příkazovou řádku a nástroj make.

Make umožňuje provádět následující operace:

make

Pokud došlo ke změně ve zdrojových souborech, dojde k překladu kódu pro mikrokontroler a syntéze VHDL kódu pro FPGA. Výsledkem jsou soubory s příponou HEX (kód pro MCU) a BIN (konfigurace pro FPGA) umístěné v podadresáři build. Soubor končící na _f1xx.hex je určen pro mikrokontroler, který je použit na FITkitu verze 1.x; soubor končící na _f2xx.hex pro FITkit verze 2.x. Suffixy vycházejí z označení rodiny MSP430F1xx a MSP430F2xxx.

make load

Pomocí nástroje fkflash naprogramuje FPGA a MCU. Během programování se kontroluje, zda-li FITkit obsahuje aktuální verze souborů. Nahrávají se tedy pouze změny.

make forceload

Provede programovaní jako příkaz gmake load s tím rozdílem, že se naprogramování provede vždy, tzn. bez ohledu na obsah FITkitu.

make term

Spustní nástroj fkterm, pomocí kterého je možné s FITkitem komunikovat.

make synth

Pokud došlo ke změně ve zdrojových souborech, provede se syntéza projektu. Další fáze vedoucí k vytvoření konfigurace jsou vynechány. Toto pravidlo je vhodné používat při ladění.

make simmodel

Vygeneruje "post place&route" simulační model, který lze použít pro časovou simulaci.

make rtl

Vygeneruje RTL schéma (soubor s příponou ngr), které je možné otevřít v ISE.

make sim

Existuje-li v adresáři fpga/sim skript sim.fdo, vytvoří simulační knihovnu sim/work, zkompiluje všechny zdrojové soubory a spustí ModelSIM.

make isim

Existuje-li v adresáři fpga/sim skript isim.tcl, spustí se simulace pomocí nástroje ISIM, který je součástí balíku XILINX ISE.

make ise

Vytvoří projekt pro XILINX ISE (pomocí skriptu s koncovkou _ise.tcl v podadresáři build/fpga), který obsahuje veškeré závislosti a spustí grafické prostředí, kde je možné projekt syntetizovat případně provádět další analýzu.

make clean

Odstraní veškeré soubory, které vznikly během překladu. Ponechá však soubory vygenerované nástrojem fcmake.

make cleanmcu

Odstraní veškeré soubory související s překladem kódu pro mikrokontroler.

make cleanfpga

Odstraní veškeré soubory související s generováním konfigurace pro FPGA.

make purge

Odstraní veškeré soubory, které vznikly během překladu, včetně souborů vygenerovaných nástrojem fcmake.