Documenting Digital Design - Schematics and Figures

Question

I'm working on a small digital design using a Xilinx picoblaze softcore processor, and I'm finding that producing schematics of acceptable quality to be frustrating and time consuming. I've attempted to shoehorn previously drawn schematics (From LTSpice, or Eagle) into documentation, but the results look fuzzy or terrible.

I've been using LibreOffice Draw, with subpar results - because the drawings do not contain any information about connections, having to propagate a small change through all items is really frustrating. For example, if I want to add a port onto a part, but that part appears multiple times in my schematic, I have to add them to every instance by hand.

Similarly, when deciding the format of my wires and bus lines, perhaps I'd like the wires to 'jump' when not connected to another line? What if I'd like to add a bubble to indicate connections instead? These items must all be added by hand, which is ridiculous.

I'm sure something like this could be done with LaTeX, but I'd like the feedback of being able to look at my drawing as it is being built, and I need to convince other people who are working on this project to use similar tools, and not many people are willing to undergo the learning curve of LaTeX just for this purpose.

I've tried Inkscape and Dia and found them to be lacking, I've used LTSpice, but that's for SPICE and not digital schematics, and the diagrams are not very appealing anyway - a similar argument for EAGLE schematics.

Is there a better way, something that I'm missing or not considering? I've just begun examining Electric VLSI - it seems to be a much better fit, but still rough around the edges.

Does anyone have a good suggestion? Thanks!

Answer 1

Here is a better way: Don't!

The best way to document the design is by using the original code (VHDL, or Verilog). This is the most accurate, and will always be up to date. For simple designs, schematics might be more readable but that is not true for medium to large FPGA designs. At that size, schematics become hard to follow, large, cumbersome, difficult to modify/update, and are impossible to debug. So just don't use them.

When I have to document an FPGA design with schematics, I do it with Visio and make it more of a high level block diagram than schematics. Doing anything with more detail is a frustrating and fruitless task.

I would also argue that VHDL/Verilog are not difficult to follow. If someone can't follow them then the problem is the person, not the code. I have some FPGA designs that if printed out would take up about 800 pages of standard paper. That same design, if shown using schematics, would require 2,000+ large pages. It is easier to get proficient at reading VHDL/Verilog than to transcribe 800 pages of VHDL code into schematics (and then keep it up to date and accurate).

Answer 2

While I agree with David that trying to produce detailed schematics to mirror your FPGA design is more trouble than it's worth, sometimes just writing clean code is not an option. I have been in situations where the design must be documented fully and the documentation must be readable by people who can't read code and have no intention of learning.

My solution was to adapt a verbose commenting style and use doxygen to produce HTML or PDF documents that fully documented the design in a fashion that was easily understandable by those not inclined to be able to read code. The actual code structure can be automatically extracted and it will group and link the relevant sections which would be of more use to team members trying to figure out how different code sections fit together.

Some discipline needs to be maintained so that comments always reflect the code but at least you aren't jumping back and forth between programs trying to keep things in sync. There is a slight learning curve but much less (IMO) than \$\LaTeX\$. It supports Markdown which is what the Stack Exchange uses. So anyone on your team that uses this site should already be familiar. It supports VHDL out of the box with a plugin available for Verilog.

After a slight learning curve and some initial setup, it becomes a one click solution to generating documents that can even be scripted into your build process if you're so inclined.

Answer 3

Have you tried using CircuitLab? It isn't digital-oriented, and we have some room to grow the symbol library, but it does produce what I think are nice-looking schematics and a lot of our users say they're embedding the resulting PDF/PNG/EPS/SVGs into documentation/reports/presentations. You can use the "custom part" tool to define rectangular items, and add some standard digital symbols around that. (Disclaimer: I'm one of the developers and wrote some of the rendering code, but not the UI.)