Further documentation for overlay relocation (#1498)

* Further documentation for overlay relocation

* Suggested changes

* Format

* REL_ -> RELOC_

1 files changed, 29 insertions, 21 deletions

diff --git a/src/code/load.c b/src/code/load.c
index 888f2bdc9..570a968d0 100644
--- a/src/code/load.c
+++ b/src/code/load.c
@@ -1,14 +1,14 @@
 #include "global.h"
 
-s32 Overlay_Load(uintptr_t vRomStart, uintptr_t vRomEnd, void* vRamStart, void* vRamEnd, void* allocatedVRamAddr) {
+s32 Overlay_Load(uintptr_t vromStart, uintptr_t vromEnd, void* vramStart, void* vramEnd, void* allocatedRamAddr) {
     s32 pad[3];
     uintptr_t end;
-    OverlayRelocationSection* ovl;
-    u32 ovlOffset;
+    OverlayRelocationSection* ovlRelocs;
+    u32 relocSectionOffset;
     size_t size;
 
-    size = vRomEnd - vRomStart;
-    end = (uintptr_t)allocatedVRamAddr + size;
+    size = vromEnd - vromStart;
+    end = (uintptr_t)allocatedRamAddr + size;
 
     if (gOverlayLogSeverity >= 3) {
         // "Start loading dynamic link function"
@@ -17,44 +17,52 @@ s32 Overlay_Load(uintptr_t vRomStart, uintptr_t vRomEnd, void* vRamStart, void*
 
     if (gOverlayLogSeverity >= 3) {
         // "DMA transfer of TEXT, DATA, RODATA + rel (%08x-%08x)"
-        osSyncPrintf("TEXT,DATA,RODATA+relをＤＭＡ転送します(%08x-%08x)\n", allocatedVRamAddr, end);
+        osSyncPrintf("TEXT,DATA,RODATA+relをＤＭＡ転送します(%08x-%08x)\n", allocatedRamAddr, end);
     }
 
-    DmaMgr_RequestSync(allocatedVRamAddr, vRomStart, size);
+    // DMA the overlay, wait until transfer completes
+    DmaMgr_RequestSync(allocatedRamAddr, vromStart, size);
 
-    ovlOffset = ((s32*)end)[-1];
+    // The overlay file is expected to contain a 32-bit offset from the end of the file to the start of the
+    // relocation section.
+    relocSectionOffset = ((s32*)end)[-1];
+    ovlRelocs = (OverlayRelocationSection*)(end - relocSectionOffset);
 
-    ovl = (OverlayRelocationSection*)(end - ovlOffset);
     if (gOverlayLogSeverity >= 3) {
-        osSyncPrintf("TEXT(%08x), DATA(%08x), RODATA(%08x), BSS(%08x)\n", ovl->textSize, ovl->dataSize, ovl->rodataSize,
-                     ovl->bssSize);
+        osSyncPrintf("TEXT(%08x), DATA(%08x), RODATA(%08x), BSS(%08x)\n", ovlRelocs->textSize, ovlRelocs->dataSize,
+                     ovlRelocs->rodataSize, ovlRelocs->bssSize);
     }
 
     if (gOverlayLogSeverity >= 3) {
         osSyncPrintf("リロケーションします\n"); // "Relocate"
     }
 
-    Overlay_Relocate(allocatedVRamAddr, ovl, vRamStart);
+    // Relocate pointers in overlay code and data
+    Overlay_Relocate(allocatedRamAddr, ovlRelocs, vramStart);
 
-    if (ovl->bssSize != 0) {
+    // Clear bss if present, bss is located immediately following the relocations
+    if (ovlRelocs->bssSize != 0) {
         if (gOverlayLogSeverity >= 3) {
             // "Clear BSS area (% 08x-% 08x)"
-            osSyncPrintf("BSS領域をクリアします(%08x-%08x)\n", end, end + ovl->bssSize);
+            osSyncPrintf("BSS領域をクリアします(%08x-%08x)\n", end, end + ovlRelocs->bssSize);
         }
-        bzero((void*)end, ovl->bssSize);
+        bzero((void*)end, ovlRelocs->bssSize);
     }
 
-    size = (uintptr_t)&ovl->relocations[ovl->nRelocations] - (uintptr_t)ovl;
+    size = (uintptr_t)&ovlRelocs->relocations[ovlRelocs->nRelocations] - (uintptr_t)ovlRelocs;
+
     if (gOverlayLogSeverity >= 3) {
         // "Clear REL area (%08x-%08x)"
-        osSyncPrintf("REL領域をクリアします(%08x-%08x)\n", ovl, (uintptr_t)ovl + size);
+        osSyncPrintf("REL領域をクリアします(%08x-%08x)\n", ovlRelocs, (uintptr_t)ovlRelocs + size);
     }
 
-    bzero(ovl, size);
+    // Clear relocations, this space remains allocated and goes unused
+    bzero(ovlRelocs, size);
 
-    size = (uintptr_t)vRamEnd - (uintptr_t)vRamStart;
-    osWritebackDCache(allocatedVRamAddr, size);
-    osInvalICache(allocatedVRamAddr, size);
+    // Manually flush caches
+    size = (uintptr_t)vramEnd - (uintptr_t)vramStart;
+    osWritebackDCache(allocatedRamAddr, size);
+    osInvalICache(allocatedRamAddr, size);
 
     if (gOverlayLogSeverity >= 3) {
         // "Finish loading dynamic link function"