Rumble doc (#1375)

* Rumble doc

* Fixes, suggested changes

* Improve padmgr retrace callback related code

* Name some rumble-adjacent things, further suggested changes

* Further suggested changes

* Suggested changes

5 files changed, 89 insertions, 30 deletions

diff --git a/include/functions.h b/include/functions.h
index 8df78a215..eddb732f8 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -1288,15 +1288,6 @@ void SsSram_Init(u32 addr, u8 handleType, u8 handleDomain, u8 handleLatency, u8
                  u8 handlePulse, u32 handleSpeed);
 void SsSram_Dma(void* dramAddr, size_t size, s32 direction);
 void SsSram_ReadWrite(u32 addr, void* dramAddr, size_t size, s32 direction);
-void func_800A9F30(PadMgr*, s32);
-void func_800A9F6C(f32, u8, u8, u8);
-void func_800AA000(f32, u8, u8, u8);
-void func_800AA0B4(void);
-void func_800AA0F0(void);
-u32 func_800AA148(void);
-void func_800AA15C(void);
-void func_800AA16C(void);
-void func_800AA178(u32);
 View* View_New(GraphicsContext* gfxCtx);
 void View_Free(View* view);
 void View_Init(View*, GraphicsContext*);
@@ -1693,9 +1684,6 @@ u64* SysUcode_GetUCodeBoot(void);
 size_t SysUcode_GetUCodeBootSize(void);
 u64* SysUcode_GetUCode(void);
 u64* SysUcode_GetUCodeData(void);
-void func_800D2E30(UnkRumbleStruct* arg0);
-void func_800D3140(UnkRumbleStruct* arg0);
-void func_800D3178(UnkRumbleStruct* arg0);
 void func_800D31A0(void);
 void func_800D31F0(void);
 void func_800D3210(void);
diff --git a/include/padmgr.h b/include/padmgr.h
index bddb136eb..65705949e 100644
--- a/include/padmgr.h
+++ b/include/padmgr.h
@@ -40,8 +40,8 @@ typedef struct PadMgr {
     /* 0x045C */ vu8 rumbleOffTimer; // amount of VI retraces to not rumble for, takes priority over rumbleOnTimer
     /* 0x045D */ vu8 rumbleOnTimer; // amount of VI retraces to rumble for
     /* 0x045E */ u8 isResetting;
-    /* 0x0460 */ void (*retraceCallback)(struct PadMgr* padMgr, s32 arg);
-    /* 0x0464 */ s32 retraceCallbackValue;
+    /* 0x0460 */ void (*retraceCallback)(struct PadMgr* padMgr, void* arg);
+    /* 0x0464 */ void* retraceCallbackArg;
 } PadMgr; // size = 0x468
 
 extern PadMgr gPadMgr;
@@ -70,4 +70,36 @@ void PadMgr_RumbleReset(PadMgr* padMgr);
 void PadMgr_RumbleSetSingle(PadMgr* padMgr, u32 port, u32 rumble);
 void PadMgr_RumbleSet(PadMgr* padMgr, u8* enable);
 
+// Retrace callback
+
+/**
+ * Sets the padmgr retrace callback that runs while waiting for controller input. The callback may be passed a single
+ * user-provided argument. The callback function should be `void (*)(PadMgr*, void*)`.
+ *
+ * @param callback callback to run before rumble state is updated for the current VI
+ * @param arg the argument to pass to the calback
+ *
+ * @see PADMGR_UNSET_RETRACE_CALLACK
+ */
+#define PADMGR_SET_RETRACE_CALLACK(padmgr, callback, arg) \
+    do {                                                  \
+        (padmgr)->retraceCallback = (callback);           \
+        (padmgr)->retraceCallbackArg = (arg);             \
+    } while (0)
+
+/**
+ * Unsets the current padmgr retrace callback if it and the argument are the same as the ones already registered.
+ *
+ * @param callback the callback to unset, if it is set
+ * @param arg the argument to unset, if it is set
+ *
+ * @see PADMGR_SET_RETRACE_CALLACK
+ */
+#define PADMGR_UNSET_RETRACE_CALLACK(padmgr, callback, arg)                                 \
+    if ((padmgr)->retraceCallback == (callback) && (padmgr)->retraceCallbackArg == (arg)) { \
+        (padmgr)->retraceCallback = NULL;                                                   \
+        (padmgr)->retraceCallbackArg = NULL;                                                \
+    }                                                                                       \
+    (void)0
+
 #endif
diff --git a/include/regs.h b/include/regs.h
index d9b0708fd..a873e34c9 100644
--- a/include/regs.h
+++ b/include/regs.h
@@ -171,6 +171,9 @@
 #define R_ITEM_AMMO_Y(i)                         VREG(68 + (i))
 #define R_ITEM_ICON_WIDTH(i)                     VREG(76 + (i))
 #define R_ITEM_BTN_WIDTH(i)                      VREG(80 + (i))
+#define R_GAME_OVER_RUMBLE_STRENGTH              VREG(90)
+#define R_GAME_OVER_RUMBLE_DURATION              VREG(91)
+#define R_GAME_OVER_RUMBLE_DECREASE_RATE         VREG(92)
 #define R_DISABLE_INPUT_DISPLAY                  HREG(47)
 #define R_ENABLE_PLAY_LOGS                       HREG(63)
 #define R_EN_GOROIWA_SPEED                       mREG(12)
diff --git a/include/rumble.h b/include/rumble.h
new file mode 100644
index 000000000..2ce8f4e71
--- /dev/null
+++ b/include/rumble.h
@@ -0,0 +1,51 @@
+#ifndef RUMBLE_H
+#define RUMBLE_H
+
+#include "ultra64.h"
+
+#define RUMBLE_MAX_REQUESTS 64
+
+typedef enum {
+    RUMBLE_STATE_CLEAR,
+    RUMBLE_STATE_RUNNING,
+    RUMBLE_STATE_RESET
+} RumbleState;
+
+typedef struct {
+    /* 0x000 */ u8 rumbleEnable[MAXCONTROLLERS];
+    /* 0x004 */ u8 reqStrengths[RUMBLE_MAX_REQUESTS];       // Source strength modulated by distance to the source
+    /* 0x044 */ u8 reqDurations[RUMBLE_MAX_REQUESTS];       // Duration until decreaseRate kicks in
+    /* 0x084 */ u8 reqDecreaseRates[RUMBLE_MAX_REQUESTS];   // Decreases the strength by this much every Vertical Retrace, once the strength hits 0 the request slot is freed
+    /* 0x0C4 */ u8 reqAccumulators[RUMBLE_MAX_REQUESTS];    // Starts at 0, incremented by the strength every Vertical Retrace
+    /* 0x104 */ u8 state;
+    /* 0x105 */ u8 updateEnabled;
+    /* 0x106 */ u16 onTimer;    // Duration for which there has been an active rumble request running
+    /* 0x108 */ u16 offTimer;   // Duration for which there has not been an active rumble request running, capped at 5
+    /* 0x10A */ u8 overrideStrength;    // overrides requests with these parameters
+    /* 0x10B */ u8 overrideDuration;
+    /* 0x10C */ u8 overrideDecreaseRate;
+    /* 0x10D */ u8 overrideAccumulator;
+} RumbleMgr; // size = 0x10E
+
+// internal
+
+void RumbleMgr_Init(RumbleMgr* rumbleMgr);
+void RumbleMgr_Destroy(RumbleMgr* rumbleMgr);
+void RumbleMgr_Update(RumbleMgr* rumbleMgr);
+
+// external
+
+void Rumble_Override(f32 distSq, u8 sourceStrength, u8 duration, u8 decreaseRate);
+void Rumble_Request(f32 distSq, u8 sourceStrength, u8 duration, u8 decreaseRate);
+
+void Rumble_Init(void);
+void Rumble_Destroy(void);
+
+s32 Rumble_Controller1HasRumblePak(void);
+
+void Rumble_Reset(void);
+void Rumble_ClearRequests(void);
+
+void Rumble_SetUpdateEnabled(u32 enable);
+
+#endif
diff --git a/include/z64.h b/include/z64.h
index 7128cd1b2..c63dcab5b 100644
--- a/include/z64.h
+++ b/include/z64.h
@@ -36,6 +36,7 @@
 #include "padmgr.h"
 #include "fault.h"
 #include "sched.h"
+#include "rumble.h"
 
 #define SCREEN_WIDTH  320
 #define SCREEN_HEIGHT 240
@@ -1814,22 +1815,6 @@ typedef struct {
 } struct_80166500; // size = 0x10
 
 typedef struct {
-    /* 0x000 */ u8 rumbleEnable[4];
-    /* 0x004 */ u8 unk_04[0x40];
-    /* 0x044 */ u8 unk_44[0x40];
-    /* 0x084 */ u8 unk_84[0x40];
-    /* 0x0C4 */ u8 unk_C4[0x40];
-    /* 0x104 */ u8 unk_104;
-    /* 0x105 */ u8 unk_105;
-    /* 0x106 */ u16 unk_106;
-    /* 0x108 */ u16 unk_108;
-    /* 0x10A */ u8 unk_10A;
-    /* 0x10B */ u8 unk_10B;
-    /* 0x10C */ u8 unk_10C;
-    /* 0x10D */ u8 unk_10D;
-} UnkRumbleStruct; // size = 0x10E
-
-typedef struct {
     /* 0x00 */ char unk_00[0x18];
     /* 0x18 */ s32 unk_18;
     /* 0x1C */ s32 y;