Documenting DSP pipeline?

[mrflibble]

What do you DSP people use to document your far-too-long and complex DSP pipelines?

When you have multiple stages of multipliers, adders, accus and whatnot ... what tools do you use to keep track of this? If the answer is "visio" are there any specific stencils needed that did not come with the basic visio install?

thanks!

 

[permute]

Honestly, I usually use comments in the code. The biggest issue with any method is staleness. Eg, if you make a formal visio drawing, it will be out of date after rev 1.1. The same goes for any comments in the HDL, but that's at least easier to see when modifying the code.

a good text editor makes ascii-tables easy to draw.

 

[mrflibble]

You are exactly right about the staleness. As for any decent technical person, documentation is my favorite thing!

So to prevent documentation staleness, the best way I found is to make the maintenance of documentation as low threshold as possible. Adding comments to the HDL is a pretty good way. However for a multi-stage pipeline, the ascii art becomes hard to maintain. Suppose I have to move an accumulator to somewhere else in the pipeline, that is quite a bit of ascii art editing. So as far as I am concerned that method is out.

Or maybe you don't mean ascii art, but mean that I just maintain the formula's for every stage in HDL comment? If yes, that is exactly what I do now. But I find that 1 overview picture really helps in understanding what is going on. I can't get that from a long line of expressions.