docs: specify what's expected of the VM

Sponsored-by: author

1 files changed, 31 insertions, 0 deletions

diff --git a/ambient.md b/ambient.md
index de78993..f9a3a36 100644
--- a/ambient.md
+++ b/ambient.md
@@ -248,6 +248,37 @@ amount of memory. We fail the build if it exceeds a pre-determined
 time limit. We fail the build if the amount of output via the serial
 console exceeds a pre-determined limit.
 
+# Architecture
+
+At a very abstract level, the Ambient architecture is as follows:
+
+* Ambient creates a virtual machine with four block devices (using
+  `virtio_blk`) in addition to the system disk (`/dev/vda` on Linux):
+  - `/dev/vdb`: the read-only source device: a tar archive of the
+    project's source tree
+  - `/dev/vdc`: the read/write artifact device: for the project to
+    write a tar archive of any build artifacts it wants to export
+    - this would be write-only if that was possible
+  - `/dev/vdd`: the read-only dependencies device: a tar archive of
+    additional dependencies in a form that the project can use
+  - `/dev/vde`: the read/write cache device: a tar archive of any
+    files the project wants to persist across runs; for example, for a
+    Rust project, this would contains the cargo target directory
+    contents
+* The VM additionally has a serial port where it will write the
+  build log. On Linux this is `/dev/ttyS0`.
+* The VM automatically, on boot, creates
+  `/workspace/{src,cache,deps}`, and extracts the source, cache, and
+  dependencies tar archives to those directories.
+* The VM then changes current working directory to `/workspace/src`
+  and runs `./.ambient-script` (if the script isn't executable, the VM
+  first makes it so). The script's stdout and stderr are redirected to
+  the serial port.
+
+The `ambient-build.service` and `ambient-run-script` files in the
+Ambient source tree implement this for Linux with systemd, and have
+been tested with Debian.
+
 # Acceptance criteria
 
 [Subplot]: https://subplot.tech