LaunchFlags

On 5.0.0+, the LaunchFlag enum looks like this:

Bit Mask Name
0 1 LaunchFlags_SignalOnExit
1 2 LaunchFlags_SignalOnStart
2 4 LaunchFlags_SignalOnCrash
3 8 LaunchFlags_SignalOnDebug
4 0x10 LaunchFlags_StartSuspended
5 0x20 LaunchFlags_DisableAslr

Prior to system version 5.0.0, the LaunchFlag enum had its entries in a different order:

Bit Mask Name
0 1 LaunchFlags_SignalOnExit
1 2 LaunchFlags_StartSuspended
2 4 LaunchFlags_SignalOnCrash
3 8 LaunchFlags_DisableAslr
4 0x10 LaunchFlags_SignalOnDebug
5 0x20 [2.0.0+] LaunchFlags_SignalOnStart

ProcessEventInfo

Offset Size Description
0x0 0x4 ProcessEvent
0x4 0x4 Padding/Reserved
0x8 0x8 ProcessId

Process Tracker thread

PM has a separate thread that is waiting for synchronization on process handles.

State changes

When the kernel signals a process handle, it uses svcResetSignal on the process handle and then it uses svcGetProcessInfo to read out the ProcessEvent.

If the process moved from non-crashed -> ProcessEvent_Crashed it clears 4 in process flags.

If process flags has mask 8 set:

  • If event is ProcessEvent_Running or ProcessEvent_DebugDetached, it clears 0x20 and sets 0x10 in process flags, and signals the ProcessEventWaiter handle.
  • If event is ProcessEvent_DebugSuspended, it sets 0x20 and 0x10 in process flags, and signals the ProcessEventWaiter handle.

[2.0.0+] If new state is ProcessEvent_DebugDetached, and process flags has 0x80 set, it sets mask 0x100 and signals the ProcessEventWaiter handle.

If process flags has mask 1 set:

  • If new state is ProcessEvent_Exited, it signals the ProcessEventWaiter handle.

If mask 1 is not set, it immediately does what is otherwise done by the #FinalizeDeadProcess command.

Process launch

This thread can also be triggered by the pm:shell #LaunchProcess cmd.

It uses ldr:pm GetProgramInfo with the supplied title-id.

If ApplicationType == Application, it goes through the process list and errors if any has mask 0x40 set. Thus you can only run one Application at a time.

Resource limits for the process is selected by ApplicationType.

It calls ldr:pm RegisterTitle, then ldr:pm CreateProcess, then fsp-pr RegisterTitle, then sm:m RegisterTitle.

[1.0.0] The second input argument for ldr:pm CreateProcess is (launch_flags >> 2) & 3.

[2.0.0+] The second input argument for ldr:pm CreateProcess is ((launch_flags >> 2) & 2) | ((launch_flags >> 1) != 1).

If launch_flags has mask 1 set, it sets mask 1 in process flags.

If launch_flags has mask 0x10 set, it sets mask 8 in process flags.

[2.0.0+] If launch_flags has mask 0x20 set, it sets mask 0x80 in process flags.

[2.0.0+] The launch_flags mask 0x10 and 0x20 will be ignored unless ((*(u8*) (info_output+2)) & 4) is set.

If ApplicationType == Application, it sets 0x40 in the process flags, and signals the event returned by #EnableDebugForApplication. svcStartProcess is not called in this case, it has to be done manually by the #StartProcess command.

If the title-id matches the title-id given in #EnableDebugForTitleId, then svcStartProcess is not called. Instead process remains in suspended state, and has to be done manually by the #StartProcess command.

If launch_flags has mask 2 set, svcStartProcess is skipped.

Finally it does svcStartProcess on the process handle that was returned by ldr:pm CreateProcess, and sets process state to 2.

The arguments for svcStartProcess are process_handle, *(u8*)info_output, *(u8*)(info_output+1), *(u32*)(info_output+4).

Thus at the point of launch, the pid is already registered in ldr, fs, sm, and pm.

pm:bm

This is "nn::pm::detail::IBootModeInterface".

Cmd Name
0 GetBootMode
1 SetMaintenanceBoot

pm:dmnt

This is "nn::pm::detail::IDebugMonitorInterface".

Cmd Name
[1.0.0-4.1.0] 0 #GetModuleIdList
0 ([1.0.0-4.1.0] 1) #GetJitDebugProcessIdList
1 ([1.0.0-4.1.0] 2) #StartProcess
2 ([1.0.0-4.1.0] 3) #GetProcessId
3 ([1.0.0-4.1.0] 4) #HookToCreateProcess
4 ([1.0.0-4.1.0] 5) #GetApplicationProcessId
5 ([1.0.0-4.1.0] 6) #HookToCreateApplicationProcess
[6.0.0+] 6 #ClearHook


GetModuleIdList

Stubbed in all versions of retail firmware (just returns 0).

[2.0.0+] When output buffer size is > INT_MAX, returns ResultInvalidSize.

GetJitDebugProcessIdList

Returns an array of pids of all processes that have mask 4 set in process flags.

[2.0.0+] When output buffer size is > INT_MAX, returns ResultInvalidSize.

StartProcess

Takes a pid. Last process event must be ProcessEvent_Created or ProcessEvent_DebugAttached.

Then it uses svcStartProcess(process_handle, u8, u8, u32) with args coming from ldr:pm GetProgramInfo.

After that, it sets last process state to ProcessEvent_DebugDetached.

GetProcessId

Takes a title-id and returns the pid.

HookToCreateProcess

Takes a title-id of the program to debug. Sets this to a global field.

Next time it gets launched it will be handled differently.

Returns an event handle that is signaled when the requested title is about to be launched.

GetApplicationProcessId

Returns the pid of the application process.

HookToCreateApplicationProcess

Does *not* take a specific title-id as input.

Returns an event handle that is triggered for application titles.

ClearHook

Takes in a u32 of bitflags.

Disables debugging/clears the globally specified tid if bit 0 is set, disables debugging/clears the next application if bit 1 is set.

pm:info

This is "nn::pm::detail::IInformationInterface".

Cmd Name
0 #GetProgramId

GetProgramId

Takes a pid and returns the title-id associated with the process.

pm:shell

This is "nn::pm::detail::IShellInterface".

Cmd Name
0 #LaunchProgram
1 TerminateProcess
2 TerminateProgram
3 GetProcessEventHandle
4 #GetProcessEventInfo
([1.0.0-4.1.0] 5) #CleanupProcess
([1.0.0-4.1.0] 6) #ClearJitDebugOccured
5 ([1.0.0-4.1.0] 7) #NotifyBootFinished
6 ([1.0.0-4.1.0] 8) #GetApplicationProcessIdForShell
7 ([4.0.0-4.1.0] 9) [4.0.0+] #BoostSystemMemoryResourceLimit
8 [7.0.0+] #BoostApplicationThreadResourceLimit
9 [8.0.0+] #GetBootFinishedEventHandle

LaunchProgram

Takes an u32 launch_flags and ProgramLocation. Returns the u64 title PID.

See #Process launch.

GetProcessEventInfo

Returns 1 if flags has mask 2 set.

Returns 2 if flags has mask 1 set and state is 6.

Returns 3 if flags has mask 0x10 set and not 0x20.

Returns 4 if flags has mask 0x30 set.

[2.0.0+] returns 5 if state >= 2 and flags has mask 0x100 set.

Returns 0 if process is not found.

CleanupProcess

Takes a pid as input. If the process with pid has the state "dead", it unregisters the pid in fsp:pr, sm:m, and ldr:pm.

Then it removes the process from PMs internal linked-list of active processes.

[5.0.0+] This command was removed.

ClearJitDebugOccured

Takes a pid as input. Clears 0x10 from process flags.

[5.0.0+] This command was removed.

NotifyBootFinished

This launches the boot2 title.

[4.0.0+] When booting from SafeMode Firmware, instead of boot2, this launches the following titles in order:

  • 0100000000000009 (settings)
  • 0100000000000006 (usb)
  • 010000000000001D (pcie)
  • 0100000000000007 (tma)
  • 010000000000001F (ns)
  • 0100000000000015 (lm)
  • 0100000000000010 (ptm)
  • 0100000000000016 (wlan)
  • 0100000000000012 (bsdsockets)
  • 010000000000000F (nifm)
  • 0100000000000024 (ssl)
  • 0100000000000025 (nim)
  • 0100000000000031 (glue)
  • 010000000000003D (safemode)

GetApplicationProcessIdForShell

Loops through the internal linked-list of processes, looks for mask 0x40 set in process flags. Returns pid of first such entry.

BoostSystemMemoryResourceLimit

Takes an u64 mem_size as input. If the desired memory size doesn't exceed an internal limit (imposed by PM by looking at the MemoryArrange ConfigItem), PM calls svcSetResourceLimitLimitValue to set the new LimitableResource_Memory value.

This is used directly by ns:am2 BoostSystemMemoryResourceLimit.

BoostApplicationThreadResourceLimit

Calls svcSetResourceLimitLimitValue to increase the limit on application threads by an amount calculated dynamically during setup.

This function can only increase the limit once, on further calls it will call svcSetResourceLimitLimitValue with the same value it called the first time.

On normal 7.0.0 retail firmware, this will double the limit on application threads from 0x60 to 0xC0.

GetBootFinishedEventHandle

This function returns a handle to an event that is signaled when #NotifyBootFinished is called.

However, this is only used/available in safe mode; in normal, non-safe FIRM, the implementation for this command just does "abort();".