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).

Extracting every .rodata string beginning -- from the binary's string table yields 147 distinct -- literals. 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.

GOTCHA — the "layers per module" knob is --meta-module, whose metavar is M. There is no --M flag; no such literal exists in CompileCommand.so. Tools that scrape metavars out of a usage line can manufacture one.

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).

Cf (confidence). CERTAIN = literal + help/dest both in .rodata and consistent, or a decompiled equality/SetAttr pins the default/effect. HIGH = literal + dest present; default/effect inferred from the adjacent dest plus its buildPipeline/validateArgs use, with no literal default constant. MEDIUM = literal present; type/default/visibility reasoned from naming convention and Action class alone. 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

The precision-flag defaults. The registered argparse defaults are the off settings: --auto-cast builds default= from the interned none token, and --fast-math builds default= from PyList_New(0) — an empty list. So the shipped behaviour is no casting until the user asks for it. --fast-math additionally carries kind=ArgKind.INTERNAL and nargs='+'.

GOTCHA — matmult and fp32-cast-matmult describe the behaviour selected once casting is enabled, not the defaults. Documentation that leads with "auto-cast defaults to matmult" is describing the enabled mode.

Anchors: CompileCommand.__init__ @ 0x36290 — --auto-cast default=none at 0x39a7b/0x39a82, --fast-math PyList_New(0) at 0x3a6ec/0x3a702, ArgKind.INTERNAL fetch at 0x3a833.

--auto-cast-type has four choices. fp8_e4m3 is a genuine direct choice alongside fp16/bf16/tf32, not a macro-only spelling: the literal is interned as __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" [0x8536e] sits contiguous with the fp16:/bf16:/tf32: doc lines at [0x85320]/[0x85346]/[0x85357], forming one four-choice description block. buildPipeline canonicalizes the user spelling fp8_e4m3 → fp8e4 (3.14 §4.1). Only fp32r (the tf32 canonical form) and the relayout-dtype variants are macro-only.

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)

What -O3 actually does

The --optlevel choice set is exactly the four Cython string-table tokens "0", "1", "2", "3" (string_tab[1..4]); no -O4..-O9 constants exist anywhere in .rodata, and the help text names only -O1/-O2/-O3. -O is the short alias (string_tab[111] = ("-O", &__pyx_kp_u_O)), with -O0/-O1/-O2/-O3 as its argparse short spellings.

-O3 is then unconditionally rewritten to -O2. The only guard is the equality test _Pyx_PyUnicode_Equals(kp_u_3, optlevel) (buildPipeline L15261); when it holds, buildPipeline sets optlevel="2" (L15279), sets layer_unroll_factor=0 (L15288) and layer_unroll_factor_Used=True, and logs the USER advisory kp_u_The_O3_setting_is_not_optimized. There is no precondition and no further guarding if.

GOTCHA — -O3 is not a "degrade only if preconditions are unmet" path. Passing -O3 always yields an -O2 compile plus a zeroed layer-unroll factor. The level→knob map is in 3.10 — opt-level planes §2.4.

Evidence summary — the five strongest claims

Each is grounded in CompileCommand.cpython-310-…so's string table and .rodata:

1. 147 distinct -- literals. The count 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. No --M literal exists in the 147-set. --meta-module is present with the byte-verbatim help "Number of layers to be clustered into a module…".
3. --optlevel is 0–3, default 2, no 4–9. The help string names only -O1/-O2/-O3, and no 4–9 choice tokens exist.
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. --output's default file.neff is a rodata token; --fast-math's default is the empty list built by PyList_New(0) @ 0x3a6ec, not a macro token (the fp32-cast-matmult macro string exists in the choice set but is not the default).
5. --scheduler choice set + validation. none | experimental-loop-shift-left | experimental-loop-lsa, plus the validateArgs raise string "Unsupported scheduler= %s", are all in .rodata.

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).