From c71706e74296687ff8b35590af1f595421c20069 Mon Sep 17 00:00:00 2001 From: Philipp AUER Date: Mon, 26 Sep 2022 05:14:43 +0200 Subject: [PATCH] update for 9b6b164aadd18052d9d44be03f3f851a909cf527 --- Debugging-using-printf.md | 49 ++++++++++++++++++++++++++ printf-in-mGBA.md | 74 --------------------------------------- 2 files changed, 49 insertions(+), 74 deletions(-) create mode 100644 Debugging-using-printf.md delete mode 100644 printf-in-mGBA.md diff --git a/Debugging-using-printf.md b/Debugging-using-printf.md new file mode 100644 index 0000000..168296a --- /dev/null +++ b/Debugging-using-printf.md @@ -0,0 +1,49 @@ +When programming a common tool to debug is to log strings to a terminal / log file. On a GBA we don't necessarily have that ability, but many emulators will implement extensions that allow us to write to a log from within our running game. Please note that those debugging extensions are only valid for the respective emulator and will not work on other ones or real hardware. In fact they might break on other guest devices, therefore make sure to only use debugging when developing something and turn it off for productive builds. + +The code for talking to the debug loggers is already included in pokeemerald since 9b6b164aadd18052d9d44be03f3f851a909cf527. + +## 1. Enabling external Debugging + +Go to `include/config.h` and comment `#define NDEBUG`: +```diff +-#define NDEBUG ++// #define NDEBUG +``` + +Make sure to remove the comment when you want to build without logging enabled, e.g. in a productive environment. Debug logs only work on the respective target devices and are potential hard hits on your game's performance if you do them a lot. + +## 2. Print something + +Wherever you want to use the debug log use the following syntax: +```c +DebugPrintf(str, ...); +``` +Like you would use `printf` from the C standard library. View `man 3 printf` or find a ressource online to see a list of format arguments you can provide and what they do, e.g.: +```c +u32 a = 42; +DebugPrintf("a = %ud. But also a = 0x%ux", a, a); +``` +should print the following string to the log: `a = 42. But also a = 0x2a`, since `%ud`, `%ux` can be used to print unsigned decimal / hexadecimal integers respectively. + +Additionally if you are using the default configuration, a custom format option `%S` is added, which will print strings from the game, e.g.: +```c +DebugPrintf("%S", gSpeciesNames[SPECIES_BULBASAUR]); +``` +should print the following string to the log: `BULBASAUR`. + +## 3. Assertions + +This implementation supports 2 versions of Assertions. + +* `AGB_ASSERT(expression)` will print an error to the log if `expression` is violated. It will then crash the game. +* `AGB_WARNING(expression)` will print a warning to the log if `expression` is violated. It will then continue to gracefully operate the program. + +## 4. Viewing the logs + +Since `AGBPrintf` is not widely supported by emulators it is recommended to use mGBA. The default configuration will use the mGBA handler for printing to the log. + +In order to view our logs, we'll need to use the [mGBA](https://mgba.io/) emulator. Open the log viewer by going to the "Tools" menu and selecting "View Logs...". Make sure the log level checkboxes for INFO, WARNING, ERROR are checked and run your game until it hits a `DebugPrintf` statement. + +## 5. Configuration + +Apart from enabling debugging you can also change the `LOG_HANDLER` and the `PRETTY_PRINT_HANDLER`. See the comments in `include/config.h`. Note that when using LIBC as your `PRETTY_PRINT_HANDLER` it was discovered that the devkitPro libc does not link well against it and it does not support the `%S` format extension. \ No newline at end of file diff --git a/printf-in-mGBA.md b/printf-in-mGBA.md deleted file mode 100644 index d6b9fa6..0000000 --- a/printf-in-mGBA.md +++ /dev/null @@ -1,74 +0,0 @@ -Credits to SBird for this tutorial, Petuh for the original tutorial, and for Lunos for finding an archived version. - -TODO: rewrite to be in line with the standards of other tutorials. As of now, this is (almost) identical to Petuh's original post. - -This adds debug functionality to interact with the mGBA Debug Log. It will only work on mGBA, other emulators or real GBAs do not include this Hardware extension and are allowed to break! The implementation also needs a considerable amount of CPU Resources. It should be disabled on Release builds! - -NOTE: Since linking libc libraries will usually bring you to library hell this printf includes a standalone version of `vsnprintf` called `mini_printf` which does not have any libc dependencies and should yield a smaller footprint. It does not support the full range of `printf` pretty formats. - -NOTE: You can also find the changes here: https://github.com/SBird1337/pokeemerald/tree/debug/mgba-print - You still need to make a call to `MgbaOpen` as explained in this tutorial. - -## 1. Getting the printf and mgba Files - -Create the following files and directories: -* `src/mgba_printf/mgba.c`: https://gist.github.com/SBird1337/95d6faf92c394a3778d9e9a9fd920c45 -* `src/mgba_printf/mini_printf.c`: https://gist.github.com/SBird1337/ef5b2190b8fa9ca1e0038490697d0093 -* `include/mgba_printf/mgba.h`: https://gist.github.com/SBird1337/48e468e1c81d12e1e6f7e0443af343e2 -* `include/mgba_printf/mini_printf.h`: https://gist.github.com/SBird1337/ccff38b13163f80eb05b7764f87e3b2d - -## 2. Add the new files to the build. -We need to tell the linker about the new files we just added. Open `ld_script.txt`. Find the section that begins with `.text :`. At the end of this section, add the following: -```c -src/mgba_printf/mgba.o(.text); -src/mgba_printf/mini_printf.o(.text); -``` - -Next find the section that begins with `.rodata :`. At the end of this section, add the following: -```c -src/mgba_printf/mgba.o(.rodata); -``` - -## 3. Initialize mGBA logging -In order to print anything to the debugger, we need to first initialize it. Open `src/main.c`. At the top, add `#include "mgba_printf/mgba.h"`. Then edit the starting function to start mGBA logging: -```diff -void AgbMain() -{ -... - - ResetBgs(); - SetDefaultFontsPointer(); -+ MgbaOpen(); - InitHeap(gHeap, HEAP_SIZE); -... -``` - -## 4. Testing the code - -You can now print debug strings to the log using `MgbaPrintf` from anywhere inside your codebase. Just make sure to `#include "mgba_printf/mgba.h"` and e.g. call `MgbaPrintf(MGBA_LOG_INFO, "I am logging")` from anywhere inside a codefile. The library also includes a method to print `PokeString` encoded data. If you want to e.g. print the species **and** name of every wild Pokémon you encounter you can add the following lines to `src/wild_encounter.c`: - -```diff -static void CreateWildMon(u16 species, u8 level) -{ -... -+ MgbaPrintf(MGBA_LOG_INFO, "%d", species); // Print the species id -+ MgbaPrintEncoded(MGBA_LOG_INFO, gSpeciesNames[species]); // Print the species name - CreateMonWithNature(&gEnemyParty[0], species, level, 32, PickWildMonNature()); -} -``` -Make sure to `#include` both `"data.h"` (for `gSpeciesNames`) and `mgba_printf/mgba.h` (For the printf functions). - -NOTE: `MgbaPrintEncoded` is only used to print `PokeString` formatted text (like species names) - If you just want to print regular debug strings you can use `MgbaPrintf` as shown above. - -## 5. Assertions - -This implementation supports 2 versions of Assertions. - -* `MGBA_ASSERT(expression)` will print an error to the MGBA Error log if `expression` is violated. It will then crash the game. -* `MGBA_WARNING(expression)` will print a warning to the MGBA Warning log if `expression` is violated. It will then continue to gracefully operate the program. - -## 6. Viewing the logs -In order to view our logs, we'll need to use the [mGBA](https://mgba.io/) emulator. Open the log viewer by going to the "Tools" menu and selecting "View Logs...". Make sure the log level checkbox for your specific type of log (INFO, DEBUG, WARNING, ERROR) is checked and you should see a message like this one when you encounter a wild Pokémon: -``` -[INFO] GBA Debug: 286 -[INFO] GBA Debug: POOCHYENA -``` \ No newline at end of file