1. Home
  2. Field-Programmable Gate Arrays
  3. FPGA Design Docs

FPGA Design Docs

I work in a large company. Two years ago, most of our FPGA developments were over budget and schedule. Management wanted us to fix this. We've been successful and today only a few FPGA developments have severe problems. As you can imagine, there's more structure and "process" in the development. However, we have tried hard to keep it reasonable and most of the developers adopt the key elements with only a little whining.

There are a few things we're still working and one of these is documentation. All of our developments have a good requirement spec and most can pick up anyone's VHDL and figure out the lower level functions. The element we're missing is the middle level documentation. To me this is a detailed block diagram with enough verbiage or whatever to describe the flow of the design and how the major functions work together. This level of documentation is not being captured in our designs and it becomes tough for another developer to pick up a design and fix anything but the most minor items. No one wants to pay for or create a document that's not immediately useful so I'd rather not force that. Rather than defining something new, I'd like some suggestions on what others do. Is there a document that can be created during the development that answers this and benefits the developer as well? Is there another way to approach this problem?

Sam

Reply to
se
Loading thread data ...

I use regression testing, code comments and source control to cover these problems.

One way to capture theory of operation details is with multiple levels of closed loop testbenches that are run between builds.

If I write code that breaks the regression suite, I debug the problem using the simulator and then add steps to the test to cover the new code. Running the testbench and looking at waveforms of interest is always up to date and better than any other type of technical documentation for me or for another developer.

All other design documentation is done using text comments right in the code.

I use simple text with block diagrams like this:

--[foo]---[bar]---[bas]--

and timing diagram snippets like this

--foo ___--__-_-__----

--bar ___-____-_-_-___

My most important code comments consist of a plain English description of what I expect the module to do. Here I introduce significant variables and structures by name, and explain what happens to them. This gives me a starting point and reference to use while writing and debugging the code.

If all developers maintain such comments in all modules, then all levels are covered. In any case, there is at least a regression suite to watch the waves with.

-- Mike Treseler

Reply to
Mike Treseler

Does this really cover the problem the OP is outlining Mike?

If one of your designs is handed to another engineer with the details of a bug that your testbenches don't pick up, it's going to be really hard for the new engineer to know where to look without some top level hierarchical description of the design.

One idea I had was a system where a top level hierarchy could be drawn. Each block could represent sub levels of the hierarchy/design modules etc, data paths would be shown here.

If a block represents a design module it could be drawn with a bold (?) outline to represent that, and clicking it (or hyperlinks in the block) would open up source code, testbenches, scanned design notes/timing diagrams for that particular module.

If a block represents a level of hierarchy then it could be clicked down through to the next level.

It's the best way I can think if of collating all the design documentation for a design in a manner that makes it easier to see what's doing what in the overall scheme of things.

Nial.

Reply to
Nial Stewart

I agree, but a good editor can do this. See:

formatting link

-- Mike Treseler

Reply to
Mike Treseler

ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.