TUTORIAL: How to use VHDL with the Alhambra II FPGA

The Alhambra II FPGA is a very compact and powerful FPGA designed in Spain. It is completely programmable using Verilog / SystemVerilog with open source and libre toolchains. However, there is little information about programming it using VHDL. Let me tell you, it is utterly possible, and there is manufacturer support for it. You won’t use open source tools though, but VHDL is still very powerful in the industry, and you might want to use it with your new and shiny Alhambra board. Let’s see how to use VHDL with the Alhambra II FPGA.

Setting up the VHDL toolchain

The Alhambra II board uses a Lattice iCE40HX FPGA, manufactured by Lattice Semiconductor. It was originally only programmable with their own software, but the whole toolchain got reverse-engineered, which has made a lot of open source boards and designs appear using the ice40 family of FPGAs. Only the official toolchains support VHDL Synthesis.

Installing Lattice iCEcube2 FPGA tools on Ubuntu - Pascal Cotret @ ENSTA Bretagne — iCEcube2 is the official synthesis tool for these FPGA chips

To donwload the software (it is available for both Linux and Windows) you should visit this page. You will need to request a free licence for the tool, as it is only free for individuals and is not developed directly by Lattice. Head up to the Software Downloads & Documentation section and start downloading the latest release (2020 build at the time of writing). While you’re at it, request your license here. You will need the following:

Lattice website user account
Physical MAC address (12-digit hexadecimal value) (you can get this using ipconfig on Windows, or ifconfig on Linux)

Once you are done, install the software, during the installation you will need to choose the licence file you should have received in your email.

VHDL Synthesis

Here’s some sample VHDL code to test the toolchain is working:

-- VHDL Code for AND gate

-- Header file declaration

library IEEE;
use IEEE.std_logic_1164.all;

-- Entity declaration

entity andGate is

    port(A : in std_logic;      -- AND gate input
         B : in std_logic;      -- AND gate input
         Y : out std_logic);    -- AND gate output

	Z : out std_logic;      --test led output
	X : out std_logic;      --test led output
         

end andGate;

-- Architecture definition
architecture andLogic of andGate is

 begin
    
    Y <= A AND B; -- and gate
    Z <= '1';     -- wired '1', the LED will always be on
    X <= B;       -- wired directly to the B button

end andLogic;

Create a new project browsing to “File” > “New Project” and choosing these parameters:

These are the FPGA and package that the Alhambra II uses

Copy this code into a .vhdl or .vhd file in your filesystem. Afterwards, you need to import it into the “Design Files” section of the iCEcube2 tool:

Add VHDL files into your project by right-clicking on “Design Files” after creating a project

That’s pretty much it. Now, we need to assign some actual pins (the physical inputs and outputs of your board) into the input and output ports of our design. The code above is a simple AND gate, plus some extra logic to test the LED array on the FPGA’s board.

How Logic Gates Work - Homemade Circuit Projects

We are going to assign the A signal to one button on our board, B to the other push button, and Y to a LED light. To do so, click on the “Pin constrains” editor:

This window should open:

Here, you can assign the signals in your design to actual pins, by specifying the “pin location” or pin number. To know what is the pin number for a given peripheral or FPGA pin, you can use this great pinout diagram provided by Eladio from Alhambra Bits:

As you can see, I use input pins 33 and 34 which are the “User Switches”, and connect them to A and B. Y is mapped to pin 39 which is the LED5. The other two signals X,Z are mapped to other two leds. The complete and official pinout made by Lattice can also be found here, and you should download it for reference:

The great thing about iCEcube2 is that it comes with all the pinout mappings for all the Lattice board, unlike Xilinx’s or Altera’s software where you had to provide a file with the pin constrains for your specific FPGA.

Synthesis, placing and routing

This is very easy, trust me. If your code is correct, all you need to do is click on the “Play” button to run synthesis. Once synthesis is run, you’ll be able to run the next step (importing constrains), then the next (placing), then routing, and finally, generate bitmap, which creates the final file you can flash into your FPGA.

Run Synplify Pro Synthesis is the first step. It will warn you if there are any errors in your code.

This is how it should look at the end:

Programming the board

We need a different software to flash the board with the bitmap file we just generated. We’ll use the privative “Diamond Programmer” again by Lattice to upload the design to our board. Download it here. Once you’ve got it, plug your board with an usb cable and open the program:

Choose “Create a new project from a JTAG scan”

The tool will scan for your board automatically if you select the first Action in the list. A new window will open and you’ll probably get this error:

It’s fine, we’ll just manually specify our board details

We just need to feed the programmer the details for our board. To do so, change the “Device Family” from Generic JTAG Device to ice40:

Also, changer your Device, to the ice40HX4K, which is the model on the Alhambra II:

We are getting closer. Finally, click on Operation, and fill the following details:

Access Mode: SPI Flash Programming
Micron N25Q032A as the SPI memory model
Package: 8-pin VDFPN8

Last but not least, select the bitmap file we generated with iCEcube2:

Now click the “Program” icon:

If everything was successful your log should look like this:

If you get errors, double-check your USB cable and connections. Make sure you have a data cable, and that you have set up the SPI flash memory model properly.

Success! Pressing both buttons makes the logic and be 1 & 1, and the result is a ‘1’ that goes to the LED

Any questions? Let me know in the comments and don’t forget to check all the other articles!