Chapter 14: Narrow typeslinear-chapter14

Co-authored-by: Thalia Archibald <thalia@archibald.dev>
Co-authored-by: Dibyendu Majumdar <mobile@majumdar.org.uk>
Co-authored-by: XmiliaH <45106915+XmiliaH@users.noreply.github.com>
Co-authored-by: Robert Obkircher <robert.obkircher@gmail.com>

3 files changed, 221 insertions, 0 deletions

diff --git a/docs/chapter14/14-grammar.md b/docs/chapter14/14-grammar.md
new file mode 100644
index 00000000..a6d4df42
--- /dev/null
+++ b/docs/chapter14/14-grammar.md
@@ -0,0 +1,124 @@
+# Grammar for Chapter 14
+
+```antlrv4
+grammar SimpleLanguage;
+
+program : block EOF ;
+
+block : statement+ ;
+
+
+statement
+    : '{' block '}'
+    | returnStatement
+    | ifStatement
+    | whileStatement
+    | breakStatement
+    | continueStatement
+    | metaStatement
+    | structDeclaration
+    | expressionStatement
+    ;
+
+
+returnStatement : 'return' expression ';' ;
+
+ifStatement : 'if' '(' expression ')' statement ('else' statement)? ;
+
+whileStatement : 'while' '(' expression ')' statement ;
+
+breakStatement : 'break' ';' ;
+
+continueStatement : 'continue' ';' ;
+
+metaStatement : '#showGraph' ';' ;
+
+structDeclaration : 'struct' IDENTIFIER '{' fields '}'  ;
+
+fields : field+ ;
+
+field : type IDENTIFIER ';'  ;
+
+
+expressionStatement
+    : type IDENTIFIER ';'
+    | type IDENTIFIER '=' expression ';'
+    |      IDENTIFIER '=' expression ';'
+    |                     expression
+    ;
+
+PRIMTYPE
+    : 'int'
+    | 'i8'
+    | 'i16'
+    | 'i32'
+    | 'i64'
+    | 'u8'
+    | 'u16'
+    | 'u32'
+    | 'flt'
+    | 'f32'
+    | 'f64'
+    | 'bool'
+    ;
+
+type
+    : PRIMTYPE
+    | typeName ('?')?
+    ;
+
+typeName : IDENTIFIER ;
+
+
+expression : bitWiseExpression ;
+
+bitWiseExpression
+    : comparisonExpression ( '&' | '|' | '^' ) comparisonExpression)*
+    ;
+    
+comparisonExpression
+    : shiftExpression (('==' | '!='| '>'| '<'| '>='| '<=') shiftExpression)*
+    ;
+
+shiftExpression
+    : additiveExpression ( '<<' | '>>>' | '>>' ) additiveExpression)*
+    ;
+    
+additiveExpression
+    : multiplicativeExpression (('+' | '-') multiplicativeExpression)*
+    ;
+
+multiplicativeExpression
+    : unaryExpression (('*' | '/') unaryExpression)*
+    ;
+
+unaryExpression
+    : ('-') unaryExpression
+    | '!' unaryExpression
+    | primaryExpression postFix*
+    ;
+
+primaryExpression
+    : INTEGER_LITERAL
+    | '(' expression ')'
+    | 'true'
+    | 'false'
+    | 'null'
+    | newExpression
+    | IDENTIFIER
+    ;
+
+newExpression : 'new' IDENTIFIER ;
+
+postFix : '.' IDENTIFIER [ '=' expression ] ;
+
+INTEGER_LITERAL
+    : [1-9]DIGIT*
+    | [0]
+    ;
+
+IDENTIFIER : NON_DIGIT (NON_DIGIT | DIGIT)*  ;
+
+NON_DIGIT: [a-zA-Z_];
+DIGIT: [0-9];
+```
diff --git a/docs/chapter14/Makefile b/docs/chapter14/Makefile
new file mode 100644
index 00000000..12659b8f
--- /dev/null
+++ b/docs/chapter14/Makefile
@@ -0,0 +1,12 @@
+GV := $(wildcard *.gv)
+SVG := $(patsubst %.gv,%.svg,$(GV))
+
+.PHONY: all
+all: $(SVG)
+
+%.svg: %.gv
+	dot -Tsvg $< > $@
+
+.PHONY: clean
+clean:
+	@rm -f $(SVG)
diff --git a/docs/chapter14/README.md b/docs/chapter14/README.md
new file mode 100644
index 00000000..8451c4f5
--- /dev/null
+++ b/docs/chapter14/README.md
@@ -0,0 +1,85 @@
+# Chapter 14: Narrow types
+
+In this chapter, we add sub-word integer types.
+
+You can also read [this chapter](https://github.com/SeaOfNodes/Simple/tree/linear-chapter14) in a linear Git revision history on the [linear](https://github.com/SeaOfNodes/Simple/tree/linear) branch and [compare](https://github.com/SeaOfNodes/Simple/compare/linear-chapter13...linear-chapter14) it to the previous chapter.
+
+## Narrow or sub-word types
+
+As a prelude to arrays, especially arrays of bytes common in all networking
+codes, Simple needs some way to manipulate sub-word integer types.
+Computations are always done in 64 bits for both integer and float ops, but
+will be truncated (rounded) on a variable or field assignment, and (sign)
+extended on a load.
+
+```java
+i8 x = 123456789;
+if( x != 21 ) 
+  return false;
+return true;
+```
+
+The variable `x` is limited to 8 bits signed.  Assigning the vary large value
+`123456789` (hex `0x75BCD15`) simply truncates to 8 bits yielding `21 (0x15)`.
+The value is sign-extended on a load.
+
+```java
+i16 x = 123456789;
+if( x != -13035 ) 
+  return false;
+return true;
+```
+
+The variable `x` is limited to 16 bits signed.  Assigning the vary large value
+`0x75BCD15` simply truncates to 16 bits yielding `0xCD15`.  The value is
+sign-extended on a load yielding `-13035 (0xFFFF FFFF FFFF CD15)`.
+
+```java
+u16 x = 123456789;
+if( x != 52501 ) 
+  return false;
+return true;
+```
+
+The variable `x` is limited to 16 bits unsigned.  Assigning the vary large value
+`0x75BCD15` simply truncates to 16 bits yielding `0xCD15`.  The value is
+zero-extended on a load yielding `52501 (0x0000 0000 0000 CD15)`.
+
+Similarly, floats can be limited to IEEE754 32-bit standard format and will be
+rounded when assigned, and inflated to 64-bits when loaded.
+
+The complete list of primitive types is now:
+```java
+int, i64  // 64-bits, matching modern hardware
+// u64    // NOT implemented, as it hints at some kind of >64 bit behavior
+i32, u32  // 32 bits, sign or zero extended on load
+i16, u16  // 16 bits, sign or zero extended on load
+ i8,  u8  //  8 bits, sign or zero extended on load
+ i1,  u1  //  1 bit , sign or zero extended on load
+bool      // Same as u1 
+flt, f64  // IEEE 754 64-bit float, sometimes called a "double"
+f32       // IEEE 754 32-bit float
+```
+
+
+
+## Type Implementation
+
+The TypeInteger class is reworked to support a full range of min/max values.
+At this time, only some power-of-2 sized ranges are exposed but the optimizer
+internally supports all ranges.  The MEET operation takes the min-of-mins and
+max-of-maxes.  The DUAL operation inverts the min and max.
+
+The TypeFloat class is also reworked to support 32-bit and 64-bit sizes.
+
+
+## Nodes
+
+Added this Chapter are some bit-manipulation Nodes representing common hardware
+ops to mask, shift, sign-extend and round bits.  The truncation and extension
+logic uses these.  They are otherwise very similar to the previous
+`Add/Sub/Mul/Div` Nodes but with slightly different constant math and
+slightly different `idealize()` calls.
+
+
+