UTTORI ASM · IN DEVELOPMENT

6502 family memory maps

Understand how raw 6502 and NES CPU addresses map into output files.

A 65xx CPU address is 16-bit. How that address becomes a file offset depends on the target.

6502 family behavior

Raw origin (65xx.raw, 65xx.ca65-raw)

The flat address space is an identity map: offset = address − origin. Addresses below origin or above $FFFF are rejected. org moves the write position. Writing at $8000 with origin 0 really does emit 32,768 prefix bytes. Set origin to the load address you actually want at file offset 0.

org $8000
BankStart:
  nop

base address changes the logical address seen by labels and operands without seeking the physical output cursor. base off returns to the saved physical/base relationship. pushpc / pullpc and pushbase / pullbase save and restore those cursors. Pulling an empty stack is an error.

NES iNES layout (65xx.nes)

Writes follow the current .segment load region. The default linker config, used when linkerConfig is omitted, is:

MEMORY {
    ROM: start = $8000, size = $8000, file = %O, fill = yes, fillval = $FF ;
}
SEGMENTS {
    CODE: load = ROM, type = ro ;
}

A 16-byte iNES header is synthesized from PRG size when header is omitted: magic NES\x1A, PRG bank count, CHR banks 0 (CHR-RAM). Supply your own 16 (or more) header bytes to set mapper, mirroring, NES 2.0 flags, and CHR ROM size.

Overlay segments (run ≠ load) use base so labels live in RAM while bytes go into PRG:

.segment "CODE"
  nop
.segment "OVERLAY"
OverlayStart:
  lda #$01
.segment "CODE"
  lda #<__OVERLAY_LOAD__
  lda #>__OVERLAY_RUN__

define = yes on a segment exports __NAME_LOAD__, __NAME_RUN__, __NAME_SIZE__, and __NAME_RUN_END__. The SYMBOLS block is evaluated after the last segment closes. file = "" MEMORY regions are RAM: they never appear in the image.

This is the selected MEMORY/SEGMENTS load/run/fill model used by the NES integration fixture. It is not a general ld65 linker. FILES, FORMAT, bank switching objects, and relocatable o65 output are out of scope.

See src/linker-config.ts for the accepted attribute subset (start, size, file, fill, fillval, load, run, define, type, value).