instabrew / brewer.py: the *OpGen Contract

All symbols, addresses, and brewer.py:<line> references on this page apply to neuronx_cc 2.24.5133.0+58f8de22 (cp310). The C++ artifacts live in neuronxcc/starfish/lib/libBIR.so; the Python artifacts under neuronxcc/starfish/penguin/targets/generated/*.cpython-310-*.so and neuronxcc/starfish/birpy/InstructionOpcodes.cpython-310-*.so. The cp311/cp312 mirrors carry byte-identical brewer.py line numbers (only the .rodata VA of the path string drifts); treat every VA as version-pinned.

Abstract

Every BIR instruction in neuronx_cc exists twice: once as a Python <Op>OpGen Cython class the penguin front-end instantiates, and once as a C++ bir::Inst<Op> class the back-end (libwalrus.so) consumes. The two are not written by hand and kept in sync — they are two projections of one ISA datamodel spec, emitted by a single code generator, neuronxcc/instabrew/brewer.py. This is the mechanism that makes the Python-emitted BIR and the C++-parsed BIR agree on field names, key order, and enum spellings: there is exactly one source of truth, and both languages are generated from it. This page documents the generator's input→output contract and the five emitter regions whose fingerprints survive in the binary.

The decisive constraint on this page is a provenance one, and it is featured up front as a gotcha: brewer.py is not shipped in the wheel. The neuronxcc/instabrew/ package (brewer.py + main.py) is a build-time generator that runs inside Amazon's native build (/opt/workspace/KaenaCompilerNativeBuild-310/...) and is dropped before packaging — an exhaustive fd over the extracted wheel for instabrew, brewer.py, or main.py returns nothing. Only its outputs ship. Consequently, the generator's internal structure here is reconstructed from its outputs plus the breadcrumbs that survive compilation, never read from a .py. Two breadcrumb kinds make this possible: (A) C++ assert() macros whose __FILE__ preprocessor-expands to brewer.py and __LINE__ to the generator source line — recoverable as the mov edx,<imm> argument to __assert_fail; and (B) the Python "Generated by brewer from the definition in neuronxcc/instabrew/<gen>.py at line N" docstring baked into every generated module. The generated *Gen bodies are CONFIRMED-citeable (they are in libBIR.so); the generator's logic is INFERRED-from-output.

The single-spec→two-output thesis is then proved three independent ways: by provenance (the same brewer.py path string is the __FILE__ of generated C++ asserts in libBIR/libwalrus/libBIRSimulator and the docstring of the Python *OpGen.so), by wire-key parity (the C++ toJson/readFieldsFromJson key set equals the Python birpy key set for Activation and Matmul), and by output diffing (every *Gen shares a fixed skeleton, with only the spec's param list varying). Compare Dtype Tables and AluOpType + the Mode Enums for the enum-domain side of the contract, and The bir::Instruction Base Struct / InstructionType for the C++ class hierarchy the generator emits into.

For reimplementation, the contract is:

• The generator I/O: one ISAInstructionInfo spec (api_name, params:[ISAInstructionParam], default_engine, perf_est, constraints) → one Python <Op>OpGen(NeuronInst) class and one C++ bir::Inst<Op> : bir::Instruction class.
• The five emitter regions (brewer.py line ranges), each producing one generated construct — the spec-absent fall-through arm of each is a brewer.py-lined assert(), which is how the line map is recovered.
• The *Gen contract surface: __init__/serialize/verify/operands/replaceUseOfWith (Python) ≡ ctor/toJson/readFieldsFromJson/createFromJson/sameInst/getLatency* (C++), plus per-param get<X> accessors driven 1:1 by the spec param list.
• The five guarantees (G1–G5) the single-spec generation structurally enforces: wire-key identity, round-trip symmetry, enum-domain identity, structural-eq consistency, perf/engine binding.

Provenance: What Is and Is Not in the Wheel

GOTCHA — the generator is reconstructed, not read. brewer.py and the whole neuronxcc/instabrew/ package are absent from the shipped wheel (fd -t f 'brewer.py$' --no-ignore over the cp310 tree returns nothing; no instabrew directory exists). Every statement below about brewer's internal line structure or emission logic is INFERRED from its outputs. Every statement about a generated *Gen body, symbol, address, or string is CONFIRMED in libBIR.so / the *OpGen.so modules. Do not conflate the two: the C++ assert(false && "Not Implemented") at 0x2dcca9 is CONFIRMED; the claim that brewer.py line 1327 is the no-eq fall-through emitter is the breadcrumb-driven reconstruction.

The reconstruction rests on two compilation-surviving breadcrumbs.

(A) The C++ __assert_fail __FILE__/__LINE__ pair. When brewer emits a C++ assert() into a generated translation unit, the C preprocessor expands __FILE__ to the generator's path and __LINE__ to the brewer source line. In the glibc ABI __assert_fail(expr, file, line, func), the file pointer is in RSI and the line is the edx immediate. The path string is CONFIRMED at .rodata VA 0x7208d0:

/opt/workspace/KaenaCompilerNativeBuild-310/build/private/src-3.10.16/
    neuronxcc/instabrew/brewer.py

It is loaded into RSI immediately before call __assert_fail@plt at every generated-assert site; the companion edx immediate is the brewer.py line. Verified directly — the getDmaBlock bounds check at 0x26209a loads edx,0x58d (= 1421) right before the assert call, and the three contiguous sameInst stubs at 0x2dcc6b/0x2dcc8a/0x2dcca9 load edx = 0x539/0x70c/0x52f (= 1337/1804/1327):

26209a:  ba 8d 05 00 00    mov    edx,0x58d          ; brewer.py:1421 (getDmaBlock)
2620..:  ...               call   __assert_fail@plt
2dcc6b:  ba 39 05 00 00    mov    edx,0x539          ; brewer.py:1337 (InstNKIKLIRKernel::sameInst)
2dcc8a:  ba 0c 07 00 00    mov    edx,0x70c          ; brewer.py:1804 (InstCall::sameInst)
2dcca9:  ba 2f 05 00 00    mov    edx,0x52f          ; brewer.py:1327 (InstNKIKernel::sameInst)

(B) The Python provenance docstring. Every generated Python module carries a verbatim docstring naming its emitter and line. CONFIRMED in ActivationOpGen.cpython-310-*.so:

  Generated by brewer from the definition in neuronxcc/instabrew/brewer.py at line 3384

and in MatMulOpGen.cpython-310-*.so:

  Generated by brewer from the definition in neuronxcc/instabrew/main.py at line 363

NOTE — cross-binary, single-generator. The same brewer.py:1421 line appears in all three C++ libraries (1 site in libBIR, 3 in libBIRSimulator, 16 inlined in libwalrus), and the instabrew/brewer.py path string is present (strings | rg -c) once in each of libBIR, libwalrus, and libBIRSimulator. One generator drove three independently-linked libraries. The brewer.py line numbers are byte-identical across cp310/cp311/cp312 (the C++ source is ABI-independent; it was generated once, then compiled once per Python ABI) — the strongest single-source proof.

The Single-Spec → Two-Output Contract

Purpose

brewer is a multi-target emitter. It reads one ISAInstructionInfo @datamodel spec per op and emits two classes — a Python Cython <Op>OpGen and a C++ bir::Inst<Op> — that are guaranteed field-, key-, and enum-consistent because they are projections of the same param list. This is the structural alternative to maintaining two hand-written serializers and praying they never drift.

Entry Point

[SPEC]  neuronxcc/include/isa/<op>_info.so   (ISAInstructionInfo @datamodel)
          api_name, params:[ISAInstructionParam], default_engine,
          perf_est:Optional, traits, constraints
              │
              ▼
[GEN]   neuronxcc/instabrew/  (NOT shipped — INFERRED)
          main.py:<N>      ── registers op / op-family (factory call site)
          brewer.py:3384   ── generic per-op class-body emitter
          brewer.py:1327.. ── deeper method-emitter sub-routines (R1..R5)
              │
        ┌─────┴───────────────────────────────────┐
        ▼                                          ▼
[PY]  <Op>OpGen.cpython-310.so              [C++] bir::Inst<Op>  (libBIR.so)
      class <Op>OpGen(NeuronInst)                 : bir::Instruction
      __init__/serialize/verify/operands/         ctor/toJson/readFieldsFromJson/
      replaceUseOfWith + spec accessors           createFromJson/sameInst/getLatency*
              │                                          │
              └──────────► same wire keys ◄──────────────┘
                    (round-trip-safe BIR JSON)

Algorithm

The generator body is not in the wheel; the following is the INFERRED-from-output template every *Gen exhibits. It is annotated with the CONFIRMED output evidence each line produces.

// INFERRED brewer per-op emission (reconstructed from uniform output shape).
function brewer_emit_op(spec):                  // spec = ISAInstructionInfo
    emit_class("<Op>OpGen", base="NeuronInst")  // CONFIRMED: ActivationOpGen(NeuronInst)
    emit_class("bir::Inst<Op>", base="bir::Instruction")  // CONFIRMED: nm -DC, 121 classes

    // --- INVARIANT skeleton (every op, no spec dependence) ---
    emit __init__/ctor                          // assigns fields, links operands
    emit serialize / toJson                      // CONFIRMED key set (see parity)
    emit verify                                  // thin: structural checks + delegate
    emit operands, replaceUseOfWith / clone

    // --- SPEC-DRIVEN payload (one statement per spec param) ---
    for p in spec.params:
        if p.is_tensor:
            emit get<P>()                        // operand accessor
            if p.indirectable:
                emit get<P>Offsets()             // brewer.py:1624 (non-const)
                emit get<P>Offsets() const       // brewer.py:1638 (const, +14 lines)
                // fall-through assert:
                //   false && "<P>Offsets in Inst<Op> does not have an indirection tensor"
        elif p.is_field_enum:
            register_enum(p.enum)                // -> R5: <Enum>2string / string2<Enum>
        emit serialize_field(p)                  // recurse: p.serialize() | number | 'none'

    // --- mode arms keyed on optional spec sections ---
    if spec.has_structural_eq: emit sameInst(field-compare)   // 17 C++ overrides
    else:                      emit sameInst(assert false&&"Not Implemented") // R1
    if spec.perf_est: emit getLatency*(real model)            // 32/121 override
    else:             emit getLatency*(assert "Unimplemented") // R4: 1922-2007

The Invariant vs Spec-Driven Partition

Diffing five Python *OpGen modules (ActivationOpGen, MatMulOpBaseGen, ReciprocalOpGen, MemsetOpGen, TensorReduceOpGen) and three C++ classes (InstActivation, InstReciprocal, InstMemset) isolates the fixed skeleton from the per-op payload. The partition is the brewer template, seen by set-difference (CONFIRMED via string-pool / nm -DC diff):

QUIRK — the OpGen / public-op split is two brewer products, not a parent→child chain. Activation.so's string pool does not contain "ActivationOpGen"; both Activation (from main.py:165) and ActivationOpGen (from brewer.py:3384) ImportFrom the same bare NeuronInst base. They are siblings — two emissions over the same spec from two generator entry points — not a strict inheritance chain through the OpGen name. The C++ side folds both into one bir::Inst<Op> translation unit, splitting only where a shared base is genuinely needed (InstMatmult : InstMatmultBase : bir::Instruction, mirroring Python MatMul : MatMulOpBase : NeuronInst).

The Five Emitter Regions

The 153 brewer.py:<line> assert sites in libBIR.so cluster into five contiguous line ranges, each guarding one kind of generated method. Because each assert is the spec-absent fall-through arm of an emitter sub-routine, the line map reads as a catalogue of brewer's emitters. Every line below is CONFIRMED (it is the mov edx,<imm> argument of a real __assert_fail call); the interpretation of each line as a specific emitter is STRONG (reconstructed from the host method's nm-resolved signature + the assert expr).

R1 — sameInst "Not Implemented" Fall-Throughs

Three opcodes declare no structural equality, so brewer emits a sameInst whose entire body is assert(false && "Not Implemented"): InstNKIKernel (1327), InstNKIKLIRKernel (1337), InstCall (1804). The three are contiguous in .text (0x2dcc70..0x2dccbc). This is brewer's default "no-eq" arm: CSE / dedup over kernel-call opcodes is unsupported by design. The line gap (1327→1337 = 10 lines, then 1337→1804 = 467 lines) reflects emission order in brewer's per-op loop — NKIKernel/NKIKLIRKernel are adjacent spec entries, Call is far later. (See InstructionType for the full 110-arm sameInst family.)

R2 — getDmaBlock Container Accessor

The generated bir::InstDMATrigger::getDmaBlock(uint32_t id) const indexes the DmaBlocks vector with assert(id < DmaBlocks.size()) at brewer.py:1421, then returns DmaBlocks[id]. This is brewer's indexed-child accessor emitter (a container field fetched by id with a bounds assert). The cross-binary identity of line 1421 — same line in libBIRSimulator (3×) and inlined into 16 libwalrus call sites — is the cleanest single-generator proof.

R3 — Per-Tensor Offsets Accessors

For each indirectable tensor param, brewer emits a pair: get<P>Offsets() at brewer.py:1624 and a const overload at brewer.py:1638 (a fixed 14-line gap). Verified directly: objdump | rg -c 'mov edx,0x658' = 33 and 'mov edx,0x666' = 33 (0x658 = 1624, 0x666 = 1638) — the 66 sites. The fall-through fires when the named tensor has no indirection tensor; the assert string is name-substituted, CONFIRMED verbatim:

false && "IfmapOffsets in InstActivation does not have an indirection tensor"
false && "WeightsOffsets in InstMatmult does not have an indirection tensor"

The accessor body calls get<P>(), reads the argument's indirection-kind dword (cmp 0x1/0x2), and either tail-calls Instruction::getIndirectArgumentById(...) or falls through to the assert. The param name is the only spec-driven variation in this sub-template; 15 distinct bir::Inst* classes (the ops with indirectable tensor operands) carry these accessor pairs.

R4 — Perf-Model Stubs

When an op's spec carries no ISAPerformanceEstimation, brewer emits getLatency() / getLatencyExec() / getLatencyReadInit() / getLatencyWriteDrain() as assert("Unimplemented") stubs, and getDefaultEngine() as assert("No engine assignment for arch") when there is no default_engine. The four latency methods occupy four adjacent line-bands (ReadInit ~1951–1956, Exec ~1965–1975, WriteDrain ~1979–1992, Latency ~1991–2007) — brewer emits the four-method perf block together per op. Only 32 of 121 classes override getLatency with a real model; the rest hit these stubs. (This is the spec-absent counterpart to the real latency models documented for the C++ side.)

R5 — Enum Converter Block (Serialize Mode)

The 27 spec field-enums are each emitted as a <Enum>2string (serialize) + string2<Enum> (deserialize) pair. All 54 functions are contiguous in libBIR .text: the 2string halves at 0x4002a0–0x402480, the string2 halves at 0x40d710–0x40f4b2. Brewer emits all 27 2string converters first, then all 27 string2 converters, iterating the same enum order — the fingerprint of one templated loop with a fixed per-enum preamble plus one switch arm per member. The 2string default arm asserts "Unknown <Enum>"; the string2 default returns None / throws.

GOTCHA — brewer owns exactly 27 enums, not all 45. libBIR.so has 45 *2string converters total (nm -DC | rg -c '2string\[abi' = 45). Only the 27 co-located in the brewer .text block 0x4002a0..0x402480 are the brewer field-enum template (verified: 27 of the converters fall in that VA range). The other ~17 (Dtype, InstructionType, EngineType, MemoryType, …) live at far-apart VAs (0x233ae0..0x47fa80) and use NeuronAssertion defaults, not the brewer "Unknown <Enum>" assert — they are core/structural enums from a different codepath. A reimplementer who treats all 45 as field-enums will misclassify the structural ones.

A representative slice of the R5 table — full member counts in AluOpType and Dtype Tables:

The within-pair Δ (2string→string2 line) ranges 7..38 and correlates with enum member count (ActivationFunctionType 30 members Δ36, AluOpType 33 members Δ38; small enums like MemsetMode Δ7). A bigger enum → longer 2string switch → string2 default arm pushed further down. This is the signature of one per-enum emitter loop, and it is STRONG corroboration that all 27 came from one template.

The Wire-Key Parity Proof

Purpose

The single-spec thesis is only useful if the two outputs actually agree on the wire format. They do: the C++ toJson/readFieldsFromJson key set equals the Python birpy toJson/fromJson key set, op-for-op, because both are generated from the same param list. This is what makes Python-emitted BIR parse losslessly in the C++ back-end.

Activation — 11 Keys

bir::InstActivation::toJson (0x435450, CONFIRMED symbol) emits 11 wire-key string literals; readFieldsFromJson (0x417f00, CONFIRMED) reads the same 11 (symmetric round-trip):

can_read_uninit  func  is_activate2  reverse0  reverse1
scale  reduce_op  op1  op0  acc  alpha

Each is a param/derived-name from the shared activate2_info spec (func ← activation_func, op0/op1 ← AluOpType tensor-scalar ops, alpha ← relu_param, acc ← read-accumulator flag). The Python counterpart, neuronxcc/starfish/birpy/InstructionOpcodes.so, defines a class named exactly InstActivation with .toJson/.fromJson; its string pool carries the same keys (verified present: reverse0, reverse1, reduce_op, is_activate2, …, with can_read_uninit and acc carried via the eval-flag / setAcc setter path rather than as a standalone interned literal — the count comes to 7+ plain literals plus the setter-carried remainder).

Matmul — 13 Keys

bir::InstMatmultBase::toJson (0x4358b0, CONFIRMED symbol) emits 13 wire keys; readFieldsFromJson reads the same 13:

accumulation_flag  psum_zero_region  replication_resolution
replication_shift_amnt  replication_num_rows  is_transpose
is_fmap_onezero  is_weight_onezero  tile_size  tile_position
ifmap_quant_offset  weights_quant_offset  perf_mode

The Python birpy/InstructionOpcodes.so InstMatmult carries all 13 verbatim — verified by counting the 13-key set in the canonical starfish/birpy/InstructionOpcodes.cpython-310-*.so string pool: exactly 13 hits. (InstMatmult's own toJson adds zero scalar keys — its ifmap/weights/dst serialize as operands via the base operand list, not as JSON scalars.)

QUIRK — there are two InstructionOpcodes.so copies, and only one is canonical. The cp310 tree ships both neuronxcc/generated/starfish/birpy/InstructionOpcodes.so (a sparser copy carrying only 3 of the Activation keys / 0 of the Matmul keys in its pool) and neuronxcc/starfish/birpy/InstructionOpcodes.so (the full wire layer: 7 Activation + 13 Matmul keys). Grounding parity on the generated/ copy under-counts; use the non-generated/ path.

The Five Guarantees

Because both sides regenerate from one spec, the generation structurally prevents the classic two-implementation drift bugs:

NOTE — enums serialize as their string name. Each C++ to_json calls <Enum>2string then builds a JSON string node (e.g. to_json(json&, ActivationFunctionType const&)), and from_json calls string2<Enum> — so the wire carries the enum name, and the Python emitter must produce the identical spelling for the round-trip to parse. This is why G3 is a hard requirement, not a nicety. The shared Dtype enum (20 members, ordinals 0..19) is the canonical example; see Dtype Tables.

The Two Entry Points

Purpose

The Python provenance docstrings reveal two generator entry points with two roles, which together reconstruct brewer's driver structure.

The Generic Emitter — brewer.py:3384

45 generated modules cite brewer.py:3384 verbatim — one function: the generic per-op class-body emitter (the "datamodel-default" template). Ops with no special handling are emitted straight from it: ActivationOpGen, MatMulOpBaseGen, TensorReduceOpGen, TensorScalarPtrOpGen, the tiled-softmax / tiled-collective family, the SBAtom load/store ops, and ~35 others.

The Family Factories — instabrew/main.py:<N>

49 modules cite main.py at 36 distinct lines. A shared main.py line means a shared op-family factory call — the same generated shape. The multi-op clusters are the strongest evidence (CONFIRMED — verified: three collective OpGens all report main.py at line 1764):

STRONG (INFERRED interpretation) — main.py is the brewer driver / op-catalogue: it holds the per-op (or per-family) spec registration + factory call. Ops sharing a family are registered by one shared factory function (one main.py line) parameterised by the specific op — hence 7 ops report main.py:1764. brewer.py:3384 is the generic class-body emitter that main.py's factories (and the datamodel-default path) call. The pipeline is: main.py registers/parametrises → brewer.py:3384 emits the uniform class body → Cython compiles. The C++ asserts (R1–R5) are brewer.py-lined because the C++ TU is emitted by the same brewer.py at its deeper lines (1327..4799), confirming main.py and brewer.py are one instabrew/ package. This two-role reading is reconstructed from the docstrings; the .py bodies are not shipped.

Adversarial Self-Verification

The five strongest claims, re-checked against the cp310 binary, with an honest ceiling on what is reconstructed vs. confirmed.

CORRECTION (BREWER-01) — the backing analysis reported 44 total *2string converters in libBIR.so; direct nm -DC | rg -c '2string\[abi' on the cp310 image returns 45. The brewer-owned subset (27, co-located at 0x4002a0..0x402480) is unaffected and re-verified; the discrepancy is in the non-brewer structural-enum count (~17 → ~18). Treat "the OTHER 17" as "~18".

Re-verification ceiling — what is reconstructed vs. confirmed. Everything tied to a binary artifact is CONFIRMED: the 121 bir::Inst* classes, the *2string/toJson/readFieldsFromJson symbols and their addresses, the brewer.py line immediates, the indirection/Not Implemented/Unknown <Enum> strings, the Python provenance docstrings, and the non-existence of instabrew/ in the wheel. What is INFERRED and cannot be raised above STRONG from this build: (a) the exact brewer.py/main.py source text and line-by-line logic (the .py is not shipped — the template in Algorithm is reconstructed from the uniform output shape); (b) the role each brewer.py line plays (a line number is CONFIRMED, its identification as a specific emitter sub-routine is reconstructed from the host method and assert expression); (c) the two-entry-point driver semantics (main.py registers, brewer.py:3384 emits) — read off the docstrings and the line-clustering, not from generator code. No generator internal was fabricated; where the .py would be needed to be certain, the claim is tagged.

Related Components

Cross-References

• The bir::Instruction Base Struct — the C++ class hierarchy brewer's bir::Inst<Op> outputs inherit from
• InstructionType: the 110-Opcode Enum & sameInst Family Masks — the sameInst family whose three no-eq arms are R1
• Dtype Tables & Wire-Tag LUTs — the shared Dtype enum (G3); a structural enum, not a brewer R5 field-enum
• AluOpType + the Mode Enums — AluOpType (R5, 33 members) and the field-enum domains brewer owns
• The Compile Pipeline at a Glance — where the generated bir::Inst* classes sit in the IR descent (penguin → BIR)