Soul of a tiny new machine. More thorough tests → More comprehensible and rewrite-friendly software → More resilient society.
Go to file
Kartik K. Agaram 71e4f38129 7842 - new directory organization
Baremetal is now the default build target and therefore has its sources
at the top-level. Baremetal programs build using the phase-2 Mu toolchain
that requires a Linux kernel. This phase-2 codebase which used to be at
the top-level is now under the linux/ directory. Finally, the phase-2 toolchain,
while self-hosting, has a way to bootstrap from a C implementation, which
is now stored in linux/bootstrap. The bootstrap C implementation uses some
literate programming tools that are now in linux/bootstrap/tools.

So the whole thing has gotten inverted. Each directory should build one
artifact and include the main sources (along with standard library). Tools
used for building it are relegated to sub-directories, even though those
tools are often useful in their own right, and have had lots of interesting
programs written using them.

A couple of things have gotten dropped in this process:
  - I had old ways to run on just a Linux kernel, or with a Soso kernel.
    No more.
  - I had some old tooling for running a single test at the cursor. I haven't
    used that lately. Maybe I'll bring it back one day.

The reorg isn't done yet. Still to do:
  - redo documentation everywhere. All the README files, all other markdown,
    particularly vocabulary.md.
  - clean up how-to-run comments at the start of programs everywhere
  - rethink what to do with the html/ directory. Do we even want to keep
    supporting it?

In spite of these shortcomings, all the scripts at the top-level, linux/
and linux/bootstrap are working. The names of the scripts also feel reasonable.
This is a good milestone to take stock at.
2021-03-03 22:21:03 -08:00
archive 6206 2020-04-17 01:33:51 -07:00
editor 7842 - new directory organization 2021-03-03 22:21:03 -08:00
html 7834 2021-03-01 14:59:37 -08:00
linux 7842 - new directory organization 2021-03-03 22:21:03 -08:00
shell 7842 - new directory organization 2021-03-03 22:21:03 -08:00
tools 7842 - new directory organization 2021-03-03 22:21:03 -08:00
.gitattributes 6690 2020-07-30 21:39:19 -07:00
101screen.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
102keyboard.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
103grapheme.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
104test.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
105string-equal.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
106stream.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
108write.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
109stream-equal.subx 6769 - support for creating fake files in Mu tests 2020-09-10 23:00:19 -07:00
112read-byte.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
113write-stream.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
115write-byte.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
117write-int-hex.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
118parse-hex-int.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
120allocate.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
121new-stream.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
123slice.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
124next-token.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
126write-int-decimal.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
127next-word.subx 7329 - snapshot: advent day 4 part 2 2020-12-04 23:02:53 -08:00
301array-equal.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
302stack_allocate.subx 7254 2020-11-17 01:06:43 -08:00
308allocate-array.subx 7254 2020-11-17 01:06:43 -08:00
309stream.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
310copy-bytes.subx 7254 2020-11-17 01:06:43 -08:00
311decimal-int.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
312copy.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
313index-bounds-check.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
314divide.subx 7290 2020-11-27 21:37:20 -08:00
400.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
403unicode.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
408float.mu 7276 2020-11-26 11:36:29 -08:00
411string.mu 7690 2021-02-07 00:20:29 -08:00
412render-float-decimal.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
500text-screen.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
501draw-text.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
502test.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
503manhattan-line.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
504test-screen.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
LICENSE.txt 7489 - include GNU Unifont 2021-01-09 18:20:28 -08:00
README.baremetal.md 7842 - new directory organization 2021-03-03 22:21:03 -08:00
README.md 7842 - new directory organization 2021-03-03 22:21:03 -08:00
boot.bochsrc 7842 - new directory organization 2021-03-03 22:21:03 -08:00
boot.hex 7842 - new directory organization 2021-03-03 22:21:03 -08:00
boot0.hex 7842 - new directory organization 2021-03-03 22:21:03 -08:00
bootstrap.md 6618 - new docs 2020-07-06 01:05:10 -07:00
cheatsheet.pdf 5485 - promote SubX to top-level 2019-07-27 17:47:59 -07:00
ex1.hex 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex1.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex2.hex 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex2.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex2.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex3.hex 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex3.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex4.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex5.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex6.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex7.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
ex8.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
life.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
modrm.pdf 5485 - promote SubX to top-level 2019-07-27 17:47:59 -07:00
mu-init.subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
mu.md 7691 2021-02-07 09:53:14 -08:00
mu_instructions 7478 2021-01-03 22:38:41 -08:00
rpn.mu 7842 - new directory organization 2021-03-03 22:21:03 -08:00
sib.pdf 5485 - promote SubX to top-level 2019-07-27 17:47:59 -07:00
subx.md 6885 - starting on floating-point instructions 2020-09-27 21:12:48 -07:00
subx_bare.md 7439 - start translating Mu programs to baremetal 2020-12-28 11:09:30 -08:00
subx_debugging.md 7401 - clean up support for non-Linux platforms 2020-12-25 12:28:10 -08:00
subx_opcodes 7412 - drawing pixels to screen 2020-12-26 19:13:23 -08:00
translate 7842 - new directory organization 2021-03-03 22:21:03 -08:00
translate_emulated 7842 - new directory organization 2021-03-03 22:21:03 -08:00
translate_subx 7842 - new directory organization 2021-03-03 22:21:03 -08:00
translate_subx_emulated 7842 - new directory organization 2021-03-03 22:21:03 -08:00
vimrc.vim 7760 2021-02-20 22:37:08 -08:00
vocabulary.md 6658 2020-07-18 15:56:32 -07:00
x86_approx.md 6945 2020-10-04 01:33:49 -07:00

README.md

Mu: a human-scale computer

Mu is a minimal-dependency hobbyist computing stack (everything above the processor).

Mu is not designed to operate in large clusters providing services for millions of people. Mu is designed for you, to run one computer. (Or a few.) Running the code you want to run, and nothing else.

$ git clone https://github.com/akkartik/mu
$ cd mu
$ ./translate_mu apps/ex2.mu  # emit a.elf
$ ./a.elf  # add 3 and 4
$ echo $?
7

Rather than start from some syntax and introduce layers of translation to implement it, Mu starts from the processor's instruction set and tries to get to some safe and clear syntax with as few layers of translation as possible. The emphasis is on internal consistency at any point in time rather than compatibility with the past. (More details.)

Currently Mu requires a 32-bit x86 processor.

Goals

In priority order:

  • Reward curiosity.
  • Safe.
    • Thorough test coverage. If you break something you should immediately see an error message. If you can manually test for something you should be able to write an automated test for it.
    • Memory leaks over memory corruption.
  • Teach the computer bottom-up.

Non-goals

  • Speed. Staying close to machine code should naturally keep Mu fast enough.
  • Efficiency. Controlling the number of abstractions should naturally keep Mu using far less than the gigabytes of memory modern computers have.
  • Portability. Mu will run on any computer as long as it's x86. I will enthusiastically contribute to support for other processors -- in separate forks. Readers shouldn't have to think about processors they don't have.
  • Compatibility. The goal is to get off mainstream stacks, not to perpetuate them. Sometimes the right long-term solution is to bump the major version number.
  • Syntax. Mu code is meant to be comprehended by running, not just reading. For now it's a thin veneer over machine code. I'm working on memory safety before expressive syntax.

Toolchain

The Mu stack consists of:

  • the Mu type-safe language;
  • SubX, an unsafe notation for a subset of x86 machine code; and
  • bare SubX, a more rudimentary form of SubX without certain syntax sugar.

All Mu programs get translated through these layers into tiny zero-dependency binaries that run natively. The translators for most levels are built out of lower levels. The translator from Mu to SubX is written in SubX, and the translator from SubX to bare SubX is built in bare SubX. There is also an emulator for Mu's supported subset of x86, that's useful for debugging SubX programs.

Mu programs build natively either on Linux or on Windows using WSL 2. For Macs and other Unix-like systems, use the emulator:

$ ./translate_mu_emulated apps/ex2.mu  # ~2 mins to emit a.elf
$ ./bootstrap run ./a.elf  # run in the emulator
$ echo $?

Mu programs can be written for two very different environments:

  • With just a Linux kernel. This is the environment that Mu bootstraps itself into, and it's the option for programming with stdin, stdout and file descriptors.

  • Without an OS, by interacting directly with the screen and keyboard. This is the option for rudimentary pixel graphics. There's currently no mouse, no hardware acceleration, no virtual memory, no process separation, no multi-tasking, no persistent storage, no network. These programs have not yet been tested on native hardware, only on on Qemu and Bochs. But these baremetal programs build from scratch, without any reliance on C. This is the future. Here is Conway's Game of Life on Mu:

    $ ./translate_mu_baremetal baremetal/life.mu  # emit disk.img
    $ qemu-system-i386 disk.img
    
    screenshot of Game of Life running on Mu without any intervening Operating System

Use translate_mu to build programs for Linux, and translate_mu_baremetal for running without Linux. The standard libraries are totally separate for the two options, so programs for one won't run on the other.

Syntax

The entire stack shares certain properties and conventions. Programs consist of functions and functions consist of statements, each performing a single operation. Operands to statements are always variables or constants. You can't perform a + b*c in a single statement; you have to break it up into two. Variables can live in memory or in registers. Registers must be explicitly specified. There are some shared lexical rules. Comments always start with '#'. Numbers are always written in hex. Many terms can have context-dependent metadata attached after '/'.

Here's an example program in Mu:

ex2.mu

More details on Mu syntax →

Here's an example program in SubX:

== code
Entry:
  # ebx = 1
  bb/copy-to-ebx  1/imm32
  # increment ebx
  43/increment-ebx
  # exit(ebx)
  e8/call  syscall_exit/disp32

More details on SubX syntax →

Forks

Forks of Mu are encouraged. If you don't like something about this repo, feel free to make a fork. If you show it to me, I'll link to it here. I might even pull your changes into this repo!

  • mu-normie: with a more standard build system that organizes the repo by header files and compilation units. Stays in sync with this repo.
  • mu-x86_64: experimental fork for 64-bit x86 in collaboration with Max Bernstein. It's brought up a few concrete open problems that I don't have good solutions for yet.
  • uCISC: a 16-bit processor being designed from scratch by Robert Butler and programmed with a SubX-like syntax.
  • subv: experimental SubX-like syntax by s-ol bekic for the RISC-V instruction set.

Desiderata

If you're still reading, here are some more things to check out:

Credits

Mu builds on many ideas that have come before, especially:

  • Peter Naur for articulating the paramount problem of programming: communicating a codebase to others;
  • Christopher Alexander and Richard Gabriel for the intellectual tools for reasoning about the higher order design of a codebase;
  • David Parnas and others for highlighting the value of separating concerns and stepwise refinement;
  • The folklore of debugging by print and the trace facility in many Lisp systems;
  • Automated tests for showing the value of developing programs inside an elaborate harness;

On a more tactical level, this project has made progress in a series of bursts as I discovered the following resources. In autobiographical order, with no claims of completeness: