Tang Nano 20K - hoglet67/BeebFpga GitHub Wiki
- Add notes on the TangNano20K doc (describe each connector and each jumper block and power warnings)
- Add notes about using ADFS 1.57 with the 2GB Disk Image
- Introduction
- Summary of the Beeb FPGA
- Summary of the Tang Nano 20K
- Connecting up the Tang Nano 20K
- Installing the Gowin EDA Software
- Building Beeb FPGA from the source files in github
- Programming the Tang Nano 20K
- Using Beeb FPGA
This wiki page contains a few notes to help you get up and running with Beeb FPGA on the Tang Nano 20K.
I minimal setup comprises just the Tang Nano 20K and a PS/2 Keyboard.
A more comprehensive setup might use the TangNano20K Dock PCB:
Beeb FPGA on the Tang Nano 20K provides:
- a BBC Model B configuration
- a BBC Master configuration
These share a common feature set:
- High quality HDMI/DVI output @ 50Hz
- PSG (76489) audio (mono)
- SID audio (mono)
- Music 5000 audio with/without a low pass filter (stereo)
- High quality audio mixer/resampler based on a 3840 tap polyphase filter:
- Three input sources: PSG, SID and Music 5000
- Digital volume control
- HDMI audio output
- S/PDIF audio output
- I2S on-board audio output (that directly connects to an 8 ohm speaker)
- Analogue audio output using an internal 1-bit DAC
- Analogue audio output using an external 24-bit CS4354 DAC
- PS/2 Keyboard
- PS/2 Mouse
- Dual Atari joystick support
- Internal 4MHz 65C02 Co Processor (for Tube Elite!)
- External PiTubeDirect Co Processor
- VideoNuLA (an extended colour palette, and additional screen modes)
- SD Card File System supported by MMFS and MMFS2 file systems
- Integrated ICE 65C02 debugger
- Software control of the 6 onboard LEDs via ?&FC50
- Software control of the RGB LED via ?&FC51/2/3
- Software control of the digital volume control via ?&FC54
- Various configuration options (via the PS/2 keyboard) and jumpers for power-on defaults
Beeb FPGA for the Tang Nano 20K is still in development. The latest code can be found in github on the dev branch.
There isn't yet an official release, so you'll need to build it from source using the Gowin EDA IDA. This is covered later on and is very straightforward.
This section provides a brief summary of the Tang Nano 20K FPGA board. This is a low cost (about £30 delivered) FPGA board manufactured by Sipeed that uses a Gowin FPGA.
The Gowin GW2AR-LV18QN88C8/I7 FPGA has the following features:
- 20K LUTs (about 2x that of the Spartan-6 LX9)
- 92KB usable block RAM (about 1.5x that of the LX9)
- 48 18x18 multipliers (about 3x that of the LX9)
- two PLLs (LX9 has four)
- 8MB SDR SDRAM (2Mx32) that can run with a random access cycle time of ~125ns
The SiPEED Tang Nano 20K board has the following features:
- 8MB QSPI flash
- 34 general purpose I/O pins (on a 40-pin DIP header, some shared with the below peripherals)
- 27 MHz Oscillator
- MS5351 Programmable Clock Generator with additional three clock outputs feeding the FPGA
- HDMI connector (full size) [ shares 2 GPIOs for EDID ]
- LCD connector (MIPI DPI) [ shares 12 GPIOs ]
- Micro SD Card slot [ shares 2 GPIOs ]
- 6x LEDs [ shares 6 GPIOs]
- 1x RGB LED [shares 1 GPIO ]
- 3x Push buttons
- 1x MAX98357A I2S DAC + Class D Amplifier (separate speaker out pads)
- BL616 micro-controller (running closed-source) firmware providing:
- JTAG programming of FPGA
- FTDI USB UART emulation
- an additional SPI channel between FPGA and BL616 [ uses 4 GPIOs ]
The USB-C port on the Tang Nano 20K serves three purpose:
- a power input (5V @ 500mA max)
- access to the integrated programmer (/dev/USB0 on Linux)
- access to the TangNano20K console and the Beeb FPGA ICE-65C02 Debugger (/dev/USB1 on Linux)
A minimal setup for Beeb FPGA on the Tang Nano 20K needs the following:
- a HDMI (or DVI) monitor, connected to the HDMI connector. This needs to support a refresh rate of 50Hz.
- a SD Card, plugged into the Micro SD Card. This needs to be formatted with FAT32 and contain a BEEB.MMB file. You can find a sample file [here](https://github.com/hoglet67/Beeb FPGA/releases/download/specnext_beta1/BEEB.MMB.zip). Unzip the file onto a freshly formatted card.
- a PS/2 keyboard.
IMPORTANT: The Tang Nano 20K is a 3.3V device and is NOT 5V tolerant (i.e. voltages above 3.3V may damage the inputs). PS/2 keyboards are designed to be powered from 5V. The PS/2 clock and data lines are "open collector" with the keyboard including resistors (~10KB) that pull these up to VCC. To safely connect a PS/2 keyboard you need to do one of the following:
- Power the keyboard from VCC=3.3V and hope that it works reliably (many do, some don't, but no damage will occur).
- Power the keyboard from VCC=5V and clamp the clock and data lines to 3.3V using 3.3V zener diodes (to 0V).
- Power the keyboard from VCC=5V and reduce clock and data voltages to 3.3V using 10K resistors (to 0V).
- Power the keyboard from VCC=5V and use a cheap level shifter between it and the Tang Nano 20K.
External connections on the DIP header:
- PS/2 Keyboard (Clock: pin 73; Data: pin 74)
- PS/2 Mouse (Clock: pin 85; Data: pin 80)
- S/PDIF digital audio (pin 86) [ needs a few passive components for signal conditioning ]
- Analog audio output (Left: pin 42; Right pin 41 [ needs a few passive components for signal conditioning ]
For additional connections, see the PDF schematic for the TangNano20KDock PCB: https://github.com/hoglet67/TangNano20KDock/blob/master/v1/tangnano20k_dock.pdf
You need to download and install the latest version of the "Gowin EDA" IDE which is used for developing and programming the Gowin family of FPGAs. This can be found on the Gowin website.
In order to access the download page, you first need to register here: https://www.gowinsemi.com/en/member/
(registration is quick)
Once registered, you should be able to login and download the latest version of Gowin EDA: https://www.gowinsemi.com/en/support/download_eda
Gowin EDA supports the Windows, Linux and MacOS operating systems.
There are two different versions available:
- the Education Edition (V1.9.10.03 at the time of writing). This needs no license.
- the Full Edition (V1.9.11 at the time of writing). This needs a (free) license that can take a couple of days to arrive.
Either version will build Beeb FPGA.
On Linux the download is a tar file (currently Gowin_V1.9.11_linux.tar.gz) and can be unpacked anywhere you like.
Here's a crib for Linux:
mkdir -p ~/gowin/v1.9.11
cd ~/gowin/v1.9.11
wget https://cdn.gowinsemi.com.cn/Gowin_V1.9.11_linux.tar.gz
tar xf Gowin_V1.9.11_linux.tar.gz
This URL actually seems to bypass the requirement to register but it's polite to do so anyway.
First, make sure you have git installed:
sudo apt-get install git
Then clone the dev-tang-debugger branch of the Beeb FPGA github repository:
git clone -b dev-tang-debugger https://github.com/hoglet67/BeebFpga.git
Start Gowin EDA:
export PATH=~/gowin/v1.9.11/IDE/bin:$PATH
gw_ide
Select "Open Project" from the Quick Start panel and navigate to one of the four Beeb FPGA gowin projects:
- The "NoDebugger VGA" project is at
~/BeebFpga/src/gowin/tang20k/tang20k_nodebugger_vga/tang20k.gprj - The "NoDebugger PiTube" project is at
~/BeebFpga/src/gowin/tang20k/tang20k_nodebugger_pitube/tang20k.gprj - The "Debugger VGA" project is at
~/BeebFpga/src/gowin/tang20k/tang20k_debugger_vga/tang20k.gprj - The "Debugger PiTube" project is at
~/BeebFpga/src/gowin/tang20k/tang20k_debugger_pitube/tang20k.gprj
The "Debugger" projects includes the ICE-65C02 Debugger. This allows 6502 machine code to be debugged through a simple command-line interface (through the serial USB connection). The only disadvantage is an increase in build time.
The "VGA" projects support an external 50Hz VGA interface, using on-board high speed 1-bit DACs to get 4-bit R/G/B (with some external signal conditioning components).
The "PiTube" projects support an external PiTubeDirect Co Processor (this also repurposes the signals to the onboard LEDs).
Once the project is open:
- select the Process tab (so you can easily monitor the build progress)
- click on the
icon in the tool bar to start a build - building may take a few minutes, so go and make a cup of tea!
- a few WARNINGs are normal, but there should be no ERRORs
If the build is successful then you can continue on to the programming step.
There are three parts to programming Beeb FPGA onto the Tang Nano 20K:
- Programming the MS5351 Clock Generator (to configure 27MHz and 24.576MHz clocks)
- Programming the ROM Image (into external FLASH)
- Programming the FPGA Bitstream (into either FPGA SRAM or external FLASH)
Beeb FPGA currently gets its clock(s) from the external MS5351 clock generator:
- the CLK0 output should to be set to 27MHz; this is required.
- the CLK1 output should to be set to 24.576MHz; this is used for the on board I2S, external I2S and external S/PDIF digital audio.
- the CLK2 output is not currently used.
It's important that CLK0 and CLK1 are configured following the procedure below, otherwise you might get occasional glitches on the digital audio outputs (for reasons explained later on).
You'll need a serial terminal program for this step.
The expected baud rate is 115,200 baud.
Connect up the Tang Nano 20K with the USB-C cable and start your terminal program.
On Linux the following command should work:
gtkterm -p /dev/ttyUSB1 -s 115200
In the Terminal type ^X ^C (Control-X Control-C) and you should see the TangNano20K> prompt.
Enter the following commands:
TangNano20K />pll P0:35,1217,3125 D0@P0:32,96,125 D1@P0:36,0,1 O0@D0 O1@D1
TangNano20K />pll_clk -s
This configures the MS5351 as follows:
25.000MHz x (35 + 1217 / 3125) = 884.736MHz (intenal PLL)
884.736MHz / (32 + 96 / 125) = 27.000MHz (CLK0 output)
884.736MHz / (36 + 0 / 1) = 24.576MHz (CLK1 output)
So why are we not using the more well known pll_clk command?
TangNano20K />pll_clk O0=27M O1=24576K -s
Using pll_clk will appear to work, but the parameters selected by the SiPEED BL616 firmware result in clocks that will drift over time.
In more detail, the ratio between the 27MHz and 24.576MHz should be exactly 1125/1024 so clocks will remain phase locked.
Unfortunately, the parameters that pll_clk chooses are:
- CLK0 (27MHz): 29,660213,1048575
- CLK1 (24.576MHz): 32,578900,1048575
The ratio here is (32 + 578900/1048575) / (29 + 660213/1048575) which works out to 1125.0000063488 / 1024. That's an error of 5.6 parts per billion, which may not seem much. On a scope, one clock will be sliding past the other at ~6ns per second. At this rate, a 48KHz audio sample (20.833us) will be dropped every 3720 seconds (62 minutes). Or worse, several samples will be corrupted causing an audible click.
On startup, Beeb FPGA loads a set of standard ROMs from external FLASH. So this needs to be programmed with an appropriate set of BBC ROMs. A standard set of ROMs (for both the Model B and Master) are included in ~/BeebFpga/roms directory, together with a build script that concatenates them together. The result is a single 512KB file that contains (up to) sixteen 16KB ROMs for the Model B and another sixteen for the Master. There's are plenty of slots free if you want to add ROMs of your own.
To build the ROM image run the following commands:
cd ~/BeebFpga/roms/
./make_rom_image_tangnano.sh
The output should look like:
-rw-rw-r-- 1 dmb dmb 524288 Feb 17 19:04 tmp/tang_image_combined_MMFS.bin
On a TANG Nano 9K program to external FLASH address 0x000000
On a TANG Nano 20K program to external FLASH address 0x500000
-rw-rw-r-- 1 dmb dmb 524288 Feb 17 19:04 tmp/tang_image_combined_MMFS2.bin
On a TANG Nano 9K program to external FLASH address 0x000000
On a TANG Nano 20K program to external FLASH address 0x500000
The images can be found in the ~/BeebFpga/roms/tmp directory.
Two different images have been built. They differ only in whether they include the MMFS or the MMFS2 file system. If you are unfamiliar with the BBC family of machines, it's probably best to go with MMFS for now.
The chosen image needs to be programmed to address 0x500000 in the serial FLASH chip on the Tang Nano 20K.
There are two ways to do this:
- Using the Programmer part of Gowin EDA
- Using the Programmer_cli command line tool
Connect the Tang Nano 20K to your machine with the provided USB-C cable.
At this point, nothing else needs to be connected, but you might as well also connect a HDMI cable.
In Gowin EDA, launch the Programmer by clicking the Programmer icon:
You should immediately see Cable Setting dialog box:
If the Gowin USB cable has been detected, click save to acknowledge this. If not, then try the Query/Detect cable option. If this fails then you likely have a driver problem. Consult the Gowin documentation for instructions on installing the cable drivers.
Once the Tang Nano 20K board is detected, you should see a "device" line that starts with GW2AR. Click on the device line to select it:
Then go to Edit/Configure Device and change the fields as follows:
Click Save then click the Program button on the tool bar:
You should get a Progress bar and the following log messages in the output window:
Info: Target Cable: Gowin USB Cable(WINUSB)/0/820/[email protected]
Info: Target Device: GW2AR-18C(0x0000081B)
Info: Operation "exFlash C Bin Erase,Program,Verify thru GAO-Bridge" for device#1...
Info: Loading GAO-Bridge...
Info: Gao-Bridge User Code is: 0x0000B8DF
Info: Status Code is: 0x00006020
Info: Try to program spi-flash: 0xEF4017!
Info: Erasing 128 sectors from address 0x500000 to 0x580000...
Info: Program and Verify flash successfully.
Info: Finished.
Info: Cost 21.12 second(s)
An alternative method of programming is to use the programmer_cli command line tool directly:
PROG=~/gowin/v1.9.11/Programmer/bin/programmer_cli
$PROG --cable-index 5 --device GW2AR-18 --run 39 --spiaddr 0x500000 --mcuFile ~/BeebFpga/roms/tmp/tang_image_combined_MMFS.bin
Note 1: Depending on your operating system, you might need to change the cable-index value, or you might not need it at all:
--cable-index <int> Select a number for USB cable:
0: Gowin USB Cable(GWU2X);
1: Gowin USB Cable(FT2CH);
2: Parallel Port(LPT);
3: Digilent USB Device;
4: USB Debugger A;
5: Gowin USB Cable(WINUSB);
Both 5 and 1 work (for me) on Linux.
Note 2: programmer_cli doesn't seem to like being invoked from the PATH variable, as the session below shows:
$ export PATH=~/gowin/v1.9.11/Programmer/bin:$PATH
$ programmer_cli --cable-index 5 --device GW2AR-18 --run 39 --spiaddr 0x500000 --mcuFile ~/atom/BeebFpga/roms/tmp/tang_image_combined_MMFS.bin
Target Cable: Gowin USB Cable(WINUSB)/0/None/[email protected]
Target Device: GW2AR-18(0x0000081B)
Operation "exFlash C Bin Erase,Program,Verify thru GAO-Bridge" for device#1...
Preparing data...: [#########################] 100%
Loading GAO-Bridge...
Error: Error found!
$ ls -lt | head -2
total 2060348
-rw-rw-r-- 1 dmb dmb 133 Feb 18 16:28 2025-02-18.log
$ cat 2025-02-18.log
2025-02-18 16:28:54,420 - ERROR :
268@bitstream: contents--[Errno 2] No such file or directory: 'data/spi/gao_bridges/0000081B.fs'
For some reason, when invoked like this the tool is unable to find the data directory.
The FPGA bitstream can be programmed into either:
- SRAM, which is quick but non-persistent
- External FLASH, which is slower but survives power cycles
It's recommended you start with the SRAM option as this leaves the default Tang Nano 20K "Litex" program intact. Once your are happy with Beeb FPGA, then you can program it into FLASH if you prefer.
If you still have the programmer open, close and re-open it to get the default device configuration:
To program into SRAM, just click the Program button on the tool bar:
To program into FLASH, you first need to edit the device configuration (as described above) to:
To program into SRAM:
PROG=~/gowin/v1.9.11/Programmer/bin/programmer_cli
$PROG --run 2 --cable-index 5 --device GW2AR-18 --fsFile ~/BeebFpga/src/gowin/tang20k/tang20k_nodebugger/impl/pnr/tang20k.fs
To program into FLASH:
PROG=~/gowin/v1.9.11/Programmer/bin/programmer_cli
$PROG --run 37 --cable-index 5 --device GW2AR-18 --fsFile ~/atom/BeebFpga/src/gowin/tang20k/tang20k_nodebugger/impl/pnr/tang20k.fs
If the programming is successful you should see the familiar BBC Computer 32K screen on the HDMI monitor. If you have a DVI monitor and get no picture, see below for how to select DVI mode.
Several configuration options can be accessed from the PS/2 keyboard by pressing the "config modifier" key in conjunction with one of F1..F10. There are several ways to invoke the config modifier:
- Ctrl-Left Alt
- Right Alt
- The S2 button on the Nano
- The boot button on the Nano
The available configuration options are
- Config-F1 = Volume down (clamped at MinVolume = 0)
- Config-F2 = Volume up (clamped at MaxVolume = 20)
- Config-F3 = Volume default (10)
- Config-F4 = M5K Filter (On/Off)
- Config-F5 = Audio Source (Mixer/Legacy)
- Config-F6 = HDMI Aspect Ratio (Auto/DVI/16:9/4:3) [**]
- Config-F7 = Co Pro (Off/Int/Ext) [**]
- Config-F8 = Machine (Beeb/Master) [**]
- Config-F9 = Reserved for serial
- Config-F10 = Spare
The volume control is part of the resampler and has a log-volume range of 21 steps (0..20), with a default of fairly quiet (10).
The defaults for options marked [**] can be set with the external config jumpers.
The BREAK key is mapped to F12.
On the TangNano20K Dock board there are six external config jumpers that allow the default configuration to be set:
Config-0 - Machine Type: Off=Beeb On=Master
Config-1 - Co Pro Config: Off=NOTUBE On=TUBE
Config-2 - Co Pro Config: Off=INTUBE Off=EXTUBE
Config-3/4 - HDMI Config: Off/Off=HDMI Auto; Off/On=HDMI 4:3; On/Off=AR 16:9; On/On=DVI Mode
Config-5 - Spare (might get used for default volume)
If you have a DVI monitor that doesn't support HDMI, then you will get a blank screen unless you fit jumpers at Config-3 and Config-4. If the Dock is not used, these jumpers will all appear to be in the off state, so to invoke DVI mode press Config=F6 once.
Pressing button S1 will perform a power up reset (and force the configuration jumpers to be re-read).
Pressing button S2 will act as a config modifier (in conjunction with F1..F10).
The Tang Nano 20K has six LEDs.
LED1 is closest to the USB socket (at front of the dock)
In the VGA builds, these default to the following indications:
- LED 6 - Beeb Caps Lock
- LED 5 - Beeb Shift Lock
- LED 4 - Music 5000 Filter(on=Filter On, off=Filter Off)
- LED 3 - Audio clipping
- LED 2 - Audio source (on=resampler, off=legacy)
- LED 1 - Video mode (on=HDMI mode, off=DVI mode)
In the PiTube builds, the LEDs pins are re-purposed to form part of the Tube interface:
- LED 6 - nRST
- LED 5 - A2
- LED 4 - A1
- LED 3 - nTube
- LED 2 - RnW
- LED 1 - A0
Note: the Clipping LED was chosen to alias with nTUBE as it's normally off (high). This ensures if VGA build is ever incorrectly loaded onto a PiTube jumpered hardware, the likelihood of a data bus conflict (between the Pi and the VGA data) is reduced.
In the VGA builds, the 6 onboard LEDs can be controlled by writing to location &FC50 in the host address space. Values between &80 and &BF will activate the LEDs, with bits 5..0 of the value setting the controlling the individual LEDs.
The RGB LED can be controlled by reading/writing the following locations:
- &FC51 (Red)
- &FC52 (Green)
- &FC53 (Blue) The range is 0 to 255 but values above 63 are seriously bright. You have been warned. If you do try 255, please be careful not to look directly at the LED.
The resampler volume can be read/written through location &FC54.
If you're running a BBC or Master with second processor enabled, note that your Basic program doesn't have easy access to the host address space.
The Debugger version of the Beeb FPGA includes the ICE-65C02 debugger.
To use this, start a terminal program and connect to the USB serial port.
For example, on Linux:
gtkterm -p /dev/ttyUSB1 -s 115200
When the core boots (or when pressing button S1) you should see a banner like:
ICE-65C02 In-Circuit Emulator version 0.998
Compiled at 10:22:33 on Feb 8 2022
8 watches/breakpoints implemented
Tracing every 1 instructions while single stepping
CPU free running...
Hitting return in the terminal emulator should get you a command prompt:
>>
You can then type help:
>> help
Further documentation can be found here:
https://github.com/hoglet67/AtomBusMon/wiki
In particular, there is a command reference here:
https://github.com/hoglet67/AtomBusMon/wiki/User-Manual---Command-Reference
MMFS is a modern SD Card File System, widely used in the Acorn community, and is included as standard in Beeb FPGA. MMFS uses a FAT16/32 formatted SD Card containing a single file called BEEB.MMB. This file is normally ~100MB, and is a concatenation of 511 raw 200KB 80-track disc images.
There are two limitations with MMFS's use of the SD Card:
- BEEB.MMB must be one of the first 16 files in the root directory
- BEEB.MMB must be contiguous (i.e. it cannot be fragmented)
Here is a link to a standard BEEB.MMB file: https://github.com/hoglet67/BeebFpga/releases/download/specnext_beta1/BEEB.MMB.zip
It contains the following
- Disk 0: Stairway to Hell Archive MENU
- Disk 1: Beeb FPGA Support Disk
- Disk 2: MMFS 1.44 ROM images
- Disk 3: Klaus Dormann 6502 Test Suite
- Disk 4: Bruce Clark BCD Test Suite
- Disks 20-252: Stairway to Hell Archive Disks
- Disk 299: 6502 Co Processor Life
- Disks 301-315: Beeb SID Demos
- Disk 320: Music 5000 System Disk
- Disks 323-352: Music 5000 Compilation Disks
- Disk 360: Bad Apple
- Disk 370: Video NuLA System Disk
- Disk 371-377: Video NuLA Demo Disks (gallery, games, etc)
- Disk 400-437: Retro Software Games
See the examples section below for some things to actually try out!
The complete MMFS Command Reference can be found here: https://github.com/hoglet67/MMFS/wiki/Command-Reference
These instructions all assume the Master configuration of the Beeb FPGA is being used.
- Shift-BREAK to boot STH Menu
- 43
- E
- Enter
- Shift-BREAK to boot STH Menu
- 47
- T
- Enter
- *DBOOT 436
- Press S1 until you get to the Master configuration with the Co Pro enabled
- Control Break
- *DIN 45
- *TUBEELT
- Press Space
- Press F10 (=F0) to launch
The flight controls are documented here:
http://www.elitehomepage.org/playguide.htm#A14
And here's a scan of the original "Space Trader's Flight Training Manual":
https://openretro.org/file/37a540d376344ac9add72431ecf70ab46dfb7fe4
- *DBOOT 320
- *DBOOT 320
- Use Up/Down/Enter to select "Load program"
- enter filename: ppach
- Enter to "Run program"
Other music files on this disc are:
- concert
- pavane
- ppach
- jukebox
You can try other disks by pressing Escape to get to the % command prompt.
%*DIN 322
%*CAT
%"JEM" LOAD RUN
After pressing Escape, F10 (=F0) will return to the menu.
- *DBOOT 305 ( or any disk from 301 to 315)
- *DBOOT 371 or *DBOOT 372