Document sys_freeze.[ch] (#2666)

4 files changed, 19 insertions, 7 deletions

diff --git a/include/sys_freeze.h b/include/sys_freeze.h
index 0e033cacd..6ccf6dca3 100644
--- a/include/sys_freeze.h
+++ b/include/sys_freeze.h
@@ -3,6 +3,6 @@
 
 #include "attributes.h"
 
-NORETURN void func_800D31A0(void);
+NORETURN void Freeze_CurrentThread(void);
 
 #endif
diff --git a/src/code/sys_freeze.c b/src/code/sys_freeze.c
index 295715555..e4e1dccd9 100644
--- a/src/code/sys_freeze.c
+++ b/src/code/sys_freeze.c
@@ -4,7 +4,19 @@
 #include "sys_freeze.h"
 #include "terminal.h"
 
-NORETURN void func_800D31A0(void) {
+/**
+ * Halts the calling thread forever (this neither destroys it nor affects other threads).
+ * This may be used to halt execution in the event of an irrecoverable error without triggering
+ * the crash screen or otherwise halting the rest of the programs, other threads will continue
+ * to run as normal.
+ *
+ * @note In practice, use of this function is very rare, only occuring in a few N64DD-related
+ *       codepaths. In most cases where one needs to halt execution due to a critical error,
+ *       it is more appropriate to use Fault_AddHangupAndCrash or related functions.
+ *
+ * @see Fault_AddHungupAndCrash
+ */
+NORETURN void Freeze_CurrentThread(void) {
     PRINTF(VT_FGCOL(RED) "\n**** Freeze!! ****\n" VT_RST);
     for (;;) {
         Sleep_Msec(1000);
diff --git a/src/n64dd/z_n64dd.c b/src/n64dd/z_n64dd.c
index 4c896b587..c05bf3ad8 100644
--- a/src/n64dd/z_n64dd.c
+++ b/src/n64dd/z_n64dd.c
@@ -143,7 +143,7 @@ s32 func_801C7098(void) {
     B_801D9D50.unk_00 = 10;
     phi_v1 = (&func_801C8000)(&B_801D9D50);
     if (phi_v1 < 0) {
-        func_800D31A0();
+        Freeze_CurrentThread();
     }
     return phi_v1;
 }
@@ -375,7 +375,7 @@ s32 func_801C7818(void) {
 
     if (func_801C81C4() != 2) {
         func_801C761C();
-        func_800D31A0();
+        Freeze_CurrentThread();
         return -3;
     }
 
@@ -411,7 +411,7 @@ void func_801C7920(s32 arg0, void* arg1, s32 arg2) {
     }
     B_801D9D50.unk_00 = 7;
     if ((&func_801C8000)(&B_801D9D50) != 0) {
-        func_800D31A0();
+        Freeze_CurrentThread();
     }
 }
 
diff --git a/src/overlays/gamestates/ovl_title/z_title.c b/src/overlays/gamestates/ovl_title/z_title.c
index 907fdb886..a17bd0f4d 100644
--- a/src/overlays/gamestates/ovl_title/z_title.c
+++ b/src/overlays/gamestates/ovl_title/z_title.c
@@ -203,7 +203,7 @@ void ConsoleLogo_Destroy(GameState* thisx) {
 #if PLATFORM_N64
     if (this->unk_1E0) {
         if (func_801C7818() != 0) {
-            func_800D31A0();
+            Freeze_CurrentThread();
         }
         func_801C7268();
     }
@@ -223,7 +223,7 @@ void ConsoleLogo_Init(GameState* thisx) {
 #if PLATFORM_N64
     if ((D_80121210 != 0) && (D_80121211 != 0) && (D_80121212 == 0)) {
         if (func_801C7658() != 0) {
-            func_800D31A0();
+            Freeze_CurrentThread();
         }
         this->unk_1E0 = true;
     } else {