Atmosphere Documentation

File: README.md Copy Chapter

=====

Atmosphère is a work-in-progress customized firmware for the Nintendo Switch.

Components

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.
• 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

Licensing

This software is licensed under the terms of the GPLv2, with exemptions for specific projects noted below.

You can find a copy of the license in the LICENSE file.

Exemptions:

• Nintendo is exempt from GPLv2 licensing and may (at its option) instead license any source code authored for the Atmosphère project under the Zero-Clause BSD license.

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.

File: docs/components/modules/ams_mitm.md Copy Chapter

ams_mitm

This module provides methods to intercept services provided by other system modules. It is further sub-divided according to the service it targets.

bpc_mitm Copy Chapter

bpc_mitm enables intercepting requests to power control services. It currently intercepts:

• am system module (to intercept the Reboot/Power buttons in the overlay menu)
• fatal system module (to simplify payload reboot logic significantly)
• nx-hbloader (to allow homebrew to take advantage of the feature)

fs_mitm Copy Chapter

fs_mitm enables intercepting file system operations. It can deny, delay, replace, or redirect any request made to the file system. It enables LayeredFS to function, which allows for replacement of game assets.

hid_mitm Copy Chapter

hid_mitm enables intercepting requests to controller device services. It is currently disabled by default. If enabled, it intercepts:

• nx-hbloader (to help homebrew not need to be recompiled due to a breaking change introduced in the past)

Note that hid_mitm is currently deprecated and might be removed entirely in the future.

ns_mitm Copy Chapter

ns_mitm enables intercepting requests to application control services. It currently intercepts:

• Web Applets (to facilitate nx-hbloader web browser launching)

set_mitm Copy Chapter

set_mitm enables intercepting requests to the system settings service. It currently intercepts:

• ns system module and games (to allow for overriding game locales)
• All firmware debug settings requests (to allow modification of system settings not directly exposed to the user)

Firmware Version Copy Section

set_mitm intercepts the GetFirmwareVersion command, if the requester is qlaunch or maintenance.
It modifies the display_version field of the returned system version, causing the version to display
in settings as #.#.#|AMS #.#.#|? with ? = S when running under system eMMC or ? = E when running under emulated eMMC. This allows users to easily verify what version of Atmosphère and what eMMC environment they are running.

System Settings Copy Section

set_mitm intercepts the GetSettingsItemValueSize and GetSettingsItemValue commands for all requesters.
It does so in order to enable user configuration of system settings, which are parsed from /atmosphere/system_settings.ini on boot. See here for more information on the system settings format.

dns_mitm Copy Chapter

dns_mitm enables intercepting requests to dns resolution services, to enable redirecting requests for specified hostnames.

For documentation, see here.

File: docs/components/modules/boot.md Copy Chapter

boot

This module is a reimplementation of the Horizon OS's boot system module, which is responsible for initializing and configuring hardware.

Atmosphère's reimplementation displays its own black and white splash screen and battery icons as replacements for the original assets used during display initialization.

File: docs/components/modules/boot2.md Copy Chapter

boot2

This module is a reimplementation of the Horizon OS's boot2 system module, which is responsible for launching all the other necessary system modules.

Atmosphère's reimplementation allows launching user provided system modules from the SD card. See here for more information.

File: docs/components/modules/creport.md Copy Chapter

creport

This module is a reimplementation of the Horizon OS's creport system module, which is responsible for managing crash reports.

Atmosphère's reimplementation redirects writing of generated crash reports to the SD card under the folder /atmosphere/crash_reports/. It also prevents the automatic uploading of said crash reports.

File: docs/components/modules/dmnt.md Copy Chapter

dmnt

This module is a reimplementation of the Horizon OS's dmnt system module, which provides a debug monitor.

Extensions Copy Chapter

Atmosphère implements an extension to provide cheat code functionality.

Cheat Service Copy Section

A HIPC service API is provided for interacting with the cheat code manager through the service dmnt:cht. See here for more information on the cheat code format.

The SwIPC definition for dmnt:cht follows:

interface ams::dmnt::cheat::CheatService is dmnt:cht {
  [65000] HasCheatProcess() -> sf::Out out;
  [65001] GetCheatProcessEvent() -> sf::OutCopyHandle out_event;
  [65002] GetCheatProcessMetadata() -> sf::Out<CheatProcessMetadata> out_metadata;
  [65003] ForceOpenCheatProcess();
  [65004] PauseCheatProcess();
  [65005] ResumeCheatProcess();

  [65100] GetCheatProcessMappingCount() -> sf::Out out_count;
  [65101] GetCheatProcessMappings(u64 offset) -> sf::OutArray<MemoryInfo> &mappings, sf::Out out_count;
  [65102] ReadCheatProcessMemory(u64 address, u64 out_size) -> sf::OutBuffer &buffer;
  [65103] WriteCheatProcessMemory(sf::InBuffer &buffer, u64 address, u64 in_size);
  [65104] QueryCheatProcessMemory(u64 address) -> sf::Out<MemoryInfo> mapping;

  [65200] GetCheatCount() -> sf::Out out_count;
  [65201] GetCheats(u64 offset) -> sf::OutArray<CheatEntry> &cheats, sf::Out out_count;
  [65202] GetCheatById(u32 cheat_id) -> sf::Out<CheatEntry> cheat;
  [65203] ToggleCheat(u32 cheat_id);
  [65204] AddCheat(CheatDefinition &cheat, bool enabled) -> sf::Out out_cheat_id;
  [65205] RemoveCheat(u32 cheat_id);
  [65206] ReadStaticRegister(u8 which) -> sf::Out out;
  [65207] WriteStaticRegister(u8 which, u64 value);
  [65208] ResetStaticRegisters();

  [65300] GetFrozenAddressCount() -> sf::Out out_count;
  [65301] GetFrozenAddresses(u64 offset) ->sf::OutArray<FrozenAddressEntry> &addresses, sf::Out out_count;
  [65302] GetFrozenAddress(u64 address) -> sf::Out<FrozenAddressEntry> entry;
  [65303] EnableFrozenAddress(u64 address, u64 width) -> sf::Out out_value;
  [65304] DisableFrozenAddress(u64 address);
}

File: docs/components/modules/eclct.stub.md Copy Chapter

eclct.stub

This module is a reimplementation of the Horizon OS's eclct system module, which collects error reports.

Atmosphère's reimplementation is a stub to remove any and all functionality pertaining to error report collection.

File: docs/components/modules/erpt.md Copy Chapter

erpt

This module is a reimplementation of the Horizon OS's erpt system module, which is responsible for managing error reports.

Atmosphère's reimplementation redirects writing of generated error reports to the SD card under the folder /atmosphere/erpt_reports/.

File: docs/components/modules/fatal.md Copy Chapter

fatal

This module is a reimplementation of the Horizon OS's fatal system module, which is responsible for managing fatal reports.

Atmosphère's reimplementation prevents error report creation and draws a custom error screen, showing registers and a backtrace. It also attempts to gather debugging info for any and all crashes and tries to save reports to the SD card under the folder /atmosphere/fatal_reports/.

File: docs/components/modules/jpegdec.md Copy Chapter

jpegdec

This module is a reimplementation of the Horizon OS's jpegdec system module, which is responsible for JPEG format decoding.

Atmosphère's reimplementation allows two sessions instead of 1, so homebrew can use it for software JPEG decoding in addition to the OS itself.