===== How to setup a new project =====

In diesem HowTo wird das Anlegen eines Syntheseprojektes am Beispiel einer Verschaltung von zwei UND Gattern Schritt für Schritt beschrieben.

=== Funktion der Beispielschaltung ===

{{::howto-and5.png}}

Ein Modul "and5" soll ein UND Gatter mit fünf Eingängen und einem Ausgang beschreiben. Dieses "myand5" Modul soll zweimal instantiiert werden. Die Eingänge von myand5_i0 werden mit den Schaltern SW0 bis SW4 verbunden. Die Eingänge des Moduls myand5_i1 werden mit den Schaltern SW5 bis SW9 verbunden. Der Ausgang von myand5_i0 wird mit der roten Leuchtdiode LEDR0 verbunden. Der Ausgang von myand5_i1 wird mit der roten Leuchtdiode LEDR1 verbunden. Wenn die Schalter SW0 bis SW4 alle auf "on" geschaltet sind, dann soll die rote Leuchtdiode LED0 leuchten. Entsprechend die LED1. Die Instantiierung der beiden "myand5" Module und die Verbindung der beiden UND Gatter mit den Schaltern und den roten Leuchtdioden wird auf dem Toplevelmodul de1_and5 gemacht.

=== 1. Partitionierung in Module ===

Die Schaltung wird in einzelne Teilschaltungen aufgeteilt. Es gibt immer ein "Toplevelmodul", das die oberste Schaltungshierarchie repräsentiert. Dieses Modul hat als Ein- und Ausgänge die Pins des FPGAs. In diesem Beispiel ist das das Modul "de1_and5". Der Name des Toplevelmoduls soll immer die Form de1_XXXX haben. Damit wird schon am Namen deutlich, dass es ein Toplevelmodul ist. Das Toplevelmodul hat die Eingänge SW[9..0] und die Ausgänge LEDR[1..0].

Neben dem Toplevelmodul gibt es in diesem Beispiel ein weiteres Modul "myand5". Das Modul "myand5" hat die Funktion des UND Gatters mit fünf Eingängen. Das Modul "myand5" hat die Eingänge x_i[4..0] und den Ausgang y_o. In diesem Beispiel gibt es nur das Modul "myand5" neben dem Toplevelmodul "de1_and5". In einem Design kann es aber beliebig viele weitere Module geben, die alle miteinander verschaltet werden können.

=== 2. Erstellen der VHDL Dateien ===

Jedes Schaltungsmodul kommt in eine eigene VHDL Datei. Das Toplevelmodul repräsentiert die oberste Hierarchie in der Schaltung und hat als Ports die Pins des FPGAs, also bei uns die Schalter SWx und die Leuchtdioden LEDRx.

  * Für das Modul myand5 wird eine VHDL Datei "myand5_rtl.vhd" angelegt.
  * Für das Toplevelmodul de1_and5 wird eine VHDL Datei "de1_and5_rtl.vhd" angelegt.

Der Dateiname der VHDL Datei eines normalen Moduls hat die Form "MODULNAME_rtl.vhd" (hier: myand5_rtl.vhd). Der Name der VHDL Datei des Toplevelmoduls lautet "TOPLEVELMODULNAME_rtl.vhd" (hier: de1_and5_rtl.vhd).

Die VHDL Dateien befinden sich alle in dem Verzeichnis "src". Zweckmäßigerweise kopiert man eine existierende VHDL Datei und benennt sie um.

<code>
cd ~/projects/digitaltechnikpraktikum
cd src
cp cntones_rtl.vhd myand5_rtl.vhd
cp de1_ledcntsw_rtl.vhd de1_and5_rtl.vhd
</code>

Danach kann man die VHDL Dateien mit einem Editor der Wahl an das Projekt anpassen. Zunächst sollten minimale Dateien nur mit einer Entity und einer leeren Architecture erstellt werden. Die Datei "myand5_rtl.vhd" sollte dann so wie hier aussehen:

<file vhdl myand5_rtl.vhd>
library ieee;
use ieee.std_logic_1164.all;

entity myand5 is 
port ( x_i  : in  std_ulogic_vector(4 downto 0);
       y_o  : out std_ulogic);  
end entity myand5;

architecture rtl of myand5 is 
begin
end architecture rtl;
</file>

Die Datei hat schon eine korrekte entity mit den richtigen Ports, aber eine leere Architecture. Im Beispiel hier sind die fünf Eingänge des Moduls "myand5" als Typ "std_ulogic_vector" mit einer Arraylänge von 5 definiert. Der Ausgang ist ein einzelner Ausgang vom Typ "std_ulogic". Der Name des Eingangs ist "x_i" und der Name des Ausgangs is "y_o". Der Name "x_i" deutet schon im Namen auf einen Eingang hin. Beim Namen des Ausgangs "y_o" deutet "_o" darauf hin, dass es sich um einen Ausgang handelt. Diese Namenskonvention mit "_i" und "_o" sollte bei allen Module eingehalten werdne. Der Entityname ist der Name des Moduls, hier "myand5". 

Entsprechend wird die Toplevel VHDL Datei erstellt. Die Portnamen vom Toplevelmodul sind Namen, die auf dem Altera DE1 Modul eine Bedeutung haben. In diesem Beispiel steht der Port "SW" für die Schalter auf dem Board ("Switches"). Der Port "LEDR" steht für die roten Leuchtdioden, die direkt über den Schaltern angeordnet sind. Von den roten Leuchtdioden werden in diesem Projekt nur zwei verwendet. 

<file vhdl de1_and5_rtl.vhd>
library ieee;
use ieee.std_logic_1164.all;

entity de1_and5 is
port ( SW   : in   std_ulogic_vector(9 downto 0);
       LEDR : out  std_ulogic_vector(1 downto 0));
end entity de1_and5;

architecture rtl of de1_and5 is
begin
end architecture rtl;
</file>

=== 3. Erstellen des Syntheseprojektes ===

Nachdem die VHDL Dateien erstellt wurden, kann man den Ordner für das Syntheseprojekt im Ordner "pnr" erstellen. Der Name des Ordners muss der gleiche sein wie der Modulname des Toplevelmoduls. Auch hier kann man am einfachsten ein existierendes Projekt kopieren und dann das Makefile und die Pinkonfigurationsdatei anpassen. Im Beispiel hier kopiere ich die Dateien vom Projekt "de1_ledcntsw". 

<code>
cd ~/projects/digitaltechnikpraktikum
cd pnr
cp -R de1_ledcntsw de1_and5
cd de1_and5
</code>

Das Verzeichnis "pnr/de1_and5" enthält nun die beiden Dateien "de1_ledcntsw_pins.tcl" und "makefile". 

<code>
caeuser@CAE-Tools-OS:~/projects/digitaltechnikpraktikum/pnr/de1_and5$ ls -la
total 16
drwxr-xr-x  2 caeuser users 4096 Apr  2 22:51 .
drwxr-xr-x 19 caeuser users 4096 Apr  2 22:51 ..
-rw-r--r--  1 caeuser users 1234 Apr  2 22:51 de1_ledcntsw_pins.tcl
-rw-r--r--  1 caeuser users  247 Apr  2 22:51 makefile
caeuser@CAE-Tools-OS:~/projects/digitaltechnikpraktikum/pnr/de1_and5$
</code>

Die Pinkonfigurationsdatei muss umbenannt werden in "TOPLEVELMODULNAME_pins.tcl". Hier in "de1_and5_pins.tcl".

<code>
mv de1_ledcntsw_pins.tcl de1_and5_pins.tcl
</code>

In der Pinkonfigurationsdatei wird jedem Portnamen des Toplevelmoduls ein Pin auf dem FPGA zugeordnet. Es müssen genau die Ports aus dem Toplevelmodul aufgeführt werden, d.h. es dürfen auch nicht mehr Pins enthalten sein. In diesem Beispiel müssen einige Pindefinitionen gelöscht werden. Die Pinkonfigurationsdatei muss danach so ausssehen:

<file tcl de1_and5_pins.tcl>
# Pin Configuration 
set_location_assignment PIN_L22 -to SW[0]
set_location_assignment PIN_L21 -to SW[1]
set_location_assignment PIN_M22 -to SW[2]
set_location_assignment PIN_V12 -to SW[3]
set_location_assignment PIN_W12 -to SW[4]
set_location_assignment PIN_U12 -to SW[5]
set_location_assignment PIN_U11 -to SW[6]
set_location_assignment PIN_M2  -to SW[7]
set_location_assignment PIN_M1  -to SW[8]
set_location_assignment PIN_L2  -to SW[9]
set_location_assignment PIN_R20 -to LEDR[0]
set_location_assignment PIN_R19 -to LEDR[1]
</file>

Im Makefile muss die Variable PROJECT auf den Namen des Toplevelmoduls gesetzt werden und alle VHDL Dateien, die zum Projekt gehören müssen unter der Variable SOURCE_FILES aufgeführt werden. Nach den Anpassungen muss das Makefile so aussehen:

<file makefile makefile>
# The PROJECT variable must match the
# toplevel VHDL entity name
# and should match the directory name in the pnr directory

PROJECT = de1_and5

SOURCE_FILES = \
../../src/de1_and5_rtl.vhd \
../../src/myand5_rtl.vhd

include ../makefile
</file>

=== 4. Testen des Syntheseprojektes ===

Jetzt muss man Testen ob die Konfiguration des Syntheseprojektes funktioniert hat. Dazu geht man in Projektordner im Verzeichnis "pnr" und öffnet quartus über den Makemechanismus.

<code>
cd ~/projects/digitaltechnikpraktikum
cd pnr
make quartus
</code>

Mit "make quartus" wird das Syntheseprojekt angelegt und die GUI der Quartussoftware geöffnet. Wenn sich die GUI öffnet, ist es schonmal nicht schlecht. Danach kann man die Synthese starten. Wenn hier noch Syntaxfehler in den VHDL Dateien sind oder noch VHDL Dateien fehlen, dann fällt es hier auf.

=== 5. Testen der Pinkonfiguration ===

In der Quartus GUI kann man jetzt über "Assignments->Pin Planner" den Pinplanner aufrufen und nachschauen ob für alle Ports des Toplevelmoduls auch ein Pin auf dem FPGA eingetragen ist.

==== Mögliche Fehler ====

=== Nicht existierende VHDL Dateien in SOURCE_FILES ===
Der Schritt "make quartus" schlägt fehlt, wenn das makefile nicht korrekt konfiguriert ist. Wenn beispielsweise eine VHDL Datei in "SOURCE_FIlES" aufgelistet wird, die nicht existiert wie in diesem Beispiel:

<file makefile makefile_NON_EXISTING_VHD_FILE>
# The PROJECT variable must match the
# toplevel VHDL entity name
# and should match the directory name in the pnr directory

PROJECT = de1_and5

SOURCE_FILES = \
../../src/de1_and5_rtl.vhd \
../../src/MICH_GIBT_ES_NICHT.vhd

include ../makefile
</file>

Dann führt das zu:

<code>
caeuser@CAE-Tools-OS:~/projects/digitaltechnikpraktikum/pnr/de1_and5$ make quartus
make: *** No rule to make target '../../src/MICH_GIBT_ES_NICHT.vhd', needed by 'de1_and5.qpf'.  Stop.
caeuser@CAE-Tools-OS:~/projects/digitaltechnikpraktikum/pnr/de1_and5$ 
</code>

=== PROJECT und der Name der Pinkonfigurationsdatei passen nicht zusammen ===

Der erwartete Name der Pinkonfigurationsdatei ist "$(PROJECT)_pins.tcl". Wenn das nicht zusammenpasst und die Variable PROJECT im Makefile beispielsweise auf "PROJECT = de1_MICH_GIBT_ES_NICHT" gesetzt wird, dann sieht das im Ergebnis so aus:

<code>
caeuser@CAE-Tools-OS:~/projects/digitaltechnikpraktikum/pnr/de1_and5$ make quartus
make: *** No rule to make target 'de1_MICH_GIBT_ES_NICHT_pins.tcl', needed by 'de1_MICH_GIBT_ES_NICHT.qpf'.  Stop.
</code>

=== Entity im Toplevelmodul hat anderen Namen als PROJECT ===

Wenn der Name der Entity im Toplevelmodul nicht gleich PROJECT (hier "de1_XXXX") ist, dann sieht das bei Start der Synthese so aus:

<code>
Error (12007): Top-level design entity "de1_XXXX" is undefined
Error: Quartus II 32-bit Analysis & Synthesis was unsuccessful. 1 error, 2 warnings
	Error: Peak virtual memory: 358 megabytes
	Error: Processing ended: Sun Apr  2 23:29:52 2023
	Error: Elapsed time: 00:00:01
	Error: Total CPU time (on all processors): 00:00:01
Error (293001): Quartus II Full Compilation was unsuccessful. 3 errors, 2 warnings
</code>