Filestick

FileStick

This is still a very early work in progress.

This project implements an Econet fileserver "onna stick". Acorn had the FileStore, so this is kind of a play on words on the FileStore. The system is built on a Lattice UltraPlus 5K FPGA, which includes 128kbyte of static RAM on the chip, as well as a number of dual ported blockrams, which makes it ideal for a small system project.

The prototype board is based on the UPduino 3.1 board. See: https://tinyvision.ai/products/upduino-v3-1

The version 1 board contains the econet front end, the up5k FPGA, an SD card slot, flash memory and a USB interface, implemented with an FTDI USB UART.

The system consists of a RISC-V core (modified FemtoRV core supporting some extra CSRs, the ecall instruction to handle system calls, ebreak and some limited illegal instruction trapping). The core is an rv32imc (RISC-V 32 bit with the multiply/divide and compressed instructions extensions).

Features

• USB powered, < 500mA
• Simple RISC-V implementation and early microcomputer style operating system. System functions via ecall interface.
• Fully buffered econet implementation, with econet exposed via standard open/read/write/close/ioctl operations.
• Switchable econet clock generation and termination, so that you don't need a separate clock and terminators for a small Econet.
• Programmable timers.
• USB serial interface with hardware FIFO and hardware CTS/RTS flow control. Has an interactive mode for use as the system console and raw mode for transferring files over USB etc.
• FAT support using FatFS for both microSD and built-in flash.
• RGB LED, useful for showing system activity.
• C / C++ programming made easy with newlib and GCC riscv cross compiler, and a lightweight library and specs file for system-specifics.

Project structure

• hardware: Contains the Verilog source code. Requires a recent version of yosys, nextpnr, and the icestorm tools. (Debian users will need to build these from source, as Debian is still on the old arachnepnr).

• system: Contains the operating system. This isn't a multiuser/ multitasking operating system, it's an OS in the vein of a classic home micro's operating system. It does provide a number of system calls using the Linux rv32 syscall numbers. Remember there is no virtual memory on this very small system, however, some simple memory protection is planned so that user programs can't accidentally overwrite kernel memory or device address space.

• lib: The filestick library. This is required for most userspace programs as at the very least it provides the sbrk implementation needed to properly support libc's malloc.

Other programs

(Full disclosure: the emulator and BASIC interpreter below was done with the full assistance of Claude Code, much as it would be an interesting project to do them from scratch, it would take me far too long, I had already been putting off writing the emulator for 2 years :-) )

• emulator: An emulator. See the README file for how to use it. The emulator is based off the Verilog code and should match it closely. At the moment it only supports an OS with pseudottys (e.g. Linux) but it's probably not too hard to do a version for Windows for anyone so inclined. By default, tries to match the running speed of the real hardware.

• basic: A small BBC BASIC implementation. Implements most of BASIC II as you would find on a BBC Micro and should be compatible with a saved BBC BASIC file. Graphics/sound/screen modes not implemented because there aren't any. Nor is there an assembler (if you want to write rv32 asm, I suggest using xpack's gnu as). The code segment is around 28k, and when running on the board, there's about 33k available for BASIC programs.

• cputest: A test suite for the CPU, checking each unprivileged RV32IMC instruction against the RISC-V specification. See the README file.

Toolchain

The xPack GNU RISC-V embedded GCC project is used to build all source code. xPack provides ready-to-run toolchains for many platforms including Linux, Windows and MacOS. Other GCC toolchains will probably work, but xPack is likely the easiest/most convenient to use.

The xPack toolchain includes newlib (the libc).

See their releases here: https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases

The build system uses cmake. If you're running Linux, your distro almost certainly has cmake. Otherwise see: https://cmake.org/

Building

To build the gateware, you will need yosys, nextpnr and icestorm tools installed. Run:

$ cd rtl
$ make PCF=<pcf version of your board>

If the PCF variable is left unset, the default will be picked which will be for the latest version of the hardware.

To build the software, assuming a suitable rv32 compiler (e.g. the xpack one suggested):

$ cmake -B build
$ cd build
$ make

Outputs will be build/system/filestick-system.bin, build/boot/filestick-boot.bin, build/lib/libfilestick.a, build/init/init.elf.

Installing

To install the gateware, in the rtl directory run make flash which will use a suitable FTDI FT232H programmer to write the flash. This also installs the bootloader as part of the gateware file.

To install the system image with the FTDI programmer:

iceprog -d i:0x0403:0x6014 -X -o 0x020000 build/system/filestick-system.bin

To install init with the FTDI programmer:

iceprog -d i:0x0403:0x6014 -o 0x030000 build/init/init.elf

To install the in-built filesystem:

iceprog -d i:0x0403:0x6014 -o 0x040000 256kfs.img

(256kfs.img is a blank 256k fat12 filesystem, used for storing system settings and some basic software).

TODO

There's much to do. More to come later, including how to write programs for the FileStick.