overlay: match five level functions, apply Naming Desk names and define level data

config/us/rnc1.us.yaml

@@ -650,7 +650,7 @@ segments:
           - [0x2ac6c, textbin, text_gap_00129b60_post_sdk_worker]
           - [0x2ac70, c, sdk/library/_dispRefImage]
           - [0x2ad80, c, sdk/library/disprefimagefield]
-          - [0x2af38, c, assembly/sdk/dma/dma_ref_image]
+          - [0x2af38, c, sdk/dma/dma_ref_image]
           - [0x2b0a4, textbin, text_gap_00129fb8_post_sdk_worker]
           - [0x2b0a8, c, sdk/dma/receive_data_from_ipu]
           - [0x2b12c, textbin, text_gap_0012a128_post_sdk_worker]

configure.py

@@ -1677,6 +1677,33 @@ def rewrite(match: re.Match[str]) -> str:
         fixed += 1
     return fixed
 
+def fix_mirror_symbols(asm_root: Path) -> int:
+    """Write splat's ``%lo(D_2xxxxxxx)`` / ``%hi(...)`` operands as immediates.
+
+    Code that ORs 0x20000000 into a RAM address (the uncached mirror) gets the
+    sum paired into a symbol, e.g. ``addiu $10, $10, %lo(D_20000020)`` for a
+    plain pointer step of 0x20.  No symbol lives there; the relocation only
+    makes objdiff reject a compiler object that emits the bare immediate.
+    The same words are written the way splat spells its other immediates.
+    """
+    pattern = re.compile(r"%(?P<op>lo|hi)\(D_(?P<addr>[23][0-9A-F]{7})\)")
+
+    def rewrite(match: re.Match[str]) -> str:
+        if int(match.group("addr"), 16) & 0x8000:
+            return match.group(0)  # a negative %lo: leave the pair to splat
+        if match.group("op") == "lo":
+            return f"(0x{match.group('addr')} & 0xFFFF)"
+        return f"(0x{match.group('addr')} >> 16)"
+
+    fixed = 0
+    for asm_file in asm_root.rglob("*.s"):
+        text = asm_file.read_text()
+        updated = pattern.sub(rewrite, text)
+        if updated != text:
+            asm_file.write_text(updated)
+            fixed += 1
+    return fixed
+
 def make_asm(config_path: Path, config: dict[str, Any]):
     with tempfile.TemporaryDirectory(dir=config_path, prefix="tmp_") as tmp_dir:
         tmp_path = Path(tmp_dir)
@@ -1740,6 +1767,9 @@ def make_asm(config_path: Path, config: dict[str, Any]):
         rewritten = fix_gp_rel_stores(dst_path)
         if rewritten:
             print(f"normalized gp-relative stores in {rewritten} expected asm files")
+        rewritten = fix_mirror_symbols(dst_path)
+        if rewritten:
+            print(f"unpaired uncached-mirror immediates in {rewritten} expected asm files")
 
         print(f"expected asm extracted to '{dst_path}'")
 
@@ -1760,6 +1790,7 @@ def make_asm(config_path: Path, config: dict[str, Any]):
             split.main([yaml_path], modes=["all"], verbose=False)
 
         rename_locals(asm_path)
+        fix_mirror_symbols(tmp_path / "asm")
 
         dst_path = dst_path.parent / "obj"
         tmp_obj_path = tmp_path / "obj"
@@ -2251,6 +2282,7 @@ class ArgsProtocol:
         clean(config_dir)
 
     split.main([args.YAML_FILE], modes=["all"], verbose=False)
+    fix_mirror_symbols(config_dir / "asm")
 
     fix_assets(config_dir, config)
 

include/rnc/gameplay/camera/follow_cam.h

@@ -6,7 +6,7 @@
 
 /*
  * State of the follow camera: the saved state of its camera record
- * (UpdateCam.saved_state, +0x70). FUN_L00_002e4fe8 writes `velocity`,
+ * (UpdateCam.saved_state, +0x70). follow_cam_focus_velocity writes `velocity`,
  * follow_camera_transition reads `follow` for its spring constants, and
  * fast_dec_timer counts `blend_timer` down. The follow_camera_set_* setters
  * (FUN_L00_002e8450..002e8680) each write one field and do nothing while the

include/rnc/gameplay/entities/moby.h

@@ -45,7 +45,7 @@ struct Moby {
     u16 flags;
     u16 occlusion;                    /* occlusion bits; 0x7F80 set by spawners */
     u64 spawn_frame;                  /* frame count at which it may respawn */
-    Vec4f rot;                        /* z: yaw (FUN_L00_00266448 compares it with atan2 to the hero) */
+    Vec4f rot;                        /* z: yaw (update_npc_dialogue compares it with atan2 to the hero) */
     u8 frame;                         /* animation frame */
     u8 prev_frame;                    /* frame index in prev_seq */
     u8 seq;                           /* animation sequence id */
@@ -65,13 +65,13 @@ struct Moby {
     u8 unk7C;
     u8 sound_slot;                    /* 0x7D: D_0013E550 slot of its looping sound, 0xFF: none (FUN_L00_00232670) */
     u8 anim_trigger_count;
-    u8 shadow_range;                  /* shadow range in units of 1024; 0x17 from FUN_L09_002c5990 near D_L09_00166F40 */
+    u8 shadow_range;                  /* shadow range in units of 1024; 0x17 from seeker_update near D_L09_00166F40 */
     u8 pad80[6];
     s16 unk86;
     u8 pad88[8];
     s32 glow_color;                   /* glow colour (class header + 0x40) */
     u32 collision;                    /* collision data, from the class header (MobyClass.collision) */
-    s32 collision_disable;            /* per-primitive collision disable bits; 1 while a carrier holds the moby (FUN_L00_002c7a58) */
+    s32 collision_disable;            /* per-primitive collision disable bits; 1 while a carrier holds the moby (glove_of_doom_update) */
     u8 pad9C[8];
     u8 hit_slot;                      /* hit-message slot (0xFF: none) */
     u8 padA5;

include/rnc/gameplay/hero.h

@@ -327,7 +327,7 @@ struct Hero {
     f32 unk414;                    /* 0x414 */
     s32 unk418;                    /* 0x418: set when velocity.z clamps to unk500.z, counts up */
     s16 unk41C;                    /* 0x41C */
-    s16 unk41E;                    /* 0x41E: set to 1 when FUN_L00_00233a78(velocity) < 0.001 */
+    s16 unk41E;                    /* 0x41E: set to 1 when gravity_z(velocity) < 0.001 */
     s32 unk420;                    /* 0x420: per-state scale_game_frames(N), compared with state_timer */
     f32 unk424;                    /* 0x424 */
     f32 unk428;                    /* 0x428 */
@@ -662,7 +662,7 @@ struct Hero {
     u8 unk12ED;                    /* 0x12ED */
     u8 unk12EE;                    /* 0x12EE */
     u8 pad_12EF[0x301];
-    struct Moby *ship_moby;        /* 0x15F0: the ship the hero is flying (l17 FUN_L17_002ed018) */
+    struct Moby *ship_moby;        /* 0x15F0: the ship the hero is flying (l17 fighter_jet_update) */
     s16 ship_oclass;               /* 0x15F4: its oclass, -1 when none */
     u8 ship_ammo;                  /* 0x15F6: shots left in the space levels; firing needs one and takes it (FUN_L11_003126f8) */
     u8 ship_ammo_max;              /* 0x15F7: ammo pips the ship HUD draws, lit while below ship_ammo */
@@ -732,7 +732,7 @@ struct Hero {
     u8 pad_1FF8[0x28];
     u8 *unk2020[6];                /* 0x2020: six moby slots, filled at the index a moby carries at +0x54 */
     u8 pad_2038[0x8];
-    struct Moby *unk2040;          /* 0x2040: nearest oclass 0x25D moby (FUN_L00_002d2ee8) */
+    struct Moby *unk2040;          /* 0x2040: nearest oclass 0x25D moby (metal_detector_update) */
     f32 unk2044;                   /* 0x2044: distance to unk2040; 100000 when none */
     s32 unk2048;                   /* 0x2048 */
     u8 pad_204C[0x4];
@@ -797,7 +797,7 @@ struct Hero {
     f32 unk22A4;                   /* 0x22A4 */
     struct HeroHealth health;      /* 0x22A8 */
     s32 unk22B4;                   /* 0x22B4 */
-    f32 unk22B8;                   /* 0x22B8: distance to the nearest carrying path this frame (FUN_L01_002f3120 keeps the minimum) */
+    f32 unk22B8;                   /* 0x22B8: distance to the nearest carrying path this frame (water_current_update keeps the minimum) */
     u8 pad_22BC[0x8];
     s32 unk22C4;                   /* 0x22C4 */
     s16 unk22C8;                   /* 0x22C8 */

include/rnc/input/pad_state.h

@@ -36,7 +36,7 @@ struct PadState {
     f32 analog[16];                     /* 0x100: [0..3] stick axes (-1..1), [4..15] pressure (0..1) */
     f32 analog_prev[16];                /* 0x140: copy of analog */
     u8 pad_180[0x9];
-    u8 unk189;                          /* 0x189: copied by FUN_L00_002d2ee8 on spawn */
+    u8 unk189;                          /* 0x189: copied by metal_detector_update on spawn */
     u8 pad_18A[0x4];
     s16 unk18E;                         /* 0x18E: cleared with unk190 by reset_global_state_fields */
     s32 unk190;                         /* 0x190 */

include/rnc/overlay/collision.h

@@ -6,14 +6,14 @@
 
 /*
  * Collision hit record filled by the overlay collision queries
- * (FUN_L00_001f0d60, FUN_L00_001f19a0, coll_line_fix) at D_L00_00173E40
+ * (coll_sphere, rig_probe, coll_line_fix) at D_L00_00173E40
  * (per-level copies at other addresses). FUN_L00_002133a8 copies +0x30 into
  * hero.motion.pos, +0x40 into hero.unk200, +0x20 into hero.unk210 and +0x18 into
  * hero.coll_hit_moby.
  */
 typedef struct {
     u8 pad0[0x18];
-    s32 moby;                      /* 0x18: passed to FUN_002141f8 (reads moby+0x34, moby+0x78); 0 when no moby was hit */
+    s32 moby;                      /* 0x18: passed to suck_get_aim_height (reads moby+0x34, moby+0x78); 0 when no moby was hit */
     s32 unk1C;                     /* 0x1C: > 0 gates copying point and the normal into the hero (shared/gameplay/hero/air_accel.c) */
     union {
         OvlQuad q;

include/rnc/overlay/leg_rig.h

@@ -11,7 +11,7 @@ typedef struct {
     /* 0x00 */ u8 unk0;
     /* 0x01 */ u8 attached;
     /* 0x02 */ u8 pad2[0xE];
-    /* 0x10 */ sceVu0FVECTOR rot;     /* quaternion, turned by FUN_L04_00292d48 */
+    /* 0x10 */ sceVu0FVECTOR rot;     /* quaternion, turned by rig_animate */
     /* 0x20 */ u8 pad20[0x20];
 } LegRigManip;
 
@@ -46,8 +46,8 @@ typedef struct {
     /* 0x00 */ s32 id;                /* animation sequence id */
     /* 0x04 */ f32 unk4;
     /* 0x08 */ f32 rate;              /* unk4 / multiply_global_factor_ed64(len * 2) */
-    /* 0x0C */ f32 start;             /* FUN_L04_002418b0(class slot, id) */
-    /* 0x10 */ f32 len;               /* FUN_L04_00241910(class slot, id) - start */
+    /* 0x0C */ f32 start;             /* animation_start(class slot, id) */
+    /* 0x10 */ f32 len;               /* animation_end(class slot, id) - start */
     /* 0x14 */ u8 pad14[0xC];
     /* 0x20 */ LegRigPhase phase[2];
 } LegRigAnim;

scripts/materialize-textbin-oracles.py

@@ -29,6 +29,17 @@
 PROJECT_ROOT = Path(__file__).resolve().parents[1]
 
 
+def _oracle_word(word: int, address: int, starts: dict[int, str]) -> str:
+    """One raw word, except a `jal` to a function of the same unit: that one is
+    written as `jal <symbol>` so the oracle carries the relocation our object
+    has (a recursive call would otherwise differ only in its relocation)."""
+    if word >> 26 == 3:
+        target = (address & 0xF0000000) | ((word & 0x3FFFFFF) << 2)
+        if target in starts:
+            return f"    jal {starts[target]}\n"
+    return f"    .word 0x{word:08X}\n"
+
+
 def parse_main_subsegments(path: Path) -> list[dict[str, object]]:
     """Read the project's simple `main.subsegments` YAML without PyYAML."""
     boundary = re.compile(
@@ -271,6 +282,7 @@ def install(
         obj.parent.mkdir(parents=True, exist_ok=True)
         try:
             body = ""
+            starts = {int(f["address"]): str(f["symbol"]) for f in row["functions"]}
             for function in row["functions"]:
                 name = str(function["symbol"])
                 start = int(function["address"])
@@ -294,7 +306,7 @@ def install(
                     else:
                         labels += retail
                 body += "".join(f"glabel {label}\n" for label in labels)
-                body += "".join(f"    .word 0x{word:08X}\n" for word in words)
+                body += "".join(_oracle_word(word, start + 4 * i, starts) for i, word in enumerate(words))
                 body += f".size {name}, . - {name}\n"
             rendered = (
                 '.include "macro.inc"\n.set noreorder\n.text\n'

src/assembly/math/convert_integer_to_float.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/math/convert_integer_to_float/func_001FA6C0.s",
-            func_001FA6C0);
+            convert_integer_to_float);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/math/multiply_global_factor_ed64.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/math/multiply_global_factor_ed64/func_001F96B0.s",
-            func_001F96B0);
+            scale_time);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/math/multiply_global_factor_ed70.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/math/multiply_global_factor_ed70/func_001F9730.s",
-            func_001F9730);
+            multiply_global_factor_ed70);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/math/multiply_global_scale.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/math/multiply_global_scale/func_001F96E8.s",
-            func_001F96E8);
+            multiply_global_scale);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/sdk/library/sceFsInit.c

@@ -28,7 +28,7 @@ struct FsWord4 {
 };
 
 /* Incomplete arrays keep these small globals on the absolute-address path. */
-extern u8 D_0011B980[];
+extern void invoke_sif_file_command_callback(void *, void *) __asm__("func_0011B980");
 extern s32 D_0012FC94[];
 extern s32 D_0012FC98[];
 extern s32 D_0012FCA0[];
@@ -62,11 +62,11 @@ s32 sceFsInit(void) {
     struct FsWord4 response_word;
 
     sceSifInitRpc(0);
-    *init_request++ = 0;
-    *init_request-- = 0;
+    init_request[0] = 0;
+    init_request[1] = 0;
     irq_state = DIntr();
     sceSifAddCmdHandler(0x80000011, &_sceFs_Rcv_Intr, D_00157FC0);
-    sceSifAddCmdHandler(0x80000013, D_0011B980, init_request);
+    sceSifAddCmdHandler(0x80000013, invoke_sif_file_command_callback, init_request);
 
     if (irq_state != 0) {
         EnableInterrupts();

src/assembly/textbin/audio/voices/sound_update.c

@@ -103,8 +103,8 @@ extern void scale_vector_xyz(void *out, void *a, f32 scale) __asm__("FUN_001f9a6
 extern f32 dot_vectors_xyz(void *a, void *b) __asm__("FUN_001f9ab0");
 extern f32 vector_length_xyz(void *a) __asm__("FUN_001f9af0");
 extern void normalize_vector_xyz(void *out, void *a, f32 len) __asm__("FUN_001f9bf8");
-extern void func_001F9CF8(void *out, void *a, void *b) __asm__("FUN_001f9cf8");
-extern void func_001FA2D8(void *out, void *a) __asm__("FUN_001fa2d8");
+extern void transform_vector_by_basis(void *out, void *a, void *b) __asm__("FUN_001f9cf8");
+extern void transpose_rotation_matrix(void *out, void *a) __asm__("FUN_001fa2d8");
 extern f32 convert_integer_to_float(s32) __asm__("func_001FA6C0");
 extern s32 truncate_float_to_s32(f32) __asm__("FUN_001fa6d0");
 extern void music_update() __asm__("FUN_00216290");
@@ -265,7 +265,7 @@ s32 sound_update(void) {
         if (D_0013E550.voices[slot_index].moby != NULL &&
             !(D_0013E550.voices[slot_index].flags & 8)) {
             if (D_0013E550.voices[slot_index].flags & 0x40) {
-                func_001F9CF8(&direction, &D_0013E550.voices[slot_index].position_offset,
+                transform_vector_by_basis(&direction, &D_0013E550.voices[slot_index].position_offset,
                               &moby->rotation);
                 add_vector_xyz(&direction, &direction, &moby->position);
                 subtract_vector_xyz(&relative_velocity, &direction,
@@ -385,7 +385,7 @@ s32 sound_update(void) {
         }
     }
 
-    func_001FA2D8(listener_matrix, camera_rows);
+    transpose_rotation_matrix(listener_matrix, camera_rows);
     for (slot_index = 0; slot_index < 30; slot_index++) {
         command_flags = voice_flags[slot_index];
         if (command_flags == 0) {

src/assembly/textbin/build_shrub_texture_dma.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/build_shrub_texture_dma/FUN_0022a330.s",
-            FUN_0022a330);
+            build_shrub_texture_dma);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/build_tfrag_texture_dma.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/build_tfrag_texture_dma/FUN_00234d48.s",
-            FUN_00234d48);
+            build_tfrag_texture_dma);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/build_tie_texture_dma.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/build_tie_texture_dma/FUN_002370c0.s",
-            FUN_002370c0);
+            build_tie_texture_dma);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/compute_tfrag_texture_usage.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/compute_tfrag_texture_usage/FUN_00234bd8.s",
-            FUN_00234bd8);
+            compute_tfrag_texture_usage);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/fast_bsphere_check.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/fast_bsphere_check/FUN_001fa728.s",
-            FUN_001fa728);
+            fast_bsphere_check);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/fast_dec_timer_s16.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/fast_dec_timer_s16/FUN_001f9770.s",
-            FUN_001f9770);
+            fast_dec_timer_s16);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/fast_draw_quad_real.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/fast_draw_quad_real/FUN_001f7d30.s",
-            FUN_001f7d30);
+            draw_geometry_quad);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/fast_intersect_vert.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/fast_intersect_vert/FUN_001f7a98.s",
-            FUN_001f7a98);
+            fast_intersect_vert);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/fast_tween_color.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/fast_tween_color/FUN_001fa6e0.s",
-            FUN_001fa6e0);
+            fast_tween_color);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public

src/assembly/textbin/fast_vec_normalize.c

@@ -3,7 +3,7 @@
 
 #ifndef NON_MATCHING
 INCLUDE_ASM("config/us/expected/asm/assembly/textbin/fast_vec_normalize/FUN_001f9bf8.s",
-            FUN_001f9bf8);
+            fast_vec_normalize);
 #else
 /* No C body on purpose: this unit is intentional low-level assembly
    (config/us/unit_categories.json), so it has no C goal and no public