.CIL File Format – Branches and switch

CIL: the Common Intermediate Language, the bytecode of .NET

Introduction

A branch transfers control to another instruction in the same method. Its operand is a signed offset, counted from the end of the branch instruction itself to the first byte of the target: a target one instruction after a 2-byte br.s has offset 0, and an offset of −2 would jump back to the br.s itself. Each branch has a short form (an opcode ending in .s with a one-byte offset, −128 to 127) and a long form (a four-byte offset); the two do exactly the same and a compiler picks the short one when the target is near enough. Tools write the target as a label, IL_0012, which is the offset of the target instruction from the start of the code in hex.

The conditional branches pop their operands, so the stack at the target is the stack after the pop. Wherever control can arrive from, the stack at an instruction must hold the same number and kinds of values. A branch must not jump into or out of a try block or a handler; the instruction that leaves one is leave. A target that is not the start of an instruction is invalid.

Exceptions and verifiability, for the whole page. None of these instructions throws. A branch whose target breaks the rules above, or whose operand types do not match, is not verifiable. ilasm also accepts brnull and brzero as other names of brfalse, and brinst for brtrue.

Unconditional and single-operand branches

OpcodeInstructionStackWhat it doesExceptions · verifiability
2B i1br.s target… → …Jumps to the target.None.
38 i4br target… → …Jumps to the target.None.
2C i1brfalse.s target…, value → …Pops a value and jumps if it is false: 0, or the null reference.None.
39 i4brfalse target…, value → …As above, long form.None.
2D i1brtrue.s target…, value → …Pops a value and jumps if it is true: not 0, or a non-null reference.None.
3A i4brtrue target…, value → …As above, long form.None.

Comparing branches

Each pops two values, a then b (b on top), compares them and jumps if the condition holds: the same as a comparison followed by brtrue. The operands are two integers of the same kind or two floats (beq and bne.un also take two object references). The .un forms compare integers as unsigned; for floats the plain forms are false and the .un forms are true when either operand is a NaN, so bne.un is the branch for “not equal” (a NaN is not equal to anything) and ble.un jumps on “not greater than”.

OpcodeInstructionStackJumps ifExceptions · verifiability
2E i1beq.s target…, a, b → …a = bNone.
3B i4beq target…, a, b → …a = bNone.
2F i1bge.s target…, a, b → …a ≥ b (signed or float)None.
3C i4bge target…, a, b → …a ≥ b (signed or float)None.
30 i1bgt.s target…, a, b → …a > b (signed or float)None.
3D i4bgt target…, a, b → …a > b (signed or float)None.
31 i1ble.s target…, a, b → …a ≤ b (signed or float)None.
3E i4ble target…, a, b → …a ≤ b (signed or float)None.
32 i1blt.s target…, a, b → …a < b (signed or float)None.
3F i4blt target…, a, b → …a < b (signed or float)None.
33 i1bne.un.s target…, a, b → …a ≠ b, or unorderedNone.
40 i4bne.un target…, a, b → …a ≠ b, or unorderedNone.
34 i1bge.un.s target…, a, b → …a ≥ b unsigned, or unorderedNone.
41 i4bge.un target…, a, b → …a ≥ b unsigned, or unorderedNone.
35 i1bgt.un.s target…, a, b → …a > b unsigned, or unorderedNone.
42 i4bgt.un target…, a, b → …a > b unsigned, or unorderedNone.
36 i1ble.un.s target…, a, b → …a ≤ b unsigned, or unorderedNone.
43 i4ble.un target…, a, b → …a ≤ b unsigned, or unorderedNone.
37 i1blt.un.s target…, a, b → …a < b unsigned, or unorderedNone.
44 i4blt.un target…, a, b → …a < b unsigned, or unorderedNone.

Switch

OpcodeInstructionStackWhat it doesExceptions · verifiability
45 u4, i4 × nswitch (t0, t1, …)…, value → …Pops an unsigned int32. If it is less than the count n, jumps to the target with that number (0-based); otherwise falls through to the next instruction. The operand is the count n and then n signed 32-bit offsets, all counted from the end of the whole instruction (4 + 4n + 1 bytes), not from their own position.None. An empty table (n = 0) is valid and always falls through.

Example: 45 03 00 00 00 0C 00 00 00 0D 00 00 00 0E 00 00 00 is a switch with three targets that start 12, 13 and 14 bytes after the end of the instruction.

Not described

Known, not yet covered

  • Stack consistency at targets: the rule is stated here, but the explorer does not simulate the stack, so it does not report a mismatch.

Unknown

  • How the runtime treats a switch operand with a huge count that runs past the end of the code (the explorer reports it as cut off).

Links

Reference