From 003d63b8208267bde36eb76967d6cffd6ed8746b Mon Sep 17 00:00:00 2001
From: Emery Hemingway <ehmry@posteo.net>
Date: Mon, 27 Jan 2020 11:46:41 +0100
Subject: [PATCH] Add boot descriptions to README

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 2c4f03e..f45b447 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,50 @@
 [Nix](https://nixos.org/nix/) expressions related to the
 [Genode OS framework](https://genode.org).
 
+# System description format
+
+The high-level interface to system building are boot descriptions. These Dhall 
+documents describe the configuration of an [Init](https://genode.org/documentation/genode-foundations/19.05/system_configuration/The_init_component.html)
+instance and a store of ROM (Read-Only Memory) modules. These description can be 
+used to build firmware-like binary images or merged and nested within other 
+descriptions. In theory these descriptions can arrange file-systems, but those
+functions are missing.
+
+The description schema is documented as code:
+https://git.sr.ht/~ehmry/dhall-genode/tree/master/Boot/package.dhall
+
+# Package manifests
+
+Software packages are described my manifest documents, which can be used to 
+build the ROM map in boot descriptions. This manifests can be automatically 
+generated and made available within Nix builds and dev-shells via environmental 
+variables. This may seem awkward, but consider that this is to support building 
+firmware systems without a $PATH or even a file-system.
+
+An example manifest:
+
+```dhall
+{ bin =
+    { init = { mapKey = "init", mapValue = "/nix/store/.../bin/init" }
+    , vfs  = { mapKey = "vfs",  mapValue = "/nix/store/.../bin/vfs" }
+    }
+, lib =
+    { vfs =
+        { mapKey = "vfs.lib.so", mapValue = "/nix/store/.../lib/vfs.lib.so" }
+    }
+}
+```
+
+Referenced in a boot configuration:
+
+```dhall
+let m = env:MANIFEST -- take the manifest from the shell environment
+
+let rom = Genode.Boot.toRomPaths [ m.bin.init, m.bin.vfs, m.lib.vfs ]
+
+in  { config = Genode.Init.default, rom = rom } : Genode.Boot.Type
+```
+
 # Contributing
 
 At the moment every user needs to also act as distro developer, designing how