From 24d68e841f6c4adf0622b132f905e97d115a4e2d Mon Sep 17 00:00:00 2001
From: Chenguang Wang <w@bunny.rocks>
Date: Sat, 30 Dec 2023 10:43:10 -0800
Subject: Add missing documentation for union types and VAL.

See previous discussion here[1]. It's unclear to me how to preview HTML page
generated from the .txt file, though.

[1]: https://lists.sr.ht/~mpu/qbe/%3C87cz1jq26k.fsf%40greenfork.me%3E
---
 doc/il.txt | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/doc/il.txt b/doc/il.txt
index cc3e021..2e57290 100644
--- a/doc/il.txt
+++ b/doc/il.txt
@@ -15,7 +15,7 @@
   2. <@ Types >
       * <@ Simple Types >
       * <@ Subtyping >
-  3. <@ Constants >
+  3. <@ Constants and Vals >
   4. <@ Linkage >
   5. <@ Definitions >
       * <@ Aggregate Types >
@@ -168,8 +168,8 @@ The rationale is that a word can be signed or unsigned, so
 extending it to a long could be done in two ways, either
 by zero-extension, or by sign-extension.
 
-- 3. Constants
---------------
+- 3. Constants and Vals
+-----------------------
 
     `bnf
     CONST :=
@@ -182,6 +182,10 @@ by zero-extension, or by sign-extension.
         CONST
       | 'thread' $IDENT  # Thread-local symbol
 
+    VAL :=
+        DYNCONST
+      | %IDENT
+
 Constants come in two kinds: compile-time constants and
 dynamic constants.  Dynamic constants include compile-time
 constants and other symbol variants that are only known at
@@ -221,6 +225,10 @@ When the `thread` keyword prefixes a symbol name, the
 symbol's numeric value is resolved at runtime in the
 thread-local storage.
 
+Vals are used as arguments in regular, phi, and jump
+instructions within function definitions.  They are
+either constants or function-scope temporaries.
+
 - 4. Linkage
 ------------
 
@@ -293,6 +301,15 @@ using linkage flags.
         '{'
             ( SUBTY [NUMBER] ),
         '}'
+      | # Union type
+        'type' :IDENT '=' ['align' NUMBER]
+        '{'
+            (
+                '{'
+                    ( SUBTY [NUMBER] ),
+                '}'
+            )+
+        '}'
       | # Opaque type
         'type' :IDENT '=' 'align' NUMBER '{' NUMBER '}'
 
@@ -318,6 +335,15 @@ explicitly specified by the programmer.
 
     type :cryptovector = align 16 { w 4 }
 
+Union types allow the same chunk of memory to be used with
+different layouts.  They are defined by enclosing multiple
+regular aggregate type bodies in a pair of curly braces.
+Size and alignment of union types are set to the maximum size
+and alignment of each variation or, in the case of alignment,
+can be explicitly specified.
+
+    type :un9 = { { b } { s } }
+
 Opaque types are used when the inner structure of an
 aggregate cannot be specified; the alignment for opaque
 types is mandatory.  They are defined simply by enclosing
-- 
cgit 1.4.1