v3.3.0 — SYSNAND now supported

Release asset: fs_codecvt_dual_unpacked.kip

The overlay now works on SysNAND (sysMMC), not just emuMMC. That is the whole
of this release: no change to the UTF-8 conversion, the directory-name filter,
or the supported firmware list.

Supersedes v3.2.0's SysNAND warning. That release said "Do not use this KIP
on SysNAND … Supporting SysNAND is out of scope." The cause has been found and
fixed. SysNAND is supported as of this version.

Support Matrix

HOS	SysNAND	emuMMC
19.0.1	✅ TESTED (3/3)	✅ TESTED (3/3)
20.2.0 / 20.5.0	✅offset verified	✅ TESTED (3/3)
21.2.0	✅offset verified	✅offset verified
22.0.0	✅offset verified	✅offset verified
22.5.0	✅ TESTED (3/3)	✅ TESTED (3/3)
23.0.0 / 23.0.1	✅ TESTED (3/3)	✅ TESTED (3/3)

• TESTED (3/3) — real-hardware PASS for direct CJK read/write, /ROM
  enumeration showing the CJK directory, and enumeration inside the CJK
  directory.
• offset verified — the matches_fs opcode checks pass against that
  version's FS image. For the RTLD site this also means the site opcode matches
  and the branch delta decoded from its immediate matches the table, so the
  patch cannot land at a wrong target. On-console regression of that exact
  combination is still pending.

The 21.2.0 RTLD site sits at a higher offset (0x2E1C0) than 22.0.0's
(0x2DED0) despite being an older release. Every offset was measured against
the actual image rather than derived by shifting, for exactly that reason.

Requirements

slankka/hekate-fs-overlay — an
unofficial Hekate fork adding fsoverlay= support. This KIP cannot be loaded
without it.

bootloader/sys/emummc.kipm must still exist

The loader copies the 0x80-byte capability array out of that file into the merged
KIP, and injects none of its code. The file is not optional: with it missing
the boot stops with bootloader/sys/emummc.kipm is missing or invalid.

Those capabilities are what allow the overlay to call svcMapProcessMemory on
its own process, which is how it obtains write access to FS's read-execute
pages. FS's own capability array is too small for that — tested, not assumed: a
build that keeps FS's caps and skips the file black-screens, because the mapping
fails, no hook is installed, and FS then aborts in the RTLD walk described above.

Removing this last dependency is planned, not done.

Do not set kip1patch=emummc

That injects emuMMC's code, and five of its six hooks replace FS's media path
with emuMMC's own driver. On SysNAND that driver has nowhere to read from, so the
console does not boot. If you copied a boot entry from an older guide, delete
that line.

Note: fs_codecvt_dual_unpacked.kip is an FS Overlay KIP, not a
standalone Initial Process KIP. Do not load it with kip1= — it must be
merged into the existing FS process image by the overlay-aware loader.

Installation

1. Download fs_codecvt_dual_unpacked.kip from this release.
2. Place it at sdmc:/bootloader/fsoverlays/fs_codecvt_dual_unpacked.kip.
3. Add a boot entry.

On SysNAND:

[真实系统-中文路径]
pkg3=atmosphere/package3
emummc_force_disable=1
fsoverlay=bootloader/fsoverlays/fs_codecvt_dual_unpacked.kip

On emuMMC:

[虚拟系统-中文路径]
pkg3=atmosphere/package3
emummcforce=1
fsoverlay=bootloader/fsoverlays/fs_codecvt_dual_unpacked.kip

The entry is identical apart from which medium is being booted. There is no
SysNAND-specific variant, no extra key, and no kip1patch= line.

Verify the CJK round trip

The test_program homebrew client creates and reads
sdmc:/ROM/中文目录/往返测试.txt and confirms both Chinese names appear through
directory enumeration. Launch it via the Homebrew Menu after boot.

A pass means all three of: the CJK directory can be created, it can be stat'd by
its own UTF-8 path, and it appears when the parent directory is listed.

Checksums

File:    fs_codecvt_dual_unpacked.kip
Size:    11,140 bytes (0x2B84)
SHA-256: 68d889364d1302b410209b78098f3c64a48382117b30ef42c74a6f066ba98b25

The image grew by 552 bytes over v3.2.0 (10,588 → 11,140). The memory extent is
unchanged at 0x8000, so deployments keep the same layout.

Rollback

Remove the fsoverlay= line from hekate_ipl.ini. The stock FS image on disk is
never modified, so nothing needs to be restored.

If the console hangs, hold the power button for 12 seconds, take out the SD card,
and delete that line.

Upgrading from v3.2.0

Nothing to do beyond replacing the .kip and deleting kip1patch=emummc if you
had it. The firmware list is unchanged, so an image that matched before still
matches.

Historical builds remain available in earlier releases.

---

Attribution & Notes

Copyright (c) 2026 slankka and contributors. Licensed under
GPL-2.0-only — see LICENSE.

The RTLD workaround was originally written for emuMMC by the Atmosphère project;
this release ports the idea to a standalone overlay. The KIP startup framework is
likewise derived from the Atmosphère emuMMC design.

Development was assisted by generative AI. The maintainer directed, reviewed,
modified, tested, and approved the resulting code. The AI tool is not an author
or copyright holder.

v3.2.0 — HOS 23.0.1 Support

v3.2.0 — HOS 23.0.1 Support

Release asset: fs_codecvt_dual_unpacked.kip

Adds the exFAT-capable FS of HOS 23.0.0 / 23.0.1 to the dual-media UTF-8 FS
Overlay KIP. Everything from v3.1.0 is unchanged — same media-independent
codecvt, same single-KIP-for-both-media design.

What's New

• New FS 23.0.1 offset table. The 23.0.1 exFAT FS.kip1
  (SHA-256 prefix FDAF163288E10805…) is structurally the 22.5.0 image shifted
  by +0x3030. All six PF_CHARCODE slots, every utf8dir hook, the
  path / pattern / SFN guards and the code cave land at the shifted addresses
  byte-identically. The only field that is not a pure shift is one identity
  check at dir_reject (0xD28A9041 → 0xD2822461), updated accordingly.
• One KIP now covers the exFAT-capable FS of 19.0.1, 20.2.0, 21.2.0, 22.0.0,
  22.5.0 and 23.0.1 (23.0.0 shares the same FS binary).

Support Matrix

HOS Version	FAT32 media (alone)	exFAT media (alone)	One-KIP dual-media
19.0.1	✅ TESTED (3/3)	✅ offset verified	✅ offset verified
20.2.0	✅ offset verified	✅ TESTED (3/3)	✅ offset verified
21.2.0	✅ offset verified	✅ offset verified	✅ offset verified
22.0.0	✅ offset verified	✅ offset verified	✅ offset verified
22.5.0	✅ offset verified	✅ offset verified	✅ offset verified
23.0.1	✅ offset verified	✅ offset verified	✅ offset verified

The three checks cover: direct CJK file read/write, /ROM enumeration showing
the CJK directory, and enumerating files inside the CJK directory — including
the Chinese directory duplication issue previously reported.

Notes on the matrix:

• TESTED (3/3) — real-hardware PASS for all three checks with this
  release's KIP (fs_codecvt_dual_unpacked.kip): HOS 19.0.1 on FAT32, and
  HOS 20.2.0 on exFAT.
• offset verified — the matches_fs opcode-level offset check passes
  against that version's exFAT-capable FS image (six-slot table + dir/path/
  pattern/SFN + identity checks). The KIP is guaranteed to select and hook the
  correct version at runtime, but on-console regression on that combination is
  still pending.

Requirements

• slankka/hekate-fs-overlay —
  an unofficial Hekate fork adding support for prepending overlay KIPs to the
  FS process image. This KIP can only be loaded by this modified Hekate.
• exFAT-capable FS image (FAT32 media also boots on the exFAT-capable FS)

Note: this is an FS Overlay KIP, not a standalone Initial Process KIP.
Do not load it with Hekate's kip1= key. It must be merged into the
existing FS.kip1 process image by the FS Overlay-aware loader in the
slankka/hekate-fs-overlay
fork.

Installation

1. Download fs_codecvt_dual_unpacked.kip from this release.
2. Place it on the SD card at
   sdmc:/bootloader/fsoverlays/fs_codecvt_dual_unpacked.kip

Hekate boot entry (bootloader/hekate_ipl.ini):

fsoverlay=bootloader/fsoverlays/fs_codecvt_dual_unpacked.kip

(If your fsoverlay= line already references a different filename, update the
path to match the file you actually copied.)

Verify the CJK round trip

The test_program homebrew client creates and reads
sdmc:/ROM/中文目录/往返测试.txt and confirms both Chinese names appear through
directory enumeration. Launch it via the Homebrew Menu after boot.

Download test_program.nro

Checksums

File:    fs_codecvt_dual_unpacked.kip
Size:    10,588 bytes (0x295C)
SHA-256: C438EB09D6ED9A921F7DB834A020143811224369A4195F56D3B8A3114A0D445F

Rollback

Remove the fsoverlay= line — the stock FS image is untouched. Historical
builds remain available on the codex/exfat branch and in earlier releases.

---

Attribution & Notes

• For details see docs/fs-header-formats-zh_CN.md and the flight-test
  manifest (flight_test/MANIFEST.md).

3.1.0 - Dual-Variant Support

v3.1.0 — Dual-Media UTF-8 FS Overlay KIP

Release asset: fs_codecvt_dual_unpacked.kip

This release delivers the final dual-media build of nx-fs-utf8, an FS
Overlay KIP that adds UTF-8 (CJK / Chinese) filename compatibility to the
Nintendo Switch FS sysmodule. It works on both exFAT and FAT32 media with a
single, media-independent codecvt (no runtime media detection, no anchors).

What's New in v3.1.0

• Unified no-dispatch codecvt — the six PF_CHARCODE slots are replaced
  with a fixed, media-independent implementation:
  • slot0 (oem2unicode): full 3-byte UTF-8 decoder (exFAT fix)
  • slot1 (unicode2oem): bounded ≤2-byte UTF-8 encoder (FAT32 safe)
  • slots 2/4/5: UTF-8 width / classification
• No media signal — no g_fat_path dispatch flag, no exFAT mount anchors.
  This removes the previous FAIL PASS FAIL failure mode caused by bounded
  slot0 on exFAT and the stack-overflow risk of a 3-byte slot1 on FAT32.
• Cross-version — one build targets the exFAT-capable FS of HOS 19.0.1,
  20.2.0, 21.2.0, 22.0.0 and 22.5.0.

Verification Matrix

HOS Version	FAT32 media (alone)	exFAT media (alone)	One-KIP dual-media
19.0.1	✅ TESTED (3/3)	✅ offset verified	✅ offset verified
20.2.0	✅ offset verified	✅ TESTED (3/3)	✅ offset verified
21.2.0	✅ offset verified	✅ offset verified	✅ offset verified
22.0.0	✅ offset verified	✅ offset verified	✅ offset verified
22.5.0	✅ offset verified	✅ offset verified	✅ offset verified

The three checks cover: direct CJK file read/write, /ROM enumeration showing
the CJK directory, and enumerating files inside the CJK directory — including
the Chinese directory duplication issue previously reported.

Notes on the matrix:

• TESTED (3/3) — real-hardware PASS for all three checks with this
  release's KIP (fs_codecvt_dual_unpacked.kip): HOS 19.0.1 on FAT32, and
  HOS 20.2.0 on exFAT.
• offset verified — the matches_fs opcode-level offset check passes
  against that version's exFAT-capable FS image (six-slot table + dir/path/
  pattern/SFN + identity checks). The KIP is guaranteed to select and hook the
  correct version at runtime, but on-console regression on that combination is
  still pending.
• One-KIP dual-media is considered fully verified only when the same KIP
  passes 3/3 on both media within one HOS version. Cross-media operation is
  already demonstrated (the identical KIP passes on 19.0.1 FAT32 and
  20.2.0 exFAT); per-version dual regression is pending (offset verified).

Requirements

• slankka/hekate-fs-overlay —
  an unofficial Hekate fork adding support for prepending overlay KIPs to the
  FS process image. This KIP can only be loaded by this modified Hekate.
• exFAT-capable FS image (FAT32 media also boots on the exFAT-capable FS)

Note: this is an FS Overlay KIP, not a standalone Initial Process KIP.
Do not load it with Hekate's kip1= key. It must be merged into the
existing FS.kip1 process image by the FS Overlay-aware loader in the
slankka/hekate-fs-overlay
fork.

Installation

1. Download fs_codecvt_dual_unpacked.kip from this release.
2. Place it on the SD card at sdmc:/bootloader/fsoverlays/fs_codecvt_unpacked.kip

Hekate boot entry (bootloader/hekate_ipl.ini):

fsoverlay=bootloader/fsoverlays/fs_codecvt_unpacked.kip

(Rename fs_codecvt_dual_unpacked.kip to fs_codecvt_unpacked.kip if your
fsoverlay= config references that name, or update the path to the actual
filename.)

Verify the CJK round trip

The test_program homebrew client creates and reads
sdmc:/ROM/中文目录/往返测试.txt and confirms both Chinese names appear through
directory enumeration. Launch it via the Homebrew Menu after boot.

Checksums

File:    fs_codecvt_dual_unpacked.kip
Size:    10,428 bytes (0x28BC)
SHA-256: B78E72FB56085E130E445641426EDB2651EA19DE375473F49DE4B4DA8FDD7F55

Rollback

• exFAT-only six-slot KIP (codex/exfat branch)
• FAT32 dual-contract KIP (earlier releases)

---

Attribution & Notes

• For details see docs/fs-header-formats-zh_CN.md and the flight-test
  manifest (flight_test/MANIFEST.md).