Improve documentation of some SRAM routines (#114)

constants/hardware_constants.asm

@@ -8,8 +8,9 @@ DEF MBC1RomBank         EQU $2000
 DEF MBC1SRamBank        EQU $4000
 DEF MBC1SRamBankingMode EQU $6000
 
-DEF SRAM_DISABLE EQU $00
-DEF SRAM_ENABLE  EQU $0a
+DEF SRAM_DISABLE      EQU $00
+DEF SRAM_BANKING_MODE EQU $01
+DEF SRAM_ENABLE       EQU $0a
 
 DEF NUM_SRAM_BANKS EQU 4
 

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

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:

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

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

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,23 +645,23 @@ 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
 	push af
 	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

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

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

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

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

home/bankswitch2.asm

@@ -20,19 +20,19 @@ Bankswitch::
 JumpToAddress::
 	jp hl
 
-SwitchSRAMBankAndLatchClockData::
+OpenSRAM::
 	push af
-	ld a, $1
+	ld a, SRAM_BANKING_MODE
 	ld [MBC1SRamBankingMode], a
 	ld a, SRAM_ENABLE
 	ld [MBC1SRamEnable], a
 	pop af
 	ld [MBC1SRamBank], a
 	ret
 
-PrepareRTCDataAndDisableSRAM::
+CloseSRAM::
 	push af
-	ld a, $0
+	ld a, SRAM_DISABLE
 	ld [MBC1SRamBankingMode], a
 	ld [MBC1SRamEnable], a
 	pop af