Improve documentation of some SRAM routines (#114)

9 files changed, 56 insertions, 59 deletions

diff --git a/engine/battle/core.asm b/engine/battle/core.asm
index b7b10d06..b0f4f13f 100644
--- a/engine/battle/core.asm
+++ b/engine/battle/core.asm
@@ -6555,14 +6555,14 @@ LoadPlayerBackPic:
 	ld de, vBackPic
 	call InterlaceMergeSpriteBuffers
 	ld a, $0
-	call SwitchSRAMBankAndLatchClockData
+	call OpenSRAM
 	ld hl, vSprites
 	ld de, sSpriteBuffer1
 	ldh a, [hLoadedROMBank]
 	ld b, a
 	ld c, 7 * 7
 	call CopyVideoData
-	call PrepareRTCDataAndDisableSRAM
+	call CloseSRAM
 	ld a, $31
 	ldh [hStartTileID], a
 	hlcoord 1, 5
diff --git a/engine/battle/scale_sprites.asm b/engine/battle/scale_sprites.asm
index 2e33f536..eedd2e1d 100644
--- a/engine/battle/scale_sprites.asm
+++ b/engine/battle/scale_sprites.asm
@@ -3,9 +3,9 @@
 ; resulting in a 7*7 tile output sprite chunk
 ScaleSpriteByTwo:
 	ld a, $0
-	call SwitchSRAMBankAndLatchClockData
+	call OpenSRAM
 	call .ScaleSpriteByTwo
-	call PrepareRTCDataAndDisableSRAM
+	call CloseSRAM
 	ret
 
 .ScaleSpriteByTwo:
diff --git a/engine/debug/debug_menu.asm b/engine/debug/debug_menu.asm
index b90c16b2..25e36cae 100644
--- a/engine/debug/debug_menu.asm
+++ b/engine/debug/debug_menu.asm
@@ -1601,7 +1601,7 @@ Data_ff2eb:
 
 Func_ff2f3:
 	push hl
-	call Func_ff316
+	call DebugEnableSRAM
 	ld a, b
 	ld [MBC1SRamBank], a
 	ld bc, sBox2 - sBox1
@@ -1615,18 +1615,18 @@ Func_ff2f3:
 	ld bc, sBox5 - sBox1 + 1
 	call Func_ff32a
 	ld [sBox5], a
-	call Func_ff321
+	call DebugDisableSRAM
 	ret
 
-Func_ff316:
-	ld a, 1
+DebugEnableSRAM: ; duplicate of EnableSRAM
+	ld a, SRAM_BANKING_MODE
 	ld [MBC1SRamBankingMode], a
 	ld a, SRAM_ENABLE
 	ld [MBC1SRamEnable], a
 	ret
 
-Func_ff321:
-	ld a, 0
+DebugDisableSRAM: ; duplicate of DisableSRAM
+	ld a, SRAM_DISABLE
 	ld [MBC1SRamBankingMode], a
 	ld [MBC1SRamEnable], a
 	ret
diff --git a/engine/menus/main_menu.asm b/engine/menus/main_menu.asm
index ca837143..06f3c2a7 100644
--- a/engine/menus/main_menu.asm
+++ b/engine/menus/main_menu.asm
@@ -276,13 +276,11 @@ DisplayOptionMenu:
 	ret
 
 CheckForPlayerNameInSRAM:
-; Check if the player name data in SRAM has a string terminator character
-; (indicating that a name may have been saved there) and return whether it does
-; in carry.
 	ld a, SRAM_ENABLE
 	ld [MBC1SRamEnable], a
-	ld a, $1
+	ld a, SRAM_BANKING_MODE
 	ld [MBC1SRamBankingMode], a
+	assert SRAM_BANKING_MODE == BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld b, NAME_LENGTH
 	ld hl, sPlayerName
@@ -292,7 +290,6 @@ CheckForPlayerNameInSRAM:
 	jr z, .found
 	dec b
 	jr nz, .loop
-; not found
 	xor a
 	ld [MBC1SRamEnable], a
 	ld [MBC1SRamBankingMode], a
diff --git a/engine/menus/save.asm b/engine/menus/save.asm
index fb7526b3..5b7cebc5 100644
--- a/engine/menus/save.asm
+++ b/engine/menus/save.asm
@@ -32,8 +32,8 @@ FileDataDestroyedText:
 	text_end
 
 LoadSAV0:
-	call EnableSRAMAndLatchClockData
-	ld a, $1
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 ; This vc_hook does not have to be in any particular location.
 ; It is defined here because it refers to the same labels as the two lines below.
@@ -80,8 +80,8 @@ LoadSAV0:
 	jp SAVGoodChecksum
 
 LoadSAV1:
-	call EnableSRAMAndLatchClockData
-	ld a, $1
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld hl, sGameData
 	ld bc, sGameDataEnd - sGameData
@@ -98,8 +98,8 @@ LoadSAV1:
 	jp SAVGoodChecksum
 
 LoadSAV2:
-	call EnableSRAMAndLatchClockData
-	ld a, $1
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld hl, sGameData
 	ld bc, sGameDataEnd - sGameData
@@ -123,7 +123,7 @@ SAVBadCheckSum:
 	scf
 
 SAVGoodChecksum:
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 LoadSAVIgnoreBadCheckSum:
@@ -195,8 +195,8 @@ OlderFileWillBeErasedText:
 	text_end
 
 SaveSAVtoSRAM0:
-	call EnableSRAMAndLatchClockData
-	ld a, $1
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld hl, wPlayerName
 	ld de, sPlayerName
@@ -220,13 +220,13 @@ SaveSAVtoSRAM0:
 	ld bc, sGameDataEnd - sGameData
 	call SAVCheckSum
 	ld [sMainDataCheckSum], a
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 SaveSAVtoSRAM1:
 ; stored pokémon
-	call EnableSRAMAndLatchClockData
-	ld a, $1
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld hl, wBoxDataStart
 	ld de, sCurBoxData
@@ -236,12 +236,12 @@ SaveSAVtoSRAM1:
 	ld bc, sGameDataEnd - sGameData
 	call SAVCheckSum
 	ld [sMainDataCheckSum], a
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 SaveSAVtoSRAM2:
-	call EnableSRAMAndLatchClockData
-	ld a, $1
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld hl, wPartyDataStart
 	ld de, sPartyData
@@ -262,7 +262,7 @@ SaveSAVtoSRAM2:
 	ld bc, sGameDataEnd - sGameData
 	call SAVCheckSum
 	ld [sMainDataCheckSum], a
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 SaveSAVtoSRAM::
@@ -386,7 +386,7 @@ WhenYouChangeBoxText:
 CopyBoxToOrFromSRAM:
 ; copy an entire box from hl to de with b as the SRAM bank
 	push hl
-	call EnableSRAMAndLatchClockData
+	call EnableSRAM
 	ld a, b
 	ld [MBC1SRamBank], a
 	ld bc, wBoxDataEnd - wBoxDataStart
@@ -404,7 +404,7 @@ CopyBoxToOrFromSRAM:
 	call SAVCheckSum
 	ld [sBank2AllBoxesChecksum], a ; sBank3AllBoxesChecksum
 	call CalcIndividualBoxCheckSums
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 DisplayChangeBoxMenu:
@@ -500,14 +500,14 @@ BoxNoText:
 EmptyAllSRAMBoxes:
 ; marks all boxes in SRAM as empty (initialisation for the first time the
 ; player changes the box)
-	call EnableSRAMAndLatchClockData
-	ld a, 2
+	call EnableSRAM
+	ld a, BANK("Saved Boxes 1")
 	ld [MBC1SRamBank], a
 	call EmptySRAMBoxesInBank
-	ld a, 3
+	ld a, BANK("Saved Boxes 2")
 	ld [MBC1SRamBank], a
 	call EmptySRAMBoxesInBank
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 EmptySRAMBoxesInBank:
@@ -541,14 +541,14 @@ EmptySRAMBox:
 GetMonCountsForAllBoxes:
 	ld hl, wBoxMonCounts
 	push hl
-	call EnableSRAMAndLatchClockData
-	ld a, $2
+	call EnableSRAM
+	ld a, BANK("Saved Boxes 1")
 	ld [MBC1SRamBank], a
 	call GetMonCountsForBoxesInBank
-	ld a, $3
+	ld a, BANK("Saved Boxes 2")
 	ld [MBC1SRamBank], a
 	call GetMonCountsForBoxesInBank
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	pop hl
 
 ; copy the count for the current box from WRAM
@@ -581,8 +581,8 @@ SAVCheckRandomID:
 ; checks if Sav file is the same by checking player's name 1st letter
 ; and the two random numbers generated at game beginning
 ; (which are stored at wPlayerID)s
-	call EnableSRAMAndLatchClockData
-	ld a, $01
+	call EnableSRAM
+	ld a, BANK("Save Data")
 	ld [MBC1SRamBank], a
 	ld a, [sPlayerName]
 	and a
@@ -604,7 +604,7 @@ SAVCheckRandomID:
 	ld a, [wPlayerID + 1]
 	cp h
 .next
-	ld a, $00
+	ld a, SRAM_DISABLE
 	ld [MBC1SRamBankingMode], a
 	ld [MBC1SRamEnable], a
 	ret
@@ -645,15 +645,15 @@ LoadHallOfFameTeams:
 	; fallthrough
 
 HallOfFame_Copy:
-	call EnableSRAMAndLatchClockData
+	call EnableSRAM
 	xor a
 	ld [MBC1SRamBank], a
 	call CopyData
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 ClearSAV:
-	call EnableSRAMAndLatchClockData
+	call EnableSRAM
 	ld a, $4
 .loop
 	dec a
@@ -661,7 +661,7 @@ ClearSAV:
 	call PadSRAM_FF
 	pop af
 	jr nz, .loop
-	call DisableSRAMAndPrepareClockData
+	call DisableSRAM
 	ret
 
 PadSRAM_FF:
@@ -671,14 +671,14 @@ PadSRAM_FF:
 	ld a, $ff
 	jp FillMemory
 
-EnableSRAMAndLatchClockData:
-	ld a, $1
+EnableSRAM:
+	ld a, SRAM_BANKING_MODE
 	ld [MBC1SRamBankingMode], a
 	ld a, SRAM_ENABLE
 	ld [MBC1SRamEnable], a
 	ret
 
-DisableSRAMAndPrepareClockData:
+DisableSRAM:
 	ld a, SRAM_DISABLE
 	ld [MBC1SRamBankingMode], a
 	ld [MBC1SRamEnable], a
diff --git a/engine/movie/hall_of_fame.asm b/engine/movie/hall_of_fame.asm
index db3ab617..5f441343 100644
--- a/engine/movie/hall_of_fame.asm
+++ b/engine/movie/hall_of_fame.asm
@@ -201,12 +201,12 @@ HoFLoadPlayerPics:
 	ld a, BANK(RedPicFront)
 	call UncompressSpriteFromDE
 	ld a, $0
-	call SwitchSRAMBankAndLatchClockData
+	call OpenSRAM
 	ld hl, sSpriteBuffer1
 	ld de, sSpriteBuffer0
 	ld bc, $310
 	call CopyData
-	call PrepareRTCDataAndDisableSRAM
+	call CloseSRAM
 	ld de, vFrontPic
 	call InterlaceMergeSpriteBuffers
 	ld de, RedPicBack
diff --git a/engine/movie/oak_speech/oak_speech.asm b/engine/movie/oak_speech/oak_speech.asm
index 6e09cfad..3884d271 100644
--- a/engine/movie/oak_speech/oak_speech.asm
+++ b/engine/movie/oak_speech/oak_speech.asm
@@ -232,12 +232,12 @@ IntroDisplayPicCenteredOrUpperRight:
 	ld a, b
 	call UncompressSpriteFromDE
 	ld a, $0
-	call SwitchSRAMBankAndLatchClockData
+	call OpenSRAM
 	ld hl, sSpriteBuffer1
 	ld de, sSpriteBuffer0
 	ld bc, $310
 	call CopyData
-	call PrepareRTCDataAndDisableSRAM
+	call CloseSRAM
 	ld de, vFrontPic
 	call InterlaceMergeSpriteBuffers
 	pop bc
diff --git a/engine/movie/title.asm b/engine/movie/title.asm
index c012e92a..d0a97a6f 100644
--- a/engine/movie/title.asm
+++ b/engine/movie/title.asm
@@ -378,10 +378,10 @@ IncrementResetCounter:
 
 FillSpriteBuffer0WithAA:
 	xor a
-	call SwitchSRAMBankAndLatchClockData
+	call OpenSRAM
 	ld hl, sSpriteBuffer0
 	ld bc, $20
 	ld a, $aa
 	call FillMemory
-	call PrepareRTCDataAndDisableSRAM
+	call CloseSRAM
 	ret
diff --git a/engine/pikachu/pikachu_pic_animation.asm b/engine/pikachu/pikachu_pic_animation.asm
index 125313ac..8abbb1f9 100644
--- a/engine/pikachu/pikachu_pic_animation.asm
+++ b/engine/pikachu/pikachu_pic_animation.asm
@@ -666,12 +666,12 @@ DecompressRequestPikaPicAnimGFX:
 	ld a, b
 	call UncompressSpriteFromDE
 	ld a, BANK(sSpriteBuffer1)
-	call SwitchSRAMBankAndLatchClockData
+	call OpenSRAM
 	ld hl, sSpriteBuffer1
 	ld de, sSpriteBuffer0
 	ld bc, SPRITEBUFFERSIZE * 2
 	call CopyData
-	call PrepareRTCDataAndDisableSRAM
+	call CloseSRAM
 	ld a, [wPikaPicAnimCurGraphicID]
 	call LookUpTileOffsetForCurrentPikaPicAnimGFX
 	call GetPikaPicVRAMAddressForNewGFX