Home » Alchitry Notes

Categories

Alchitry Notes

Notes on setting up and using Alchitry FPGA boards

(last updated November 3, 2020 by Eric Prebys)

These are notes on acquiring, setting up, and using the Alchitry Au FPGA board. At the time this page was first written, there were a lot of problems with the documentation at the Alchitry website, but it has improved significantly since then.

Hardware

You’ll need the following hardware from Alchitry

  • Alchitry Au FPGA board:  main board with FPGA and USB-C interface
  • Alchitry Io I/O board:  has 24 DIP switches, 24 LEDs, 4 segment displays, and 5 pushbuttons
  • (Optional) Alchitry Br breakout board:  extra board that goes between the Au and the Io board, to allow connections to all the other I/O pins on the FPGA.  For example, you’ll need this to access the analog inputs for the XADC example below.

The interface to the board is USB-C, which also provides power, so depending on your computer, you’ll need a USB-C or USB to USB-C cable.

Software

This can be a little confusing, because the website is a mix of their old Mojo Board stuff, examples using the older Xilinx ISE software, and finally the more modern version, using Vivado, which is what you want.

You’ll need the Vivado sofware from Xilinx to compile the FPGA code, but because this board is not officially supported by Xilinx, you cannot download the bitfile from the Vivado Hardware Manager.  If you want to build your project using exclusively Vivado, you’ll need at least the Alchitry Loader; however, Alchitry also has their own simplified IDE, called “Alchitry Labs”, which will allow you to build projects by calling Vivado in the background and then downloading the file directly.  That’s the path I’m using for the P116B course at UC Davis, and that’s what’s described below.

Before you start, make sure you’ve got the latest versions of the Java Runtime environment found here (click “Java Download”) and the Java Development Kit, found here (accept the license agreement and download the Windows executable installer).

Follow the instructions here to download the correct (free) version of Vivado and the required Alchitry software.  The software runs on Windows and Linux, but I’ve only tested it on Windows (Unlike ISE, it works fine from the Windows VM on my Mac).  Be warned that even the minimal version of Vivado takes over 20 Gbytes of disk space!  Note that the newest version of Vivado doesn’t quite match the screen shots at the Alchitry site.  The key points are that you want to install “Vivado” rather than “Vadis”, and eliminate all the optional devices to save disk space (Vivado requires you to install several Series 7 devices, which contains the one you need).

Starting with version 1.2, you no longer need to download any special drivers to use the board.

The Alchitry Labs IDE will work with Verilog or VHDL.  It also supports the “Lucid” language, which is a more C-like version of Verilog.  In the case of Lucid, the Alchitry Lab IDE precompiles it into Verilog, which is then passed to Vivado.  I’m sticking with Verilog.

Getting Started

If you follow the tutorial links, you’ll find a lot of them are outdated.   The easiest way to get started is to launch Alchitry Labs, do “File->Open Project…”, then navigate to “(installation dir)/library/base/alchitry-au/Verilog/Base Project/” and open “Base Project.alp”.  You can then do “File->clone project…” to make a local copy and start from there.  You can also start with this example project, which implements a variable speed counter that will display on the Io board in HEX or DEC.  It demonstrates a lot of the functionality of the Io board. Details in comments of main file.

The program expects the top file to be called “au_top.v”.  Any other files you add are automatically linked.  Under “Constraints”, you’ll find the “au.xdc” file that’s passed directly to Vivido, with some general constraints.   There is also the file “alchitry.acf”, which is their own constraint file that lets you assign pins based on their names on the Alchitry board.  Unfortunately, the only documentation for these names is the board schematic, but you can find the definitions for the Alchitry Io board in “(installation dir)/library/components/io.acf”.  Note that if pins are defined and not used, it will generate an error, so you’ll need comment out any unused pin names.  Note!  it’s very important to copy the contents of alchitry.acf and io.acf into a new .acf file if you edit them, then remove the originals.  This is because they link to files in the library that will be overwritten if you upgrade the IDE.  Starting with version 1.0.6 of the code, the io.acf file mysteriously changed the numbering of the dip and led pins from a 1D array to a 2D array, which can break some examples.  The easiest thing to do is to just change it back to 1D.

Once you’ve written your code, click the little “hammer” icon to compile it, and then the hollow “program” arrow to download it to the board.  The solid arrow will write the new file to the onboard flash memory, so it will be loaded at power-up.  For the record, I’ve found the Alchitry loader to be a lot more robust than the Xilinx Hardware Manager. I’ve used it with no problem using a Windows 10 VM on a Mac under both Parallels and VirtualBox, although there are some reports of problems with Linux running in a Mac VM.

XADC

The Artix-7 chip has DUAL 12-bit ADCs, referred to as “XADC”.  These are internally multiplexed to independently access one dedicated differential analog input, as well as 16 auxiliary differential inputs that can also be used for digital I/O.  In addition, it can internally monitor temperature, supply, and reference voltages, and optionally assert alarm signals if they go out of range.  Full documentation on the XADC can be found in this User Guide.  The XADC is very versatile, with lots of configuration options, and is therefore a bit daunting to use.  In general, all access to the XADC is through a set of registers described in Chapter 3 of the User Guide.  These are all accessed via the “Dynamic Reconfiguration Port” (DRP).  The XADC can be configured to scan over any set of the analog inputs, and the results are written to registers 0x00-0x19.

The HDL interface to the XADC is the XADC primitive (unisim.vcomponents.XADC for VHDL).  If you use this component directly, you’ll need to supply all the configuration information, either as an initialization or by dynamically loading the configuration registers.  It’s much easier to use the XADC Wizard tool in Vivado to select exactly the features you want, as described in this YouTube video.  After you’ve used the wizard to create the device, you can use it directly in a Vivado project, but if you want to use it with Alchitry (or a different Vivado project), then

  • Locate the files xadc_wiz_0.v and xadc_wiz_0.vhd in (project_directory)/(project_name).sources/sources_1/ip/xadc_wiz_0/.
  • Use “File->Import…” to add it to the project.

In the XADC_read_MUX example,  the wizard generated code to continuously scan over all the internal channels and the dedicated analog input and display one of the results in hex or decimal on the Io board display, based on the first four DIP switches.

Summary of Example Projects

These a couple of my projects in .zip files which unpack to an Alchitry project directory tree. In both cases, the details are in the au_top.v top comments (will open in Google Drive.  Click the download icon at the upper right to download .zip file).  Note that if you open them with the latest version of Alchitry Labs, you’ll get a message that the project was created with an older version of the IDE.  Just click “OK” to update it to the new version.

  • io-counter: Variable speed counter that will display on the Io board in HEX or DEC.
  • XADC_read_MUX: Continuously scan over all the internal channels and the dedicated analog input and display one of the results in HEX or DEC on the Io board display, based on the first four DIP switches.