Game Boy Advance开发者实现控制台日志输出

背景

Game Boy Advance（GBA）开发中，调试手段极其有限。开发者无法像现代应用那样使用 printf()（C 语言）或 console.log()（JavaScript）将信息输出到控制台。通常只能将日志信息绘制到 GBA 那小小的屏幕上，这既占用宝贵的显示资源，又难以阅读。mGBA 模拟器为此提供了一套专有的内存映射寄存器，使得开发者可以在 GBA 游戏中像使用 printf 一样方便地输出日志，从而大幅提升开发效率。

核心内容

工作原理：mGBA 的内存映射日志寄存器

在 GBA 开发中，经常通过写入像 REG_DISPCNT 这样的寄存器来控制硬件。这些寄存器实际上是 GBA 内存映射中的特定地址，写入数据后硬件会按收到的指令行动。mGBA 在此基础上扩展了几个额外的内存映射寄存器，专门用于日志功能。这些寄存器仅在游戏运行于 mGBA 内部时生效。

关键寄存器定义如下：

#define REG_LOG_ENABLE (vu32*)(0x4FFF780)
#define REG_LOG_BUFFER (vu32*)(0x4FFF600)
#define REG_LOG_SEND   (vu32*)(0x4FFF700)

• REG_LOG_ENABLE：启用日志功能，需写入特殊值 0xC0DE。
• REG_LOG_BUFFER：写入要输出的日志数据。
• REG_LOG_SEND：写入日志级别，此时 mGBA 会读取缓冲区内容并输出到日志窗口。

基础日志函数实现

将上述细节封装成一个函数，开发者只需调用它即可。简化版实现如下：

#define MGBA_LOG_MAX_LINE 256
#define ERROR   0x101
#define WARNING 0x102
#define INFO    0x103
#define DEBUG   0x104

void mgbalog(u32 level, const char *msg) {
    *REG_LOG_ENABLE = 0xC0DE;
    tonccpy((void *)REG_LOG_BUFFER, msg, MGBA_LOG_MAX_LINE);
    *REG_LOG_SEND = level;
}

使用示例：

#include "mgbalog.h"

void myFunc() {
    // ...
    mgbalog(DEBUG, "hello mGBA log");
}

运行游戏后，通过菜单 Tools > View logs... 即可打开日志窗口查看消息。

日志级别与命令行输出

mGBA 支持多种日志级别，通过 REG_LOG_SEND 写入的值决定。级别定义如下：

• FATAL = 1
• ERROR = 2
• WARNING = 4
• INFO = 8
• DEBUG = 16
• STUB = 32
• IN-GAME ERROR = 64

若觉得每次打开日志窗口麻烦，可从命令行启动 mGBA 并添加 --log-level 参数将日志输出到终端。例如：

mgba --log-level 16 yourRom.gba

级别值可以组合——例如同时输出 DEBUG（16）和 ERROR（2）时，使用 --log-level 18。

添加格式化支持

仅输出固定字符串用处有限。通过标准库的 vsnprintf 可以轻松添加格式化功能。改进后的 mgbalog 接受可变参数：

#include <stdarg.h>
#include <stdio.h>

static char logBuffer[MGBA_LOG_MAX_LINE];

void mgbalog(u32 level, const char *format, ...) {
    *REG_LOG_ENABLE = 0xC0DE;
    va_list formatArgs;
    va_start(formatArgs, format);
    vsnprintf(logBuffer, MGBA_LOG_MAX_LINE, format, formatArgs);
    va_end(formatArgs);
    tonccpy((void *)REG_LOG_BUFFER, logBuffer, MGBA_LOG_MAX_LINE);
    *REG_LOG_SEND = level;
}

现在可以写出 mgbalog(DEBUG, "pos.x=%i", pos.x); 这样的调用。

仅在开发阶段启用日志

日志会增加二进制体积、消耗 CPU 和内存，在最终发布版本中应将其移除。尤其对于 GBA 这种资源紧张的平台，vsnprintf 等标准库函数开销很大。推荐的做法是将日志实现放在条件编译之后，通过宏 MGBALOG 控制是否包含日志代码。

条件编译实现

在头文件 mgbalog.h 中：

#pragma once
#include <tonc.h>

#define MGBA_LOG_MAX_LINE 256

#define ERROR   0x101
#define WARNING 0x102
#define INFO    0x103
#define DEBUG   0x104

#define REG_LOG_ENABLE (vu32*)(0x4FFF780)
#define REG_LOG_BUFFER (vu32*)(0x4FFF600)
#define REG_LOG_SEND   (vu32*)(0x4FFF700)

#ifdef MGBALOG
void _mgbalog(u32 level, const char *format, ...);
#define mgbalog(...) _mgbalog(__VA_ARGS__)
#else
#define mgbalog(level, format, ...)
#endif

实现文件 mgbalog.c 同样用条件编译包裹：

#ifdef MGBALOG
#include "mgbalog.h"
#include <stdarg.h>
#include <stdio.h>

static char logBuffer[MGBA_LOG_MAX_LINE];

void _mgbalog(u32 level, const char *format, ...) {
    *REG_LOG_ENABLE = 0xC0DE;
    va_list formatArgs;
    va_start(formatArgs, format);
    vsnprintf(logBuffer, MGBA_LOG_MAX_LINE, format, formatArgs);
    va_end(formatArgs);
    tonccpy((void *)REG_LOG_BUFFER, logBuffer, MGBA_LOG_MAX_LINE);
    *REG_LOG_SEND = level;
}
#endif

这样一来，整个游戏中调用 mgbalog(...) 的地方无需改动：当定义了 MGBALOG 时，宏会展开为实际函数调用；否则宏展开为空，编译器不会生成任何日志相关代码。

关键要点

• mGBA 模拟器为 GBA 开发提供了三个专用内存映射寄存器，用于启用日志、写入日志数据和发送日志，相当于给 GBA 模拟了 printf 功能。
• 日志数据通过 tonccpy 复制到缓冲区，写入 REG_LOG_SEND 时 mGBA 即输出日志。
• 支持多种日志级别（FATAL/ERROR/WARNING/INFO/DEBUG/STUB/IN-GAME ERROR），可通过 --log-level 命令行参数组合，并将日志输出到终端。
• 利用 vsnprintf 很容易实现格式化字符串日志，但会增加二进制体积和运行时开销。
• 通过条件编译宏 MGBALOG 可以优雅地将日志代码仅保留在开发版本中，发布版本中自动移除，无需修改业务代码。
• 如果不想自己实现，社区已有现成的 mGBA 日志库可用；像 Butano 这样的 GBA 引擎也已内置 mGBA 日志功能。
• 了解底层实现原理有助于更好地使用现有日志库，也体现了开源生态中“知其所以然”的精神。

意义与影响

此文介绍的 mGBA 日志功能本质上是在模拟器层面为复古硬件调试提供了现代化工具。对于 GBA homebrew 开发者而言，这从“只能在屏幕上画字”的原始调试方式跃升到“可变参数、多级别、可条件编译”的成熟日志体系，极大降低了调试门槛，提高了开发效率。更重要的是，这种思想体现了模拟器不仅可用于运行游戏，还可以成为强大的开发辅助平台——通过扩展内存映射接口，模拟器能够提供原始硬件不存在的调试能力。类似的思路也适用于其他模拟平台（如 NES、SNES 等）。通过开源社区的贡献，每一位 GBA 开发者都能受益于这项轻量级但实用的技术，而理解其背后的寄存器操作原理，也加深了对 GBA 硬件和模拟器工作机制的理解。