brass!!

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/runtime/u3.md b/docs/runtime/u3.md
new file mode 100644
index 0000000..5f1457f
--- /dev/null
+++ b/docs/runtime/u3.md
@@ -0,0 +1,34 @@
+---
+description: "Introduction to u3, the Nock runtime system. C library for making and storing nouns. Solid-state interpreter."
+layout:
+  title:
+    visible: true
+  description:
+    visible: false
+  tableOfContents:
+    visible: true
+  outline:
+    visible: true
+  pagination:
+    visible: true
+---
+
+# U3
+
+The Urbit interpreter is built on a Nock runtime system written in C, `u3`.  This section is a relatively complete description.
+
+You should keep reading if (a) you're planning to work on the Urbit interpreter; (b) you're a language implementation geek; or (c) you don't really understand anything until you've seen the actual structs.
+
+## u3: Noun processing in C {#u3-noun-processing-in-c}
+
+`u3` is the C library that makes Urbit work.  If it wasn't called `u3`, it might be called `libnoun` - it's a library for making and storing nouns.
+
+What's a noun?  A noun is either a cell or an atom.  A cell is an ordered pair of any two nouns.  An atom is an unsigned integer of any size.
+
+To the C programmer, this is not a terribly complicated data structure, so why do you need a library for it?
+
+One: nouns have a well-defined computation kernel, Nock, whose spec fits on a page and gzips to 340 bytes.  But the only arithmetic operation in Nock is increment.  So it's nontrivial to compute both efficiently and correctly.
+
+Two: `u3` is designed to be a "solid-state interpreter," ie, a single-level store which is transparently snapshotted.  This implies a specialized memory-management model, etc, etc.
+
+(Does `u3` depend on the higher levels of Urbit, Arvo and Hoon? Yes and no.  `u3` expects you to load something shaped like an Arvo kernel, and use it as an event-processing function.  But you don't need to use this feature if you don't want, and your kernel doesn't have to be Arvo proper - just Arvo-compatible.  Think of `u3` as the BIOS and Arvo as the boot kernel.  And there are no dependencies at all between Hoon the language and `u3`.)