Work towards GDB support

.devcontainer/Dockerfile

@@ -2,13 +2,20 @@ FROM debian:bookworm-slim
 
 RUN apt-get update && \
     apt-get upgrade -y && \
-    apt-get install build-essential doxygen git python3 wget -y && \
+    apt-get install build-essential doxygen git python3 wget gdb-multiarch -y && \
+    # apt-get install unzip usbutils -y && \
     wget https://github.com/DragonMinded/libdragon/releases/download/toolchain-continuous-prerelease/gcc-toolchain-mips64-x86_64.deb && \
     dpkg -i gcc-toolchain-mips64-x86_64.deb && \
     rm gcc-toolchain-mips64-x86_64.deb && \
     wget https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.17.0/sc64-deployer-linux-v2.17.0.tar.gz && \
     tar -xf sc64-deployer-linux-v2.17.0.tar.gz -C /usr/local/bin && \
     rm sc64-deployer-linux-v2.17.0.tar.gz && \
+    # wget https://github.com/buu342/N64-UNFLoader/releases/download/v2.1/UNFLoader-Linux-x64.zip && \
+    # unzip UNFLoader-Linux-x64.zip -d /usr/local/unfloader && \
+    # cp -f "/usr/local/unfloader/UNFLoader" "/usr/local/bin/UNFLoader"
+    # yes Y | . /usr/local/unfloader/installer_linux.sh && \
+    # rm UNFLoader-Linux-x64.zip && \
+    # rm -rf /usr/local/unfloader && \
     git config --global --add safe.directory "*" && \
     SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" && \
     echo "$SNIPPET" >> "/root/.bashrc"

.devcontainer/devcontainer.json

@@ -11,7 +11,8 @@
         "vscode": {
             "extensions": [
                 "ms-vscode.cpptools",
-                "ms-vscode.makefile-tools"
+                "ms-vscode.makefile-tools",
+                "coolchyni.beyond-debug"
             ],
             "settings": {
                 "git.ignoredRepositories": [

Makefile

@@ -138,6 +138,11 @@ else
 endif
 .PHONY: run-debug
 
+debug-gdb: $(OUTPUT_DIR)/$(PROJECT_NAME).n64
+	SRCS += libs/unfloader/debug.c \
+	FLAGS += -g -O0 -DDEBUG_GDB
+.PHONY: debug-gdb
+
 # test:
 #   TODO: run tests
 

README.md

@@ -110,6 +110,43 @@ NOTE: a "release" version of the SC64 menu is called `sc64menu.n64` and can be c
 * Add the required file to the correct folder on your SD card.
 
 
+# GDB in devcontainer
+**Note:** only supported on flashcarts with USB functionality
+
+## ( via WSL )
+In your WSL instance, to install the necessary drivers and udev rules, run the command:
+``` 
+    wget https://github.com/buu342/N64-UNFLoader/releases/download/v2.1/UNFLoader-Linux-x64.zip && \
+    unzip UNFLoader-Linux-x64.zip -d /usr/local/unfloader && \
+    yes Y | . /usr/local/unfloader/installer_linux.sh
+    rm -rf /usr/local/unfloader/
+```
+
+In Windows run PowerShell as Administrator.
+* install usbipd: `winget install usbipd`.
+* run `usbipd list` and note the bus id for the flashcart.
+* run `usbipd wsl attach --busid <busid>`.
+
+When the devcontainer is started, run:
+* `gdb-multiarch` and then `set architecture` to confirm support for GDB on `mips:4300`
+* `lsusb` and `ls /dev/tty*` to confirm the flashcart is mounted in the container.
+
+Add `launch.json` to `.vscode` folder
+
+
+## Via Windows
+It is not currently possible to directly communicate with USB devices.
+BUT, as a work around you can use a proxy TCP/IP connection
+
+* Download UNFLoader [here](https://github.com/buu342/N64-UNFLoader/releases/download/v2.1/UNFLoader-Windows-x86.zip)
+* Extract and place `UNFLoader.exe` in the `tools/unfLoader` directory.
+* Set up a proxy: open a terminal window, `cd ./tools/unfLoader` and then `./UNFLoader -g`
+
+
+Add a `launch.json` file to `.vscode` folder
+TBD: add content.
+
+
 # Update Libdragon submodule
 This repo currently uses the `unstable` branch as a submodule at a specific commit.
 To update to the latest version, use `git submodule update --remote ` from the terminal.

libdragon

@@ -1 +1 @@
-Subproject commit dd2202a6082cd3d92f4c22e64b27f148612c4c3a
+Subproject commit 2c3cbdb825048178729fccd992114ba70de89dad

src/libs/unfloader/debug.h

@@ -0,0 +1,180 @@
+#ifndef UNFL_DEBUG_H
+#define UNFL_DEBUG_H
+    
+    /*********************************
+             Settings macros
+    *********************************/
+    
+    // Enable/Disable debug
+    #ifndef DEBUG_MODE
+        #define DEBUG_MODE    1   // Enable/Disable debug mode
+    #endif
+    
+    // Settings
+    #define DEBUG_INIT_MSG    1   // Print a message when debug mode has initialized
+    #define AUTOPOLL_ENABLED  1   // Automatically poll the USB on a timer
+    #define AUTOPOLL_TIME     200 // Time (in milliseconds) between auto polls
+    #define USE_FAULTTHREAD   1   // Create a fault detection thread (libultra only)
+    #define USE_RDBTHREAD     1   // Create a remote debugger thread
+    #define OVERWRITE_OSPRINT 1   // Replaces osSyncPrintf calls with debug_printf (libultra only)
+    #define MAX_COMMANDS      25  // The max amount of user defined commands possible
+    
+    // USB thread definitions (libultra only)
+    #define USB_THREAD_ID    14
+    #define USB_THREAD_PRI   126
+    #define USB_THREAD_STACK 0x2000
+    
+    // Fault thread definitions (libultra only)
+    #define FAULT_THREAD_ID    13
+    #define FAULT_THREAD_PRI   125
+    #define FAULT_THREAD_STACK 0x2000
+    
+    // Remote debugger thread definitions (libultra only)
+    #define RDB_THREAD_ID    15
+    #define RDB_THREAD_PRI   124
+    #define RDB_THREAD_STACK 0x2000
+    
+    
+    /*********************************
+             Debug Functions
+    *********************************/
+    
+    #if DEBUG_MODE
+        
+        /*==============================
+            debug_initialize
+            Initializes the debug and USB library.
+            Should be called last during game initialization.
+        ==============================*/
+        
+        extern void debug_initialize();
+        
+        
+        /*==============================
+            debug_printf
+            Prints a formatted message to the developer's command prompt.
+            Supports up to 256 characters.
+            @param A string to print
+            @param variadic arguments to print as well
+        ==============================*/
+        
+        extern void debug_printf(const char* message, ...);
+        
+        
+        /*==============================
+            debug_dumpbinary
+            Dumps a binary file through USB
+            @param The file to dump
+            @param The size of the file
+        ==============================*/
+        
+        extern void debug_dumpbinary(void* file, int size);
+        
+        
+        /*==============================
+            debug_screenshot
+            Sends the currently displayed framebuffer through USB.
+            DOES NOT PAUSE DRAWING THREAD! Using outside the drawing
+            thread may lead to a screenshot with visible tearing
+        ==============================*/
+        
+        extern void debug_screenshot();
+        
+        
+        /*==============================
+            debug_assert
+            Halts the program if the expression fails.
+            @param The expression to test
+        ==============================*/
+        
+        #define debug_assert(expr) (expr) ? ((void)0) : _debug_assert(#expr, __FILE__, __LINE__)
+        
+        
+        /*==============================
+            debug_64drivebutton
+            Assigns a function to be executed when the 64drive button is pressed.
+            @param The function pointer to execute
+            @param Whether or not to execute the function only on pressing (ignore holding the button down)
+        ==============================*/
+        
+        extern void debug_64drivebutton(void(*execute)(), char onpress);
+        
+        
+        /*==============================
+            debug_pollcommands
+            Check the USB for incoming commands.
+        ==============================*/
+        
+        extern void debug_pollcommands();
+        
+        
+        /*==============================
+            debug_addcommand
+            Adds a command for the USB to read.
+            @param The command name
+            @param The command description
+            @param The function pointer to execute
+        ==============================*/
+        
+        extern void debug_addcommand(char* command, char* description, char*(*execute)());
+        
+        
+        /*==============================
+            debug_parsecommand
+            Stores the next part of the incoming command into the provided buffer.
+            Make sure the buffer can fit the amount of data from debug_sizecommand!
+            If you pass NULL, it skips this command.
+            @param The buffer to store the data in
+        ==============================*/
+        
+        extern void debug_parsecommand(void* buffer);
+                
+        
+        /*==============================
+            debug_sizecommand
+            Returns the size of the data from this part of the command.
+            @return The size of the data in bytes, or 0
+        ==============================*/
+        
+        extern int debug_sizecommand();
+        
+        
+        /*==============================
+            debug_printcommands
+            Prints a list of commands to the developer's command prompt.
+        ==============================*/
+        
+        extern void debug_printcommands();
+        
+        
+        // Ignore this, use the macro instead
+        extern void _debug_assert(const char* expression, const char* file, int line);
+        
+        // Include usb.h automatically
+        #include "usb.h"
+        
+    #else
+        
+        // Overwrite library functions with useless macros if debug mode is disabled
+        #define debug_initialize() 
+        #define debug_printf (void)
+        #define debug_screenshot(a, b, c)
+        #define debug_assert(a)
+        #define debug_pollcommands()
+        #define debug_addcommand(a, b, c)
+        #define debug_parsecommand(a) NULL
+        #define debug_sizecommand() 0
+        #define debug_printcommands()
+        #define debug_64drivebutton(a, b)
+        #define usb_initialize() 0
+        #define usb_getcart() 0
+        #define usb_write(a, b, c)
+        #define usb_poll() 0
+        #define usb_read(a, b)
+        #define usb_skip(a)
+        #define usb_rewind(a)
+        #define usb_purge()
+        
+    #endif
+    
+#endif

src/main.c

@@ -3,10 +3,18 @@
 #include "boot/boot.h"
 #include "menu/menu.h"
 
+// #ifdef DEBUG_GDB
+// #include "libs/unfloader/debug.h"
+// #endif
+
 
 int main (void) {
     boot_params_t boot_params;
 
+// #ifdef DEBUG_GDB
+//     debug_initialize();
+// #endif
+
     menu_run(&boot_params);
 
     disable_interrupts();