CompileCommand Flag Catalog — the 147-Flag Surface

All flag literals, help strings, defaults, and offsets on this page apply to neuronx_cc 2.24.5133.0+58f8de22 (cp310 Cython module neuronxcc/driver/commands/CompileCommand.cpython-310-x86_64-linux-gnu.so). Other wheels differ; treat every address as version-pinned. Offsets in [...] are .rodata byte offsets read from the IDA string table / _rodata.bin.

Abstract

This page is the complete user-facing option reference for the neuronx-cc compile subcommand: every --flag the parser recognizes, with its argument type, default value, visibility class, and a concise (byte-verbatim where present) help string, in one master catalog table. It is the authoritative grammar — a reader who wants to know "does --X exist, what does it take, and will --help show it" should be able to answer that here without touching the binary.

The flag surface is registered in exactly one Cython function — CompileCommand.__init__ (__pyx_pw_..._CompileCommand_1__init__ @ file-off 0x36290, ~30 564 decompiled lines, 717 add_argument/-- references) — and its pipeline effects are assembled in CompileCommand.buildPipeline (0x619d0, ~16 616 lines), which constructs the tensorizer_options string and the Job list. Every add_argument call is intercepted by _AddArgumentCallInterceptor (in driver/Arguments.cpython-310-...so) and recorded in _ArgumentRegistry keyed by an ArgKind (PUBLIC/INTERNAL/HIDDEN/EARG/Harg); that ArgKind decides which --help* surface a flag appears on (see 3.9 for the registry mechanics, 3.2 for the two-parser architecture).

The exact literal set was re-derived for this page by extracting every .rodata string beginning -- from the binary's string table: 147 distinct -- literals (CONFIRMED — jq -r '.[].value' …_strings.json | rg '^--' | sort -u | wc -l ⇒ 147). That is the "147-flag surface." Note what the count includes: a handful of flags appear twice — once as the bare flag and once as a defaulted =value form (e.g. --internal-dma-qos-class-count and --internal-dma-qos-class-count=) — and four --no-* negation companions are separate literals. So 147 ≠ 147 user-distinct features; the base-name count (=value/--no-/short companions folded into their parent) is ~140. Both numbers are reported, and the table below collapses the duplicate =value literals into one row while keeping the --no-* companions visible.

CORRECTION — there is no --M flag. A raw strings | rg '^--' sweep once suggested a --M flag; no byte-exact --M literal exists in CompileCommand.so (verified: rg -x -- '--M' over the 147-literal set ⇒ ABSENT). The "layers per module" knob is --meta-module (metavar M, help "Number of layers to be clustered into a module (partition). Set this to zero to treat the entire graph as a single module." [0x85b60], CONFIRMED present). The apparent --M was a multi-line/x86-fragment artifact; its candidate help string belongs to --meta-module. The catalog uses --meta-module.

How to read the catalog

Columns. flag (byte-verbatim literal) · argtype · default · Vis (visibility / ArgKind) · help (concise; quoted text is byte-verbatim .rodata, offset in []).

argtype legend. bool = store_true/store_false; ED = EnableDisableArgumentAction pair (auto-registers a --no-/--disable companion); NO = NoableArgumentAction pair (auto --no-<flag>); DEP = DeprecatedArgumentAction (still parsed, warns); int/float/str/list; enum(...) = fixed choice set; =N/=value = literal stored with its default token (Cython idiom for a defaulted opt).

Vis legend. PUB = shown by compile --help. HID = shown only by --help-hidden (HelpHiddenAction). INT = shown only by --help-hidden-list (HelpHiddenListAction); by convention every --internal-* / --enable-internal-* flag. EARG = experimental ArgKind (the --enable-experimental-* / --experimental-* family; help-suppressed from --help, listed by --help-hidden). DEP = deprecated. Where the page writes PUB(/HID) the ArgKind byte was not resolvable to a single constant from the deeply-nested __init__ decompilation (see honesty note).

Confidence. C = CONFIRMED (literal + help/dest both in .rodata and consistent, or a decompiled equality/SetAttr proves the default/effect). S = STRONG (literal + dest present; default/effect inferred from adjacent dest + buildPipeline/validateArgs use, no literal default constant). I = INFERRED (literal present; type/default/visibility reasoned from naming convention + Action class only). Cells whose value is computed at runtime from --arch/--target are tagged (per-target) and are not a static token.

NOTE — defaults honesty. (per-target) / (none) defaults are computed in validateArgs/buildPipeline from --arch/--target; they are not single rodata constants and are never guessed here. Plain bool store_true flags default False. ED/NO flags expose a --no-/--disable companion.

Master catalog — A–Z

Shared top-level driver flags

Registered in driver/CommandDriver.cpython-310-...so, not in CompileCommand — they appear on every subcommand including compile. Verbatim from the embedded usage block (0x37c02–0x37d4f) + help strings (0x37840–0x37940).

CompileCommand flags A–F

CORRECTION — the precision-flag argparse defaults are --auto-cast=none and --fast-math=[], not matmult/fp32-cast-matmult. Earlier rows on this page gave --auto-cast default matmult and --fast-math default fp32-cast-matmult. Those describe the behaviour selected when auto-cast is enabled, not the registered argparse default= literals. Byte-anchored in CompileCommand.__init__ (0x36290): the --auto-cast kwargs build PyDict_SetItem(default, __pyx_n_u_none) (mov rdx, __pyx_n_u_none @ 0x39a7b → mov rsi, __pyx_n_s_default @ 0x39a82), and --fast-math builds default= from PyList_New(0) (xor edi, edi; call _PyList_New @ 0x3a6ec → n_s_default @ 0x3a702) — i.e. an empty list. So the genuine defaults are no casting until the user asks for it. --fast-math is additionally kind=ArgKind.INTERNAL (.INTERNAL fetched @ 0x3a833), nargs='+'. The rows above and the choice appendix below are corrected accordingly; 3.14 precision-flag-marshalling §2.1/§2.3 is authoritative on this axis. (CONFIRMED — disasm at the cited offsets.)

CORRECTION — --auto-cast-type has FOUR choices, including fp8_e4m3. An earlier version of this row listed only enum(fp16, bf16, tf32) and claimed fp8e4 was "reachable only via --fast-math macros". That is wrong: fp8_e4m3 is a genuine direct choice of --auto-cast-type. Byte-anchored in CompileCommand.so .rodata: the choice literal fp8_e4m3 is interned __pyx_n_u_fp8_e4m3 at [0x8a560], and its per-choice doc line "fp8_e4m3: floating point with 4 bits exponent and 3 bits mantissa" sits at [0x8536e], contiguous with the fp16:/bf16:/tf32: doc lines at [0x85320]/[0x85346]/[0x85357] — the four-choice description block. buildPipeline then canonicalizes the user spelling fp8_e4m3 → fp8e4 (3.14 §4.1). Only fp32r (the tf32-canonical) and the relayout-dtype variants are macro-only; fp8_e4m3 is not. (CONFIRMED — .rodata string + interned-name symbol + adjacent doc-line block.)

CompileCommand flags H–M

CompileCommand flags N–Z

NOTE — no W/X/Y/Z CompileCommand flags. No --flag literal whose base-name begins W, X, Y, or Z exists in CompileCommand.so (cross-checked over the full literal set). --verbose/--version begin V but are registered in CommandDriver, catalogued above.

The --internal-* family (auto-INTERNAL, surfaced by --help-hidden-list)

These flags acquire ArgKind.INTERNAL automatically because their dest starts with "internal-" — _AddArgumentCallInterceptor.add_argument (Arguments.so @ 0x19210) calls name.startswith("internal-") (compared literal __pyx_kp_u_internal = "internal-" [0x23d08]); on match → kind = ArgKind.INTERNAL. They show only under --help-hidden-list, which dumps each INTERNAL flag with its default. Default False unless a value-arg.

The --enable-internal-* family (feature toggles; INTERNAL)

Same "internal-"-substring rule ⇒ ArgKind.INTERNAL (surfaced by --help-hidden-list). These are opt-in switches for in-development backend/flow features; off by default; more "productised" than raw --internal-* knobs. All bool, default False.

The --enable-experimental-* family (EARG; surfaced by --help-hidden)

Tagged EARG explicitly at the add_argument call (no "internal-" substring, so not auto-INTERNAL). Help-suppressed from --help; listed by --help-hidden. Least stable — bleeding-edge paths. All bool, default False.

GOTCHA — --no-enable-tritium-loopfusion implies a positive default-ON flag. The literal set contains the --no- companion but not a separate --enable-tritium-loopfusion literal in the A–Z table; the positive --enable-tritium-loopfusion defaults ON, and only its NoableArgumentAction negation --no-enable-tritium-loopfusion [0x881f0] is a distinct rodata literal. A reimplementer must register the positive flag (default True) plus the auto-generated negation.

Visibility / ArgKind in one paragraph

A flag's help surface is decided by its ArgKind, set once at add_argument time and stored in _ArgumentRegistry as the tuple "argument,kind,job,default,". The interceptor assigns INTERNAL automatically iff the dest starts "internal-"; otherwise PUBLIC, unless the call passes an explicit kind= kwarg (HIDDEN, EARG, Harg). --help shows PUBLIC only; --help-hidden adds HIDDEN + the experimental EARG/Harg args; --help-hidden-list filters to kind == INTERNAL and dumps each with its default (the registry dump). Stability ordering, most→least stable: PUBLIC > HIDDEN (hand-tagged debug) > --enable-internal-* (feature toggles) > --internal-* (raw dev knobs) > --enable-experimental-*/EARG (bleeding edge) > *unsafe* experimental; Harg-tagged args never appear on any help surface. Full mechanics: 3.9 — flag-visibility & ArgKind.

Choice / enum appendix (verbatim)

--auto-cast        : none (DEFAULT) | matmult | all   (matmult is the behaviour when enabled, not the argparse default)
--auto-cast-type   : fp16 | bf16 (DEFAULT) | tf32 | fp8_e4m3   (fp8_e4m3→fp8e4 canonicalized; fp32r only via --fast-math)
--fast-math macros : all | none |       (argparse default = [] empty list; no macro is the default)
                     fp32-cast-all | fp32-cast-all-fp16 | fp32-cast-all-fp32r |
                     fp32-cast-all-fp8e4 | fp32-cast-matmult |
                     fp32-cast-matmult-bf16 | fp32-cast-matmult-fp16 |
                     fp32-cast-matmult-fp32r | fp32-cast-matmult-fp8e4 | fp32-cast-none |
                     fast-relayout | fast-relayout-fp32 | fast-relayout-fp32r |
                     fast-relayout-fp8e4 | no-fast-relayout                 (semantics: 3.14)
--arch / --target  : inf1 | inf2 | trn1 | trn1n | trn2 | trn2n | trn3 | sunda
                     (aliases inferentia/trainium; internal core_v4/core_v5; trn3pre pre-silicon)
--cpu-arch         : skylake-avx512 | skylake
--distribution-strategy : fsdp | nemo | llm-training
--model-type       : transformer | transformer-inference | cnn-training |
                     unet-inference | vae-inference | operator-fusion | generic
--allocator        : coloring (DEFAULT) | linear_scan
--scheduler        : none (DEFAULT) | experimental-loop-shift-left | experimental-loop-lsa
--internal-interleave-kind : dst_reduce | first_mm
--optlevel / -O    : "0" (-O0) | "1" (-O1) | "2" (-O2, DEFAULT) | "3" (-O3)   — NO 4..9
--logfile-verbose / --verbose : debug | info | warning | user
--pipeline/--state stages : Frontend | WalrusDriver | Backend | BIRSim  (+ BirCodeGenLoop)

CORRECTION — --optlevel accepts only 0–3, default 2. The choice tokens are exactly the Cython string-table entries "0","1","2","3" (string_tab[1..4]); there are no -O4..-O9 constants (verified: no bare 4..9 choice tokens in .rodata). The help text names only -O1/-O2/-O3. -O is the short alias (string_tab[111] = ("-O", &__pyx_kp_u_O)); -O0/-O1/-O2/-O3 are its argparse short spellings. -O3 is an unconditional rewrite to -O2 — not a "degrade when preconditions are unmet". The only guard is the equality test itself: _Pyx_PyUnicode_Equals(kp_u_3, optlevel) (BP decompile L15261); when it is true, BP unconditionally does SetAttr optlevel="2" (L15279), SetAttr layer_unroll_factor=0 (L15288), layer_unroll_factor_Used=True, and logs the USER advisory (kp_u_The_O3_setting_is_not_optimized). There are no preconditions and no guarding if beyond optlevel=="3". Deep level→knob map: 3.10 — opt-level planes §2.4 (authoritative — full decompile L15262–15378).

Verification — the five strongest claims

Each cross-checked against CompileCommand.cpython-310-…so (string table …_strings.json + …_rodata.bin):

1. 147 distinct -- literals. jq -r '.[].value' …_strings.json | rg '^--' | sort -u | wc -l ⇒ 147. CONFIRMED. This is the literal count and includes the =value defaulted forms (--internal-dma-qos-class-count=, --internal-dma-qos-for-spill-code=) and four --no-* companions; the de-duplicated base-name count is ~140.
2. No --M; --meta-module is the real flag. rg -x -- '--M' over the 147-set ⇒ ABSENT. --meta-module present with byte-verbatim help "Number of layers to be clustered into a module…". CONFIRMED correction.
3. --optlevel is 0–3, default 2, no 4–9. Help string verbatim in .rodata names only -O1/-O2/-O3; no 4–9 choice tokens exist. CONFIRMED.
4. Default-carrying literals are byte-exact. --partitions-per-bank=64, --softmax-epsilon=-100000000.0, --partitioner-opts='--transformer', --run-simulator-after=BirCodeGenLoop, --inst-count-limit=100000000, --cc-pipeline-tiling-factor=2, --layout-transform-heuristic=mcts, --model-specific-opt=unet — all present verbatim in the literal set. CONFIRMED. --output default file.neff is a rodata token; --fast-math's argparse default is the empty list [] (PyList_New(0) @ 0x3a6ec), not a macro token (the fp32-cast-matmult macro string exists in the choice set but is not the default — see the CORRECTION in the A–F section).
5. --scheduler choice set + validation. none | experimental-loop-shift-left | experimental-loop-lsa plus the validateArgs raise string "Unsupported scheduler= %s" all present in .rodata. CONFIRMED.

Cross-references

• 3.9 — flag visibility & ArgKind — the _ArgumentRegistry, ArgKind enum, --help/--help-hidden/--help-hidden-list mechanics, the "internal-"-prefix rule.
• 3.10 — optimization levels — deep -O0..-O3 → per-pass / --walrus-passes knob mapping and the -O3→-O2 fallback.
• 3.14 — precision flags — --fast-math / --auto-cast / --auto-cast-type macro semantics (this page lists only the choice surface).
• 3.2 — the two-parser frontend — InterceptingArgumentParser vs the second parser and how the surface is split.
• 0.2 — the compile pipeline — how buildPipeline turns these flags into the Job list / tensorizer_options.
• Part 14 flag appendix — the consolidated cross-tool flag index (walrus_driver cl::opt flags are a distinct surface).