Rooba
/
pokeemerald
mirror of https://github.com/pret/pokeemerald.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update for 9b6b164aad

Philipp AUER 2022-09-26 05:14:43 +02:00
parent 7797ea8f6a
commit c71706e742
2 changed files with 49 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Debugging-using-printf.md Normal file

@ -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.

74
printf-in-mGBA.md

@ -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
```