diff --git a/docs/building.md b/docs/building.md index 5e5449c29..d8c920d6e 100644 --- a/docs/building.md +++ b/docs/building.md @@ -4,18 +4,24 @@ Building Atmosphère is a very straightforward process that relies almost exclus ## Dependencies + [devkitA64](https://devkitpro.org) + [devkitARM](https://devkitpro.org) -+ [Python 2 or 3](https://www.python.org) -+ [PyCryptodome](https://pypi.org/project/pycryptodome) ++ [Python 2 or 3](https://www.python.org) (optional) ++ [PyCryptodome](https://pypi.org/project/pycryptodome) (optional) ## Instructions -Follow the guide located [here](https://switchbrew.org/wiki/Setting_up_Development_Environment) to install and configure all the tools necessary for the build process. +1. Follow the guide located [here](https://devkitpro.org/wiki/Getting_Started) to install and configure all the tools necessary for the build process. -Install the following packages via (dkp-)pacman: -+ switch-dev -+ switch-libjpeg-turbo -+ devkitARM -+ devkitarm-rules +2. Install the following packages via (dkp-)pacman: ++ `switch-dev` ++ `switch-libjpeg-turbo` ++ `devkitARM` ++ `devkitarm-rules` -In order to build [Sept](components/sept.md) the pycryptodome PyPi package is required. You may install this package by running `pip install pycryptodome` under the installed Python environment of your choice. You may also want to install the zip package to support the `make dist` recipe. +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. -Finally, clone the Atmosphère repository and run `make` under its root directory. +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/docs/components/emummc.md b/docs/components/emummc.md index f7d45f462..6ae69b9ce 100644 --- a/docs/components/emummc.md +++ b/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. diff --git a/docs/components/exosphere.md b/docs/components/exosphere.md index 41eee173b..1b7f963da 100644 --- a/docs/components/exosphere.md +++ b/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. diff --git a/docs/components/fusee.md b/docs/components/fusee.md index 9a47bedd4..4cd777f40 100644 --- a/docs/components/fusee.md +++ b/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. diff --git a/docs/components/libraries.md b/docs/components/libraries.md index 06b13d23d..c3840a681 100644 --- a/docs/components/libraries.md +++ b/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 diff --git a/docs/components/mesosphere.md b/docs/components/mesosphere.md index 5ee758fa1..a56af4ba8 100644 --- a/docs/components/mesosphere.md +++ b/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. diff --git a/docs/components/modules/ams_mitm.md b/docs/components/modules/ams_mitm.md index e95dfd1a5..0f17c5d26 100644 --- a/docs/components/modules/ams_mitm.md +++ b/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. diff --git a/docs/components/modules/loader.md b/docs/components/modules/loader.md index 97204bee4..6ddd3bbd9 100644 --- a/docs/components/modules/loader.md +++ b/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//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//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//.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. diff --git a/docs/components/modules/ncm.md b/docs/components/modules/ncm.md index 5a4971d91..89bfab956 100644 --- a/docs/components/modules/ncm.md +++ b/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. diff --git a/docs/components/modules/pgl.md b/docs/components/modules/pgl.md index fa1658a8d..305594b22 100644 --- a/docs/components/modules/pgl.md +++ b/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`. diff --git a/docs/components/modules/ro.md b/docs/components/modules/ro.md index 9f6f7d767..25d967aaf 100644 --- a/docs/components/modules/ro.md +++ b/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. diff --git a/docs/components/sept.md b/docs/components/sept.md index b080cba7c..9b91969f2 100644 --- a/docs/components/sept.md +++ b/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. diff --git a/docs/components/stratosphere.md b/docs/components/stratosphere.md index e539b887d..8eafc1412 100644 --- a/docs/components/stratosphere.md +++ b/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) diff --git a/docs/components/thermosphere.md b/docs/components/thermosphere.md index c12f7c85d..ad75fb256 100644 --- a/docs/components/thermosphere.md +++ b/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. diff --git a/docs/components/troposphere.md b/docs/components/troposphere.md index 538bc8d88..91b62afc2 100644 --- a/docs/components/troposphere.md +++ b/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. diff --git a/docs/features/cheats.md b/docs/features/cheats.md index 007a50584..16514bb32 100644 --- a/docs/features/cheats.md +++ b/docs/features/cheats.md @@ -19,7 +19,7 @@ This behavior ensures that cheat codes are only loaded when the user would want In cases where `dmnt` has not activated the cheat manager, but the user wants to make it do so anyway, the cheat manager's service API provides a `ForceOpenCheatProcess` command that homebrew can use. This command will cause the cheat manager to try to force itself to attach to the process. -By default, all cheat codes listed in the loaded .txt file will be toggled on. This is configurable by the user, and the default can be set to toggled off by editing the `atmosphere!dmnt_cheats_enabled_by_default` entry to 0 instead of 1. +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. diff --git a/docs/features/configurations.md b/docs/features/configurations.md index b296de6fe..858ec443c 100644 --- a/docs/features/configurations.md +++ b/docs/features/configurations.md @@ -2,23 +2,26 @@ 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 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 ``` -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. - ### 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. +"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 ``` ``` @@ -29,10 +32,13 @@ nogc = X ### 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] @@ -47,17 +53,23 @@ log_level = X 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. +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 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 ``` @@ -105,15 +117,15 @@ To invert the behavior of the override key, place an exclamation point in front 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 -Settings are parsed from the `/atmosphere/config/system_settings.ini` file during the boot process. This file is a normal ini file, with some specific interpretations. +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 system 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: +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 = ... ``` -System 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. +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] diff --git a/docs/main.md b/docs/main.md index c6bd497e3..44e64a7de 100644 --- a/docs/main.md +++ b/docs/main.md @@ -3,17 +3,17 @@ Atmosphère is a work-in-progress customized firmware for the Nintendo Switch. I ## 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) ++ [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) Additionally, Atmosphère also provides the following secondary components: + [emummc](components/emummc.md) -+ [Sept](components/sept.md) -+ [Libraries](components/libraries.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: