Documentar diseño digital - Esquemas y figuras

Aquí hay una mejor manera: ¡No!

La mejor manera de documentar el diseño es usando el código original (VHDL o Verilog). Este es el más preciso, y siempre estará actualizado. Para diseños simples, los esquemas pueden ser más legibles, pero eso no es cierto para los diseños de FPGA de mediano a grande. En ese tamaño, los esquemas se vuelven difíciles de seguir, grandes, engorrosos, difíciles de modificar / actualizar, y son imposibles de depurar. Así que simplemente no los uses.

Cuando tengo que documentar un diseño de FPGA con esquemas, lo hago con Visio y lo hago más como un diagrama de bloques de alto nivel que los esquemas. Hacer cualquier cosa con más detalle es una tarea frustrante e infructuosa.

También diría que VHDL / Verilog no son difíciles de seguir. Si alguien no puede seguirlos, entonces el problema es la persona, no el código. Tengo algunos diseños de FPGA que si se imprimen ocuparían unas 800 páginas de papel estándar. Ese mismo diseño, si se muestra usando esquemas, requeriría más de 2,000 páginas grandes. Es más fácil dominar la lectura de VHDL / Verilog que transcribir 800 páginas de código VHDL en esquemas (y luego mantenerlo actualizado y preciso).

Si bien estoy de acuerdo con David en que tratar de producir esquemas detallados para reflejar su diseño de FPGA es más problemático de lo que vale, a veces simplemente escribir código limpio no es una opción. He estado en situaciones donde el diseño debe estar completamente documentado y la documentación debe ser legible por personas que no pueden leer el código y no tienen intención de aprender.

Mi solución fue adaptar un estilo de comentario detallado y utilizar doxygen para producir documentos HTML o PDF que documenten completamente el diseño. de una manera que era fácilmente comprensible para aquellos que no estaban dispuestos a poder leer el código. La estructura de código real se puede extraer automáticamente y agrupará y vinculará las secciones relevantes, lo que sería más útil para los miembros del equipo que intentan descubrir cómo encajan las diferentes secciones de código.

Debe mantenerse cierta disciplina para que los comentarios siempre reflejen el código, pero al menos no está saltando de un lado a otro entre programas que tratan de mantener las cosas sincronizadas. Hay una leve curva de aprendizaje pero mucho menos (IMO) que \ $ \ LaTeX \ $ . Es compatible con Markdown que es lo que usa Stack Exchange. Así que cualquiera en su equipo que use este sitio ya debería estar familiarizado. Admite VHDL fuera de la caja con un complemento disponible para Verilog.

Después de una ligera curva de aprendizaje y un poco de configuración inicial, se convierte en una solución de un solo clic para generar documentos que incluso pueden incluirse en el proceso de compilación si lo desea.

¿Ha intentado usar CircuitLab ? No está orientado a lo digital, y tenemos espacio para hacer crecer la biblioteca de símbolos, pero produce lo que creo que son esquemas de buen aspecto y muchos de nuestros usuarios dicen que están incrustando el PDF / PNG / EPS resultante SVGs en documentación / informes / presentaciones. Puede utilizar la herramienta "parte personalizada" para definir elementos rectangulares y agregar algunos símbolos digitales estándar alrededor de eso. (Descargo de responsabilidad: soy uno de los desarrolladores y escribí parte del código de representación, pero no la interfaz de usuario).