[LLVM][TableGen][Jupyter] Add first tutorial notebook

[DavidSpickett]

Summary

This first notebook covers the basics.

• classes
• defs
• basic types
• let in various forms

Everything up to multiclass, which will be the
start of the 2nd part of the tutorial.

I'd like to keep them in logical sections as
far as possible, so they are easy to digest.

[DavidSpickett]

Mucking about with this I realised multiple inheritance is a thing, so I'm going to note that here too.

(all the more reason to have exploration tools isn't it)

[DavidSpickett]

• Added section on inheritance and multiple inheritance.
• Demonstrated more of the error states.
• Added headings for easier browsing.

[DavidSpickett]

Minor wording changes and proof reading.

[DavidSpickett]

• Use default values for template arguments instead of a def inside the class.
• General wording changes.

I'm going to lock the content there until review suggestions come in.
I keep finding new language features and it'll go on forever if I keep
adding them to this.

[Eymay]

Typo fix on file name in recommended command

[DavidSpickett]

Rebase and put back the patch content.

You somehow managed to update the diff itself. Normally one would
either leave a comment on the part of the diff that is incorrect,
or upload your own patch (https://llvm.org/docs/Contributing.html#how-to-submit-a-patch)
to address it (if the code has already landed).

That said I've done my fair share of strange things with
arc and Phabricator :). Thanks for the note, I will fix the command.

If you have feedback on the tutorial you can add it as comments here.
If you click on the line numbers, it'll bring up a comment box.
Just remember to scroll down and click "Submit" to actually send the comments.

[DavidSpickett]

Fixed the readme in https://github.com/llvm/llvm-project/commit/78d91e4452d0085c929eaa7a8dddccf7b077556b.

[Eymay]

llvm/utils/TableGen/jupyter/tablegen_tutorial_part_1.ipynb

16

I get the reasoning behind %reset but there is a risk that a complete beginner may miss this sentence and think of it an integral part of TableGen.
If it could be greyed with a syntax highligher that could help. Or a different logic for clearing cache like a %global can be used. I found it was a little annoying seeing it in every cell block.

78

Embedding links could be better

155

first let can be enclosed as let

155

It is a little difficult to track, more descriptive names instead of X,Y,Z can maybe help the reader.

Another option is to keep the structure consistent with the previous code blocks so it can be more familiar.
For example, X can be repeated as:

def X: C {
	
    let b=5;
			
}

158

This sentence can be moved after the block as it is or can be merged with the previous sentence as a broad introduction to the code block's use case. The issue I had was transitioning from a code block's explanation to the other. It would be good to keep it a single paragraph to introduce each code block like it seems in the Programmer's Reference.

236

Is this let statement relevant, it can be confusing if not.

[DavidSpickett]

Address review comments.

I'll see what I can do about a configurable default for %reset or not.

llvm/utils/TableGen/jupyter/tablegen_tutorial_part_1.ipynb

16

We have conflicting use cases going on.

For a tutorial where each snippet is standalone, I agree that making %reset the default would be correct.
For a tutorial where you build up a large example by combining snippets as you go, you would want a default of %global (as you put it).
For prototyping something bit by bit, the same applies.

Most Jupyter kernels default to global cells, because they're writing to an interpreter process underneath. So I've stuck with that tradition.

We could add a magic to configure it. I think "noreset" would be a better name than "global" given how the kernel works, but you get the idea.

%cellsreset on

Then if the default is not what you want for a specific cell you can do %reset/%noreset in that one cell.
I'd argue the default for the kernel should be %reset then for these tutorials we change that to %noreset.

TLDR: Yes the line noise is annoying, I will look at adding a configurable default for it.

78

I'm taking embedding to mean linking words rather than pasting the literal link in. I've updated the links to do that.

155

I think I've improved it, you tell me :)

I made the base class not a single letter name to distinguish it from the defs. Then I changed the variable name to var so that it's distinct from the def names. Finally I rearranged it a bit so that the value of var counts up and things get more complex each time.

I'm not sure what I would rename X/Y/Z to. I thought maybe "Inner", "InnerMost" but it wouldn't really be accurate imo. Maybe you have an idea there.

158

Agreed. Moved it down to below the code.

In general I think I flipped back and forth on describing the blocks first, or after the code. I did what felt right but it may be better to pick one style and that probably is description after.

236

Good spot, this is unused. I think I left it in from an earlier draft.

[DavidSpickett]

Plan changes because this needs updating if/when configurable reset is a thing, see https://reviews.llvm.org/D149055.

[DavidSpickett]

Use the config command added in the previous patch to remove a bunch of %reset lines.

[DavidSpickett]

Small changes to text.

Removed the last part about part 2 of the tutorial. Not sure when I'll
get to that, and it would just confuse readers. Better that they go back
to the folder and look around there for more notebooks.

[DavidSpickett]

Update error output after named arguments were added to Tablegen.

Which I may add to this, but in a later patch to prevent more churn.

[DavidSpickett]

This has had some review and realistically, the only way it will get more is if/when people use it. So I'm landing this without any accepts.

llvm/utils/TableGen/jupyter/tablegen_tutorial_part_1.ipynb

+## Introduction to TableGen Part 1: Classes, Defs, Basic Types and Let
+**Note:** The content in this notebook is adapted from [this document](https://llvm.org/docs/TableGen/index.html). Refer to it if you want more details.
+This tutorial will cover:
* Classes
* Defs
* Basic types
* `let` in various forms
* Class template arguments
+## What is TableGen?
+TableGen is a language used in LLVM to automate the generation of certain types of code. Usually repetitive code that has a common structure. TableGen is used to generate "records" that are then processed by a "backend" into domain specific code.
+The compiler for TableGen is the binary `llvm-tblgen`. This contains the logic to convert TableGen source into records that can then be passed to a TableGen backend.
+TableGen allows you to define Classes and Defs (which are instances of classes) but it doesn't encode what to do with that structure. That's what the backend does. The backend converts this structure into something useful, for example C++ code.
+These backends are included in the `llvm-tblgen` binary and you can choose which one to run using a command line option. If you don't choose a backend you get a dump of the structure, and that is what this notebook will be showing.
+This tutorial will focus on the language itself only. The only thing you need to know now is that in addition to `llvm-tblgen` you will see other `*-tblgen` like `clang-tblgen`. The difference between them is the backends they include.
+The default output from `llvm-tblgen` looks like this:
+In [1]:%config cellreset on
+
+// Empty source file
+------------- Classes -----------------
------------- Defs -----------------
+**Note:** `%config` is not a TableGen command but a "magic" command to the Jupyter kernel for this notebook. By default new cells include the content of previously run cells, but for this notebook we mostly want each to be isolated. On occasion we will use the `%noreset` magic to override this.
+No source means no classes and no defs. Let's add a class.
+## Classes
+In [2]:class C {}
+------------- Classes -----------------
class C {
}
------------- Defs -----------------
+Followed by a def (definition).
+In [3]:%noreset
+
+def X: C;
+------------- Classes -----------------
class C {
}
------------- Defs -----------------
def X {	// C
}
+`def` creates an instance of a class. Typically, the main loop of a TableGen backend will look for all defs that are instances of a certain class.
+For example if I am generating register information I would look for all defs that are instances of `RegisterInfo` in the example below.
+In [4]:class RegisterInfo {}
+def X0: RegisterInfo {}
+def X1: RegisterInfo {}
+------------- Classes -----------------
class RegisterInfo {
}
------------- Defs -----------------
def X0 {	// RegisterInfo
}
def X1 {	// RegisterInfo
}
+## Inheritance
+Like many other languages with classes, a class in TableGen can inherit properties of another class.
+In [5]:class C {}
+class D : C {}
+------------- Classes -----------------
class C {
}
class D {	// C
}
------------- Defs -----------------
+Inheritance is done by putting the class you want to inherit from after `:`, before the opening `{`.
+You'll know that `D` inherits from `C` by the `// C` comment on the `class D {` line in the output.
+Not very interesting though, what are we actually inheriting? The members of the parent class.
+In [6]:class C {
+    int a;
+}
+class D : C {}
+------------- Classes -----------------
class C {
  int a = ?;
}
class D {	// C
  int a = ?;
}
------------- Defs -----------------
+Note that `D` now has the `a` member which was defined in the class `C`.
+You can inherit from multiple classes. In that case the order that that happens in matches the order you write the class names after the `:`.
+In [7]:class C {
+    int a = 1;
+}
+class D {
+    int a = 2;
+}
+class E : C, D {}
+------------- Classes -----------------
class C {
  int a = 1;
}
class D {
  int a = 2;
}
class E {	// C D
  int a = 2;
}
------------- Defs -----------------
+Class `E` first inherits from class `C`. This gives `E` a member `a` with value `1`. Then it inherits from class `D` which also has a member `a` but with a value of `2`. Meaning the final value of `E`'s `a` is `2`.
+When a member has the same name this is handled on a "last one in wins" basis. Assuming the types match.
+In [8]:class C {
+    string a = "";
+}
+class D {
+    int a = 2;
+}
+class E : C, D {}
+<stdin>:7:14: error: New definition of 'a' of type 'int' is incompatible with previous definition of type 'string'
class E : C, D {}
             ^
+When they don't match, we get an error. Luckily for us, we're about to learn all about types.
+## Types
+TableGen is statically typed with error checking to prevent you from assigning things with mismatched types.
+In [9]:class C {
+    int a;
+    bit b = 0;
+    string s = "Hello";
+}
+------------- Classes -----------------
class C {
  int a = ?;
  bit b = 0;
  string s = "Hello";
}
------------- Defs -----------------
+Here we've created a class C with integer, bit (1 or 0) and string members. See [here](https://llvm.org/docs/TableGen/ProgRef.html#types) for a full list of types.
+Note that you do not have to give a member a default value, it can be left uninitialised.
+In [10]:%noreset
+
+def X: C {}
+------------- Classes -----------------
class C {
  int a = ?;
  bit b = 0;
  string s = "Hello";
}
------------- Defs -----------------
def X {	// C
  int a = ?;
  bit b = 0;
  string s = "Hello";
}
+When you make an instance of a class using `def`, that instance gets all the members of the class. Their values will be as set in the class, unless otherwise overridden.
+In the case of `a` it also keeps the undefined value. Any backend using that definition would have to check for that case.
+In [11]:%noreset
+
+def Y {
+    int a = "abc"
+}
+<stdin>:10:13: error: Field 'a' of type 'int' is incompatible with value '"abc"' of type 'string'
    int a = "abc"
            ^
<stdin>:11:1: error: expected ';' after declaration
}
^
+Here we see the type checking in action. Member `a` has type `int` so we cannot assign a `string` to it.
+## Let
+If we want to override those member values we can use `let` ([documented here](https://llvm.org/docs/TableGen/ProgRef.html#let-override-fields-in-classes-or-records)). This can be done in a couple of ways. The first is where you mark the scope of the `let` using `in {}`.
+`let <name>=<value> in {`
+The code below says that within the `{}` after the `let`, all `a` should have the value 5.
+In [12]:class C {
+    int a = 9;
+}
+let a=5 in {
+    def X: C {}
+}
+------------- Classes -----------------
class C {
  int a = 9;
}
------------- Defs -----------------
def X {	// C
  int a = 5;
}
+For multiple names, separate them with a comma.
+In [13]:class C {
+    int a;
+    int b;
+}
+let a=5, b=6 in {
+    def X: C {}
+}
+------------- Classes -----------------
class C {
  int a = ?;
  int b = ?;
}
------------- Defs -----------------
def X {	// C
  int a = 5;
  int b = 6;
}
+You can also use `let` within a `def`. This means the scope of the `let` is the same as the scope of the `def` (the def's `{...}`).
+In [14]:class C {
+    int a = 9;
+}
+def X: C {
+    let a=5;
+}
+def Y: C {}
+------------- Classes -----------------
class C {
  int a = 9;
}
------------- Defs -----------------
def X {	// C
  int a = 5;
}
def Y {	// C
  int a = 9;
}
+Note that `Y` has `a` as `9` because the `let` was only applied to `X`.
+It is an error to try to `let` a name that hasn't been defined or to give it a value of the incorrect type.
+In [15]:class C {
+    int a = 9;
+}
+def X: C {
+    let a="Hello";
+}
+<stdin>:5:9: error: Field 'a' of type 'int' is incompatible with value '"Hello"' of type 'string'
    let a="Hello";
        ^
+Above, the member `a` was defined but with a type of `int`. We therefore cannot `let` it have a value of type `string`.
+In [16]:class C {
+    int a = 9;
+}
+def X: C {
+    let b=5;
+}
+<stdin>:5:11: error: Value 'b' unknown!
    let b=5;
          ^
+Above, class `C` only has one member, `a`. Therefore we get an error trying to override the value of `b` which doesn't exist.
+If you have multiple let, the outer scope is applied first then on down to the narrowest scope.
+In [17]:class Base {
+    int var=4;
+}
+let var=5 in {
+    def X: Base {}
+    let var=6 in {
+        def Y: Base {}
+    }
+    def Z: Base { let var=7; }
+}
+------------- Classes -----------------
class Base {
  int var = 4;
}
------------- Defs -----------------
def X {	// Base
  int var = 5;
}
def Y {	// Base
  int var = 6;
}
def Z {	// Base
  int var = 7;
}
+The first `let` is at what we call the "top level". That means the outer most scope in terms of the source code. A bit like a global variable in a C file.
+This is applied first and changes `var` from `4` to `5` for all classes within that `let` (`4` came from the definition of `Base`).
+def `X` is within the global `let`, therefore `var` is `5` within `X`.
+Then we have a `let` inside the global `let`. This one changes `var` from `5` to `6`. The scope of the `let` only contains the def `Y` therefore within `Y`, `var` is `6`.
+Finally def `Z` is within the global `let`, so `var` starts as `5`. `Z` has an inner `let` that changes `var` to `7`.
+That example is quite complex just to demonstrate the feature. Let's look at something more practical.
+In [18]:class Register {
+    int size=4;
+}
+let size=8 in {
+    def X0: Register {}
+    // Repeats 30 times for X1...X31
+}
+def W0: Register {}
+// Repeats 30 times for W1...W31
+------------- Classes -----------------
class Register {
  int size = 4;
}
------------- Defs -----------------
def W0 {	// Register
  int size = 4;
}
def X0 {	// Register
  int size = 8;
}
+(for anyone curious that's AArch64's register naming)
+The use case here is that we are describing registers. Some are 32 bits wide and some are 64 bits wide.
+We start by setting a default value of `size` which is 4 (4x8=32 bits) in the class `Register`. Then using a top level `let` we override that value and set it to 8 for all the 64 bit registers at once. So we don't need to do `size=8` over and over again.
+## Classes As Class Members
+In addition to the built in types, class members can be user defined classes.
+In [19]:class Inner {}
+class Outer {
+    Inner i;
+}
+------------- Classes -----------------
class Inner {
}
class Outer {
  Inner i = ?;
}
------------- Defs -----------------
+Of course that raises the question, how do we construct an instance of `Inner` to use as the value?
+We simply use a `def` like we have done before.
+In [20]:class Inner {}
+def AnInner: Inner {}
+class Outer {
+    Inner i = AnInner;
+}
+def AnOuter: Outer {}
+------------- Classes -----------------
class Inner {
}
class Outer {
  Inner i = AnInner;
}
------------- Defs -----------------
def AnInner {	// Inner
}
def AnOuter {	// Outer
  Inner i = AnInner;
}
+## Class Template Arguments
+Class template arguments are used to pass parameters to classes when you `def` them.
+In [21]:class C <int a, int b> {
+    int c = a;
+    int d = b;
+}
+def X: C<0, 1> {}
+------------- Classes -----------------
class C<int C:a = ?, int C:b = ?> {
  int c = C:a;
  int d = C:b;
}
------------- Defs -----------------
def X {	// C
  int c = 0;
  int d = 1;
}
+This means that to `def` a `C` we must now provide 2 arguments that have type `int` (type checking applies here as it does elsewhere).
+This is going to look familiar if you have written C++. In C++ it might look like:
```
template<int a, int b>
class C {
    int c = a;
    int d = b;
};
C<0, 1> X;
```
+If templates aren't your thing, another way to think of them is as parameters to the constructor of a class. 
+For instance Python code might look like this:
```
class C(object):
    def __init__(self, a, b):
        self.c = a
        self.d = b
+print(C(0, 1).c)
# prints "0"
```
+In [22]:class C <int a, int b> {
+    int c = a;
+    int d = b;
+}
+def X: C<0> {}
+<stdin>:5:8: error: value not specified for template argument 'C:b'
def X: C<0> {}
       ^
<stdin>:1:21: note: declared in 'C'
class C <int a, int b> {
                    ^
+When not enough arguments are provided, you get an error.
+Below is what happens when one of those arguments is of the wrong type.
+In [23]:class C <int a, int b> {
+    int c = a;
+    int d = b;
+}
+def X: C<0, "hello"> {}
+<stdin>:5:8: error: Value specified for template argument 'C:b' is of type string; expected type int: "hello"
def X: C<0, "hello"> {}
       ^
+You can also provide default values for template arguments.
+In [24]:class C <int a=10> {
+    int b = a;
+}
+def X: C<> {}
+------------- Classes -----------------
class C<int C:a = 10> {
  int b = C:a;
}
------------- Defs -----------------
def X {	// C
  int b = 10;
}
+Using class template arguments you can enforce a structure on the user of the classes. In our previous register example I could use this to require the the user pass a value for the size.
+The code below makes the size argument mandatory but the alias optional.
+In [25]:class Register<int _size, string _alias=""> {
+    int size = _size;
+    string alias = _alias;
+}
+def X0: Register<8> {}
+def X29: Register<8, "frame pointer"> {}
+------------- Classes -----------------
class Register<int Register:_size = ?, string Register:_alias = ""> {
  int size = Register:_size;
  string alias = Register:_alias;
}
------------- Defs -----------------
def X0 {	// Register
  int size = 8;
  string alias = "";
}
def X29 {	// Register
  int size = 8;
  string alias = "frame pointer";
}
+**Note:** You can't reuse the name between the template argument and the class member.
Here I have added `_` to the template argument but there's no required style.
+For `X0` we don't pass an alias so we get the default of `""`, which would mean there is no alias.
+For `X29` we've passed a value for the alias, which overrides the default value.
+In C++, the equivalent would be:
```
// Constructor for class Register
Register(int size, const char* alias=nullptr) :
```
+Or in Python:
```
def __init__(self, size, alias=""):
```

llvm/utils/TableGen/jupyter/tablegen_tutorial_part_1.md

+## Introduction to TableGen Part 1: Classes, Defs, Basic Types and Let
+
+**Note:** The content in this notebook is adapted from [this document](https://llvm.org/docs/TableGen/index.html). Refer to it if you want more details.
+
+This tutorial will cover:
+* Classes
+* Defs
+* Basic types
+* `let` in various forms
+* Class template arguments
+
+## What is TableGen?
+
+TableGen is a language used in LLVM to automate the generation of certain types of code. Usually repetitive code that has a common structure. TableGen is used to generate "records" that are then processed by a "backend" into domain specific code.
+
+The compiler for TableGen is the binary `llvm-tblgen`. This contains the logic to convert TableGen source into records that can then be passed to a TableGen backend.
+
+TableGen allows you to define Classes and Defs (which are instances of classes) but it doesn't encode what to do with that structure. That's what the backend does. The backend converts this structure into something useful, for example C++ code.
+
+These backends are included in the `llvm-tblgen` binary and you can choose which one to run using a command line option. If you don't choose a backend you get a dump of the structure, and that is what this notebook will be showing.
+
+This tutorial will focus on the language itself only. The only thing you need to know now is that in addition to `llvm-tblgen` you will see other `*-tblgen` like `clang-tblgen`. The difference between them is the backends they include.
+
+The default output from `llvm-tblgen` looks like this:
+
+
+```tablegen
+%config cellreset on
+
+// Empty source file
+```
+
+    ------------- Classes -----------------
+    ------------- Defs -----------------
+
+
+**Note:** `%config` is not a TableGen command but a "magic" command to the Jupyter kernel for this notebook. By default new cells include the content of previously run cells, but for this notebook we mostly want each to be isolated. On occasion we will use the `%noreset` magic to override this.
+
+No source means no classes and no defs. Let's add a class.
+
+## Classes
+
+
+```tablegen
+class C {}
+```
+
+    ------------- Classes -----------------
+    class C {
+    }
+    ------------- Defs -----------------
+
+
+Followed by a def (definition).
+
+
+```tablegen
+%noreset
+
+def X: C;
+```
+
+    ------------- Classes -----------------
+    class C {
+    }
+    ------------- Defs -----------------
+    def X { // C
+    }
+
+
+`def` creates an instance of a class. Typically, the main loop of a TableGen backend will look for all defs that are instances of a certain class.
+
+For example if I am generating register information I would look for all defs that are instances of `RegisterInfo` in the example below.
+
+
+```tablegen
+class RegisterInfo {}
+def X0: RegisterInfo {}
+def X1: RegisterInfo {}
+```
+
+    ------------- Classes -----------------
+    class RegisterInfo {
+    }
+    ------------- Defs -----------------
+    def X0 {  // RegisterInfo
+    }
+    def X1 {  // RegisterInfo
+    }
+
+
+## Inheritance
+
+Like many other languages with classes, a class in TableGen can inherit properties of another class.
+
+
+```tablegen
+class C {}
+class D : C {}
+```
+
+    ------------- Classes -----------------
+    class C {
+    }
+    class D { // C
+    }
+    ------------- Defs -----------------
+
+
+Inheritance is done by putting the class you want to inherit from after `:`, before the opening `{`.
+
+You'll know that `D` inherits from `C` by the `// C` comment on the `class D {` line in the output.
+
+Not very interesting though, what are we actually inheriting? The members of the parent class.
+
+
+```tablegen
+class C {
+    int a;
+}
+class D : C {}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = ?;
+    }
+    class D { // C
+      int a = ?;
+    }
+    ------------- Defs -----------------
+
+
+Note that `D` now has the `a` member which was defined in the class `C`.
+
+You can inherit from multiple classes. In that case the order that that happens in matches the order you write the class names after the `:`.
+
+
+```tablegen
+class C {
+    int a = 1;
+}
+class D {
+    int a = 2;
+}
+class E : C, D {}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = 1;
+    }
+    class D {
+      int a = 2;
+    }
+    class E { // C D
+      int a = 2;
+    }
+    ------------- Defs -----------------
+
+
+Class `E` first inherits from class `C`. This gives `E` a member `a` with value `1`. Then it inherits from class `D` which also has a member `a` but with a value of `2`. Meaning the final value of `E`'s `a` is `2`.
+
+When a member has the same name this is handled on a "last one in wins" basis. Assuming the types match.
+
+
+```tablegen
+class C {
+    string a = "";
+}
+class D {
+    int a = 2;
+}
+class E : C, D {}
+```
+
+    <stdin>:7:14: error: New definition of 'a' of type 'int' is incompatible with previous definition of type 'string'
+    class E : C, D {}
+                 ^
+
+
+When they don't match, we get an error. Luckily for us, we're about to learn all about types.
+
+## Types
+
+TableGen is statically typed with error checking to prevent you from assigning things with mismatched types.
+
+
+```tablegen
+class C {
+    int a;
+    bit b = 0;
+    string s = "Hello";
+}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = ?;
+      bit b = 0;
+      string s = "Hello";
+    }
+    ------------- Defs -----------------
+
+
+Here we've created a class C with integer, bit (1 or 0) and string members. See [here](https://llvm.org/docs/TableGen/ProgRef.html#types) for a full list of types.
+
+Note that you do not have to give a member a default value, it can be left uninitialised.
+
+
+```tablegen
+%noreset
+
+def X: C {}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = ?;
+      bit b = 0;
+      string s = "Hello";
+    }
+    ------------- Defs -----------------
+    def X { // C
+      int a = ?;
+      bit b = 0;
+      string s = "Hello";
+    }
+
+
+When you make an instance of a class using `def`, that instance gets all the members of the class. Their values will be as set in the class, unless otherwise overridden.
+
+In the case of `a` it also keeps the undefined value. Any backend using that definition would have to check for that case.
+
+
+```tablegen
+%noreset
+
+def Y {
+    int a = "abc"
+}
+```
+
+    <stdin>:10:13: error: Field 'a' of type 'int' is incompatible with value '"abc"' of type 'string'
+        int a = "abc"
+                ^
+    <stdin>:11:1: error: expected ';' after declaration
+    }
+    ^
+
+
+Here we see the type checking in action. Member `a` has type `int` so we cannot assign a `string` to it.
+
+## Let
+
+If we want to override those member values we can use `let` ([documented here](https://llvm.org/docs/TableGen/ProgRef.html#let-override-fields-in-classes-or-records)). This can be done in a couple of ways. The first is where you mark the scope of the `let` using `in {}`.
+
+`let <name>=<value> in {`
+
+The code below says that within the `{}` after the `let`, all `a` should have the value 5.
+
+
+```tablegen
+class C {
+    int a = 9;
+}
+let a=5 in {
+    def X: C {}
+}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = 9;
+    }
+    ------------- Defs -----------------
+    def X { // C
+      int a = 5;
+    }
+
+
+For multiple names, separate them with a comma.
+
+
+```tablegen
+class C {
+    int a;
+    int b;
+}
+let a=5, b=6 in {
+    def X: C {}
+}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = ?;
+      int b = ?;
+    }
+    ------------- Defs -----------------
+    def X { // C
+      int a = 5;
+      int b = 6;
+    }
+
+
+You can also use `let` within a `def`. This means the scope of the `let` is the same as the scope of the `def` (the def's `{...}`).
+
+
+```tablegen
+class C {
+    int a = 9;
+}
+def X: C {
+    let a=5;
+}
+def Y: C {}
+```
+
+    ------------- Classes -----------------
+    class C {
+      int a = 9;
+    }
+    ------------- Defs -----------------
+    def X { // C
+      int a = 5;
+    }
+    def Y { // C
+      int a = 9;
+    }
+
+
+Note that `Y` has `a` as `9` because the `let` was only applied to `X`.
+
+It is an error to try to `let` a name that hasn't been defined or to give it a value of the incorrect type.
+
+
+```tablegen
+class C {
+    int a = 9;
+}
+def X: C {
+    let a="Hello";
+}
+```
+
+    <stdin>:5:9: error: Field 'a' of type 'int' is incompatible with value '"Hello"' of type 'string'
+        let a="Hello";
+            ^
+
+
+Above, the member `a` was defined but with a type of `int`. We therefore cannot `let` it have a value of type `string`.
+
+
+```tablegen
+class C {
+    int a = 9;
+}
+def X: C {
+    let b=5;
+}
+```
+
+    <stdin>:5:11: error: Value 'b' unknown!
+        let b=5;
+              ^
+
+
+Above, class `C` only has one member, `a`. Therefore we get an error trying to override the value of `b` which doesn't exist.
+
+If you have multiple let, the outer scope is applied first then on down to the narrowest scope.
+
+
+```tablegen
+class Base {
+    int var=4;
+}
+let var=5 in {
+    def X: Base {}
+    let var=6 in {
+        def Y: Base {}
+    }
+    def Z: Base { let var=7; }
+}
+```
+
+    ------------- Classes -----------------
+    class Base {
+      int var = 4;
+    }
+    ------------- Defs -----------------
+    def X { // Base
+      int var = 5;
+    }
+    def Y { // Base
+      int var = 6;
+    }
+    def Z { // Base
+      int var = 7;
+    }
+
+
+The first `let` is at what we call the "top level". That means the outer most scope in terms of the source code. A bit like a global variable in a C file.
+
+This is applied first and changes `var` from `4` to `5` for all classes within that `let` (`4` came from the definition of `Base`).
+
+def `X` is within the global `let`, therefore `var` is `5` within `X`.
+
+Then we have a `let` inside the global `let`. This one changes `var` from `5` to `6`. The scope of the `let` only contains the def `Y` therefore within `Y`, `var` is `6`.
+
+Finally def `Z` is within the global `let`, so `var` starts as `5`. `Z` has an inner `let` that changes `var` to `7`.
+
+That example is quite complex just to demonstrate the feature. Let's look at something more practical.
+
+
+```tablegen
+class Register {
+    int size=4;
+}
+let size=8 in {
+    def X0: Register {}
+    // Repeats 30 times for X1...X31
+}
+def W0: Register {}
+// Repeats 30 times for W1...W31
+```
+
+    ------------- Classes -----------------
+    class Register {
+      int size = 4;
+    }
+    ------------- Defs -----------------
+    def W0 {  // Register
+      int size = 4;
+    }
+    def X0 {  // Register
+      int size = 8;
+    }
+
+
+(for anyone curious that's AArch64's register naming)
+
+The use case here is that we are describing registers. Some are 32 bits wide and some are 64 bits wide.
+
+We start by setting a default value of `size` which is 4 (4x8=32 bits) in the class `Register`. Then using a top level `let` we override that value and set it to 8 for all the 64 bit registers at once. So we don't need to do `size=8` over and over again.
+
+## Classes As Class Members
+
+In addition to the built in types, class members can be user defined classes.
+
+
+```tablegen
+class Inner {}
+class Outer {
+    Inner i;
+}
+```
+
+    ------------- Classes -----------------
+    class Inner {
+    }
+    class Outer {
+      Inner i = ?;
+    }
+    ------------- Defs -----------------
+
+
+Of course that raises the question, how do we construct an instance of `Inner` to use as the value?
+
+We simply use a `def` like we have done before.
+
+
+```tablegen
+class Inner {}
+def AnInner: Inner {}
+class Outer {
+    Inner i = AnInner;
+}
+def AnOuter: Outer {}
+```
+
+    ------------- Classes -----------------
+    class Inner {
+    }
+    class Outer {
+      Inner i = AnInner;
+    }
+    ------------- Defs -----------------
+    def AnInner { // Inner
+    }
+    def AnOuter { // Outer
+      Inner i = AnInner;
+    }
+
+
+## Class Template Arguments
+
+Class template arguments are used to pass parameters to classes when you `def` them.
+
+
+```tablegen
+class C <int a, int b> {
+    int c = a;
+    int d = b;
+}
+def X: C<0, 1> {}
+```
+
+    ------------- Classes -----------------
+    class C<int C:a = ?, int C:b = ?> {
+      int c = C:a;
+      int d = C:b;
+    }
+    ------------- Defs -----------------
+    def X { // C
+      int c = 0;
+      int d = 1;
+    }
+
+
+This means that to `def` a `C` we must now provide 2 arguments that have type `int` (type checking applies here as it does elsewhere).
+
+This is going to look familiar if you have written C++. In C++ it might look like:
+```
+template<int a, int b>
+class C {
+    int c = a;
+    int d = b;
+};
+C<0, 1> X;
+```
+
+If templates aren't your thing, another way to think of them is as parameters to the constructor of a class. 
+
+For instance Python code might look like this:
+```
+class C(object):
+    def __init__(self, a, b):
+        self.c = a
+        self.d = b
+
+print(C(0, 1).c)
+# prints "0"
+```
+
+
+```tablegen
+class C <int a, int b> {
+    int c = a;
+    int d = b;
+}
+def X: C<0> {}
+```
+
+    <stdin>:5:8: error: value not specified for template argument 'C:b'
+    def X: C<0> {}
+           ^
+    <stdin>:1:21: note: declared in 'C'
+    class C <int a, int b> {
+                        ^
+
+
+When not enough arguments are provided, you get an error.
+
+Below is what happens when one of those arguments is of the wrong type.
+
+
+```tablegen
+class C <int a, int b> {
+    int c = a;
+    int d = b;
+}
+def X: C<0, "hello"> {}
+```
+
+    <stdin>:5:8: error: Value specified for template argument 'C:b' is of type string; expected type int: "hello"
+    def X: C<0, "hello"> {}
+           ^
+
+
+You can also provide default values for template arguments.
+
+
+```tablegen
+class C <int a=10> {
+    int b = a;
+}
+def X: C<> {}
+```
+
+    ------------- Classes -----------------
+    class C<int C:a = 10> {
+      int b = C:a;
+    }
+    ------------- Defs -----------------
+    def X { // C
+      int b = 10;
+    }
+
+
+Using class template arguments you can enforce a structure on the user of the classes. In our previous register example I could use this to require the the user pass a value for the size.
+
+The code below makes the size argument mandatory but the alias optional.
+
+
+```tablegen
+class Register<int _size, string _alias=""> {
+    int size = _size;
+    string alias = _alias;
+}
+def X0: Register<8> {}
+def X29: Register<8, "frame pointer"> {}
+```
+
+    ------------- Classes -----------------
+    class Register<int Register:_size = ?, string Register:_alias = ""> {
+      int size = Register:_size;
+      string alias = Register:_alias;
+    }
+    ------------- Defs -----------------
+    def X0 {  // Register
+      int size = 8;
+      string alias = "";
+    }
+    def X29 { // Register
+      int size = 8;
+      string alias = "frame pointer";
+    }
+
+
+**Note:** You can't reuse the name between the template argument and the class member.
+Here I have added `_` to the template argument but there's no required style.
+
+For `X0` we don't pass an alias so we get the default of `""`, which would mean there is no alias.
+
+For `X29` we've passed a value for the alias, which overrides the default value.
+
+In C++, the equivalent would be:
+```
+// Constructor for class Register
+Register(int size, const char* alias=nullptr) :
+```
+
+Or in Python:
+```
+def __init__(self, size, alias=""):
+```