diff --git a/Home.md b/Home.md index c9cc2e0..44e64a7 100644 --- a/Home.md +++ b/Home.md @@ -1,5 +1,30 @@ -Welcome to the Atmosphère wiki! +# Atmosphère +Atmosphère is a work-in-progress customized firmware for the Nintendo Switch. Its design principle consists of a multi-layered approach where each layer replaces/modifies a different component of the Nintendo Switch's system. -This page is a work-in-progress, and will be more updated soon. +## Components +Atmosphère provides six core components, mimicking to some degree the various layers of the Earth's atmosphere: ++ [fusée](components/fusee.md) ++ [exosphère](components/exosphere.md) ++ [thermosphère](components/thermosphere.md) ++ [mesosphère](components/mesosphere.md) ++ [stratosphère](components/stratosphere.md) ++ [troposphère](components/troposphere.md) -For information on release plans, see [here](release-plans). \ No newline at end of file +Additionally, Atmosphère also provides the following secondary components: ++ [emummc](components/emummc.md) ++ [sept](components/sept.md) ++ [libraries](components/libraries.md) + +## Features +Atmosphère provides several original features which add or expand functionalities for the customized firmware environment: ++ [Cheats](features/cheats.md) ++ [Configurations](features/configurations.md) + +## Building Atmosphère +A guide to building Atmosphère can be found [here](building.md). + +## Upcoming Features +A list of planned features for Atmosphère can be found [here](roadmap.md). + +## Release History +A changelog of previous versions of Atmosphère can be found [here](changelog.md). diff --git a/building.md b/building.md new file mode 100644 index 0000000..a96173c --- /dev/null +++ b/building.md @@ -0,0 +1,27 @@ +# Building Atmosphère +Building Atmosphère is a very straightforward process that relies almost exclusively on tools provided by the [devkitPro](https://devkitpro.org) organization. + +## Dependencies ++ [devkitA64](https://devkitpro.org) ++ [devkitARM](https://devkitpro.org) ++ [Python 2 or 3](https://www.python.org) (optional) ++ [PyCryptodome](https://pypi.org/project/pycryptodome) (optional) + +## Instructions +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` + + `switch-libjpeg-turbo` + + `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. + +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. diff --git a/changelog.md b/changelog.md new file mode 100644 index 0000000..9f43dfd --- /dev/null +++ b/changelog.md @@ -0,0 +1,700 @@ +# Changelog + +## 0.12.0 ++ Configuration for exosphere was moved to sd:/exosphere.ini. + + This is to facilitate BIS protection changes described below. + + Hopefully having this outside of the Atmosphere folder will prevent accidental deletion, since this now contains important settings. ++ Atmosphere's bis protection policy for the PRODINFO partition was substantially reworked. + + Support was added for "automatically" performing a "blanking" operation to PRODINFO without actually modifying NAND. + + This is equivalent to using the "incognito" homebrew tool, but NAND is never actually modified. + + This can be turned on in sysmmc by setting `blank_prodinfo_sysmmc=1` in exosphere.ini, and in emummc by setting `blank_prodinfo_emummc=1` in exosphere.ini. + + **Please note**: This is not known to be safe. There is a lack of research on whether the information blanked out is cached elsewhere in the system. + + Usage of this option is not encouraged for this reason. + + Support was added for writing to the PRODINFO partition, if a verified encrypted backup has been made. + + PRODINFO is the only system data that cannot be recovered if not backed up, and thus Atmosphere has backed it up to the SD card on boot for some time now. + + Users who wish to modify their calibration data may now do so unconditionally in emummc, and in sysmmc if `allow_writing_to_cal_sysmmc=1` is set in exosphere.ini. + + **Please note**: This is heavily discouraged, and the typical user will almost never want to do this. + + Setting this option will cause Atmosphere to attempt to verify (or create) an encrypted backup of the PRODINFO data to an unused region in the partition. + + The backup is encrypted with per-console keys that Atmosphere's developers do not know. + + If the backup is not verified or created, writes will not work. Users who have corrupted their PRODINFO in the past are encouraged to flash a good backup to allow use of this setting. + + Reads and writes to the region used for the securely encrypted backup will appear to succeed, but will actually read/write from a buffer filled with garbage in memory. + + Support will be investigated in the future for supporting booting with fully blanked calibration. + + This is desirable to allow boot to succeed for users who lost their calibration data due to bricking homebrew before bis protection was implemented. ++ `creport` has been updated to use the new screenshot APIs added in 9.0.0+. + + On 10.0.0+, if a crash occurs in an application (not applet or sysmodule) a screenshot will now be automatically saved to the SD card. + + If the user applies a patch to vi on 9.0.0 (as the command this uses was previously for dev-units only), this can also work on 9.0.0. ++ The new sysmodule `pgl` added in 10.0.0 was reimplemented. + + `pgl` ("Program Launcher", probably) is responsible for managing launched user-processes, previously this was handled by NS. + + The most exciting thing about pgl is that it finally provides an API for multiple clients to subscribe to process events. + + Using these new APIs, system modules / other homebrew can subscribe to be notified whenever a process event occurs. + + This means action can be taken on process launch, process exit, process crash, etc. + + A slight concern with Nintendo's implementation is that each subscriber object uses 0x448 bytes of memory, and N only reserves 8KB for all allocations in pgl. + + Atmosphere's implementation uses a 32KB heap, which should not be exhaustible. + + Atmosphere's implementation has a total memory footprint roughly 0x28000 bytes smaller than Nintendo's. ++ A reimplementation was added for the `jpegdec` system module (thanks @HookedBehemoth)! + + This allows two sessions instead of 1, so homebrew can now use it for software jpeg decoding in addition to the OS itself. + + As usual the implementation has a very slightly smaller memory footprint than Nintendo's. ++ `dmnt`'s Cheat VM was extended to add three new opcodes. + + The first new opcode, "ReadWriteStaticRegister", allows for cheats to read from a bank of 128 read-only static registers, and write to a bank of 128 write-only static registers. + + This can be used in concert with new IPC commands that allow a cheat manager to read or write the value of these static registers to have "dynamic" cheats. + + As an example, a cheat manager could write a value to a static register that a cheat to control how many of an item to give in a game. + + As another example, a cheat manager could read a static register that a cheat writes to to learn how many items a player has. ++ The second and third opcodes are a pair, "PauseProcess" and "ResumeProcess". + + Executing pause process in a cheat will pause the game (it will be frozen) until a resume process opcode is used. + + These are also available over IPC, for cheat managers or system modules that want to pause or resume the attached cheat process. + + This allows a cheat to know that the game won't modify or access data the cheat is accessing. + + For example, this can be used to prevent Pokemon from seeing a pokemon a cheat is in the middle of injecting and turning it into a bad egg. ++ A bug was fixed that would cause the console to crash when connected to Wi-Fi on versions between 3.0.0 and 4.1.0 inclusive. ++ A bug was fixed that could cause boot to fail sporadically due to cache/tlb mismanagement when doing physical ASLR of the kernel. ++ A number of other minor issues were addressed (and more of Atmosphere was updated to reflect other changes in 10.0.x). ++ General system stability improvements to enhance the user's experience. + +## 0.11.1 ++ A bug was fixed that could cause owls to flicker under certain circumstances. + + For those interested in technical details, in 10.0.0 kernelldr/kernel no longer set cpuactlr_el1, assuming that it was set correctly by the secure monitor. + + However, exosphere did not set cpuactlr_el1. This meant that the register held the reset value going into boot. + + This caused a variety of highly erratic symptoms, including causing basically any game to crash seemingly randomly. ++ A number of other major inaccuracies in exosphere were corrected. ++ General system stability improvements to enhance the user's experience. + +## 0.11.0 ++ Support was added for 10.0.0. + + Exosphere has been updated to reflect the new key import semantics in 10.0.0. + + kernel_ldr now implements physical ASLR for the kernel's backing pages. + + Loader, NCM, and PM have been updated to reflect the changes Nintendo made in 10.0.0. + + Creport was updated to use the new `pgl` service to terminate processes instead of `ns:dev`. ++ A reimplementation of the `erpt` (error reports) system module was added. + + In previous versions of Atmosphere, a majority of error reports were prevented via a combination of custom creport, fatal, and stubbed eclct. + + However, error reports were still generated via some system actions. + + Most notably, any time the error applet appeared, an error report was generated. + + By default, atmosphere disabled the *uploading* of error reports, but going online in OFW after an error report occurred in Atmosphere could lead to undesirable telemetry. + + Atmosphere's `erpt` reimplementation allows the system to interact with existing error reports as expected. + + However, all new error reports are instead saved to the sd card (`/atmosphere/erpt_reports`), and are not committed to the system savegame. + + Users curious about what kind of telemetry is being prevented can view the reports as they're generated in there. + + Reports are saved as msgpack (as this is what Nintendo uses). + + Please note, not all telemetry is disabled. Play reports and System reports will continue to function unmodified. + + With atmosphere's `erpt` implementation, homebrew can now use the native error applet to display errors without worrying about generating undesirable telemetry. ++ libstratosphere and libvapours received a number of improvements. + + With thanks to @Adubbz for his work, the NCM namespace now has client code. + + This lays the groundwork for first-class system update/downgrade homebrew support in the near future. + + In particular, code implementing the os namespace is significantly more accurate. + + In addition, Nintendo's allocators were implemented, allowing for identical memory efficiency versus Nintendo's implementations. ++ General system stability improvements to enhance the user's experience. + +## 0.10.5 ++ Changes were made to the way fs.mitm builds images when providing a layeredfs romfs. + + Building romfs metadata previously had a memory cost of about ~4-5x the file table size. + + This caused games that have particularly enormous file metadata tables (> 4 MB) to exhaust fs.mitm's 16 MB memory pool. + + The code that creates romfs images was thus changed to be significantly more memory efficient, again. + + Memory requirements have been lowered from ~4x file table size to ~2x file table size + 0.5 MB. + + There is a slight speed penalty to this, but testing on Football Manager 2020 only took an extra ~1.5 seconds for the game to boot with many modded files. + + This shouldn't be noticeable thanks to the async changes made in 0.10.2. + + If you encounter a game that exhausts ams.mitm's memory (crashing it) when loading layeredfs mods, please contact SciresM. + + Romfs building can be made even more memory efficient, but unless games show up with even more absurdly huge file tables it seems not worth the speed trade-off. ++ A bug was fixed that caused Atmosphere's fatal error context to not dump TLS for certain processes. ++ General system stability improvements to enhance the user's experience. + +## 0.10.4 ++ With major thanks to @Adubbz for his work, the NCM system module has now been re-implemented. + + This was a major stepping stone towards the goal of having implementations everything in the Switch's package1/package2 firmware. + + This also lays the groundwork for libstratosphere providing bindings for changing the installed version of the Switch's OS. + + **Please Note**: The NCM implementation will initially be opt-in. + + The Atmosphere team is confident in our NCM implementation (and we have tested it on every firmware version). + + That said, this is our first system module that manages NAND savegames -- and caution is a habit. + + We do not anticipate any issues that didn't come up in testing, so this is just our being particularly careful. + + Users interested in opting in to using our implementation should set `stratosphere!ncm_enabled = 1` in BCT.ini. + + In the unlikely event that any issues are encountered, please report them to @SciresM. + + The NCM implementation will stop being opt-in in a future update, after thorough testing has been done in practice. ++ A bug was fixed in emummc that caused Nintendo path to be corrupted on 1.0.0. + + This manifested as the emummc folder being created inside the virtual NAND instead of the SD card. + + It's unlikely there are any negative consequences to this in practice. + + If you want to be truly sure, you can re-clone sysmmc before updating a 1.0.0 emummc to latest firmware. ++ Stratosphere system modules now use new Nintendo-style FS bindings instead of stdio. + + This saves a modest amount of memory due to leaner code, and greatly increases the accuracy of several components. + + These bindings will make it easier for other system modules using libstratosphere to interact with the filesystem. + + This also lays the groundwork for changes necessary to support per-emummc Atmosphere folders in a future update. ++ Atmosphere's fatal error context now dumps 0x100 of TLS. + + This will make it much easier to fix bugs when an error report is dumped for whatever caused the crash. ++ General system stability improvements to enhance the user's experience. + +## 0.10.3 ++ Support was added for 9.2.0. ++ Support was added for redirecting manual html content for games. + + This works like normal layeredfs, replacing content placed in `/atmosphere/contents//manual_html/`. + + This allows for game mods/translations to provide custom manual content, if they so choose. ++ A number of improvements were made to Atmosphere's memory usage, including: + + `fatal` now uses STB instead of freetype for rendering. + + This saves around 1 MB of memory, and makes our fatal substantially leaner than Nintendo's. + + `sm` no longer wastes 2 MiB unnecessarily. ++ fusee/sept's sdmmc access now better matches official behavior. + + This improves compatibility with some SD cards. ++ `ro` has been updated to reflect changes made in 9.1.0. ++ The temporary auto-migration added in 0.10.0 has been removed, since the transitionary period is well over. ++ General system stability improvements to enhance the user's experience. + +## 0.10.2 ++ hbl configuration was made more flexible. + + Up to eight specific program ids can now be specified to have their own override keys. + + This allows designating both the album applet and a specific game as hbl by default as desired. + + Configuration targeting a specific program is now mutually exclusive with override-any-app for that program. + + This fixes unintuitive behavior when override key differed for an application specific program. ++ Loader's external content fileystem support was fixed (thanks @misson20000!). ++ KernelLdr was reimplemented. + + This is the first step towards developing mesosphere, Atmosphere's planned reimplementation of the Switch's Kernel. + + The typical user won't notice anything different, as there are no extensions, but a lot of groundwork was laid for future development. ++ Improvements were made to the way Atmosphere's buildsystem detects source code files. + + This significantly reduces compilation time (saving >30 seconds) on the machine that builds official releases. ++ Certain device code was cleaned up and made more correct in fusee/sept/exosphere (thanks @hexkyz!). ++ A number of changes were made to the way fs.mitm builds images when providing a layeredfs romfs. + + Some games (Resident Evil 6, Football Manager 2020 Touch, possibly others) have enormous numbers of files. + + Attempting to create a layeredfs mod for these games actually caused fs.mitm to run out of memory, causing a fatal error. + + The code that creates these images was changed to be significantly more memory efficient. + + However, these changes also cause a significant slowdown in the romfs building code (~2-5x). + + This introduced a noticeable stutter when launching a game, because the UI thread would block on the romfs creation. + + To solve this, fs.mitm now lazily initializes the image in a background thread. + + This fixes stutter issues, however some games may be slightly slower (~1-2s in the worst cases) to transition from the "loading" GIF to gameplay now. + + Please note: the slowdown is not noticeable in the common case where games don't have tons of files (typical is ~0.1-0.2 seconds). + + Once the image has been built, there is no further speed penalty at runtime -- only when the game is launched. ++ A number of other bugs were fixed, including: + + Several minor logic inversions that could have caused fatal errors when modding games. + + Atmosphere's new-ipc code did not handle "automatic" recvlist buffers correctly, so some non-libnx homebrew could crash. + + fs.mitm now correctly mitms sdb, which makes redirection of certain system data archives work again. + + In 0.10.0/0.10.1, changing the system font/language did not work correctly due to this. + + A bug was fixed in process cleanup that caused the system to hang on < 5.0.0. ++ The temporary hid-mitm added in Atmosphere 0.9.0 was disabled by default. + + Please ensure your homebrew is updated. + + For now, users may re-enable this mitm by use of a custom setting (`atmosphere!enable_deprecated_hid_mitm`) to ease the transition process some. + + Please note: support for this setting may be removed to save memory in a future atmosphere release. ++ General system stability improvements to enhance the user's experience. + +## 0.10.1 ++ A bug was fixed that caused memory reallocation to the system pool to work improperly on firmware 5.0.0 and above. + + Atmosphere was always trying to deallocate memory away from the applet pool and towards the system pool. + + The intent of this is to facilitate running more custom sysmodules/atmosphere binaries. + + However, while memory was always successfully taken away from the applet pool, on 5.0.0+ granting it to the system pool did not work for technical reasons. + + If you are interested in the technical details, talk to SciresM. + + This has now been fixed by adding new kernel patches, and memory is correctly granted to the system pool as intended. ++ Atmosphere's library system has been overhauled: + + libstratosphere's repository has been rebranded, more generally, to "Atmosphere-libs". + + In addition to libstratosphere, a new general library for not-stratosphere-specific code has been added. + + This is currently named `libvapours`. + + In the future, kernel functionality will be available as `libmesosphere`. + + The build system for stratosphere system modules has been similarly overhauled. ++ A number of other bugs were fixed, including: + + A bug was fixed that could cause memory corruption when redirecting certain Romfs content. + + A bug was fixed that could cause an infinite loop when redirecting certain Romfs content. + + A bug was fixed that could cause certain NROs to fail to load. + + This caused the latest version of Super Smash Bros to display "An error has occurred" on launch. + + A bug was fixed that caused input/output array sizes for certain circumstances to be calculated incorrectly. + + This caused cheats to fail to function properly. + + C++ exception code is now more thoroughly removed from stratosphere executables. + + This saves a minor amount of memory. + + A number of minor logic inversions were fixed in libstratosphere. + + These did not affect any code currently used by released Atmosphere binaries. ++ *Please note**: Because this update is releasing so soon after 0.10.0, the removal of the temporary hid-mitm has been postponed to 0.10.2. + + Please ensure your homebrew is updated. ++ Random number generation now uses TinyMT instead of XorShift. ++ General system stability improvements to enhance the user's experience. + +## 0.10.0 ++ Support was added for 9.1.0 + + **Please note**: The temporary hid-mitm added in Atmosphere 0.9.0 will be removed in Atmosphere 0.10.1. + + Please ensure your homebrew is updated. ++ The Stratosphere rewrite was completed. + + libstratosphere was rewritten as part of Stratosphere's refactor. + + Code responsible for providing and managing IPC services was greatly improved. + + The new code is significantly more accurate (it is bug-for-bug compatible with Nintendo's code), and significantly faster. + + ams.mitm was rewritten as part of Stratosphere's refactor. + + Saves redirected to the SD card are now separated for sysmmc vs emummc. + + **Please note**: If you find any bugs, please report them so they can be fixed. ++ Thanks to the rewrite, Atmosphere now uses significantly less memory. + + Roughly 10 additional megabytes are now available for custom system modules to use. + + This means you can potentially run more custom system modules simultaneously. + + If system modules are incompatible, please ask their authors to reduce their memory footprints. ++ Atmosphere's configuration layout has had major changes. + + Configuration now lives inside /atmosphere/config/. + + Atmosphere code now knows what default values should be, and includes them in code. + + It is no longer an error if configuration inis are not present. + + Correspondingly, Atmosphere no longer distributes default configuration inis. + + Templates are provided in /atmosphere/config_templates. + + loader.ini was renamed to override_config.ini. + + This fixes the longstanding problem that atmosphere updates overwrote user configuration when extracted. ++ Atmosphere's process override layout was changed. + + Atmosphere now uses the /atmosphere/contents directory, instead of /atmosphere/titles. + + This goes along with a refactoring to remove all reference to "title id" from code, as Nintendo does not use the term. + + To make this transition easier, a temporary functionality has been added that migrates folders to the new directory. + + When booting into 0.10.0, Atmosphere will rename /atmosphere/titles/`` to /atmosphere/contents/``. + + This functionality may or may not be removed in some future update. + + This should solve any transition difficulties for the typical user. + + Please make sure that any future mods you install extract to the correct directory. ++ Support for configuring override keys for hbl was improved. + + The key used to override applications versus a specific program can now be different. + + The key to override a specific program can be managed via override_key. + + The key to override any app can be managed via override_any_app_key. + + Default override behavior was changed. + + By default, atmosphere will now override the album applet with hbl unless R is held. + + By default, atmosphere will now override any application with hbl only if R is held. ++ The default amount of applet memory reserved has been slightly increased. + + This allows the profile selector applet to work by default in applet mode. ++ The way process override status is captured was changed. + + Process override keys are now captured exactly once, when the process is created. + + This fixes the longstanding issue where letting go of the override button partway into the process launch could cause problems. + + The Mitm API was changed to pass around override status. + + Mitm services now know what keys were held when the client was created, as well as whether the client is HBL/should override contents. + + An extension was added to pm:info to allow querying a process's override status. ++ Thanks to process override capture improvements, hbl html behavior has been greatly improved. + + Web applets launched by hbl will now always see the /atmosphere/hbl_html filesystem ++ Support was added to exosphere for enabling usermode access to the PMU registers. + + This can be controlled via exosphere!enable_user_pmu_access in BCT.ini. ++ An enormous number of minor bugs were fixed. + + dmnt's cheat VM had a fix for an inversion in opcode behavior. + + An issue was fixed in fs.mitm's management of domain object IDs that could lead to system corruption in rare cases. + + The Mitm API no longer silently fails when attempting to handle commands passing C descriptors. + + On previous atmosphere versions, certain commands to FS would silently fail due to this... + + No users reported any visible errors, but it was definitely a problem behind the scenes. + + These commands are now handled correctly. + + Atmosphere can now display a fatal error screen significantly earlier in the boot process, if things go wrong early on. + + The temporary hid mitm will no longer sometimes cause games to fail to detect input. + + Mitm Domain object ID management no longer desynchronizes from the host process. + + An issue was fixed that could cause service acquisition to hang forever if certain sm commands were called in a precise order. + + An off-by-one was fixed that could cause memory corruption in server memory management. + + ... and too many more bugs fixed to reasonably list them all :) ++ General system stability improvements to enhance the user's experience. + +## 0.9.4 ++ Support was added for 9.0.0. + + **Please note**: 9.0.0 made a number of changes that may cause some issues with homebrew. Details: + + 9.0.0 changed HID in a way that causes libnx to be unable to detect button input. + + Homebrew should be recompiled with newest libnx to fix this. + + Atmosphere now provides a temporary hid-mitm that will cause homebrew to continue to work as expected. + + This mitm will be removed in a future Atmosphere revision once homebrew has been updated, to allow users to use a custom hid mitm again if they desire. + + 9.0.0 introduced an dependency in FS on the USB system module in order to launch the SD card. + + This means the USB system module must now be launched before the SD card is initialized. + + Correspondingly, the USB system module can no longer be IPS patched, and its settings cannot be reliably mitm'd. + + We know this is frustrating, so we'll be looking into whether there is some way of addressing this in the future. ++ An off-by-one error was fixed in `boot` system module's pinmux initialization. + + This could theoretically have caused issues with HdmiCec communication. + + No users reported issues, so it's unclear if this was a problem in practice. ++ A bug was fixed that could cause webapplet launching homebrew to improperly set the accessible url whitelist. ++ BIS key generation has been fixed for newer hardware. + + Newer hardware uses new, per-firmware device key to generate BIS keys instead of the first device key, so previously the wrong keys were generated as backup. + + This only affects units manufactured after ~5.0.0. ++ General system stability improvements to enhance the user's experience. + +## 0.9.3 ++ Thanks to hexkyz, fusee's boot sequence has been greatly optimized. + + Memory training is now managed by a separate binary (`fusee-mtc`, loaded by fusee-primary before fusee-secondary). + + Unnecessarily long splash screen display times were reduced. + + The end result is that Atmosphere now boots *significantly* faster. :) + + **Note:** This means fusee-primary must be updated for Atmosphere to boot successfully. ++ The version string was adjusted, and now informs users whether or not they are using emummc. ++ Atmosphere now automatically backs up the user's BIS keys on boot. + + This should prevent a user from corrupting nand without access to a copy of the keys needed to fix it. + + This is especially relevant on ipatched units, where the RCM vulnerability is not an option for addressing bricks. ++ The `pm` system module was rewritten as part of Stratosphere's ongoing refactor. + + Support was added for forward-declaring a mitm'd service before a custom user sysmodule is launched. + + This should help resolve dependency issues with service registration times. + + SM is now informed of every process's title id, including built-in system modules. ++ The `creport` system module was rewritten as part of Stratosphere's ongoing refactor. + + creport now dumps up to 0x100 of stack from each thread in the target process. + + A few bugs were fixed, including one that caused creport to incorrectly dump process dying messages. ++ Defaults were added to `system_settings.ini` for controlling hbloader's memory usage in applet mode. + + These defaults reserve enough memory so that homebrew can launch swkbd while in applet mode. ++ The `fatal` system module was rewritten as part of Stratosphere's ongoing refactor. + + Incorrect display output ("2000-0000") has been fixed. Fatal will now correctly show 2162-0002 when this occurs. + + A longstanding bug in how fatal manages the displays has been fixed, and official display init behavior is now matched precisely. ++ General system stability improvements to enhance the user's experience. + +## 0.9.2 ++ A number of emummc bugfixes were added (all thanks to @m4xw's hard work). The following is a summary of emummc changes: + + Support for file-based emummc instances was fixed. + + Please note: file-based emummc is still unoptimized, and so may be much slower than partition-based. + + This speed differential should hopefully be made better in a future emummc update. + + The way emummc handles power management was completely overhauled. + + Emummc now properly handles init/de-init, and now supports low voltage mode. + + Much better support for shutdown was added, which should assuage corruption/synchronization problems. + + This should also improve support for more types of SD cards. + + A bug was fixed that caused emummc to not work on lower system versions due to missing SVC access. + + **Please note**: The configuration entries used for emummc have been changed. + + `emummc_` prefixes have been removed, since they are superfluous given the `emummc` category they are under. + + As an example, `emummc!emummc_enabled` is now `emummc!enabled`. + + INI configurations made by @CTCaer's [tool](https://github.com/ctcaer/hekate/releases/latest) (which is the recommended way to manage emummc) should automatically work as expected/be corrected. + + **If you do not wish to use the above, you will need to manually correct your configuration file**. + + General system stability improvements to enhance the user's experience. ++ Stratosphere is currently in the process of being re-written/refactored. + + Stratosphere was my (SciresM's) first C++ project, ever -- the code written for it a year ago when I was learning C++ is/was of much lower quality than code written more recently. + + Code is thus being re-rwitten for clarity/stlye/to de-duplicate functionality, with much being moved into libstratosphere. + + Stratosphere will, after the rewrite, globally use the `sts::` namespace -- this should greatly enhancing libstratosphere's ability to provide functionality for system modules. + + The rewritten modules consistently have lower memory footprints, and should be easier to maintain going forwards. + + The `sm`, `boot`, `spl`, `ro`, and `loader` modules have been tackled so far. ++ General system stability improvements to enhance the user's experience. + +## 0.9.1 ++ Support was added for 8.1.0. ++ Please note, emummc is still considered **beta/experimental** -- this is not the inevitable bugfix update for it, although some number of bugs have been fixed. :) ++ General system stability improvements to enhance the user's experience. + +## 0.9.0 ++ Creport output was improved significantly. + + Thread names are now dumped on crash in addition to 0x100 of TLS from each thread. + + This significantly aids debugging efforts for crashes. + + Support was added for 32-bit stackframes, so reports can now be generated for 32-bit games. ++ `dmnt`'s Cheat VM was extended to add a new debug opcode. ++ With thanks to/collaboration with @m4xw and @CTCaer, support was added for redirecting NAND to the SD card (emummc). + + Please note, this support is very much **beta/experimental**. + + It is quite likely we have not identified all bugs -- those will be fixed as they are reported over the next few days/weeks. + + In addition, some niceties (e.g. having a separate Atmosphere folder per emummc instance) still need some thought put in before they can be implemented in a way that makes everyone happy. + + If you are not an advanced user, you may wish to think about waiting for the inevitable 0.9.1 bugfix update before using emummc as your default boot option. + + You may especially wish to consider waiting if you are using Atmosphere on a unit with the RCM bug patched. + + Emummc is managed by editing the emummc section of "emummc/emummc.ini". + + To enable emummc, set `emummc!emummc_enabled` = 1. + + Support is included for redirecting NAND to a partition on the SD card. + + This can be done by setting `emummc!emummc_sector` to the start sector of your partition (e.g., `emummc_sector = 0x1A010000`). + + Support is also included for redirecting NAND to a collection of loose files on the SD card. + + This can be done by setting `emummc!emummc_path` to the folder (with archive bit set) containing the NAND boot partitions' files "boot0" and "boot1", and the raw NAND image files "00", "01", "02", etc. (single "00" file with the whole NAND image requires exFAT mode while multipart NAND can be used in both exFAT and FAT32 modes). + + The `Nintendo` contents directory can be redirected arbitrarily. + + By default, it will be redirected to `emummc/Nintendo_XXXX`, where `XXXX` is the hexadecimal representation of the emummc's ID. + + The current emummc ID may be selected by changing `emummc!emummc_id` in emummc.ini. + + This can be set to any arbitrary directory by setting `emummc!emummc_nintendo_path`. + + To create a backup usable for emummc, users may use tools provided by the [hekate](https://github.com/CTCaer/hekate) project. + + If, when using emummc, you encounter a bug, *please be sure to report it* -- that's the only way we can fix it. :) + +## 0.8.10 ++ A bug was fixed that could cause incorrect system memory allocation on 5.0.0. + + 5.0.0 should now correctly have an additional 12 MiB allocated for sysmodules. ++ Atmosphère features which check button presses now consider all controllers, isntead of just P1. ++ Support was added for configuring language/region on a per-game basis. + + This is managed by editing `atmosphere/titles//config.ini` for the game. + + To edit title language, edit `override_config!override_language`. + + The languages supported are `ja`, `en-US`, `fr`, `de`, `it`, `es`, `zh-CN`, `ko`, `nl`, `pt`, `ru`, `zh-TW`, `en-GB`, `fr-CA`, `es-419`, `zh-Hans`, `zh-Hant`. + + To edit title region, edit `override_config!override_region`. + + The regions supported are `jpn`, `usa`, `eur`, `aus`, `chn`, `kor`, `twn`. ++ Atmosphère now provides a reimplementation of the `boot` system module. + + `boot` is responsible for performing hardware initialization, showing the Nintendo logo, and repairing NAND on system update failure. + + Atmosphère's `boot` implementation preserves AutoRCM during NAND repair. + + NAND repair occurs when an unexpected shutdown or error happens during a system update. + + This fixes a final edge case where AutoRCM might be removed by HOS, which could cause a user to burn fuses. ++ General system stability improvements to enhance the user's experience. + +## 0.8.9 ++ A number of bugs were fixed, including: + + A data abort was fixed when mounting certain partitions on NAND. + + All Stratosphère system modules now only maintain a connection to `sm` when actively using it. + + This helps mitigate the scenario where sm hits the limit of 64 active connections and crashes. + + This sometimes caused crashes when custom non-Atmosphère sysmodules were active and the user played certain games (ex: Smash's Stage Builder). + + fatal now uses the 8.0.0 clkrst API, instead of silently failing to adjust clock rates on that firmware version. + + A wait loop is now performed when trying to get a session to `sm`, in the case where `sm:` is not yet registered. + + This fixes a race condition that could cause a failure to boot under certain circumstances. + + libstratosphere's handling of domain object closing has been improved. + + Previously, this code could cause crashes/extremely odd behavior (misinterpreting what object a service is) under certain circumstances. ++ An optional automatic reboot timer was added to fatal. + + By setting the system setting `atmosphere!fatal_auto_reboot_interval` to a non-zero u64 value, fatal can be made to automatically reboot after a certain number of milliseconds. + + If the setting is zero or not present, fatal will wait for user input as usual. ++ Atmosphère now provides a reimplementation of the `ro` system module. + + `ro` is responsible for loading dynamic libraries (NROs) on 3.0.0+. + + On 1.0.0-2.3.0, this is handled by `loader`. + + Atmosphere's `ro` provides this functionality (`ldr:ro`, `ro:dmnt`) on all firmware versions. + + An extension was implemented to provide support for applying IPS patches to NROs. + + All patches at paths like /atmosphere/nro_patches/<user-defined patch name>/<Hex Build-ID for NRO to patch>.ips will be applied, allowing for easy distribution of patches. + + Both the IPS and IPS32 formats are supported. ++ Atmosphère now provides a reimplementation of the `spl` system module. + + `spl` (Secure Platform Services) is responsible for cryptographic operations, including all communications with the secure monitor (exosphère). + + In the future, this may be used to provide extensions to the API for interacting with exosphère from userland. ++ General system stability improvements to enhance the user's experience. + +## 0.8.8 ++ Support was added for firmware version 8.0.0. ++ Custom exception handlers were added to stratosphere modules. + + If a crash happens in a core atmosphere module now, instead of silently failing a reboot will occur to log the information to the SD card. ++ A bug was fixed in creport that caused games to hang when crashing under certain circumstances. ++ A bug was fixed that prevented maintenance mode from booting on 7.0.0+. ++ General system stability improvements to enhance the user's experience. + +## 0.8.7 ++ A few bugs were fixed that could cause fatal to fail to show an error under certain circumstances. ++ A bug was fixed that caused an error when launching certain games (e.g. Hellblade: Senua's Sacrifice). + + Loader had support added in ams-0.8.4 for a new (7.0.0+) flag bit in NPDMs during process creation, but forgot to allow this bit to be set when validating the NPDM. ++ dmnt's cheat virtual machine received new instructions. + + These allow for saving, restoring, or clearing registers to a secondary bank, effectively doubling the number of values that can be stored. ++ SHA256 code has been swapped from linux code to libnx's new hw-accelerated cryptography API. ++ Extensions were added to smcGetInfo: + + A ConfigItem was added to detect whether the current unit has the RCM bug patched. + + A ConfigItem was added to retrieve the current Atmosphère build hash. ++ Exosphère now tells the kernel to enable user-mode exception handlers, which should allow for better crash reporting/detection from Atmosphère's modules in the future.. ++ Opt-in support was added for redirecting game save files to directories on the SD card. + + Please note, this feature is **experimental**, and may cause problems. Please use at your own risk (and back up your saves before enabling it), as it still needs testing. + + This can be enabled by setting `atmosphere!fsmitm_redirect_saves_to_sd` to 1 in `system_settings.ini`. ++ General system stability improvements to enhance the user's experience. + +## 0.8.6 ++ A number of bugs were fixed, including: + + A case of inverted logic was fixed in fs.mitm which prevented the flags system from working correctly. + + Time service access was corrected in both creport/fatal. + + This fixes the timestamps used in fatal/crash report filenames. + + A coherency issue was fixed in exosphère's Security Engine driver. + + This fixes some instability issues encountered when overclocking the CPU. + + Loader now unmaps NROs correctly, when ldr:ro is used. + + This fixes a crash when repeatedly launching the web applet on < 3.0.0. + + Usage of hidKeysDown was corrected to hidKeysHeld in several modules. + + This fixes a rare issue where keypresses may have been incorrectly detected. + + An issue with code filesystem unmounting was fixed in loader. + + This issue could occasionally cause a fatal error 0x1015 to be thrown on boot. + + Two bugs were fixed in the implementations of dmnt's cheat virtual machine. + + These could cause cheats to work incorrectly under certain circumstances. + + PM now uses a static buffer instead of a dynamically allocated one during process launch. + + This fixes a memory exhaustion problem when building with gcc 8.3.0. + + A workaround for a deadlock bug in Horizon's kernel on >= 6.0.0 was added in dmnt. + + This prevents a system hang when booting certain titles with cheats enabled (ex: Mario Kart 8 Deluxe). + + set.mitm now reads the system firmware version directly from the system version archive, instead of calling into set:sys. + + This fixes compatibility with 1.0.0, which now successfully boots again. ++ dmnt's cheat virtual machine had some instruction set changes. + + A new opcode was added for beginning conditional blocks based on register contents. + + More addressing modes were added to the StoreRegisterToAddress opcode. + + These should allow for more complex cheats to be implemented. ++ A new system for saving the state of cheat toggles between game boots was added. + + Toggles are now saved to `atmosphere/titles/<title id>/cheats/toggles.txt` when either toggles were successfully loaded from that file or the system setting `atmosphere!dmnt_always_save_cheat_toggles` is non-zero. + + This removes the need for manually setting cheats from all-on or all-off to the desired state on each game boot. ++ The default behavior for loader's HBL support was changed. + + Instead of launching HBL when album is launched without R held, loader now launches HBL when album or any game is launched with R held. + + Loader will now override any app in addition to a specific title id when `hbl_config!override_any_app` is true in `loader.ini`. + + Accordingly, the `hbl_config!title_id=app` setting was deprecated. Support will be removed in Atmosphère 0.9.0. ++ First-class support was added to loader and fs.mitm for enabling homebrew to launch web applets. + + Loader will now cause the "HtmlDocument" NCA path to resolve for whatever title HBL is taking over, even if it would not normally do so. + + fs.mitm will also now cause requests to mount the HtmlDocument content for HBL's title to open the `sdmc:/atmosphere/hbl_html` folder. + + By default, this just contains a URL whitelist. ++ General system stability improvements to enhance the user's experience. + +## 0.8.5 ++ Support was added for overriding content on a per-title basis, separate from HBL override. + + This allows for using mods on the same title that one uses to launch HBL. + + By default, `!L` is used for title content override (this is configurable by editing `default_config!override_key` in `loader.ini`) + + This key combination can be set on a per-title basis by creating a `atmosphere/titles/<title id>/config.ini`, and editing `override_config!override_key`. ++ Content headers were added for the embedded files inside of fusee-secondary. + + This will allow non-fusee bootloaders (like `hekate`) to extract the components bundled inside release binaries. + + This should greatly simplify the update process in the future, for users who do not launch Atmosphère using fusee. ++ Support for cheat codes was added. + + These are handled by a new `dmnt` sysmodule, which will also reimplement Nintendo's Debug Monitor in the future. + + Cheat codes can be enabled/disabled at application launch via a per-title key combination. + + For details, please see the [cheat loading documentation](https://github.com/Atmosphere-NX/Atmosphere/blob/master/docs/cheats.md#cheat-loating-process). + + Cheat codes are fully backwards compatible with the pre-existing format, although a number of bugs have been fixed and some new features have been added. + + For details, please see [the compatibility documentation](https://github.com/Atmosphere-NX/Atmosphere/blob/master/docs/cheats.md#cheat-code-compatibility). + + An HIPC service API was added (`dmnt:cht`), that will allow user homebrew to interface with and control Atmosphère's cheat manager. + + Please see [the relevant documentation](https://github.com/Atmosphere-NX/Atmosphere/blob/master/docs/modules/dmnt.md). + + Full client code can be found in [libstratosphere](https://github.com/Atmosphere-NX/libstratosphere/blob/master/include/stratosphere/services/dmntcht.h). + + Users interested in interfacing should see [EdiZon](https://github.com/WerWolv/EdiZon), which should have support for interfacing with Atmosphère's API shortly after 0.8.5 releases. ++ A bug was fixed that would cause Atmosphère's fatal screen to not show on 1.0.0-2.3.0. ++ A bug was fixed that caused Atmosphère's automatic ProdInfo backups to be corrupt. ++ General system stability improvements to enhance the user's experience. + +## 0.8.4 ++ Support for 7.0.0/7.0.1 was added. + + This is facilitated through a new payload, `sept`, which can be signed, encrypted, and then loaded by Nintendo's TSEC firmware. + + `sept` will derive the keys needed to boot new firmware, and then load `sept/payload.bin` off the SD card and jump to it. ++ Recognition of applications for override/mitm has been improved. + + Nintendo's official Title ID range (`0x0100000000000000`-`0x01FFFFFFFFFFFFFF`) is now enforced. ++ A deadlock condition was fixed involving libstratosphere mitm sysmodules. ++ Kernel patches for JIT support were added (Thanks, @m4xw!). + + These loosen restrictions on caller process in svcControlCodeMemory. ++ `set.mitm` and `fs.mitm` were merged into a single `ams_mitm` sysmodule. + + This saves a process ID, allowing users to run one additional process up to the 0x40 process limit. ++ A `bpc.mitm` component was added, performing custom behavior on shutdown/reboot requests from `am` or applications. + + Performing a reboot from the reboot menu now reboots to atmosphere. This can be configured via `system_settings.ini`. + + Performing a shutdown from the reboot menu now works properly with AutoRCM, and does a real shutdown. ++ General system stability improvements to enhance the user's experience. + +## 0.8.3 ++ A custom warmboot firmware was implemented, which does not perform anti-downgrade fuse checks. + + This fixes sleep mode when using a downgraded NAND. + + This also removes Atmosphère's final dependency on Nintendo's encrypted PK11 binary; all components are now re-implemented. ++ The ExternalContentSource API was changed to not clear on failure. ++ Content override now supports an "app" setting, that causes all applications to be overridden with HBL instead of a specific title. + + Note: because override keys are system-wide, using this setting will prevent using mods in games (as every game will be HBL). ++ A bug was fixed causing incorrect fatal-error output when svcBreak was called on 5.0.0+. ++ An extension was added to set.mitm to support customization of system settings. + + These are controlled by `atmosphere/system_settings.ini`, see [here](https://github.com/Atmosphere-NX/Atmosphere/blob/master/docs/modules/set_mitm.md) for documentation. ++ An extension was added to sm, adding a new `sm:dmnt` service. + + This can be used by a debug monitor in order to debug the registration state of various other services. ++ A bug was fixed in the MitM API that could sometimes cause a system hang during boot. ++ A change was made to the MitM API: in cases where sm would have returned 0xE15 when installing a mitm service, it now defers the result (following GetService semantics). ++ Support for booting into maintenance mode by holding +/- was added to PM. ++ An extension was added to exosphere, adding a custom SMC that allows for DMA to IRAM. ++ In addition, smcGetConfig was extended to reboot to a payload in IRAM at 0x40010000 when ConfigItem 65001 is set to 2. + + Fatal will now use this to reboot to sdmc:/atmosphere/reboot_payload.bin if present, when a vol button is pressed. + + An example homebrew ("reboot_to_payload") was also written and is now included with Atmosphère. ++ General system stability improvements to enhance the user's experience. + +## 0.8.2 ++ A number of bugs were fixed causing users to sometimes see `Key Derivation Failed!`. + + KFUSE clock enable timings have been adjusted to allow time to stabilize before TSEC is granted access. + + A race condition was fixed that could cause wrong key data to be used on 6.2.0 + + The TSEC firmware is now retried on failure, fixing a failure affecting ~1/50 boots on 6.2.0. ++ A bug was fixed causing some modules to not work on firmware 1.0.0. ++ A bug was fixed causing sleep mode to not work with debugmode enabled. + + As a result, debugmode is now enabled in the default BCT.ini. ++ General system stability improvements to enhance the user's experience. + +## 0.8.1 ++ A bug was fixed causing users to see `Failed to enable SMMU!` if fusee had previously rebooted. + + This message will still occur sporadically if fusee is not launched from coldboot, but it can never happen twice in a row. ++ A race condition was fixed in Atmosphere `bis_protect` functionality that could cause NS to be able to overwrite BCT public keys. + + This sometimes broke AutoRCM protection, the current fix has been tested on hardware and verified to work. ++ Support was added for enabling `debugmode` based on the `exosphere` section of `BCT.ini`: + + Setting `debugmode = 1` will cause exosphere to tell the kernel that debugmode is active. + + Setting `debugmode_user = 1` will cause exosphere to tell userland that debugmode is active. + + These are completely independent of one another, allowing fine control of system behavior. ++ Support was added for `nogc` functionality; thanks to @rajkosto for the patches. + + By default, `nogc` patches will automatically apply if the user is booting into 4.0.0+ with fuses from <= 3.0.2. + + Users can override this functionality via the `nogc` entry in the `stratosphere` section of `BCT.ini`: + + Setting `nogc = 1` will force enable `nogc` patches. + + Setting `nogc = 0` will force disable `nogc` patches. + + If patches are enabled but not found for the booting system, a fatal error will be thrown. + + This should prevent running FS without `nogc` patches after updating to an unsupported system version. ++ An extension was added to `exosphere` allowing userland applications to cause the system to reboot into RCM: + + This is done by calling smcSetConfig(id=65001, value=<nonzero>); user homebrew can use splSetConfig for this. ++ On fatal error, the user can now choose to perform a standard reboot via the power button, or a reboot into RCM via either volume button. ++ A custom message was added to `fatal` for when an Atmosphère API version mismatch is detected (2495-1623). ++ General system stability improvements to enhance the user's experience. + +## 0.8.0 ++ A custom `fatal` system module was added. + + This re-implements and extends Nintendo's fatal module, with the following features: + + Atmosphère's `fatal` does not create error reports. + + Atmosphère's `fatal` draws a custom error screen, showing registers and a backtrace. + + Atmosphère's `fatal` attempts to gather debugging info for all crashes, and not just ones that include info. + + Atmosphère's `fatal` will attempt saving reports to the SD, if a crash report was not generated by `creport`. ++ Title flag handling was changed to prevent folder clutter. + + Instead of living in `atmosphere/titles/<tid>/%s.flag`, flags are now located in `atmosphere/titles/<tid>/flags/%s.flag` + + The old format will continue to be supported for some time, but is deprecated. + + Flags can now be applied to HBL by placing them at `atmosphere/flags/hbl_%s.flag`. ++ Changes were made to the mitm API, greatly improving caller semantics. + + `sm` now informs mitm services of a new session's process id, enabling custom handling based on title id/process id. ++ smhax is no longer enabled, because it is no longer needed and breaks significant functionality. + + Users with updated HBL/homebrew should see no observable differences due to this change. ++ Functionality was added implementing basic protections for NAND from userland homebrew: + + BOOT0 now has write protection for the BCT public key and keyblob regions. + + The `ns` sysmodule is no longer allowed to write the BCT public keys; all other processes can. + + This should prevent system updates from removing AutoRCM. + + No processes should be allowed to write to the keyblob region. + + By default, BIS partitions other than BOOT0 are now read-only, and CAL0 is neither readable nor writable. + + Adding a `bis_write` flag for a title will allow it to write to BIS. + + Adding a `cal_read` flag for a title will allow it to read CAL0. + + An automatic backup is now made of CAL0 on boot. + + `fs.mitm` maintains a file handle to this backup, so userland software cannot read it. + + To facilitate this, `fs.mitm` now mitms all sessions for non-system modules; content overriding has been made separate from service interception. + + Please note: these protections are basic, and sufficiently malicious homebrew ++can defeat them++. + + Please be careful to only run homebrew software from sources that you trust. ++ A bug involving HDCP titles crashing on newer firmwares was fixed. ++ Support was added for system version 6.2.0; our thanks to @motezazer for his invaluable help. + + By default, new keys will automatically be derived without user input. + + Support is also present for loading new keys from `atmosphere/prod.keys` or `atmosphere/dev.keys` ++ General system stability improvements to enhance the user's experience. + +## 0.7.5 ++ DRAM training was added to fusee-secondary, courtesy @hexkyz. + + This greatly improves the speed of memory accesses during boot, resulting in a boot time that is ~200-400% faster. ++ creport has had its code region detection improved. + + Instead of only checking one of the crashing thread's PC/LR for code region presence, creport now checks both + every address in the stacktrace. This is also now done for every thread. + + This matches the improvement Nintendo added to official creport in 6.1.0. + + The code region detection heuristic was further improved by checking whether an address points to .rodata or .rwdata, instead of just .text. + + This means that a crash appears in a loaded NRO (or otherwise discontiguous) code region, creport will be able to detect all active code regions, and not just that one. + +## 0.7.4 ++ [libstratosphere](https://github.com/Atmosphere-NX/libstratosphere) has been completely refactored/rewritten, and split into its own, separate submodule. + + While this is mostly "under the hood" for end-users, the refactor is faster (improving both boot-time and runtime performance), more accurate (many of the internal IPC structures are now bug-for-bug compatible with Nintendo's implementations), and significantly more stable (it fixes a large number of bugs present in the old library). + + The refactored API is significantly cleaner and easier to write system module code for, which should improve/speed up development of stratosphere. + + Developers looking to write their own custom system modules for the Switch can now easily include libstratosphere as a submodule in their projects. ++ Loader was extended to add a new generic way to redirect content (ExternalContentSources), courtesy @misson20000: + + A new command was added to ldr:shel, taking in a tid to redirect and returning a session handle. + + When the requested TID is loading, Loader will query the handle as though it were an IFileSystem. + + This allows clients to generically define their own filesystems, and override content with them in loader. ++ fs.mitm has gotten several optimizations that should improve its performance and stability: + + RomFS redirection now only occurs when there is content to redirect, even if the title is being mitm'd elsewhere. + + A cache is now maintained of the active data storage, if any, for all opened title IDs. This means if two processes both try to open the same archive, fs.mitm won't duplicate any of its work. + + RomFS metadata is now cached to the SD card on build instead of being persisted in memory -- this greatly reduces memory footprint and allows fs.mitm to redirect more titles simultaneously than before. ++ A number of bugs were fixed, including: + + A resource leak was fixed in process creation. This fixes crashes that occur when a large number (>32) games have been launched since the last reboot. + + fs.mitm no longer errors when receiving a zero-sized buffer. This fixes crashes in some games, including The Messenger. + + Multi-threaded server semantics should no longer cause deadlocks in certain circumstances. This fixes crashes in some games, including NES Classics. + + PM now only gives full FS permissions to the active KIPs. This fixes a potential crash where new processes might be unable to be registered with FS. ++ The `make dist` target now includes the branch in the generated zip name. ++ General system stability improvements to enhance the user's experience. + +## 0.7.3 ++ Loader and fs.mitm now try to reload loader.ini before reading it. This allows for changing the override button combination/HBL title id at runtime. ++ Added a MitM between set:sys and qlaunch, used to override the system version string displayed in system settings. + + The displayed system version will now display `<Actual version> (AMS <x>.<y>.<z>)`. ++ General system stability improvements to enhance the user's experience. + +## 0.7.2 ++ Fixed a bug in fs.mitm's LayeredFS read implementation that caused some games to crash when trying to read files. ++ Fixed a bug affecting 1.0.0 that caused games to crash with fatal error 2001-0106 on boot. ++ Improved filenames output by the make dist target. ++ General system stability improvements to enhance the user's experience. + +## 0.7.1 ++ Fixed a bug preventing consoles on 4.0.0-4.1.0 from going to sleep and waking back up. ++ Fixed a bug preventing consoles on < 4.0.0 from booting without specific KIPs on the SD card. ++ An API was added to Atmosphère's Service Manager for deferring acquisition of all handles for specific services until after early initialization is completed. ++ General system stability improvements to enhance the user's experience. + +## 0.7.0 ++ First official release of Atmosphère. ++ Supports the following featureset: + + Fusée, a custom bootloader. + + Supports loading/customizing of arbitrary KIPs from the SD card. + + Supports loading a custom kernel from the SD card ("/atmosphere/kernel.bin"). + + Supports compile-time defined kernel patches on a per-firmware basis. + + All patches at paths like /atmosphere/kip_patches/<user-defined patch name>/<SHA256 of KIP>.ips will be applied to the relevant KIPs, allowing for easy distribution of patches supporting multiple versions. + + Both the IPS and IPS32 formats are supported. + + All patches at paths like /atmosphere/kernel_patches/<user-defined patch name>/<SHA256 of Kernel>.ips will be applied to the kernel, allowing for easy distribution of patches supporting multiple versions. + + Both the IPS and IPS32 formats are supported. + + Configurable by editing BCT.ini on the SD card. + + Atmosphère should also be launchable by the alternative hekate bootloader, for those who prefer it. + + Exosphère, a fully-featured custom secure monitor. + + Exosphere is a re-implementation of Nintendo's TrustZone firmware, fully replicating all of its features. + + In addition, it has been extended to provide information on current Atmosphere API version, for homebrew wishing to make use of it. + + Stratosphère, a set of custom system modules. This includes: + + A loader system module. + + Reimplementation of Nintendo's loader, fully replicating all original functionality. + + Configurable by editing /atmosphere/loader.ini + + First class support for the Homebrew Loader. + + An exefs NSP (default "/atmosphere/hbl.nsp") will be used in place of the victim title's exefs. + + By default, HBL will replace the album applet, but any application should also be supported. + + Extended to support arbitrary redirection of executable content to the SD card. + + Files will be preferentially loaded from /atmosphere/titles/<titleid>/exefs/, if present. + + Files present in the original exefs a user wants to mark as not present may be "stubbed" by creating a .stub file on the SD. + + If present, a PFS0 at /atmosphere/titles/<titleid>/exefs.nsp will fully replace the original exefs. + + Redirection is optionally toggleable by holding down certain buttons (by default, holding R disables redirection). + + Full support for patching NSO content is implemented. + + All patches at paths like /atmosphere/exefs_patches/<user-defined patch name>/<Hex Build-ID for NSO to patch>.ips will be applied, allowing for easy distribution of patches supporting multiple firmware versions and/or titles. + + Both the IPS and IPS32 formats are supported. + + Extended to support launching content from loose executable files on the SD card, without requiring any official installation. + + This is done by specifying FsStorageId_None on launch. + + A service manager system module. + + Reimplementation of Nintendo's service manager, fully replicating all original functionality. + + Compile-time support for reintroduction of "smhax", allowing clients to optionally skip service access verification by skipping initialization. + + Extended to allow homebrew to acquire more handles to privileged services than Nintendo natively allows. + + Extended to add a new API for installing Man-In-The-Middle listeners for arbitrary services. + + API can additionally be used to safely detect whether a service has been registered in a non-blocking way with no side-effects. + + Full API documentation to come. + + A process manager system module. + + Reimplementation of Nintendo's process manager, fully replicating all original functionality. + + Extended to allow homebrew to acquire handles to arbitrary processes, and thus read/modify system memory without blocking execution. + + Extended to allow homebrew to retrieve information about system resource limits. + + Extended by embedding a full, extended implementation of Nintendo's boot2 system module. + + Title launch order has been optimized in order to grant access to the SD card faster. + + The error-collection system module is intentionally not launched, preventing many system telemetry error reports from being generated at all. + + Users may place their own custom sysmodules on the SD card and flag them for automatic boot2 launch by creating a /atmosphere/titles/<title ID>/boot2.flag file on their SD card. + + A custom fs.mitm system module. + + Uses Atmosphère's MitM API in order to provide an easy means for users to modify game content. + + Intercepts all FS commands sent by games, with special handling for commands used to mount RomFS/DLC content to enable easy creation and distribution of game/DLC mods. + + fs.mitm will parse the base RomFS image for a game, a RomFS image located at /atmosphere/titles/<title ID>/romfs.bin, and all loose files in /atmosphere/titles/<title ID>/romfs/, and merge them together into a single RomFS image. + + When merging, loose files are preferred to content in the SD card romfs.bin image, and files from the SD card image are preferred to those in the base image. + + Can additionally be used to intercept commands sent by arbitrary system titles (excepting those launched before SD card is active), by creating a /atmosphere/titles/<title ID>/fsmitm.flag file on the SD card. + + Can be forcibly disabled for any title, by creating a /atmosphere/titles/<title ID>/fsmitm_disable.flag file on the SD card. + + Redirection is optionally toggleable by holding down certain buttons (by default, holding R disables redirection). + + A custom crash report system module. + + Serves as a drop-in replacement for Nintendo's own creport system module. + + Generates detailed, human-readable reports on system crashes, saving to /atmosphere/crash_reports/<timestamp>_<title ID>.log. + + Because reports are not sent to the erpt sysmodule, this disables all crash report related telemetry. + + General system stability improvements to enhance the user's experience. diff --git a/components/emummc.md b/components/emummc.md new file mode 100644 index 0000000..6ae69b9 --- /dev/null +++ b/components/emummc.md @@ -0,0 +1,4 @@ +# emummc +emummc is a collaborative project that provides eMMC storage emulation. + +Please refer to the project's repository [here](https://github.com/m4xw/emuMMC) for detailed instructions and documentation. diff --git a/components/exosphere.md b/components/exosphere.md new file mode 100644 index 0000000..1b7f963 --- /dev/null +++ b/components/exosphere.md @@ -0,0 +1,76 @@ +# exosphère +exosphère is a customized reimplementation of the Horizon OS's Secure Monitor. +The Secure Monitor follows the same design principle as Arm's TrustZone and both terms can be used interchangeably in this context. It runs at the highest privilege mode (EL3) available to the main processor and is responsible for all the sensitive cryptographic operations needed by the system as well as power management for each CPU. + +## Extensions +exosphère expands the original Secure Monitor design by providing custom SMCs (Secure Monitor Calls) necessary to the homebrew ecosystem. Currently, these are: +``` +uint32_t smc_ams_iram_copy(smc_args_t *args); +uint32_t smc_ams_write_address(smc_args_t *args); +uint32_t smc_ams_get_emummc_config(smc_args_t *args); +``` + +Additionally, exosphère expands the functionality of two SMCs provided by the Horizon OS for getting/setting configuration items. The following custom configuration items are provided by exosphère: +``` +CONFIGITEM_EXOSPHERE_VERSION = 65000, +CONFIGITEM_NEEDS_REBOOT = 65001, +CONFIGITEM_NEEDS_SHUTDOWN = 65002, +CONFIGITEM_EXOSPHERE_VERHASH = 65003, +CONFIGITEM_HAS_RCM_BUG_PATCH = 65004, +CONFIGITEM_SHOULD_BLANK_PRODINFO = 65005, +CONFIGITEM_ALLOW_CAL_WRITES = 65006, +``` + +### smc_ams_iram_copy +This function implements a copy of up to one page between DRAM and IRAM. Its arguments are: +``` +args->X[1] = DRAM address (translated by kernel), must be 4-byte aligned. +args->X[2] = IRAM address, must be 4-byte aligned. +args->X[3] = Size (must be <= 0x1000 and 4-byte aligned). +args->X[4] = 0 for read, 1 for write. +``` + +### smc_ams_write_address +This function implements a write to a DRAM page. Its arguments are: +``` +args->X[1] = Virtual address, must be size-bytes aligned and readable by EL0. +args->X[2] = Value. +args->X[3] = Size (must be 1, 2, 4, or 8). +``` + +### smc_ams_get_emummc_config +This function retrieves configuration for the current [emummc](emummc.md) context. Its arguments are: +``` +args->X[1] = MMC id, must be size-bytes aligned and readable by EL0. +args->X[2] = Pointer to output (for paths for filebased + nintendo dir), must be at least 0x100 bytes. +``` + +### CONFIGITEM_EXOSPHERE_VERSION +This custom configuration item gets information about the current exosphere version. + +### CONFIGITEM_NEEDS_REBOOT +This custom configuration item is used to issue a system reboot into RCM or into a warmboot payload leveraging a secondary vulnerability to achieve code execution from warm booting. + +### CONFIGITEM_NEEDS_SHUTDOWN +This custom configuration item is used to issue a system shutdown with a warmboot payload leveraging a secondary vulnerability to achieve code execution from warm booting. + +### CONFIGITEM_EXOSPHERE_VERHASH +This custom configuration item gets information about the current exosphere git commit hash. + +### CONFIGITEM_HAS_RCM_BUG_PATCH +This custom configuration item gets whether the unit has the CVE-2018-6242 vulnerability patched. + +### CONFIGITEM_SHOULD_BLANK_PRODINFO +This custom configuration item gets whether the unit should simulate a "blanked" PRODINFO. See [here](../features/configurations.md) for more information. + +### CONFIGITEM_ALLOW_CAL_WRITES +This custom configuration item gets whether the unit should allow writing to the calibration partition. + +## lp0fw +This is a small, built-in payload that is responsible for waking up the system during a warm boot. + +## sc7fw +This is a small, built-in payload that is responsible for putting the system to sleep during a warm boot. + +## rebootstub +This is a small, built-in payload that provides functionality to reboot the system into any payload of choice. diff --git a/components/fusee.md b/components/fusee.md new file mode 100644 index 0000000..4cd777f --- /dev/null +++ b/components/fusee.md @@ -0,0 +1,22 @@ +# fusée +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/BCT.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. +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. diff --git a/components/libraries.md b/components/libraries.md new file mode 100644 index 0000000..c3840a6 --- /dev/null +++ b/components/libraries.md @@ -0,0 +1,11 @@ +# libraries +This is a collection of libraries for doing operating system development for the Nintendo Switch. + +## libmesosphere +libmesosphere is a work-in-progress C++ library implementing functionality for the Horizon Kernel. + +## libstratosphere +libstratosphere is a work-in-progress C++ library for development of system modules for the Nintendo Switch. + +## libvapours +Common boilerplate code for various purposes. diff --git a/components/mesosphere.md b/components/mesosphere.md new file mode 100644 index 0000000..a56af4b --- /dev/null +++ b/components/mesosphere.md @@ -0,0 +1,3 @@ +# mesosphère +mesosphère is a work in progress customized kernel reimplementation. +The Horizon OS's kernel follows microkernel design principles and runs at the EL1 level. It is currently subdivided into a loader (kernel_ldr) and the main kernel code. diff --git a/components/modules/ams_mitm.md b/components/modules/ams_mitm.md new file mode 100644 index 0000000..0f17c5d --- /dev/null +++ b/components/modules/ams_mitm.md @@ -0,0 +1,35 @@ +# 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 +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](https://github.com/switchbrew/nx-hbloader) (to allow homebrew to take advantage of the feature) + +## fs_mitm +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 +hid_mitm enables intercepting requests to controller device services. It is currently disabled by default. If enabled, it intercepts: ++ [nx-hbloader](https://github.com/switchbrew/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 +ns_mitm enables intercepting requests to application control services. It currently intercepts: ++ Web Applets (to facilitate nx-hbloader web browser launching) + +## set_mitm +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 +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 +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. diff --git a/components/modules/boot.md b/components/modules/boot.md new file mode 100644 index 0000000..c000558 --- /dev/null +++ b/components/modules/boot.md @@ -0,0 +1,4 @@ +# 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. diff --git a/components/modules/boot2.md b/components/modules/boot2.md new file mode 100644 index 0000000..4b7e6f9 --- /dev/null +++ b/components/modules/boot2.md @@ -0,0 +1,4 @@ +# 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](../../features/configurations.md) for more information. diff --git a/components/modules/creport.md b/components/modules/creport.md new file mode 100644 index 0000000..0517840 --- /dev/null +++ b/components/modules/creport.md @@ -0,0 +1,4 @@ +# 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. diff --git a/components/modules/dmnt.md b/components/modules/dmnt.md new file mode 100644 index 0000000..aa9f5fa --- /dev/null +++ b/components/modules/dmnt.md @@ -0,0 +1,42 @@ +# dmnt +This module is a reimplementation of the Horizon OS's `dmnt` system module, which provides a debug monitor. + +## Extensions +Atmosphère implements an extension to provide cheat code functionality. + +### Cheat Service +A HIPC service API is provided for interacting with the cheat code manager through the service `dmnt:cht`. See [here](../../features/cheats.md) 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<bool> out; + [65001] GetCheatProcessEvent() -> sf::OutCopyHandle out_event; + [65002] GetCheatProcessMetadata() -> sf::Out<CheatProcessMetadata> out_metadata; + [65003] ForceOpenCheatProcess(); + [65004] PauseCheatProcess(); + [65005] ResumeCheatProcess(); + + [65100] GetCheatProcessMappingCount() -> sf::Out<u64> out_count; + [65101] GetCheatProcessMappings(u64 offset) -> sf::OutArray<MemoryInfo> &mappings, sf::Out<u64> 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<u64> out_count; + [65201] GetCheats(u64 offset) -> sf::OutArray<CheatEntry> &cheats, sf::Out<u64> out_count; + [65202] GetCheatById(u32 cheat_id) -> sf::Out<CheatEntry> cheat; + [65203] ToggleCheat(u32 cheat_id); + [65204] AddCheat(CheatDefinition &cheat, bool enabled) -> sf::Out<u32> out_cheat_id; + [65205] RemoveCheat(u32 cheat_id); + [65206] ReadStaticRegister(u8 which) -> sf::Out<u64> out; + [65207] WriteStaticRegister(u8 which, u64 value); + [65208] ResetStaticRegisters(); + + [65300] GetFrozenAddressCount() -> sf::Out<u64> out_count; + [65301] GetFrozenAddresses(u64 offset) ->sf::OutArray<FrozenAddressEntry> &addresses, sf::Out<u64> out_count; + [65302] GetFrozenAddress(u64 address) -> sf::Out<FrozenAddressEntry> entry; + [65303] EnableFrozenAddress(u64 address, u64 width) -> sf::Out<u64> out_value; + [65304] DisableFrozenAddress(u64 address); +} +``` diff --git a/components/modules/eclct.stub.md b/components/modules/eclct.stub.md new file mode 100644 index 0000000..c33df9e --- /dev/null +++ b/components/modules/eclct.stub.md @@ -0,0 +1,4 @@ +# 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. diff --git a/components/modules/erpt.md b/components/modules/erpt.md new file mode 100644 index 0000000..dd8e459 --- /dev/null +++ b/components/modules/erpt.md @@ -0,0 +1,4 @@ +# 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/`. diff --git a/components/modules/fatal.md b/components/modules/fatal.md new file mode 100644 index 0000000..63e8ed1 --- /dev/null +++ b/components/modules/fatal.md @@ -0,0 +1,4 @@ +# 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/`. diff --git a/components/modules/jpegdec.md b/components/modules/jpegdec.md new file mode 100644 index 0000000..fcc0d3a --- /dev/null +++ b/components/modules/jpegdec.md @@ -0,0 +1,4 @@ +# 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. diff --git a/components/modules/loader.md b/components/modules/loader.md new file mode 100644 index 0000000..7d3800d --- /dev/null +++ b/components/modules/loader.md @@ -0,0 +1,106 @@ +# loader +This module is a reimplementation of the Horizon OS's `ldr` system module, which is responsible for creating processes from executable NSO images and registering their access control. + +## Extensions +Atmosphère extends this module to allow executables to be replaced or patched by files stored on the SD card. Note that a few services are required for SD card access and therefore cannot be replaced or patched in this manner. + +### Exefs Replacement +Atmosphère's reimplementation allows replacing executable files in the file system. + +#### Partition Replacement +It is possible to replace the full exefs partition at once with a PFS0 file. In that case, Atmosphère will load the following file: +``` +/atmosphere/contents/<program id>/exefs.nsp +``` + +#### File Replacement +When a process is created, loader will search for several NSO filenames in the program's exefs directory. +These filenames are, in this order: + - rtld + - main + - subsdk0 + - subsdk1 + - ... + - subsdk9 + - sdk + +Each NSO that is found will be loaded into the process contiguously. The process's entrypoint is at the first NSO to be loaded, usually `rtld` or `main`. + +Additionally, when a process is loaded, loader will search for a `main.npdm` file in the exefs directory specifying the program's permissions. + +Atmosphère extends this functionality by also searching for these files on the SD card. When searching for a file, loader will first check if it exists on the SD card. If it does, that file will be used instead. Otherwise, it will use the copy located in the exefs, if that is present. The following directory will be searched: +``` +/atmosphere/contents/<program id>/exefs/ +``` + +This allows the replacement of applets, system modules, or even games with homebrew versions. + +##### File Stubbing +In order to prevent an NSO from being loaded even if it exists in the exefs, loader will also check if a stub file exists. If such a file exists, the NSO will not be loaded. The files should be named like `rtld.stub`, `main.stub`, etc. and may be empty. + +##### Technical Semantics + +loader's semantics for content override can (as you may observe from reading the above) be complicated to understand. The following is an abbreviated description of the very technical semantics by which loader decides what content to read when trying to read a file for a program id. + +* If an external content filesystem exists for the program id, the external content filesystem is used directly with no further redirection. +* Otherwise, if the program ID is being overridden with [nx-hbloader](https://github.com/switchbrew/nx-hbloader/releases) (see Homebrew Support below), the nsp filesystem for hbl is used directly with no further redirection. +* Otherwise, if content redirection is enabled for the program ID (controlled by a configurable button combination) and a loose file exists on the SD card, the loose file is used. +* Otherwise, if a stub file exists, a "Not Found" error is returned. +* Otherwise, if an SD card executable filesystem ("exefs.nsp") exists, it is used without further redirection. +* Finally, the "real"/base code file system is used without further redirection. + +In addition, there are a few other technical details relevant to Atmosphere's redirection: +* When overriding with nx-hbloader, the real code filesystem must exist. When "main.npdm" (a program capabilities descriptor file) is read, the content from the real code filesystem is read in order to determine whether an applet or an application is being overridden. This allows nx-hbloader to automatically support both applet and application environments. +* When overriding applications, the real code filesystem must exist and contain valid content. This is required to perform accurate-to-Nintendo content verification procedures. +* When programs are launched, both a program id and a "storage id" are specified by the launch requester. When the storage id specified is "none" (normally always invalid), Atmosphere assumes that a custom system module is attempting to be launched. This removes the aforementioned requirement on base content validity; the above procedure is still used to determine how to redirect content, however reads to the "real"/base code file system may return "Not Found" errors if the real/base code file system does not exist. + +### NSO Patching +When an NSO is loaded, Atmosphère's reimplementation will search for IPS patch files on the SD card in the following locations. +``` +/atmosphere/exefs_patches/<patchset name>/<nso build id>.ips +``` + +This organization allows patch sets affecting multiple NSOs to be distributed as a single directory and also allows patches from multiple patch sets to be stacked. Patches will be searched for in each patch set directory. The name of each patch file should match the hexadecimal build ID of the NSO to affect, except that trailing zero bytes may be left off. Because the NSO build ID is unique for every NSO, this means patches will only apply to the files they are meant to apply to. + +Patch files are accepted in either IPS format or IPS32 format. + +Because NSO files are compressed, patch files are not made between the original version of a compressed NSO and the modified version of such an NSO. Instead, they are made between the uncompressed version of an NSO and the modified (and still uncompressed) version of that NSO. This also means that a patch file cannot be manually applied to the compressed version of an NSO; it must be applied to the uncompressed version. Atmosphère's reimplementation will correctly apply these patches while loading the process regardless of whether the NSO it finds is compressed or not. + +When authoring patches, [hactool](https://github.com/SciresM/hactool) can be used to find an NSO's build ID and to uncompress NSOs. Recent versions of the [ReSwitched IDA loaders](https://github.com/reswitched/loaders) can be used to load uncompressed NSOs into IDA in such a way that you can [apply patches to the input file](https://www.hex-rays.com/products/ida/support/idadoc/1618.shtml). From there, any IPS tool can be used to create the patch between the original NSO and the patched NSO. Note that if the NSO you are patching is larger than 16 MiB, you will have to use a tool that supports IPS32. + +### Homebrew Support +Atmosphère provides first class support for [nx-hbloader](https://github.com/switchbrew/nx-hbloader/releases) and [nx-hbmenu](https://github.com/switchbrew/nx-hbmenu/releases). + +Launching of the nx-hbloader process is controlled by configurable button inputs. See [here](../../features/configurations.md) for more detailed information. + +In addition, loader has extensions to enable homebrew to launch web applets. This normally requires the application launching the applet to have HTML Manual content inside an installed NCA. Atmosphère's reimplementation will automatically ensure that the commands used to check this succeed, and will redirect the relevant file system to the `/atmosphere/hbl_html/` subdirectory. + +### IPC Commands +Atmosphère's reimplementation extends the HIPC loader services' API with several custom commands. + +The SwIPC definition for the `ldr:pm` extension commands follows: +``` +interface ams::ldr::pm::ProcessManagerInterface is ldr:pm { + ... + [65000] AtmosphereHasLaunchedProgram(ncm::ProgramId program_id) -> sf::Out<bool> out; + [65001] AtmosphereGetProgramInfo(ncm::ProgramLocation &loc) -> sf::Out<ProgramInfo> out_program_info, sf::Out<cfg::OverrideStatus> out_status; + [65002] AtmospherePinProgram(ncm::ProgramLocation &loc, cfg::OverrideStatus &override_status) -> sf::Out<PinId> out_id; +} +``` + +The SwIPC definition for the `ldr:dmnt` extension commands follows: +``` +interface ams::ldr::dmnt::DebugMonitorInterface is ldr:dmnt { + ... + [65000] AtmosphereHasLaunchedProgram(ncm::ProgramId program_id) -> sf::Out<bool> out; +} +``` + +The SwIPC definition for the `ldr:shel` extension commands follows: +``` +interface ams::ldr::shell::ShellInterface is ldr:shel { + ... + [65000] AtmosphereRegisterExternalCode(ncm::ProgramId program_id) -> sf::OutMoveHandle out; + [65001] AtmosphereUnregisterExternalCode(ncm::ProgramId program_id); +} +``` diff --git a/components/modules/ncm.md b/components/modules/ncm.md new file mode 100644 index 0000000..89bfab9 --- /dev/null +++ b/components/modules/ncm.md @@ -0,0 +1,4 @@ +# ncm +This module is a reimplementation of the Horizon OS's `ncm` system module, which is responsible for content management. + +Atmosphère's reimplementation is currently opt-in only. See [here](../../features/configurations.md) for more information. diff --git a/components/modules/pgl.md b/components/modules/pgl.md new file mode 100644 index 0000000..305594b --- /dev/null +++ b/components/modules/pgl.md @@ -0,0 +1,4 @@ +# pgl +This module is a reimplementation of the Horizon OS's `pgl` system module, which is responsible for launching programs and was introduced by firmware version `10.0.0`. + +Currently, Atmosphère's reimplementation doesn't backport this module's functionalities to firmware versions lower than `10.0.0`. diff --git a/components/modules/pm.md b/components/modules/pm.md new file mode 100644 index 0000000..cc52a46 --- /dev/null +++ b/components/modules/pm.md @@ -0,0 +1,30 @@ +# pm +This module is a reimplementation of the Horizon OS's `pm` system module, which is responsible for tracking running processes on the system, and managing resource limits. + +## Extensions +Atmosphère extends this module with extra IPC commands and memory restriction changes. + +### IPC Commands +Atmosphère's reimplementation extends the HIPC loader services' API with several custom commands. + +The SwIPC definition for the `pm:dmnt` extension commands follows: +``` +interface ams::pm::dmnt::DebugMonitorServiceBase is pm:dmnt { + ... + [65000] AtmosphereGetProcessInfo(os::ProcessId process_id) -> sf::OutCopyHandle out_process_handle, sf::Out<ncm::ProgramLocation> out_loc, sf::Out<cfg::OverrideStatus> out_status; + [65001] AtmosphereGetCurrentLimitInfo(u32 group, u32 resource) -> sf::Out<s64> out_cur_val, sf::Out<s64> out_lim_val; +} +``` + +The SwIPC definition for the `pm:info` extension commands follows: +``` +interface ams::pm::info::InformationService is pm:info { + ... + [65000] AtmosphereGetProcessId(ncm::ProgramId program_id) -> sf::Out<os::ProcessId> out; + [65001] AtmosphereHasLaunchedProgram(ncm::ProgramId program_id) -> sf::Out<bool> out; + [65002] AtmosphereGetProcessInfo(os::ProcessId process_id) -> sf::Out<ncm::ProgramLocation> out_loc, sf::Out<cfg::OverrideStatus> out_status; +} +``` + +### Extra System Memory +Atmosphère's reimplementation shrinks the APPLET memory pool by 24 MiB by default, giving this memory to the SYSTEM pool. This allows custom system modules to use more memory without hitting the SYSTEM memory limit. diff --git a/components/modules/ro.md b/components/modules/ro.md new file mode 100644 index 0000000..25d967a --- /dev/null +++ b/components/modules/ro.md @@ -0,0 +1,16 @@ +# ro +This module is a reimplementation of the Horizon OS's `ro` system module, which is responsible for loading dynamic libraries and was introduced by firmware version `3.0.0`. + +Atmosphère's reimplementation backports this module's functionalities to firmware versions lower than `3.0.0` where said functionalities were provided by the `ldr` system module instead. + +## Extensions +Atmosphère extends this module to allow libraries to be patched by files stored on the SD card. + +### NRO Patching +When an NRO is loaded, Atmosphère's reimplementation will search for IPS patch files on the SD card in the following locations. +``` +/atmosphere/nro_patches/<patchset name>/<nro build id>.ips +``` +This organization allows patch sets affecting multiple NROs to be distributed as a single directory. Patches will be searched for in each patch set directory. The name of each patch file should match the hexadecimal build ID of the NRO to affect, except that trailing zero bytes may be left off. Because the NRO build ID is unique for every NRO, this means patches will only apply to the files they are meant to apply to. + +Patch files are accepted in either IPS format or IPS32 format. diff --git a/components/modules/sm.md b/components/modules/sm.md new file mode 100644 index 0000000..bba1712 --- /dev/null +++ b/components/modules/sm.md @@ -0,0 +1,47 @@ +# sm +This module is a reimplementation of the Horizon OS's `sm` system module, which is responsible for service management. + +## Extensions +Atmosphère extends this module with extra IPC commands and new services. + +### Debug Monitor +Atmosphère's reimplementation provides an interface `sm:dmnt` to allow a debug monitor to query the service manager's state. + +The SwIPC definition for `sm:dmnt` follows: +``` +interface ams::sm::DmntService is sm:dmnt { + [65000] AtmosphereGetRecord(ServiceName service) -> sf::Out<ServiceRecord> record; + [65001] AtmosphereListRecords(u64 offset) -> sf::OutArray<ServiceRecord> &records, sf::Out<u64> out_count; + [65002] AtmosphereGetRecordSize() -> sf::Out<u64> record_size; +} +``` + +### IPC Commands +Atmosphère's reimplementation extends the HIPC loader services' API with several custom commands. + +The SwIPC definition for the `sm:` extension commands follows: +``` +interface ams::sm::UserService is sm: { + ... + [65000] AtmosphereInstallMitm(ServiceName service) -> sf::OutMoveHandle srv_h, sf::OutMoveHandle qry_h; + [65001] AtmosphereUninstallMitm(ServiceName service); + [65002] Deprecated_AtmosphereAssociatePidTidForMitm(); + [65003] AtmosphereAcknowledgeMitmSession(ServiceName service) -> sf::Out<MitmProcessInfo> client_info, sf::OutMoveHandle fwd_h; + [65004] AtmosphereHasMitm(ServiceName service) -> sf::Out<bool> out; + [65005] AtmosphereWaitMitm(ServiceName service); + [65006] AtmosphereDeclareFutureMitm(ServiceName service); + + [65100] AtmosphereHasService(ServiceName service) -> sf::Out<bool> out; + [65101] AtmosphereWaitService(ServiceName service); +} +``` + +The SwIPC definition for the `sm:m` extension commands follows: +``` +interface ams::sm::ManagerService is sm:m { + ... + [65000] AtmosphereEndInitDefers(os::ProcessId process_id, sf::InBuffer &acid_sac, sf::InBuffer &aci_sac); + [65001] AtmosphereHasMitm(ServiceName service) -> sf::Out<bool> out; + [65002] AtmosphereRegisterProcess(os::ProcessId process_id, ncm::ProgramId program_id, cfg::OverrideStatus override_status, sf::InBuffer &acid_sac, sf::InBuffer &aci_sac); +} +``` diff --git a/components/modules/spl.md b/components/modules/spl.md new file mode 100644 index 0000000..ec1605a --- /dev/null +++ b/components/modules/spl.md @@ -0,0 +1,2 @@ +# spl +This module is a reimplementation of the Horizon OS's `spl` system module, which is responsible for providing secure platform services such as cryptographic operations. diff --git a/components/sept.md b/components/sept.md new file mode 100644 index 0000000..9b91969 --- /dev/null +++ b/components/sept.md @@ -0,0 +1,14 @@ +# sept +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. diff --git a/components/stratosphere.md b/components/stratosphere.md new file mode 100644 index 0000000..8eafc14 --- /dev/null +++ b/components/stratosphere.md @@ -0,0 +1,21 @@ +# stratosphère +stratosphère provides customization of the Horizon OS at the system level. This includes a reimplementation of several system modules and additional, custom system modules that extend or add a variety of features. + +## Modules +The modules currently provided by stratosphère are: ++ [ams_mitm](modules/ams_mitm.md) ++ [boot](modules/boot.md) ++ [boot2](modules/boot2.md) ++ [creport](modules/creport.md) ++ [dmnt](modules/dmnt.md) ++ [eclct.stub](modules/eclct.stub.md) ++ [erpt](modules/erpt.md) ++ [fatal](modules/fatal.md) ++ [jpegdec](modules/jpegdec.md) ++ [loader](modules/loader.md) ++ [ncm](modules/ncm.md) ++ [pgl](modules/pgl.md) ++ [pm](modules/pm.md) ++ [ro](modules/ro.md) ++ [sm](modules/sm.md) ++ [spl](modules/spl.md) diff --git a/components/thermosphere.md b/components/thermosphere.md new file mode 100644 index 0000000..ad75fb2 --- /dev/null +++ b/components/thermosphere.md @@ -0,0 +1,3 @@ +# thermosphère +thermosphère is a work in progress hypervisor implementation. +This aims to provide functionality at the EL2 level which remains unused by the Horizon OS. diff --git a/components/troposphere.md b/components/troposphere.md new file mode 100644 index 0000000..91b62af --- /dev/null +++ b/components/troposphere.md @@ -0,0 +1,5 @@ +# troposphère +troposphère provides customization of the Horizon OS at the application level. + +## reboot_to_payload +Sample application to perform a system reboot into a payload of choice. diff --git a/features/cheats.md b/features/cheats.md new file mode 100644 index 0000000..16514bb --- /dev/null +++ b/features/cheats.md @@ -0,0 +1,428 @@ +# Cheats +Atmosphère supports Action-Replay style cheat codes, with cheats loaded off of the SD card. + +## Cheat Loading Process +By default, Atmosphère will do the following when deciding whether to attach to a new application process: + ++ Retrieve information about the new application process from `pm` and `loader`. ++ Check whether a user-defined key combination is held, and stop if not. + + This defaults to "L is not held", but can be configured with override keys. + + The ini key to configure this is `cheat_enable_key`. ++ Check whether the process is a real application, and stop if not. + + This guards against applying cheat codes to the Homebrew Loader. ++ Attempt to load cheats from `/atmosphere/contents/<program_id>/cheats/<build_id>.txt`, where `build_id` is the hexadecimal representation of the first 8 bytes of the application's main executable's build id. + + If no cheats are found, then the cheat manager will stop. ++ Open a kernel debug session for the new application process. ++ Signal to a system event that a new cheat process has been attached to. + +This behavior ensures that cheat codes are only loaded when the user would want them to. + +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. + +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. + +## Cheat Code Compatibility +Atmosphère manages cheat code through the execution of a small, custom virtual machine. Care has been taken to ensure that Atmosphère's cheat code format is fully backwards compatible with the pre-existing cheat code format, though new features have been added and bugs in the pre-existing cheat code applier have been fixed. Here is a short summary of the changes from the pre-existing format: + ++ A number of bugs were fixed in the processing of conditional instructions. + + The pre-existing implementation was fundamentally broken, and checked for the wrong value when detecting the end of a conditional block. + + The pre-existing implementation also did not properly decode instructions, and instead linearly scanned for the terminator value. This caused problems if an instruction happened to encode a terminator inside its immediate values. + + The pre-existing implementation did not bounds check, and thus certain conditional cheat codes could cause it to read out-of-bounds memory, and potentially crash due to a data abort. ++ Support was added for nesting conditional blocks. ++ An instruction was added to perform much more complex arbitrary arithmetic on two registers. ++ An instruction was added to allow writing the contents of register to a memory address specified by another register. ++ The pre-existing implementation did not correctly synchronize with the application process, and thus would cause heavy lag under certain circumstances (especially around loading screens). This has been fixed in Atmosphère's implementation. + +## Cheat Code Format +The following provides documentation of the instruction format for the virtual machine used to manage cheat codes. + +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. + +#### 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). ++ 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. + +If the condition is not met, all instructions until the appropriate 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). ++ C: Condition to use, see below. ++ A: Immediate offset to use from memory region base. ++ V: Value to compare to. + +#### Conditions ++ 1: > ++ 2: >= ++ 3: < ++ 4: <= ++ 5: == ++ 6: != + +--- + +### 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). + +#### Encoding +`20000000` + +--- + +### Code Type 3: Start/End Loop +Code type 3 allows for iterating in a loop a fixed number of times. + +#### Start Loop Encoding +`300R0000 VVVVVVVV` + ++ R: Register to use as loop counter. ++ V: Number of iterations to loop. + +#### End Loop Encoding +`310R0000` + ++ R: Register to use as loop counter. + +--- + +### Code Type 4: Load Register with Static Value +Code type 4 allows setting a register to a constant value. + +#### Encoding +`400R0000 VVVVVVVV VVVVVVVV` + ++ R: Register to use. ++ V: Value to load. + +--- + +### 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. + +#### 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). ++ R: Register to load value into. ++ A: Immediate offset to use from memory region base. + +#### Load from Register Address Encoding +`5TMR10AA 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. ++ 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. + +#### Encoding +`6T0RIor0 VVVVVVVV VVVVVVVV` + ++ T: Width of memory write (1, 2, 4, or 8 bytes). ++ R: Register used as base memory address. ++ I: Increment register flag (0 = do not increment R, 1 = increment R by T). ++ o: Offset register enable flag (0 = do not add r to address, 1 = add r to address). ++ r: Register used as offset when o is 1. ++ V: Value to write to memory. + +--- + +### Code Type 7: Legacy Arithmetic +Code type 7 allows performing arithmetic on registers. + +However, it has been deprecated by Code type 9, and is only kept for backwards compatibility. + +#### Encoding +`7T0RC000 VVVVVVVV` + ++ T: Width of arithmetic operation (1, 2, 4, or 8 bytes). ++ R: Register to apply arithmetic to. ++ C: Arithmetic operation to apply, see below. ++ V: Value to use for arithmetic operation. + +#### Arithmetic Types ++ 0: Addition ++ 1: Subtraction ++ 2: Multiplication ++ 3: Left Shift ++ 4: Right Shift + +--- + +### Code Type 8: Begin Keypress Conditional Block +Code type 8 enters or skips a conditional block based on whether a key combination is pressed. + +#### Encoding +`8kkkkkkk` + ++ k: Keypad mask to check against, see below. + +Note that for multiple button combinations, the bitmasks should be ORd together. + +#### Keypad Values +Note: This is the direct output of `hidKeysDown()`. + ++ 0000001: A ++ 0000002: B ++ 0000004: X ++ 0000008: Y ++ 0000010: Left Stick Pressed ++ 0000020: Right Stick Pressed ++ 0000040: L ++ 0000080: R ++ 0000100: ZL ++ 0000200: ZR ++ 0000400: Plus ++ 0000800: Minus ++ 0001000: Left ++ 0002000: Up ++ 0004000: Right ++ 0008000: Down ++ 0010000: Left Stick Left ++ 0020000: Left Stick Up ++ 0040000: Left Stick Right ++ 0080000: Left Stick Down ++ 0100000: Right Stick Left ++ 0200000: Right Stick Up ++ 0400000: Right Stick Right ++ 0800000: Right Stick Down ++ 1000000: SL ++ 2000000: SR + +--- + +### Code Type 9: Perform Arithmetic +Code type 9 allows performing arithmetic on registers. + +#### Register Arithmetic Encoding +`9TCRS0s0` + ++ T: Width of arithmetic operation (1, 2, 4, or 8 bytes). ++ C: Arithmetic operation to apply, see below. ++ R: Register to store result in. ++ S: Register to use as left-hand operand. ++ s: Register to use as right-hand operand. + +#### Immediate Value Arithmetic Encoding +`9TCRS100 VVVVVVVV (VVVVVVVV)` + ++ T: Width of arithmetic operation (1, 2, 4, or 8 bytes). ++ C: Arithmetic operation to apply, see below. ++ R: Register to store result in. ++ S: Register to use as left-hand operand. ++ V: Value to use as right-hand operand. + +#### Arithmetic Types ++ 0: Addition ++ 1: Subtraction ++ 2: Multiplication ++ 3: Left Shift ++ 4: Right Shift ++ 5: Logical And ++ 6: Logical Or ++ 7: Logical Not (discards right-hand operand) ++ 8: Logical Xor ++ 9: None/Move (discards right-hand operand) + +--- + +### Code Type 10: Store Register to Memory Address +Code type 10 allows writing a register to memory. + +#### Encoding +`ATSRIOxa (aaaaaaaa)` + ++ T: Width of memory write (1, 2, 4, or 8 bytes). ++ S: Register to write to memory. ++ R: Register to use as base address. ++ I: Increment register flag (0 = do not increment R, 1 = increment R by T). ++ O: Offset type, see below. ++ x: Register used as offset when O is 1, Memory type when O is 3, 4 or 5. ++ a: Value used as offset when O is 2, 4 or 5. + +#### Offset Types ++ 0: No Offset ++ 1: Use Offset Register ++ 2: Use Fixed Offset ++ 3: Memory Region + Base Register ++ 4: Memory Region + Relative Address (ignore address register) ++ 5: Memory Region + Relative Address + Offset Register + +--- + +### Code Type 11: Reserved +Code Type 11 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. + +This reserves an additional 64 opcodes for future use. + +--- + +### Code Type 0xC0: Begin Register Conditional Block +Code type 0xC0 performs a comparison of the contents of a register and another value. This code support multiple operand types, see below. + +If the condition is not met, all instructions until the appropriate conditional block terminator are skipped. + +#### Encoding +``` +C0TcSX## +C0TcS0Ma aaaaaaaa +C0TcS1Mr +C0TcS2Ra aaaaaaaa +C0TcS3Rr +C0TcS400 VVVVVVVV (VVVVVVVV) +C0TcS5X0 +``` + ++ T: Width of memory write (1, 2, 4, or 8 bytes). ++ c: Condition to use, see below. ++ S: Source Register. ++ X: Operand Type, see below. ++ M: Memory Type (operand types 0 and 1). ++ R: Address Register (operand types 2 and 3). ++ a: Relative Address (operand types 0 and 2). ++ r: Offset Register (operand types 1 and 3). ++ X: Other Register (operand type 5). ++ V: Value to compare to (operand type 4). + +#### Operand Type ++ 0: Memory Base + Relative Offset ++ 1: Memory Base + Offset Register ++ 2: Register + Relative Offset ++ 3: Register + Offset Register ++ 4: Static Value ++ 5: Other Register + +#### Conditions ++ 1: > ++ 2: >= ++ 3: < ++ 4: <= ++ 5: == ++ 6: != + +--- + +### Code Type 0xC1: Save or Restore Register +Code type 0xC1 performs saving or restoring of registers. + +#### Encoding +`C10D0Sx0` + ++ D: Destination index. ++ S: Source index. ++ x: Operand Type, see below. + +#### Operand Type ++ 0: Restore register ++ 1: Save register ++ 2: Clear saved value ++ 3: Clear register + +--- + +### Code Type 0xC2: Save or Restore Register with Mask +Code type 0xC2 performs saving or restoring of multiple registers using a bitmask. + +#### Encoding +`C2x0XXXX` + ++ x: Operand Type, see below. ++ X: 16-bit bitmask, bit i == save or restore register i. + +#### Operand Type ++ 0: Restore register ++ 1: Save register ++ 2: Clear saved value ++ 3: Clear register + +--- + +### Code Type 0xC3: Read or Write Static Register +Code type 0xC3 reads or writes a static register with a given register. + +#### Encoding +`C3000XXx` + ++ XX: Static register index, 0x00 to 0x7F for reading or 0x80 to 0xFF for writing. ++ x: Register index. + +--- + +### Code Type 0xF0: Double Extended-Width Instruction +Code Type 0xF0 signals to the VM to treat the upper three nybbles of the first dword as instruction type, instead of just the upper nybble. + +This reserves an additional 16 opcodes for future use. + +--- + +### Code Type 0xFF0: Pause Process +Code type 0xFF0 pauses the current process. + +#### Encoding +`FF0?????` + +--- + +### Code Type 0xFF1: Resume Process +Code type 0xFF1 resumes the current process. + +#### Encoding +`FF1?????` + +--- + +### Code Type 0xFFF: Debug Log +Code type 0xFFF writes a debug log to the SD card under the folder `/atmosphere/cheat_vm_logs/`. + +#### Encoding +``` +FFFTIX## +FFFTI0Ma aaaaaaaa +FFFTI1Mr +FFFTI2Ra aaaaaaaa +FFFTI3Rr +FFFTI4X0 +``` + ++ T: Width of memory write (1, 2, 4, or 8 bytes). ++ I: Log id. ++ X: Operand Type, see below. ++ M: Memory Type (operand types 0 and 1). ++ R: Address Register (operand types 2 and 3). ++ a: Relative Address (operand types 0 and 2). ++ r: Offset Register (operand types 1 and 3). ++ X: Value Register (operand type 4). + +#### Operand Type ++ 0: Memory Base + Relative Offset ++ 1: Memory Base + Offset Register ++ 2: Register + Relative Offset ++ 3: Register + Offset Register ++ 4: Register Value diff --git a/features/configurations.md b/features/configurations.md new file mode 100644 index 0000000..858ec44 --- /dev/null +++ b/features/configurations.md @@ -0,0 +1,153 @@ +# Configurations +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. +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. + +To change its functionality, add the following line to the `stratosphere` section and change the value of `X` according to the following list: +``` +[stratosphere] +nogc = X +``` +``` +1 = force-enable nogc, so Atmosphère will always disable the Game Card reader. +0 = force-disable nogc, so Atmosphère will always enable the Game Card reader. +``` + +### NCM opt-in +Atmosphère provides a reimplementation of the [ncm](../components/modules/ncm.md) system module, but currently this is not enabled by default. If you wish to enable this reimplementation add the following line to the `stratosphere` section: +``` +[stratosphere] +enable_ncm = 1 +``` + +### 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. + +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 special level is also provided to prevent prefix creation. To use it, do a bitwise OR with this mask: +`0x100 = NO_PREFIX` + +## emummc.ini +This is the configuration file used for the [emummc](../components/emummc.md) component. +This file is located under the `/emuMMC/` folder on your SD card. + +Please refer to the project's repository [here](https://github.com/m4xw/emuMMC) for detailed instructions and documentation. + +## exosphere.ini +This is the configuration file used by exosphère. +This file is located in the root of your SD card and a default template can be found inside the `/atmosphere/config_templates/` folder. + +### Configuring Debugging Modes +By default, Atmosphère signals to the Horizon kernel that debugging is enabled while leaving usermode debugging disabled, but this can cause undesirable side-effects. If you wish to change this behavior, go to the `exosphere` section and change the value of `X` according to the following list. +``` +[exosphere] +debugmode = X +debugmode_user = X +``` +``` +1 = enable +0 = disable +``` + +### Blanking PRODINFO +Atmosphère provides a way for users to blank their factory installed calibration data (known as PRODINFO) in either emulated or system eMMC environments. You can find more detailed information on this inside the respective template file. Usage of this configuration is not encouraged. + +## override_config.ini +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. + +### Overrides Format +Overrides are parsed from the `/atmosphere/config/override_config.ini` file during the boot process. + +By default `override_config.ini` is not configured. It can be used to select the behavior of certain buttons and bind them to functionalities such as launching the Homebrew Menu or enabling the cheat code manager. + +You can modify the override_key entries in `override_config.ini` with this list of valid buttons: +| Formal Name | .ini Name | +| ----------- | --------- | +| A Button | A | +| B Button | B | +| X Button | X | +| Y Button | Y | +| Left Stick | LS | +| Right Stick | RS | +| L Button | L | +| R Button | R | +| ZL Button | ZL | +| ZR Button | ZR | +| + Button | PLUS | +| - Button | MINUS | +| Left Dpad | DLEFT | +| Up Dpad | DUP | +| Right Dpad | DRIGHT | +| Down Dpad | DDOWN | +| SL Button | SL | +| SR Button | SR | + +To invert the behavior of the override key, place an exclamation point in front of whatever button you wish to use. It will launch the actual game while holding down that button, instead of going into the Homebrew Menu. For example, `override_key=!R` will run the game only while holding down R when launching it, otherwise it will boot into the Homebrew Menu. Afterwards you may reinsert your SD card into your Switch and boot into Atmosphère as you normally would. You should now be able to boot into the Homebrew Menu by launching your designated program of choice. + +## system_settings.ini +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. + +### Settings Format +Atmosphère provides a way to override the firmware debug settings used by the system. These can be parsed from the `/atmosphere/config/system_settings.ini` file during the boot process. This file is a normal ini file, with some specific interpretations. + +The standard representation of a setting's identifier takes the form `name!key`. This is represented within `system_settings.ini` as a section `name`, with an entry `key`. For example: +``` +[name] +key = ... +``` + +Settings can have variable types (strings, integral values, byte arrays, etc). To accommodate this, `system_settings.ini` must store values as a `type_identifier!value_store` pair. A number of different types are supported, with identifiers detailed below. +Please note that a malformed value string will cause a fatal error to occur on boot. A full example of a custom setting is given below (setting `eupld!upload_enabled = 0`), for posterity: +``` +[eupld] +upload_enabled = u8!0x0 +``` + +#### Supported Types +* Strings + * Type identifiers: `str`, `string` + * The value string is used directly as the setting, with null terminator appended. +* Integral types + * Type identifiers: `u8`, `u16`, `u32`, `u64` + * The value string is parsed via a call to `strtoul(value, NULL, 0)`. + * Setting bitwidth is determined by the identifier (8 for 1 byte, 16 for 2 bytes, and so on). +* Raw bytes + * Type identifiers: `hex`, `bytes` + * The value string is parsed as a hexadecimal string. + * The value string must be of even length, or a fatal error will be thrown on parse. + +## Content Specific Flags +Atmosphère supports customizing CFW behavior based on the presence of `flags` on the SD card. + +The following flags are supported on a per-program basis, by placing `<flag_name>.flag` inside `/atmosphere/contents/<program_id>/flags/`: ++ `boot2`, which indicates that the program should be launched during the `boot2` process. ++ `redirect_save`, which indicates that the program wants its savedata to be redirected to the SD card. diff --git a/release-plans.md b/release-plans.md deleted file mode 100644 index 778a83a..0000000 --- a/release-plans.md +++ /dev/null @@ -1,77 +0,0 @@ -## Upcoming ------ - -**0.7** will be Atmosphère's first official release. It will be released following the resolution of the remaining [0.7 Milestone issues](https://github.com/Atmosphere-NX/Atmosphere/issues?q=is%3Aopen+is%3Aissue+milestone%3A0.7). - -Current best estimate for 0.7's release is August, 2018. - -It will support the following featureset: - -* **Fusée**, a custom bootloader. - * Supports loading/customizing of arbitrary KIPs from the SD card. - * Supports compile-time defined kernel patches on a per-firmware basis. - * Configurable by editing `BCT.ini` on the SD card. - * Atmosphère should also be launchable by the alternative [hekate](https://github.com/CTCaer/hekate) bootloader, for those who prefer it. -* **Exosphère**, a fully-featured custom secure monitor. - * Exosphere is a re-implementation of Nintendo's TrustZone firmware, fully replicating all of its features. - * In addition, it has been extended to provide information on current Atmosphere API version, for homebrew wishing to make use of it. -* **Stratosphère**, a set of custom system modules. This includes: - * A **loader** system module. - * Reimplementation of Nintendo's loader, fully replicating all original functionality. - * Extended to support arbitrary redirection of executable content to the SD card. - * Files will be preferentially loaded from `/atmosphere/titles/<titleid>/exefs/`, if present. - * Files present in the original exefs a user wants to mark as not present may be "stubbed" by creating a .stub file on the SD. - * If present, a PFS0 at `/atmosphere/titles/<titleid>/exefs.nsp` will fully replace the original exefs on 2.0.0+ - * Redirection will be optionally toggleable by holding down certain buttons. - * Full support for patching NSO content is implemented. - * All patches at paths like `/atmosphere/exefs_patches/<user-defined patch name>/<Hex Build-ID for NSO to patch>.ips` will be applied, allowing for easy distribution of patches supporting multiple firmare versions and/or titles. - * Both the IPS and IPS32 formats are supported. - * Extended to support launching content from loose executable files on the SD card, without requiring any official installation. - * This is done by specifying `FsStorageId_None` on launch. - * A **service manager** system module. - * Reimplementation of Nintendo's service manager, fully replicating all original functionality. - * Compile-time support for reintroduction of "smhax", allowing clients to optionally skip service access verification by skipping initialization. - * Extended to allow homebrew to acquire more handles to privileged services than Nintendo natively allows. - * Extended to add a new API for installing Man-In-The-Middle listeners for arbitrary services. - * API can additionally be used to safely detect whether a service has been registered in a non-blocking way with no side-effects. - * Full API documentation to come. - * A **process manager** system module. - * Reimplementation of Nintendo's process manager, fully replicating all original functionality. - * Extended to allow homebrew to acquire handles to arbitrary processes, and thus read/modify system memory without blocking execution. - * Extended by embedding a full, extended implementation of Nintendo's **boot2** system module. - * Title launch order has been optimized in order to grant access to the SD card faster. - * The error-collection system module is intentionally not launched, preventing many system telemetry error reports from being generated at all. - * Users may place their own custom sysmodules on the SD card and flag them for automatic boot2 launch by creating a `/atmosphere/titles/<title ID>/boot2.flag` file on their SD card. - * A custom **fs.mitm** system module. - * Uses Atmosphère's MitM API in order to provide an easy means for users to modify game content. - * Intercepts all FS commands sent by games, with special handling for commands used to mount RomFS/DLC content to enable easy creation and distribution of game/DLC mods. - * fs.mitm will parse the base RomFS image for a game, a RomFS image located at `/atmosphere/titles/<title ID>/romfs.bin`, and all loose files in `/atmosphere/titles/<title ID>/romfs/`, and merge them together into a single RomFS image. - * When merging, loose files are preferred to content in the SD card romfs.bin image, and files from the SD card image are preferred to those in the base image. - * Can additionally be used to intercept commands sent by arbitrary system titles (excepting those launched before SD card is active), by creating a `/atmosphere/titles/<title ID>/fsmitm.flag` file on the SD card. - * A custom **crash report** system module. - * Serves as a drop-in replacement for Nintendo's own creport system module. - * Generates detailed, human-readable reports on system crashes, saving to `/atmosphere/crash_reports/<timestamp>_<title ID>.log`. - * Because reports are not sent to the `erpt` sysmodule, this disables all crash report related telemetry. -* General system stability improvements to enhance the user's experience. - -## Planned ------ - -There are a number of features planned for inclusion Atmosphère that won't make the cut for 0.7's release. As they are implemented, Atmosphère's release version will tick upward from 0.7 to 0.8 to 0.9, and finally 1.0. - -These currently planned features include (but aren't limited to): -* **Thermosphère**, a hypervisor-based emunand implementation. -* A feature-rich debugging toolset (a component of Stratosphère). - * A custom **debug monitor** system module, providing an API for debugging Switch's processes. This may not be a reimplementation of Nintendo's own debug monitor. - * This should include a gdbstub implementation, possibly borrowing from Luma3DS's. - * This API should be additionally usable for RAM Editing/"Cheat Engine" purposes. - * A custom **shell** system module, providing an means for users to perform various RPC (with support for common/interesting functionality) on their Switch remotely. This may not be a reimplementation of Nintendo's own shell. - * This should support client connections over both Wi-Fi and USB. - * A custom **logging** system module, providing a means for other Atmosphère components (and possibly Nintendo's own system modules) to log debug output. - * This should support logging to the SD card, over Wi-Fi, and over USB. -* An application-level plugin system. - * This will, ideally, work somewhat like NTR-CFW's plugin system on the 3DS, allowing users to run their own code in a game's process in their own thread. -* An AR Code/Gameshark analog implementation, allowing for easy sharing/development of cheat codes to run on device. -* Further extensions to existing Atmosphère components. -* General system stability improvements to enhance the user's experience. - diff --git a/roadmap.md b/roadmap.md new file mode 100644 index 0000000..210e3b6 --- /dev/null +++ b/roadmap.md @@ -0,0 +1,49 @@ +# Planned Features +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 in late April of 2020. + +## system updater api +* **Description**: A planned extension api for stratosphere (tenatively `ams:su`), this will provide an interface for homebrew to safely install system upgrades or downgrades. This will allow for much more easily transitioning safely between different versions of the operating system. +* **Development Status**: Under active development by SciresM +* **Estimated Time**: May 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 semi-active development by SciresM; temporarily on pause while the System Updater API is completed. +* **Estimated Time**: Mid-to-Late 2020 + +## 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. +* **Development Status**: Planned. +* **Estimated Time**: 2020-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. + +## 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 + +## 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. + +## thermosphère +* **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. + +## other planned features +* **Description**: General system stability improvements to enhance the user's experience. +* **Development Status**: Undergoing active development by all members of the atmosphère team. +* **Estimated Time**: June 15th.