Homebrew ABI - Revision history

Fincs: Added SyscallAvailableHint2

2022-10-12T15:35:22Z

Added SyscallAvailableHint2

← Older revision		Revision as of 19:35, 12 October 2022
Line 84:		Line 84:

	* 16: [[#HosVersion]]		* 16: [[#HosVersion]]

			* 17: [[#SyscallAvailableHint2]]

	==== EndOfList ====		==== EndOfList ====
Line 242:		Line 244:
	* '''Value[0]:''' HOS version, formatted using libnx's [https://github.com/switchbrew/libnx/blob/master/nx/include/switch/runtime/hosversion.h#L11 MAKEHOSVERSION macro].		* '''Value[0]:''' HOS version, formatted using libnx's [https://github.com/switchbrew/libnx/blob/master/nx/include/switch/runtime/hosversion.h#L11 MAKEHOSVERSION macro].
	* '''Value[1]:''' Magic value indicating the current implementation of Horizon OS.		* '''Value[1]:''' Magic value indicating the current implementation of Horizon OS.

			==== SyscallAvailableHint2 ====
			Supplement to [[#SyscallAvailableHint]] for the extended SVC range.

			* '''Key:''' 17
			* '''Value[0]:''' 64-bit mask for the 0x80-0xBF SVC range. n:th bit set means SVC is accessible.
			* '''Value[1]:''' Reserved/should be zero.
			* '''DefaultBehavior:''' See [[#SyscallAvailableHint]].

	{\| class="wikitable" border="1"		{\| class="wikitable" border="1"

Fincs: /* HosVersion */

2021-04-11T10:40:59Z

HosVersion

← Older revision		Revision as of 14:40, 11 April 2021
Line 237:		Line 237:

	==== HosVersion ====		==== HosVersion ====
	This key provides the currently running version of Horizon OS.		This key provides information about the currently running version of Horizon OS. This is used in order to determine the compatible ABI/API (both kernel and userland) available to homebrew applications.

	* '''Key''': 16		* '''Key''': 16
	* '''Value[0]:''' HOS version, formatted using libnx's [https://github.com/switchbrew/libnx/blob/master/nx/include/switch/runtime/hosversion.h#L11 MAKEHOSVERSION macro].		* '''Value[0]:''' HOS version, formatted using libnx's [https://github.com/switchbrew/libnx/blob/master/nx/include/switch/runtime/hosversion.h#L11 MAKEHOSVERSION macro].
	* '''Value[1]:''' ~~Reserved~~/~~should be zero~~.		* '''Value[1]:''' Magic value indicating the current implementation of Horizon OS.

			{\| class="wikitable" border="1"
			! Value
			! Description
			\|-
			\| 0
			\| Unspecified implementation/official stock firmware by Nintendo.
			\|-
			\| 0x41544d4f53504852 (ATMOSPHR)
			\| [https://github.com/Atmosphere-NX/Atmosphere Atmosphère-NX customized firmware].
			\|}

Fincs at 18:07, 29 July 2019

2019-07-29T16:07:17Z

← Older revision		Revision as of 20:07, 29 July 2019
Line 80:		Line 80:

	* 14: [[#RandomSeed]]		* 14: [[#RandomSeed]]

			* 15: [[#UserIdStorage]]

			* 16: [[#HosVersion]]

	==== EndOfList ====		==== EndOfList ====
	EndOfList is the final entry in the LoaderConfig.		EndOfList is the final entry in the LoaderConfig. It also provides optional human readable information about the Homebrew loader.

	* '''Key:''' 0		* '''Key:''' 0
	* '''Value[0]:''' ~~Ignored~~.		* '''Value[0]:''' Pointer to loader information string, or zero if not present.
	* '''Value[1]:''' ~~Ignored~~.		* '''Value[1]:''' Size in bytes of the information string, or zero if not present.

	==== MainThreadHandle ====		==== MainThreadHandle ====
Line 93:		Line 97:
	* '''Key:''' 1		* '''Key:''' 1
	* '''Value[0]:''' Handle to the main thread.		* '''Value[0]:''' Handle to the main thread.
	* '''Value[1]:''' ~~Ignored~~.		* '''Value[1]:''' Reserved/should be zero.
	* '''DefaultBehavior:''' Use main thread handle from entry function arguments.		* '''DefaultBehavior:''' Use main thread handle from entry function arguments.

Line 112:		Line 116:

	==== OverrideService ====		==== OverrideService ====
	The NRO loader should be able to steal handles from more priliveged processes. In this case, ~~the~~ homebrew should use this handle instead of the normal one.		The NRO loader should be able to steal handles from more priliveged processes. In this case, homebrew should use this handle instead of the normal one.

	Homebrew should allow ~~up to~~ 32 service overrides.		Homebrew should allow at least 32 service overrides.

	Note: Overridden service handles should not be converted to domains or closed. If they are domain, they should be converted to sessions before passed to the homebrew application.		Note: Overridden service handles should not be converted to domains or closed. If they are domain, they should be converted to sessions before passed to the homebrew application.
Line 131:		Line 135:

	* '''Key:''' 5		* '''Key:''' 5
	* '''Value[0]:''' ~~Ignored~~.		* '''Value[0]:''' Reserved/should be zero.
	* '''Value[1]:''' Argv string pointer.		* '''Value[1]:''' Argv string pointer.
	* '''DefaultBehavior:''' Setting (argc == 1, argv[0] == "", argv[1] == NULL), or argv parsed in NSO0 fashion.		* '''DefaultBehavior:''' Setting (argc == 1, argv[0] == "", argv[1] == NULL), or argv parsed in NSO0 fashion.
Line 171:		Line 175:
	* '''Key:''' 8		* '''Key:''' 8
	* '''Value[0]:''' AppletResourceUserId		* '''Value[0]:''' AppletResourceUserId
	* '''Value[1]:''' ~~Ignored~~.		* '''Value[1]:''' Reserved/should be zero.

	==== Reserved9 ====		==== Reserved9 ====
	This ~~was originally stdiosockets which couldn't work long term in clean environments the way this was designed. Now~~ reserved for future use.		This key has been deleted/reserved for future use.

	==== ProcessHandle ====		==== ProcessHandle ====
Line 181:		Line 185:
	* '''Key:''' 10		* '''Key:''' 10
	* '''Value[0]:''' Process handle.		* '''Value[0]:''' Process handle.
	* '''Value[1]:''' ~~Ignored~~.		* '''Value[1]:''' Reserved/should be zero.

	==== LastLoadResult ====		==== LastLoadResult ====
Line 188:		Line 192:
	* '''Key:''' 11		* '''Key:''' 11
	* '''Value[0]:''' Result.		* '''Value[0]:''' Result.
	* '''Value[1]:''' ~~Ignored~~.		* '''Value[1]:''' Reserved/should be zero.

	==== AllocPages ====		==== AllocPages ====
Line 224:		Line 228:
	* '''Value[0]:''' Random data.		* '''Value[0]:''' Random data.
	* '''Value[1]:''' More random data.		* '''Value[1]:''' More random data.

			==== UserIdStorage ====
			This key is used to provide persistent storage space for the preselected user id when launching homebrew under an application that has an account selection screen.

			* '''Key''': 15
			* '''Value[0]:''' Pointer to a buffer containing enough space (16 bytes) to store a user id.
			* '''Value[1]:''' Reserved/should be zero.

			==== HosVersion ====
			This key provides the currently running version of Horizon OS.

			* '''Key''': 16
			* '''Value[0]:''' HOS version, formatted using libnx's [https://github.com/switchbrew/libnx/blob/master/nx/include/switch/runtime/hosversion.h#L11 MAKEHOSVERSION macro].
			* '''Value[1]:''' Reserved/should be zero.

Yellows8 at 02:51, 15 November 2018

2018-11-15T01:51:50Z

← Older revision		Revision as of 04:51, 15 November 2018
Line 15:		Line 15:

	'''NRO0:''' the homebrew loader puts X0=loader_config_ptr, X1=0xFFFFFFFFFFFFFFFF.		'''NRO0:''' the homebrew loader puts X0=loader_config_ptr, X1=0xFFFFFFFFFFFFFFFF.

			When X0 is non-zero and X1 is not 0xFFFFFFFFFFFFFFFF, the application must handle userland [[SVC#Exception_Handling\|exceptions]] (with the same entrypoint args described there). This must be done without corrupting registers for this (x8..x29).

			The loader should forward exceptions to the mapped NRO by just jumping to the NRO entrypoint, without the above register corruption. When the NRO is not mapped the loader can run: <code>svcReturnFromException(0xf801); while(1);</code>

	=== Loader Config ===		=== Loader Config ===

Fincs: Add RandomSeed

2018-10-17T22:24:38Z

Add RandomSeed

← Older revision		Revision as of 02:24, 18 October 2018
Line 74:		Line 74:

	* 13: [[#LockRegion]]: If present, must not be ignored		* 13: [[#LockRegion]]: If present, must not be ignored

			* 14: [[#RandomSeed]]

	==== EndOfList ====		==== EndOfList ====
Line 211:		Line 213:
	* '''Value[0]:''' Pointer to region to lock		* '''Value[0]:''' Pointer to region to lock
	* '''Value[1]:''' Size of region to lock		* '''Value[1]:''' Size of region to lock

			==== RandomSeed ====
			This key is used to provide an extra entropy source to the application (in addition to the seed provided by the kernel), allowing it to generate different pseudo-random numbers every time it's launched from within the same process.

			* '''Key''': 14
			* '''Value[0]:''' Random data.
			* '''Value[1]:''' More random data.

Yellows8: /* Reserved9 */

2018-10-17T13:14:13Z

Reserved9

← Older revision		Revision as of 17:14, 17 October 2018
Line 168:		Line 168:

	==== Reserved9 ====		==== Reserved9 ====
	This was originally stdiosockets which couldn't work long term the way this was designed. Now reserved for future use.		This was originally stdiosockets which couldn't work long term in clean environments the way this was designed. Now reserved for future use.

	==== ProcessHandle ====		==== ProcessHandle ====

Yellows8: /* AppletType */

2018-10-04T19:28:20Z

AppletType

← Older revision		Revision as of 23:28, 4 October 2018
Line 144:		Line 144:
	* '''Key:''' 7		* '''Key:''' 7
	* '''Value[0]:''' AppletType		* '''Value[0]:''' AppletType
	* '''Value[1]:''' ~~Ignored~~.		* '''Value[1]:''' AppletFlags

			AppletFlags ApplicationOverride: Use AppletType_Application instead of AppletType_SystemApplication, only when AppletType is SystemApplication. This should only be handled when AppletType_Application is properly supported where applet may have been previously initialized in the context of the current process, for AppletType_Application. This avoids breaking backwards-compatibility with apps which don't support AppletType_Application as previously described.

	enum LoaderConfigAppletType {		enum LoaderConfigAppletType {
Line 152:		Line 154:
	LoaderConfigAppletType_OverlayApplet = 3,		LoaderConfigAppletType_OverlayApplet = 3,
	LoaderConfigAppletType_SystemApplication = 4,		LoaderConfigAppletType_SystemApplication = 4,
			};

			enum LoaderConfigAppletFlags {
			LoaderConfigAppletFlags_ApplicationOverride = BIT(0),
	};		};

WinterMute at 09:21, 19 June 2018

2018-06-19T07:21:18Z

← Older revision		Revision as of 11:21, 19 June 2018
Line 65:		Line 65:
	* 8: [[#AppletWorkaround]]: If present, must not be ignored		* 8: [[#AppletWorkaround]]: If present, must not be ignored

	* 9: [[#~~StdioSockets~~]]		* 9: [[#Reserved9]]

	* 10: [[#ProcessHandle]]		* 10: [[#ProcessHandle]]
Line 160:		Line 160:
	* '''Value[0]:''' AppletResourceUserId		* '''Value[0]:''' AppletResourceUserId
	* '''Value[1]:''' Ignored.		* '''Value[1]:''' Ignored.

			==== Reserved9 ====
			This was originally stdiosockets which couldn't work long term the way this was designed. Now reserved for future use.

	==== ProcessHandle ====		==== ProcessHandle ====

WinterMute at 11:22, 18 June 2018

2018-06-18T09:22:25Z

@@ Line 160: / Line 160: @@
 * '''Value[0]:''' AppletResourceUserId
 * '''Value[1]:''' Ignored.
 ==== ProcessHandle ====

Misson20000: AllocPages & LockRegion

2018-02-24T03:37:18Z

AllocPages & LockRegion

@@ Line 70: / Line 70: @@
 * 11: [[#LastLoadResult]]
 ==== EndOfList ====
@@ Line 94: / Line 98: @@
 ==== OverrideHeap ====
-If the NRO loader has reserved some space in the heap for itself, the application must not manipulate the heap.
+If the NRO loader has reserved some space in the heap for itself, the application must not manipulate the heap. If an [[#AllocPages]] key is present, the region this points to should be accepted by <code>free_pages</code>.
 * '''Key:''' 3
@@ Line 182: / Line 186: @@
 * '''Value[0]:''' Result.
 * '''Value[1]:''' Ignored.