docs: address review commentary

docs/components/emummc.md

@@ -1,4 +1,4 @@
 # emummc
-emummc is a collaboration project that provides eMMC storage emulation.
+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.

docs/components/exosphere.md

@@ -1,12 +1,70 @@
-# Exosphère
-Exosphère is a customized reimplementation of the Horizon OS's Secure Monitor.
+# 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:
-+ smc_ams_iram_copy
-+ smc_ams_write_address
-+ smc_ams_get_emummc_config
+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.

docs/components/fusee.md

@@ -1,22 +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
+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 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'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.
+## 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.
+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-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.
+## fusée-secondary
+fusée-secondary is the last fusée sub-component that runs on the system.
 It is responsible for configuring and bootstrapping the Atmosphère environment by mimicking the Horizon OS's design.
-This includes setting up the cryptosystem, mounting or emulating the eMMC, injecting or patching system modules and launching the Exosphère component.
+This includes setting up the cryptosystem, mounting or emulating the eMMC, injecting or patching system modules and launching the exosphère component.

docs/components/libraries.md

@@ -1,4 +1,4 @@
-# Libraries
+# libraries
 This is a collection of libraries for doing operating system development for the Nintendo Switch.
 
 ## libmesosphere

docs/components/mesosphere.md

@@ -1,3 +1,3 @@
-# Mesosphère
-Mesosphère is a work in progress customized kernel reimplementation.
+# 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.

docs/components/modules/ams_mitm.md

@@ -5,28 +5,30 @@ This module provides methods to intercept services provided by other system modu
 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)
-+ Homebrew Loader (to allow homebrew to take advantage of the feature)
++ [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:
-+ Homebrew Loader (to help homebrew not need to be recompiled due to a breaking change introduced in the past)
++ [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 hbl web browser launching)
++ 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 settings requests
++ 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 #.#.#)`. This allows users to easily verify what version of Atmosphère they are running.
+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.

docs/components/modules/loader.md

@@ -5,6 +5,15 @@ This module is a reimplementation of the Horizon OS's `ldr` system module, which
 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
@@ -26,19 +35,16 @@ Atmosphère extends this functionality by also searching for these files on the
 
 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.
 
-It is also 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
-```
-
 ### 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. 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.
+
+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.
 
@@ -46,8 +52,10 @@ Because NSO files are compressed, patch files are not made between the original
 
 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
-Atmosphère provides first class support for [hbmenu](https://github.com/switchbrew/nx-hbmenu/releases) and [hbloader](https://github.com/switchbrew/nx-hbloader/releases).
+### 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.
 

docs/components/modules/ncm.md

@@ -1,4 +1,4 @@
 # ncm
-This module is a reimplementation of the Horizon OS's `ncm` system module, which is responsible content management.
+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.

docs/components/modules/pgl.md

@@ -1,2 +1,4 @@
 # pgl
-This module is a reimplementation of the Horizon OS's `pgl` system module, which is responsible for launching programs.
+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`.

docs/components/modules/ro.md

@@ -1,5 +1,7 @@
 # ro
-This module is a reimplementation of the Horizon OS's `ro` system module, which is responsible for loading dynamic libraries.
+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.

docs/components/sept.md

@@ -1,14 +1,14 @@
-# Sept
+# 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`.
+## 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.
+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`.
+## 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.
+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.

docs/components/stratosphere.md

@@ -1,8 +1,8 @@
-# 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.
+# 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:
+The modules currently provided by stratosphère are:
 + [ams_mitm](modules/ams_mitm.md)
 + [boot](modules/boot.md)
 + [boot2](modules/boot2.md)

docs/components/thermosphere.md

@@ -1,3 +1,3 @@
-# Thermosphère
-Thermosphère is a work in progress hypervisor implementation.
+# 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.

docs/components/troposphere.md

@@ -1,5 +1,5 @@
-# Troposphère
-Troposphère provides customization of the Horizon OS at the application level.
+# 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.