Tutorial: entender el substrato del DRx
Estas páginas no son una referencia: son un camino de aprendizaje. Van en orden, cada una
explica por qué existe lo que explica antes de decir cómo funciona, y todas terminan con resultados
reales — números y salidas de consola que produce el repositorio hoy, no ejemplos inventados.
Si solo quieres el inventario de lo que hay construido y su estado, ve a
Substrato Z0. Si quieres entenderlo, sigue aquí.
El orden
|
Página |
Qué aprendes |
| 1 |
El paquete de parámetros |
Por qué una sola constante gobierna el proyecto entero, y cómo se impide que aparezca una segunda |
| 2 |
Aritmética de punto fijo |
Complemento a dos, redondeo, saturación, y por qué un LSB importa |
| 3 |
La cadena DDC |
NCO, mezclador, CIC, FIR y enrejado en rango, con las gráficas que salen del modelo |
| 4 |
Simulación |
Qué son Verilator, cocotb y pytest, cómo encajan y dónde se rompió el plan |
| 5 |
El contrato DRx↔DSP |
Un esquema, tres lenguajes, y cómo se comprueba que no divergen |
| 6 |
Gateware |
El flujo Vivado sin GUI y qué hace falta para un BOOT.BIN reproducible |
| 7 |
Resultados |
Todo lo que está verde hoy, con su salida real |
Antes de empezar: monta el entorno
make venv # crea .venv e instala requirements-dev.txt, con versiones pinadas
make check # corre todos los gates que no necesitan Vivado
Hacen falta verilator, gcc y make en el PATH. En Debian y Ubuntu:
sudo apt-get install -y verilator gcc make
Las herramientas externas, y por qué cada una
Este proyecto usa piezas de terceros. Cada enlace va a la documentación oficial; si algo de las
páginas siguientes te suena a magia, empieza por aquí.
Simulación y verificación
| Herramienta |
Qué es |
Por qué la usamos |
| Verilator |
Compilador de Verilog/SystemVerilog a C++ que produce un simulador nativo |
Rápido y libre, sin licencia en el runner de CI. Es el nivel L0 de D-05 |
| cocotb |
Framework para escribir testbenches de HDL en Python en vez de en SystemVerilog |
Los bancos comparten lenguaje con el modelo dorado, así que el oráculo se importa directamente en el testbench |
| pytest |
Runner de tests de Python |
Un único comando corre el modelo, la simulación, el contrato y el firmware |
| Verilator: catálogo de avisos |
La lista de qué significa cada UNUSEDSIGNAL, WIDTH… |
Es lo que hay que leer cuando el lint falla en CI |
Numérico
| Herramienta |
Qué es |
Por qué |
| NumPy |
Álgebra y arrays en Python |
El modelo dorado trabaja sobre arrays de enteros de 64 bits |
| SciPy · señal |
Diseño de filtros, entre otras cosas |
firwin2 diseña el FIR compensador por muestreo en frecuencia |
| Herramienta |
Qué es |
Por qué |
| TOML |
Formato de configuración legible y sin ambigüedades |
config/params.toml es la fuente única de verdad |
tomllib |
Lector de TOML en la biblioteca estándar de Python desde 3.11 |
Leer los parámetros no añade ninguna dependencia |
| Ruff |
Linter y formateador de Python |
Gate de estilo en CI |
| uv |
Gestor de entornos y paquetes de Python |
Instala el entorno pinado en segundos, igual en local que en CI |
FPGA y hardware
Teoría
| Referencia |
Para qué |
| Filtro CIC (resumen) |
Entender integradores y peines antes de leer el modelo |
| Hogenauer, An economical class of digital filters for decimation and interpolation, IEEE TASSP, 1981 · DOI |
El artículo original: de aquí sale la fórmula del ancho de registro |
| Oscilador controlado numéricamente |
Qué es una palabra de fase y por qué truncarla produce espurios |
| Complemento a dos |
La representación de todos los enteros con signo del proyecto |
Infraestructura
Cómo se mantiene esto honesto
Todas las gráficas de este tutorial salen de tools/gen_docs_figures.py, que las dibuja
ejecutando el propio modelo dorado. Todos los números y las salidas de consola están copiados de
ejecuciones reales. Si el modelo cambia y alguien no regenera, la documentación y el código
discrepan de forma visible en vez de en silencio.