z_overlay and z_fbdemo_dlftbls (Transition overlay handling), clean up a lot of u32s used to store pointers (#1073)

* overlay matches

* prototypes

* fbdemo too

* virtual to physical

* names, cleanup, etc

* bss reordering

* uintptr stuff

* fixed now?

* one fix

* headers and such

* fixes'n'stuff

* XXX action

* docs of a sort

* useless error codes

* n

* format

* header? I barely know her!

Co-authored-by: petrie911 <petrie911@users.noreply.github.com>

src/code/z_lib.c

@@ -704,11 +704,29 @@ void* Lib_SegmentedToVirtual(void* ptr) {
 void* Lib_SegmentedToVirtualNull(void* ptr) {
     if (((uintptr_t)ptr >> 28) == 0) {
         return ptr;
+    } else {
+        return SEGMENTED_TO_VIRTUAL(ptr);
     }
-
-    return SEGMENTED_TO_VIRTUAL(ptr);
 }
 
+/*
+ * Converts a 32-bit virtual address (0x80XXXXXX) to a 24-bit physical address (0xXXXXXX). The NULL case accounts for
+ * the NULL virtual address being 0x00000000 and not 0x80000000. Used by transition overlays, which store their
+ * addresses in 24-bit fields.
+ */
+void* Lib_VirtualToPhysical(void* ptr) {
+    if (ptr == NULL) {
+        return NULL;
+    } else {
+        return (void*)VIRTUAL_TO_PHYSICAL(ptr);
+    }
+}
+
+/*
+ * Converts a 24-bit physical address (0xXXXXXX) to a 32-bit virtual address (0x80XXXXXX). The NULL case accounts for
+ * the NULL virtual address being 0x00000000 and not 0x80000000. Used by transition overlays, which store their
+ * addresses in 24-bit fields.
+ */
 void* Lib_PhysicalToVirtual(void* ptr) {
     if (ptr == NULL) {
         return NULL;
@@ -716,11 +734,3 @@ void* Lib_PhysicalToVirtual(void* ptr) {
         return (void*)PHYSICAL_TO_VIRTUAL(ptr);
     }
 }
-
-void* Lib_PhysicalToVirtualNull(void* ptr) {
-    if (ptr == NULL) {
-        return NULL;
-    } else {
-        return (void*)PHYSICAL_TO_VIRTUAL(ptr);
-    }
-}