Litex for Tang Nano 20K

Prerequisities

ArchLinux

pacman -Sy
pacman -S python-pip sbt jdk-openjdk riscv64-elf-gcc meson verilator

Prepare Litex

git clone [email protected]:litex-hub/linux-on-litex-vexriscv.git
cd linux-on-litex-vexriscv

wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
chmod +x litex_setup.py

## Remove the following file to fix `litex_setup.py` with ArchLinux (1)
sudo mv -v '/usr/lib/python3.13/EXTERNALLY-MANAGED' /tmp/

## Provide your linux account name to run `litex_setup.py` with
./litex_setup.py --init --install --user <YourLinuxAccount> --config=full

## Update your shell' PATH (also in your `.profile`)
PATH=$PATH:$HOME/.local/bin

## Run the help and make sure `sipeed_tang_nano_20k` board is listed
./make.py --help

(1)

Build

./make.py --board sipeed_tang_nano_20k --cpu-count 2

Gowin for ArchLinux

Gowin IDE

1. Register or Login at Gowin
2. In Support download latest Education version for Linux: Gowin V1.9.11.03 Education (Linux x64)
3. Untar the archive in /opt/gowin for two sub-directories IDE and Programmer

mkdir /opt/gowin
cd /opt/gowin
tar -zxvf Gowin\_V1.9.11.03\_Education\_Linux.tar.gz

4. Set the root user to the whole directory

chown -R root:root /opt/gowin

5. Make sure of the prerequisite packages:

pacman -S fontconfig freetype2 qt5-base

6. IDE is failing to start with a library issue. Remove it:

rm -i /opt/gowin/IDE/lib/libfreetype.so.6

7. Create a shell script to start the IDE with those environment variables.
   For example: gowin.sh

nano ${HOME}/bin/gowin.sh

QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt/plugins QT_QPA_PLATFORM=xcb QT_XCB_GL_INTEGRATION=none gw_ide "$@"

8. Update your PATH, preferably in your session .profile

PATH=$PATH:$HOME/bin:/opt/gowin/IDE/bin

9. Add a desktop shortcut.
   For example ${HOME}/.local/share/applications/gowin-ide.desktop

[Desktop Entry]
Type=Application
Version=1.0
Name=Gowin FPGA Designer
Comment=Gowin IDE: FPGA Designer
Exec=gowin.sh %U
Path=/opt/gowin/IDE/
Categories=Development;

10. I'm using XFCE and I now have a Gowin FPGA Designer icon in the Development menu to start the Gowin IDE

Gowin Programmer

1- Update the udev rules to let Programmer query the USB cable

cp -v /opt/gowin/Programmer/Driver/50-programmer_usb.rules /etc/udev/rules.d/

2- In your session .profile add the Programmer path

PATH=$PATH:$HOME/bin:/opt/gowin/IDE/bin:/opt/gowin/Programmer/bin

3- Reboot the system to apply all those changes

4- Start the Gowin IDE and go to menu Tools > Programmer

5. The cable should be detected with the following settings:
   ( if not go to Programmer menu Edit > Cable Setting > USB Cable Setting )

• Cable [ USB Debugger A ]
• Port [ USB Debugger A/0/4129/null ]
• Frequency [ 2.5MHz ]
• [x] using ftd2xx driver

6- Go to Programmer menu Edit > Configure Device and Save these settings:

• Access Mode [ External Flash Mode ]
• Operation [ exFlash Erase,Program thru GAO-Bridge ]
• File name [ YourBitStream.fs ]
• Device [ Generic Flash ]
• Start Address [ 0x000000 ]

7- Now program the FPGA from menu Program/Configure

Litex

• Based on TangNano-20K-example

Build

• Go to the Litex directory

cd linux-on-litex-vexriscv

QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt/plugins QT_QPA_PLATFORM=xcb QT_XCB_GL_INTEGRATION=none \
python -m litex_boards.targets.sipeed_tang_nano_20k --build

Program

openFPGALoader -b tangnano20k -f build/sipeed_tang_nano_20k/gateware/sipeed_tang_nano_20k.fs 

empty
write to flash
Jtag frequency : requested 6.00MHz   -> real 6.00MHz  
Parse file Parse build/sipeed_tang_nano_20k/gateware/sipeed_tang_nano_20k.fs: 
Done
DONE
after program flash: displayReadReg 00006020
	Memory Erase
	Done Final
	Security Final
Erase SRAM DONE
Jtag probe limited to %d MHz6000000
Jtag frequency : requested 10.00MHz  -> real 6.00MHz  
JEDEC ID: 0xef4017
Detected: Winbond W25Q64 128 sectors size: 64Mb
JEDEC ID: 0xef4017
Detected: Winbond W25Q64 128 sectors size: 64Mb
RDSR : 0x00
WIP  : 0
WEL  : 0
BP   : 0
TB   : 0
SRWD : 0
00000000 00000000 00000000 00
start addr: 00000000, end_addr: 000e0000
Erasing: [==================================================] 100.00%
Done
Writing: [==================================================] 100.00%
Done

Run

Gowin Analyzer Oscilloscope

TangNano-20K-example

• Clone the examples from the repository

git clone [email protected]:sipeed/TangNano-20K-example.git

FPGA Designer

• Start the Gowin FPGA Designer and load the project TangNano-20K-example/led/blink_led/blink_led.gprj

Analyzer Oscilloscope

• Create a GAO Config File from menu File > New > GAO Config File
• Choose the default Setting:
  • [o] For RTL Design
  • [o] Standard
• Keep the suggested GAO Name as blink_led
  • and the sub-directory to TangNano-20K-example/led/blink_led/src
  • button [Next >] will add src/blink_led.rao to the current project

Signals

• Back to the Design tree, double click the GAO file blink_led.rao

Trigger

• From the Trigger Options tab
• Double click Trigger Port 0
• Click (+) to add a signal
  • Click [Search] button to popup the Nets window
  • Select count_1s[23:0] and add it to the right panel with button [>]
  • Validate with [OK]
  • You will get count_1s[23:0] assigned to the Port 0
• In the middle column Match Units, double click the M0
  • You are in the Match Unit 0 where you select Trigger Port 0 from the drop-down box
  • With count_1s[23:0] selected, enter the decimal value 13500000
  • This matches condition in the Verilog code blink_led.v where ( count_1s < 27000000/2 )
  • Validate with [OK]
  • The match unit [x] M0 should be ticked
• In the right column, add an expression
  • In the empty panel, right-click mouse button to choose menu [Add]
  • In the Expression calculator, click button M0
  • Validate with [OK]
  • Expression M0 should be listed

Capture

• Choose the Capture Options tab
• Click the 3-dots buttons to assign a sample clock
• In the Nets popup window click [Search] to populate the left panel with signals
• Select clk and add it to the right panel with [>] button
• In the Capture Signals panel add two signals
  • [Search] for count_1s[23:0] and count_1s_flag
  • Click [>] to add both to the Capture Signals panel

Build

• The GAO is all set up, save it from menu File > "Save blink_led.rao"
• Back to the Process tree of the FPGA Designer, select Place & Route
• Right-click mouse button to choose Clean&Rerun All
• Accept to remove the previous results

Oscilloscope

• Plug the TN20K to the PC from its USB-C cable
• If ftdi_sio module present then unload it with sudo modprobe -r ftdi_sio
• Choose menu Tools > Gowin Analyzer Oscilloscope
• You should see all settings made so far:
  • exp0: M0 trigger expression
  • M0 match unit condition

Program fs

• Tick option [o] Enable Programmer
• Select the row which targets the GW2AR-18 device
• Click button to program the TN20k
• Once FPGA programmed, it will auto reset with the blink_led bitstream
  ...

Acquisition

• In green is displayed in the top bar [Ready to acquire]
• Click Play to start the acquisition: the ( > ) round blue button
• This will popup Oscilloscope window and the recorded signals