Documentation for fault.c and fault_drawer.c (#1106)

* Mostly document fault and fault_drawer

* FaultDrawer printf functions return s32

* Review Suggestions for comments

Co-authored-by: EllipticEllipsis <73679967+EllipticEllipsis@users.noreply.github.com>

* Some further review suggestions

* Further changes from suggestions

* Fix Fault_AddClient doc comment

* Bug comment for memdump overrun, add more to Fault_PadCallback bug comment

* mb -> MB, comment about bss above externs

* Fix color codes

Co-authored-by: EllipticEllipsis <73679967+EllipticEllipsis@users.noreply.github.com>

10 files changed, 173 insertions, 189 deletions

diff --git a/include/fault.h b/include/fault.h
new file mode 100644
index 000000000..642d581d8
--- /dev/null
+++ b/include/fault.h
@@ -0,0 +1,92 @@
+#ifndef FAULT_H
+#define FAULT_H
+
+#include "padmgr.h"
+
+// These are the same as the 3-bit ansi color codes
+#define FAULT_COLOR_BLACK      0
+#define FAULT_COLOR_RED        1
+#define FAULT_COLOR_GREEN      2
+#define FAULT_COLOR_YELLOW     3
+#define FAULT_COLOR_BLUE       4
+#define FAULT_COLOR_MAGENTA    5
+#define FAULT_COLOR_CYAN       6
+#define FAULT_COLOR_WHITE      7
+// Additional color codes
+#define FAULT_COLOR_DARK_GRAY  8
+#define FAULT_COLOR_LIGHT_GRAY 9
+
+#define FAULT_COLOR_STRINGIFY(s) #s
+#define FAULT_COLOR_EXPAND_AND_STRINGIFY(s) FAULT_COLOR_STRINGIFY(s)
+
+#define FAULT_ESC '\x1A'
+#define FAULT_COLOR(n) "\x1A" FAULT_COLOR_EXPAND_AND_STRINGIFY(FAULT_COLOR_ ## n)
+
+typedef struct FaultClient {
+    /* 0x00 */ struct FaultClient* next;
+    /* 0x04 */ void* callback;
+    /* 0x08 */ void* arg0;
+    /* 0x0C */ void* arg1;
+} FaultClient; // size = 0x10
+
+typedef struct FaultAddrConvClient {
+    /* 0x00 */ struct FaultAddrConvClient* next;
+    /* 0x04 */ void* callback;
+    /* 0x08 */ void* arg;
+} FaultAddrConvClient; // size = 0xC
+
+// Initialization
+
+void Fault_Init(void);
+
+// Fatal Errors
+
+void Fault_AddHungupAndCrashImpl(const char* exp1, const char* exp2);
+void Fault_AddHungupAndCrash(const char* file, s32 line);
+
+// Client Registration
+
+void Fault_AddClient(FaultClient* client, void* callback, void* arg0, void* arg1);
+void Fault_RemoveClient(FaultClient* client);
+
+void Fault_AddAddrConvClient(FaultAddrConvClient* client, void* callback, void* arg);
+void Fault_RemoveAddrConvClient(FaultAddrConvClient* client);
+
+// For use in Fault Client callbacks
+
+void Fault_WaitForInput(void);
+void Fault_FillScreenBlack(void);
+void Fault_SetFrameBuffer(void* fb, u16 w, u16 h);
+
+void FaultDrawer_SetForeColor(u16 color);
+void FaultDrawer_SetBackColor(u16 color);
+void FaultDrawer_SetFontColor(u16 color);
+void FaultDrawer_SetCharPad(s8 padW, s8 padH);
+void FaultDrawer_SetCursor(s32 x, s32 y);
+s32 FaultDrawer_VPrintf(const char* fmt, va_list args);
+s32 FaultDrawer_Printf(const char* fmt, ...);
+void FaultDrawer_DrawText(s32 x, s32 y, const char* fmt, ...);
+
+typedef struct FaultMgr {
+    /* 0x000 */ OSThread thread;
+    /* 0x1B0 */ u8 unk_1B0[0x600];
+    /* 0x7B0 */ OSMesgQueue queue;
+    /* 0x7C8 */ OSMesg msg;
+    /* 0x7CC */ u8 exit;
+    /* 0x7CD */ u8 msgId;
+    /* 0x7CE */ u8 faultHandlerEnabled;
+    /* 0x7CF */ u8 autoScroll;
+    /* 0x7D0 */ OSThread* faultedThread;
+    /* 0x7D4 */ void (*padCallback)(Input*);
+    /* 0x7D8 */ FaultClient* clients;
+    /* 0x7DC */ FaultAddrConvClient* addrConvClients;
+    /* 0x7E0 */ u8 unk_7E0[4];
+    /* 0x7E4 */ Input padInput;
+    /* 0x7FC */ u16 colors[36];
+    /* 0x844 */ void* fb;
+    /* 0x848 */ void* clientThreadSp;
+} FaultMgr; // size = 0x850
+
+extern FaultMgr gFaultMgr;
+
+#endif
diff --git a/include/functions.h b/include/functions.h
index 6a3f86265..cd5f12d32 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -1809,66 +1809,6 @@ void DebugArena_Check(void);
 void DebugArena_Init(void* start, u32 size);
 void DebugArena_Cleanup(void);
 u8 DebugArena_IsInitalized(void);
-void Fault_SleepImpl(u32);
-void Fault_ClientProcessThread(void* arg);
-void Fault_ProcessClientContext(FaultClientContext*);
-u32 Fault_ProcessClient(u32, u32, u32);
-void Fault_AddClient(FaultClient*, void*, void*, void*);
-void Fault_RemoveClient(FaultClient*);
-void Fault_AddAddrConvClient(FaultAddrConvClient*, void*, void*);
-void Fault_RemoveAddrConvClient(FaultAddrConvClient*);
-u32 Fault_ConvertAddress(FaultAddrConvClient*);
-void Fault_Sleep(u32);
-void Fault_PadCallback(Input*);
-void Fault_UpdatePadImpl();
-u32 Fault_WaitForInputImpl();
-void Fault_WaitForInput();
-void Fault_DrawRec(s32, s32, s32, s32, u16);
-void Fault_FillScreenBlack();
-void Fault_FillScreenRed();
-void Fault_DrawCornerRec(u16);
-void Fault_PrintFReg(s32, f32*);
-void Fault_LogFReg(s32, f32*);
-void Fault_PrintFPCR(u32);
-void Fault_LogFPCR(u32);
-void Fault_PrintThreadContext(OSThread*);
-void Fault_LogThreadContext(OSThread*);
-OSThread* Fault_FindFaultedThread();
-void Fault_Wait5Seconds();
-void Fault_WaitForButtonCombo();
-void Fault_DrawMemDumpPage(const char*, u32*, u32);
-void Fault_DrawMemDump(u32, u32, u32, u32);
-void Fault_WalkStack(u32* spPtr, u32* pcPtr, u32* raPtr);
-void Fault_DrawStackTrace(OSThread* thread, s32 x, s32 y, s32 height);
-void Fault_LogStackTrace(OSThread* thread, s32 height);
-void Fault_ResumeThread(OSThread*);
-void Fault_CommitFB();
-void Fault_ProcessClients();
-void Fault_UpdatePad();
-void Fault_ThreadEntry(void*);
-void Fault_SetFB(void*, u16, u16);
-void Fault_Init(void);
-void Fault_HangupFaultClient(const char*, const char*);
-void Fault_AddHungupAndCrashImpl(const char*, const char*);
-void Fault_AddHungupAndCrash(const char*, u32);
-void FaultDrawer_SetOsSyncPrintfEnabled(u32);
-void FaultDrawer_DrawRecImpl(s32, s32, s32, s32, u16);
-void FaultDrawer_DrawChar(char);
-s32 FaultDrawer_ColorToPrintColor(u16);
-void FaultDrawer_UpdatePrintColor();
-void FaultDrawer_SetForeColor(u16);
-void FaultDrawer_SetBackColor(u16);
-void FaultDrawer_SetFontColor(u16);
-void FaultDrawer_SetCharPad(s8, s8);
-void FaultDrawer_SetCursor(s32, s32);
-void FaultDrawer_FillScreen();
-void* FaultDrawer_FormatStringFunc(void*, const char*, u32);
-void FaultDrawer_VPrintf(const char*, char*);
-void FaultDrawer_Printf(const char*, ...);
-void FaultDrawer_DrawText(s32, s32, const char*, ...);
-void FaultDrawer_SetDrawerFB(void*, u16, u16);
-void FaultDrawer_SetInputCallback(void (*)());
-void FaultDrawer_SetDefault();
 // ? UCodeDisas_TranslateAddr(?);
 // ? UCodeDisas_ParseCombineColor(?);
 // ? UCodeDisas_ParseCombineAlpha(?);
diff --git a/include/irqmgr.h b/include/irqmgr.h
new file mode 100644
index 000000000..0f26fc3ce
--- /dev/null
+++ b/include/irqmgr.h
@@ -0,0 +1,30 @@
+#ifndef IRQMGR_H
+#define IRQMGR_H
+
+#include "ultra64.h"
+
+typedef struct {
+    /* 0x00 */ s16 type;
+    /* 0x02 */ char misc[0x1E];
+} OSScMsg; // size = 0x20
+
+typedef struct IrqMgrClient {
+    /* 0x00 */ struct IrqMgrClient* prev;
+    /* 0x04 */ OSMesgQueue* queue;
+} IrqMgrClient;
+
+typedef struct {
+    /* 0x000 */ OSScMsg retraceMsg; // this apparently got moved from OSSched
+    /* 0x020 */ OSScMsg prenmiMsg; // this apparently got moved from OSSched
+    /* 0x040 */ OSScMsg nmiMsg;
+    /* 0x060 */ OSMesgQueue queue;
+    /* 0x078 */ OSMesg msgBuf[8];
+    /* 0x098 */ OSThread thread;
+    /* 0x248 */ IrqMgrClient* clients;
+    /* 0x24C */ u8 resetStatus;
+    /* 0x250 */ OSTime resetTime;
+    /* 0x258 */ OSTimer timer;
+    /* 0x278 */ OSTime retraceTime;
+} IrqMgr; // size = 0x280
+
+#endif
diff --git a/include/libc/stddef.h b/include/libc/stddef.h
index 7a481e97e..ac71ed362 100644
--- a/include/libc/stddef.h
+++ b/include/libc/stddef.h
@@ -5,4 +5,6 @@
 
 typedef unsigned long size_t;
 
+typedef unsigned int uintptr_t;
+
 #endif
diff --git a/include/padmgr.h b/include/padmgr.h
new file mode 100644
index 000000000..459bcfeba
--- /dev/null
+++ b/include/padmgr.h
@@ -0,0 +1,40 @@
+#ifndef PADMGR_H
+#define PADMGR_H
+
+#include "irqmgr.h"
+
+typedef struct {
+    /* 0x00 */ OSContPad cur;
+    /* 0x06 */ OSContPad prev;
+    /* 0x0C */ OSContPad press; // X/Y store delta from last frame
+    /* 0x12 */ OSContPad rel; // X/Y store adjusted
+} Input; // size = 0x18
+
+typedef struct PadMgr {
+    /* 0x0000 */ OSContStatus padStatus[4];
+    /* 0x0010 */ OSMesg serialMsgBuf[1];
+    /* 0x0014 */ OSMesg lockMsgBuf[1];
+    /* 0x0018 */ OSMesg interruptMsgBuf[4];
+    /* 0x0028 */ OSMesgQueue serialMsgQ;
+    /* 0x0040 */ OSMesgQueue lockMsgQ;
+    /* 0x0058 */ OSMesgQueue interruptMsgQ;
+    /* 0x0070 */ IrqMgrClient irqClient;
+    /* 0x0078 */ IrqMgr* irqMgr;
+    /* 0x0080 */ OSThread thread;
+    /* 0x0230 */ Input inputs[4];
+    /* 0x0290 */ OSContPad pads[4];
+    /* 0x02A8 */ vu8 validCtrlrsMask;
+    /* 0x02A9 */ u8 nControllers;
+    /* 0x02AA */ u8 ctrlrIsConnected[4]; // "Key_switch" originally
+    /* 0x02AE */ u8 pakType[4]; // 1 if rumble pack, 2 if mempak?
+    /* 0x02B2 */ vu8 rumbleEnable[4];
+    /* 0x02B6 */ u8 rumbleCounter[4]; // not clear exact meaning
+    /* 0x02BC */ OSPfs pfs[4];
+    /* 0x045C */ vu8 rumbleOffFrames;
+    /* 0x045D */ vu8 rumbleOnFrames;
+    /* 0x045E */ u8 preNMIShutdown;
+    /* 0x0460 */ void (*retraceCallback)(struct PadMgr* padmgr, s32 unk464);
+    /* 0x0464 */ u32 retraceCallbackValue;
+} PadMgr; // size = 0x468
+
+#endif
diff --git a/include/ultra64/convert.h b/include/ultra64/convert.h
index 13679fc5b..62409158c 100644
--- a/include/ultra64/convert.h
+++ b/include/ultra64/convert.h
@@ -15,4 +15,6 @@
 #define OS_PHYSICAL_TO_K0(x)    (void*)(((u32)(x)+0x80000000))
 #define OS_PHYSICAL_TO_K1(x)    (void*)(((u32)(x)+0xA0000000))
 
+#define OS_SEC_TO_CYCLES(n)     OS_USEC_TO_CYCLES((n) * 1000 * 1000)
+
 #endif
diff --git a/include/ultra64/thread.h b/include/ultra64/thread.h
index 69cbc775f..6b901d4f2 100644
--- a/include/ultra64/thread.h
+++ b/include/ultra64/thread.h
@@ -12,6 +12,8 @@
 #define OS_PRIORITY_APPMAX   127
 #define OS_PRIORITY_IDLE       0
 
+#define OS_PRIORITY_THREADTAIL -1
+
 #define OS_STATE_STOPPED    1
 #define OS_STATE_RUNNABLE   2
 #define OS_STATE_RUNNING    4
diff --git a/include/variables.h b/include/variables.h
index 429e1a775..392b58d73 100644
--- a/include/variables.h
+++ b/include/variables.h
@@ -208,7 +208,6 @@ extern volatile OSTime gRSPAudioTotalTime;
 extern volatile OSTime gRSPGFXTotalTime;
 extern volatile OSTime gRSPOtherTotalTime;
 extern volatile OSTime gRDPTotalTime;
-extern FaultThreadStruct gFaultStruct;
 
 extern ActiveSound gActiveSounds[7][MAX_CHANNELS_PER_BANK]; // total size = 0xA8
 extern u8 gSoundBankMuted[];
diff --git a/include/vt.h b/include/vt.h
index 46cbf05e7..4f7c73641 100644
--- a/include/vt.h
+++ b/include/vt.h
@@ -1,16 +1,15 @@
 #ifndef VT_H
 #define VT_H
 
+// 3-bit color codes
 #define VT_COLOR_BLACK         0
 #define VT_COLOR_RED           1
 #define VT_COLOR_GREEN         2
 #define VT_COLOR_YELLOW        3
 #define VT_COLOR_BLUE          4
-#define VT_COLOR_PURPLE        5
+#define VT_COLOR_MAGENTA       5
 #define VT_COLOR_CYAN          6
 #define VT_COLOR_WHITE         7
-#define VT_COLOR_LIGHTGRAY     8
-#define VT_COLOR_DARKGRAY      9
 
 #define VT_COLOR_FOREGROUND    3
 #define VT_COLOR_BACKGROUND    4
diff --git a/include/z64.h b/include/z64.h
index 9483483f9..4fb0f5c47 100644
--- a/include/z64.h
+++ b/include/z64.h
@@ -29,6 +29,9 @@
 #include "color.h"
 #include "ichain.h"
 #include "regs.h"
+#include "irqmgr.h"
+#include "padmgr.h"
+#include "fault.h"
 
 #define SCREEN_WIDTH  320
 #define SCREEN_HEIGHT 240
@@ -146,13 +149,6 @@ typedef struct GraphicsContext {
 } GraphicsContext; // size = 0x300
 
 typedef struct {
-    /* 0x00 */ OSContPad cur;
-    /* 0x06 */ OSContPad prev;
-    /* 0x0C */ OSContPad press; // X/Y store delta from last frame
-    /* 0x12 */ OSContPad rel; // X/Y store adjusted
-} Input; // size = 0x18
-
-typedef struct {
    /* 0x0000 */ s32 topY;    // uly (upper left y)
    /* 0x0004 */ s32 bottomY; // lry (lower right y)
    /* 0x0008 */ s32 leftX;   // ulx (upper left x)
@@ -1452,73 +1448,6 @@ typedef enum {
     MTXMODE_APPLY // applies transformation to the current matrix
 } MatrixMode;
 
-typedef struct FaultClient {
-    /* 0x00 */ struct FaultClient* next;
-    /* 0x04 */ u32 callback;
-    /* 0x08 */ u32 param1;
-    /* 0x0C */ u32 param2;
-} FaultClient; // size = 0x10
-
-typedef struct FaultAddrConvClient {
-    /* 0x00 */ struct FaultAddrConvClient* next;
-    /* 0x04 */ u32 callback;
-    /* 0x08 */ u32 param;
-} FaultAddrConvClient; // size = 0xC
-
-
-typedef struct {
-    /* 0x00 */ u32 (*callback)(u32, u32);
-    /* 0x04 */ u32 param0;
-    /* 0x08 */ u32 param1;
-    /* 0x0C */ u32 ret;
-    /* 0x10 */ OSMesgQueue* queue;
-    /* 0x14 */ OSMesg msg;
-} FaultClientContext; // size = 0x18
-
-typedef struct FaultThreadStruct {
-    /* 0x000 */ OSThread thread;
-    /* 0x1B0 */ u8 unk_1B0[0x600];
-    /* 0x7B0 */ OSMesgQueue queue;
-    /* 0x7C8 */ OSMesg msg;
-    /* 0x7CC */ u8 exitDebugger;
-    /* 0x7CD */ u8 msgId;
-    /* 0x7CE */ u8 faultHandlerEnabled;
-    /* 0x7CF */ u8 faultActive;
-    /* 0x7D0 */ OSThread* faultedThread;
-    /* 0x7D4 */ void(*padCallback)(Input*);
-    /* 0x7D8 */ FaultClient* clients;
-    /* 0x7DC */ FaultAddrConvClient* addrConvClients;
-    /* 0x7E0 */ u8 unk_7E0[4];
-    /* 0x7E4 */ Input padInput;
-    /* 0x7FC */ u16 colors[36];
-    /* 0x844 */ void* fb;
-    /* 0x848 */ u32 currClientThreadSp;
-    /* 0x84C */ u8 unk_84C[4];
-} FaultThreadStruct; // size = 0x850
-
-typedef struct {
-    /* 0x00 */ u16* fb;
-    /* 0x04 */ u16 w;
-    /* 0x08 */ u16 h;
-    /* 0x0A */ u16 yStart;
-    /* 0x0C */ u16 yEnd;
-    /* 0x0E */ u16 xStart;
-    /* 0x10 */ u16 xEnd;
-    /* 0x12 */ u16 foreColor;
-    /* 0x14 */ u16 backColor;
-    /* 0x14 */ u16 cursorX;
-    /* 0x16 */ u16 cursorY;
-    /* 0x18 */ const u32* fontData;
-    /* 0x1C */ u8 charW;
-    /* 0x1D */ u8 charH;
-    /* 0x1E */ s8 charWPad;
-    /* 0x1F */ s8 charHPad;
-    /* 0x20 */ u16 printColors[10];
-    /* 0x34 */ u8 escCode; // bool
-    /* 0x35 */ u8 osSyncPrintfEnabled;
-    /* 0x38 */ void(*inputCallback)();
-} FaultDrawer; // size = 0x3C
-
 typedef struct {
     /* 0x00 */ PrintCallback callback;
     /* 0x04 */ Gfx* dList;
@@ -1595,57 +1524,6 @@ typedef struct {
     /* 0x10 */ u32 data[1];
 } Yaz0Header; // size = 0x10 ("data" is not part of the header)
 
-typedef struct {
-    /* 0x00 */ s16 type;
-    /* 0x02 */ char  misc[0x1E];
-} OSScMsg; // size = 0x20
-
-typedef struct IrqMgrClient {
-    /* 0x00 */ struct IrqMgrClient* prev;
-    /* 0x04 */ OSMesgQueue* queue;
-} IrqMgrClient;
-
-typedef struct {
-    /* 0x000 */ OSScMsg retraceMsg; // this apparently got moved from OSSched
-    /* 0x020 */ OSScMsg prenmiMsg; // this apparently got moved from OSSched
-    /* 0x040 */ OSScMsg nmiMsg;
-    /* 0x060 */ OSMesgQueue queue;
-    /* 0x078 */ OSMesg msgBuf[8];
-    /* 0x098 */ OSThread thread;
-    /* 0x248 */ IrqMgrClient* clients;
-    /* 0x24C */ u8 resetStatus;
-    /* 0x250 */ OSTime resetTime;
-    /* 0x258 */ OSTimer timer;
-    /* 0x278 */ OSTime retraceTime;
-} IrqMgr; // size = 0x280
-
-typedef struct PadMgr {
-    /* 0x0000 */ OSContStatus padStatus[4];
-    /* 0x0010 */ OSMesg serialMsgBuf[1];
-    /* 0x0014 */ OSMesg lockMsgBuf[1];
-    /* 0x0018 */ OSMesg interruptMsgBuf[4];
-    /* 0x0028 */ OSMesgQueue serialMsgQ;
-    /* 0x0040 */ OSMesgQueue lockMsgQ;
-    /* 0x0058 */ OSMesgQueue interruptMsgQ;
-    /* 0x0070 */ IrqMgrClient irqClient;
-    /* 0x0078 */ IrqMgr* irqMgr;
-    /* 0x0080 */ OSThread thread;
-    /* 0x0230 */ Input inputs[4];
-    /* 0x0290 */ OSContPad pads[4];
-    /* 0x02A8 */ vu8 validCtrlrsMask;
-    /* 0x02A9 */ u8 nControllers;
-    /* 0x02AA */ u8 ctrlrIsConnected[4]; // "Key_switch" originally
-    /* 0x02AE */ u8 pakType[4]; // 1 if rumble pack, 2 if mempak?
-    /* 0x02B2 */ vu8 rumbleEnable[4];
-    /* 0x02B6 */ u8 rumbleCounter[4]; // not clear exact meaning
-    /* 0x02BC */ OSPfs pfs[4];
-    /* 0x045C */ vu8 rumbleOffFrames;
-    /* 0x045D */ vu8 rumbleOnFrames;
-    /* 0x045E */ u8 preNMIShutdown;
-    /* 0x0460 */ void (*retraceCallback)(struct PadMgr* padmgr, s32 unk464);
-    /* 0x0464 */ u32 retraceCallbackValue;
-} PadMgr; // size = 0x468
-
 // == Previously sched.h
 
 #define OS_SC_NEEDS_RDP         0x0001