Hallo zusammen, ich möchte mein FPGA-Projekt gerne für die Nachwelt etwas konservieren und auch gut dokumentieren! Hierfür bräuchte ich ein Tool, mit dessen Hilfe ich etwas mehr Struktur in so ein Dokument reinbringen kann. Mir gefällt sehr, was hier als Initial-Vorgabe angegeben wird: https://tex.stackexchange.com/questions/176040/draw-register-map-with-tikz - was mir nicht besonders gefällt, ist der Vorschlag, der doch sehr viel weniger Informationen erhält. https://github.com/briandong/regModel/blob/master/example/example_addr_map.md geht über Markdown, wobei das auch mehr als unübersichtlich ist. Ich hätte gerne etwas, das schön aussieht, gerne in LaTeX, und möglichst gut aussieht. Wenn es nichts gutes gibt, schreibe ich auch gerne meine eigenen LaTeX Makros mit TikZ, aber vielleicht gibt es sowas bereits? Viele Grüße
Angehängte Dateien:
-
latex-register.png
20 KB
dono schrieb: > Ich hätte gerne etwas, das schön aussieht, gerne in LaTeX, und möglichst > gut aussieht. Das einfachste ist via Latex Tabellen. Das sieht dann relativ simpel aus, ist aber trotzdem einigermassen uebersichtlich. Ein Beispiel aus meiner Diplomarbeit habe ich mal angehaengt. Der Vorteil ist, du kannst das relativ gut automatisieren, z.B. mit einem Python Skript. Wenn du noch eine gute VHDL Beschreibung hast, kannst du evtl. sogar aus dem Code direkt die Latex Sources generieren. Die Arbeit lohnt sich auf alle Faelle.
Schön das sich hier wer Gedanken macht. Hat zwar nicht mit dem Tool zu tun, aber ein Inspirationsbeispiel zwecks Layout. Ist zwar Geschmackssache aber mir gefällt das Layout von den Microchip Datenblättern recht gut. Bin damit immer prima zurecht gekommen. Z.B.: von ENC28J60 (siehe ein paar Screenshots). Falls du das Datenblatt noch nicht kennst. Ich finde, hier sind die Register und Flags sehr gut beschrieben. Bin hier eher der visuelle Typ. Sicherlich gibt es noch mehrere gute Bespiele von anderen Firmen.
:
Bearbeitet durch User
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.
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. Es gibt auch eine Python Implementierung die solche RDL Files verarbeiten kann: https://systemrdl-compiler.readthedocs.io/en/release-1.7/ Damit liesse sich sicher einigermassen einfach ein Konverter fuer Latex bauen.
Angehängte Dateien:
-
timing.png
1,5 KB -
flow.png
9,6 KB
Mit LaTeX und tikzpicture lassen sich auch Timing-Diagramme, State-Machines u.ä. dokumentieren... Duke
Duke Scarring schrieb: > Mit LaTeX und tikzpicture lassen sich auch Timing-Diagramme, > State-Machines u.ä. dokumentieren... Stichwort dazu ist: tikztimingtable Fuer State-Machine Diagramme nehme ich immer Sigasi. Sehen optisch ansprechend aus und werden direkt aus dem Code erzeugt. Spart enorm Zeit. :-) Carl schrieb: > Wie kann man in Latex eigentlich VHDL-Code gut dargestellt einbinden? Ich verwende immer gewoehnliche listings mit ein paar zusaetzlichen optionen. So richtig ideal ist es zwar nicht, aber besser als nix. Kleines Beispiel:
1 | \begin{lstlisting}[
|
2 | language=VHDL, |
3 | firstnumber=154, |
4 | label={lst:buffer-fifo},
|
5 | caption={FIFO instance from Xilinx macro in \texttt{buffer\_fifo.vhd}.}
|
6 | ] |
7 | u_fifo : FIFO_DUALCLOCK_MACRO |
8 | generic map( --@suppress |
9 | DEVICE => "7SERIES", -- Target Device: "VIRTEX5", ... |
10 | ALMOST_FULL_OFFSET => X"0100", -- Sets almost full threshold ... |
11 | ALMOST_EMPTY_OFFSET => X"000F", -- Sets the almost empty thre ... |
12 | DATA_WIDTH => 64, -- Valid values are 1-72 (37- ... |
13 | FIFO_SIZE => "36Kb", -- Target BRAM, "18Kb" or "36 ... |
14 | FIRST_WORD_FALL_THROUGH => FALSE -- Sets the FIFO FWFT to TRUE ... |
15 | ) |
16 | \end{lstlisting}
|
In der Preaembel setze ich die entsprechenden Optionen mit:
1 | \usepackage{listings} % Source Code Listings. Usage: \begin{lstlisting}...\end{lstlisting}
|
2 | \lstset{
|
3 | backgroundcolor=\color{white}, % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}; should come as last argument
|
4 | basicstyle=\footnotesize\ttfamily, % the size of the fonts that are used for the code |
5 | breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace |
6 | breaklines=true, % sets automatic line breaking |
7 | captionpos=b, % sets the caption-position to bottom |
8 | commentstyle=\color{gray}, % comment style
|
9 | deletekeywords={...}, % if you want to delete keywords from the given language
|
10 | escapeinside={\%*}{*)}, % if you want to add LaTeX within your code
|
11 | extendedchars=true, % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8 |
12 | firstnumber=1, % start line enumeration with line 1000 |
13 | frame=single, % adds a frame around the code |
14 | identifierstyle=\color{black},
|
15 | keepspaces=true, % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible) |
16 | keywordstyle=\color{blue}, % keyword style
|
17 | language=VHDL, % the language of the code |
18 | morekeywords={*,...}, % if you want to add more keywords to the set
|
19 | numbers=left, % where to put the line-numbers; possible values are (none, left, right) |
20 | numbersep=5pt, % how far the line-numbers are from the code |
21 | numberstyle=\tiny\color{black}, % the style that is used for the line-numbers
|
22 | rulecolor=\color{black}, % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
|
23 | showspaces=false, % show spaces everywhere adding particular underscores; it overrides 'showstringspaces' |
24 | showstringspaces=false, % underline spaces within strings only |
25 | showtabs=false, % show tabs within strings adding particular underscores |
26 | stepnumber=1, % the step between two line-numbers. If it's 1, each line will be numbered |
27 | stringstyle=\color{OrangeRed}, % string literal style
|
28 | tabsize=4, % sets default tabsize to 2 spaces |
29 | title=\lstname % show the filename of files included with \lstinputlisting; also try caption instead of title |
30 | } |
:
Bearbeitet durch User
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.
dono schrieb: > Klar, eine Register Map vorher festzuzurren, und sich danach strikt > daran zu halten Es muss ja kein "strikt dran halten" sein, man kann die Spec bei Bedarf ja auch nachbessern. Aber letztlich kommt meist ein besseres Design heraus, wenn man sich vorher zur nötigen Funktionalität Gedanken macht und ein "vorläufiges Datenblatt" für dieses FPGA schreibt. Mit diesem Datenblatt kann dann der Softie schon mal loslegen, und wenn es dann während der Entwicklung laufend gepflegt wird, hat man bei Projektabschluss schon die Doku zur Hand.
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.
Strubi schrieb: > 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?). > > ... Hallo Strubi, vielen Dank fuer den tiefen Einblick. Ich werde mir das zumindest mal ansehen, auch wenn es nicht zum produktiv damit arbeiten reicht, aber immerhin kann man dann mitreden. Carl schrieb: > 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. Eventuell koennte da XeLatex helfen. Muss man zwar ein paar Dinge beachten, im Allgemeinen bin ich damit aber gluecklicher als mit Latex.
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.
Carl schrieb: > Danke für den Hinweis, aber da müsste ich jetzt noch mal was neues > Anfangen ... Ja, das ist nicht wirklich eine Umstellung. Nur statt pdflatex wird eben XeLatex aufgerufen und ein paar Kleinigkeiten wie die Verwendung von fontspec statt fontenc muss man beachten. Siehe auch: https://texwelt.de/wissen/fragen/5868/was-ist-der-unterschied-zwischen-latex-pdflatex-lualatex-und-xelatex Carl schrieb: > 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. Ich weiss aber nicht ob das nicht ein PDF Viewer Problem ist. Wenn ich z.B. Okular verwende, dann kann ich einfach den zu kopierenden Bereich auswaehlen. Da kann ich die Zeilennummern einfach ausklammern. Kannst du denn einfach nur eine einzelne Spaalte einer Tabelle markieren? Ich denke damit wuerdest du auch Probleme haben.
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 :-)
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.