32-bit Forth OS mixed with C
text/ed: fix out of bounds regression on :godown
lib/ll: new unit


browse  log 



You can also use your local clone with git send-email.

#Dusk OS

builds.sr.ht status

Dusk OS is a 32-bit Forth and big brother to Collapse OS. Its primary purpose is to be maximally useful during the first stage of civilizational collapse, that is, when we can't produce modern computers anymore but that there's still many modern computers still around.

It does so by aggressively prioritizing simplicity at the cost of unorthodox constraints, while also aiming to make power users happy.

Dusk OS innovates by having an "almost C" compiler allowing it to piggy-back on UNIX C code, through a modest porting effort, to reach its goals and stay true to its design constraints with a minimal effort.

#Why build this OS?

Most modern operating systems can do whatever we want them to do. Why do we need another one? Simplicity.

It's difficult to predict post-collapse conditions, but we can suppose that many users will need to use their machines in novel and creative ways. Hackability of the operating system then becomes paramount. Open source modern operating systems all can be modified to fit its user's needs, but their complexity limits the likelihood that the user is able to do so. A simpler OS increases this likelihood.

But we can't have our cake and eat it too, right? Either you have a simple toy OS or a complex one. Well, maybe not?

Its authors believe that in the history of computing, Forth has been under-explored. Its approach to simplicity is, we think, revolutionary. It has significant shortcomings when system specifications become more complex (Forth hates complexity and doesn't manage it well), but we believe it possible to elegantly marry it with languages that like complexity better.

This mix, we believe, could provide a creative user with computing powers rarely seen with other approaches. We've got to try it.

To be clear: this is a research project, we don't know what it will yield beforehand. We have the intuition that it might lead to a big "ah ah!" moment and reveal a breathtaking combination of power and simplicity.

#Features making Dusk OS special

#A whole OS built from source on boot

One thing that makes Dusk OS special is that it boots from a very tiny core (1000 lines of i386 assembly). From this tiny core, on boot, it builds its way up to a system that has a functional C compiler, which then allows it to bootstrap itself some more.

With regards to "source bootstrapping", it's even more extreme than Collapse OS because modern machines allows this process to run quickly and the whole process is still faster than a regular Linux boot. On Collapse OS target machines, this process would be prohibitive, so a bigger part of the OS is cross-compiled into the kernel.

This peculiarity of Dusk OS has interesting properties. The nicest one, in my humble opinion, is that this allows us to sidestep the entire problems of binary compatibility and relocation and only deal with source compatibility. So, no ELF, no binutils, only code that is designed to run from where it was generated in the first place. This is so much simpler!

Object files? Global symbols? Nah. C functions that don't have a static storage type are simple Forth words.

#Shortest path to self-hosting for an "almost C" compiler

Dusk OS self-hosts in about 1000 lines of assembly and a few hundred lines of Forth (the exact number depends on the target machine). From there, it bootstraps to DuskCC, which is roughly 2000 lines of Forth code (including arch-specific backend and assembler). To my knowledge, Dusk OS is unique in that regard.

You can pick any C compiler that requires POSIX and it will automatically require order of magnitudes more lines of code to bootstrap because you need that POSIX system in addition to the C compiler. So even if you pick a small C compiler such as tcc, you still need a POSIX system to build it, which is usually in the millions of LOCs.

One of your best pick, should you try this path, would be Fiwix, a minimal POSIX i386 kernel weighting less than 50K lines of C+asm. If you run tcc on top of it, that brings your total LOC to 80K. Not bad. But as is, the kernel is not usable, you need userspace. To be minimalist, your best bet would be busybox at 190K LOC (bash+coreutils are 400K). To build Fiwix itself, you'll also need GNU Make at 25K LOC. So, not millions, but still a lot more than Dusk.

In your search for competitors to DuskCC, you can go back in time and look for simpler systems that have a C compiler. There's plenty of them, some of them open source. For example, there is FreeDOS, an open source implementation compatible with MS-DOS. It can certainly run a C compiler, but its kernel is 26K lines of C and assembler and building it requires Open Watcom, which clocks at more than 2M lines of code (since it's an IDE, it's probably only a subset of it that is actually needed for compilation, but I haven't looked closely enough to have a precise figure), and NASM which is 15K lines of C code for its "juicy" part (the assembler).

You can try to dive further down the history lane for even simpler systems such as CP/M and BDS C. But even then, you're still looking at 25K lines of assembler for BDS C and it's going to lack backends for modern CPUs.

So, unless someone tells me about some option I don't know about, DuskCC is quite innovative on the aspect of self-hosting path length.

#Who is Dusk for?

The target Dusk user is someone who's creative, close to hardware, can read a datasheet. Dusk shines (well, will shine) when one wants to poke around the hardware without limit.

It compares favorably to other more complete OSes because there's no concurrent process to mess with your poking and the driver structure is (well, will hopefully be) more approachable, hackable due to its stricter scope and savvier target audience.

Let's use an example. Let's say you're on a notebook that runs on a chipset of Intel's ICHn family. You read the datasheet and see "oh, nice, there's an SPI interface in there. Maybe that it's not hooked to anything on the notebook, let's play with it."

Now, that chipset is very, very central to the computer. There are good chances, on a BSD or Linux system, that if you begin poking around its registers, you'll step on someone else toes and crash the system because, for example, of some other process that needed to read from disk at the same time.

In Dusk, you could completely break the SATA controller, you'll still be golden as long as you don't access mass storage. Because Dusk doesn't have concurrency, you have tight control over what happen or doesn't happen on the machine, so all you need to do is to avoid words that access mass storage. That gives you ample wiggling space for your hacking session.

To be clear: this is also possible with a custom made BSD or Linux, but you're going to have to strip a lot of pieces from your distro before you get there and some of those pieces might be useful debugging tools which will be difficult to retrofit because they need a wider system. You'll also need a higher cognitive space to fit BSD/Linux wider abstractions in your mind.


  • Has a VM written in C, buildable from a POSIX environment, which allows Dusk to build itself for any of its supported targets.
  • Has an "almost C" compiler which still needs some work, but is already capable of compiling a nice subset of C.
  • It can run bare metal on some PCs (and QEMU, of course). It has drivers (in various state of sophistication) for:
    • VGA in text mode
    • PS/2 keyboard
    • PCI controllers
    • ATA controllers
    • AHCI controllers
    • Floppy controllers
    • PC COM ports
    • VESA in graphical mode
    • PS/2 mouse support
  • Can read, write and boot from FAT12/FAT16 (no FAT32 for now) volumes.
  • Can create new FAT12 volumes.
  • Very small footprint. In Grid mode (TUI mode) with the Grid text editor and DuskCC (including its stdlib) loaded, Dusk uses 180KB of RAM on a PC.
  • It completely self-hosts on all its target (only PC for now) machines.
  • Did I mention that the whole code for Dusk OS and its ported applications (excluding docs and test code) is less than 13K lines of code and that DuskCC, including its assemblers, is 2000 lines?
  • Since text/ed has reached a usable status, the main author of Dusk has been developing it from within itself on an old Pentium 75 Mhz with 16mb of RAM and he's having a blast.

List of ported codebases:

  • The CVM of Collapse OS
  • The uxn VM
  • The puff() algorithm from zlib
  • The left text editor. (Still a bit glitchy...)

List of homegrown applications:

  • C Compiler (see doc/cc)
  • Text editor (see doc/text/ed)

What's next? See the roadmap!

Development happens on sourcehut.

Unlike Collapse OS which is a personal effort and doesn't lend itself well to collaboration, Dusk OS' wider scope makes it fitting for a collective effort. Let's discuss this on its public mailing list.

#Build and run Dusk

Dusk is designed to run on bare metal and to build itself from itself. However, it's also possible to build Dusk from any POSIX platform using Dusk's C VM from posix/vm.c. This VM implements a Forth that can interpret the whole of Dusk's Forth code, but this VM is CPU-agnostic and has its own simplistic bytecode.

That is enough to generate bare metal images for any of its target platforms, so that's why it exists. To build this VM, you need:

  • GNU Make
  • A C compiler

Running make will yield a ./dusk binary which if opened, provides an interactive prompt.

Documentation lives in fs/doc. You can begin with doc/index. Type bye to quit.

Dusk OS expects a non-canonical raw input. With a regular TTY, your input will be buffered and echoed twice and reads to it will be blocking. We don't want that. To avoid that, you can invoke it like this:

(stty -icanon -echo min 0; ./dusk; stty icanon echo)

make run does this for you.

#Running on QEMU or bare metal

Running Dusk under the POSIX VM is fine, but severly limited: the filesystem is read-only and there is no Grid (text UI system) or Screen (graphical system).

To see a fully-featured Dusk, it's better to run it on an actual machine or, if you're in a hurry, under QEMU. You can do the latter with make pcrun.

To deploy Dusk on a real machine, it's a bit more involving and you should read doc/deploy.txt.

#See what it can do

Dusk OS on the PC has graphical capabilities as well as varvara bindings for it. If you have QEMU installed, you can try a few little things on it. First, start the QEMU VM with make pcrun. Then, enter this:

f<< tests/manual/uxn/sprite.fs

This will:

  1. Compile DuskCC (in forth)
  2. Compile uxn (in C)
  3. Compile uxntal (the uxn assembler) (in C)
  4. Compile varvara (in forth)
  5. Compile tests/manual/uxn/sprite.tal (a copy of the official screen.tal)
  6. Put the system in graphical mode
  7. Run the compiled sprite.tal

You now have it running. There is also a mouse cursor that you can move around. Press Escape to return to prompt. You can try the same thing with:

  • tests/manual/uxn/mandel.fs
  • tests/manual/uxn/ctrl.fs
  • tests/manual/uxn/mouse.fs
  • text/left.fs