LumaTeam/Luma3DS

# Luma3DS   *Nintendo 3DS “自制固件”*   ## 描述 **Luma3DS** 对运行于 Nintendo 3DS 系列所有型号主机上的系统软件进行了修补和大量重实现。其目标是极大提升用户体验，并在 3DS 停产之后继续为其提供支持。功能包括： * **对自制软件 (homebrew) 的一流支持** * **Rosalina**，一个通过 L+Down+Select（默认）触发的覆盖层菜单，支持如下功能： * 在游戏中截图 * 蓝光滤镜和其他屏幕滤镜 * 输入重定向，以使用外部设备（如控制器）进行游玩 * 使用作弊码 * 从网络 (NTP) 精确设置时间和日期 * ……以及更多！ * **丰富的游戏 Mod 功能**，包括但不限于： * 游戏插件（3GX 格式） * 单游戏语言覆盖（“locale 模拟”） * 资源内容路径重定向（“LayeredFS”） * **支持用户提供的补丁和/或完整的“系统模块”替换**，这是 Nintendo Network 替代项目（及其他项目）的一项 essential 功能 * 一个**功能齐全的 GDB stub**，让自制软件开发者和逆向工程师都能更高效地工作 * 能够链式加载其他固件文件，包括其自身的其他版本 * ……以及更多！ ## 安装与升级 Luma3DS 需要 [boot9strap](https://github.com/SciresM/boot9strap) 才能运行。 安装 boot9strap 后，只需下载 [最新发布版归档](https://github.com/LumaTeam/Luma3DS/releases/latest) 并将其解压到 SD 卡的根目录，即可“安装”或升级 Luma3DS，其中附带了 [自制软件菜单和证书包](https://github.com/devkitPro/3ds-hbmenu)。如有必要，请覆盖现有文件并合并现有文件夹。 ## 基本用法 **Luma3DS 主配置菜单** 可在启动时按下 Select 访问。配置文件存储在 SD 卡的 `/luma/config.ini` 中（如果 Luma3DS 从 CTRNAND 分区启动——这通常发生在 SD 卡缺省时——则存储在 `/rw/luma/config.ini`）。 **Chainloader 菜单** 可在启动时按下 Start 或从配置菜单访问。Payload 文件应位于 `/luma/payloads`，扩展名为 `.firm`；如果此类 payload 只有一个，上述选择菜单将被跳过。可以为 payload 分配热键，例如在启动时按下 X 将链式加载 `x_test.firm`。 **覆盖层菜单 Rosalina** 的默认按键组合是：L+Down+Select。为了灵活性，大多数 Rosalina 菜单设置不会自动保存，因此提供了“Save settings”选项。 **GDB 端口** 启用后，常规端口为 `4000-4002`。支持并鼓励在“extended-remote”模式下使用 `attach` 以及 `info os processes`（用于逆向工程，也可查看 `monitor getmemregions`）。用于“启动时中断”功能的端口是 `4003`，不使用“extended-remote”。我们积极支持 devkitARM-patched GDB 和 IDA Pro（不启用“stepping support”）。 我们有一个 wiki，但目前内容非常过时。 ## 组件 Luma3DS 由多个组件构成。虽然每个组件内部的代码风格基本一致，但这些组件是多年间编写的，可能无法反映维护者如今在新组件/项目中编写代码的方式： * **arm9**, **arm11**: 裸机主设置菜单、chainloader 和固件加载器。除了显示设置和按需链式加载其他自制固件文件外，它还负责修补官方固件以修改 `Process9` 代码并注入所有其他自定义组件。这是该项目在 2015 年编写的第一个组件 * **k11_extension**: 扩展 Arm11 `NATIVE_FIRM` 内核（`Kernel11`）的代码。它由上述裸机加载器通过挂钩内核启动代码注入内核，然后将自身挂钩到内核的其余部分。其功能包括挂钩系统调用、引入新的 SVC 以及挂钩进程间通信，以绕过 Nintendo 系统设计中的限制。例如，这个组件允许 Rosalina 在进入覆盖层菜单时暂停其他进程。这是在我们尚未完全逆向工程内核时编写的，并于 2017 年与 Rosalina 一同发布。2023 年合并了对“游戏插件”支持的进一步挂钩 * **sysmodules**: 3DS 操作系统“系统模块”（进程）的重实现（Rosalina 除外，它是自定义的），目前仅包含由内核直接在内存中加载的初始进程（“kernel initial process”，简称 KIP） * **loader**: 从存储加载非 KIP 进程的进程。因为这是修补/替换可执行代码的最佳位置，所有进程修补都在此进行，特别是实现了“游戏 Mod”功能。这也是处理 3DSX 自制软件加载的 sysmodule。于 2016 年引入 * _**rosalina**_: Luma3DS 最重要的组件和自定义 KIP：覆盖层菜单、GDB 服务器、`err:f`（致命错误屏幕）重实现等等。于 2017 年中引入，此后不断发生变化并收到了许多外部贡献 * **pxi**: Arm11<>Arm9 通信 KIP，仅为重实现而重实现。于 2017 年末引入 * **sm**: 服务管理器 KIP，重实现以移除服务访问控制限制。于 2017 年末引入 * **pm**: 进程管理器 KIP，负责启动/终止进程并指示 `loader` 加载它们。该重实现支持 Rosalina 中的“启动时中断”GDB 功能，并以正确的方式解除了 FS 访问控制限制。于 2019 年引入 ## 维护者 * **[@TuxSH](https://github.com/TuxSH)**: 主要开发者，创建并维护项目的大部分功能。于 2016 年加入 * **[@AuroraWright](https://github.com/AuroraWright)**: 项目作者，实现了核心功能（大部分裸机启动设置菜单和固件加载代码），其成功的设计决策使该项目广受欢迎。于 2015 年创建项目，目前不活跃 * **[@PabloMK7](https://github.com/PabloMK7)**: 合并于 v13.0 版本的插件加载器功能的维护者。于 2023 年加入 ## 路线图 Luma3DS 仍计划推出更多功能和巩固性更新！以下是当前计划的内容： * 完全重实现 `TwlBg` 和 `AgbBg`。这将为 DS 和 GBA 游戏的顶屏提供更好、更可配置的升频（Old 2DS 除外）。目前正在使用 C++23 进行私密开发（无 ETA）。虽然这是一项艰巨的任务，因为需要在半裸机（无 IPC 的受限内核）环境下重写整个驱动程序栈，但这是 Luma3DS 最关键的功能，并将使驱动程序 sysmodule 的重实现变得微不足道 * 重实现 `TWL_FIRM` 和 `AGB_FIRM` 的 `Process9`，以便在 DS 和 GBA 兼容模式下实现更多功能（需要文件访问的功能） * 最终，完全重实现 `Kernel11` ## 已知问题 * **作弊引擎在某些应用中崩溃，特别是 Pokémon 游戏**：Nintendo 的 `Kernel11` 中存在一个竞态条件，涉及在创建线程时将新的 `KDebugThread` 附加到 `KThread`，以及另一个线程对 `thread->debugThread` 的空指针解引用。这导致作弊引擎使那些不断创建和销毁大量线程的游戏（如 Pokémon）崩溃。 * 对于这些游戏，在 `Kernel11` 被重实现之前，拥有一个**专用的“游戏插件”**是唯一的替代方案。 * **应用程序对 Rosalina 菜单按键组合做出反应**：Rosalina 仅按间隔轮询按键输入以确定何时显示菜单。这意味着 Rosalina 菜单组合有时会被即将被暂停的游戏/进程处理。 * 您可以在“Miscellaneous options”子菜单中**更改菜单组合**（然后在主菜单中使用“Save settings”保存）来解决此问题。 ## 从源代码构建 构建 Luma3DS 需要以下工具： * git * 位于 `$PATH` 中的 [makerom](https://github.com/jakcron/Project_CTR) * 已安装的 [firmtool](https://github.com/TuxSH/firmtool) * 最新的 devkitARM 和 libctru： * 安装 `dkp-pacman`（或者，对于已提供 pacman 的发行版，添加仓库）：https://devkitpro.org/wiki/devkitPro_pacman * 从 `3ds-dev` 元包安装软件包：`sudo dkp-pacman -S 3ds-dev --needed` * 虽然 libctru 和 Luma3DS 发布版保持同步，但对于非发布版的 Luma3DS 提交，您可能需要从源代码构建 libctru 虽然 Luma3DS 发布版捆绑了 `3ds-hbmenu`，但 Luma3DS 实际上编译为单个文件：`boot.firm`。只需将其复制到 SD 卡的根目录（[ftpd](https://github.com/mtheall/ftpd) 是最简单的方法），就完成了。 ## 许可证 本软件根据 GPLv3 条款授权。您可以在 LICENSE.txt 文件中找到该许可证的副本。 GDB stub 中的文件采用 MIT 或“GPLv2 or any later version”的三重许可，具体情况在文件头中指定。PM、SM、PXI 重实现也采用 MIT 许可。 ## 致谢 如果没有许多人的贡献和建设性反馈，Luma3DS 就不会有今天的成就。我们要特别感谢： * **[@devkitPro](https://github.com/devkitPro)**（特别是 **[@fincs](https://github.com/fincs)**, **[@WinterMute](https://github.com/WinterMute)** 和 **[@mtheall](https://github.com/mtheall)**）提供高质量且易于使用、搭载最新 GCC 的工具链，以及他们持续的技术建议 * **[@Nanquitas](https://github.com/Nanquitas)** 提供游戏插件加载器代码的初始版本以及对 GDB stub 非常有用的贡献 * **[@piepie62](https://github.com/piepie62)** 提供 Rosalina 作弊引擎的当前实现，**Duckbill** 提供原始实现 * **[@panicbit](https://github.com/panicbit)** 提供 Rosalina 中屏幕滤镜的原始实现 * **[@jasondellaluce](https://github.com/jasondellaluce)** 提供 LayeredFS * **[@LiquidFenrir](https://github.com/LiquidFenrir)** 提供 Rosalina “Process List”中的内存查看器 * **ChaN** 提供 [FatFs](http://elm-chan.org/fsw/ff/00index_e.html) * 所有为 Luma3DS 仓库做出贡献的人 * 所有协助终端用户进行故障排除的人 * 所有为 Luma3DS 提供建设性反馈的人

标签：3DS, boot9strap, C++, CFW, GDB调试, Homebrew, LayeredFS, Luma3DS, NTP校时, Rosalina, 云资产清单, 任天堂3DS, 客户端加密, 嵌入式开发, 截图工具, 掌机, 数据擦除, 游戏主机, 游戏模组, 系统破解, 系统补丁, 自制固件, 蓝光过滤, 输入重定向, 逆向工程, 金手指