La prueba «Hola, mundo» de Xillybus
Este es el tercer paso para empezar con Xillybus: el flujo de bits (bitstream) que contiene Xillybus ya está cargado en la FPGA, y el controlador está instalado en el ordenador anfitrión. Ahora toca hacer una prueba sencilla. El propósito de esta prueba es comprobar que se han creado los archivos de dispositivo (device files) y que funcionan.
Esta página trata de Xillybus cuando el ordenador anfitrión usa Windows. Hay una página similar para Linux.
Aquí me centraré en Xillybus con PCIe, pero con XillyUSB casi todo es igual. Las diferencias se indican al final de esta página.
Para más información sobre este tema, consulta Getting started with Xillybus on a Windows host.
¿Se detecta el dispositivo PCIe?
El Administrador de dispositivos (Device Manager) muestra los dispositivos PCIe que se han detectado. Esto ya se explicó anteriormente en el contexto de la instalación del controlador.
Antes de instalar el controlador, el dispositivo de Xillybus aparecía en la lista de «Otros dispositivos» (Other Devices). Después de la instalación, este dispositivo aparece en un grupo llamado «Xillybus». Si el Administrador de dispositivos no muestra ninguna de estas dos opciones, la FPGA no se detecta como dispositivo PCIe: probablemente hay un problema con la FPGA. A menudo el motivo es una confusión sobre qué flujo de bits se ha cargado en la FPGA.
Hay capturas de pantalla y una explicación más detallada sobre este tema en la guía de inicio para Windows.
¿Se ha iniciado el controlador correctamente?
El siguiente paso es comprobar el estado del controlador. Esto se hace en el Administrador de dispositivos: haz clic con el botón derecho sobre el icono situado en el grupo «Xillybus» (el nombre del dispositivo es «Xillybus driver for generic FPGA interface»). Elige «Propiedades» (Properties). Aparecerá una ventana emergente. Busca el recuadro de texto cuyo título es «Estado del dispositivo» (Device status). El texto que aparece debe ser «Este dispositivo funciona correctamente» (The device is working properly). Esto significa que el controlador ha inicializado Xillybus correctamente y ha creado los archivos de dispositivo necesarios.
Si el texto dice cualquier otra cosa, algo ha ido mal durante la inicialización del controlador. Normalmente se trata de un problema con la lógica de la FPGA. En particular, esto suele ocurrir cuando el bloque PCIe de la FPGA está mal configurado. Por ejemplo, si cambiaste los parámetros del bloque PCIe en el paquete de demostración (demo bundle), puede provocar errores de este tipo.
Puedes encontrar más información sobre el problema en el Visor de eventos (Event Viewer) de Windows. Los mensajes del controlador de Xillybus se pueden filtrar: crea una vista personalizada que muestre los mensajes del origen llamado «Xillybus». Cómo hacerlo se explica en detalle en la guía de inicio para Windows.
«Hola, mundo»
El controlador crea cinco archivos de dispositivo: \\.\xillybus_read_8, \\.\xillybus_read_32, \\.\xillybus_write_8, \\.\xillybus_write_32 y \\.\xillybus_mem_8. Ten en cuenta que si creas un núcleo IP personalizado (custom IP core) en la IP Core Factory, puedes elegir cuántos archivos de dispositivo se crean, así como sus nombres y sus propiedades.
Pero, en este momento, la FPGA contiene el paquete de demostración. Probemos con dos de los archivos de dispositivo. Estos archivos de dispositivo son en realidad objetos del sistema operativo, pero pueden tratarse como archivos normales. La parte «\\.\» puede parecer extraña a quienes no estén familiarizados con la programación de bajo nivel en Windows. Sin embargo, así es como el software de espacio de usuario (user-space software), normalmente DLL, suele acceder al hardware.
En el paquete de demostración hay un bucle de retorno (loopback) entre read_8 y write_8. Esto significa que, cuando el ordenador escribe datos en write_8, la FPGA devuelve exactamente los mismos datos a través de read_8. Esto está pensado únicamente como demostración; no tiene ningún otro uso práctico.
La prueba es la siguiente: abre dos ventanas del Símbolo del sistema (Command Prompt) en tu ordenador. En ambas ventanas, cambia el directorio a «precompiled-demoapps». Este directorio está dentro del directorio «xillybus-windowspack». Recuerda que en su momento te sugerí descargar xillybus-windowspack.zip junto con el paquete de demostración.
Escribe esto en la primera ventana del Símbolo del sistema:
$ streamread \\.\xillybus_read_8
A continuación, escribe esto en la segunda ventana del Símbolo del sistema:
$ streamwrite \\.\xillybus_write_8
Ahora escribe cualquier cosa en la segunda ventana y pulsa ENTER. El mismo texto aparecerá en la primera ventana. De este modo se ve cómo el texto se escribió en el primer archivo de dispositivo, llegó después a la FPGA y finalmente volvió al ordenador.
Puedes detener estos dos programas con CTRL-C.
El código fuente de estos programas se encuentra en el subdirectorio demoapps (del mismo archivo Zip). Los programas están escritos en C y demuestran cómo acceder a los archivos de dispositivo de Xillybus mediante una API estándar de entrada/salida (I/O). La guía de inicio para Windows sugiere cómo compilar estos programas.
Aunque este ejemplo es sencillo, es importante entender cómo funciona. En particular, conviene entender cómo la lógica de la FPGA hizo posible que esto ocurriera. Ese es el punto de partida para integrar tu propia lógica.
XillyUSB
Si estás usando XillyUSB, todo lo dicho arriba es aplicable, pero hay algunas diferencias.
XillyUSB incluye una herramienta llamada showdiagnostics para examinar la calidad de la conexión física con la FPGA. Se recomienda encarecidamente utilizar esta herramienta para asegurarse de que el enlace de datos en bruto esté libre de errores. Aunque XillyUSB parezca funcionar perfectamente, es importante hacer esta comprobación. La razón es que el protocolo USB 3.0 oculta los errores que se producen en el enlace de datos en bruto, pero esos errores pueden causar problemas poco frecuentes que parecen un bug.
No hay motivo para tolerar errores de este tipo. La solución suele ser sencilla, por ejemplo, usar otro puerto USB del ordenador.
Otras diferencias:
- Los nombres de los archivos de dispositivo son un poco diferentes. Por ejemplo, en lugar de \\.\xillybus_read_8, el nombre es \\.\xillyusb_00_read_8. La parte «00» puede variar.
- El Administrador de dispositivos mostrará el dispositivo en el grupo llamado «Controladores de bus serie universal» (Universal Serial Bus controllers), tanto si el controlador está instalado como si no.