Atmosphere Switch

Atmosphere
General
Author	Atmosphere-NX
Type	Custom Firmwares
Version	1.7.0
License	GPL-2.0
Last Updated	2024/03/29
Links
Download
Website
Source

Atmosphère is an open-source Nintendo Switch custom firmware (CFW) developed by the Atmosphere team. It allows users to modify and customize their Nintendo Switch consoles, enabling various homebrew applications, custom themes, cheat codes, and other features not available in the official Nintendo software.

Recommended guides:

• https://rentry.org/SwitchHackingIsEasy/
• https://nh-server.github.io/switch-guide/
• https://switch.homebrew.guide/

User guide

Atmosphère consists of multiple components, each of which replaces/modifies a different component of the system:

• Fusée - First-stage Loader, responsible for loading and validating stage 2 (custom TrustZone) plus package2 (Kernel/FIRM sysmodules), and patching them as needed. This replaces all functionality normally in Package1loader/NX Bootloader.
  • Sept - Payload used to enable support for runtime key derivation on 7.0.0.
• Exosphère - Customized TrustZone, to run a customized Secure Monitor.
• Thermosphère - EL2 EmuNAND support, i.e. backing up and using virtualized/redirected NAND images.
• Stratosphère - Custom Sysmodule(s), both Rosalina style to extend the kernel/provide new features, and of the loader reimplementation style to hook important system actions.
• Troposphère - Application-level Horizon OS patches, used to implement desirable CFW features.

Screenshots

Changelog

v1.7.0

• With thanks to the @switchbrew team, Atmosphère 1.7.0 is bundled with hbl 2.4.4, and hbmenu 3.6.0.
• Basic support was added for 18.0.0.
  • The console should boot and atmosphère should be fully functional. However, not all modules have been fully updated to reflect the latest changes.
    • There shouldn't be anything user visible resulting from this, but it will be addressed in a future atmosphère update, once I am not traveling so much.
  • exosphère was updated to reflect the latest official secure monitor behavior.
  • mesosphère was updated to reflect the latest official kernel behavior.
  • spl was updated to reflect the latest official behavior.
• fusee no longer supports applying IPS patches to KIPs.
  • The only KIPs that are ever present are a) atmosphère modules, b) custom system modules, or c) FS.
  • The IPS subsystem was originally designed to make nogc patches work for FS, but these are now internal, and it appears the literal only kip patches that exist are for piracy.
    • I could not find any kip patches posted anywhere made for any other purpose.
  • It fundamentally does not make sense to slow down boot for every normal user for a feature that has no actual use-case, especially when fusee seeks to be a minimal bootloader.
• Minor improvements were made to atmosphere's gdbstub, including:
  • Support was added for QStartNoAckMode.
  • An issue was fixed that could cause a fatal error when creating too many breakpoints.
• A number of minor issues were fixed and improvements were made, including:
  • pt-BR (PortugueseBr) is now accepted as a valid language when overriding game locales.
  • A bug was fixed that could cause atmosphere to incorrectly serialize output object IDs over IPC when using domain objects.
  • A bug was fixed in pm's resource limit boost logic that could potentially cause legitimate boosts to fail in certain circumstances.
  • loader/ro will now throw a fatal error when using invalid IPS patches that go out of bounds, instead of corrupting memory.
  • Support was fixed for booting using a memory configuration of half of the true available memory (e.g. forcing a 4GB configuration on an 8GB board).
• General system stability improvements to enhance the user's experience.

v1.6.2

• Support was finished for 17.0.0.
  • erpt was updated to support the latest official behavior.
  • jpegdec was updated to support the latest official behavior.
  • pm was updated to support the latest official behavior.
• General system stability improvements to enhance the user's experience.

v.1.6.1-prerelease

• An improved solution to the problem that would cause consoles which had previously re-built their SYSTEM partition to brick on update-to-17.0.0 was added.
  • In particular, booting atmosphère will now automatically detect the problem and unbrick any consoles which have fallen into this state.
• Some improvements were made to haze, including:
  • Performance was greatly improved:
    • Support was added for GetObjectPropList, which decreases the amount of requests made by ~8x.
    • Haze now performs rendering on the GPU, freeing up the CPU to respond to requests in a more timely manner.
  • An issue was fixed with how haze configures bMaxPacketSize0 which improves support for USB3.
• General system stability improvements to enhance the user's experience.

v1.6.0

• Basic support was added for 17.0.0.
  • The console should boot and atmosphère should be fully functional. However, not all modules have been fully updated to reflect the latest changes.
    • There shouldn't be anything user visible resulting from this, but it will be addressed in a soon-to-come atmosphère update.
  • exosphère was updated to reflect the latest official secure monitor behavior.
  • mesosphère was updated to reflect the latest official kernel behavior.
  • ncm was updated to reflect the latest official behavior.
  • erpt was partially updated to support the latest official behavior.
• Atmosphere's gdbstub now supports waiting to attach to a specific program id on launch (as opposed to any application).
  • The monitor command for this is monitor wait <hex program id>, where program id can optionally have an 0x prefix.
• Support was added to haze for editing files in-place and performing 64-bit transfers (files larger than 4 GB).
• bpc.mitm was enabled on Mariko units, and now triggers pmic-based shutdowns/reboots (thanks @CTCaer).
  • This should cause the console to no longer wake ~15 seconds after shutdown on Mariko.
• A number of minor issues were fixed and improvements were made, including:
  • A workaround was added for a change in 17.0.0 that would cause consoles which had previously re-built their SYSTEM partition to brick on update-to-17.0.0.
• General system stability improvements to enhance the user's experience.

v1.5.5

• Support was added for 16.1.0.
• General system stability improvements to enhance the user's experience.

v1.5.4

• Experimental new functionality was implemented to prevent crashing when building romfs for certain games with obscene file counts.
  • This includes both Fire Emblem: Engage (~190000 files), and The Legend of Zelda: Tears of the Kingdom (~300000) files.
  • The solution involved adding functionality to ams.mitm/pm to dynamically steal memory from the application (and system) pool as needed when the games have romfs mods.
    • No memory is taken, and there is no cost to this functionality when playing without mods (or with overrides disabled).
  • The Legend of Zelda: Tears of the Kingdom is currently the absolute worst case game, requiring ~48 MB of memory to build a romfs image to play with mods.
    • Right now, the memory is sourced as follows: 32 MB (base ams.mitm heap), 10 MB (stolen from application pool), 8 MB (dynamically stolen from system pool).
    • This is 50 MB, which allows a little overhead in the worst case (prevents crashing due to exhausting the heap for other allocations in ams.mitm).
    • Zelda is remarkably sensitive to memory being stolen from the application pool, tolerating no more than 16 MB on 1.0.0 and 12 MB on 1.1.0. I have chosen to steal 10 MB, to be safe, for now.
      • This may break on a future game update, but I will fix it if and when that happens. There is no perfect solution; the game simply requires too much memory to support mods flawlessly, and I am forced to compromise.
  • As usual, if you encounter a game that exhausts ams.mitm's memory (crashing it) when loading layeredfs mods, please contact SciresM#0524.
    • "I am jinxing myself by saying this, but it's really hard to imagine any game being worse than The Legend of Zelda: Tears of the Kingdom, but if it happens again I will drop everything to fix it as usual".
• General system stability improvements to enhance the user's experience.

v1.5.3

• Support was added for 16.0.3.
• Atmosphère was updated to use GCC 13/newlib (latest devkitA64/devkitARM releases).
• Please note: This introduces a known issue, which is currently being worked on.
  • As you may recall from the 1.4.1 changelog, Fire Emblem: Engage requires enormous amounts of memory to support using layeredfs mods with the game.
  • Latest GCC/newlib slightly increases malloc overhead size, which makes the previous memory increase insufficient.
  • A general-case solution to this is in the works, which should hopefully fix the problem in a way that doesn't jinx me for the future.
• A number of minor issues were fixed and improvements were made, including:
  • An issue was fixed that caused system font replacement to not work on 16.0.0+.
  • An minor accuracy issue was addressed in mesosphere's management of certain memory ranges; this issue would have had zero visible impact to the end-user.
• General system stability improvements to enhance the user's experience.

v1.5.2

• A homebrew application (haze) was added for performing USB file transfer (with thanks to @liamwhite for both design and implementation).
  • haze is included with atmosphère, and provides access to the SD card via the PTP/MTP protocol.
    • Please note: haze will show inside the homebrew menu under the name "USB File Transfer".
  • Please note: Atmosphère cannot be updated at runtime, and trying to install an atmosphère update via haze will fail as usual.
• General system stability improvements to enhance the user's experience.
• For information on the featureset supported by 1.5, please see the official release notes.

v1.5.1

• fatal was updated to reduce memory footprint.
  • Starting in 16.0.0, official fatal has no framebuffer or rendering logic, and instead calls other system service commands to draw the screen.
  • However, these commands aren't usable by atmosphère (too small rendering window, bad color support).
  • To reduce the relative memory footprint differential between atmosphère and official code, the framebuffer (2 MB) is now dynamically allocated when needed.
    • This will try to allocate from multiple pools (preferring System > System_NonSecure > Application).
    • This technically requires that 2 MB be available in at least one of these pools for the fatal screen to render (otherwise, a reboot-to-black-and-white-fatal will occur), but this should be a non-issue in almost all cases.
• A feature was added to optionally mirror the bluetooth pairing database to the SD card (thanks @ndeadly).
  • This allows device pairings to be automatically kept in-sync across sysmmc/all emummcs.
  • This is opt-in, and can be controlled by setting atmosphere!enable_external_bluetooth_db = u8!0x1.
  • When enabled, the pairing database will be synchronized to /atmosphere/bluetooth_devices.db.
• General system stability improvements to enhance the user's experience.

And the following was changed in 1.5.0:

• Support was added for 16.0.0
  • mesosphère was updated to reflect the latest official kernel behavior.
  • ncm was updated to reflect the latest official behavior.
  • Many FS apis were updated under the hood to reflect the latest official behavior.
  • Please Note: 16.0.0 made breaking changes to a number of system APIs, including in FS/NCM/Shared Font commands that some homebrew programs may use.
    • These programs may encounter strange errors, and may need to be recompiled with a libnx updated to support 16.0.0's changes to function properly.
    • If you are an impacted developer, please contact SciresM#0524 on discord for assistance.
• A number of minor issues were fixed and improvements were made, including:
  • An issue was fixed that could cause GPIO outputs to be misconfigured under certain circumstances.
• General system stability improvements to enhance the user's experience.
• For information on the featureset supported by 1.5, please see the official release notes.

Release notes.

Credits

Atmosphère is currently being developed and maintained by SciresM, TuxSH, hexkyz, and fincs.

In no particular order, we credit the following for their invaluable contributions:

• switchbrew for the libnx project and the extensive documentation, research and tool development pertaining to the Nintendo Switch.
• devkitPro for the devkitA64 toolchain and libnx support.
• ReSwitched Team for additional documentation, research and tool development pertaining to the Nintendo Switch.
• ChaN for the FatFs module.
• Marcus Geelnard for the bcl-1.2.0 library.
• naehrwert and st4rk for the original hekate project and its hwinit code base.
• CTCaer for the continued hekate project's fork and the minerva_tc project.
• m4xw for development of the emuMMC project.
• Riley for suggesting "Atmosphere" as a Horizon OS reimplementation+customization project name.
• hedgeberg for research and hardware testing.
• lioncash for code cleanup and general improvements.
• jaames for designing and providing Atmosphère's graphical resources.
• Everyone who submitted entries for Atmosphère's splash design contest.
• All those who actively contribute to the Atmosphère repository.

External links

• GitHub - https://github.com/Atmosphere-NX/Atmosphere
• GBAtemp - https://gbatemp.net/threads/atmosphere-nx-custom-firmware-in-development-by-sciresm.496832/