;*******************************************************************************
; SOUPER Mapper for the Atari 7800 ProSystem                                   *
;*******************************************************************************
; - 512KB of ROM
;   \- 16KB Paged Segment
;    - 16KB Fixed Segment
; - 32KB of EXRAM
;   \- Flat 16KB Mode
;    - Segmented 8KB + 4KB + 4KB Mode
; - Maria Fetch Trapping
; - BupChip Expansion Audio *
;-------------------------------------------------------------------------------


;-------------------------------------------------------------------------------
; Memory Map (Sally)                                                           /
;------------------------------------------------------------------------------
; Upon reset, SOUPER partitions Sally's view of memory as shown below...
;
;               | $xx00        | $xx40        | $xx80        | $xxC0
;---------------------------------------------------------------------------
; $00xx - $3Fxx |...........................................................
;---------------|-----------------------------------------------------------
; $40xx - $7Fxx | EXRAM (16KB)
;---------------|-----------------------------------------------------------
; $80xx - $BFxx | Paged ROM (16KB, BANK_SEL)
; $C0xx - $FFxx | Fixed ROM (16KB, BANK_F_SEL / END) *
;---------------------------------------------------------------------------
;
; This resembles a 512KB SUPER Cartridge with 16KB of EXRAM and is intended to
; simplify software migration. The 16KB EXRAM viewport from $4000 - $7FFF is
; fixed to the lower 16KB of SOUPER's full 32KB of EXRAM.
;
; The Fixed ROM segment from $C000 - $FFFF contains the last 16KB page ($1F)
; of the 512KB ROM, unless the mapper variant both supports and is currently
; in Flash ROM programming mode (see "Registers").
;
;
; Setting MODE,2 (MODE_EXS) enables EXRAM Segmented Mode...
;
;               | $xx00        | $xx40        | $xx80        | $xxC0
;---------------------------------------------------------------------------
; $00xx - $3Fxx |...........................................................
;---------------|-----------------------------------------------------------
; $40xx - $5Fxx | EXRAM (8KB)
; $60xx - $6Fxx | EXRAM (4KB, EXRAM_V_SEL)
; $70xx - $7Fxx | EXRAM (4KB, EXRAM_D_SEL)
;---------------|-----------------------------------------------------------
; $80xx - $BFxx | Paged ROM (16KB, BANK_SEL)
; $C0xx - $FFxx | Fixed ROM (16KB, BANK_F_SEL / END) *
;---------------------------------------------------------------------------
;
; This allows access to all 32KB of EXRAM using two 4KB pages. The 8KB segment
; in $4000 - $5FFF is fixed to the first 8KB of SOUPER's full 32KB of EXRAM.
;---------------------------------------
EXRAM_BASE	EQU $4000
EXRAM_SIZE	EQU $4000
EXRAM_TOP	EQU (EXRAM_BASE + EXRAM_SIZE)

EXRAM_PAGES	EQU 8

EXRAMV_BASE	EQU $6000
EXRAMV_SIZE	EQU $1000
EXRAMV_TOP	EQU (EXRAMV_BASE + EXRAMV_SIZE)

EXRAMD_BASE	EQU $7000
EXRAMD_SIZE	EQU $1000
EXRAMD_TOP	EQU (EXRAMD_BASE + EXRAMD_SIZE)

EXRAM_V_BASE	EQU $6000
EXRAM_V_SIZE	EQU $1000
EXRAM_V_TOP	EQU (EXRAM_V_BASE + EXRAM_V_SIZE)

EXRAM_D_BASE	EQU $7000
EXRAM_D_SIZE	EQU $1000
EXRAM_D_TOP	EQU (EXRAM_D_BASE + EXRAM_D_SIZE)

ROM_BASE	EQU $8000

BANK_SIZE	EQU $4000
BANK_SWAP	EQU ROM_BASE
BANK_FIXED	EQU (ROM_BASE + BANK_SIZE)


;-------------------------------------------------------------------------------
; Memory Map (Maria)                                                           /
;------------------------------------------------------------------------------
; Maria's view of memory is identical to Sally's until MODE,0 (MODE_MFT) is set,
; this enables Maria Fetch Trapping and repartitions her arrangement to...
;
;               | $xx00        | $xx40        | $xx80        | $xxC0
;---------------------------------------------------------------------------
; $00xx - $3Fxx |...........................................................
;---------------|-----------------------------------------------------------
; $40xx - $7Fxx | EXRAM
;---------------|-----------------------------------------------------------
; $80xx - $BFxx | Paged ROM (16KB, BANK_SEL)
;---------------|-----------------------------------------------------------
; $C0xx - $FFxx | EXRAM
;---------------------------------------------------------------------------
;
; The EXRAM segment from $C000 - $FFFF is identical to the one visible by Sally
; in $4000 - $7FFF, including whether paging is enabled (MODE_EXS). This allows
; Maria to use her Holey DMA feature while reading graphic data from EXRAM.
;
;
; Setting MODE,1 (MODE_CHR) will alter Maria's view further...
;
;               | $xx00        | $xx40        | $xx80        | $xxC0
;---------------------------------------------------------------------------
; $00xx - $3Fxx |...........................................................
;---------------|-----------------------------------------------------------
; $40xx - $7Fxx | EXRAM
;---------------|-----------------------------------------------------------
; $80xx - $9Fxx | Fixed ROM ($C000 - $DFFF)
;---------------|-----------------------------------------------------------
; $A0xx - $AFxx | CHR_A                       | CHR_B
;---------------|-----------------------------------------------------------
; $C0xx - $FFxx | EXRAM
;---------------------------------------------------------------------------
;
; The Fixed ROM segment from $8000 - $9FFF is identical to the lower 8KB of
; Fixed ROM visible to Sally in $C000 - $DFFF. This region is intended for
; static resources such as fonts or status bar graphics.
;
; The CHR_A and CHR_B regions automatically route Maria's fetches to different
; addresses within the cartridge's ROM. Two selects are given, which are chosen
; by the state of A7 within $A000 - $AFFF (CHR_A == '0', CHR_B == '1') enabling
; access to all 512KB of ROM through two 2KB pages.
;
; Any empty areas will respond to both Maria and Sally's fetches identically.
;---------------------------------------
CHR_A		EQU $A000
CHR_B		EQU $A080

VMEM8_BASE	EQU $8000
VMEM16_BASE	EQU $C000


;-------------------------------------------------------------------------------
; Registers                                                                    /
;------------------------------------------------------------------------------
; SOUPER's registers are accessed by writing above $8000 - with an upper limit
; and feature set defined by the mapper variant...
;
;        | ACTIVE RANGES | FLASH ROM SUPPORT
; -------------------------------------------
; SOUPER | $8000 - $FFFF | NO
; SUBPAR | $8000 - $FFFF | NO
; SUBLET | $8000 - $BFFF | YES
; -------------------------------------------
;
; Only the defined set from $8000 - $8007 should be used and undefined bits in
; all registers zeroed in order to ensure compatibility.
;
; Flash ROM support consists of a write signal (romWrite_n) along with three 
; new registers (FLASH_UNLOCK, FLASH_PROTECT, BANK_F_SEL) which control both
; protection of the write signal and use of the fixed bank for programming.
;
; While SUBPAR does not contain Flash ROM support, it does have a romWrite_n
; pin which is stuck HIGH. This was intended to allow a single board layout to
; support both SUBPAR or SUBLET.
;---------------------------------------
BANK_SEL	EQU $8000
; -/W
; Paged ROM Bank Select (%xxxBBBBB)
; Select the 16KB ROM page visible in $8000 - $BFFF.


CHR_A_SEL	EQU $8001
CHR_B_SEL	EQU $8002
; -/W
; ROM Character 'A/B' Page Selects (%BBBBBBBS)
;
; 111
; 210 FEDCBA98 76543210
; ... ........ BBBBBBBS : CHR_A/B (!)
; ... 101xHHHH !LLLLLLL : ADDRESS
; BBB BBBBHHHH SLLLLLLL = ROM


SOUPMODE_SEL	EQU $8003
MODE_SEL	EQU $8003
MODE_EXS	EQU $04
MODE_CHR	EQU $02
MODE_MFT	EQU $01
; -/W
; Operating Mode (%xxxxxECS, '1' == Enable)
; 7 - 3 : ???
; 2 : EXRAM Segmented Memory (Paging Support)
; 1 : Character Remapping
; 0 : Maria Fetch Trapping


EXRAMV_SEL	EQU $8004
EXRAM_V_SEL	EQU $8004
; -/W
; EXRAM Video Page Select
; Select the 4KB EXRAM page visible in $6000 - $6FFF when MODE,2 is set.


EXRAMD_SEL	EQU $8005
EXRAM_D_SEL	EQU $8005
; -/W
; EXRAM Data Page Select
; Select the 4KB EXRAM page visible in $7000 - $7FFF when MODE,2 is set.


AUDIO_CMD	EQU $8007
; -/W
; Audio Command
; Written value is sent to the BupChip.




FLASH_UNLOCK	EQU $8080
; -/W
; Flash Write Unlock
; Writing the ASCII sequence "WR" ($57,$52) will unlock the flash for write
; access in $C000 - $FFFF and allow selecting a 16KB ROM page with BANK_F_SEL.


FLASH_PROTECT	EQU $8081
; -/W
; Flash Write Protect
; Any value disables write access to the flash and sets BANK_F to $1F.


BANK_F_SEL	EQU $8082
; -/W
; Fixed ROM Bank Select (%xxxBBBBB)
; Select the 16KB ROM page visible in $C000 - $FFFF, this can only be altered
; after a flash unlock procedure.
