Update broken syntax on isa_parser
Signed-off-by: Jason Lowe-Power <jason@lowepower.com>
diff --git a/_pages/documentation/general_docs/architecture_support/isa_parser.md b/_pages/documentation/general_docs/architecture_support/isa_parser.md
index e8c2337..e5456a3 100644
--- a/_pages/documentation/general_docs/architecture_support/isa_parser.md
+++ b/_pages/documentation/general_docs/architecture_support/isa_parser.md
@@ -15,17 +15,20 @@
The decode section of the description is a set of nested decode blocks. A decode block specifies a field of a machine instruction to decode and the result to be provided for particular values of that field. A decode block is similar to a C switch statement in both syntax and semantics. In fact, each decode block in the description file generates a switch statement in the resulting decode function.
Let's begin with a (slightly oversimplified) example:
-
+{% raw %}
```
decode OPCODE {
0: add({{ Rc = Ra + Rb; }});
1: sub({{ Rc = Ra - Rb; }});
}
```
+{% endraw %}
A decode block begins with the keyword `decode` followed by the name of the instruction field to decode. The latter must be defined in the declarations section of the file using a bitfield definition (see [Bitfield definitions](#bitfield-definitions)). The remainder of the decode block is a list of statements enclosed in braces. The most common statement is an integer constant and a colon followed by an instruction definition. This statement corresponds to a 'case' statement in a C switch (but note that the 'case' keyword is omitted for brevity). A comma-separated list of integer constants may be used to allow a single decode statement to apply to any of a set of bitfield values.
+{% raw %}
Instruction definitions are similar in syntax to C function calls, with the instruction mnemonic taking the place of the function name. The comma-separated arguments are used when processing the instruction definition. In the example above, the instruction definitions each take a single argument, a ''code literal''. A code literal is operationally similar to a string constant, but is delimited by double braces (`{{` and `}}`). Code literals may span multiple lines without escaping the end-of-line characters. No backslash escape processing is performed (e.g., `\t` is taken literally, and does not produce a tab). The delimiters were chosen so that C-like code contained in a code literal would be formatted nicely by emacs C-mode.
+{% endraw %}
A decode statement may specify a nested decode block in place of an instruction definition. In this case, if the bitfield specified by the outer block matches the given value(s), the bitfield specified by the inner block is examined and an additional switch is performed.
@@ -38,15 +41,19 @@
Instruction formats can be specified in two ways. An explicit format specification can be given before the mnemonic, separated by a double colon (::), as follows:
+
+{% raw %}
```
decode OPCODE {
0: Integer::add({{ Rc = Ra + Rb; }});
1: Integer::sub({{ Rc = Ra - Rb; }});
}
```
+{% endraw %}
In this example, both instruction definitions will be processed using the format Integer. A more common approach specifies the format for a set of definitions using a format block, as follows:
+{% raw %}
```
decode OPCODE {
format Integer {
@@ -55,6 +62,7 @@
}
}
```
+{% endraw %}
In this example, the format "Integer" applies to all of the instruction definitions within the inner braces. The two examples are thus functionally equivalent. There are few restrictions on the use of format blocks. A format block may include only a subset of the statements in a decode block. Format blocks and explicit format specifications may be mixed freely, with the latter taking precedence. Format and decode blocks can be nested within each other arbitrarily. Note that a closing brace will always bind with the nearest format or decode block, making it syntactically impossible to generate format or decode blocks that do not nest fully inside the enclosing block.
@@ -94,11 +102,13 @@
The syntax for defining an instruction format is as follows:
+{% raw %}
```
def format FormatName(arg1, arg2) {{
[code omitted]
}};
```
+{% endraw %}
In this example, the format is named "FormatName". (By convention, instruction format names begin with a capital letter and use mixed case.) Instruction definitions using this format will be expected to provide two arguments (`arg1` and `arg2`). The language also supports the Python variable-argument mechanism: if the final parameter begins with an asterisk (e.g., `*rest`), it receives a list of all the otherwise unbound arguments from the call site.
@@ -117,11 +127,13 @@
As discussed in section Format definitions above, the purpose of an instruction format is to process the arguments of an instruction definition and generate several pieces of C++ code. These code pieces are usually generated by specializing a code template. The description language provides a simple syntax for defining these templates: the keywords `def template`, the template name, the template body (a code literal), and a semicolon. By convention, template names start with a capital letter, use mixed case, and end with "Declare" (for declaration (header output) templates), "Decode" (for decode-block templates), "Constructor" (for decoder output templates), or "Execute" (for exec output templates).
For example, the simplest useful decode template is as follows:
+{% raw %}
```
def template BasicDecode {{
return new %(class_name)s(machInst);
}};
```
+{% endraw %}
An instruction format would specialize this template for a particular instruction by substituting the actual class name for `%(class_name)s`. (Template specialization relies on the Python string format operator `%`. The term `%(class_name)s` is an extension of the C `%s` format string indicating that the value of the symbol `class_name` should be substituted.) The resulting code would then cause the C++ decode function to create a new object of the specified class when the particular instruction was recognized.
@@ -133,11 +145,13 @@
Output blocks allow the ISA description to include C++ code that is copied nearly verbatim to the output file. These blocks are useful for defining classes and local functions that are shared among multiple instruction objects. An output block has the following format:
+{% raw %}
```
output <destination> {{
[code omitted]
}};
```
+{% endraw %}
The `<destination>` keyword must be one of `header`, `decoder`, or `exec`. The code within the code literal is treated as if it were assigned to the `header_output` `decoder_output`, or `exec_output` variable within an instruction format, respectively, including the special processing of CPU-model-specific symbols. The only additional processing performed on the code literal is substitution of bitfield operators, as used in instruction definitions (see [Bitfield operators](#bitfield-operators), and interpolation of references to templates.
@@ -202,6 +216,7 @@
The effective type of an instruction operand (e.g., a register) may be specified by appending a period and a type qualifier to the operand name. The list of type qualifiers is architecture-specific; the `def operand_types` statement in the ISA description is used to specify it. The specification is in the form of a Python dictionary which maps a type extension to type name. For example, the Alpha ISA definition is as follows:
+{% raw %}
```
def operand_types {{
'sb' : 'int8_t',
@@ -216,6 +231,7 @@
'df' : 'double'
}};
```
+{% endraw %}
Thus the Alpha 32-bit add instruction addl could be defined as:
```
@@ -239,6 +255,7 @@
For example, a simplified subset of the Alpha ISA operand traits map is as follows:
+{% raw %}
```
def operands {{
'Ra': ('IntReg', 'uq', 'RA', 'IsInteger', 1),
@@ -251,10 +268,11 @@
'NPC': ('NPC', 'uq', None, ( None, None, 'IsControl'), 4)
}};
```
+{% endraw %}
The operand named `Ra` is an integer register, default type `uq` (unsigned quadword), uses the `RA` bitfield from the instruction, implies the `IsInteger` instruction flag, and has a sort priority of 1 (placing it first in any list of operands).
-For the instrucion flag element, a single string (such as `'IsInteger'` implies an unconditionally inferred instruction flag. If the flag operand is a triple, the first element is unconditional, the second is inferred when the operand is a source, and the third when it is a destination. Thus the `('IsMemRef', 'IsLoad', 'IsStore')` element for memory references indicates that any instruction with a memory operand is marked as a memory reference. In addition, if the memory operand is a source, the instruction is marked as a load, while if the operand is a destination, the instruction is marked a store. Similarly, the `(None, None, 'IsControl')` tuple for the NPC operand indicates that any instruction that writes to the NPC is a control instruction, but instructions which merely reference NPC as a source do not receive any default flags.
+For the instruction flag element, a single string (such as `'IsInteger'` implies an unconditionally inferred instruction flag. If the flag operand is a triple, the first element is unconditional, the second is inferred when the operand is a source, and the third when it is a destination. Thus the `('IsMemRef', 'IsLoad', 'IsStore')` element for memory references indicates that any instruction with a memory operand is marked as a memory reference. In addition, if the memory operand is a source, the instruction is marked as a load, while if the operand is a destination, the instruction is marked a store. Similarly, the `(None, None, 'IsControl')` tuple for the NPC operand indicates that any instruction that writes to the NPC is a control instruction, but instructions which merely reference NPC as a source do not receive any default flags.
Note that description code parsing uses regular expressions, which limits the ability of the parser to infer the nature of a partciular operand. In particular, destination operands are distinguished from source operands solely by testing whether the operand appears on the left-hand side of an assignment operator (`=`). Destination operands that are assigned to in a different fashion, e.g. by being passed by reference to other functions, must still appear on the left-hand side of an assignment to be properly recognized as destinations. The parser also does not recognize C compound assignments, e.g., `+=`. If an operand is both a source and a destination, it must appear on both the left- and right-hand sides of `=`.
@@ -278,7 +296,7 @@
Instances of the InstObjParams class encapsulate all of the parameters needed to substitute into a code template, to be used as the argument to a template's `subst()` method (see Template definitions).
-```
+```python
class InstObjParams(object):
def __init___(self, parser,
mem, class_name, base_class = '',
