From 23ac63a261d4e4775539d17439089ff72bee5feb Mon Sep 17 00:00:00 2001
From: Christophe Parent <christopheparent@thatspaceandtime.org>
Date: Tue, 26 Dec 2023 19:03:13 -0800
Subject: [PATCH] Add comments to bank switching

---
 src/main.asm | 34 +++++++++++++++++++++++-----------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/src/main.asm b/src/main.asm
index bec0caa..68a01fb 100644
--- a/src/main.asm
+++ b/src/main.asm
@@ -24,7 +24,7 @@ JOYPAD_PORT           = $4016
 JOYPAD_PORT1          = $4016
 JOYPAD_PORT2          = $4017
 
-; GAME SPECIFIC DEFINES
+; game specific defines
 
 ObjectOffset          = $08
 
@@ -530,6 +530,8 @@ PauseModeFlag         = $07c6
 GroundMusicHeaderOfs  = $07c7
 AltRegContentFlag     = $07ca
 
+; mapper specific defines
+
 CurrentBank           = $15   ; The mapper is read-only; need to track its state separately
 CharsCopy             = $41   ; Reserving $41 and $42
 XStore                = $43   ; To store the X register
@@ -652,6 +654,7 @@ VictoryModeValue      = 2
 GameOverModeValue     = 3
 
 ;-------------------------------------------------------------------------------------
+; HEADER DEFINITION
 
 .segment "HEADER"
 
@@ -4804,10 +4807,10 @@ AreaDataAddrHigh:
     .byte >L_GroundArea22, >L_UndergroundArea1, >L_UndergroundArea2, >L_UndergroundArea3, >L_CastleArea1
     .byte >L_CastleArea2, >L_CastleArea3, >L_CastleArea4, >L_CastleArea5, >L_CastleArea6
 
-.segment "ENEMYDATA"
-
 ; ENEMY OBJECT DATA
 
+.segment "ENEMYDATA"
+
 ; level 1-4/6-4
 E_CastleArea1:
     .byte $76, $dd, $bb, $4c, $ea, $1d, $1b, $cc, $56, $5d
@@ -5055,10 +5058,10 @@ E_WaterArea3:
     .byte $56, $07, $88, $1b, $07, $9d, $2e, $65, $f0
     .byte $ff
 
-.segment "AREADATA"
-
 ; AREA OBJECT DATA
 
+.segment "AREADATA"
+
 ; level 1-4/6-4
 L_CastleArea1:
     .byte $9b, $07
@@ -17296,14 +17299,17 @@ BrickShatterEnvData:
     .byte $1a, $1a, $1c, $1d, $1d, $1e, $1e, $1f
 
 ;-------------------------------------------------------------------------------------
+; BANK SWITCHING
 
 .segment "BANKSWITCH"
 
+; We make sure to have Bank 0 loaded on startup, as the startup code is located there
 StartBankSwitch:
     ldx #$00
     jsr BankSwitch
     jmp Start
 
+; We make sure to have Bank 0 loaded at NMI, as the NMI code is located there; we switch back to the saved bank when we are done
 NonMaskableInterruptBankSwitch:
     ldx #$00
     jsr BankSwitchNoSave
@@ -17312,30 +17318,33 @@ NonMaskableInterruptBankSwitch:
     jsr BankSwitchNoSave
     rti
 
+; Area data is located in Bank 1; we switch back to Bank 0 when we are done
 AreaDataBankSwitch:
-    stx XStore
+    stx XStore           ; We need to save the value of X because X is used for bank switching
     ldx #$01
     jsr BankSwitchNoSave
     lda (AreaData),y
-    pha
+    pha                  ; We need to save the byte because A is used for bank switching
     ldx #$00
     jsr BankSwitchNoSave
     pla
     ldx XStore
     rts
 
+; Enemy data is located in Bank 1; we switch back to Bank 0 when we are done
 EnemyDataBankSwitch:
-    stx XStore
+    stx XStore           ; We need to save the value of X because X is used for bank switching
     ldx #$01
     jsr BankSwitchNoSave
     lda (EnemyData),y
-    pha
+    pha                  ; We need to save the byte because A is used for bank switching
     ldx #$00
     jsr BankSwitchNoSave
     pla
     ldx XStore
     rts
 
+; Graphic tiles and the graphics init copy routine are located in Bank 2; we switch back to Bank 0 when we are done
 CopyCharsBankSwitch:
     ldx #$02
     jsr BankSwitch
@@ -17344,6 +17353,7 @@ CopyCharsBankSwitch:
     jsr BankSwitch
     rts
 
+; The sound engine is located in Bank 2; we switch back to Bank 0 when we are done
 SoundEngineBankSwitch:
     ldx #$02
     jsr BankSwitchNoSave
@@ -17361,18 +17371,19 @@ BankSwitchNoSave:
     rts
 
 BankTable:
-    .byte $00, $01, $02
+    .byte $00, $01, $02 ; No need for Bank 3 here
 
 ;-------------------------------------------------------------------------------------
+; INTERRUPT VECTORS
 
 .segment "VECTORS"
 
-; INTERRUPT VECTORS
     .addr NonMaskableInterruptBankSwitch
     .addr StartBankSwitch
     .addr $fff0                          ; unused
 
 ;-------------------------------------------------------------------------------------
+; INSERTION OF GRAPHIC TILES
 
 .segment "CHARS"
 
@@ -17380,6 +17391,7 @@ Chars:
     .incbin "chars.bin"
 
 ;-------------------------------------------------------------------------------------
+; GRAPHICS INIT LOADING
 
 .segment "COPYCHARS"