diff --git a/ipc/docs/processes.rst b/ipc/docs/processes.rst index c0d2b2f0044a..1cb1463b4f0e 100644 --- a/ipc/docs/processes.rst +++ b/ipc/docs/processes.rst @@ -96,7 +96,148 @@ The rest of the sections will explain how to compose these classes and integrate Process Bookkeeping ~~~~~~~~~~~~~~~~~~~ -To begin with, look at the `geckoprocesstypes generator `_ which adds the bones for a new process (by defining enum values and so on). It contains instructions on additional steps that are required to add the new process type. +To begin with, look at the `geckoprocesstypes generator `_ which adds the bones for a new process (by defining enum values and so on). Some further manual intervention is still required, and you need to follow the following checklists depending on your needs. + +Basic requirements +^^^^^^^^^^^^^^^^^^ + +* Add a new entry to the `enum WebIDLProcType `_ +* Update the `static_assert `_ call checking for boundary against ``GeckoProcessType_End`` +* Add your process to the correct ``MessageLoop::TYPE_x`` in the first ``switch(XRE_GetProcessType())`` in `XRE_InitChildProcess `_. You can get more information about that topic in `this comment `_ +* Instantiate your child within the second ``switch (XRE_GetProcessType())`` in `XRE_InitChildProcess `_ +* Add a new entry ``PROCESS_TYPE_x`` in `nsIXULRuntime interface `_ + +Graphics +######## + +If you need graphics-related interaction, hack into `gfxPlatform `_ + +- Add a call to your process manager init in ``gfxPlatform::Init()`` in `gfxPlatform `_ +- Add a call to your process manager shutdown in ``gfxPlatform::Shutdown()`` in `gfxPlatform `_ + +Android +####### + +You might want to talk with `#geckoview` maintainers to ensure if this is required or applicable to your new process type. + +- Add a new ```` entry against ``org.mozilla.gecko.process.GeckoChildProcessServices$XXX`` in the `AndroidManifest `_ +- Add matching class inheritance from `GeckoChildProcessServices `_ +- Add new entry in `public enum GeckoProcessType `_ + +Crash reporting +############### + +- Add new ``Xxx*Status`` `annotations `_ entry for your new process type description. The link here points to `UtilityProcessStatus` so you can see the similar description you have to write, but you might want to respect ordering in that file and put your new code at the appropriate place. +- Add entry in `PROCESS_CRASH_SUBMIT_ATTEMPT `_ + +Process reporting +################# + +Those elements will be used for exposing processes to users in some `about:` pages. You might want to ping `#fluent-reviewers` to ensure if you need your process there. + +- Add a `user-facing localizable name `_ for your process, if needed +- Hashmap from process type to user-facing string above in `const ProcessType `_ + +Static Components +################# + +The amount of changes required here are significant, `Bug 1740485: Improve StaticComponents code generation `_ tracks improving that. + +- Update allowance in those configuration files to match new process selector that includes your new process. When exploring those components definitions, keep in mind that you are looking at updating `processes` field in the `Classes` object. The `ProcessSelector` value will come from what the reader writes based on the instructions below. Some of these also contains several services, so you might have to ensure you have all your bases covered. Some of the components might not need to be updated as well. + + + `libpref `_ + + `telemetry `_ + + `android `_ + + `gtk `_ + + `windows `_ + + `base `_ + + `components `_ + + `ds `_ + + `threads `_ + + `cocoa kWidgetModule `_ + + `build `_ + + `XPCOMinit kXPCOMModule `_ + +- Within `static components generator `_ + + + Add new definition in ``ProcessSelector`` for your new process ``ALLOW_IN_x_PROCESS = 0x..`` + + Add new process selector masks including your new process definition + + Also add those into the ``PROCESSES`` structure + +- Within `module definition `_ + + + Add new definition in ``enum ProcessSelector`` + + Add new process selector mask including the new definition + + Update ``kMaxProcessSelector`` + +- Within `nsComponentManager `_ + + + Add new selector match in ``ProcessSelectorMatches`` for your new process (needed?) + + Add new process selector for ``gProcessMatchTable`` in ``nsComponentManagerImpl::Init()`` + +Glean telemetry +############### + +- Within `FOGIPC `_ + + + Add handling of your new process type within ``FlushAllChildData()`` `here `_ and ``SendFOGData()`` `here `_ + + Add support for sending test metrics in ``TestTriggerMetrics()`` `here `_ + +- Handle process shutdown in ``register_process_shutdown()`` of `glean `_ + +Sandboxing +########## + +Sandboxing changes related to a new process can be non-trivial, so it is strongly advised that you reach to the Sandboxing team in ``#hardening`` to discuss your needs prior to making changes. + +Linux Sandbox +_____________ + +Linux sandboxing mostly works by allowing / blocking system calls for child process and redirecting (brokering) some from the child to the parent. Rules are written in a specific DSL: `BPF `_. + +- Add new ``SetXXXSandbox()`` function within `linux sandbox `_ +- Within `sandbox filter `_ + + + Add new helper ``GetXXXSandboxPolicy()`` `like this one `_ called by ``SetXXXSandbox()`` + + Derive new class `similar to this `_ inheriting ``SandboxPolicyCommon`` or ``SandboxPolicyBase`` and defining the sandboxing policy + +- Add new ``SandboxBrokerPolicyFactory::GetXXXProcessPolicy()`` in `sandbox broker `_ +- Add new case handling in ``GetEffectiveSandboxLevel()`` in `sandbox launch `_ +- Add new entry in ``enum class ProcType`` of `sandbox reporter header `_ +- Add new case handling in ``SubmitToTelemetry()`` in `sandbox reporter `_ +- Add new case handling in ``SandboxReportWrapper::GetProcType()`` of `sandbox reporter wrapper `_ + +MacOS Sandbox +_____________ + +- Add new case handling in ``GeckoChildProcessHost::StartMacSandbox()`` of `GeckoChildProcessHost `_ +- Add new entry in ``enum MacSandboxType`` defined in `macOS sandbox header `_ +- Within `macOS sandbox core `_ handle the new ``MacSandboxType`` in + + + ``MacSandboxInfo::AppendAsParams()`` in the `switch statement `_ + + ``StartMacSandbox()`` in the `serie of if/else statements `_. This code sets template values for the sandbox string rendering, and is running on the side of the main process. + + ``StartMacSandboxIfEnabled()`` in this `switch statement `_. You might also need a ``GetXXXSandboxParamsFromArgs()`` that performs CLI parsing on behalf of ``StartMacSandbox()``. + +- Create the new sandbox definition file ``security/sandbox/mac/SandboxPolicy.h`` for your new process ````, and make it exposed in the ``EXPORTS.mozilla`` section of `moz.build `_. Those rules follows a specific Scheme-like language. You can learn more about it in `Apple Sandbox Guide `_ as well as on your system within ``/System/Library/Sandbox/Profiles/``. + +Windows Sandbox +_______________ + +- Introduce a new ``SandboxBroker::SetSecurityLevelForXXXProcess()`` that defines the new sandbox in both + + + the sandbox broker basing yourself on that `example `_ + + the remote sandbox broker getting `inspired by `_ + +- Add new case handling in ``WindowsProcessLauncher::DoSetup()`` calling ``SandboxBroker::SetSecurityLevelForXXXProcess()`` in `GeckoChildProcessHost `_. This will apply actual sandboxing rules to your process. + +Sandbox tests +_____________ + +- New process' first top level actor needs to `include PSandboxTesting `_ and implement ``RecvInitSandboxTesting`` `like there `_. +- Add your new process ``string_name`` in the ``processTypes`` list of `sandbox tests `_ +- Add a new case in ``SandboxTest::StartTests()`` in `test core `_ to handle your new process +- Add a new if branch for your new process in ``SandboxTestingChild::Bind()`` in `testing child `_ +- Add a new ``RunTestsXXX`` function for your new process (called by ``Bind()`` above) `similar to that implementation `_ Creating the New Process ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py b/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py index 9ae6fec04fbd..b6ff3c777c38 100644 --- a/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py +++ b/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py @@ -4,147 +4,10 @@ from collections import namedtuple -# Besides adding a new process type to this file, a bit of extra work is -# required for places where generated code has not yet been implemented. -# TODO: Bug 1740268: Move this piece into doc and link doc from here. -# -# Basic requirements: -# dom/chrome-webidl/ChromeUtils.webidl -# - Add a new entry to the enum WebIDLProcType -# -# gfx/thebes/gfxPlatform.cpp -# - (if you need GFX related stuff ?) -# - Add a call to your process manager init in gfxPlatform::Init() -# - Add a call to your process manager shutdown in gfxPlatform::Shutdown() -# -# mobile/android/geckoview/src/main/AndroidManifest.xml -# - Add a new entry targetting -# org.mozilla.gecko.process.GeckoChildProcessServices$XXX -# -# mobile/android/geckoview/src/main/java/org/mozilla/gecko/process/GeckoChildProcessServices.jinja -# - Add matching class inheritance from GeckoChildProcessServices -# -# mobile/android/geckoview/src/main/java/org/mozilla/gecko/process/GeckoProcessType.java -# - Add new entry in public enum GeckoProcessType -# -# toolkit/crashreporter/CrashAnnotations.yaml -# - Add new Xxx*Status entry for your new process type description -# -# toolkit/components/telemetry/Histograms.json -# - Add entry in PROCESS_CRASH_SUBMIT_ATTEMPT -# -# toolkit/locales/en-US/toolkit/global/processTypes.ftl -# - Add a user-facing localizable name for your process, if needed -# -# toolkit/modules/ProcessType.jsm -# - Hashmap from process type to user-facing string above in const ProcessType -# -# toolkit/xre/nsAppRunner.cpp -# - Update the static_assert call checking for boundary against -# GeckoProcessType_End -# -# toolkit/xre/nsEmbedFunctions.cpp -# - Add your process to the correct MessageLoop::TYPE_x in the first -# switch(XRE_GetProcessType()) in XRE_InitChildProcess -# - Instantiate your child within the second switch (XRE_GetProcessType()) -# in XRE_InitChildProcess -# -# xpcom/system/nsIXULRuntime.idl -# - Add a new entry PROCESS_TYPE_x in nsIXULRuntime interface -# -# -# For static components: -# modules/libpref/components.conf -# toolkit/components/telemetry/core/components.conf -# widget/android/components.conf -# widget/gtk/components.conf -# widget/windows/components.conf -# xpcom/base/components.conf -# xpcom/build/components.conf -# xpcom/components/components.conf -# xpcom/ds/components.conf -# xpcom/threads/components.conf -# widget/cocoa/nsWidgetFactory.mm -# xpcom/build/XPCOMInit.cpp -# - Update allowance in those config file to match new process selector -# including your new process -# -# xpcom/components/gen_static_components.py -# - Add new definition in ProcessSelector for your new process -# ALLOW_IN_x_PROCESS = 0x.. -# - Add new process selector masks including your new process definition -# - Also add those into the PROCESSES structure -# -# xpcom/components/Module.h -# - Add new definition in enum ProcessSelector -# - Add new process selector mask including the new definition -# - Update kMaxProcessSelector -# -# xpcom/components/nsComponentManager.cpp -# - Add new selector match in ProcessSelectorMatches for your new process -# (needed?) -# - Add new process selector for gProcessMatchTable -# in nsComponentManagerImpl::Init() -# xpcom/build/XPCOMInit.cpp -# -# -# For sandbox: -# Sandbox Linux: -# security/sandbox/linux/Sandbox.cpp -# - Add new SetXXXSandbox() function -# security/sandbox/linux/SandboxFilter.cpp -# - Add new helper GetXXXSandboxPolicy() called by SetXXXSandbox() -# - Derive new class inheriting SandboxPolicyCommon or SandboxPolicyBase and -# defining the sandboxing policy -# security/sandbox/linux/broker/SandboxBrokerPolicyFactory.cpp -# - Add new SandboxBrokerPolicyFactory::GetXXXProcessPolicy() -# security/sandbox/linux/launch/SandboxLaunch.cpp -# - Add new case handling in GetEffectiveSandboxLevel() -# security/sandbox/linux/reporter/SandboxReporter.cpp -# - Add new case handling in SubmitToTelemetry() -# security/sandbox/linux/reporter/SandboxReporterCommon.h -# - Add new entry in enum class ProcType -# security/sandbox/linux/reporter/SandboxReporterWrappers.cpp -# - Add new case handling in SandboxReportWrapper::GetProcType() -# -# Sandbox Mac: -# ipc/glue/GeckoChildProcessHost.cpp -# - Add new case handling in GeckoChildProcessHost::StartMacSandbox() -# security/sandbox/mac/Sandbox.h -# - Add new entry in enum MacSandboxType -# security/sandbox/mac/Sandbox.mm -# - Handle the new MacSandboxType in MacSandboxInfo::AppendAsParams() -# - Handle the new MacSandboxType in StartMacSandbox() -# - Handle the new MacSandboxType in StartMacSandboxIfEnabled() -# security/sandbox/mac/SandboxPolicy.h -# - Create this new file for your new process , it defines the new -# sandbox -# security/sandbox/mac/moz.build -# - Add the previous new file -# -# Sandbox Win: -# ipc/glue/GeckoChildProcessHost.cpp -# - Add new case handling in WindowsProcessLauncher::DoSetup() calling -# SandboxBroker::SetSecurityLevelForXXXProcess() -# security/sandbox/win/src/remotesandboxbroker/remoteSandboxBroker.cpp -# - Introduce a new SandboxBroker::SetSecurityLevelForXXXProcess() -# security/sandbox/win/src/sandboxbroker/sandboxBroker.cpp -# - Introduce a new SandboxBroker::SetSecurityLevelForXXXProcess() that -# defines the new sandbox -# -# Sandbox tests: -# - Your new process needs to implement PSandboxTesting.ipdl -# security/sandbox/test/browser_sandbox_test.js -# - Add your new process string_name in the processTypes list -# security/sandbox/common/test/SandboxTest.cpp -# - Add a new case in SandboxTest::StartTests() to handle your new process -# security/sandbox/common/test/SandboxTestingChild.cpp -# - Add a new if branch for your new process in SandboxTestingChild::Bind() -# security/sandbox/common/test/SandboxTestingChildTests.h -# - Add a new RunTestsXXX function for your new process (called by Bind() above) -# -# ~~~~~ -# +# Please make sure you follow ipc/docs/processes.rst and keep updating all +# places that might depend on a new process type and that are not covered (yet) +# by that code. + # The entries in this file define support functions for each of the process # types present in Gecko. #