Community
cancel
Showing results for 
Search instead for 
Did you mean: 
Altera_Forum
Honored Contributor I
2,296 Views

Tool for VHDL/Verilog code documentation

Hi,  

 

Can someone share experience on writing documentation for FPGA design? How do you write it?  

 

 

I want to write documentation for FPGA project, describe which top modules are responsible for what, and main source files should also be documented.  

The main purpose of this documentation should be that other designer can easily take and modify my project or quickly understand structure of my project.  

 

 

I have found some tools for creating documentation like Doxygen and Sigasi. But Doxygen has only few features to support VHDL language and Sigasi is not free tool.  

 

 

Thanks
0 Kudos
7 Replies
Altera_Forum
Honored Contributor I
355 Views

Usually, we write word documentation showing the architecture and interfaces, design decision etc.

Altera_Forum
Honored Contributor I
355 Views

 

--- Quote Start ---  

Usually, we write word documentation showing the architecture and interfaces, design decision etc. 

--- Quote End ---  

 

 

Hi, Tricky 

 

Can I ask you to share some examples? Or could you point me where to find good detailed FPGA project documentation? Because now i dont have any ideas from where to start.  

I have googled for documents which describes whole FPGA design but did not find anything except small readme files for separate VHDL files.
Altera_Forum
Honored Contributor I
355 Views

I cant share because they are all protected company documents. 

Usually, the document contains: 

 

1. Reasons for the project 

2. The interfaces used and why 

3. The overall architecture and design functionality 

4. Interface descriptions, including block to block port map, CPU register map etc. 

5. Test plan, including the testbenches required, the tests required, and the hardware tests required. 

6. The estimated resource usage 

 

And this should all be written and reviewed before you write much/any HDL (obviously it should be updated as things change during the implementation, as they inevitably will)
Altera_Forum
Honored Contributor I
355 Views

Apart from writing a high level description (text, not code) of the system in word or similar programs, I also include a short behavioural description in the first few lines of each source file. 

If that is a package I write the reason for that package. 

Most of the time I also include one or more block diagrams in the high level description.
Altera_Forum
Honored Contributor I
355 Views

Thank you for your answers (Tricky, PietervanderStar). 

 

So there is no other popular solution to document projects apart from writing word documents?
Altera_Forum
Honored Contributor I
355 Views

 

--- Quote Start ---  

Thank you for your answers (Tricky, PietervanderStar). 

 

So there is no other popular solution to document projects apart from writing word documents? 

--- Quote End ---  

 

 

Some people use libreoffice (because it's free). 

This is a cool website for drawing wave diagrams: 

 

http://wavedrom.com/ 

 

Use Visio for other diagrams. 

 

Documentation is engineers bugbear. They hate creating it, and hate it when other engineers havent created it.
Altera_Forum
Honored Contributor I
355 Views

Inaddition to Trickys reply, most of "us engineers" don't mind how itnis written as long as it is clear and easy to understand.