InstructionEncoder produces corrupted IL when mixing OpCode with direct CodeBuilder writes across BlobBuilder chunk boundaries

[jkoritzinsky]

Description

InstructionEncoder produces corrupted IL bodies when its CodeBuilder (BlobBuilder) crosses chunk boundaries (default 256 bytes). The corruption occurs when mixing InstructionEncoder.OpCode() with direct CodeBuilder.WriteByte() / CodeBuilder.WriteInt32() calls for instruction operands.

This is the expected usage pattern for instructions like ldarg.s where OpCode(ILOpCode.Ldarg_s) emits the opcode and CodeBuilder.WriteByte(index) emits the operand — there is no dedicated InstructionEncoder API for these operands.

Impact

Any consumer of InstructionEncoder that writes operand bytes directly to CodeBuilder (rather than using high-level APIs like Branch, LoadString, Token) will produce corrupted IL when the method body exceeds 256 bytes.

Workaround

Use new BlobBuilder(capacity) with a capacity larger than the expected IL body size to avoid multi-chunk operation:

var codeBuilder = new BlobBuilder(4096); // avoid 256-byte chunk boundary
var il = new InstructionEncoder(codeBuilder, new ControlFlowBuilder());

Reproduction

See the standalone repro in the comment below. Reproduces on .NET 9 and .NET 11.

Note

This issue was created with the assistance of Copilot.

[dotnet-policy-service]

Tagging subscribers to this area: @JulieLeeMSFT, @dotnet/jit-contrib
See info in area-owners.md if you want to be subscribed.

[jkoritzinsky]

Standalone repro

The bug reproduces with pure System.Reflection.Metadata APIs on both .NET 9 and .NET 11. The key pattern is mixing InstructionEncoder.OpCode() with direct CodeBuilder.WriteByte() calls (for operands) when the BlobBuilder has the default 256-byte chunk size and the IL body crosses a chunk boundary.

Steps

1. Save the code below as Program.cs
2. Run with dotnet run
3. Output shows corruption at ldarg.s instructions after the chunk boundary

Output

BUG: ldarg.s #29 at IL_0102: expected index 3, got 0
BUG: ldarg.s #31 at IL_0114: expected index 3, got 0
...
Corruption found in 540-byte IL body.

Repro code

using System;
using System.Reflection.Metadata;
using System.Reflection.Metadata.Ecma335;

// Repro for IL body corruption when mixing InstructionEncoder.OpCode
// with direct CodeBuilder.WriteByte across BlobBuilder chunk boundaries.
//
// This mirrors the pattern used by the managed ilasm for ldarg.s with
// named parameters: il.OpCode(ILOpCode.Ldarg_s) followed by
// codeBuilder.WriteByte(index).

var codeBuilder = new BlobBuilder(); // default 256-byte chunks
var controlFlow = new ControlFlowBuilder();
var il = new InstructionEncoder(codeBuilder, controlFlow);

var doneLabel = il.DefineLabel();

// Each block is 18 bytes:
//   il.OpCode(Ldarg_s) + codeBuilder.WriteByte(3)    = 2 bytes
//   il.OpCode(Ldarg_s) + codeBuilder.WriteByte(0)    = 2 bytes
//   il.OpCode(Ceq)                                   = 2 bytes (0xFE 0x01)
//   il.Branch(Brfalse_s, skipLabel)                   = 2 bytes
//   il.LoadString(handle)                             = 5 bytes
//   il.Branch(Br, doneLabel)                          = 5 bytes
// Total per block: 18 bytes
// 30 blocks = 540 bytes, crossing 256 and 512-byte chunk boundaries

for (int i = 0; i < 30; i++)
{
    var skipLabel = il.DefineLabel();

    // ldarg.s 3 — OpCode + direct WriteByte (the managed ilasm pattern)
    il.OpCode(ILOpCode.Ldarg_s);
    codeBuilder.WriteByte(3);

    // ldarg.s 0
    il.OpCode(ILOpCode.Ldarg_s);
    codeBuilder.WriteByte(0);

    // ceq (2-byte opcode)
    il.OpCode(ILOpCode.Ceq);

    // brfalse.s skipLabel
    il.Branch(ILOpCode.Brfalse_s, skipLabel);

    // ldstr
    il.LoadString(MetadataTokens.UserStringHandle(i + 1));

    // br doneLabel
    il.Branch(ILOpCode.Br, doneLabel);

    il.MarkLabel(skipLabel);
}

il.MarkLabel(doneLabel);
il.OpCode(ILOpCode.Ret);

// Serialize through MethodBodyStreamEncoder to trigger label patching
var ilStream = new BlobBuilder();
var bodyEncoder = new MethodBodyStreamEncoder(ilStream);
bodyEncoder.AddMethodBody(il, maxStack: 8);

// Extract IL bytes after fat header (12 bytes)
var streamBytes = ilStream.ToArray();
int headerSize = 12;
var ilBytes = streamBytes.AsSpan(headerSize, streamBytes.Length - headerSize).ToArray();

// Verify all ldarg.s instructions
int pos = 0, ldargCount = 0;
bool foundBug = false;
while (pos < ilBytes.Length - 1)
{
    if (ilBytes[pos] == 0x0E) // ldarg.s
    {
        ldargCount++;
        byte argIndex = ilBytes[pos + 1];
        int expected = (ldargCount % 2 == 1) ? 3 : 0;
        if (argIndex != expected)
        {
            Console.WriteLine($"BUG: ldarg.s #{ldargCount} at IL_{pos:X4}: expected index {expected}, got {argIndex}");
            foundBug = true;
        }
        pos += 2;
    }
    else if (ilBytes[pos] == 0xFE) pos += 2; // 2-byte opcode (ceq)
    else if (ilBytes[pos] == 0x72) pos += 5; // ldstr
    else if (ilBytes[pos] == 0x38) pos += 5; // br
    else if (ilBytes[pos] == 0x2C) pos += 2; // brfalse.s
    else pos += 1;
}

if (foundBug)
{
    Console.WriteLine($"\nCorruption found in {ilBytes.Length}-byte IL body.");
    Console.WriteLine("Root cause: mixing InstructionEncoder.OpCode with direct CodeBuilder.WriteByte");
    Console.WriteLine("across BlobBuilder chunk boundaries (default chunk size = 256 bytes).");
    Console.WriteLine("Workaround: new BlobBuilder(capacity) with capacity > expected IL size.");
    return 1;
}
else
{
    Console.WriteLine($"No corruption: {ldargCount} ldarg.s verified across {ilBytes.Length} bytes.");
    return 0;
}

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-reflection-metadata
See info in area-owners.md if you want to be subscribed.