Merge pull request #72 from BrianPugh/header-meta-data

store firmware metadata in vector table

Author: BrianPugh

README.md

@@ -131,6 +131,22 @@ Main stages to developing a feature:
 3. Implement your own function, possibly in `Core/Src/main.c`. There's a good chance your custom function will call the function in (2). You will also probably have to add `-Wl,--undefined=my_custom_function` to `LDFLAGS` in the Makefile so that it doesn't get optimized out as unreachable code.
 4. Add a patch definition to `patches/patches.py`.
 
+### Protocols
+We store information about how much external flash this firmware uses at internal-flash offset `0x01B8`.
+This location is in the HDMI-CEC handler in the vector-table; this is unused for all game-and-watch purposes, so serves as a safe, standardized spot to put a bit of data.
+At this location we store the following data:
+
+```C
+struct {
+  external_flash_size: 24; // This value * 4096 is the amount of external flash used by this firmware.
+  must_be_4: 4; // "magic" value that would never be valid in any real hdmi-cec firmware. 0x4 is in the hardware perhipheral space.
+  is_mario: 1;  // This is the mario firmware.
+  is_zelda: 1;  // This is the zelda firmware.
+  _unused: 2;   // Reserved for future use. All 0 for now.
+}
+```
+
+
 # Journal
 This is my first time ever developing patches for a closed source binary. [I documented my journey in hopes that it helps other people](docs/journal.md). If you have any recommendations, tips, tricks, or anything like that, please leave a github issue and I'll update the documentation!
 

patches/firmware.py

@@ -1,4 +1,6 @@
 import hashlib
+import struct
+from dataclasses import dataclass
 
 from colorama import Fore, Style
 from Crypto.Cipher import AES
@@ -12,7 +14,7 @@
     ParsingError,
 )
 from .patch import FirmwarePatchMixin
-from .utils import round_down_word, round_up_word
+from .utils import round_down_word, round_up_page, round_up_word
 
 
 def _val_to_color(val):
@@ -40,6 +42,55 @@ def __repr__(self):
         return "\n".join(substrs)
 
 
+METADATA_MAGIC = 0x4  # chosen because no real executable code starts with address 0x4
+
+
+@dataclass
+class HeaderMetaData:
+    """4 bytes of data that can be stored at the hdmi-cec handler in the vector-table (0x01B8)"""
+
+    external_flash_size: int  # Actual size in bytes (will be divided by 4096 for storage)
+
+    # 4 LSb are used for MAGIC
+    is_mario: bool  # 1 bit
+    is_zelda: bool  # 1 bit
+    # 2 MSb are free
+
+    def pack(self) -> bytes:
+        # Convert size to 4K blocks (right shift by 12)
+        blocks_4k = round_up_page(self.external_flash_size) >> 12
+
+        # Ensure the shifted value fits in 3 bytes
+        if not (0 <= blocks_4k < (1 << 24)):
+            raise ValueError(
+                "external_flash_size must fit in 3 bytes when divided by 4096"
+            )
+
+        # Pack the flags into a single byte
+        flags = METADATA_MAGIC | (int(self.is_mario) << 4) | (int(self.is_zelda) << 5)
+
+        # Pack as little-endian:
+        # - First 3 bytes: external_flash_size
+        # - Last byte: flags
+        return struct.pack("<I", (blocks_4k & 0xFFFFFF) | (flags << 24))
+
+    @classmethod
+    def unpack(cls, data: bytes) -> "HeaderMetaData":
+        # Unpack the 32-bit value
+        [value] = struct.unpack("<I", data)
+
+        # Extract fields
+        # Convert from 4K blocks back to bytes (left shift by 12)
+        external_flash_size = (value & 0xFFFFFF) << 12
+        flags = (value >> 24) & 0xFF
+        if (flags & 0x0F) != METADATA_MAGIC:
+            raise ValueError("Invalid Magic.")
+        is_mario = bool(flags & (1 << 4))
+        is_zelda = bool(flags & (1 << 5))
+
+        return cls(external_flash_size, is_mario, is_zelda)
+
+
 class Firmware(FirmwarePatchMixin, bytearray):
 
     RAM_BASE = 0x02000000
@@ -675,8 +726,23 @@ def move_to_compressed_memory(self, ext, size, reference):
         return new_loc
 
     def __call__(self):
+        from . import MarioGnW, ZeldaGnW
+
         self.int_pos = self.internal.empty_offset
-        return self.patch()
+        out = self.patch()
+        is_mario, is_zelda = False, False
+        if isinstance(self, MarioGnW):
+            is_mario = True
+        elif isinstance(self, ZeldaGnW):
+            is_zelda = True
+        metadata = HeaderMetaData(
+            external_flash_size=len(self.external),
+            is_mario=is_mario,
+            is_zelda=is_zelda,
+        )
+        # hdmi-cec = 0x01B8; not used in the gnw hardware.
+        self.internal.replace(0x01B8, metadata.pack())
+        return out
 
     def patch(self):
         """Device specific argument parsing and patching routine.