Revision as of 23:58, 21 November 2015

The NS (Nintendo User Interface Shell) system module is the first module launched from a CTR-NAND title after the FIRM processes are loaded (also see Bootloader). This module is launched by the pm process, with the titleID loaded from NS state(hard-coded TID initialized during applet TID-array initialization). NS first launches ErrDisp, then the menu. On retail the menu TID is loaded from NS state, while on dev/debug the menu TID is loaded from config. On dev-units if the menu TID block doesn't exist in config, NS will attempt to launch the alternate menu instead. The TID of the launched menu is then written to ACTIVEMENUTID. NS uses pm:app to launch titles.

NS will not trigger the fatal-error screen when launching the regular/alternate menu fails.

Like home menu NS is constantly running while the system is in 3DS-mode. When attempting to return to home-menu when the home-menu process isn't running(like when the process terminated/crashed), NS will trigger a fatal error.

Alternate menu

When launching the regular menu fails, NS will then attempt to launch the alternate menu. This title could be used as a recovery process, however it's normally not used after the factory.

At the factory for all 3DS systems, Test Menu is installed with this TID. On retail this title is eventually deleted during Factory Setup.

Auto-boot

After loading FIRM params and prior to launching ErrDisp/Home Menu, NS handles auto-booting titles. The same code called by APT:Reboot is used for launching FIRM here. When the UPDATEFLAG is set, NS will launch SAFE_MODE_FIRM with the application titleID set to the System Updater titleID for this region. When the UPDATEFLAG is not set, NS can auto-boot the following titles as well if 0x1FF80016 bit0 is set.

When bit1 and bit2 are value zero in 0x1FF80016, NS will launch the title specified by the FIRM parameters if the title-info is set. This FIRM launch is done after launching ErrDisp and Home Menu. Otherwise when 0x1FF80016 is value 2 and the output u8 from PTMSYSM command 0x08140000 is value 0, NS will boot the title specified from the TWL TLNC block from FIRMparams+0x300. This is the same TLNC block which DSi titles wrote to RAM+0x300 for launching other titles via the launcher title. When handling the TLNC block, NS will boot the 3DS System Settings title when the TLNC titleID is the DSi System Settings titleID(the region field in the TLNC TID is not checked/used). When the TLNC titleID is not System Settings, NS will convert the input DSi titleID-high to the 3DS TWL titleID-high(tidhigh = (TLNCtidhigh & 0x7FFF) | 0x48000), then launch TWL_FIRM to run the title. NS does not support launching from gamecard via TLNC.

NS Workaround

A "ns_workaround" was added in NS to workaround the flaw added with 5.0.0-11. When NS is loading before launching any ARM11 processes and certain Configuration Memory fields are set, NS will launch AM then use command AM:InstallNATIVEFIRM. NS will then execute the code called by APT:StartNewestHomeMenu, the code related to APT:PrepareToStartNewestHomeMenu is not executed here.

NS will only execute this code-path when 0x1FF80016 is value zero, when KERNEL_VERSIONMAJOR is value 2, and when KERNEL_VERSIONMINOR is less than 35. Therefore, this code-path is only executed when the running NATIVE_FIRM version is prior to 5.0.0-11.

NS Service "ns:s"

Command Header	Available since system version	Description
0x000100C0	1.0.0-0 - 2.0.0-2	LaunchFIRM
0x000200C0	1.0.0-0 - 2.0.0-2	LaunchTitle
0x0003....	1.0.0-0 - 2.0.0-2	Wrapper for PMApp command 0x00030080.
0x0004....	1.0.0-0 - 2.0.0-2	Wrapper for PMApp command 0x000500C0.
0x000500C0	1.0.0-0 - 2.0.0-2	LaunchApplicationFIRM
0x00060042	1.0.0-0 - 2.0.0-2	SetFIRMParams4A0
0x00070042	1.0.0-0 - 2.0.0-2	CardUpdateInitialize
0x00080000	1.0.0-0 - 2.0.0-2	This shuts down the gamecard system update interface: the shared memory is unmapped, the CFA archive is closed, state is cleared, etc.
0x00090000	1.0.0-0 - 2.0.0-2	Gamecard system update related.
0x000A0000	1.0.0-0 - 2.0.0-2	Gamecard system update related.
0x000B....	1.0.0-0 - 2.0.0-2	Gamecard system update related.
0x000C....	1.0.0-0 - 2.0.0-2	Gamecard system update related.
0x000D0140	1.0.0-0 - 2.0.0-2	SetFIRMParams4B0
0x000E0000	1.0.0-0 - 2.0.0-2	ShutdownAsync
0x000F0000	1.0.0-0 - 2.0.0-2	This calls APT:AppletUtility with fixed input params.
0x00100180	1.0.0-0 - 2.0.0-2	RebootSystem
0x0011....	1.0.0-0 - 2.0.0-2	TerminateProcessTID
0x0012....	?	Uses pm:app cmdA&B
0x00130000	?	?
0x00140042	?	?
0x00150140	?	LaunchApplication : unlike LaunchTitle, this will do a "proper" app launch, using the update title if present. It seems to set proper internal states, like APT:PrepareToStartApplication and APT:StartApplication would.
0x00160000	8.0.0-18	This triggers a hw-reboot.

The maximum sessions that can be used with this service is two, therefore only two processes can use this service at the same time.

NS Service "ns:p"

This was added with 3.0.0-5. The PTM sysmodule connects to this service, and syncs whenever ptm:s GetShellState() changes.

NS Service "ns:c"

This was added with 5.0.0-11, it's unknown what this is used for.

APT Services

Command Header	Available since system version	Accessible with APT:U	Description
0x00010040		Yes	GetLockHandle
0x00020080		See here.	Initialize
0x00030040		Yes	Enable
0x00040040		Yes	Finalize
0x00050040		Yes	GetAppletManInfo
0x00060040		Yes	GetAppletInfo
0x00070000		Yes	GetLastSignaledAppletId
0x00080000		Yes	CountRegisteredApplet
0x00090040		Yes	IsRegistered
0x000A0040		Yes	GetAttribute
0x000B0040		Yes	InquireNotification
0x000C0104		Yes	SendParameter
0x000D0080		Yes	ReceiveParameter
0x000E0080		Yes	GlanceParameter
0x000F0100		Yes	CancelParameter
0x001000C2		Yes	DebugFunc
0x001100C0		Yes	MapProgramIdForDebug
0x00120040		Yes	SetHomeMenuAppletIdForDebug
0x00130000		Yes	GetPreparationState
0x00140040		Yes	SetPreparationState
0x00150140		No	PrepareToStartApplication
0x00160040		Yes	PreloadLibraryApplet
0x00170040		Yes	FinishPreloadingLibraryApplet
0x00180040		Yes	PrepareToStartLibraryApplet
0x00190040		Yes	PrepareToStartSystemApplet
0x001A0000		Yes	PrepareToStartNewestHomeMenu
0x001B00C4		Yes	StartApplication
0x001C0000		Yes	WakeupApplication
0x001D0000		Yes	CancelApplication
0x001E0084		Yes	StartLibraryApplet
0x001F0084		Yes	StartSystemApplet
0x00200044		Yes	StartNewestHomeMenu
0x00210000		No	OrderToCloseApplication
0x00220040		Yes	PrepareToCloseApplication
0x00230040		Yes	PrepareToJumpToApplication
0x00240044		Yes	JumpToApplication
0x002500C0		Yes	PrepareToCloseLibraryApplet
0x00260000		Yes	PrepareToCloseSystemApplet
0x00270044		Yes	CloseApplication
0x00280044		Yes	CloseLibraryApplet
0x00290044		Yes	CloseSystemApplet
0x002A0000		Yes	OrderToCloseSystemApplet
0x002B0000		Yes	PrepareToJumpToHomeMenu
0x002C0044		Yes	JumpToHomeMenu
0x002D0000		Yes	PrepareToLeaveHomeMenu
0x002E0044		Yes	LeaveHomeMenu
0x002F0040		Yes	PrepareToLeaveResidentApplet This is stubbed: this just returns 0.
0x00300044		Yes	LeaveResidentApplet This is stubbed: this just returns 0 after verifying the cmd/translate headers.
0x00310100		Yes	PrepareToDoApplicationJump
0x00320084		Yes	DoApplicationJump
0x00330000		Yes	GetProgramIdOnApplicationJump
0x00340084		Yes	SendDeliverArg
0x00350080		Yes	ReceiveDeliverArg
0x00360040		Yes	LoadSysMenuArg
0x00370042		Yes	StoreSysMenuArg
0x00380040		Yes	PreloadResidentApplet This is stubbed: this just returns 0.
0x00390040		Yes	PrepareToStartResidentApplet This is stubbed: this just returns 0.
0x003A0044		Yes	StartResidentApplet This is stubbed: this just returns 0 after verifying the cmd/translate headers.
0x003B0040		Yes	CancelLibraryApplet
0x003C0042		Yes	SendDspSleep
0x003D0042		Yes	SendDspWakeUp
0x003E0080		Yes	ReplySleepQuery
0x003F0040		Yes	ReplySleepNotificationComplete
0x00400042		Yes	SendCaptureBufferInfo
0x00410040		Yes	ReceiveCaptureBufferInfo
0x00420080		Yes	SleepSystem
0x00430040		Yes	NotifyToWait
0x00440000		Yes	GetSharedFont
0x00450040		Yes	GetWirelessRebootInfo
0x00460104		Yes	Wrap
0x00470104		Yes	Unwrap
0x00480100		No	GetProgramInfo
0x00490180		No	Reboot
0x004A0040		Yes	GetCaptureInfo
0x004B00C2		Yes	AppletUtility
0x004C0000		Yes	SetFatalErrDispMode
0x004D0080		Yes	GetAppletProgramInfo
0x004E0000		Yes	HardwareResetAsync
0x004F0080	2.2.0-X	Yes	SetApplicationCpuTimeLimit
0x00500040	2.2.0-X	Yes	GetApplicationCpuTimeLimit
0x00510080	3.0.0-5	?	Uses pm:app cmdB
0x00520104	4.0.0-7	?	Wrap1
0x00530104	4.0.0-7	?	Unwrap1
0x00540040	5.0.0-11	?	?
0x00550040	7.0.0-13	Yes	This writes the input u8 to a NS state field.
0x00560000	7.0.0-13	Yes	This returns an u8 NS state field(which can be set by cmd 0x00550040), at cmdreply+8.
0x00570044	7.0.0-13	?	WakeupApplication2?
0x00580002	7.0.0-13	Yes	GetProgramID
0x01010000	8.0.0-18	Yes	This writes an output u8 to cmdreply indexword[2]. This uses PTMSYSM:CheckNew3DS. When a certain NS state field is non-zero, the output value is zero, otherwise the output is from PTMSYSM:CheckNew3DS. Normally this NS state field is zero, however this state field is set to 1 when APT:PrepareToStartApplication is used with flags bit8 is set.
0x01020000	8.0.0-18	Yes	Wrapper for PTMSYSM:CheckNew3DS.
0x01030000	8.0.0-18	Yes	?
0x01040000	8.0.0-18	?	?

These "APT:U" and "APT:S" NS services can handle launching titles/"applets", these services handle signaling for home/power button as well. Only one session for either APT service can be open at a time, normally processes close the service handle immediately once finished using the service. The commands for APT:U and APT:S are exactly the same, however certain commands are only accessible with APT:S(NS module will call svcBreak when the command isn't accessible).

Applets returning to home-menu first use commands APT:PrepareToJumpToHomeMenu and APT:JumpToHomeMenu, followed by these commands to launch home-menu: APT:PrepareToStartSystemApplet and APT:StartSystemApplet. APT:PrepareToStartSystemApplet and APT:StartSystemApplet are also used for launching the Internet Browser, the camera applet, etc.

Processes launch applications via home-menu, not directly with APT:PrepareToStartApplication and APT:StartApplication. Regular applications can't directly launch applications since APT:StartApplication launches the process without terminating the currently running application.

APT:PrepareToDoApplicationJump and APT:DoApplicationJump are used by applications, for launching native/<non-NATIVE_FIRM> applications. These commands notify Home Menu that title launching needs done, Home Menu does the actual title launching via NS commands.

AppletAttr

Bits	Description
0-2	AppletPos
3	Manually Acquire/Release GPU Rights
4	Manually Acquire/Release DSP Rights
5	?

DisplayBufferMode

Value	Description
0	FORMAT_R8G8B8A8
1	FORMAT_R8G8B8
2	FORMAT_R5G6B5
3	FORMAT_R5G5B5A1
4	FORAMT_R4G4B4A4
0xFFFFFFFF	FORMAT_UNIMPORTABLE

This is the same mapping as used for the GPU framebuffer color formats.

AppletPos

Value	Description
-1	POS_NONE
0	POS_APP
1	POS_APPLIB
2	POS_SYS
3	POS_SYSLIB
4	POS_RESIDENT

QueryReply

Value	Description
0	REPLY_REJECT
1	REPLY_ACCEPT
2	REPLY_LATER

Notification

Value	Description
0	NOTIFICATION_NONE
1	NOTIFICATION_HOME_BUTTON_1
2	NOTIFICATION_HOME_BUTTON_2
3	NOTIFICATION_SLEEP_QUERY
4	NOTIFICATION_SLEEP_CANCELED_BY_OPEN
5	NOTIFICATION_SLEEP_ACCEPTED
6	NOTIFICATION_SLEEP_AWAKE
7	NOTIFICATION_SHUTDOWN
8	NOTIFICATION_POWER_BUTTON_CLICK
9	NOTIFICATION_POWER_BUTTON_CLEAR
10	NOTIFICATION_TRY_SLEEP
11	NOTIFICATION_ORDER_TO_CLOSE

Command

Value	Description
0	COMMAND_NONE
1	COMMAND_WAKEUP
2	COMMAND_REQUEST
3	COMMAND_RESPONSE
4	COMMAND_EXIT
5	COMMAND_MESSAGE
6	COMMAND_HOME_BUTTON_SINGLE
7	COMMAND_HOME_BUTTON_DOUBLE
8	COMMAND_DSP_SLEEP
9	COMMAND_DSP_WAKEUP
10	COMMAND_WAKEUP_BY_EXIT
11	COMMAND_WAKEUP_BY_PAUSE
12	COMMAND_WAKEUP_BY_CANCEL
13	COMMAND_WAKEUP_BY_CANCELALL
14	COMMAND_WAKEUP_BY_POWER_BUTTON_CLICK
15	COMMAND_WAKEUP_TO_JUMP_HOME
16	COMMAND_REQUEST_FOR_SYS_APPLET
17	COMMAND_WAKEUP_TO_LAUNCH_APPLICATION
65536	COMMAND_FINALIZE

AppletPreparationState

Value	Description
0	NO_PREPARATION
1	PREPARED_TO_LAUNCH_APP
2	PREPARED_TO_CLOSE_APP
3	PREPARED_TO_FORCE_TO_CLOSE_APP
4	PREPARED_TO_PRELOAD_APPLIB
5	PREPARED_TO_LAUNCH_APPLIB
6	PREPARED_TO_CLOSE_APPLIB
7	PREPARED_TO_LAUNCH_SYS
8	PREPARED_TO_CLOSE_SYS
9	PREPARED_TO_PRELOAD_SYSLIB
10	PREPARED_TO_LAUNCH_SYSLIB
11	PREPARED_TO_CLOSE_SYSLIB
12	PREPARED_TO_LAUNCH_RESIDENT
13	PREPARED_TO_LEAVE_RESIDENT
14	PREPARED_TO_DO_HOMEMENU
15	PREPARED_TO_LEAVE_HOMEMENU
16	PREPARED_TO_START_RESIDENT
17	PREPARED_TO_DO_APP_JUMP
18	PREPARED_TO_FORCE_TO_CLOSE_SYS
19	PREPARED_TO_LAUNCH_OTHER_SYS
20	PREPARED_TO_JUMP_TO_APP

"APT:A" Service

This was added with 7.0.0-X. Official apps built with the CTRSDK for system-version >=7.0.0-X normally use the "APT:A" service instead of "APT:U". Those processes also have "APT:A" instead of "APT:U" in the service-access-control. It's unknown whether there's anything which is only accessible via "APT:A".

Applets

NS module does not verify that the input appID for the APT service cmds are correct for that type of command. For example, a process-launch of a SystemApplet via LibraryApplet commands works fine(minus the launched-process side of APT probably).

System Applets

On Old3DS there could only be one applet here(Home Menu, Internet Browser, Friend-List, etc) with programID-high 00040030 running at a time. On Old3DS when directly launching one of these 00040030 applets with Home Menu, the Home Menu process will terminate once the process is launched. On Old3DS when returning to Home Menu from that launched process, the Home Menu process is launched again.

On New3DS the Home Menu process is still running/in-memory, while another system-applet is running. On New3DS it appears that the Home Menu process is terminated+relaunched, when another system-applet terminated without exiting with APT properly.

Library Applets

Library applets can be launched by applications and regular applets. These library applets render to the screen(s) when running, etc. For example, this includes swkbd for text input. See the below appIDs in the 0x2XX range, the actual appID used is 0x4XX however.

Input data can be sent to the library applet via the NS parameter buffer, and/or with shared-memory with a shared-mem handle sent to the library applet. Output data from the library applet can be received by APT:ReceiveParameter, the library applet can also use the specified shared-mem for output too.

AppIDs

AppID	Description
0x101	Home Menu (menu)
0x103	Alternate Menu
0x110	Camera applet (CtrApp)
0x112	Friends List applet (friend)
0x113	Game Notes applet (Cherry)
0x114	Internet Browser (spider/SKATER)
0x115	Instruction Manual applet
0x116	Notifications applet (newslist)
0x117	Miiverse applet (olv)
0x118	Miiverse posting applet (solv3)
0x119	Amiibo settings (cabinet)
0x201	Software Keyboard (swkbd) (?)
0x202	Mii Selector (appletEd) (?)
0x204	Photo Selector (PNOTE_AP) (?)
0x205	Sound Selector (SNOTE_AP) (?)
0x206	Error Display (error) (?)
0x207	eShop applet (mint) (?)
0x208	Circle Pad Pro Calibrator (extrapad) (?)
0x209	Notepad (memolib) (?)
0x300	Application
0x301	eShop (tiger)
0x401	Software Keyboard (swkbd)
0x402	Mii Selector (appletEd)
0x404	Photo Selector (PNOTE_AP)
0x405	Sound Selector (SNOTE_AP)
0x406	Error Display (error)
0x407	eShop applet (mint)
0x408	Circle Pad Pro Calibrator (extrapad)
0x409	Notepad (memolib)
0xF10	ProgramID: 0004003000008900.
0xF11	ProgramID: 000400000FFFFD00.
0xF12	ProgramID: 000400000FFFFC00.
0xF13	ProgramID: 000400000FFFFB00.
0xF14	ProgramID: 000400000FFFF900.
0xF15	ProgramID: 000400000FFFF800.
0xF16	ProgramID: 000400000FFFF700.
0xF17	ProgramID: 000400000FFFF600.
0xF18	ProgramID: 000400000FFFF500.

These AppIDs are all for NAND titles, except for 0x300. AppIDs in the 0x1XX range are applets(programID-high 00040030), and the AppIDs in the 0x2XX range are "system libraries"(programID-high 00040030). The 0xFXX AppID range is for development NAND applications, these are not available for retail.

Note that at some point the total AppID entry count was changed from 28 to 27.

Difference between revisions of "NS and APT Services"