diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index 0ad09b4a3488a6512c86a6175682da5c63868465..0f37c6654ed3d5728e3dd6d7c3e66d0fc283151d 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -74,6 +74,7 @@ - [Startup](subsys-boot-overview.md) - [init Module](subsys-boot-init.md) - [appspawn Module](subsys-boot-appspawn.md) + - [appspawn Module for the Standard System](subsys-boot-appspawn-standard.md) - [bootstrap Module](subsys-boot-bootstrap.md) - [syspara Module](subsys-boot-syspara.md) - [FAQs](subsys-boot-faqs.md) diff --git a/en/device-dev/subsystems/subsys-boot-init.md b/en/device-dev/subsystems/subsys-boot-init.md index 1be8617beeba51061bf79045576dd3e50f3f7139..4fff3dafd166be597885752587fee0885545447b 100644 --- a/en/device-dev/subsystems/subsys-boot-init.md +++ b/en/device-dev/subsystems/subsys-boot-init.md @@ -1,58 +1,135 @@ # init Module -- [Configuration File](#section56901555917) -- [Development Guidelines](#section15371931131117) -- [Development Example](#section173413113565) +## Introduction -The init module starts key service processes during system startup. If you would like to add a system service that automatically starts upon system startup, you can add the service to the **init.cfg** file. + The init module starts key service processes during system startup. If you would like to add a system service that automatically starts upon system startup, you can add a configuration file named in the **xxx.cfg** format. The system automatically analyzes the **.cfg** file and starts the corresponding service. -## Configuration File of the init Module +- Configuration file of the init module -The configuration file **init.cfg** of the init module contains service names, executable file paths, permissions, and other information of all key system services that need to be started by the init process. The file is stored in the code repository **vendor/huawei/camera/init\_configs/**, and can be found in **/etc/** after burning is complete. The file is in JSON format, and its size cannot exceed 100 KB. + The configuration file of the init module, that is, **init.cfg**, contains service names, executable file paths, permissions, and other information of all key system services that need to be started by the init process. The file can be found in **/etc/** after burning is complete. The file is in JSON format, and its size cannot exceed 100 KB. -After the init process starts, it reads the **/etc/init.cfg** file, parses the content in JSON format, and loads system services in sequence based on the parsing result. + After the init process starts, it reads the **/etc/init.cfg** file, parses the content in JSON format, and loads system services in sequence based on the parsing result. -## Development Guidelines + If you need to add a key service to a module, you can also add the **.cfg** file of the module. During compilation, copy the file to the **/system/etc/init** directory. The init process will parse the **.cfg** file and starts the corresponding service. -1. Configure the **jobs** array. +- init service startup control (for standard system or higher) - The init module completes the system startup in three phases: + The init process classifies services into three types based on service configurations and starts the services in different phases. - - **pre-init**: operations required before system services are started, for example, mounting a file system, creating a folder, and modifying permissions. - - **init**: operations required for starting system services. - - **post-init**: operations required after system services are started. + - **boot**: services that need to be preferentially started in the system. This type of services are started after the init phase is complete. + - **normal**: common services in the system. These services are started after the init command is executed successfully. This is the default service type. + - **condition**: services with special requirements. You can run the **start xxx** command to start such a service. Generally, this type of services are started in a condition job or in a certain phase of the init process. - Each of the preceding phases is represented by a job, which corresponds to a command set. The init module initializes the system by executing the commands in each job in sequence. The **pre-init** job is executed first, then the **init** job, and finally the **post-init** job. + If dependencies exist between services or between services and commands, you need to use **condition** to describe services. For example: + ``` + "services" : [{ + "name" : "service1", + "path" : ["/bin/process1", "param1", "param2"], + "uid" : 1, + "gid" : 1, + "once" : 0, + "importance" : 1, + "caps" : [0, 1, 2, 5], + "start-mode" : "condition", + "cpucore" : [0], + "critical" : [0, 5, 10], + "apl" : "normal", + "d-caps" : ["OHOS_DMS"] + "jobs" : { + "on-boot" : "boot", + "on-start" : "services:service1_start", + "on-stop" : "services:service1_stop", + "on-restart" : "services:service1_restart" + } + }, + + ``` +- init parallel service control (for standard system or higher) + + The init module provides the parallel service processing function, which allows services to execute jobs in different phases. + + - **on-start**: a job executed after the service process is forked. The on-start jobs of different services can be executed in parallel. (The on-start job is executed in the subprocess of the service and affects only the subprocess.) + - **on-stop**: a job executed when the service is stopped. + - **on-restart**: a job executed when the service is restarted. + +- init on-demand startup (for standard system or higher) + + Services managed by the init process can be started on demand. Such services are not automatically started during system startup. Instead, they are started by the init process only when a certain event occurs. Typical events that trigger service startup are as follows: Messages are sent over the socket listened by the init process. The samgr process receives a request from the client and needs to start the SA service. + + The **ondemand** attribute indicates whether a service is started on demand. If this attribute is set to **true** for a service, the service does not need to be started by running the **start** command. Instead, it is started only when the corresponding event occurs. + + - SA process on-demand startup + 1. When an application requests an SA handle, the samgr process checks whether the process to which the SA belongs can be dynamically started. + 2. If the SA process needs to be started, the samgr process blocks the request. After the init process starts and registers the SA process, the samgr process returns the SA handle. + + - Socket process on-demand startup + 1. The init process creates a socket for socket processes in the pre-fork phase, and listens to network events on this socket. + 2. When messages are detected on the socket, the init process starts the socket process for message processing. The init process then stops listening to network data over the socket and waits until the socket process completes message processing. + 3. If no more messages need to be processed, the socket process can automatically exit. After that, the init process reclaims the subprocess and listens to network data over the socket again. + + - Hot-swap service process on-demand startup +
  The hot-swap service process can be started to process hot swap events based on system parameter changes. + +- Enhanced init process startup and recycling + + The CPU core binding, priority, MAC address, and AccessToken information of the service process can be configured in the configuration file during process startup. + + - Support of CPU core binding for service processes (through modification of the **.cfg** file) + - Support of priority setting for service processes (through modification of the **.cfg** file) + - Support of AccessToken setting for service processes and distributed capability setting for system service processes (through modification of the **.cfg** file) + - Support of the suppression mechanism for service processes (through modification of the **.cfg** file) + +- init fd proxy (for standard system or higher) + + fd proxy is an extended mechanism for on-demand startup. It can ensure that the fd state handle is not lost before the service process exits. Specifically, a service process sends the fd to the init process before it exits, and then reclaims the fd from the init process when it is started again. + + This mechanism is implemented using the API provided by the init process. Before a service process exits, it can call the related API to send the fd to the init process over the socket that supports IPC communication. After the service process is restarted, the init process returns the corresponding fd handle to it in the same way. + +- init job + + A job provided by the init process. It is actually a set of commands. A job can be configured in the **init.cfg** file or the custom **.cfg** file of the module. The parser of the init process aggregates commands of the jobs with the same name into one job. For jobs with the same name, the init process only ensures that the commands in the **init.cfg** file are executed in preference. It does not guarantee the execution sequence of commands in other **cfg** files. - ``` - "jobs" : [{ - "name" : "pre-init", - "cmds" : [ - "mkdir /testdir", - "chmod 0700 /testdir", - "chown 99 99 /testdir", - "mkdir /testdir2", - "mount vfat /dev/mmcblk0p0 /testdir2 noexec nosuid" // mount command (format: mount file system type source target flags data) - ] + - Common job: A job executed in a fixed phase during init process startup, for example, pre-init, init, or post-init. + + - Custom job: A job is triggered based on certain rules. + - job: A user-defined job, which can be executed using the **trigger** command. + - Control job (for standard system or higher): A job triggered based on specified conditions. You can set trigger conditions in such a job. When the corresponding attribute values meet the trigger conditions, the job will be triggered. && and || operations are supported for trigger conditions, and these operations can be used in flexible combinations as needed. + +## Development Guidelines + + 1. Configure the **jobs** array. + + The init module completes the system startup in three phases: + + - **pre-init**: operations required before system services are started, for example, mounting a file system, creating a folder, and modifying permissions. + - **init**: operations required for starting system services. + - **post-init**: operations required after system services are started. + + ``` + "jobs" : [{ + "name" : "pre-init", + "cmds" : [ + "mkdir /testdir", + "chmod 0700 /testdir", + "chown 99 99 /testdir", + "mount vfat /dev/mmcblk0p0 /testdir2 noexec nosuid" // mount command (format: mount file system type source target flags data) + ] }, { - "name" : "init", + "name" : "init", "cmds" : [ - "start service1", - "start service2" - ] - }, { - "name" : "post-init", - "cmds" : [] - } - ], - ``` - - **Table 1** Job description + "start service1", + ] + }, { + "name" : "post-init", + "cmds" : [] + } + ] + ``` - -

Job

+**Table 1** Job description + - @@ -68,20 +145,16 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the c -

Job

Description

+

Description

post-init

Job that is finally executed. Operations (for example, mounting the device after the driver initialization) required after the process startup are executed in this job.

+

Job that is finally executed. Operations (for example, mounting the device after the driver initialization) required after the process startup are executed in this job. A single job can hold a maximum of 30 commands (Only start, mkdir, chmod, chown, mount, and loadcfg are supported currently). The command name and parameters (128 bytes or less) must be separated by only one space.
- A single job can hold a maximum of 30 commands (only **start**, **mkdir**, **chmod**, **chown**, **mount**, and **loadcfg** are supported currently). The command name and parameters (128 bytes or less) must be separated by only one space. - - **Table 2** Commands supported by a job - - -

Command

+**Table 2** Commands supported by a job + - @@ -136,40 +209,52 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the c -

Command

Format and Example

+

Format and Example

Description

loadcfg filePath

Example: loadcfg /patch/fstab.cfg

Loads other .cfg files. The maximum size of the target file (only -/patch/fstab.cfg supported currently) is 50 KB. Each line in the /patch/fstab.cfg file is a command. The command types and formats must comply with their respective requirements mentioned in this table. A maximum of 20 commands are allowed.

+

Loads other .cfg files. The maximum size of the target file (Only /patch/fstab.cfg supported currently) is 50 KB. Each line in the /patch/fstab.cfg file is a command. The command types and formats must comply with their respective requirements mentioned in this table. A maximum of 20 commands are allowed.
-2. Configure the services array, which holds all system services (a maximum of 100) that need to be started by the init process. - - ``` - "services" : [{ - "name" : "service1", - "path" : ["/bin/process1", "param1", "param2"], - "uid" : 1, - "gid" : 1, - "once" : 0, - "importance" : 1, - "caps" : [0, 1, 2, 5] - }, { - "name" : "service2", - "path" : "/bin/process2", - "uid" : 2, - "gid" : 2, - "once" : 1, - "importance" : 0, - "caps" : [ ] - } - ] - ``` + 2. Configure the services array, which holds all system services (a maximum of 100) that need to be started by the init process. - **Table 3** Fields in the services array +``` + "services" : [{ + "name" : "service1", + "path" : ["/bin/process1", "param1", "param2"], + "uid" : 1, + "gid" : 1, + "once" : 0, + "importance" : 1, + "caps" : [0, 1, 2, 5], + "start-mode" : "condition", + "cpucore" : [0], + "critical" : [0, 5, 10], + "apl" : "normal", + "d-caps" : ["OHOS_DMS"] + "jobs" : { + "on-boot" : "boot", + "on-start" : "services:service1_start", + "on-stop" : "services:service1_stop", + "on-restart" : "services:service1_restart" + } + }, { + "name" : "service2", + "path" : "/bin/process2", + "uid" : 2, + "gid" : 2, + "once" : 1, + "importance" : 0, + "caps" : [ ], + "cpucore" : 0, + "critical" : [ ], + "apl" : "normal", + "d-caps" : [ ] + }] +``` + +**Table 3** Service field description - -

Field

+ @@ -205,9 +290,7 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the c - + + + + + + + + + + + + + + + + + + + + + +

Field

Description

importance

Whether the current service process is a key system process.

-

0: The current service process is not a key system process. If it exits, the init process does not reset or restart the system.

-

1: The current service process is a key system process. If it exits, the init process resets and restarts the system.

+

Standard system:
Priority of a service process. The value ranges from -20 to 19.
Small system:
0: non-critical process
1: critical process

caps

@@ -215,13 +298,57 @@ After the init process starts, it reads the **/etc/init.cfg** file, parses the c

Capabilities required by the current service. They are evaluated based on the capabilities supported by the security subsystem and configured in accordance with the principle of least permission. Currently, a maximum of 100 values can be configured.

critical

+

Whether to enable system restarting when a critical service fails to be restarted for a specified number of times. If this field is enabled, the critical service will be started in M seconds. If the restarting fails for N times, the system will be restarted. The default value of N is 4 and that of M is 20. (Only for standard system or higher. Configuration: [0, 2, 10], in int array.)

+

0: enable

+

1: disable

+

cpucore

+

Number of CPU cores bound to the service. The value is an int array.

+

d-caps

+

Distributed capabilities (Only for standard system or higher)

+

apl

+

Ability privilege level: system_core, normal, or system_basic. The default value is system_core. (Only for the standard system or higher).

+

start-mode

+

Service startup mode. For details, see init Service Startup Control. (Only for standard system or higher)

+

jobs

+

Jobs that can be executed by the current service in different phases. For details, see init Service Parallel Service Control. (Only for standard system or higher)

+
+ **Table 4** APIs + + | API | Function|Description | + | :---------- | :---------- |:--------| + | int *ServiceGetFd(const char *serviceName, size_t *outfdCount) | Obtains the fd from the init process.| Return value: Returns the pointer to the fd array if the operation is successful; returns **NULL** otherwise. (Note: Manual release is required.)
Input arguments:
**serviceName**: service name.
**outfdCount**: length of the returned fd array.| + | int ServiceSaveFd(const char *serviceName, int *fds, int fdCount) | Requests the init process for fd proxy.| Return value: Returns **0** if the operation is successful; returns **-1** otherwise.
Input arguments:
**serviceName**: service name.
**fds**: pointer to the fd array for fd proxy.
**fdCount**: length of the fd array + | int ServiceControlWithExtra(const char *serviceName, int action, const char *extArgv[], int extArgc) | Configures service parameters.| Return value: Returns **0** if the operation is successful; returns **-1** otherwise.
Input arguments:
**serviceName**: service name.
**action**: service action, which can be **start**, **stop**, or **restart**.
**extArgv**: parameter array.
**extArgc**: number of parameters. + | int ServiceControl(const char *serviceName, int action) | Controls the service behavior.| Return value: Returns **0** if the operation is successful; returns **-1** otherwise.
Input arguments:
**serviceName**: service name.
**action**: service action, which can be **start**, **stop**, or **restart**. -## Development Example +## Development Example -The following uses the MySystemApp service as an example to illustrate how to use the init process to start a system service. + The following uses the MySystemApp service as an example to illustrate how to use the init process to start a system service. ``` { @@ -250,6 +377,14 @@ The following uses the MySystemApp service as an example to illustrate how to us "once" : 0, // Not a one-off process of the MySystemApp service. If MySystemApp exits, the init process needs to restart it. "importance" : 0, // Not a key system process of the MySystemApp service. If MySystemApp exits, the init process does not need to restart the development board. "caps" : [] // Do not perform capability-related operations because capabilities are not required by the MySystemApp service. + "start-mode" : "condition", + "critical": [1, 2, 10], // Configure the critical field for MySystemApp system services. You need to pass three parameters, wherein, 1 means to enable system restarting, 2 means the number of times the critical service is restarted, and 10 means the time within which the critical service is restarted. + "jobs" : { + "on-boot" : "boot", + "on-start" : "services:MySystemApp_start", + "on-stop" : "services:MySystemApp_stop", + "on-restart" : "services:MySystemApp_restart" + } } ] } @@ -260,3 +395,41 @@ After the configuration is complete, compile the package to burn the board. 1. Run the **task -a** command for liteos-a or **ps** for Linux to check whether the MySystemApp service process is started. 2. Run the **kill** command to kill the MySystemApp process, and then verify that the process will be restarted. 3. Run the **kill** command to kill the MySystemApp process, and then verify that the development board will not be restarted. + +## FAQ + +### Service Not Exist + +   **Symptom**
+    "Failed get servName" is recorded in the kernel log. + +   **Cause Analysis**
+     The kernel log is printed by the init process. After a code review on the init process, it is found that the service does not exist. + +   **Solution**
+     1. Check whether the service is correctly configured in the **.cfg** file.
+     2. Check whether the **.cfg** file of the service is loaded normally.
+     3. Check whether the format of the **.cfg** file is correct. + +### Requesting FD Proxy for Other Services Failed + +  **Symptom** + +     "Service \' xxx \'(pid = xxx) is not valid or request with unexpected process(pid = xxx)" is recorded in the kernel log. + +   **Cause Analysis**
+     The kernel log is printed by the init process. After a code review on the init process, it is found that fd proxy is requested for other services. + +   **Solution**
+     Request fd proxy for the current service, but not other services. + +### No ondemand Configuration is not configured for the service. + +   **Symptom**
+     "service: %s had started already" is recorded in the kernel log. + +   **Cause Analysis**
+     The kernel log is printed by the init process. After a code review on the init process, it is found that **ondemand** is not configured for the service. + +   **Solution**
+     Correct the service configuration in the **.cfg** file as follows: "ondemand" : true