Some notes:
* Unless `atmosphere!enable_log_manager` is true, Nintendo's log manager will be used instead.
* This prevents paying memory costs for LM when not enabling logging.
* To facilitate this, Atmosphere's log manager has a different program id from Nintendo's.
* `atmosphere!enable_htc` implies `atmosphere!enable_log_manager`.
* LogManager logs to tma, and the SD card (if `lm!enable_sd_card_logging` is true, which it is by default).
* Binary logs are saved to `lm!sd_card_log_output_directory`, which is `atmosphere/binlogs` by default.
mtc will jump back to us, so we need a compatible binary.
This also makes some changes to our layout to minimize the likelihood of
an incompatible mtc binary (I made some arbitrary .text/.rodata/.rwdata changes)
and saw identical mtc binaries, so hopefully this all works out.
Nintendo's Mariko tables result in trained frequency of 1599999 instead of 1600000.
PCV checks for rate == 1600000 exactly, when doing EMC init.
Thus EMC init does not succeed if we are trained to 1600000.
PCV has a fudge factor of 1000 used in SetEmcDvfsFreq, but this is not used in InitEmcDvfs.
This failure means that PCV cannot change rate back to 204MHz before sleep, and then after
wake extremely degraded performance is observed.
Restoring DRAM to 204MHz before boot causes EMC init to succeed/fixes performance degradation.
* ams: replace sept with tsec firmware
This replaces sept with a custom tsec key derivation firmware.
NOTE: This does not use any TSEC exploits whatsoever; it is a well-signed
TSEC binary assembled with envyas and signed with the real cauth key.
For more details, contact SciresM#0524.
* fusee: only set SBK if it's readable
* docs: update cheats doc to clarify Code Type 5 encoding
This change removes references to the "M" nibble for the "Register Address" encoding of Code Type 5 whis is not used in this mode.
In the dword block the "M" has been replaced with a "0"
* docs: update cheats doc to clarify register usage on Code Type 5
This adds additional clarification for "Register Address Encoding" mode of Code Type 5 that the "R" nibble reflects both the destination as well as the base memory address.
* docs: update cheats doc to make Code Types consistent
Code Types are now consistently written in hex notation.
* cs: add stub sysmodule to host command shell server
* cs: implement logic for main (linker error paradise, for now)
* cs: implement more of the system module's skeleton
* htcs: update client type names for libnx pr merge
* set.mitm: fake compatibility for usb!usb30_force_enabled on 9.0.0+
* set.mitm: add value meaning comment for usb!usb30_force_enabled
* loader: pretend to be polite about patch ordering
1. Follow the guide located [here](https://devkitpro.org/wiki/Getting_Started) to install and configure all the tools necessary for the build process.
1. Follow the guide located [here](https://devkitpro.org/wiki/Getting_Started) to install and configure all the tools necessary for the build process.
2. Install the following packages via (dkp-)pacman:
+ `switch-dev`
@@ -17,12 +18,7 @@ Building Atmosphère is a very straightforward process that relies almost exclus
+ `devkitARM`
+ `devkitarm-rules`
3.(Optional) In order to build [sept](components/sept.md) the pycryptodome PyPi package is required, which can be installed by running `pip install pycryptodome` under the installed Python environment of your choice or by installing the complete zip package to support the `make dist` recipe. This is an optional step included for advanced users who have the ability to provide the necessary encryption/signing keys themselves.
3.Install the following library via python's package manager `pip`, required by [exosphere](components/exosphere.md):
+ `lz4`
4.It is, instead, possible to build [sept](components/sept.md) by providing previously encrypted/signed binaries distributed by official Atmosphère release packages. In order to do so, export the following variables in your current environment:
+ `SEPT_00_ENC_PATH` (must point to the `sept-secondary_00.enc` file)
+ `SEPT_01_ENC_PATH` (must point to the `sept-secondary_01.enc` file)
+ `SEPT_DEV_00_ENC_PATH` (must point to the `sept-secondary_dev_00.enc` file)
+ `SEPT_DEV_01_ENC_PATH` (must point to the `sept-secondary_dev_01.enc` file)
5. Finally, clone the Atmosphère repository and run `make` under its root directory.
4.Finally, clone the Atmosphère repository and run `make` under its root directory.
+ `fusee` was completely re-written in C++ to use the same atmosphere-libs APIs as the rest of atmosphere's code.
+ The rewrite was performed with a big emphasis on ensuring a good boot speed, and generally boot should be much faster than it was previously.
+ Depending on SD card/environment, boot speed may now be slightly faster than, roughly the same as, or slightly slower than when booting with hekate.
+ The obvious low-hanging fruit for performance improvements has been picked, so hopefully the improved performance is to everybody's liking.
+ SD card compatibility was improved: fusee should now have SD card compatibility identical to the official OS driver.
+ **Please Note**: various components were renamed (fusee-primary.bin -> fusee.bin, fusee-secondary.bin -> package3).
+ If you use another bootloader (like hekate), you may need to update your configuration to use the new layout.
+ **Please Note**: BCT.ini no longer exists, nogc configuration has been moved to `/atmosphere/stratosphere.ini`.
+ If you rely on custom nogc configuration, please be sure to update accordingly.
+ Custom splash screen BMP parsing is no longer supported (as it slows down boot for 99% of users).
+ To compensate for this, a script to insert a custom splash screen into a `package3` binary has been added to the `utilities` folder of the atmosphere repository.
+ The release build should be equivalent to running the following command from the root of the atmosphere repository: `python utilities/insert_splash_screen.py img/splash.png fusee/package3`
+ A number of pending changes were made, following the end of the relevant testing periods:
+ `mesosphere` is no longer opt-out, and stratosphere code will begin depending on its being present/in use.
+ `NCM` is no longer opt-out.
+ The cleanup to ease the transition from < 0.19.0 to 0.19.0 has been removed.
+ General system stability improvements to enhance the user's experience.
## 0.20.1
+ An issue was fixed that caused severely degraded performance after wake-from-sleep on Mariko hardware.
+ This was due to Mariko MTC resulting in a frequency of 1599.999MHz instead of 1600MHz.
+ Due to this off-by-one, Nintendo's EMC management code failed to initialize/take over, and after wake from sleep RAM would be in a strange state.
+ General system stability improvements to enhance the user's experience.
## 0.20.0
+ DRAM training (MTC) was implemented for Mariko hardware, increasing RAM speed from 204MHz to 1600MHz.
+ This significantly optimizes Mariko boot speed, cutting boot time roughly in half.
+ Typical boot time reductions (measured as "select fusee" to "home menu visible"):
+ Normal (Iowa): ~35 seconds -> ~18 seconds.
+ Lite (Hoag): ~65 seconds -> ~30 seconds.
+ NOTE: Work is being started on a re-written `fusee` component, with an eye specifically towards ensuring a good boot speed.
+ With any luck, boot will be much much faster on all units (Mariko and Erista) in an upcoming release.
+ Sept was replaced, and deleted from the repository.
+ Erista units now use a custom TSEC firmware to manage key derivation.
+ For more details, contact SciresM#0524 on discord.
+ This has a number of benefits, including:
+ This greatly simplifies key derivation logic by making it consistent on all firmwares.
+ Fusee no longer accesses/uses keyblobs at all, so units which have accidentally destroyed/lost keyblobs can boot without them.
+ This greatly increases stability (sept was the biggest source of boot failures).
+ This improves boot speed (sept rebooted multiple times, performed hardware init multiple times, and was generally very slow).
+ Atmosphère build process is now much saner.
+ A number of improvements were made to the dmnt cheat engine.
+ Cheats which take in a memory region operand may now use types "2" or "3" to perform accesses relative to the alias/aslr regions, respectively.
+ Support was added for an "else" opcode in the cheat engine, to make writing certain conditional logic more natural.
+ Support was added for a cheat orchestrator homebrew (like edizon) to detach from a cheat process/set the master cheat programmatically.
+ Daybreak now provides a warning when attempting to install a firmware newer than the highest version atmosphère knows it supports.
+ To facilitate this, exosphere now exposes the supported HOS version via an extension ConfigItem.
+ A number of minor issues were fixed, including:
+ Several mesosphere debug SVC implementations were updated to reflect the semantics of the latest kernel.
+ Support was fixed for deriving BIS encryption keys on certain prototype hardware.
+ General system stability improvements to enhance the user's experience.
## 0.19.5
+ Support was added for 12.1.0.
+ LayeredFS support was added for OpenDataStorageWithProgramIndex commands.
+ Certain games using newer (7.0.0+ APIs) which include multiple programs under a single title previously could not be modified.
+ These are now supported as normal, and LayeredFS should have 100% compatibility again.
+ A number of minor issues were fixed, including:
+ The Reboot to Payload NRO was updated to allow the OS to save state prior to rebooting (thanks @AuroraWright)!
+ An issue was fixed that could cause dns.mitm to fail when games requested resolution of an empty string.
+ An issue was fixed that caused a memory leak in the erpt system module.
+ This would eventually cause a system crash after ~540 reports were generated without rebooting.
+ A number of minor improvements were made to improve mesosphere's accuracy.
+ General system stability improvements to enhance the user's experience.
## 0.19.4
+ Support was added for 12.0.3.
+ A number of minor issues were fixed, including:
+ An issue was fixed that could cause heap memory corruption when allocation was highly contended.
+ An issue was fixed that could cause sleep to fail under certain conditions.
+ An issue was fixed that could cause a scheduler slow path to be taken more often than necessary.
+ General system stability improvements to enhance the user's experience.
## 0.19.3
+ Support was added for 12.0.2.
+ A number of minor issues were fixed, including:
+ An issue was fixed in dns.mitm that caused a crash when games attempted to resolve the IP address of nullptr.
+ An issue was fixed in erpt that would cause an abort when booting without having ever booted stock previously.
+ An issue was fixed in (file-based) emummc that caused an error on system format/downloading certain games.
+ General system stability improvements to enhance the user's experience.
## 0.19.2
+ Atmosphère's components were further updated to reflect latest official behaviors as of 12.0.0.
+ Notably, `erpt` was updated to implement the new forced shutdown detection feature.
+ When a forced-shutdown occurs, an erpt_report will be generated and saved to the SD card on the next boot.
+ Atmosphere-libs was updated to use GCC 11 (latest devkitA64/devkitARM releases).
+ Initial inspections show mild-to-moderate optimizer improvements in several important places (kernel is 0x3000 smaller).
+ General system stability improvements to enhance the user's experience.
+ A number of minor issues were fixed, including:
+ A bug was fixed that caused a black screen when attempting to boot firmware versions 2.0.0-4.1.0.
+ A bug was fixed that caused sm to abort when at the session limit, rather than returning error codes.
+ A bug was fixed that allowed for resource exhaustion on 12.0.0, under certain circumstances.
+ Several issues were fixed, and usability and stability were improved.
## 0.19.1
+ An issue was fixed that caused a fatal error when using official `migration` services to transfer data between consoles.
+ An issue was fixed in `ncm` that caused an error when the OS tried to enumerate installed SD card content.
+ Several issues were fixed, and usability and stability were improved.
## 0.19.0
+ Support was added for 12.0.0.
+ `mesosphère` was updated to reflect the latest official kernel behavior.
+ `sm`, `boot2`, `pgl` were updated to reflect the latest official behaviors.
+ **Please Note**: 12.0.0 added a new protocol for IPC ("tipc"), which has been freshly reimplemented in its entirety.
+ It is possible there may be as of yet unfound issues; if there are, please send the appropriate crash reports to SciresM (SciresM#0524 on discord).
+ Homebrew which uses atmosphere extensions (including the mitm API) will need to be re-compiled in order to function on 0.19.0.
+ I apologize for this, but it's unavoidable for technical reasons. If you're affected by this and mad about it, please contact SciresM to complain.
+ `erpt` was partially updated to reflect the latest official behaviors.
+ New features were added to erpt to track the activity of running applets, and to detect when a forced shutdown occurs.
+ These behaviors have been temporarily stubbed, as they are not necessary for 12.0.0 to run (and their outputs won't be saved anywhere).
+ A future atmosphère update will implement these behaviors, in the interest of reflecting official logic as faithfully as we can.
+ Atmosphère no longer uses the /contents/ folder for its own programs.
+ Atmosphère's system modules are now bundled together in the single file "stratosphere.romfs".
+ For those working on developing for atmosphère, executables inside the /contents/ directory will be preferred to those in "stratosphere.romfs".
+ **Please Note**: In order to facilitate this change (and the desired behavior), the first time you boot after extracting a release zip, atmosphère system modules inside /contents/ will be deleted.
+ This will have no impact on user programs (it only removes programs with specific program ids).
+ Improvements were made to mesosphere, including:
+ An extension InfoType was added for getting the current process handle, without having to spawn a thread and do IPC with oneself.
+ An issue was fixed in SvcSetDebugThreadContext.
+ An issue was fixed when doing IPC with user buffers.
+ Support was fixed for toggling the custom setting `usb!usb30_force_enabled` on 9.0.0+.
+ This was broken by Nintendo's introducing a dependency that made USB a requirement to launch before custom settings are parsed.
+ Since the fix, you can now toggle the setting (as you could prior to atmosphère 0.9.4), and it will work as expected.
+ **Please Note**: Enabling USB 3.0 often severely impacts wireless communications.
+ Because of this, the setting will default to off. If you experience issues with it enabled, consider disabling it.
+ A warning was added to daybreak when resetting the console to factory settings.
+ Substantial work was completed towards atmosphere's upcoming implementation of the host target connection protocol.
+ Once completed, users will be able to interact with a Switch running atmosphère via a PC application ("Starlink") currently under development.
+ Planned eventual features for connected consoles include a gdbstub, interacting with memory (for cheat development), streaming gameplay audio and video, and accessing the Switch's SD card filesystem.
+ Switch homebrew will also have access to a (configurable and sandboxed) filesystem on the host PC, while connected.
+ Towards this end, the following was accomplished:
+ The "htc" system module was reimplemented completely.
+ The system module which provides remote access to the SD card was reimplemented completely.
+ This is currently the active focus of atmosphère's development.
+ **Please Note**: Support is not yet completed, and users are disadvised from interacting with the related settings for the time being, unless they particularly know what they're doing.
+ A number of minor issues were fixed, including:
+ A bug was fixed in `dmnt` that could cause a fatal when launching certain games with cheats active.
+ An issue was fixed that could cause an abort in `sm` when using a large number of custom system modules.
+ An issue was fixed that prevented launching gamecards on 1.0.0.
+ Minor issues were fixed in the cheat virtual machine's behavior.
+ Several issues were fixed, and usability and stability were improved.
## 0.18.1
+ A number of minor issues were fixed, including:
+ The new `dns.mitm` module added in 0.18.0 no longer fatal errors when receiving port=nullptr.
+ This fixes youtube ad-blocking, and possibly other usecases.
+ A bug was fixed that caused ams.mitm to incorrectly cache data storages.
+ This potentially broke DLC when using romfs mods, and could have caused other issues (e.g. with custom themes, and maybe other cases).
+ A bug was fixed in power state control module registration.
+ This might fix a weird edge case with system module dependencies on sleep/wake, but probably nobody should notice any differences.
+ A bug was fixed where mesosphere sometimes treated virtual core IDs as though they were physical core IDs.
+ This had zero impact, because for Switch virtual core == physical core, but it could have affected future platforms if it had remained unresolved.
+ Several issues were fixed, and usability and stability were improved.
## 0.18.0
+ A new mitm module was added (`dns.mitm`).
+ This provides a highly configurable mechanism for redirecting DNS resolution requests.
+ By default atmosphère redirects resolution requests for official telemetry servers to a loopback address.
+ Documentation on how to configure `dns.mitm` to meet your more specific needs may be found [here](https://github.com/Atmosphere-NX/Atmosphere/blob/master/docs/features/dns_mitm.md).
+ The service framework API (`sf`) was refactored to be more accurate to official logic and greatly reduce memory requirements.
+ The comparison of atmosphère module memory usage versus Nintendo's found [here](https://github.com/Atmosphere-NX/Atmosphere/wiki/Memory-Comparisons) was updated to reflect this.
+ **Please Note**: If you are a developer using the libstratosphere service APIs, some updating may be required. Contact SciresM#0524 on discord for assistance if required.
+ A number of deprecations were removed, following a general codebase cleanup:
+ The `sm` extension to not unregister services on connection close was superseded by official opt-in logic in 11.0.0, and has been removed in favor of official logic.
+ This should have zero impact on users.
+ The temporary `hid-mitm` added in 0.9.0 has finally been removed, following over a year of deprecation.
+ There shouldn't be any homebrew in use still affected by this, but the situation will be monitored.
+ If this is somehow still a real issue, an unaffiliated hid mitm sysmodule providing the same functionality can be created and released, separate from atmosphère itself.
+ Several issues were fixed, and usability and stability were improved.
## 0.17.1
+ A number of atmosphère's modules were using more memory than their Nintendo equivalent's in 0.17.0; a number of code generatio tweaks have been applied to fix this across the board.
+ A detailed comparison of atmosphère module memory usage versus Nintendo's was made and can be found [here](https://github.com/Atmosphere-NX/Atmosphere/wiki/Memory-Comparisons).
+ Several minor bugs were fixed, including:
+ A bug was fixed in mesosphère that caused games which attempt to map more memory than the Switch has to fail.
+ This affected "Piczle Lines DX 500 More Puzzles!", and possibly other games.
+ Enabling configuration to "blank" PRODINFO no longer causes a hang on Mariko devices (or any devices with newer format).
+ Several issues were fixed, and usability and stability were improved.
## 0.17.0
+ fusee was heavily rewritten in order to add support for Mariko hardware.
+ **Please Note**: Mariko hardware currently has no (and may not ever have any) software exploits; fusee works when loaded from bootloader context with the right keys in the security engine. No means of getting the system into this state is provided.
+ An issue was fixed in the way shutdown was performed on Erista hardware.
+ This fixes an issue that caused OFW to black screen on boot after power off from atmosphere without first doing a reboot.
+ This also substantially improves power drain when the system is shut off; consoles powered off from Atmosphere should now drain battery at the same reduced rate as original firmware.
+ A number of minor changes were made, including:
+ A number of inconsistencies in the build system were fixed.
+ For those building atmosphère at home, the `boot` sysmodule will no longer rebuild every time make is invoked.
+ This substantially improves build times during development iteration.
+ `sm` was updated to more accurately reflect how official code manages request deferral.
+ `mesosphère` was updated to more accurately reflect official kernel management of the trace buffer.
+ `mesosphère` was updated to improve kernel loader's logic by taking advantage of the assumption that we only boot our kernel, not Nintendo's.
+ As it has been a few months with zero reported issues, `mesosphère` is now opt-out.
+ Users who wish to begin using or continue using mesosphere should use the standard/cool kids zip ("atmosphere-").
+ Users who wish to opt-out of mesosphere should download and extract the opt-out zip ("atmosphere-WITHOUT_MESOSPHERE-").
+ Several issues were fixed, and usability and stability were improved.
## 0.16.2
+ Atmosphère release zips no longer bundle BCT.ini, instead relying on defaults in code.
+ This means atmosphere updates should no longer overwrite any user configuration at all.
+ If you wish to modify BCT.ini config, copy the template from /config_templates/ as with other configuration.
+ `pgl` and `creport` were further updated to reflect differences in official behavior in 11.0.0.
+ An issue was fixed that caused creport to be launched multiple times on process crash.
+ This fixes the "duplicate reports" issue that sometimes plagued people.
+ A new system setting (`atmosphere!enable_am_debug_mode`) configuring am to use debug mode.
+ If you are not a developer or don't see a clear use for this, leave it configured to the default (off).
+ Reboot to payload NRO was updated to fix support with certain payloads.
+ Support was fixed for atmosphere's extension to support homebrew use of new (8.0.0+) kernel mappings.
+ In particular, when running tracing debug builds of `mesosphère`, hbloader now has access to the kernel trace buffer.
+ Several issues were fixed, and usability and stability were improved.
## 0.16.1
+ Support was added for 11.0.1.
+ `mesosphère` was updated to reflect the latest official kernel behavior.
+ A new svc::InfoType added in 11.0.0 was implemented (it wasn't discovered before 0.16.0 released).
+ The new Control Flow Integrity (CFI) logic added in 11.0.0 kernel was implemented.
+ `fs` logic was refactored and cleaned up to reflect some newer sysmodule behavioral and structural changes.
+ `exosphère` was updated to allow dynamic control of what uart port is used for logging.
+ This can be controlled by editing the `log_port`, `log_baud_rate`, and `log_inverted` fields in `exosphere.ini`.
+ `mesosphère` was updated to improve debugging capabilities.
+ This is still a work in progress, but developers may be interested.
+ A bug was fixed that caused `fatal` to fatal error if the fatal process was already being debugged.
+ Several issues were fixed, and usability and stability were improved.
## 0.16.0
+ Support was added for 11.0.0.
+ `exosphère` was updated to reflect the latest official secure monitor behavior.
+ `mesosphère` was updated to reflect the latest official kernel behavior.
+ `loader`, `sm`, `boot`, `pgl` were updated to reflect the latest official behaviors.
+ **Please Note**: 11.0.0 implements an opt-in version of the atmosphère `sm` extension that allows for closing session without unregistering services.
+ Correspondingly, the extension will be deprecated in favor of the new official opt-in command. In 0.17.0, it will be removed entirely.
+ If your custom system module relies on this extension (however unlikely that seems to me), please update it accordingly.
+ `erpt` was partially updated to provide compatibility with 11.0.0.
+ The latest firmware attaches additional fields and context information to logs.
+ A future atmosphère update will implement this logic, so that users who are interested can also get the new information when examining their logs.
+ **Please Note**: 11.0.0 introduced breaking changes to the `usb` system module's `usb:ds` API.
+ Homebrew which uses the `usb:ds` service should rebuild with the latest libnx version to support running on 11.0.0.
+ The `boot` system module was rewritten to reflect the huge driver changes introduced in 8.0.0.
+ This includes a number of improvements to both logo display and battery management logic.
+ Support was added for configuring the address space width for `hbl`.
+ The `hbl_config!override_address_space_(#)` and `hbl_config!override_any_app_address_space` can now be set to `39_bit`, `36_bit`, or `32_bit` to control the address space for hbl on a per-override basis.
+ If a configuration has not been set, hbl will now default to 39-bit address space.
+ Previously, a legacy 36-bit address space was always used to maintain compatibility with 1.0.0.
+ A new loader extension was added to support 39-bit whenever possible (including mesosphere-on-1.0.0), with fallback to 36-bit when unavailable.
+ Support was added to a number of components for running on Mariko hardware.
+ The `boot` system module can now safely be run on mariko hardware, performing correct hardware initialization.
+ Daybreak (and generally, system update logic) were updated to be usable on Mariko.
+ Boot0 protection/management logic was updated to perform correct actions on Mariko.
+ Reboot to payload does not and cannot work on Mariko. Correspondingly, A "fatal error" handler was written, to display and save fatal errors from within TrustZone.
+ **Please Note:** Atmosphere is still not properly usable on Mariko hardware.
+ In particular, wake-from-sleep will not properly function (the magic numbers aren't set correctly), among a few other minor issues.
+ `exosphère` received support for building under debug configuration.
+ A small (otherwise unused) portion of IRAM is now reserved for debug-only exosphere code (this region is unused/untouched under release config).
+ This enables logging (including printf) to uart from the secure monitor, for those interested.
+ A number of bugs were fixed, including:
+ Minor issues in a number of filesystem related code were fixed.
+ An issue was fixed that could cause NCM to abort on consoles which came with 3.0.x and were never updated.
+ Several issues were fixed, and usability and stability were improved.
## 0.15.0
+ fusee-primary's panic display was updated to automatically identify and give suggestions to resolve many of the most common errors users encounter.
+ Having been tested as well as I can alone, `mesosphere` (atmosphère's reimplementation of the Nintendo Switch kernel) is now available for users interested in trying it.
fusée is a custom bootloader used to start the Atmosphère environment.
It is divided into three sub-components: fusée-primary, fusée-mtc and fusée-secondary.
fusée is also capable of chainloading other payloads (e.g.: Android).
fusée's behavior can be configured via the [BCT.ini](../features/configurations.md) file located on the SD card.
## fusée-primary
fusée-primary is the first piece of Atmosphère's code that runs on the hardware.
## fusée
fusée is the first piece of Atmosphère's code that runs on the hardware.
It is distributed as a standalone payload designed to be launched via RCM by abusing the CVE-2018-6242 vulnerability.
This payload is responsible for all the low-level hardware initialization required by the Nintendo Switch, plus the extra task of initializing the SD card and reading the next fusée sub-components from it.
## fusée-mtc
fusée-mtc is an optional, but heavily recommended sub-component that performs DRAM memory training.
This ensures a proper environment for running the final fusée sub-component.
## fusée-secondary
fusée-secondary is the last fusée sub-component that runs on the system.
It is responsible for configuring and bootstrapping the Atmosphère environment by mimicking the Horizon OS's design.
This includes setting up the cryptosystem, mounting or emulating the eMMC, injecting or patching system modules and launching the exosphère component.
This payload is responsible for all the low-level hardware initialization required by the Nintendo Switch, setting up the cryptosystem, mounting/emulating the eMMC, injecting/patching system modules, and launching the exosphère component.
@@ -33,3 +33,8 @@ in settings as `#.#.#|AMS #.#.#|?` with `? = S` when running under system eMMC o
### System Settings
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](../../features/configurations.md) for more information on the system settings format.
## dns_mitm
dns_mitm enables intercepting requests to dns resolution services, to enable redirecting requests for specified hostnames.
For documentation, see [here](../../features/dns_mitm.md).
Sept is a payload that facilitates booting Atmosphère when targeting firmware version 7.0.0+.
It consists of a primary and a secondary payload.
## sept-primary
sept-primary is essentially a stand-in for Nintendo's package1ldr, on 7.0.0+. To use it, the caller (normally fusée-secondary) loads the sept-primary binary to `0x4003F000`, loads the 7.0.0+ TSEC firmware to `0x40010F00`, and loads a signed, encrypted payload to `0x40016FE0`.
This signed, encrypted payload is normally sept-secondary.
## sept-secondary
sept-secondary is a payload that performs 7.0.0+ key derivation, and then chainloads to `sept/payload.bin`.
It is normally stored encrypted/signed. Therefore, if one wishes to build sept-secondary instead of using release builds, one must bring their own keys.
@@ -19,6 +19,8 @@ This behavior ensures that cheat codes are only loaded when the user would want
In cases where `dmnt` has not activated the cheat manager, but the user wants to make it do so anyway, the cheat manager's service API provides a `ForceOpenCheatProcess` command that homebrew can use. This command will cause the cheat manager to try to force itself to attach to the process.
In cases where `dmnt` has activated the cheat manager, but the user wants to use an alternate debugger, the cheat manager's service API provides a `ForceCloseCheatProcess` command that homebrew can use. This command will cause the cheat manager to detach itself from the process.
By default, all cheat codes listed in the loaded .txt file will be toggled on. This is configurable by the user by editing the `atmosphere!dmnt_cheats_enabled_by_default` [system setting](configurations.md).
Users may use homebrew programs to toggle cheats on and off at runtime via the cheat manager's service API.
@@ -40,30 +42,30 @@ The following provides documentation of the instruction format for the virtual m
Typically, instruction type is encoded in the upper nybble of the first instruction u32.
### Code Type 0: Store Static Value to Memory
Code type 0 allows writing a static value to a memory address.
### Code Type 0x0: Store Static Value to Memory
Code type 0x0 allows writing a static value to a memory address.
#### Encoding
`0TMR00AA AAAAAAAA VVVVVVVV (VVVVVVVV)`
+ T: Width of memory write (1, 2, 4, or 8 bytes).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap, 2 = Alias, 3 = Aslr).
+ R: Register to use as an offset from memory region base.
+ A: Immediate offset to use from memory region base.
+ V: Value to write.
---
### Code Type 1: Begin Conditional Block
Code type 1 performs a comparison of the contents of memory to a static value.
### Code Type 0x1: Begin Conditional Block
Code type 0x1 performs a comparison of the contents of memory to a static value.
If the condition is not met, all instructions until the appropriate conditional block terminator are skipped.
If the condition is not met, all instructions until the appropriate End or Else conditional block terminator are skipped.
#### Encoding
`1TMC00AA AAAAAAAA VVVVVVVV (VVVVVVVV)`
+ T: Width of memory write (1, 2, 4, or 8 bytes).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap, 2 = Alias, 3 = Aslr).
+ C: Condition to use, see below.
+ A: Immediate offset to use from memory region base.
+ V: Value to compare to.
@@ -78,16 +80,20 @@ If the condition is not met, all instructions until the appropriate conditional
---
### Code Type 2: End Conditional Block
Code type 2 marks the end of a conditional block (started by Code Type 1 or Code Type 8).
### Code Type 0x2: End Conditional Block
Code type 0x2 marks the end of a conditional block (started by Code Type 0x1 or Code Type 0x8).
When an Else is executed, all instructions until the appropriate End conditional block terminator are skipped.
#### Encoding
`20000000`
`2X000000`
+ X: End type (0 = End, 1 = Else).
---
### Code Type 3: Start/End Loop
Code type 3 allows for iterating in a loop a fixed number of times.
### Code Type 0x3: Start/End Loop
Code type 0x3 allows for iterating in a loop a fixed number of times.
#### Start Loop Encoding
`300R0000 VVVVVVVV`
@@ -102,8 +108,8 @@ Code type 3 allows for iterating in a loop a fixed number of times.
---
### Code Type 4: Load Register with Static Value
Code type 4 allows setting a register to a constant value.
### Code Type 0x4: Load Register with Static Value
Code type 0x4 allows setting a register to a constant value.
#### Encoding
`400R0000 VVVVVVVV VVVVVVVV`
@@ -113,29 +119,28 @@ Code type 4 allows setting a register to a constant value.
---
### Code Type 5: Load Register with Memory Value
Code type 5 allows loading a value from memory into a register, either using a fixed address or by dereferencing the destination register.
### Code Type 0x5: Load Register with Memory Value
Code type 0x5 allows loading a value from memory into a register, either using a fixed address or by dereferencing the destination register.
#### Load From Fixed Address Encoding
`5TMR00AA AAAAAAAA`
+ T: Width of memory read (1, 2, 4, or 8 bytes).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap, 2 = Alias, 3 = Aslr).
+ R: Register to load value into.
+ A: Immediate offset to use from memory region base.
#### Load from Register Address Encoding
`5TMR10AA AAAAAAAA`
`5T0R10AA AAAAAAAA`
+ T: Width of memory read (1, 2, 4, or 8 bytes).
+ M: Memory region to write to (0 = Main NSO, 1 = Heap).
+ R: Register to load value into.
+ R: Register to load value into. (This register is also used as the base memory address).
+ A: Immediate offset to use from register R.
---
### Code Type 6: Store Static Value to Register Memory Address
Code type 6 allows writing a fixed value to a memory address specified by a register.
### Code Type 0x6: Store Static Value to Register Memory Address
Code type 0x6 allows writing a fixed value to a memory address specified by a register.
#### Encoding
`6T0RIor0 VVVVVVVV VVVVVVVV`
@@ -149,10 +154,10 @@ Code type 6 allows writing a fixed value to a memory address specified by a regi
---
### Code Type 7: Legacy Arithmetic
Code type 7 allows performing arithmetic on registers.
### Code Type 0x7: Legacy Arithmetic
Code type 0x7 allows performing arithmetic on registers.
However, it has been deprecated by Code type 9, and is only kept for backwards compatibility.
However, it has been deprecated by Code type 0x9, and is only kept for backwards compatibility.
#### Encoding
`7T0RC000 VVVVVVVV`
@@ -171,8 +176,8 @@ However, it has been deprecated by Code type 9, and is only kept for backwards c
---
### Code Type 8: Begin Keypress Conditional Block
Code type 8 enters or skips a conditional block based on whether a key combination is pressed.
### Code Type 0x8: Begin Keypress Conditional Block
Code type 0x8 enters or skips a conditional block based on whether a key combination is pressed.
#### Encoding
`8kkkkkkk`
@@ -213,8 +218,8 @@ Note: This is the direct output of `hidKeysDown()`.
---
### Code Type 9: Perform Arithmetic
Code type 9 allows performing arithmetic on registers.
### Code Type 0x9: Perform Arithmetic
Code type 0x9 allows performing arithmetic on registers.
#### Register Arithmetic Encoding
`9TCRS0s0`
@@ -248,8 +253,8 @@ Code type 9 allows performing arithmetic on registers.
---
### Code Type 10: Store Register to Memory Address
Code type 10 allows writing a register to memory.
### Code Type 0xA: Store Register to Memory Address
Code type 0xA allows writing a register to memory.
#### Encoding
`ATSRIOxa (aaaaaaaa)`
@@ -272,13 +277,13 @@ Code type 10 allows writing a register to memory.
---
### Code Type 11: Reserved
Code Type 11 is currently reserved for future use.
### Code Type 0xB: Reserved
Code Type 0xB is currently reserved for future use.
---
### Code Type 12-15: Extended-Width Instruction
Code Types 12-15 signal to the VM to treat the upper two nybbles of the first dword as instruction type, instead of just the upper nybble.
### Code Type 0xC-0xF: Extended-Width Instruction
Code Types 0xC-0xF signal to the VM to treat the upper two nybbles of the first dword as instruction type, instead of just the upper nybble.
This reserves an additional 64 opcodes for future use.
Atmosphère provides a variety of customizable configurations to better adjust to users' needs.
## BCT.ini
This is the configuration file used by fusée.
## stratosphere.ini
This is the configuration file used by fusée for configuring user-space system modules.
This file is located under the `/atmosphere/config/` folder on your SD card and a default template can be found inside the `/atmosphere/config_templates/` folder.
### Adding a Custom Boot Splashscreen
Atmosphère provides its own default splashscreen which is displayed at boot time. However, this can be replaced at will.
The boot splashscreen must be a BMP file, it must be 720x1280 (1280x720 rotated 90 degrees left/counterclockwise/anti-clockwise) resolution, and be in 32-bit ARGB format. You can use image editing software such as GIMP or Photoshop to export the image in this format.
Add the following lines to BCT.ini and change the value of `custom_splash` to the actual path and filename of your boot splashscreen:
```
[stage2]
custom_splash = /path/to/your/bootlogo.bmp
```
### Configuring "nogc" Protection
"nogc" is a feature provided by fusée-secondary which disables the Nintendo Switch's Game Card reader. Its purpose is to prevent the reader from being updated when the console has been updated, without burning fuses, from a lower firmware version. More specifically, from firmware versions 4.0.0 or 9.0.0 which introduced updates to the Game Card reader's firmware. By default, Atmosphère will protect the Game Card reader automatically, but you are free to change it.
@@ -29,32 +18,15 @@ nogc = X
0 = force-disable nogc, so Atmosphère will always enable the Game Card reader.
```
### NCM opt-out
Atmosphère provides a reimplementation of the [ncm](../components/modules/ncm.md) system module. If you wish to disable this reimplementation add the following line to the `stratosphere` section:
```
[stratosphere]
disable_ncm = 1
```
## Adding a Custom Boot Splashscreen
Atmosphère provides its own default splashscreen which is displayed at boot time. However, this can be replaced at will.
### Logging
This is an advanced feature aimed at developers trying to debug boot time issues. It enables logging of the fusée stages to be displayed on screen.
Boot splash screens must be 1280x720 resolution.
Add the following lines to BCT.ini and change the value of `X` according to the following list:
```
[config]
log_level = X
```
```
0 = NONE
1 = ERROR
2 = WARNING
3 = MANDATORY
4 = INFO
5 = DEBUG
```
A script can be found inside the source tree (`/utilities/insert_splash_screen.py`) for inserting a custom splash screen into a release binary.
A special level is also provided to prevent prefix creation. To use it, do a bitwise OR with this mask:
`0x100 = NO_PREFIX`
To do so, execute the following command on the script:
`python insert_splash_screen.py <path to your splash screen image> <path to /atmosphere/package3 on your SD card>`
## emummc.ini
This is the configuration file used for the [emummc](../components/emummc.md) component.
As of 0.18.0, atmosphère provides a mechanism for redirecting DNS resolution requests.
By default, atmosphère redirects resolution requests for official telemetry servers, redirecting them to a loopback address.
## Hosts files
DNS.mitm can be configured through the usage of a slightly-extended `hosts` file format, which is parsed only once on system startup.
In particular, hosts files parsed by DNS.mitm have the following extensions to the usual format:
+ `*` is treated as a wildcard character, matching any collection of 0 or more characters wherever it occurs in a hostname.
+ `%` is treated as a stand-in for the value of `nsd!environment_identifier`. This is always `lp1`, on production devices.
If multiple entries in a host file match a domain, the last-defined match is used.
Please note that homebrew may trigger a hosts file re-parse by sending the extension IPC command 65000 ("AtmosphereReloadHostsFile") to a connected `sfdnsres` session.
### Hosts file selection
Atmosphère will try to read hosts from the following file paths, in order, stopping once it successfully performs a file read:
+ (emummc only) `/atmosphere/hosts/emummc_%04lx.txt`, formatted with the emummc's id number (see `emummc.ini`).
+ (emummc only) `/atmosphere/hosts/emummc.txt`.
+ (sysmmc only) `/atmosphere/hosts/sysmmc.txt`.
+ `/atmosphere/hosts/default.txt`
If `/atmosphere/hosts/default.txt` does not exist, atmosphère will create it to contain the defaults.
### Atmosphère defaults
By default, atmosphère's default redirections are parsed **in addition to** the contents of the loaded hosts file.
This is equivalent to thinking of the loaded hosts file as having the atmosphère defaults prepended to it.
This setting is considered desirable, because it minimizes the telemetry risks if a user forgets to update a custom hosts file on a system update which changes the telemetry servers.
This behavior can be opted-out from by setting `atmosphere!add_defaults_to_dns_hosts = u8!0x0` in `system_settings.ini`.
On startup (or on hosts file re-parse), DNS.mitm will log both what hosts file it selected and the contents of all redirections it parses to `/atmosphere/logs/dns_mitm_startup.log`.
In addition, if the user sets `atmosphere!enable_dns_mitm_debug_log = u8!0x1` in `system_settings.ini`, DNS.mitm will log all requests to GetHostByName/GetAddrInfo to `/atmosphere/logs/dns_mitm_debug.log`. All redirections will be noted when they occur.
## Opting-out of DNS.mitm entirely
If you wish to disable DNS.mitm entirely, `system_settings.ini` can be edited to set `atmosphere!enable_dns_mitm = u8!0x0`.
atmosphère has a number of features that are either works-in-progress or planned. Please note that while time-estimates are given, they are loose, and things may be completed sooner or later than advertised.
The following descriptions were last updated on July 7th, 2020.
## ams-on-mariko
* **Description**: Atmosphere cannot run as-is on Mariko hardware. A large number of changes are needed in many components. Although secure monitor support is complete in exosphere, additional work is needed on the bootloader and stratosphere sides as well. Mariko support will also require further design thought; atmosphere's debugging design heavily relies on reboot-to-payload and (more generally) the ability to perform warmboot bootrom hax at will. This is not possible on Mariko, and will require a new design/software support for whatever solution is chosen.
* **Development Status**: Planned.
* **Estimated Time**: Summer 2020
## settings reimplementation
* **Description**: A planned reimplementation of the settings system module, and with it a removal of the settings mitm. This will greatly simplify atmosphère's boot process, and will allow much more flexible control over the various system settings.
* **Development Status**: Undergoing research/initial development by Adubbz.
* **Estimated Time**: Mid 2020
## mesosphere
* **Description**: mesosphère is a reimplementation of the Horizon operating system's Kernel. It aims to provide an open-source reference for Nintendo's code.
* **Development Status**: Under active development by SciresM.
* **Estimated Time**: Mid-to-Late 2020
The following descriptions were last updated on January 14th, 2021
## tma reimplementation
* **Description** tma ("target manager agent") is a system module that manages communication between the Switch and a client PC. Atmosphere's implementation will allow homebrew on the switch to communicate with a connected PC to do various operations such as exchanging data or interacting with files. It will also serve as the communicator for Atmosphère's planned debugger. This will also include PC-side software for interacting with the Switch.
* **Development Status**: Planned. Switch-side code is fully implemented but needs heavy refactoring/rebasing, as the code was originally authored in 2018.
* **Estimated Time**: Late 2020-2021.
* **Estimated Time**: 2021-2022.
## dmnt.gen2 reimplementation
* **Description**: A reimplementation of the Switch's debug monitor, dmnt will provide an interface for debugging applications or system modules running on the Switch. This will include a gdbstub for debugging actively-running system components or applications.
* **Development Status**: Planned
* **Estimated Time**: 2021
* **Estimated Time**: 2021-2022
## fs reimplementation
* **Description**: Following mesosphère's completion, atmosphère will have reimplemented all components of the BootImagePackage firmware except for the filesystem services system module. Reimplementing fs will allow for fixing Nintendo bugs (such as corruption when using exFAT filesystems and encoding inconsistencies with UTF-8 and Shift-JIS).
* **Development Status**: Planned.
* **Estimated Time**: 2021-2022.
## settings reimplementation
* **Description**: A planned reimplementation of the settings system module, and with it a removal of the settings mitm. This will greatly simplify atmosphère's boot process, and will allow much more flexible control over the various system settings.
* **Development Status**: Pending development by Adubbz.
* **Description**: A general-purpose hypervisor, thermosphère will enable the virtualization of the Switch's operating system; this is planned to enable debugging of the Switch's kernel.
* **Development Status**: Under semi-active development by TuxSH.
* **Estimated Time**: 2020-2021.
* **Development Status**: Pending development by TuxSH.
* **Description**: General system stability improvements to enhance the user's experience.
@@ -59,4 +49,12 @@ Please note that this is not an exhaustive list of features present in atmosphè
## exosphere re-write
* **Description**: exosphère, atmosphère's reimplementation of Horizon's Secure Monitor, was the first component authored for the project in early 2018. It is written in C, and in a style very different from the rest of atmosphère's code. In addition, exosphère was written to conform to constraints that no longer apply in an environment where it is not launched from the web browser, and where using a custom firmware image to orchestrate wake-from-sleep is possible. exosphère currently uses all but 1 KB of the space available to it, putting it at risk of breaking as future firmware updates are supported. A re-write will solve these issues.
* **Completion Time**: June 2020
***Completion Time**: June 2020
## mesosphere
* **Description**: mesosphère is a reimplementation of the Horizon operating system's Kernel. It aims to provide an open-source reference for Nintendo's code.
* **Estimated Time**: September 2020
## ams-on-mariko
* **Description**: Atmosphere cannot run as-is on Mariko hardware. A large number of changes are needed in many components. Although secure monitor support is complete in exosphere, additional work is needed on the bootloader and stratosphere sides as well. Mariko support will also require further design thought; atmosphere's debugging design heavily relies on reboot-to-payload and (more generally) the ability to perform warmboot bootrom hax at will. This is not possible on Mariko, and will require a new design/software support for whatever solution is chosen.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.