Merge pull request #210 from joelc608/master

Add Documentation

docs/building.md

@@ -0,0 +1,6 @@
+# Building Atmosphère
+The process for building Atmosphère is similar to building Fusée Gelée payloads and other Switch apps.
+
+In order to build Atmosphère you must have devkitARM and devkitA64 installed on your computer. You can find instructions on how to install and setup devkitARM and devkitA64 on various OSes [here](https://devkitpro.org/wiki/Getting_Started).
+
+Once you have finished installing devkitARM and devkitA64, simply clone the Atmosphère repo, change to it and run `make`.

docs/components/exosphere.md

@@ -0,0 +1,10 @@
+# Exosphère
+Exosphère is a reimplementation of Arm's TrustZone (TZ), also known as Secure Monitor (Secure_Monitor.bin). It has the highest privilege mode available on the Switch’s processor, and has access to everything on the console.
+
+Exosphère will potentially play a big role in Jamais Vu and Déja Vu, which are upcoming software exploits for the Switch, allowing one to launch Atmosphère on a Fusée-Gélee patched (ipatched) Switch console, and will also enable one to launch into CFW directly from the Switch itself without the use of any sort of external device, such as a computer or RCM jig, provided they are on a low enough system firmware.
+
+## TrustZone/Secure Monitor
+TrustZone is responsible for all the cryptographic operations on the Switch. The idea behind the way it operates is that all the keys stay in the TrustZone, and userspace only gets "handles" to them. This would make sure that keydata never leaks and is kept secure. It also has a few more responsibilities, such as power management, providing a source of random numbers, and providing access to various pieces of information that are stored in the fuses.
+
+## Extensions
+Exosphère currently only contains one extension, an SMC allowing homebrew to find which version of Atmosphère is currently running, in order to find out what extensions are allowed to be used.

docs/components/fusee/BCT.md

@@ -0,0 +1,26 @@
+# BCT.ini
+BCT.ini is the configuration file used by fusée-primary and fusée-secondary. It is read by fusee-primary.bin to setup and boot fusee-secondary.bin and is also read by fusee-secondary.bin to configure Exosphère or to specify the environment it should boot.
+
+## Configuration
+This file is located at the root of your SD.
+```
+BCT0
+[stage1]
+stage2_path = fusee-secondary.bin
+stage2_addr = 0xF0000000
+stage2_entrypoint = 0xF0000000
+```
+Add the following lines and replace the `X` according to the following list if you have trouble booting past the firmware version detection.
+`target_firmware` is the OFW major version. 
+```
+[exosphere]
+target_firmware = X
+```
+```
+1.0.0 = 1
+2.X.X = 2
+3.X.X = 3
+4.X.X = 4
+5.X.X = 5
+6.0.0 = 6
+```

docs/components/fusee/fusee.md

@@ -0,0 +1,20 @@
+# Fusée
+Fusée (not to be confused with Fusée Gelée) is a custom bootloader needed to start Atmosphère and replaces Nintendo's Package1loader/bootloader. It currently utilizes the [Tegra X1 RCM Vulnerability](https://nvidia.custhelp.com/app/answers/detail/a_id/4660/~/security-notice%3A-nvidia-tegra-rcm-vulnerability) in order to function.
+
+Fusée is split into two separate parts: fusée-primary and fusée-secondary. This is due to the RCM Vulnerability only allowing payloads of a limited filesize to be sent to the device.
+
+As of June 2018, there are new Switch systems being sold that prevent Fusée (or any payload that requires the Fusée Gelée exploit) from working due to having an ipatched bootrom. All ipatched systems share the HAC-S-JXE-C3 product code. While Fusée cannot work on these ipatched units, they still come on firmware 4.1.0, which is vulnerable to the upcoming Déja Vu software exploit. Note that if you update past 4.1.0 on one of these ipatched units, your odds of being able to install Atmosphère or run any homebrew become practically non-existent.
+
+Additionally, a hardware revision of the Switch known as “Mariko” is believed to be in development. No such units have been seen in stores yet, but it is expected Nintendo will roll them out silently. The Mariko units will most likely patch the bootrom vulnerability Fusée Gelée, which is currently used to access CFW, and will likely have their own proprietary bootloader.
+
+## Fusée-Primary
+Fusée-primary is the payload file (fusee-primary.bin) sent to the Switch from an external device. Once sent, fusée-primary makes initial preparations before loading fusée-secondary from the Switch’s SD Card.
+
+Fusée-primary can be configured via the [BCT.ini](../fusee/BCT.md) file located on the Switch’s SD card.
+
+## Fusée-Secondary
+Fusée-secondary is a payload file that stays on the root of the Switch’s SD Card (fusee-secondary.bin). It is automatically launched once fusée-primary has finished, and is responsible for preparing the Switch’s hardware for future running environments, such as the homebrew menu. Fusée-secondary is also responsible for validating and launching Exosphère.
+
+Fusée-secondary contains various [.kip modules](/docs/main.md#modules). These modules modify existing features in the OS, and can also add new ones.
+
+Fusée is also capable of chainloading other payloads such as Linux.

docs/components/stratosphere.md

@@ -0,0 +1,10 @@
+# Stratosphère
+Stratosphère allows customization of the Horizon OS and Switch kernel. It includes custom sysmodules that extend the kernel and provide new features. It also includes a reimplementation of the loader sysmodules to hook important system actions.
+
+The sysmodules that Stratosphère includes are:
++ [boot](../modules/boot.md): This module boots the system and initalizes hardware.
++ [creport](../modules/creport.md): Reimplementation of Nintendo’s crash report system. Dumps all error logs to the SD card instead of saving them to the NAND and sending them to Nintendo.
++ [fs_mitm](../modules/fs_mitm.md): This module can log, deny, delay, replace, and redirect any request made to the File System.
++ [loader](../modules/loader.md): Enables modifying the code of binaries that are not stored inside the kernel.
++ [pm](../modules/pm.md): Reimplementation of Nintendo’s Process Manager.
++ [sm](../modules/sm.md): Reimplementation of Nintendo’s Service Manager.

docs/components/thermosphere.md

@@ -0,0 +1,6 @@
+# Thermosphère
+Thermosphère is a hypervisor based implementation of emuNAND. An emuNAND is a copy of the firmware on the Switch’s internal memory (sysNAND), and is typically installed on an external SD Card.
+
+An emuNAND operates completely independently of the sysNAND. This allows one to make or test various modifications and homebrew safely without needing to restore their NAND backup afterwards by testing things on the emuNAND, and switching back to the sysNAND when finished. In the case of past Nintendo systems such as the 3DS, an emuNAND could also be used to update your system to the latest firmware while keeping your sysNAND on a lower version, however this may be more difficult to do on the Switch due to Nintendo using efuse technology for major system updates.
+
+Thermosphère is currently planned to be included in the 1.0 release of Atmosphère.

docs/components/troposphere.md

@@ -0,0 +1,2 @@
+# Troposphère
+Troposphère contains various application-level modifications to the OS, such as launching homebrew directly from the homemenu or executing cheat/gameshark codes, similar to Luma3DS. Troposphère is not yet implemented in Atmosphère.

docs/main.md

@@ -0,0 +1,26 @@
+# Atmosphère
+Atmosphère is a work-in-progress customized firmware for the Nintendo Switch. Atmosphère consists of several different components, each in charge of performing different system functions of the Nintendo Switch.
+
+The components of Atmosphère are:
++ [Fusée](../docs/components/fusee/fusee.md), a custom bootloader.
++ [Exosphère](../docs/components/exosphere.md), a fully-featured custom secure monitor.
++ [Stratosphère](../docs/components/stratosphere.md), a set of custom system modules.
++ [Thermosphère](../docs/components/thermosphere.md), a hypervisor-based emuNAND implementation. This component has not been implemented yet.
++ [Troposphère](../docs/components/troposphere.md), Application-level patches to the Horizon OS. This component has also not been implemented yet.
+
+### Modules
+The Stratosphère component of Atmosphère contains various modules. These have a `.kip` extension. They provide custom features, extend existing features, or replace Nintendo sysmodules.
+
+Stratosphère's modules include:
++ [boot](../docs/modules/boot.md)
++ [creport](../docs/modules/creport.md)
++ [fs_mitm](../docs/modules/fs_mitm.md)
++ [loader](../docs/modules/loader.md)
++ [pm](../docs/modules/pm.md)
++ [sm](../docs/modules/sm.md)
+
+### Building Atmosphère
+A guide to building Atmosphère can be found [here](../docs/building.md).
+
+### Release Roadmap
+A roadmap of the releases of Atmosphère can be found [here](../docs/roadmap.md).

docs/modules/boot.md

@@ -0,0 +1,2 @@
+# boot
+The boot module is responsible for booting the system and initalizing hardware. A second boot module known as boot2 is integrated with the [pm (process manager)](../modules/pm.md) sysmodule in Atmosphère, and launches other processes.

docs/modules/creport.md

@@ -0,0 +1,2 @@
+# creport
+creport is a reimplementation of Nintendo's crash reporter. Atmosphère's creport catches all error logs that would have been saved to the NAND and instead saves them to the SD card for debugging purposes. This is helpful because the errors no longer go to Nintendo and developers of homebrew can still see the errors to help with the debugging process. creport catches system errors, game crashes, and homebrew crashes.

docs/modules/fs_mitm.md

@@ -0,0 +1,2 @@
+# fs_mitm
+fs_mitm is a sysmodule that enables intercepting file system operations. This module can log, deny, delay, replace, or redirect any request made to the filesystem. It enables LayeredFS to function, which allows for game mods.

docs/modules/loader.md

@@ -0,0 +1,64 @@
+# loader
+
+loader is a reimplementation of the loader sysmodule. This module is responsible for creating processes from executable NSO images and registering their access control with the kernel, sm, and fs.
+
+## Atmosphère 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. This includes psc, bus, and pcv.
+
+### Exefs Replacement
+
+TODO: details on buttons affecting this.
+
+When a process is created, loader will search for several NSO filenames in the title'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 title'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.
+
+```
+sdmc:/atmosphere/titles/<title id>/exefs/
+```
+
+This allows the replacement of applets, sysmodules, or even games with homebrew versions.
+
+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.
+
+### NSO Patching
+
+TODO: details on buttons affecting this.
+
+When an NSO is loaded, the stratosphere implementatin of loader will search for IPS patch files on the SD card in the following locations.
+```
+sdmc:/atmosphere/exefs_patches/<patchset name>/<nso build id>.ips
+```
+This organization allows patchsets affecting multiple NSOs to be distributed as a single directory. Patches will be searched for in each patchset 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. The Stratosphere implementation of loader 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.
+
+### HBL Support
+
+TODO
+
+### Button Overrides
+
+TODO
+
+### SM MITM Integration
+
+When the Stratosphere implementation of loader creates a new process, it notifies [sm](sm.md) through the `AtmosphereAssociatePidTidForMitm` command to notify any MITM services of new processes' identities.

docs/modules/pm.md

@@ -0,0 +1,23 @@
+# pm
+
+pm is a reimplementation of Nintendo's process manager. This module is responsible for tracking running processes on the system, and managing resource limits. pm is also required to create and manage processes for homebrew applications.
+
+## Atmosphère Extensions
+
+There are a few ways in which the Stratosphere implementation of pm differs intentionally from the stock pm.
+
+### IPC: AtmosphereGetProcessHandle
+
+The Stratosphere implementation of pm adds an additional command to the [`pm:dmnt`](https://reswitched.github.io/SwIPC/ifaces.html#nn::pm::detail::IDebugMonitorInterface) interface, called `AtmosphereGetProcessHandle`. Its command ID is `65000` on all system firmware versions. It takes a `u64 process_id` and returns a process handle for the specified process, if that process is known. Notable exceptions include KIPs, which are not known to pm. If the specified process cannot be found, error code 0x20F is returned.
+
+The SwIPC definition for this command follows.
+```
+interface nn::pm::detail::IDebugMonitorInterface is pm:dmnt {
+  ...
+  [65000] AtmosphereGetProcessHandle(u64 pid) -> handle<copy, process> process_handle;
+}
+```
+
+### Extra System Memory for Sysmodules
+
+The Stratosphere implementation of pm shrinks the APPLET memory pool by 24 MiB by default, giving this memory to the SYSTEM pool. This allows custom sysmodules to use more memory without hitting the SYSTEM memory limit.

docs/modules/sm.md

@@ -0,0 +1,69 @@
+# sm
+
+sm is a reimplementation of Nintendo's service manager. It allows Atmosphère to add or remove process handle limits, add new services, or intercept service calls. This allows high-level intercepting of Horizon OS functionality.
+
+## Atmosphère Extensions
+
+There are a few ways in which the Stratosphere implementation of sm differs intentionally from the stock sm.
+
+### IPC: MITM Commands
+
+The Stratosphere implementation of sm adds a few additional commands to the [`sm:`](https://reswitched.github.io/SwIPC/ifaces.html#nn::sm::detail::IUserInterface) port session.
+
+Their SwIPC definitions follow.
+```
+interface nn::sm::detail::IUserInterface is sm: {
+  ...
+  [65000] AtmosphereInstallMitm(ServiceName service) -> handle<port, move> service, handle<server_session, move> query;
+  [65001] AtmosphereUninstallMitm(ServiceName service);
+  [65002] AtmosphereAssociatePidTidForMitm(u64 pid, u64 tid);
+}
+```
+
+#### AtmosphereInstallMitm
+
+This command alters the registration for the named service, in order to allow services to intercept communication between client processes and their intended services. It is used by [fs_mitm](fs_mitm.md).
+
+It takes the name of the service to install an MITM for, and returns two handles. The first is a port handle, similar to those returned from the [RegisterService](https://reswitched.github.io/SwIPC/ifaces.html#nn::sm::detail::IUserInterface(2)) command. The second is the server side of a session, called the query session. This session will used by sm to determine whether or not a new session should be intercepted, and to inform the MITM service of the identity of new processes.
+
+The query session is expected to implement the following interface.
+```
+interface MitmQueryService {
+  [65000] ShouldMitm(u64 pid) -> u64 should_mitm;
+  [65001] AssociatePidTid(u64 pid, u64 tid);
+}
+```
+
+The `ShouldMitm` command is invoked whenever a process attempts to make a new connection to the MITM'd service. It should return `0` if the process's connection should not be intercepted. Any other value will cause the process's connection to be intercepted. If the command returns an error code, the process's connection will not be intercepted.
+
+The `AssociatePidTid` command is invoked on all MITM query sessions whenever a new process is created, in order to inform those services of the identity of a newly created process before it attempts to connect to any services.
+
+If the process that installed the MITM attempts to connect to the service, it will always connect to the original service.
+
+This command requires that the session be initialized, returning error code 0x415 if it is not.
+If the given service name is invalid, error code 0xC15 is returned.
+If the user does not have service registration permission for the named service, error code 0x1015 is returned.
+If the service has not yet been registered, error code 0xE15 is returned.
+If the service already has an MITM installed, error code 0x815 is returned.
+
+#### AtmosphereUninstallMitm
+
+Removes any installed MITM for the named service.
+
+This command requires that the session be initialized, returning error code 0x415 if it is not.
+
+#### AtmosphereAssociatePidTidForMitm
+
+This command is used internally by the Stratosphere implementation of the [loader](loader.md) sysmodule, when a new process is created. It will call the `AssociatePidTid` command on every registered MITM query session.
+
+If the given process ID refers to a kernel internal process, error code 0x1015 is returned. This command requires that the session be initialized, returning error code 0x415 if it is not.
+
+### Minimum Session Limit
+
+When a service is registered, the sysmodule registering it must specify a limit on the number of sessions that are allowed to be active for that service at a time. This is used to ensure that services like `fs-pr`, `fs-ldr`, and `ldr:pm` can only be connected to once, adding an additional layer of safety over the regular service verification to ensure that those services are only connected to by the highly priveleged process they are intended to be used by.
+
+By default, the Stratosphere implementation of PM will raise any session limits to at least 8, meaning that for services like `fs-pr` and those mentioned above, up to 8 processes will be able to connect to those sessions, leaving 7 sessions for homebrew to use.
+
+### Weak Service Verification
+
+In system firmware versions before 3.0.1, if a process did not call the [Initialize](https://reswitched.github.io/SwIPC/ifaces.html#nn::sm::detail::IUserInterface(0)) command on its `sm:` session, normally used to inform sm of the process's identity, sm would assume that the process was a kernel internal process and skip any service registration or access checks. The Stratosphere implementation of sm reimplements this vulnerability, allowing homebrew processes to skip service registration and access checks.

docs/roadmap.md

@@ -0,0 +1,19 @@
+# Release Roadmap
+## Upcoming Releases
+### 0.7
+0.7 will be Atmosphère's first official release.
+This release will include:
++ Fusée
+  + 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 bootloader, for those who prefer it.
++ Exosphère
+  + 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
+  + loader system module
+  + Service Manager system module (sm)
+  + Process Manager system module (pm)
+  + fs.mitm system module
+  + creport system module