Documenting digital designs for FPGAs - Page 1
Forum section: electronics / general

author: matrixofdynamism
author_rank: Regular Contributor
timestamp: August 29, 2023, 12:42:15 pm
content: Digital designs nowadays are written in RTL in VHDL or SystemVerilog. There is no more schematic entry. The design will use RTL created in house and possibly some IP from FPGA vendor or some other third party.Documenting a design is essential for future. Someone else might have to pick it up later or, we might forget some details. Now there are many ways to document a design and this includes using comments inside the code and also writing documents on confluence or word that can be circulated. Lets focus on the design for now, and leave the verification documentation for another question.There are many ways to document a design. I am interested to know, what the engineers here consider to be best practice. Do we need to just describe the top level interfaces or details of all processed inside the modules? What about showing FSM diagram for every state machine? What if the modules are very large or the FSMs are quite complex? Depending on the writing style of FSMs, making FSM diagram can become quite tedious task as well.I have basically done some of each. Describe just top level or also describe with FSM diagrams but that becomes impractical for large designs. Most modules will contain some sort of FSM anyway. Use lot of comments or use few comments. I did as I saw fit.What do you guys think from personal experience and processes adopted by your organizations?

author: betocool
author_rank: Regular Contributor
timestamp: August 29, 2023, 02:05:20 pm
content: My 2c,I find hardware best documented on Visio or LibreOffice Draw or some good diagram program (there was another one, I forget the name). What I like about Visio is the ability to link a new page to an existing block, allowing you to go deeper into the structure.Also, a simple Github Readme file with links to images and an additional explanation does wonders.The organization I work for at the moment has no processes, so it's a mix of Atlassian and GIT. Company I worked for before had Visio and a central documentation server for everything. Atlassian is more flexible and keeps copies of past versions, but it gets to be a pain for longer docs. Word and Visio work well together, but if you can't find a document quickly these days no one's gonna read it. I guess processes are important...Agree on FSM's but hey, what can you do?Cheers,Alberto

author: tggzzz
author_rank: Super Contributor
timestamp: August 29, 2023, 02:19:38 pm
content: Quote from: matrixofdynamism on August 29, 2023, 12:42:15 pmGeneral principles...Document the interface in sufficient detail that someone can tell that theydon'tneed to look at the implementation. That's more important than whether theydohave to look internally.Document the assumptions.Document the reasons for the decisions.Only then bother to document the implementation itself.Quote from: betocool on August 29, 2023, 02:05:20 pmThis is a standard issue in hardware and software systems.One technique is to define the FSM in a format (diagram and/or text) that is easy for the designer to understand, verify that it corresponds to the specification, and to modify. Use a tool to convert that format into the machine language (HiLo,VHDL/Verilog/C/Smalltalk/Java/etc). There are many such tools; MDA (model driven architecture) is an initial search term.

author: nctnico
author_rank: Super Contributor
timestamp: August 29, 2023, 06:28:41 pm
content: Just to add to tggzzz's post:If an FSM is too complicated to document, then it might be that the FSM is too complicated to begin with. What works well for me is to start with the documentation and do a first simplification round while writing the documentation. After that implement the real design. More often than not this leads to a much more streamlined implementation which is also easier to maintain.Where it comes to complex FSMs, often it helps to use sub-FSMs that take care of a certain task.

author: tggzzz
author_rank: Super Contributor
timestamp: August 30, 2023, 12:02:24 am
content: Quote from: nctnico on August 29, 2023, 06:28:41 pmJust so.Such decomposition indicates "good taste" and "elegance".I know my work is proceeding well when the number of lines of code (FSM or any other paradigm) isreducing. Beancounting managers simply can't get their head around the concept that such "negative productivity" is extremely beneficial.It is worth noting that hierarchical decomposition of specifications and the equivalent inplementation via hierarchical composition of components is:easily and well accomodated by hierarchical schematicshas no direct equivalent in traditional procedural/OOP software - but has been triumphantly and loudly re-invented by softies and given a new name: Inversion of Controlhas direct equivalents in HDLs, but softies "doing" hardware tend to avoid using those equivalents in favour ofinappropriatelytransferring software decomposition techniques - and then not even realising that they result in poor hardware designs

author: thermistor-guy
author_rank: Frequent Contributor
timestamp: August 30, 2023, 01:56:11 am
content: Quote from: matrixofdynamism on August 29, 2023, 12:42:15 pmMy rule of thumb is, whatever I used to do the design, and then to check the design, needs to be documented.If anyone (including me) needs to revisit the design in future, those same design aids will be needed once again,if only to save engineering time.This can include worst-case timing analyses, for example, proving that the FPGA meets, say, the timing specs of an external bus.It can include annotated timing diagrams, showing how certain data flows through the FPGA and is transformed along the way,and the delays involved.if it's useful, the design will get revisited for a couple of reasons: to fix subtle bugs, to add features, to adapt to a new application.So I'd keep those in the back my mind as I developed documentation: if you are reading the documentation for one of those reasons, whatdo you need to know? What will help you? So sometimes I'd briefly document why I *didn't* implement a certain feature a certain way.Another aspect I used to document was the FPGA fitting strategy. I've had cases where the chip was near-full and, paradoxically,simplifying the circuitry a certain way caused the design not to fit.So I would have separate revision numbers for the logical design itself, and for the fitted design, to ensure traceability andreproducibility.

author: tggzzz
author_rank: Super Contributor
timestamp: August 30, 2023, 08:38:49 am
content: Quote from: thermistor-guy on August 30, 2023, 01:56:11 amWhen I last played with Xilinx Vivado, I wanted to keep it under source control.I couldn't find a definition of the necessary and sufficient set of files to be able to recreate an implementation from scratch when reverting to a previous version.How have others solved that?

author: matrixofdynamism
author_rank: Regular Contributor
timestamp: August 30, 2023, 08:51:49 am
content: The biggest issues for me have been, documenting the FSM and creating timing diagrams. The main issue is that no decent tools exist to create the FSMs. Also, there are some tools that exist to create timing diagrams but they still lack a lot of features that we really need. Both of these things come down to hardware domain lagging far behind the software domain in terms of the tools. I use a single clocked process to create the entire FSM. This means that there will be counters inside it that are used to keep the FSM in one state before going to another state. These counters are integrated into the FSM code itself. I learnt software languages first (C and VB6) so my style of writing RTL code is different from someone that has not had software language exposure before they started to write RTL code.Anyway, there is something called doxygen that some software engineers use. Using this, it is possible to have a comment block above each process in the code or block of code, which describes that part of the code. Then, one can use automated tools to extract all that information and combine it into documentation for the code. Has anyone ever used something like this for RTL code?The reason for my confusion is, I have seen different approaches during my career and they all seem to lack in some way. Some people don't document FSMs, others do. Some people write RTL in a very hardware-y way and others write it like software engineers write other code (both work fine since synthesis tools are less dumb now). Some people write lot of comments, others write few or almost no comments.I had assumed that by now, some type of agreement would have been reached on the best practices but it seems this is not the case and the tools still are not really as versatile as the software engineer's tools are.

author: nctnico
author_rank: Super Contributor
timestamp: August 30, 2023, 09:31:07 am
content: Forget about doxygen. Nothing useful comes out of that stinking pile of crap. You'd be better of feeding your code into ChatGPT nowadays.As others already noted: documentation doesn't come from the code but from the mind that wrote the code. The mind knows why a particular solution has been choosen and what the big picture (aka block diagram / state diagram / flow chart) looks like.

author: tggzzz
author_rank: Super Contributor
timestamp: August 30, 2023, 09:56:26 am
content: Quote from: nctnico on August 30, 2023, 09:31:07 amJust so.Doxygen is a poor response to JavaDoc.JavaDoc is useful when theclassandpackagecomments are carefully and thoughtfully constructed; the method comments are occasionally useful.Neither much good at explaining context:whyandwhy not, nor howthis componentinteracts withthose componentsin such a way that whole is greater than the sum of the parts.

author: Someone
author_rank: Super Contributor
timestamp: August 30, 2023, 10:02:37 am
content: Quote from: tggzzz on August 30, 2023, 08:38:49 amhttps://docs.xilinx.com/r/en-US/ug892-vivado-design-flows-overview/Source-Management-and-Revision-Control-Recommendations

author: matrixofdynamism
author_rank: Regular Contributor
timestamp: August 30, 2023, 12:06:20 pm
content: The Vivado project generation can be carried out by using TCL script. I used the GUI command to generate TCL script for my project and then another script for the block design. Both of these were kept separate. One was invoked from the other.The TCL commands that Vivado uses when it creates a project are quite numerous. I felt it to be a waste of time to understand all of them. I did try to understand what needs to be changed in the automatically generated script to get what I need. The process was not difficult but it did require some trial and error to make it work correctly.When it comes to use of version control systems, we should try to version control the TCL scripts for the project in these tools (Intel Quartus, Xilinx Vivado and Microsemi Libero) and then execute these TCL scripts in the relevant executable through another script (bash or windows command-line) to generate all files for the project so it can be compiled. Finding what TCL scripts to be version controlled and any other information e.g SDC files or some other files that contain information not found in TCL script but essential for the project, is not at all an easy task. Once Microsemi told me that they do not provide any guidance on how to use VCS with Libero, this was few years ago. They said you need to figure it out. The basic minimum file list for a project given on their website was not enough and some things that could be done through GUI did not have a TCL command available (it was going to be implemented in some future version of Libero).Anyway, if you could get generate the entire project using a few TCL scripts and maybe some SDC and other constraint files then just put these on the VCS and just describe these in the documentation.

author: betocool
author_rank: Regular Contributor
timestamp: August 30, 2023, 02:01:28 pm
content: With Quartus I'm not committing the TCL script, enough with the project file (.qpf) and the .qsf file, plus sources, including the QSYS source. They are all text based. I avoid all output folders and other .csv and such files in between.It works for me, I might be missing something but all the information I need is available.Can't say for Vivado yet.Cheers,Alberto

author: asmi
author_rank: Super Contributor
timestamp: August 31, 2023, 07:52:46 pm
content: There are two sides to this: system-level interconnects and module-level documentation.When it comes to system-level interconnects, I use standard buses for interconnections whenever possible (AXI4-lite/full/stream), and I love Vivado's diagrams because they show all those interconnects in a very visual way, they also support hierarchical structures, so it's possible to create legible diagrams even for large designs with lots of interconnected modules. This also makes testing these modules easier as I can leverage existing AXI verification tools to make my job of writing testbenches easier.As for the module-level stuff, it really depends on the peculiarities of a specific module, but at the minimum I try to capture links to relevant specifications, datasheets, etc., description of register interface (if it's got one). At the subcomponent level I try to add a comment telling what the module is doing. I try to stay away from commenting on how it's doing it, relying on an actual codebase to speak for it (my experience in development taught me that this kind of comments go out of date real fast, so code is the best doc), and only comment on it if it does something out of ordinary for some specific reason (like maybe timing-critical).

author: BrianHG
author_rank: Super Contributor
timestamp: August 31, 2023, 08:33:59 pm
content: I write at least 1 line of documentation per line of code as I code.Write a line of code, then write it's function in English and why I coded it as such.Small example: (Ok, the only lines without comments are the 'regs')https://github.com/BrianHGinc/Verilog-RS232-Synch-UART-RS232-Debugger-and-PC-host-RS232-Hex-editor/blob/main/sync_rs232_uart_v1.2.v

author: DiTBho
author_rank: Super Contributor
timestamp: September 03, 2023, 07:46:16 am
content: Dia + Graphviz to generate flowcharts vectorial pics for LaTek doc.Useful to document synchronous and asynchronous timing relations, and also fsm details.Everythingelse is a few lines of documentation per line of code as I code.

author: pbernardi
author_rank: Contributor
timestamp: September 04, 2023, 01:40:31 pm
content: It is only a small part of design documentation, but when I need to describe digital waveforms I use wavedrom:http://wavedrom.com/editor.html

author: SiliconWizard
author_rank: Super Contributor
timestamp: September 04, 2023, 10:52:08 pm
content: Quote from: pbernardi on September 04, 2023, 01:40:31 pmYep it's handy, easy to use and works rather well. I have the standalone app (which pretty much is the same thing as the web app.)

author: NorthGuy
author_rank: Super Contributor
timestamp: September 10, 2023, 05:27:53 pm
content: Imagine you're hiring someone to modify the design. What would you tell him? This will give you an idea what your documentation should look like.The state diagrams probably won't be of much use as you can easily infer them from the code. But the general things matter - what is it all about, how does it work, why did you design it the way you did, what problems have you encountered and how did you solve them, what is your vision on how the project should evolve into the future. Make it more explanatory than factual.Documenting is a skill (art if you will), it takes time to master. It's difficult to keep everything concise and to the point and include all the important details at the same time. While you still remember all the details of your project it's really hard to envision how a person without such knowledge would look at it. This includes yourself in 10-20 years when you forget nearly everything.

author: matrixofdynamism
author_rank: Regular Contributor
timestamp: September 13, 2023, 01:11:59 am
content: Wavedrom is great, but its limited in many ways since it is a free tool some engineer invented during his vacation period. I wonder why such a tool does not already exist from the big names like Cadence, Synopsys or even Intel, Xilinx e.t.c.