Nintendo Switch Brew

PGL services: Difference between revisions

← Older edit
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
PGL (Program Launcher) is a sysmodule designed for encapsulating all program launching / management logic.
PGL (Program Launch) is a sysmodule designed for encapsulating all program launching / management logic.


The core logic of this sysmodule was previously encapsulated by the ns:dev interface (and the nn.nssrv.ProcessLaunchControlTask thread in particular).
The core logic of this sysmodule was previously encapsulated by the ns:dev interface (and the nn.nssrv.ProcessLaunchControlTask thread in particular).
Line 8: Line 8:
! Cmd || Name
! Cmd || Name
|-
|-
| 0 || [[#LaunchProgram]]
| 0 || [[#LaunchProgram|LaunchProgram]]
|-
|-
| 1 || [[#TerminateProcess]]
| 1 || [[#TerminateProcess|TerminateProcess]]
|-
|-
| 2 || [[#LaunchProgramFromHost]]
| 2 || [[#LaunchProgramFromHost|LaunchProgramFromHost]]
|-
|-
| 4 || [[#GetHostContentMetaInfo]]
| 4 || [[#GetProgramLaunchPropertyFromHost|GetProgramLaunchPropertyFromHost]]
|-
|-
| 5 || [[#GetApplicationProcessId]]
| 5 || [[#GetRunningApplicationProcessId|GetRunningApplicationProcessId]]
|-
|-
| 6 || [[#BoostSystemMemoryResourceLimit]]
| 6 || [[#BoostSystemMemoryResourceLimit|BoostSystemMemoryResourceLimit]]
|-
|-
| 7 || [[#IsProcessTracked]]
| 7 || [[#IsRunningProcess|IsRunningProcess]]
|-
|-
| 8 || [[#EnableApplicationCrashReport]]
| 8 || [[#EnableApplicationCrashReport|EnableApplicationCrashReport]]
|-
|-
| 9 || [[#IsApplicationCrashReportEnabled]]
| 9 || [[#IsApplicationCrashReportEnabled|IsApplicationCrashReportEnabled]]
|-
|-
| 10 || [[#EnableApplicationAllThreadDumpOnCrash]]
| 10 || [[#EnableApplicationAllThreadDumpOnCrash|EnableApplicationAllThreadDumpOnCrash]]
|-
|-
| 12 || [[#TriggerSnapShotDumper]]
| 11 || [19.0.0+] GetProcessId
|-
|-
| 20 || [[#GetShellEventObserver]]
| 12 || [10.0.0-11.0.1] [[#TriggerSnapShotDumper|TriggerSnapShotDumper]]
|-
|-
| 21 || [11.0.0+]
| 20 || [[#CreateShellEvent|CreateShellEvent]]
|}
 
= LaunchFlags =
 
The LaunchFlags enum looks like this:
 
{| class=wikitable
! Bit || Mask || Name
|-
| 0 || 1 || LaunchFlags_EnableDetailedCrashReport
|-
| 1 || 2 || LaunchFlags_EnableCrashReportScreenShotForProduction
|-
| 2 || 4 || LaunchFlags_EnableCrashReportScreenShotForDevelop
|-
|}
 
= SnapShotDumpType =
 
The SnapShotDumpType enum looks like this:
 
{| class=wikitable
! Value || Name
|-
| 0 || SnapShotDumpType_None
|-
| 1 || SnapShotDumpType_Auto
|-
| 2 || SnapShotDumpType_Full
|-
|-
| 21 || [11.0.0-11.0.1]
|}
|}
== ContentMetaInfo ==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| [[NCM_services#ProgramId|ProgramId]]
|-
| 0x8
| 0x4
| Version
|-
| 0xC
| 0x1
| ContentType
|-
| 0xD
| 0x1
| ID Offset
|-
| 0xE
| 0x2
| Padding
|}


== LaunchProgram ==
== LaunchProgram ==
Takes a [[NCM_services#ProgramLocation|ProgramLocation]], a u32 [[Process_Manager_services#LaunchFlags]] pm launch_flags, and a u8 [[#LaunchFlags|LaunchFlags]] pgl launch_flags.
Takes an input [[NCM_services#ProgramLocation|ProgramLocation]], an input [[Process_Manager_services#LaunchProgramFlags|LaunchProgramFlags]], an input [[#LaunchFlags]] and an input [[Process_Manager_services#ProcessEnvironment|ProcessEnvironment]]. Returns an output u64 '''ProcessId'''.


This calls pm:shell->LaunchProgram with the program location and the input launch flags. If jit_debug!enable_jit_debug is true, LaunchFlags_SignalOnCrash is ORRd into the flags sent to PM.
This calls pm:shell->LaunchProgram with the program location and the input launch flags. If jit_debug!enable_jit_debug is true, [[Process_Manager_services#LaunchProgramFlags|NotifyException]] is ORRd into the flags sent to PM.


This then creates a new process tracking structure for the new process id and with the pgl launch flags. If an empty process struct is not allocated from the 0x20 slab heap, pgl aborts.
This then creates a new process tracking structure for the new process id and with the pgl launch flags. If an empty process struct is not allocated from the 0x20 slab heap, pgl aborts.
Line 103: Line 46:
If settings::GetDebugModeFlag() returns 1, then LaunchFlags_EnableCrashReportScreenShotForDevelop is used to enable crash report screenshot, otherwise LaunchFlags_EnableCrashReportScreenShotForProduction is used.
If settings::GetDebugModeFlag() returns 1, then LaunchFlags_EnableCrashReportScreenShotForDevelop is used to enable crash report screenshot, otherwise LaunchFlags_EnableCrashReportScreenShotForProduction is used.


It returns a u64 process id.
== TerminateProcess ==
Takes an input u64 '''ProcessId'''. No output.


== TerminateProcess ==
This just calls pm:shell->TerminateProcess with the input process id.
This just calls pm:shell->TerminateProcess with the input process id.
== GetShellEventObserver ==
No input. Returns an [[#IEventObserver]].


== LaunchProgramFromHost ==
== LaunchProgramFromHost ==
Takes an input [[Process_Manager_services#LaunchProgramFlags|LaunchProgramFlags]] and a MapAlias input buffer containing a [[NCM_services#Path|ContentPath]]. Returns an output u64.


This takes an input u32 [[Process_Manager_services#LaunchFlags]] pm launch_flags and a MapAlias input buffer "content path".
The content path must be to an ".nsp" file or a ".nspd" folder. "*.nspd/program0.ncd/" is also allowed. The content path must start with "@Host".
 
The content path must be to an ".nsp" file or a ".nspd" folder. "*.nspd/program0.ncd/" is also allowed.


This calls fs::MountApplicationPackage on the input content path, and reads content meta from "meta0.ncd" or ".cnmt.nca" extension folder/file depending on whether it is a .nspd or .nsp content path.
This calls fs::MountApplicationPackage on the input content path, and reads content meta from "meta0.ncd" or ".cnmt.nca" extension folder/file depending on whether it is a .nspd or .nsp content path.


A location resolver for the Host storage is opened, and EraseProgramRedirection is called for the parsed program id.
A location resolver for the Host storage is opened, and EraseProgramRedirection is called for the parsed program id. RedierectProgramPath is then called for the program ID to set it to the input content path.


RedierectProgramPath is then called for the program ID to set it to the input content path.
This then calls the implementation function for [[#LaunchProgram]] with the input pm launch flags and pgl launch flags = 0. If [[SPL_services#IsDevelopment]] is false, [[Loader_services|Loader]] will abort.


This then calls the implementation function for [[#LaunchProgram]] with the input pm launch flags and pgl launch flags = 0.
== GetProgramLaunchPropertyFromHost ==
Takes a MapAlias input buffer containing a [[NCM_services#Path|ContentPath]]. Returns an output [[#ProgramLaunchProperty]].


== GetHostContentMetaInfo ==
== GetRunningApplicationProcessId ==
No input. Returns an output u64 '''ProcessId'''.


This takes an input MapAlias buffer "content path", and does the same parsing as [[#LaunchProgramFromHost]].
This calls pm:shell->GetApplicationProcessIdForShell, and returns the output process id. Error 0x6E4 is returned when there is no application process.


Instead of launching the program, it instead returns an 0x10 output [[#ContentMetaInfo]] from the parsed info.
== BoostSystemMemoryResourceLimit ==
 
Takes an input u64. No output.  
== GetApplicationProcessId ==
 
This calls pm:shell->GetApplicationProcessIdForShell, and returns the output process id.
 
Error 0x6E4 is returned when there is no application process.


== BoostSystemMemoryResourceLimit ==
This uses the u64 as input to pm:shell->BoostSystemMemoryResourceLimit.


This takes in a u64 mem_size, and uses it as input to pm:shell->BoostSystemMemoryResourceLimit
== IsRunningProcess ==
Takes an input u64 '''ProcessId'''. Returns an output bool (padded to u32).


== EnableApplicationCrashReport ==
== EnableApplicationCrashReport ==
 
Takes an input bool (padded to u32). No output.  
Takes an input boolean "enable".


This calls pm:shell->GetApplicationProcessId. If the returned process ID is tracked, this sets or clears bit 1 (value 0x2) in the tracked process's flags.
This calls pm:shell->GetApplicationProcessId. If the returned process ID is tracked, this sets or clears bit 1 (value 0x2) in the tracked process's flags.
Line 154: Line 90:


== IsApplicationCrashReportEnabled ==
== IsApplicationCrashReportEnabled ==
No input. Returns an output bool (padded to u32).


This returns the value of the bit set or cleared by [[#EnableApplicationCrashReport]]
This returns the value of the bit set or cleared by [[#EnableApplicationCrashReport]].


== EnableApplicationAllThreadDumpOnCrash ==
== EnableApplicationAllThreadDumpOnCrash ==
 
Takes an input bool (padded to u32). No output.
Takes an input boolean "enable".


This calls pm:shell->GetApplicationProcessId. If the returned process ID is tracked, this sets or clears bit 3 (value 0x8) in the tracked process's flags.
This calls pm:shell->GetApplicationProcessId. If the returned process ID is tracked, this sets or clears bit 3 (value 0x8) in the tracked process's flags.
Line 172: Line 108:


== TriggerSnapShotDumper ==
== TriggerSnapShotDumper ==
 
Takes an input [[#SnapShotDumpType]] and a MapAlias input buffer. No output.
This takes an input 32 "SnapShotDumpType" and an input MapAliasBuffer "argument".


This manually invokes the same function to launch the SnapShotDumper program (0100000000002071) as is called automatically when a process crashes and jit_debug!enable_jit_debug is 1.
This manually invokes the same function to launch the SnapShotDumper program (0100000000002071) as is called automatically when a process crashes and jit_debug!enable_jit_debug is 1.
Line 182: Line 117:
When invoked automatically, the SnapShotDumpType is SnapShotDumpType_Full if both "snap_shot_dump!full_dump" and "snap_shot_dump!auto_dump" are true, SnapShotDumpType_Auto if only "snap_shot_dump!auto_dump" is 1, and SnapShotDumpType_None otherwise.
When invoked automatically, the SnapShotDumpType is SnapShotDumpType_Full if both "snap_shot_dump!full_dump" and "snap_shot_dump!auto_dump" are true, SnapShotDumpType_Auto if only "snap_shot_dump!auto_dump" is 1, and SnapShotDumpType_None otherwise.


== IEventObserver ==
== CreateShellEvent ==
No input. Returns a [[#ShellEventObserverHolder]].
 
== ShellEventObserverHolder ==
This is "nn::pgl::ShellEventObserverHolder".
 
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
! Cmd || Name
! Cmd || Name
|-
|-
| 0 || [[#GetProcessEventHandle]]
| 0 || [[#GetShellEvent]]
|-
|-
| 1 || [[#GetProcessEventInfo]]
| 1 || [[#GetShellEventInfo]]
|}
|}


== GetProcessEventHandle ==
== GetShellEvent ==
No input. Returns an output Event handle.


This takes no input and returns an output copy event handle.
== GetShellEventInfo ==
No input. Returns an output [[#ShellEventInfo]].
 
This attempts to receive a [[Process_Manager_services#ProcessEventInfo|ProcessEventInfo]] from the observer's message queue.
 
Every time a process event occurs, pgl receives the event from PM (it does pm:shell->GetProcessEventHandle() during startup and has a thread looping pm:shell->GetProcessEventInfo() to track process events.
 
PGL sends to all observers' message queues a [[Process_Manager_services#ProcessEventInfo|ProcessEventInfo]] for each event it receives, thus allowing for multiple subscribers to process events.
 
= LaunchFlags =
{| class="wikitable" border="1"
|-
! Bit
! Description
|-
| 0
| EnableDetailedCrashReport
|-
| 1
| EnableCrashReportScreenShotForProduction
|-
| 2
| EnableCrashReportScreenShotForDevelop
|}


== GetProcessEventInfo ==
= SnapShotDumpType =
{| class=wikitable
! Value || Name
|-
| 0 || None
|-
| 1 || Auto
|-
| 2 || Full
|}


This takes no input and attempts to receive a [[Process_Manager_services#ProcessEventInfo]] from the observer's message queue.
= ProgramLaunchProperty =
This is "nn::pgl::ProgramLaunchProperty".


Every time a process event occurs, pgl receives the event from PM (it does pm:shell->GetProcessEventHandle() during startup and has a thread looping pm:shell->GetProcessEventInfo() to track process events.
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| [[NCM_services#ProgramId|ProgramId]]
|-
| 0x8
| 0x4
| Version
|-
| 0xC
| 0x1
| [[NCM_services#ContentType|ContentType]]
|-
| 0xD
| 0x1
| Offset
|-
| 0xE
| 0x1
| [[NCM_services#ContentMetaType|ContentMetaType]]
|-
| 0xF
| 0x1
| Reserved
|}
 
= ShellEventInfo =
This is "nn::pgl::ShellEventInfo".


PGL sends to all observers' message queues a [[Process_Manager_services#ProcessEventInfo]] for each event it receives, thus allowing for multiple subscribers to process events.
[[Category:Services]]
Retrieved from "https://switchbrew.org/wiki/PGL_services"