Chapter 8
Printing
A backend prints a function of a verified module as source code of its target language. The printed code does what running the function does (see Functions), over the target's own implementation of the operations: for each operation, the target gives the code of a call, given the call with its immediate operand and the printed arguments, and for each register and handle type, how the code reaches the register and which type of the target language stands for the handle type. A backend prints only the code that the function holds; it never adds a call of an operation or a decision of the parse.
SyntaxIR has two backends, Go and TypeScript. They print the compositions into each runtime (see Compositions) and the rules of a grammar, converted from the Flow stage (see Lowering From the Flow Stage), into generated parsers.
Common Rules
- The printed code is structured as the function is: a block, a loop and an
Ifprint as the corresponding statements of the target, and a block that declares locals prints in braces, so that its locals end with it. - An
Exitor aBreakof a loop prints as a break and aContinueas a continue, labeled only when the loop is not the innermost one. Labels are unique in a printed function. - Statements at an unreachable point (see Dead Stores) are not printed.
- An operator or a conversion on constants prints as its value (see Canonicalization).
- The locals that nothing reads are not declared, and the assignments that the dead-store analysis leaves out are not printed; a dead place of an assignment that stays prints as a discarded value.
- The doc of a function prints as its comment.
- An
Assertprints as a check that fails with the message "assertion failed: " followed by its message.
Go
boolisbool,intisint, andi32,u32andu64areint32,uint32anduint64, whose arithmetic wraps as Code IR's does. A handle type is the Go type that the target gives it.- A function prints as a function, or as a method of the receiver that the target gives, and a call of a function of the module goes through that receiver. A function marked no-inline prints with the directive that keeps the Go compiler from inlining it.
- A labeled block that an
Exitleaves prints its label after its statements, and theExitprints as agototo it. Agotonever skips a declaration, because every local that it could skip is inside braces that end before the label. - A
Protectprints its cleanup as a deferred function, followed by its body: since theProtectends the function, the cleanup runs as the function returns, after the values of aReturnare computed, and as the stack unwinds when an operation ends the parse. - A function with several results returns them as Go's multiple results.
TypeScript
- A function prints as a method of a class.
boolisbooleanandintisnumber, exact up to 2^53.i32andu32are numbers, normalized with| 0and>>> 0after every operation that can leave their range, and multiplied withMath.imul.u64isbigint, reduced withBigInt.asUintN. A handle type is the TypeScript type that the target gives it.- A labeled block prints as a labeled block statement and an
Exitto it as a labeledbreak. - A
Protectprints astrywith its body andfinallywith its cleanup. - A function with several results returns them as an array, except a pair of a handle type that the target packs and
bool, which is one value: the handle when theboolis true, andundefinedwhen it is false. - The rules of a grammar converted from the Flow stage print by the conventions of the TypeScript code of the runtime, so that they read as the code that the printers of the Flow stage write.
The Runtime Protocol
The printed compositions are part of the runtime of generated Go parsers, and the interface between generated code and that runtime is versioned as the runtime protocol (see Generated Parsers). A change to a printed composition that changes what generated code calls, or what a call means, changes the runtime protocol and needs a new protocol version, as any other change of that interface does.
Conformance
Three kinds of tests hold implementations to this specification.
- The conformance suite runs conformance cases, functions of Code IR that call operations, in lock-step on the reference model of the abstract machine and on an implementation under test, and fails on the first call where they differ: in its results, in which handle a result is, in whether the call ended the parse, or in units charged beyond the operation's cost bound. Cases are written by hand or generated at random within the operations' preconditions. Each case is checked against the reference model first, so a case that is wrong about a contract fails before it judges an implementation.
- The printer tests print small functions with each backend, run the printed code and compare what it does with what the reference interpreter does for the same functions.
- The value tables state what the compositions of action expressions return on the values of fixed fixtures (see Values); each target runs them through its printed compositions.
Catalog Entries
The tables of Operations, Values and Compositions declare each operation and function on one line, the header line of its listing, with the parts that the listing writes on lines of their own moved onto it.
- An operation: its kind (
op,host op,primitive oportransitional op), its name, its parameters and its results, then its features in brackets, if it has any, andnoreturn, if it may end the parse, as inop budget.charge(n u64) [budget] noreturn. The table gives the state it reads and writes, its cost bound and its contract in columns of their own. - A function:
func, its name, its parameters, its results and its features in brackets, as infunc grow(r Rule, min int) (Value, bool) [typed].
Results print bare when there is one and in parentheses when there are several. A specialization of a composition is
written as the composition's name followed by the set of features it is specialized for in brackets, as in
call [budget, document], with [] for the specialization with no feature on.