Lichee-Tang-Tutorial

KO | EN

gitlite — search

#python #typescript #llm #golang #go #linux #nodejs #macos #java #cli #security #pytorch #ios #open-source

Lichee-Tang-Tutorial

(★ 25)

No description available.

Lichee-Tang-Tutorial Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## Lichee Tang: The cheapest beginner FPGA

Have you ever wanted to start learning FPGAs but just can't spare the $80-$150 for an official Xilinx/Altera board from places like Digilent? Let me introduce you to what is possibly the best beginner FPGA for learning RTL (Verilog/VHDL)!

![](https://raw.githubusercontent.com/jeremysee2/Lichee-Tang-Tutorial/master/images/tang_fpga.jpg)

The Lichee Tang Primer is a low-cost FPGA board made by Sipeed, using Anlogic's EG4S2BG256 FPGA. It's a great value for money, with 20,000 LUT4 logic elements and an onboard JTAG interface for uploading your bitstreams directly to the FPGA or SPI flash. In fact, it's vendor IDE is especially user-friendly, being able to synthesise bitstreams in a matter of seconds, instead of minutes like Quartus/Vivado from the major players.

So, what are the downsides? Firstly, it's just not well supported by the community or industry - meaning you'll need to learn those pesky Quartus/Vivado tools eventually if you go into industry. Secondly, you'll need to dig through documentation to use specific features (SERDES, ADC, PLL...) and vendor-provided IP.

However, for a beginner like me, we can wait to sort out those problems later... I just want to have a cheap and user-friendly platform to learn Verilog!

### Toolchain Setup

To set up the toolchain for this board, you can follow the official tutorial at the [Sipeed wiki](https://tang.sipeed.com/en/getting-started/). I'll briefly go through the setup steps:

1. Download the appropriate copy of [Tang Dynasty IDE from Sipeed](http://dl.sipeed.com/TANG/Primer/IDE)
2. Download the datasheet for the board and IDE from [here](https://github.com/kprasadvnsi/Anlogic_Doc_English)
3. For Linux, follow the setup guidelines [here](http://cgoxopx.sinriv.com/psg/2019-8-31:19:28:32) and run the `td -gui` command to open the IDE
4. For Windows, install using the executable and [set your system time](https://runasdate.en.softonic.com/) to be before 2018, to enable the provided Sipeed license. Then, you will be able to run the TD IDE with the ability to synthesise the bitstream
5. Install the USB drivers [here](https://tang.sipeed.com/en/getting-started/installing-usb-driver/)
6. Double-check that your setup is valid by [running the Blinky example](https://tang.sipeed.com/en/getting-started/getting-to-blinky/)

### Tutorial 1: FPGA Basics

As this series of tutorials were inspired by [Nandland](https://www.youtube.com/channel/UCsdA-aNqtMA1_2T15aXePWw), I highly recommend you check out his videos before moving to the next few ones that actually involve implementing your designs on a physical FPGA.

For this tutorial, we will follow along with the [first lecture](https://www.youtube.com/watch?v=l_eo21vHxw0&list=PLnAoag7Ew-vr1M98Q5K2kLHxFQ5l0DU3B&index=4) of Nandland. Here, we will be setting up our development environment and writing a simple Verilog module and testbench with `iverilog` and `gtkwave`.

Firstly, we'll want to install `iverilog` and `gtkwave`. `iverilog` is the Verilog compiler to perform simulations, and `gtkwave`allows you to view the resulting waveform.

#### Installing `iverilog` and `gtkwave`

For Windows, download the setup executable [here](http://bleyer.org/icarus/). Run the installer and check the "Add to PATH" option to automatically add it to PATH, allowing you to call it from the terminal. This executable also allows you to install `gtkwave` at the same time.

For Linux, you can install from premade packages [here](https://iverilog.fandom.com/wiki/Installation_Guide#Installation_From_Premade_Packages). Follow the instructions for your distro. For Ubuntu, add the Universe repository to your `/etc/apt/sources.list` and run the command `sudo apt-get install iverilog gtkwave`.

#### Setting up Visual Studio Code

I personally prefer using Visual Studio Code (VSC) as my text editor for this series, as it has some community extensions that provide linting of Verilog code. Follow [this](https://code.visualstudio.com/download) guide to install VSC, and install the extension `mshr-h.veriloghdl`.

After installing the extension, go to `File >> Preferences >> Settings` and search for Verilog.

![](https://raw.githubusercontent.com/jeremysee2/Lichee-Tang-Tutorial/master/images/vsc_verilog.PNG)

Look for `Verilog >> Linting >> iverilog` and check that box. Then, select `iverilog` as your linter of choice. This will run `iverilog` at your code location and dynamically provide code completion and check for syntax errors. However, this does not check for logical errors, which you will need to debug using simulation.

#### Module Structure

In Verilog, a module is defined with the keyword `module`. The following is an example of how a module is defined.

```verilog
module SwitchesToLEDs
    (input i_Switch_1,  
    input i_Switch_2,
    input i_Switch_3,
    input i_Switch_4,
    output o_LED_1,
    output o_LED_2,
    output o_LED_3,
    output o_LED_4);
        
assign o_LED_1 = i_Switch_1;
assign o_LED_2 = i_Switch_2;
assign o_LED_3 = i_Switch_3;
assign o_LED_4 = i_Switch_4;
    
endmodule
```

A module always starts with the keyword `module` followed by the name of the module. Following that, the `input` and `output` wires/registers to the module are defined. It's good practice to label your variables appropriately, such as `i` for inputs and `o` for outputs. Remember to put the keyword `endmodule` at the end of your file.

Variables can have two main types in synthesizable Verilog: `wire` or `reg` for outputs and `wire` only for inputs. `wire` describes a physical connection between two ports, where any change in the driven state is propagated to the other side of the connection and is only compatible with combinational logic. `reg` is for driver states, where you can change the value of the variable using sequential logic as well.

The keyword `assign` can only be used with `wire` type variables, thereby driving the signal continuously. These will always be active, not just at the clock edge.

This example from Nandland illustrates how you can take several button inputs and directly connect them to LED outputs.

#### Logic Gates

Now that we've taken a look at this basic example, let's try to modify it with some logic gates.

```verilog
// Logic gate examples
module SwitchesToLEDs
    (input i_Switch_1,  
    input i_Switch_2,
    output o_LED_1,
    output o_LED_2,
    output o_LED_3,
    output o_LED_4);
        
assign o_LED_1 = i_Switch_1 & i_Switch_2;     // AND  gate
assign o_LED_2 = i_Switch_1 | i_Switch_2;     // OR   gate
assign o_LED_3 = ~(i_Switch_1 & i_Switch_2);  // NAND gate
assign o_LED_4 = i_Switch_1 ^  i_Switch_2;    // XOR  gate
    
endmodule
```

In this example, we use the bitwise operators `&`, `|`, `~` and `^` for AND, OR, NOT and XOR. It is also possible to use full logical operators such as `&&`, `||` and `!` for AND, OR and NOT.  A deep dive into operators is available [here](http://web.engr.oregonstate.edu/\~traylor/ece474/beamer_lectures/verilog_operators.pdf).

#### Creating a Testbench for Simulation

Now, let's save our file as `SwitchesToLEDs.v`. Create a new file for our testbench called `SwitchesToLEDs_tb.v`. At the start of the file, we will define the timescale for which the simulation is done over, which is the duration of one clock pulse.

```verilog
`timescale 1ns/1ns
```

Following that, we will need to include the source Verilog file of our module.

```verilog
`include "SwitchesToLEDs.v"
```

Then, we will create our testbench module. Testbenches don't contain inputs or outputs, hence there are no brackets containing them.