CLI Options

All addresses in this page apply to ptxas v13.0.88 (CUDA 13.0). Other versions will differ.

ptxas v13.0.88 accepts approximately 160 command-line options: 51 documented in --help output and roughly 109 internal/undocumented options discovered through binary analysis. All option names are registered via sub_432A00 (6,427 bytes at 0x432A00) using a generic option framework shared with other NVIDIA tools. The framework library (sub_1C960C0--sub_1C97640) supports short options (-X), long options (--name), and four value types: boolean toggle, list append, scalar value, and multi-value. Internal option names are stored ROT13-encoded in the binary.

Architecture

          argv
           │
           ▼
   ┌───────────────────┐      ┌─────────────────────────┐
   │  sub_1C960C0      │      │   sub_432A00             │
   │  Parser ctor      │◄─────│   Register ~160 options  │
   │  (56-byte context)│      │   (name, type, default,  │
   └───────┬───────────┘      │    help text, callback)  │
           │                  └─────────────────────────┘
           ▼
   ┌───────────────────┐
   │  sub_1C96680      │
   │  Process argv     │
   │  Detect - and --  │
   │  Type dispatch:   │
   │    1=bool toggle  │
   │    2=list append  │
   │    3=scalar value │
   │    4=multi-value  │
   └───────┬───────────┘
           │
           ▼
   ┌───────────────────┐
   │  sub_434320       │
   │  Validate combos  │
   │  Populate 1352B   │
   │  options block    │
   └───────┬───────────┘
           │
           ▼
     Compilation driver
      (sub_446240)

Quick Start

The most common ptxas invocations and essential options, ordered by frequency of use:

# 1. Basic compilation: PTX -> cubin for a specific GPU
ptxas -arch sm_90 -o kernel.cubin kernel.ptx

# 2. Compilation with optimization control
ptxas -arch sm_100 -O3 -o kernel.cubin kernel.ptx

# 3. Debug build with line info
ptxas -arch sm_90 -g -lineinfo -o kernel.cubin kernel.ptx

# 4. Register-limited compilation (occupancy tuning)
ptxas -arch sm_90 -maxrregcount 64 -o kernel.cubin kernel.ptx

# 5. Verbose output with resource statistics
ptxas -arch sm_90 -v -o kernel.cubin kernel.ptx

# 6. Relocatable object for separate linking
ptxas -arch sm_90 -c -o kernel.o kernel.ptx

# 7. Fast-compile mode (trade codegen quality for build speed)
ptxas -arch sm_100 -Ofc max -o kernel.cubin kernel.ptx

# 8. Parallel compilation with multiple threads
ptxas -arch sm_90 -split-compile 0 -o kernel.cubin kernel.ptx

# 9. Internal knob override (developer/debugging)
ptxas -arch sm_90 -knob DUMPIR=AllocateRegisters -o kernel.cubin kernel.ptx

# 10. Discover all 1,294 internal knob values
DUMP_KNOBS_TO_FILE=/tmp/knobs.txt ptxas -arch sm_90 -o kernel.cubin kernel.ptx

Option Discovery Methodology

Options were extracted from four independent sources:

1. Official --help output -- 51 options with full metadata.
2. Binary string extraction -- strings(1) reveals plaintext option names used in error messages and format strings.
3. ROT13 decode -- Internal option names stored as ROT13 in the registration function. Decoding fj4575628 yields sw4575628, pbzcvyre-fgngf yields compiler-stats, etc.
4. Decompiled code cross-reference -- String references in option processing functions (sub_434320, sub_4428E0, sub_43A400) confirm option semantics.

Tables below use these markers:

• Unmarked rows = documented in --help
• Rows marked (internal) = discovered through RE, not in --help

Core Compilation

Debug and Instrumentation

Register and Occupancy Control

Performance and Optimization

Cache Control

Warnings and Diagnostics

Output Format and Relocation

Workaround Flags

Hardware and software bug workarounds tied to internal NVIDIA bug-tracking IDs. All names are ROT13-encoded in the binary (e.g., fj2614554 decodes to sw2614554). These flags toggle specific code paths that avoid known errata or compiler defects. New workarounds appear (and old ones become permanent) with each ptxas release. The validator in sub_434320 enforces architecture restrictions: a flag set on an unsupported architecture is silently cleared with a diagnostic.

EIATTR-Level Workarounds

Three EIATTR attributes encode workaround metadata directly in the output ELF. These are set by target architecture rather than CLI flags -- ptxas emits them unconditionally when the target requires it, and the GPU driver applies fixups at load time.

Tool and Patch Modes

Statistics and Profiling

Mercury and Capsule Mercury

These options control the Mercury intermediate encoding and Capsule Mercury format, which is the default output format on sm_100+ (Blackwell).

Threading and Parallelism

Texture and Memory Modes

Constant Bank Allocation

NVIDIA GPUs provide 18 hardware constant banks (c[0] through c[17]), each a 64 KB read-only memory segment accessible by all threads in a warp with uniform-address broadcast -- loads from constant banks cost a single memory transaction when all threads in the warp read the same address. The compiler assigns different data categories (kernel parameters, driver state, user constants, PIC tables, etc.) to separate banks to avoid address-space collisions. These options override the default bank assignments; all are ROT13-encoded.

Stress Testing

Internal options for compiler stress testing and regression verification.

Query and Control Interface

Internal options for the query/control interface used by nvcc and other tools.

Syscall Integration

Internal options for system-call based operations (texturing, bulk copy).

Knobs Configuration

The -knob flag is the primary CLI mechanism for setting internal knob values -- the 1,294 tuning parameters documented in Knobs System. It is not listed in --help output and uses a single-dash prefix (not --knob).

Syntax

-knob NAME=VALUE         Set a typed knob (int, float, double, string, range)
-knob NAME               Set a boolean knob (presence = true)
-knob "A=1~B=2~C=3"     Multiple knobs in one argument, separated by ~ (tilde)

Multiple -knob flags are accumulated (list-append semantics):

ptxas -knob SchedNumBB_Limit=100 -knob DisableCSE -knob RegAllocBudget=5000 \
      -arch sm_90 -o out.cubin input.ptx

Knob names are case-insensitive. The name is resolved via ROT13-encoded lookup tables in GetKnobIndex (sub_6F0820 for DAG knobs, sub_79B240 for OCG knobs). An unrecognized name produces warning 7203: "Invalid knob specified (%s)".

Value Types

The value after = is parsed according to the knob's registered type:

Conditional Overrides (WHEN=)

Knobs can be set conditionally based on shader or instruction hash, applied only when a specific function is compiled:

# Apply knob only when shader hash matches
ptxas -knob "WHEN=SH=0xDEADBEEF;SchedNumBB_Limit=200" -arch sm_90 -o out.cubin input.ptx

# Multiple conditional overrides separated by ~
ptxas -knob "WHEN=SH=0xDEAD;DisableCSE~WHEN=IH=0x1234;RegAllocBudget=1000" ...

Condition prefixes: SH= (shader hash), IH= (instruction hash), K= (direct knob, no condition).

Interaction with Other Knob Sources

KnobsInit (sub_79D990) processes knob sources in this order -- later sources override earlier ones for the same knob index:

Environment Variable: DUMP_KNOBS_TO_FILE

The DUMP_KNOBS_TO_FILE environment variable causes ptxas to write all 1,294 knob names and their resolved values to a file:

DUMP_KNOBS_TO_FILE=/tmp/all_knobs.txt ptxas -arch sm_90 -o out.cubin input.ptx

This is the primary mechanism for discovering which knobs exist, their current defaults for a given architecture, and verifying that CLI overrides took effect.

Commonly Used Knobs

For the complete knob type system, file format, and all 1,294 knob categories, see Knobs System.

Version and Architecture Queries

Option Interaction Rules

Several options interact in non-obvious ways, as revealed by the validation logic in sub_434320:

1. --maxrregcount dominance -- When --maxrregcount is specified, --minnctapersm and --maxntid are ignored. The register constraint calculator (sub_43B660) enforces this precedence.

2. --override-directive-values -- Only affects --minnctapersm, --maxntid, and --maxrregcount. Without this flag, PTX directives (.maxnreg, .minnctapersm, .maxntid) take precedence over CLI values.

3. --device-function-maxrregcount vs --maxrregcount -- The former overrides the latter for device functions only, and only under --compile-only mode. For whole-program compilation, --device-function-maxrregcount is ignored.

4. --Ofast-compile vs --fast-compile -- The documented --Ofast-compile supersedes the internal --fast-compile. Both may conflict with --allow-expensive-optimizations (the validator in sub_434320 checks for this).

5. --device-debug auto-enables -- Setting -g auto-enables --sp-bounds-check and --g-tensor-memory-access-check. The flag --gno-tensor-memory-access-check explicitly overrides regardless of ordering.

6. --suppress-debug-info requires -- Has no effect unless --device-debug or --generate-line-info is also specified.

7. --compile-as-tools-patch forces -- Automatically sets maxrregcount to ABI minimum. Interacts with --sw200428197 workaround in the function/ABI setup path (sub_43F400).

8. --split-compile and --allow-expensive-optimizations -- Both activate the thread pool (sub_1CB18B0). The jobserver client (sub_1CC7300) integrates with GNU Make's --jobserver-auth= to respect parallel build limits.

Function Map