01signal: Guía de inicio rápido para Xillybus

Introducción

Esta página es un resumen breve de cómo empezar con Xillybus o XillyUSB. Normalmente es un procedimiento rápido y sencillo que no necesita mucha ayuda. Sin embargo, hay pequeñas variaciones según la FPGA.

Aquí solo se tratan los casos de uso más habituales y las FPGA más recientes. Si la información de esta página se queda corta, consulta la página de documentación de Xillybus, donde encontrarás información más detallada y específica.

No voy a hablar de Xillinux aquí, porque su procedimiento es un poco diferente.

Descripción general

Para empezar con Xillybus hay tres pasos:

El primer paso es generar un flujo de bits (bitstream) para la FPGA a partir del paquete de demostración (demo bundle).
El segundo paso es instalar el controlador en el ordenador (a menudo no es necesario).
El tercer paso es hacer una prueba sencilla en el ordenador que demuestre que Xillybus funciona (se explica en páginas aparte para Linux y para Windows).

Más adelante, puede que quieras crear tu propio núcleo IP personalizado (custom IP core) en la IP Core Factory. Esto te permitirá elegir tantos flujos (streams) como quieras. Pero antes de llegar a eso, probar el paquete de demostración te ayudará a entender cómo funciona Xillybus.

Xillybus vs. XillyUSB

Si estás pensando en usar XillyUSB, plantéate elegir Xillybus para PCIe si esa opción es realista: el bus PCIe es mucho más robusto que el USB.

XillyUSB solo debería utilizarse cuando la FPGA tenga que estar físicamente fuera del ordenador (por ejemplo, cuando el equipo anfitrión es un portátil).

Descarga del paquete de demostración y del software

Todo lo que se puede descargar desde la web de Xillybus es totalmente funcional. Esto incluye tanto los núcleos IP (IP cores) de la IP Core Factory como los paquetes de demostración. No hace falta pedir un código de activación ni nada parecido. Sin embargo, el permiso legal para usar el núcleo IP es limitado: solo puedes usarlo para evaluación. Después, puede que sea necesario comprar una licencia para poder seguir usándolo legalmente. Así que asegúrate de entender bien las condiciones.

Hay dos páginas web independientes para descargar archivos: una para Xillybus mediante PCIe y otra para XillyUSB. Ve a la página correspondiente y descarga lo siguiente:

El paquete de demostración pensado para tu placa.
El controlador para Linux o Microsoft Windows. Descárgalo incluso si usas Linux y el controlador ya está incluido en la distribución.
Solo usuarios de Windows: el paquete de Xillybus para Windows.
Solo usuarios de XillyUSB en Windows: la utilidad de diagnóstico para Windows.

Todos estos archivos están en formato .zip o .tar.gz. Así que empieza por descomprimir su contenido en el disco.

Si tu placa no está en la lista de paquetes de demostración, tendrás que hacer modificaciones sobre el paquete. Elige el paquete de demostración basado en la misma familia de FPGA y sigue las instrucciones de la documentación para Xilinx o para Intel FPGA.

El siguiente paso es distinto para AMD/Xilinx y para Altera.

Generación del flujo de bits para AMD/Xilinx

Necesitas tener Vivado instalado en tu ordenador. En la documentación encontrarás una lista de versiones adecuadas para cada FPGA. Pero si ya tienes Vivado instalado, pruébalo. Si la versión de Vivado no es adecuada, el procedimiento que se detalla abajo fallará: aparecerá un error indicando que se requiere una versión más reciente. Si no aparece ese error, tu versión de Vivado es correcta.

Estos son los pasos para generar el flujo de bits:

Dentro de Vivado, selecciona Tools > Tcl Script… y busca el archivo xillydemo-vivado.tcl. Este archivo está en el subdirectorio llamado verilog/ o vhdl/. Seguramente sabes cuál prefieres; si no lo sabes, elige verilog/.
Como resultado, Vivado crea un proyecto FPGA nuevo. La consola Tcl de Vivado dirá “INFO: Project created: xillydemo”.
A continuación, haz clic en “Generate Bitstream”.
Vivado ejecutará la implementación del proyecto. Al final del proceso tendrás un flujo de bits listo para usar. El archivo se llama xillydemo.bit.

Vivado generará varias advertencias durante la implementación, pero no debería haber advertencias críticas (critical warnings) ni errores.

La explicación detallada está en este documento: Getting started with the FPGA demo bundle for Xilinx. Ten en cuenta que Vivado no funciona con Virtex-5, Spartan-6 ni Virtex-6. Si usas una de estas FPGA, consulta ese documento.

No intentes crear el proyecto de FPGA sin el guion Tcl (script). Si intentas crear un proyecto nuevo e importar los archivos fuente, probablemente no funcionará bien.

Creación del flujo de bits para Altera

Necesitas tener Quartus instalado en tu ordenador. En la documentación encontrarás una lista de versiones adecuadas para cada FPGA. Pero si ya tienes Quartus instalado, pruébalo. Si la versión de Quartus no es adecuada, el procedimiento que se detalla abajo fallará: aparecerá un error indicando que se requiere una versión más reciente. Si no aparece ese error, tu versión de Quartus es correcta.

Estos son los pasos para generar el flujo de bits:

Haz doble clic en el archivo xillydemo.qpf. Este archivo está en el subdirectorio llamado verilog/ o vhdl/. Seguramente sabes cuál prefieres; si no lo sabes, elige verilog/.
Quartus abrirá el proyecto FPGA.
Haz clic en “Compile Design”.
Quartus ejecutará la implementación del proyecto. Al final del proceso tendrás un flujo de bits listo para usar. El archivo se llama xillydemo.sof.

Quartus generará varias advertencias durante la implementación, pero no debería haber advertencias críticas (critical warnings) ni errores.

La explicación detallada está en este documento: Getting started with the FPGA demo bundle for Intel FPGA. Si tu FPGA es anterior a la serie V (por ejemplo, Cyclone IV), el procedimiento es un poco más largo. Consulta ese documento para más información.

Instalación del controlador para Microsoft Windows

El controlador de Xillybus para Windows se instala de la forma habitual: enciende el ordenador con la placa FPGA dentro. La FPGA debe tener cargado el flujo de bits que contiene Xillybus antes de encender el ordenador.

Primero, extrae el contenido del archivo Zip que contiene el controlador en el disco local. Este archivo se encuentra en la página de descarga del paquete de demostración. El nombre del archivo es algo así como xillybus-windriver-1.2.0.0.zip.

En el Administrador de dispositivos (Device Manager), debería aparecer un dispositivo en la categoría “Otros dispositivos” (Other Devices). El icono de ese dispositivo indicará que no se ha instalado correctamente (llevará un signo de exclamación). Haz clic con el botón derecho sobre ese icono y selecciona “Actualizar software de controlador…” (Update Driver Software…). Elige la opción de buscar un archivo en el ordenador (“Buscar software de controlador en el equipo”). Selecciona a continuación el directorio llamado xillybus-windriver-1.2.0.0 (o similar), haz clic en “Siguiente” (Next) y después en “Instalar” (Install).

Tras la instalación correcta del controlador, aparecerá un grupo nuevo en el Administrador de dispositivos con el nombre “Xillybus”. Dentro de ese grupo habrá un dispositivo con el nombre “Xillybus driver for generic FPGA interface”. El icono de ese dispositivo no debe indicar ningún error (es decir, no debe tener ningún signo de exclamación).

Si se utiliza XillyUSB, el dispositivo aparecerá en el grupo llamado “Controladores de bus serie universal” (Universal Serial Bus controllers), y el controlador se encuentra en xillyusb-windriver-1.1.2.0-win10.zip.

Este proceso de instalación se describe con más detalle e incluye capturas de pantalla en la guía para Windows.

Después de instalar el controlador de Windows, el siguiente paso es hacer una prueba sencilla. Esto se explica en una página aparte.

Instalación del controlador para Linux(?)

El controlador de Xillybus está incluido en muchas distribuciones de Linux para ordenadores de sobremesa. Así que si usas Fedora, Ubuntu o Mint, lo más probable es que el controlador de Xillybus ya esté instalado en tu ordenador.

Para comprobar si el controlador ya está instalado, escribe esto en el indicador del shell:

$ modinfo xillybus_core

Si la respuesta son varias líneas de texto, el controlador ya está instalado y no tienes que hacer nada. Solo tienes que instalar el controlador si la respuesta es “modinfo: ERROR: Module xillybus_core not found”.

Si quieres usar XillyUSB, el comando es:

$ modinfo xillyusb

Aunque el controlador ya esté instalado, es buena idea instalar el archivo udev de Xillybus. Consulta el final de esta página. También puedes omitir este paso e ir directamente a una prueba sencilla.

Si el controlador no está instalado, tienes dos opciones:

Instalar el controlador como módulo del kernel. Cómo hacerlo se explica a continuación. Esta opción es adecuada si no has preparado el kernel por ti mismo (es decir, si has recibido el kernel como parte de una distribución o de un BSP —Board Support Package—).
Habilitar el controlador que ya está dentro del árbol del kernel. Este método requiere compilar el kernel completo. Si la compilación del kernel forma parte de tu procedimiento de trabajo, esta es la opción más fácil. Las opciones relevantes son CONFIG_XILLYBUS y CONFIG_XILLYBUS_PCIE (o CONFIG_XILLYUSB).

El controlador de Xillybus forma parte del árbol del kernel de Linux desde la versión v3.12. Si tu kernel es v4.6 o posterior, no hay motivo para actualizar el controlador: desde esa versión no ha habido cambios importantes (solo cambios de estilo de código). El controlador de XillyUSB se añadió en Linux v5.14.

Puedes encontrar más información sobre cómo empezar con Linux en la guía correspondiente.

Compilación del módulo del kernel

Para compilar el módulo del kernel de Xillybus es necesario que en el ordenador que realiza la compilación ya estén instaladas tres cosas:

El compilador gcc
“make”
Los encabezados del kernel (kernel headers) para el kernel que se usará con Xillybus

En la guía correspondiente para Linux se explica cómo comprobar si estos elementos están instalados y cómo instalarlos si no es así.

La compilación del controlador se realiza de la siguiente manera:

$ tar -xzf xillybus.tar.gz
$ cd xillybus/module/
$ make
make -C /lib/modules/4.15.0/build M=/home/01signal/xillybus/module modules
make[1]: Entering directory '/usr/src/linux-headers-4.15.0'
  CC [M]  /home/01signal/xillybus/module/xillybus_core.o
  CC [M]  /home/01signal/xillybus/module/xillybus_pcie.o
  Building modules, stage 2.
  MODPOST 2 modules
  CC      /home/01signal/xillybus/module/xillybus_core.mod.o
  LD [M]  /home/01signal/xillybus/module/xillybus_core.ko
  CC      /home/01signal/xillybus/module/xillybus_pcie.mod.o
  LD [M]  /home/01signal/xillybus/module/xillybus_pcie.ko
make[1]: Leaving directory '/usr/src/linux-headers-4.15.0'

Para instalar los módulos del kernel, escribe “make install” (esto requiere ser root).

El controlador se cargará automáticamente la próxima vez que el kernel arranque con un dispositivo Xillybus presente en el bus. También es posible usar insmod para cargar el controlador manualmente.

Ten en cuenta que quienes tengan previsto usar Xillybus en un sistema Linux embebido puede que necesiten un compilador cruzado (cross compiler). En esa situación también son necesarios los encabezados del kernel correspondientes al kernel embebido.

Si no quieres usar “make install”, puedes hacer lo mismo manualmente: copia los archivos de módulo al directorio que contiene los módulos del kernel. El nombre de ese directorio debe contener el número de versión del kernel que se usará con Xillybus.

Por ejemplo:

# cp xillybus_core.ko /lib/modules/4.15.0/kernel/drivers/char/
# cp xillybus_pcie.ko /lib/modules/4.15.0/kernel/drivers/char/

Después de esto, ejecuta depmod para que el kernel tenga constancia de los módulos nuevos. Por ejemplo:

# depmod -a 4.15.0-20

Archivo udev (Linux)

Se recomienda instalar el archivo udev de Xillybus, aunque el controlador ya esté instalado. Esto permite acceder a Xillybus sin tener que ser el usuario root. Este archivo forma parte del paquete que contiene el controlador (xillybus.tar.gz o xillyusb.tar.gz).

La instalación del archivo udev de Xillybus se hace con este comando (o similar), como usuario root:

# cp 10-xillybus.rules /etc/udev/rules.d/

¿Funciona?

El siguiente paso es comprobar que has hecho todo bien y que Xillybus funciona con tu hardware. Cómo hacerlo se explica por separado para Linux y para Windows.