Dokumentation von FPGA-Registern

Tja, Microtschip benutzt auch Framemaker*. Die wissen warum!

Nur der teutsche Deppening schreibt Dokus mit Word.




*) Für Ungläubige: Einfach mal in die Documentproperties des PDF 
schauen.

Moin,

Docbook XML ist auch ein flotter Standard, lässt sich prima in LaTeX 
übersetzen (dblatex).
Wenn man die ganzen Register-Definitionen auch in XML macht, lassen sich 
daraus auch einfach SVGs für die Registerdoku generieren. Für grosse 
Projekte schreibt man die Definition dann nur einmal, und der Rest wird 
generiert (Package über Header bis Doku). Der Aufwand ist allerdings 
nicht ganz ohne, die Style-Sheets zu erstellen.

Mit LaTeX und tikzpicture lassen sich auch Timing-Diagramme, 
State-Machines u.ä. dokumentieren...

Duke

Wie kann man in Latex eigentlich VHDL-Code gut dargestellt einbinden?

Tobias B. schrieb:
> Das Thema hat mich jetzt selbst ein bisschen neugirierg gemacht.
> Vielleicht lohnt sich mal ein Blick in SystemRDL zu verwerfen. Das ist
> ein offener Standard welcher genau solche Register Beschreibungen
> managen soll.

Leider sind diese Ansätze immer furchtbar schwergewichtig. Eigentlich 
(..eigentlich...) sollte IP-XACT dank XML-Validierung und entsprechenden 
Schemata das Erzeugen von Registerbänken usw. einfacher machen. Wegen 
gewisser Unzulänglichkeiten hat man dann wohl nochmal eine Sprache 
ersonnen, sie aber 'schemafrei' gestaltet, so dass eine vernünftige 
Validierung wegfällt (WTF?).

Nur als Beispiel, dass es auch einfacher geht: Der 'devdesc'-XMLdialekt 
(Teil der Netzwerk-Kommunikationslib 'netpp'). Einige SoC-Beispiele 
finden sich im MaSoCist-Repo, der schnellste Zugriff ist vermutlich per 
Docker-Container (https://hub.docker.com/r/hackfin/masocist/). Die 
Stylesheets/Schemata dazu kann man unter /usr/share finden. Doku gibt's 
allerdings nur auf Englisch.

Ich erzeuge mir damit inzwischen per 'make' die komplette HDL für die 
Registermap, Adressdecoder, usw., die C-Header für die Software, 
Linkerscripte, und die Docbook-Doku mit den SVG/PDF-Bildern der 
Register-Layouts. Der Gipfel der Perversion ist, dass sich Register bzw. 
Bitfelder direkt automatisch aufs Netzwerk exportieren, sprich per 
Python oder LabVIEW ansprechen lassen. (das läuft dann unter 
'Properties'). Beispielprojekt mit generierter Doku: 
https://hackaday.io/project/162259-netpp-node

Und mit dem XXE (https://www.xmlmind.com/) kann man's auch Klickibunti 
haben. Vorteil eines solch gearteten schemabasierten Workflows ist, dass 
der Editor kein illegales Format erzeugt, woran die Weiterverarbeitung 
sich verschlucken könne ('garbage in, garbage out').

Aber man muss sich auch hier wie bei IP-XACT im Klaren sein, dass sich 
das erst ab einer gewissen Komplexität amortisiert.

dono schrieb:
> ich möchte mein FPGA-Projekt gerne für die Nachwelt etwas konservieren
> und auch gut dokumentieren!

Abseits der grundsätzlichen Notwendigkeit der Doku und der hier 
vorgestellten (nicht uninteressanten Ansätze!) folgende Frage:

Wie kann es denn sein, dass man die Register im Nachhinein dokumentiert?

Sowas wird VORHER gemacht, weil es ja Teil eines Pflichtenheftes ist 
und oft genug Folge einer Abstimmung mit SW- Entwicklern. Das ist bei 
uns immer zuerst fertig und steckt in einer Exceltabelle, die 
versioniert wird.

Auch FSMs werden erst definiert, eingefroren und dann umgesetzt. Und ja, 
möglichst automatisiert und wiederholbar automatisiert (wegen der 
Änderungen) soweit sich das machen lässt.

Für mich hört sich das wieder so an, als habe da einer beim Entwickeln 
(Hacken!) nachgedacht, geplant und wenn er fertig ist, will er 
umständlch Doku machen, die eigentlich seine Arbeit hätte ordnen und 
strukturieren sollen und daher größtenteils vorher und während der 
Umsetzung gemacht gehört.

Was ich nach Fertigstellung des VHDLs mache, ist nur die automatisierten 
TBs laufen lassen, die einen Bericht erzeugen. Dann wird die Validierung 
abgeschlossen (MATLAB und ModelSIM sagen dasselbe, Testbenches sagen 
"ok") und ab dann geht es in den Test (also ins FPGA oder ASIC).

Logikpolizei schrieb:
> Sowas wird VORHER gemacht, weil es ja Teil eines Pflichtenheftes ist
> und oft genug Folge einer Abstimmung mit SW- Entwicklern.

Ja, das wünsche ich mir auch jedes mal. Jedoch erlebe ich zu oft, dass 
die Anforderungen entweder zu abstrakt sind, was zu viel Freiraum 
erlaubt, oder einfach noch unbekannt ist, weil sich weitere 
Anforderungen erst bei der Umsetzung ergeben. Man kann jetzt mit zig 
Voruntersuchungen das Pflichtenheft festzurren oder einfach mal anfangen 
ohne endlose Diskussionen und nachdokumentieren.

Aus meiner Sicht, liegt die Wahrheit (wie eigentlich üblich) irgendwo 
zwischen Schwarz und Weiss.

PS: Ich schreibe mir für meine Hobby-Projekte auch keine Lasten- 
und/oder Pflichtenhefte, sondern mache einfach.

grüße

daniel__m schrieb:
> Ich schreibe mir für meine Hobby-Projekte auch keine Lasten-
> und/oder Pflichtenhefte, sondern mache einfach.

Schlechtes Argument!

Dort braucht man keine Projektverfolgung, keine Kostenüberwachung, es 
muss kein Team synchronisert werden, es müssen keine EMV-Tests geplant 
werden, es müssen keine formellen Anforderungen durch DO 254 eingehalten 
werden.

Logikpolizei (Gast)
>Sowas wird VORHER gemacht, weil es ja Teil eines Pflichtenheftes ist
>und oft genug Folge einer Abstimmung mit SW- Entwicklern.

Ich sehe schon, Du bist kein Mann der Praxis ;-)

Carl schrieb:
> Ich sehe schon, Du bist kein Mann der Praxis ;-)

Sagt jemand aus der FErne,  der noch nie in einem team gearbeitet hat, 
dass sich über mehr, als 2 Zimmer erstrecket.

Wir haben mehr als 70 Leute, die an einem Gerät arbeiten und die meisten 
müssen über den Tellerrand hinaussehen können. Ein Tellerrand der sich 
von der Ostküste der USA über 2 Länder Europas bis nach Japan erstreckt.

daniel__m schrieb:
> Ja, das wünsche ich mir auch jedes mal. Jedoch erlebe ich zu oft, dass
> die Anforderungen entweder zu abstrakt sind, was zu viel Freiraum
> erlaubt, oder einfach noch unbekannt ist, weil sich weitere
> Anforderungen erst bei der Umsetzung ergeben. Man kann jetzt mit zig
> Voruntersuchungen das Pflichtenheft festzurren oder einfach mal anfangen
> ohne endlose Diskussionen und nachdokumentieren.

Danke für diesen Kommentar. Nach dem ersten dachte ich mir, dass ich 
wohl nicht für die Entwicklung gedacht bin, aber es beruhigt mich, dass 
es noch andere gibt, die meine Meinung teilen.

Im Pflichtenheft meines aktuellen Projekts sind die Anforderungen an die 
FPGA-Entwicklung sehr vage gehalten. Da steht drin, mit welcher Latenz 
welche Aktion durchgeführt werden muss, und welche Funktionalitäten 
implementiert werden müssen. Register Map? Das liegt im Ermessen des 
Entwicklers. Wir sind ein eng verzahntes Team, die Software wird von 
meinem Kollegen neben mir entwickelt und wenn er eine Frage zu etwas 
hat, oder es Nice-to-have Features geben soll, dann wird das auf kurzem 
Weg organisiert. PM und PL wollen davon garnichts wissen, und sind froh, 
wenn sie mit der Sache nicht belastet werden.

Klar, eine Register Map vorher festzuzurren, und sich danach strikt 
daran zu halten, finde ich dann sinnvoll, wenn das Endprodukt 
hochkomplex ist und das Team verteilt arbeitet. Dann werde ich wohl 
genauso arbeiten.

Logikpolizei schrieb:
> Sowas wird VORHER gemacht, weil es ja Teil eines Pflichtenheftes ist
> und oft genug Folge einer Abstimmung mit SW- Entwicklern.

Logikpolizei schrieb:
> Wir haben mehr als 70 Leute, die an einem Gerät arbeiten und die meisten
> müssen über den Tellerrand hinaussehen können.

In Deinem Fall würde ich das auch so machen. Du hast ja richtig 
Manpower...

Als Einzelkämpfer, der neben VHDL und Software vielleicht auch noch die 
Platinen und das Gehäusedesign macht, da läuft das anders.

Erst baue ich den VHDL-Teil. Daraus ergeben sich automatisch die 
benötigten Bits und Register. Die Software baut dann darauf auf und erst 
zum Schluß kommt womöglich eine GUI, die das ganze per Protokoll 
triggert.

Wenn ein weiteres Feature gebraucht wird (weil sich z.B. die 
Anforderungen geändert haben), fange ich wieder ganz unten bei der 
Hardware an.

Aber wir schweifen ab...

Duke

>Carl schrieb:
>> Wie kann man in Latex eigentlich VHDL-Code gut dargestellt einbinden?
Tobias B. (Firma: www.elpra.de) (ttobsen)
>Ich verwende immer gewoehnliche listings mit ein paar zusaetzlichen
>optionen. So richtig ideal ist es zwar nicht, aber besser als nix.
>Kleines Beispiel:

Danke für den Hinweis.
https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings

Ich habe jetzt ein ganze Weile damit rum probiert, weil es nicht 
kompilieren wollte ( latex ). Das Problem waren schließlich die "ä" und 
"ö" in den Kommentaren, die das Listing Modul nicht verträgt.

Ob die Darstellung des VHDL-Codes schön ist, weiß ich nicht ....

Die Schriftgröße müsste man auf jeden Fall kleiner machen.

Tobias B. (Firma: www.elpra.de) (ttobsen)
>Eventuell koennte da XeLatex helfen. Muss man zwar ein paar Dinge
>beachten, im Allgemeinen bin ich damit aber gluecklicher als mit Latex.

Danke für den Hinweis, aber da müsste ich jetzt noch mal was neues 
Anfangen ...

Mir ist übrigens ein Nachteil bei der Verwendung von "lstlisting" 
aufgefallen.
https://docs.google.com/viewer?url=http%3A%2F%2Fwww.mikrocontroller.net%2Fattachment%2F412908%2FRC_Filter.pdf
Wenn man ein PDF hat und den Code daraus kopieren will, bekommt man 
immer die Zeilennummer mit. Das ist dann lästig, weil man die Nummern 
mit einem Editor wieder von Hand entfernen muss.

Logikpolizei schrieb:
> Sowas wird VORHER gemacht, weil es ja Teil eines Pflichtenheftes ist
> und oft genug Folge einer Abstimmung mit SW- Entwicklern. Das ist bei
> uns immer zuerst fertig und steckt in einer Exceltabelle, die
> versioniert wird.

Excel? Im Ernst? Versioniert?

Die Freude geht dann schon los, wenn einer die Excel-Werte in Sourcecode 
übertragen muss (Versionen-Synchronisation...). Es ist nach wie vor ein 
Irrglaube, dass Excel die Funktion einer Datenbank erfüllen kann...

dono schrieb:
> Klar, eine Register Map vorher festzuzurren, und sich danach strikt
> daran zu halten, finde ich dann sinnvoll, wenn das Endprodukt
> hochkomplex ist und das Team verteilt arbeitet. Dann werde ich wohl
> genauso arbeiten.

Sobald eben mehrere Layer von Entwicklern (Coder, HDL-Leute, Marketing) 
daran beteiligt sind, wird's ein richtiges Palaver, und "strikt" klappt 
eben seltenst. Gerade da versucht man eigentlich mit den 
Beschreibungssprachen, den Overhead etwas zu verringern und die 
Definitionen auf genau EINE Quelle zu reduzieren, damit Änderungen 
wartungsfrei bleiben. Den oberen Layern ist die Registermap a priori 
egal, insofern kann man im Sinne einer agilen Entwicklung auch als 
Pflichtenheft eine Liste von Eigenschaften (die zB der IP-Block 
aufweisen muss) festkloppen, wie die auf Register gemappt wird, 
interessiert meistens eh nur SW-Entwickler. Die sollten IMHO auch die 
Registermap definieren, und die HDL-Seite nur die Signale zur Verfügung 
stellen. Einigen muss man sich dann nur noch auf Namen für Dinger 
(Bitfelder, Register, ...)

Es gibt auch Leute, die vor der eigentlichen Implementierung schon mal 
ein provisorisches Handbuch sehen wollen. Also ist Top-Down-Design auch 
für Einzel-Entwickler nicht unbedingt das blödeste, unter dem Vorbehalt, 
dass eine weiter zu lernende Designsprache nicht vor lauter Komplexität 
vom eigentlichen Thema ablenkt :-)