Skip to content

export.md

Latest commit

 

History

History
182 lines (135 loc) · 5.08 KB

export.md

File metadata and controls

182 lines (135 loc) · 5.08 KB

Export Output Specification

This document specifies the assembly output format generated by OpcodeOracle's export command.

Output Structure

OpcodeOracle always generates both outputs:

  1. Main disassembly file - Complete disassembly in one file
  2. Segment files - Separate file per segment in segments/ subdirectory

Segment Generation

Segment files are derived by combining:

  1. Regions - define code/data type boundaries
  2. Symbols - identify subroutines/entries within code regions

Rules

  1. Non-code regions (data) → one _dat.asm file per region

  2. Code regions are split by subroutine/entry symbols:

    • Code at region start without a subroutine symbol → _code.asm
    • Each SymbolSubroutine or SymbolEntry starts a new _sub.asm

Example

Given:

  • Region $0800-$0FFF: code
  • Region $1000-$10FF: data
  • Symbol at $0800: entry
  • Symbol at $0900: subroutine
  • Symbol at $0A00: subroutine

Produces:

segments/
├── 0x0800_sub.asm    # Entry at $0800, ends at $08FF
├── 0x0900_sub.asm    # Subroutine at $0900, ends at $09FF
├── 0x0A00_sub.asm    # Subroutine at $0A00, ends at $0FFF
└── 0x1000_dat.asm    # Data region

Auto-Generated Header

All output files must include an auto-generated header:

; ============================================================
; AUTO-GENERATED FILE - DO NOT EDIT
; ============================================================
; Generated: 2025-01-22T10:30:00Z
; Source:    game.prg
; State:     game.orc (if loaded from state)
; ============================================================

This header appears at the top of every generated .asm file.

Formatting Reference

See disassembler.md for:

  • Instruction formatting and field specifications
  • Operand formatting by addressing mode
  • Data section format

Single File Output Structure

; ============================================================
; AUTO-GENERATED FILE - DO NOT EDIT
; ============================================================
; Generated: 2025-01-22T10:30:00Z
; Source:    game.prg
; ============================================================

         .ORG $0801

; === CODE SECTION ===

L_0810:      LDA #$00          ; Initialize border color
             STA $D020
             ...

; === SUBROUTINE: SUB_1000 ===

SUB_1000:    LDX #$00          ; Loop counter
             LDA $2000,X
             ...
             RTS

; === DATA SECTION ===

$0900    .BYTE $48,$45,$4C,$4C,$4F,$20,$57,$4F,$52,$4C,$44,$00,$00,$00,$00,$00  ; "HELLO WORLD....."
...

; End of disassembly

Segment Files Structure

Output is organized as:

output/
├── game.asm                # Main file with entry point
└── segments/
    ├── 0x0810_code.asm     # Code block at $0810
    ├── 0x1000_sub.asm      # Subroutine at $1000
    ├── 0x1200_sub.asm      # Subroutine at $1200
    └── 0x0900_dat.asm      # Data section at $0900

Main file (game.asm):

; ============================================================
; AUTO-GENERATED FILE - DO NOT EDIT
; ============================================================
; Generated: 2025-01-22T10:30:00Z
; Source:    game.prg
; Segments:  see segments/ directory
; ============================================================

         .ORG $0801

; === INCLUDES ===
.INCLUDE "segments/0x0810_code.asm"
.INCLUDE "segments/0x1000_sub.asm"
.INCLUDE "segments/0x1200_sub.asm"
.INCLUDE "segments/0x0900_dat.asm"

; End of disassembly

Subroutine segment (segments/0x1000_sub.asm):

; ============================================================
; AUTO-GENERATED FILE - DO NOT EDIT
; ============================================================
; Generated: 2025-01-22T10:30:00Z
; Source:    game.prg
; Segment:   subroutine @ $1000
; ============================================================

; === SUBROUTINE: SUB_1000 ===

SUB_1000:    LDX #$00          ; Loop counter
             LDA $2000,X
             ...
             RTS

; End of segment

Data segment (segments/0x0900_dat.asm):

; ============================================================
; AUTO-GENERATED FILE - DO NOT EDIT
; ============================================================
; Generated: 2025-01-22T10:30:00Z
; Source:    game.prg
; Segment:   data @ $0900
; ============================================================

; === DATA SECTION ===

$0900    .BYTE $48,$45,$4C,$4C,$4F,$20,$57,$4F,$52,$4C,$44,$00,$00,$00,$00,$00  ; "HELLO WORLD....."
...

; End of segment

Segment File Naming

Files are named 0x{address}_{type}.asm:

Type Suffix Example Description
Subroutine _sub 0x1000_sub.asm Code reached via JSR
Code _code 0x0810_code.asm Code not associated with a subroutine (e.g. entry)
Data _dat 0x0900_dat.asm Data section