Verilog - Documentaion

OP #7532960
Lesenswert?

Hi, bin gerade dabei eine Dokumentation zu meinem Verilog-Projekt zu bauen:

https://multixmedia.org/verilogdoc/

Wollte das ein wenig grafisch aufbereiten mit Diagrammen zur besseren Übersicht über die einzelnen Module und Abhängigkeiten.

Das ganze soll dann auch noch per CSS etwas aufgehübscht werden, aber zuerst benötige ich einen groben Aufbau.

Die Seiten und Diagramme werden alle aus den Verilog-Dateien generiert und sind nicht per Hand erstellt.

das innere der module lässt sich später auch noch visualisieren und sogar interaktiv testen mit digitaljs.js :

https://raw.githubusercontent.com/multigcs/LinuxCNC-RIO/main/plugins/joint_stepper/quad_encoder.svg

Was meint ihr was noch fehlt oder was schlecht ist ?

Gruß, Olli

#7533048
Lesenswert?

Sieht mal nicht schlecht aus für den Anfang, außer dass die gekrümmten überkreuzten Signale natürlich nicht mehr zu erkennen sind (Mit welchem Tool hast du das gemacht?). Aber was willst du mit digitaljs bezwecken? Das ist doch ein Simulator, soweit ich weiß. Willst du wirklich Verilog-Module auf Gatelevel simulieren?

OP #7533058
Lesenswert?

Hi Vancouver, vielen dank !

Ja die überlappenden Liniean sind doof, muss mal schauen ob ich das besser lösen kann, aber die reihenfolgen stimmen überein, falls man es zuordnen/verfolgen möchte.

Das ganze ist ein python script mit graphviz und yosys als verilog interpreter (-> .json)

Ja, digitaljs ist ein Simulator, dachte so kann man kleinere Teile der Schaltung besser nachvolziehen, finde das klappt auch recht gut solange es KLEINE Teile sind :), kann natürlich schnell sehr unübersichtlich werden.

Gruß, Olli

Gast #7534652
Lesenswert?

Oliver D. schrieb:

Hi, bin gerade dabei eine Dokumentation zu meinem Verilog-Projekt zu bauen:

Wollte das ein wenig grafisch aufbereiten mit Diagrammen zur besseren Übersicht über die einzelnen Module und Abhängigkeiten.

Nunja, Übersicht erfordert, das man das Unwesentliche und das immer Gleiche weglässt und nur das Signifikante zeichnet.

Da man eigentlich von synchronen Komponenten mit definierten Start-wert aisgeht, kannste die ganzen Taktleitungen "clk" weglassen.

Und dann schau dir mal einen komplexeren Schaltplan an, bei dem GND nicht als komplett verzweigtes Netz gezeichnet wird sondern lediglich mehrfach GND-Symbole gesetzt werden.

Und bei einem sauberern Logikentwurf ist die Reihenfolge eine andere, erst zeichnet/entwirft man ein Blockbild in dem Signal- und Controlpfad erkennbar sind und dann implementiert man das in einer HDL. Die Spezifikation kann also als Dokumentation der Implementierung benutzt werden.

Eine aus der Implementierung "automatisch" erzeugte "Dokumentation" bedarf eigentlich immer der manuellen Nacharbeit, weil eben dem Automatismus jegliche didaktischen Kompetenz fehlt.

Zur groben Erst-Orientierung in einer Arbeit aus dritter Hand mag eine "HDL-> Gekritzel Konvertierung" begrenzt brauchbar sein, aber eine gute Dokumentation die wirklich die Struktur erläutert muss eigentlich immer "händisch" erzeugt werden.

OP #7534860
Lesenswert?

Klaus K. schrieb:

Eine aus der Implementierung "automatisch" erzeugte "Dokumentation" bedarf eigentlich immer der manuellen Nacharbeit, weil eben dem Automatismus jegliche didaktischen Kompetenz fehlt.

Hi Klaus, das mag ja teilweise zutreffend sein, allerdings ist auch das darunterliegende Projekt dynamisch generiert und somit nicht möglich jede Konstelation per Hand nach zu arbeiten.

So kann der User nachverfolgen, welche Auswirkungen, eine Änderung an der Konfiguration mit sich bringt.

OP #7535388
Lesenswert?

Was ist eigentlich mit diesem Forum los ? es kommt mir vor als würden Leute so aus Spaß/Langeweile hier negative Bewertungen abgeben.

Über konstruktive Kritik freue ich mich ja, aber einfach so, anonym, was schlecht machen ist doch seltsam.

Ok, wenn jemand totalen Schwachsinn von sich gibt, muss man das nicht kommentieren. Oder wenn irgend ein cooler link in einem kommentar ist, dann klickt man mal auf +.

Aber eine normale Konversation runter zu Bewerten !?!?!?

Naja, vielleicht auch die Schuld des Forums, wenn man einem DAU was zu klicken gibt, dann klickt er auch drauf ;)

Liebe Grüße, Olli

PS: sorry, das musste mal raus, sehe ich auch in anderen Threads, nicht nur hier bei diesem Thema

Gast #7535590
Lesenswert?

Oliver D. schrieb:

Was ist eigentlich mit diesem Forum los ? es kommt mir vor als würden Leute so aus Spaß/Langeweile hier negative Bewertungen abgeben.

Über konstruktive Kritik freue ich mich ja, aber einfach so, anonym, was schlecht machen ist doch seltsam.

Aber eine normale Konversation runter zu Bewerten !?!?!?

Naja, vielleicht auch die Schuld des Forums, wenn man einem DAU was zu klicken gibt, dann klickt er auch drauf ;)

PS: sorry, das musste mal raus, sehe ich auch in anderen Threads, nicht nur hier bei diesem Thema

+1, es ist völlig berechtigt auf die völlig kontraproduktive Bewertungsweise in diesem Forum hinzuweisen. Das die Betreiber sich hinter dem Satz "Wenn es dir nicht passt, dann ignoriere es" ist schon skandalös. Man stelle sich vor, bei der Bildung gäbe es für richtige Antworten permanent Noten vom Lehrer, die das Gegenteil behaupten. "Ungerecht, unfair" ist als bezeichnung dafür noch untertrieben, passender als Charakterisierung wäre "bösartig und manipulierend".

Gast #7535598
Lesenswert?

Martin S. schrieb:

Die Schematic-Umsetzung ist ziemlich gut, aber wie immer Geschmackssache.

Bei der Technischen Dokumentation geht es aber nicht um "Geschmack", Ästhetik wie bei einer x-beliebigen "Visualisierung" sondern um Verständlichkeit hinsichtlich der innewohnenden Funktionen.

https://de.wikipedia.org/wiki/Technische_Dokumentation#Unterbegriffe https://www.techsmith.de/blog/gute-technische-dokumentation-erstellen/

Man könnte sich allerdings überlegen, ein zweites Schematic zu generieren, das nur die Clock- und Resetlogik zwischen den Modulen zeigt.

Ja, das ist ein guter Vorschlag, jeweils auf einen Aspekt fokusierte Diagramme zu erstellen. Also beispielsweise eins das (nur) die Taktdomainen zeigt und eins das (nur) den Datenpfad darstellt.

Und bei ersteren muss es nicht eine Darstellung der Takt-verdrahtung (schematic, Stromlaufplan) sein, da passt IMHO eine rechteck-flächenhafte Darstellung besser.

So kann der User nachverfolgen, welche Auswirkungen, eine Änderung an der Konfiguration mit sich bringt.

Also ich glaube nicht, das ein Anwender eines in Verilog geschriebenen FPGA-Designs an der Veränderung von irgendwelchen automatisch erzeugten bubbles und Pfeilen erkennt, welche Konsequenzen eine Konfigurationsänderung hat.

#7535746
Lesenswert?

Persönlich ignoriere ich die Bewertungsfunktion, weil ich deren Zweck nicht erkennen kann. Soll ich vielleicht anhand der Bewertung von anderen entscheiden, ob ein Beitrag für mich relevant ist? Dazu muss ich ihn zumindest mal überfliegen. Diese "Like"-Mentalität ist völlig für die Tonne.

Es wäre schön, wenn man die Anzeige der Bewertung ausschalten könnte und dies für die anderen Leser auch sichtbar machen könnte, z.B. mit einem durchgestrichenen ThumbUp.

OP #7536158
Lesenswert?

Ich bin leider kein Profi, weder im dokumentieren noch in Verilog. Mir persönlich helfen die Diagramme um mal einen besseren Blick auf die Sache werfen zu können, muss nicht zu technisch sein.

Also so gesehen schon geschmackssache oder zumindest abhängig vom Betrachter den man damit ansprechen möchte.

Das eigentliche Projekt ist eine CNC-Steurung (Realtime-Hardware für LinuxCNC) die man relativ frei konfigurieren kann, daher weis ich auch nicht welchen technischen Hintergund die Nutzer so haben und in wie weit solche Dokumentationen helfen.

Da ich aus der Programmierer Ecke komme, plane ich sowas auch nicht vorher mit aufwendingen Logik-Diagrammen die ich später wiederverwenden könnte. Ich bin froh wenn ich mein vorhaben irgendwie in Verilog umgestzt bekomme.

Zu den Bewertungen: es würde denke ich schon reichen wenn es nicht anonym wäre.

Gruß, Olli

Persönliche Seite #7537885
Lesenswert?

Klaus K. schrieb:

Und bei einem sauberern Logikentwurf ist die Reihenfolge eine andere, erst zeichnet/entwirft man ein Blockbild in dem Signal- und Controlpfad erkennbar sind und dann implementiert man das in einer HDL. Die Spezifikation kann also als Dokumentation der Implementierung benutzt werden.

Das scheinen immer weniger so zu machen. Ich sehe immer mehr tippelei und dann notdprftige Doko. Dabei kann man gerade diese per Copy und Paste immer wieder nutzen und für Folgeprojekte einsetzen.

Gast #7537900
Lesenswert?

J. S. schrieb:

Klaus K. schrieb:

erst zeichnet/entwirft man ein Blockbild in dem Signal- und Controlpfad erkennbar sind und dann implementiert man das in einer HDL. Die Spezifikation kann also als Dokumentation der Implementierung benutzt werden.

Das scheinen immer weniger so zu machen. Ich sehe immer mehr tippelei und dann notdprftige Doko.

Hm, ja. Vielleicht liegt es daran, das die Ausbildung/das Fach "Technisches Zeichnen" vernachlässigt wird. Das mag aber auch daran liegen, das dieses Fach nie richtig den Sprung aus dem Maschinenbau in den Bereich komplexe Digitaltechnik/ VLSI Entwurf geschafft hat. Auch werden viele Vorschriften aus diesem Fach als zu starr empfunden.

UML ist im Bereich Blockbilder auch ziemlich tot und der HDL-Designer zu teuer und wurde nie richtig weiterentwickelt.

Inkscape ist als Zeichentool IMHO recht brauchbar für diesen Zweck, Visio dagegen empfinde ich als grausam.

https://lp.uni-goettingen.de/get/text/6351

Antwort schreiben

Bitte melde dich an, um einen Beitrag zu schreiben.

oder

Mit Google-Account einloggen

Die Registrierung ist kostenlos und dauert nur eine Minute.

Jetzt registrieren