### Install Spimdisasm

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Install the library via pip or include it in a requirements file.

```bash
# Install from PyPI
python3 -m pip install -U spimdisasm

# Or add to requirements.txt
spimdisasm>=1.40.2,<2.0.0
```

--------------------------------

### Install spimdisasm development version (git+)

Source: https://github.com/decompollaborate/spimdisasm/blob/1.x/README.md

Install the latest development version directly from the GitHub repository without cloning. This is useful for testing the bleeding edge without local setup.

```bash
python3 -m pip uninstall spimdisasm
python3 -m pip install git+https://github.com/Decompollaborate/spimdisasm.git@1.x
```

--------------------------------

### Install spimdisasm using pip

Source: https://github.com/decompollaborate/spimdisasm/blob/1.x/README.md

Install the latest stable version of spimdisasm from PyPI. This is the recommended installation method for general use.

```bash
python3 -m pip install -U spimdisasm
```

--------------------------------

### Install spimdisasm development version (editable)

Source: https://github.com/decompollaborate/spimdisasm/blob/1.x/README.md

Install the development version of spimdisasm from a local clone of the repository. Use the -e flag for an editable install, allowing direct modifications to the source code.

```bash
python3 -m pip install -e .
```

--------------------------------

### Disassemble N64 ROM

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Demonstrates the full pipeline for disassembling an N64 ROM, including configuration, context setup, section analysis, and file output.

```python
from spimdisasm import common, mips
from pathlib import Path

def disassemble_n64_rom(rom_path: str, output_dir: str):
    """Complete example of disassembling an N64 ROM."""

    # Configure global settings
    common.GlobalConfig.ENDIAN = common.InputEndian.BIG
    common.GlobalConfig.COMPILER = common.Compiler.IDO
    common.GlobalConfig.RODATA_STRING_GUESSER_LEVEL = 2
    common.GlobalConfig.RODATA_STRING_ENCODING = "EUC-JP"
    common.GlobalConfig.ASM_COMMENT = True

    # Create context
    context = common.Context()
    context.fillDefaultBannedSymbols()
    context.globalSegment.fillLibultraSymbols()
    context.globalSegment.fillHardwareRegs(namedRegs=True)

    # Load symbol files if available
    symbols_dir = Path("symbols")
    if (symbols_dir / "functions.csv").exists():
        context.globalSegment.readFunctionsCsv(symbols_dir / "functions.csv")
    if (symbols_dir / "variables.csv").exists():
        context.globalSegment.readVariablesCsv(symbols_dir / "variables.csv")

    # Read ROM
    rom_bytes = common.Utils.readFileAsBytearray(Path(rom_path))

    # Define sections (example for a simple ROM)
    text_start, text_end = 0x1000, 0x50000
    rodata_start, rodata_end = 0x50000, 0x60000
    data_start, data_end = 0x60000, 0x70000

    vram_base = 0x80000400

    # Set context ranges
    context.changeGlobalSegmentRanges(0, len(rom_bytes), vram_base, vram_base + len(rom_bytes))

    # Create output directory
    output_path = Path(output_dir)
    output_path.mkdir(parents=True, exist_ok=True)

    # Disassemble text section
    text_section = mips.sections.SectionText(
        context, text_start, text_end,
        vram_base + text_start, "main",
        rom_bytes[text_start:text_end], 0, None
    )
    text_section.setCommentOffset(text_start)
    text_section.analyze()

    # Disassemble rodata section
    rodata_section = mips.sections.SectionRodata(
        context, rodata_start, rodata_end,
        vram_base + rodata_start, "main",
        rom_bytes[rodata_start:rodata_end], 0, None
    )
    rodata_section.setCommentOffset(rodata_start)
    rodata_section.analyze()

    # Disassemble data section
    data_section = mips.sections.SectionData(
        context, data_start, data_end,
        vram_base + data_start, "main",
        rom_bytes[data_start:data_end], 0, None
    )
    data_section.setCommentOffset(data_start)
    data_section.analyze()

    # Save sections
    text_section.saveToFile(str(output_path / "main"))
    rodata_section.saveToFile(str(output_path / "main"))
    data_section.saveToFile(str(output_path / "main"))

    # Generate split functions with rodata migration
    funcs_path = output_path / "functions"
    funcs_path.mkdir(exist_ok=True)

    entries = mips.FunctionRodataEntry.getAllEntriesFromSections(text_section, rodata_section)
    for entry in entries:
        func_file = funcs_path / f"{entry.getName()}.s"
        with open(func_file, "w", encoding="utf-8") as f:
            f.write('.include "macro.inc"\n\n')
            entry.writeToFile(f)

    # Save context for analysis
    context.saveContextToFile(output_path / "context.csv")

    print(f"Disassembly complete!")
    print(f"  Functions: {text_section.nFuncs}")
    print(f"  Output: {output_path}")

# Run example
if __name__ == "__main__":
    disassemble_n64_rom("game.z64", "asm_output")
```

--------------------------------

### Spimdisasm Utility Functions for File I/O and Data Conversion

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Provides examples of common utility functions for reading/writing binary files, converting between bytes and words, computing file hashes, controlling output verbosity, and parsing integer strings.

```python
from spimdisasm import common
from pathlib import Path

# File I/O
binary_data = common.Utils.readFileAsBytearray(Path("game.bin"))

# Write bytes to file
common.Utils.writeBytesToFile(Path("output.bin"), binary_data)

# Byte/word conversion
words = common.Utils.bytesToWords(binary_data, vromStart=0, vromEnd=len(binary_data))
bytes_back = common.Utils.wordsToBytes(words)

# Hash computation
file_hash = common.Utils.getStrHash(binary_data)
print(f"File hash: {file_hash}")

# Print functions with verbosity control
common.Utils.printVerbose("Debug message")      # Only if GlobalConfig.VERBOSE
common.Utils.printQuietless("Important message") # Unless GlobalConfig.QUIET
common.Utils.eprint("Error message")            # Always to stderr

# Integer parsing
value = common.Utils.intFromStr("0x1000")  # Returns 4096
value = common.Utils.intFromStr("4096")    # Returns 4096

# Parse colon-separated pairs (for symbol_addrs format)
line = "my_func = 0x80100000; // type:func size:0x100"
pairs = common.Utils.parseColonSeparatedPairLine(line)
# pairs = {'my_func': '0x80100000', 'type': 'func', 'size': '0x100'}
```

--------------------------------

### Add spimdisasm to requirements.txt

Source: https://github.com/decompollaborate/spimdisasm/blob/1.x/README.md

Specify the spimdisasm library in your project's requirements.txt file for dependency management. This ensures a compatible version is installed.

```txt
spimdisasm>=1.40.2,<2.0.0
```

--------------------------------

### Create Data Section in MIPS

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Demonstrates how to create and analyze a data section for a MIPS executable. The section is saved to a file.

```python
data_start = 0x30000
data_end = 0x40000
data_vram = 0x80030000

data_section = mips.sections.SectionData(
    context=context,
    vromStart=data_start,
    vromEnd=data_end,
    vram=data_vram,
    filename="main",
    array_of_bytes=array_of_bytes[data_start:data_end],
    segmentVromStart=0,
    overlayCategory=None
)

data_section.analyze()
data_section.saveToFile("output/main")  # Creates main.data.s
```

--------------------------------

### Create Programmatic File Split Entries

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Demonstrates how to programmatically create and append file split entries for different sections like text, rodata, and add an end marker. This is useful for defining how ROM data should be structured.

```python
text_entry = common.FileSplitEntry(
    offset=0x1000,           # ROM offset
    vram=0x80001000,         # Virtual RAM address
    fileName="main",         # Output filename
    sectionType=common.FileSectionType.Text,
    nextOffset=0x10000,      # End offset
    isOverlay=False,
    isRsp=False
)
splits.append(text_entry)

rodata_entry = common.FileSplitEntry(
    offset=0x10000,
    vram=0x80100000,
    fileName="main",
    sectionType=common.FileSectionType.Rodata,
    nextOffset=0x20000,
    isOverlay=False,
    isRsp=False
)
splits.append(rodata_entry)

# Add end marker
splits.appendEndSection(vromEnd=0x100000, vramEnd=0x80100000)

# Iterate over splits
for split in splits:
    print(f"Section: {split.sectionType.toStr()}")
    print(f"  File: {split.fileName}")
    print(f"  Offset: 0x{split.offset:X} - 0x{split.nextOffset:X}")
    print(f"  VRAM: 0x{split.vram:08X}")
```

--------------------------------

### Configure File Splits

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Manages how a binary is split into multiple output files based on sections and addresses. Can read configuration from a CSV file.

```python
from spimdisasm import common
from pathlib import Path

# Create file splits configuration
splits = common.FileSplitFormat()

# Read from CSV file
# Format: offset, vram, filename, section_type, [end_offset], [is_overlay], [is_rsp]
splits.readCsvFile(Path("config/splits.csv"))
```

--------------------------------

### Invoke spimdisasm CLI help

Source: https://github.com/decompollaborate/spimdisasm/blob/1.x/README.md

Access the help screen for the spimdisasm tool or specific modules.

```bash
spimdisasm disasmdis --help
```

```bash
spimdisasm --help
```

--------------------------------

### Query and Configure Symbol Properties

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Access symbol metadata and control migration behavior or visibility settings.

```python
sym = context.globalSegment.getSymbol(0x80100000)
if sym is not None:
    print(f"Name: {sym.getName()}")           # Returns quoted name if needed
    print(f"Name unquoted: {sym.getNameUnquoted()}")
    print(f"Size: {sym.getSize()}")
    print(f"Type: {sym.getType()}")
    print(f"VRAM: 0x{sym.vram:08X}")
    print(f"VROM: 0x{sym.getVrom():08X}")
    print(f"Is function: {sym.isTrustableFunction()}")
    print(f"Is string: {sym.isString()}")
    print(f"Is float: {sym.isFloat()}")
    print(f"Is double: {sym.isDouble()}")
    print(f"Is jump table: {sym.isJumpTable()}")
    print(f"Reference count: {sym.referenceCounter}")

# Symbol with addend representation
print(sym.getSymbolPlusOffset(0x80100010))  # "main + 0x10"

# Control rodata migration behavior
rodata_sym = context.globalSegment.addSymbol(0x80300100, sectionType=common.FileSectionType.Rodata)
rodata_sym.forceMigration = True  # Always migrate to referencing function
# Or
rodata_sym.forceNotMigration = True  # Never migrate
# Or specify exact function
rodata_sym.functionOwnerForMigration = "target_function"

# Set custom alignment
rodata_sym.setAlignment(8)  # Align to 8 bytes

# Configure symbol visibility
sym.visibility = "weak"  # or "local", "global"
```

--------------------------------

### Configure Global Settings with Python API

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Use the GlobalConfig class to set architecture, compiler, and string detection parameters for the disassembler.

```python
from spimdisasm import common

# Configure endianness and architecture
common.GlobalConfig.ENDIAN = common.InputEndian.BIG
common.GlobalConfig.ABI = common.Abi.O32
common.GlobalConfig.ARCHLEVEL = common.ArchLevel.MIPS3

# Configure compiler-specific settings
common.GlobalConfig.COMPILER = common.Compiler.IDO

# String detection settings (levels 0-4)
common.GlobalConfig.RODATA_STRING_GUESSER_LEVEL = 2  # Moderate string guessing
common.GlobalConfig.DATA_STRING_GUESSER_LEVEL = 2
common.GlobalConfig.RODATA_STRING_ENCODING = "EUC-JP"  # For Japanese games
```

--------------------------------

### Create BSS Section in MIPS

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Illustrates the creation and analysis of a BSS section, which contains no ROM data but defines memory addresses. The section is saved to a file.

```python
bss_start = 0x80040000
bss_end = 0x80050000

bss_section = mips.sections.SectionBss(
    context=context,
    vromStart=0x40000,
    vromEnd=0x40000,  # BSS has no ROM data
    vram=bss_start,
    filename="main",
    bssVramEnd=bss_end,
    segmentVromStart=0,
    overlayCategory=None
)

bss_section.analyze()
bss_section.saveToFile("output/main")  # Creates main.bss.s
```

--------------------------------

### Disassemble RSP Microcode with rspDisasm

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Disassemble N64 Reality Signal Processor microcode binaries.

```bash
# Disassemble RSP microcode
rspDisasm microcode.bin output/ --vram 0x04001000
```

--------------------------------

### Manage Context and Memory Segments

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Initializes the disassembly context, defines memory ranges, and manages banned symbols and external symbol files.

```python
from spimdisasm import common
from pathlib import Path

# Create and configure context
context = common.Context()

# Set up global segment memory ranges (vromStart, vromEnd, vramStart, vramEnd)
context.changeGlobalSegmentRanges(0x0, 0x100000, 0x80000000, 0x80100000)

# Add overlay segments for games with overlapping code
actor_segment = context.addOverlaySegment(
    overlayCategory="actors",
    segmentVromStart=0x100000,
    segmentVromEnd=0x120000,
    segmentVramStart=0x80800000,
    segmentVramEnd=0x80820000
)

# Fill default N64 banned symbols (addresses that shouldn't be symbolized)
context.fillDefaultBannedSymbols()

# Add custom banned symbols/ranges
context.addBannedSymbol(0x80000010)
context.addBannedSymbolRange(0x80000000, 0x80000100)
context.addBannedSymbolRangeBySize(0x80100000, 0x1000)

# Check if address should be symbolized
if not context.isAddressBanned(0x80050000):
    print("Address can be symbolized")

# Load symbols from CSV files
context.globalSegment.readFunctionsCsv(Path("symbols/functions.csv"))
context.globalSegment.readVariablesCsv(Path("symbols/variables.csv"))
context.globalSegment.readConstantsCsv(Path("symbols/constants.csv"))

# Load splat-compatible symbol files
context.globalSegment.readSplatSymbolAddrs(Path("symbols/symbol_addrs.txt"))
context.readSplatRelocAddrs(Path("symbols/reloc_addrs.txt"))

# Fill built-in N64 symbols
context.globalSegment.fillLibultraSymbols()
context.globalSegment.fillIQueSymbols()
context.globalSegment.fillHardwareRegs(namedRegs=True)

# Add global relocation overrides
context.addGlobalReloc(
    vromAddres=0x1000,
    relocType=common.RelocType.MIPS_HI16,
    symbol="my_symbol",
    addend=0
)

# Save context for later analysis
context.saveContextToFile(Path("output/context.csv"))
```

--------------------------------

### Configure Global Disassembly Settings

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Sets global configuration options for symbol naming, assembly output formatting, and pointer detection. These settings affect the behavior of the entire disassembly process.

```python
common.GlobalConfig.AUTOGENERATED_NAMES_BASED_ON_SECTION_TYPE = True  # RO_, B_ prefixes
common.GlobalConfig.AUTOGENERATED_NAMES_BASED_ON_DATA_TYPE = True     # STR_, FLT_, DBL_ prefixes
common.GlobalConfig.SEQUENTIAL_LABEL_NAMES = True  # func_name_1, func_name_2

# Assembly output formatting
common.GlobalConfig.ASM_COMMENT = True
common.GlobalConfig.ASM_TEXT_LABEL = "glabel"
common.GlobalConfig.ASM_DATA_LABEL = "dlabel"
common.GlobalConfig.ASM_JTBL_LABEL = "jlabel"
common.GlobalConfig.ASM_INDENTATION = 4
common.GlobalConfig.ASM_EMIT_SIZE_DIRECTIVE = True

# Pointer and symbol detection
common.GlobalConfig.GP_VALUE = 0x800E0000  # Global pointer value
common.GlobalConfig.PIC = False  # Position-independent code
common.GlobalConfig.SYMBOL_FINDER_FILTER_LOW_ADDRESSES = True
common.GlobalConfig.SYMBOL_FINDER_FILTER_ADDRESSES_ADDR_LOW = 0x80000000
common.GlobalConfig.SYMBOL_FINDER_FILTER_ADDRESSES_ADDR_HIGH = 0xC0000000

# Environment variable configuration (alternative)
# Set SPIMDISASM_RODATA_STRING_GUESSER_LEVEL=2 in environment
common.GlobalConfig.processEnvironmentVariables()
```

--------------------------------

### Manage Individual Symbols

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Creates and configures individual symbols, including functions, data, jump tables, and constants within the disassembly context.

```python
from spimdisasm import common

# Create a symbol directly
symbol = common.ContextSymbol(address=0x80100000)
symbol.name = "player_init"
symbol.userDeclaredSize = 0x100
symbol.userDeclaredType = common.SymbolSpecialType.function
symbol.isUserDeclared = True

# Add symbol through segment
context = common.Context()
context.changeGlobalSegmentRanges(0, 0x100000, 0x80000000, 0x80100000)

# Add different symbol types
func_sym = context.globalSegment.addFunction(0x80100000, isAutogenerated=False, vromAddress=0x1000)
func_sym.name = "main"

data_sym = context.globalSegment.addSymbol(
    address=0x80200000,
    sectionType=common.FileSectionType.Data,
    isAutogenerated=True,
    vromAddress=0x50000
)

# Add jump table and labels
jtbl_sym = context.globalSegment.addJumpTable(0x80300000, isAutogenerated=True)
jtbl_label = context.globalSegment.addJumpTableLabel(0x80100100, isAutogenerated=True)
branch_label = context.globalSegment.addBranchLabel(0x80100050, isAutogenerated=True)

# Add constants (named values)
const_sym = context.globalSegment.addConstant(
    constantValue=0x3F800000,  # 1.0f in IEEE 754
    name="FLOAT_ONE",
    isAutogenerated=False
)
```

--------------------------------

### Disassemble ELF Files with elfObjDisasm

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Disassemble ELF object files, optionally including symbol tables, relocations, and GOT information.

```bash
# Basic ELF disassembly
elfObjDisasm game.elf output/

# Disassemble with readelf-like information
elfObjDisasm game.elf output/ --file-header --syms --relocs

# Display GOT table information
elfObjDisasm game.elf output/ --display-got

# Split functions from ELF
elfObjDisasm game.o output/ --split-functions funcs/
```

--------------------------------

### Handle Data and Rodata Sections

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Configure and disassemble data sections with specific encoding and analysis settings.

```python
from spimdisasm import common, mips
from pathlib import Path

# Read binary
binary_path = Path("game.bin")
array_of_bytes = common.Utils.readFileAsBytearray(binary_path)

# Set up context
context = common.Context()
context.changeGlobalSegmentRanges(0, 0x100000, 0x80000000, 0x80100000)

# Create rodata section
rodata_start = 0x20000
rodata_end = 0x30000
rodata_vram = 0x80020000

rodata_section = mips.sections.SectionRodata(
    context=context,
    vromStart=rodata_start,
    vromEnd=rodata_end,
    vram=rodata_vram,
    filename="main",
    array_of_bytes=array_of_bytes[rodata_start:rodata_end],
    segmentVromStart=0,
    overlayCategory=None
)

# Configure string detection
rodata_section.enableStringGuessing = True
rodata_section.stringEncoding = "EUC-JP"  # Override global encoding

# Analyze and disassemble
rodata_section.analyze()
rodata_section.saveToFile("output/main")  # Creates main.rodata.s
```

--------------------------------

### Disassemble Binary Files with singleFileDisasm

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Use singleFileDisasm to convert raw binary files into MIPS assembly with support for symbol files, compiler settings, and function splitting.

```bash
# Basic disassembly of an N64 binary
singleFileDisasm game.bin output/ --start 0x1000 --end 0x5000 --vram 0x80100000

# Disassemble with symbol files and custom settings
singleFileDisasm rom.bin asm/ \
    --start 0x0 \
    --end 0x100000 \
    --vram 0x80000400 \
    --functions syms/functions.csv \
    --variables syms/variables.csv \
    --symbol-addrs syms/symbol_addrs.txt \
    --compiler IDO \
    --rodata-string-guesser 2 \
    --libultra-syms \
    --hardware-regs

# Split functions into individual files with rodata migration
singleFileDisasm game.bin asm/ \
    --start 0x1000 \
    --end 0x80000 \
    --vram 0x80100000 \
    --split-functions asm/functions/ \
    --file-splits config/splits.csv

# Disassemble with data section
singleFileDisasm binary.bin output/ \
    --start 0x0 \
    --end 0x10000 \
    --data-start 0x10000 \
    --data-end 0x20000 \
    --vram 0x80000000

# Output function information CSV
singleFileDisasm rom.bin asm/ \
    --start 0x1000 \
    --end 0x50000 \
    --vram 0x80100000 \
    --function-info functions_info.csv \
    --save-context context.csv
```

--------------------------------

### Migrate Rodata Symbols to Functions

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Facilitates migrating rodata symbols (strings, floats, jump tables) to be co-located with their referencing functions. Requires sections to be analyzed first.

```python
from spimdisasm import common, mips
from pathlib import Path

# Set up sections (after analysis)
context = common.Context()
# ... configure context ...

# Create and analyze sections
text_section = mips.sections.SectionText(...)
text_section.analyze()

rodata_section = mips.sections.SectionRodata(...)
rodata_section.analyze()

# Get all function-rodata pairings
entries = mips.FunctionRodataEntry.getAllEntriesFromSections(text_section, rodata_section)

# Write migrated functions to individual files
output_dir = Path("output/functions")
output_dir.mkdir(parents=True, exist_ok=True)

for entry in entries:
    name = entry.getName()

    # Check if entry has associated rodata
    if entry.hasRodataSyms():
        print(f"Function {name} has {len(entry.rodataSyms)} rodata symbols")
        print(f"  Late rodata: {len(entry.lateRodataSyms)} symbols")

    # Write to file
    filepath = output_dir / f"{name}.s"
    with open(filepath, "w", encoding="utf-8") as f:
        entry.writeToFile(f, writeFunction=True)
```

```python
# Get entry for specific function
for func in text_section.symbolList:
    entry = mips.FunctionRodataEntry.getEntryForFuncFromSection(func, rodata_section)

    # Iterate over rodata symbols
    for rodata_sym in entry.iterRodataSyms():
        print(f"  Rodata: {rodata_sym.getName()}")
```

```python
# Custom section names for migration output
entry = mips.FunctionRodataEntry(
    function=func,
    rodataSyms=rodata_list,
    lateRodataSyms=late_rodata_list,
    sectionText=".text",
    sectionRodata=".rdata",      # SN64 uses .rdata instead of .rodata
    sectionLateRodata=".late_rodata"
)
```

--------------------------------

### Disassemble Text Sections

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Initialize a SectionText object to analyze and disassemble MIPS code sections.

```python
from spimdisasm import common, mips
from pathlib import Path

# Set up context
context = common.Context()
context.changeGlobalSegmentRanges(0, 0x50000, 0x80000000, 0x80050000)
context.fillDefaultBannedSymbols()
context.globalSegment.fillLibultraSymbols()

# Read binary file
binary_path = Path("game.bin")
array_of_bytes = common.Utils.readFileAsBytearray(binary_path)

# Create text section
vrom_start = 0x1000
vrom_end = 0x10000
vram = 0x80001000

text_section = mips.sections.SectionText(
    context=context,
    vromStart=vrom_start,
    vromEnd=vrom_end,
    vram=vram,
    filename="main",
    array_of_bytes=array_of_bytes[vrom_start:vrom_end],
    segmentVromStart=0,
    overlayCategory=None
)

# Configure section-specific settings
text_section.instrCat = rabbitizer.InstrCategory.CPU  # or RSP, R3000GTE, R5900
text_section.detectRedundantFunctionEnd = True  # IDO-specific optimization
text_section.gpRelHack = False  # For old assemblers without %gp_rel support

# Set comment offset for file position comments
text_section.setCommentOffset(vrom_start)

# Analyze the section (finds functions, symbols, etc.)
text_section.analyze()

# Print analysis results
text_section.printAnalyzisResults()
print(f"Found {text_section.nFuncs} functions")
print(f"File boundaries: {text_section.fileBoundaries")

# Access individual functions
for func in text_section.symbolList:
    print(f"Function: {func.getName()} at 0x{func.vram:08X}")
    print(f"  Size: {func.sizew * 4} bytes")
    print(f"  Instructions: {len(func.instructions)}")

# Disassemble to string
asm_output = text_section.disassemble()

# Save to file
text_section.saveToFile("output/main")  # Creates main.text.s

# Or write to file handle with prelude
with open("output/main.text.s", "w", encoding="utf-8") as f:
    text_section.disassembleToFile(f)

# Compare two sections
other_section = mips.sections.SectionText(...)
other_section.analyze()

comparison = text_section.compareToFile(other_section)
print(f"Equal: {comparison['equal']}")
print(f"Different opcodes: {comparison['text']['diff_opcode']}")
print(f"Same opcode, different args: {comparison['text']['same_opcode_same_args']}")

# Get suspected padding garbage (for SN64 compiler)
garbage_offsets = text_section.suspectedPaddingGarbage()
```

--------------------------------

### Disassemble Instructions with disasmdis

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Quickly disassemble individual MIPS instructions or sequences from hexadecimal input.

```bash
# Disassemble single instruction (leading 0x must be omitted)
disasmdis 03E00008
# Output: jr        $ra

# Disassemble multiple instructions
disasmdis 27BDFFE0 AFBF0014 0C000100 00000000
# Output:
# addiu     $sp, $sp, -0x20
# sw        $ra, 0x14($sp)
# jal       func_80000400
# nop

# Disassemble with specific instruction category
disasmdis --instr-category rsp 4A000000
# RSP instruction output

# Little endian disassembly
disasmdis --endian little E0FFBD27 1400BF AF

# Enable pseudo-instructions
disasmdis --pseudos 00000000 03E00008
# Output: nop; jr $ra
```

--------------------------------

### Define Non-Matching Symbol Macro in MIPS Assembly

Source: https://github.com/decompollaborate/spimdisasm/blob/1.x/CHANGELOG.md

Use this macro to generate a `.NON_MATCHING` symbol for unmatched symbols. Configure the label name using `GlobalConfig.ASM_NM_LABEL` or disable it by setting it to an empty string.

```mips
.macro nonmatching label, size=1
    .global \label\().NON_MATCHING
    .type \label\().NON_MATCHING, @object
    .size \label\().NON_MATCHING, \size
    \label\().NON_MATCHING:
.endm
```

--------------------------------

### Parse ELF32 File

Source: https://context7.com/decompollaborate/spimdisasm/llms.txt

Parses ELF object files, automatically handling symbol tables, relocations, and section headers. Provides readelf-like output and access to parsed data.

```python
from spimdisasm import common, elf32
from pathlib import Path

# Read ELF file
elf_path = Path("game.o")
elf_bytes = common.Utils.readFileAsBytearray(elf_path)

# Parse ELF
elf_file = elf32.Elf32File(elf_bytes)

# Handle ELF header flags (sets global config automatically)
elf_file.handleHeaderIdent()
elf_file.handleFlags()

# Print readelf-like output
elf_file.readelf_fileHeader()      # ELF header info
elf_file.readelf_sectionHeaders()  # Section headers
elf_file.readelf_syms()            # Symbol table
elf_file.readelf_dyn_syms()        # Dynamic symbols
elf_file.readelf_relocs()          # Relocations
elf_file.readelf_displayGot()      # GOT table
```

```python
# Access parsed sections
if elf_file.symtab is not None:
    for sym in elf_file.symtab.symbols:
        if elf_file.strtab is not None:
            name = elf_file.strtab[sym.name]
            print(f"Symbol: {name} at 0x{sym.value:08X}")

# Access section headers by type
for name, section in elf_file.progbitsExecute.items():
    print(f"Executable section: {name}, offset: 0x{section.offset:X}")

for name, section in elf_file.progbitsNoWrite.items():
    print(f"Read-only section: {name}")

# Get reginfo for GP value
if elf_file.reginfo is not None:
    gp_value = elf_file.reginfo.gpValue
    print(f"GP value: 0x{gp_value:08X}")

# Access relocations
for sect_type, rels in elf_file.rel.items():
    for rel in rels.relocations:
        print(f"Reloc: offset=0x{rel.offset:X}, type={rel.rType}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.