slankka/nx-filesystem-utf8

# nx-filesystem-utf8 `nx-filesystem-utf8` 是一个研究项目和补丁构建器，旨在为 Nintendo Switch Horizon OS 的 FAT/exFAT 文件系统堆栈添加 UTF-8 文件名支持。 它替换了传统的 OEM/DBCS 转换例程，并更新了 SFAT 目录名过滤器，以便在对原有 ASCII 文件名限制不做禁用处理的情况下，能够列出、打开、读取和写入有效的 CJK 路径。 本仓库用于研究并修复 Nintendo Switch Horizon OS FAT/exFAT 文件系统中的 UTF-8/CJK 文件名兼容问题。补丁替换旧式 OEM/DBCS 编码转换逻辑，并为 SFAT 目录遍历加入严格 UTF-8 校验，同时保留原有 ASCII 非法字符检查。 ## 当前范围 构建器目前包含针对 HOS 19.0.0、20.2.0、22.0.0 和 22.5.0 经过静态验证的 FAT 和 ExFAT 定义。HOS 19.0.0 ExFAT 还通过了 CJK 目录枚举和直接文件读写的硬件测试。其他目标应被视为硬件测试候选对象。 生成的补丁组： - `utf8codecv` — UTF-8/UTF-16 转换及相关字符处理。 - `utf8dir` — SFAT 目录枚举中的严格 UTF-8 验证。 逆向工程锚点： - codecvt 内核点是 PrFILE2 的目录输出转换路径：`VFiPFDIR_p_fsnext` 在通过 `PF_CHARCODE` 字符集构建 `PF_DTA::LongName` 时调用了 `VFiPFPATH_transformFromUnicodeToNormal`。 - Directory::Read 内核点位于更后方的 Nintendo SFAT 封装中。它会在将名称复制到 `nn::fs::DirectoryEntry` 之前扫描 PrFILE2 返回的名称；这就是被 `utf8dir` 修正的过滤器。 引用： - TFP2 项目：[github.com/koopthekoopa/TFP2](https://github.com/koopthekoopa/TFP2) - PrFILE2 源码树：[TFP2/src/vf/PrFILE2](https://github.com/koopthekoopa/TFP2/tree/main/src/vf/PrFILE2) ## 构建 要求： - Python 3 - devkitA64 - 从您自己的固件中提取的已压缩和已解压的 `FS.kip1` 文件 在 PowerShell 中运行： ``` $env:NX_UTF8_FIRMWARE_ROOT = "F:\dumped_firmware" $env:DEVKITA64 = "F:\devkitPro\devkitA64" python .\src\build_patches22.py ``` 生成的 Hekate 补丁文件是 [src/patches.ini](src/patches.ini)。构建详情和受支持的 FS 哈希记录在 [src/README.md](src/README.md) 和 [src/MANIFEST.txt](src/MANIFEST.txt) 中。 ## 验证程序 [verfiy_program](verfiy_program/) 目录包含用于硬件验证的 `sdmc2` libnx 测试应用程序。它测试直接的 CJK 路径读写、`sdmc:/ROM` 下 CJK 目录的枚举，以及该目录内 CJK 文件名的枚举。包含 PowerShell 和 Bash 的构建入口点。 ## 文档 逆向工程笔记、补丁历史以及 SFAT/PrFile2 分析可在 [docs](docs/) 下找到。 ## 安全性 补丁绑定到特定已压缩 FS KIP 的 SHA-256 前缀。请勿在未知的固件版本或 FAT/exFAT 变体之间重用偏移量。在常规使用前，请先在已备份的 SD 卡上测试新目标。 ## 免责声明 本项目仅出于研究、互操作性以及供用户在合法拥有的硬件和固件上使用而提供。它不包含或分发固件、加密密钥或其他受版权保护的二进制文件。 文件系统和固件补丁可能会导致启动失败、数据丢失或文件系统损坏。测试前请备份所有重要数据。您使用此软件的风险由您自行承担。作者和贡献者对因使用它而造成的损坏或数据丢失不承担任何责任。 本项目是独立的，与 Nintendo、Microsoft、eSOL、Atmosphère 或其各自的贡献者和权利所有者没有任何隶属关系，也未获得他们的授权、赞助或认可。

标签：AI合规, C/C++, Homebrew, UTF-8兼容性, 事务性I/O, 云资产清单, 任天堂Switch, 客户端加密, 文件系统, 补丁构建, 逆向工程