Strip dead branch code

[erkyrath]

Improved dead-code stripping! This change goes fairly deep into the code generation system. Happily, it doesn't touch too much code.

Here is a long essay about it.

Overview

The key is the execution_never_reaches_here flag. This was once a simple boolean: do we know that this line is unreachable? (The flag gets turned on after a return statement, for example.) This was used solely to print "Execution never reaches here" warnings.

(Really it had a third state: "yes, but we don't need to print a warning about it." This gets set after the first warning, and also in another case which I'll explain later.)

The new code-stripping trick goes like this: if execution_never_reaches_here is nonzero, don't generate opcodes! The assemblez_instruction() / assembleg_instruction() routines just quietly exit in this case. Or rather, they exit with a "never reaches here" warning unless we've already printed one.

compile_string() also checks this flag and skips writing strings to the string table.

I have now piled some more state into execution_never_reaches_here; enough to require named bitmask constants. The EXECSTATE_UNREACHABLE bit is set if the current line is unreachable. The EXECSTATE_NOWARN bit is set if we don't need to print a warning. The EXECSTATE_ENTIRE bit is set if the entire current statement or code block is unreachable. (This is important for better code-stripping.)

Footnote 1: If UNREACHABLE is zero, the other bits must be zero too. The constant EXECSTATE_REACHABLE is defined as (all bits) zero, but we can just test if (execution_never_reaches_here) as a shortcut.

Footnote 2: If we're between functions, execution_never_reaches_here is zero (REACHABLE). Anything defined outside a function is a global symbol, guaranteed reachable. (Forgetting this was the source of my "violence is not the answer" bug!)

In general, every time we compile a JUMP or RETURN opcode, the UNREACHABLE flag gets set. Every time we compile a label, the flag gets cleared. This makes sense if you consider a common while-true loop:

 while (true) {
   ...
   if (flag) break;
   ...
 }
 ...

This is compiled as:

 .TopLabel;
 ...
 @jnz flag ?ExitLabel;
 ...
 @jump TopLabel;
 .ExitLabel;
 ...

Code after an unconditional JUMP is obviously unreachable. But the next thing that happens is the .ExitLabel, which is the target of a branch, so the next line is reachable again.

However, we need to be a little more clever. If the unreachable flag is set when we start the while loop, then the entire loop should be unreachable, even the labels.

This is where the ENTIRE flag comes in. We set this flag when we enter an unreachable statement, or a braced block of statements; we reset it upon leaving. The ENTIRE flag prevents labels from clearing UNREACHABLE.

Backwards compatibility

This change is an optimization. It should not change the behavior of compiled code. It just makes smaller game files.

However, there are a few cases where previously-valid I6 code is now rejected. These cases look like this:

 if (DOSTUFF) {
   while (condition) {
     ...
     .MiddleLabel;
     ...
   }
 }
 jump MiddleLabel;  ! error

If DOSTUFF is defined as a constant zero, the entire while statement is considered unreachable. The .MiddleLabel in the loop is therefore not compiled. Attempting to jump to that label will be caught as a compile-time error.

This is a baroque code pattern, and I don't expect that it's ever been used in real life. However, for the sake of perfect backwards compatibility, you can give the compiler setting $STRIP_UNREACHABLE_LABELS=0. This effectively disables the ENTIRE flag. All defined labels will be jumpable, at the cost of less effective optimization.

Never-reachable warnings

The "execution never reaches here" warning is simple in principle. If assemble_instruction() skips generating code because UNREACHABLE is set, we print a warning. Then we set NOWARN so that no more warnings will be printed (for this stretch of code).

However, there are exceptions. It's pretty common to write code like:

 if (CONSTANT) {
   ...
 }

The constant may be defined true or false to enable or disable the code. The Inform library does this in a few places, for example.

We want to strip out these code blocks when appropriate. But we don't want to generate unreachability warnings. They are, by convention, "unreachable on purpose".

This makes the if-statement logic in states.c rather messy. However, the mess is confined to the if statement, and it only affects the NOWARN flag.

(A simpler version of this hack previously existed in the assemble_branch() routines. However, that was the wrong place; it messed up the warnings around certain while loops. I moved it all to the if statement.)

An exhaustive test for this logic can be found in branchprune.inf.

Code changes

The low-level set_label_offset() routine now takes offset<0 to mean that the label should be marked as unusable. Jumping to an unusable label is a compile-time error.

We keep a list of labels which have been used (as a branch target) in the current routine. This is the labeluse memlist. The mark_label_used() helper function sets this flag when a branch/jump opcode is assembled.

(We can't keep this flag in the labelinfo structure because of back-jumps, where the label is used before its labelinfo is allocated.)

Some labels are known to only be used by forward-jumps, if at all. (For example, the branches in an if statement.) When assembling these, we use the new function assemble_forward_label_no(). This checks labeluse to see whether the label has been used. If not, the label can safely be ignored (marked unusable).

(Note that named labels are never assembled this way, because they can be used by both forward and backward jumps. assemble_forward_label_no() is only used when constructing if statements, while loops, and so on.)

When making long/short decisions for branches (in transfer_routine_z() / transfer_routine_g()), we look for zero-distance branches. That is, branches which are aimed at the very next instruction. These branches are eliminated (by marking DELETED_MV over the entire opcode).

Footnote 3: Why do zero-distance branches exist at all? When we compile a forward branch, we don't always know whether the following code will be unreachable or not. If it's unreachable, no opcodes will be generated until the next label.

Footnote to the footnote: Zero-distance branches are eliminated after the assembly-trace stage. This means that if you do inform -a, you'll see a lot of this:

 27  +0003d <*> jump         L0 
 30  +00040    .L0

Disassembling the game file will show that these lines are gone.

In assemblez_1_branch(), we check for the case of @jz CONSTANT and compile either nothing or an unconditional branch. (The Glulx version of this routine already did that.)

The parse_statement_z() / parse_statement_g() routines have been refactored slightly. The code that looks for a named label (which is identical in G/Z) has been pulled out into a separate function, parse_named_label_statements(), which is now called from parse_statement().

parse_statement() and parse_code_block() now set and restore the ENTIRE flag.

In parse_statement_z() / parse_statement_g(), the IF_CODE parser (for if statements) now does a complicated dance with NOWARN. See discussion above.

In check_nonzero_at_runtime_g(), a constant argument is compiled as an unconditional branch. We set the NOWARN flag to avoid spurious warnings. (This doesn't come up in Z-code, because the check is slightly different.)

We now have the STRIP_UNREACHABLE_LABELS memory setting (defaults to 1).

Other trivial cleanup:

• The execution_never_reaches_here flag is cleared at startup and when finishing a routine. (See footnote 2, above.)
• On every non-skipped opcode, we set execution_never_reaches_here to REACHABLE or UNREACHABLE, other flags cleared. (The compiler has always done this but now it's more explicit.)
• AI.text is always cleared after use. (We don't like leaving dangling pointers to token text.)
• The assemblez_instruction() / assembleg_instruction() routines now take a const argument.