Zeitlos is a work-in-progress SOC (System-on-a-Chip) and OS (Operating System) developed in tandem and intended to provide a responsive graphical environment for using and developing timeless applications on FPGA computers.

The core applications allow Zeitlos to be used as an extensible multi-window network terminal with scripting and graphics.

Zeitlos is the successor to Zucker.

Features

SOC

OS

• Pre-emptive multitasking
• Flat memory model with virtual address space for apps
• FAT16/32 filesystem
• Core apps in flash -- boots to a desktop with no sdcard (docs/flash_apps.md)
• Object-based interprocess messaging and streaming
• IP/ARP/ICMP/UDP/DHCP/NTP/DNS/TFTP/TCP/telnet/ssh networking

Memory Translation Unit

Zeitlos doesn't have an MMU but instead has a single virtual address space that is remapped to a main memory address during context switches.

The Zeitlos kernel is located at 0x4000_0000 which is the beginning of main memory, and apps are loaded immediately after the kernel. However, each app executes at fixed address 0x8000_0000 which is a mirror of their actual address in the main memory. The translation base address register is set during context switches so that each app can access its own memory through 0x8000_0000.

With the MTU, there is no need for position independent code or complicated address relocation.

Apps

Core Apps

Additional Apps

Boards

Zeitlos will initially support ECP5, Artix-7, GateMate FPGAs.

The following boards are currently supported:

• Machdyne Obst
• Machdyne Lakritz
• Machdyne Kölsch
• Machdyne Lebkuchen
• Machdyne Mozart / ML1
• Machdyne Sergei / ML1
• ULX3S UNTESTED (see bounty)
• (more soon)

If you have an unsupported board and want to try Zeitlos, please open an issue.

Usage

An sdcard is optional. The core apps (wm, net, repl, term) are programmed into flash alongside the kernel, so a freshly flashed board boots straight to the graphical desktop with nothing else attached. See Core apps in flash below.

1. Build and flash the system:

Building Zeitlos requires FPGA tools (Yosys, nextpnr, and a bitstream packer for your FPGA family) and a RISC-V toolchain. Most of these are available as Debian/Ubuntu packages:

$ sudo apt install yosys nextpnr-ecp5 fpga-trellis fpga-trellis-database \
                   openfpgaloader

The RISC-V compiler is the one piece not to take from apt: Zeitlos is built against newlib, and Ubuntu's gcc-riscv64-unknown-elf ships no C library at all. Use the xPack prebuilt toolchain (GCC + binutils + newlib, no building required) and set RISCV_PREFIX in sw/common/arch.mk to point at it.

See docs/toolchain.md for current upstream versions, the OSS CAD Suite bundle, GateMate boards, and the trade-offs between the RISC-V toolchain options.

Note that Zeitlos now builds rv32im (hardware multiply and divide) -- see docs/muldiv.md. Gateware and software must be flashed together.

$ git clone https://github.com/machdyne/zeitlos
$ cd zeitlos
$ git submodule update --init --recursive
$ make BOARD=lakritz CABLE=dirtyJtag flash

The above command builds the SOC, BIOS, OS and apps, then writes the gateware, kernel, boot splash and core apps to flash.

The BIOS will automatically boot the kernel if no keys are pressed, and the kernel starts wm, net and repl automatically -- you'll land straight in the graphical desktop. See docs/welcome.md for how to use it from there.

The mouse pointer tells you when it's ready. It is a Z while the system is still starting up and an X once it isn't. The dock won't launch anything while the Z is showing -- term connects to repl the moment it starts, and launching it too early gives you a blank window rather than a terminal. Wait for the X. See docs/socctl.md.

2. Optionally, add an sdcard:

An sdcard is only needed for storing files and for apps beyond the core four. Write the zeitlos image to one with:

curl -LO https://github.com/machdyne/zeitlos/releases/latest/download/zeitlos.img.gz
gzip -dc zeitlos.img.gz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

Replace /dev/sdX with your sdcard's device node (check with lsblk first — writing to the wrong device will destroy its contents).

Core apps in flash

wm, net, repl and term are written to flash as part of a normal make flash, immediately after the kernel. They are an underlay beneath the filesystem, not a separate namespace: there is still exactly one name for term, and run term behaves identically whether it came from flash or from a card.

The rule is one line:

if the filesystem has it, use that; otherwise use the flash copy.

A file on the card wins, because the only way it got there was somebody deliberately putting it there — which is what makes xf wm still work as a single-app hot-swap during development, with no version scheme or timestamps involved. ls lists the flash copies in a separate section, skipping any that a real file is shadowing, so what you see is what run would actually launch.

For iterating on the OS itself, make dev-flash rebuilds and reflashes the kernel and core apps without touching the gateware:

$ make clean && make BOARD=obst dev-flash

See docs/flash_apps.md for the archive format and the design reasoning.

Developers

Documentation

The Zeitlos documentation will be the Timeless Computing book, which will be included in the default Zeitlos distribution. The later chapters will explain the system, list the API, etc.

The Zeitlos implementation portions of the book are currently located in the docs directory.

LLM-generated code

This project makes use of LLMs for code and documentation.

License

The contents of this repo are released under the Lone Dynamics Open License with the following exceptions:

• rtl/cpu/picorv32 uses the ISC license.
• rtl/ext/uart16550 uses the LGPL license.
• rtl/mem/sdram_kianv uses the Apache 2.0 license.
• rtl/ext/usb_hid_host uses the Apache 2.0 license.
• sw/os/fs/fatfs uses a BSD compatible license.