# A-machine: a minimal RISC-V (RV32IMA) emulator in POSIX AWK

## About

A-machine is a simple and straightforward implementation of the RV32I specification with M (multiplication/division) and A (atomic operations) extenstions. It consists of two files:

- [amach.awk](amach.awk), the emulator core itself that supports .dec files,
- and [amach](amach) shell script which is a two-liner that uses POSIX `od` to convert .bin files into .dec files on the fly and then passes them to the emulator core.

Additionally, A-machine is shipped with a reference test suite that assumes that you have a full RISC-V toolchain installed under the `riscv64-linux-gnu-` prefix (adjustable in the `Makefile`). Just run `make run` to build and run all tests. In case you don't have any toolchain available, a file called `rv32ima_tests.bin` is also included into the repo.

The project is to be considered highly experimental and not production-ready in any way.

## Usage

First, decide where your program needs to be loaded in memory. The default LVA (loading virtual address) is 0x100b0. In most AWK implementations, you need to convert this value to decimal (the default is 65712).

Then, most probably, you'll want to use the provided wrapper:
```sh
[LVA=...] ./amach path/to/program.bin
```

Or you can run the following:
```sh
od -An -v -tu1 path/to/program.bin | POSIXLY_CORRECT=1 awk -f amach.awk [-v LVA=...]
```

But in case you already have a program in the `.dec` format, you can pass it directly to AWK:
```sh
POSIXLY_CORRECT=1 awk -f amach.awk [-v LVA=...] -- path/to/program.dec
```

## Support

Currently, A-machine only supports the **unprivileged** RV32IMA instruction set with a few additional `ecall` syscalls: 63 (sys_read, for fd 0 only), 64 (sys_write, for fd 1 and 2 only) and 93 (sys_exit). For completeness, `fence` instruction is also supported but yields a no-op.

## Plans (from higher to lower priority)

- Implement the C-extension (compressed instruction set).
- Implement a simple RV32IMAC disassembler in POSIX AWK.
- Introduce more popular Linux-compatible syscalls (that make sense to implement in AWK but don't increase the overall project complexity).
- Test for RV32EMC compatibility (that the code built for the "embedded" variant runs here).
- Implement a privileged instruction set minimum (Zicsr), interrupts and traps.
- If time permits, implement a simple RV32IMAC assembler in POSIX AWK, with full pseudo-instruction support.

## FAQ

### What was the rationale of creating a platform emulator in the least suitable language for this purpose?

The main reason is maximum portability. While AWK is clearly tailored for text processing and, in its standard variant, doesn't even has bitwise operations and hexadecimal literals support, it still remains the single most common scripting language present on every POSIX-compatible system, including embedded ones that run [BusyBox](https://busybox.net/) on top of the kernel and might not have anything else from available programming tools at all. In such conditions, an emulation layer written in AWK is far from efficient but still better than nothing.

Apart from that, the A-machine serves more of an educational purpose for the author to learn about the RISC-V ISA and the details of its inner workings.

### Will I be able to run a Linux kernel on A-machine?

While A-Machine creation was partially inspired by the wonderful [mini-rv32ima project](https://github.com/cnlohr/mini-rv32ima) (although not a single line of code had been taken from there), running a (no-MMU) Linux kernel here is not currently possible due to several reasons. First, A-machine needs to support Zicsr and other privileged RV32 extensions to even theoretically be capable of running the kernel. Second, in order to run the same kernel build as mini-rv32ima does, A-machine will need to support the exact same MMIO model and non-standard CSR calls as mini-rv32ima, which already is non-trivial and will indeed require some logic copy-pasting, which the author is trying to avoid.

So, the answer is: no, not anytime soon.

### 64 bits, floats, doubles?

Not in this project. As already mentioned, A-machine, as well as all of its supplementary artifacts, is more of educational value. Stay tuned for the next RISC-V-related emulation projects for something more practical, fast and powerful.

### Is the project name a pun on [Z-machine](https://en.wikipedia.org/wiki/Z-machine)?

You may think so too, but it just came from "AWK machine" and the desire to denote that, despite being an AWK script, this is still "a machine". However, the name is still subject to possible changes in the future.

## Credits

Created by Luxferre in 2026, released into the public domain with no warranties.