libu64 (#2267)

* libu64

* logutils.o -> debug.o in spec

* stackcheck.c is part of libu64

* review

* add paragraph about Overlay_Load calling an external function

* audio code*

1 files changed, 77 insertions, 0 deletions

diff --git a/docs/libu64.md b/docs/libu64.md
new file mode 100644
index 000000000..34cc668c8
--- /dev/null
+++ b/docs/libu64.md
@@ -0,0 +1,77 @@
+# libu64
+
+This document explains the reasoning behind organizing the libu64 files.
+
+libu64 is known about from the Animal Crossing (GameCube) map files.
+
+Here is the relevant excerpt from the Doubutsu no Mori+ 1.0 map file (for .text):
+
+```
+  00057f00 00043c 8005d4c0  1 .text 	libu64.a debug.c
+  UNUSED   000070 ........ f_debug_range_f libu64.a debug.c
+  UNUSED   00007c ........ _dbg_range libu64.a debug.c
+  UNUSED   000158 ........ _dbg_dump libu64.a debug.c
+  UNUSED   000048 ........ _dbg_array_error libu64.a debug.c
+  UNUSED   000054 ........ _dbg_bound libu64.a debug.c
+  UNUSED   000044 ........ _dbg_null libu64.a debug.c
+  UNUSED   000060 ........ _dbg_ptr libu64.a debug.c
+  UNUSED   000058 ........ _dbg_here libu64.a debug.c
+  00057f00 00005c 8005d4c0  4 _dbg_hungup 	libu64.a debug.c
+  UNUSED   000004 ........ Reset libu64.a debug.c
+  00057f5c 000b70 8005d51c  1 .text 	libu64.a gfxprint.c
+  00057f5c 0002e8 8005d51c  4 gfxprint_setup 	libu64.a gfxprint.c
+  00058244 00004c 8005d804  4 gfxprint_color 	libu64.a gfxprint.c
+  UNUSED   000024 ........ gfxprint_locate libu64.a gfxprint.c
+  00058290 000024 8005d850  4 gfxprint_locate8x8 	libu64.a gfxprint.c
+  UNUSED   000014 ........ gfxprint_setoffset libu64.a gfxprint.c
+  000582b4 000378 8005d874  4 gfxprint_putc1 	libu64.a gfxprint.c
+  0005862c 000198 8005dbec  4 gfxprint_putc 	libu64.a gfxprint.c
+  UNUSED   000060 ........ gfxprint_write libu64.a gfxprint.c
+  UNUSED   000054 ........ gfxprint_puts libu64.a gfxprint.c
+  000587c4 000064 8005dd84  4 gfxprint_prout 	libu64.a gfxprint.c
+  00058828 000090 8005dde8  4 gfxprint_init 	libu64.a gfxprint.c
+  000588b8 000004 8005de78  4 gfxprint_cleanup 	libu64.a gfxprint.c
+  000588bc 00004c 8005de7c  4 gfxprint_open 	libu64.a gfxprint.c
+  00058908 000038 8005dec8  4 gfxprint_close 	libu64.a gfxprint.c
+  UNUSED   000020 ........ gfxprint_vprintf libu64.a gfxprint.c
+  00058940 000080 8005df00  4 gfxprint_printf 	libu64.a gfxprint.c
+  000589c0 000000 8005df80  1 .text 	libu64.a gfxprint_data.c
+  000589c0 000164 8005df80  1 .text 	libu64.a pad.c
+  UNUSED   000024 ........ pad_init libu64.a pad.c
+  UNUSED   000004 ........ pad_cleanup libu64.a pad.c
+  UNUSED   000010 ........ pad_flush libu64.a pad.c
+  UNUSED   000018 ........ pad_push_only libu64.a pad.c
+  UNUSED   00001c ........ pad_push_also libu64.a pad.c
+  UNUSED   00001c ........ pad_on_trigger libu64.a pad.c
+  UNUSED   00001c ........ pad_off_trigger libu64.a pad.c
+  UNUSED   000008 ........ pad_button libu64.a pad.c
+  UNUSED   000008 ........ pad_trigger libu64.a pad.c
+  UNUSED   00000c ........ pad_physical_stick_x libu64.a pad.c
+  UNUSED   00000c ........ pad_physical_stick_y libu64.a pad.c
+  UNUSED   000014 ........ pad_set_logical_stick libu64.a pad.c
+  UNUSED   00000c ........ pad_logical_stick_x libu64.a pad.c
+  UNUSED   00000c ........ pad_logical_stick_y libu64.a pad.c
+  UNUSED   00000c ........ pad_stick_x libu64.a pad.c
+  UNUSED   00000c ........ pad_stick_y libu64.a pad.c
+  000589c0 000054 8005df80  4 pad_correct_stick 	libu64.a pad.c
+```
+
+This repository's `debug.c` (formerly `logutils.c`), `gfxprint.c` and `pad.c` (formerly `padutils.c`) line up with the map.
+
+Note `debug.c` has additional debug-only functions in gc-eu-mq-dbg, hinting that there were two versions of libu64, a debug version and a non-debug version.
+
+Additionally `debug.c`, `gfxprint.c` and `pad.c` all require compilation flags `-O2` (instead of `-O2 -g3`) to match, as supplementary evidence these were part of a separately compiled library.
+
+`-O2` is also required for most files between `gfxprint.c` and `pad.c` in the code segment (see spec), hinting that these other files (`loadfragment2_n64.c`, `loadfragment2_gc.c`, `mtxuty-cvt.c`, `relocation_gc.c`, `load_gc.c`, `code_800FC620.c`) are also part of libu64.
+
+Files `rcp_utils.c` and `logseverity_gc.c` do not strictly require `-O2`, but they do match with `-O2`.
+
+`padsetup.c` also requires `-O2`.
+
+On the other hand, the function `Overlay_Load` (in `loadfragment2_n64.c` or `load_gc.c` depending on game version) calls `DmaMgr_RequestSync`, a function that is not part of libu64.
+This could suggest these files are not part of libu64, but the other evidence detailed above seems stronger.
+It is also a possibility that libu64 expected users to provide the function, and it would have been an undefined symbol in the library.
+
+All in all this suggests all files in code between the audio code and libc64, are part of libu64.
+
+In the OoT boot segment, `stackcheck.c` is right next to `debug.c` and requires `-O2`: this hints `stackcheck.c` could be part of libu64 too. This is confirmed by looking at Majora's Mask n64-us, where `stackcheck.c` is in the middle of other libu64 files in the boot segment (see MM spec).