提交 840191f6 编写于 作者: S shawn_he

update doc

Signed-off-by: Nshawn_he <shawn.he@huawei.com>
上级 9de0768f
......@@ -2,11 +2,11 @@
## System Startup
### System Startup Interrupted Due to "parse failed!" Error
### Device Startup Interrupted Due to "parse failed!" Error
**Symptom**
During system startup, the error message "[Init] InitReadCfg, parse failed! please check file /etc/init.cfg format." is displayed, and the startup is interrupted, as shown in the following figure.
During device startup, the error message "[Init] InitReadCfg, parse failed! please check file /etc/init.cfg format." is displayed, and the startup is interrupted, as shown in the following figure.
**Figure 1** Error information
......@@ -14,34 +14,32 @@ During system startup, the error message "[Init] InitReadCfg, parse failed! plea
**Possible Cause**
During modification of the **init.cfg** file, required commas (,) or parentheses are missing or unnecessary ones are added. As a result, the file's JSON format becomes invalid.
The content of the **init.cfg** file does not comply with the JSON specifications.
**Solution**
Check the **init.cfg** file and ensure that its format meets the JSON specifications.
### System Restarted Repeatedly
### Device Restarted Repeatedly
**Symptom**
After the image burning is complete, the system restarts over and over again.
The device restarts over and over again upon startup.
**Possible Cause**
Each service started by the init process has the **importance** attribute, as described in Table 3 in [init Module](../subsystems/subsys-boot-init.md).
Each service started by the init process has the **importance** attribute, as described in [Parameters](../subsystems/subsys-boot-init-service.md#parameters).
- If the attribute value is **0**, the init process does not need to restart the development board when the current service process exits.
- If the attribute value is **0**, the init process does not need to restart the device when the current service process exits.
- If the attribute value is **1**, the init process needs to restart the development board when the current service process exits.
During the startup of a service whose **importance** is **1**, if the service exits due to a process crash or an error, the init process automatically restarts the development board.
- If the attribute value is **1**, the init process needs to restart the device when the current service process exits.
**Solution**
1. View logs to identify the service that encounters a process crash or exits due to an error, rectify the issue, and then burn the image again.
2. Alternatively, change the value of **importance** to **0** for the service that exits due to a process crash or an error, and then burn the image again. In this way, the development board will not be restarted even if the service exits.
2. Change the value of **importance** to **0** for the service that exits due to a process crash or an error, and then burn the image again.
### **SetParameter** or **GetParameter** Failed with Correct Parameters Passed
......@@ -50,6 +48,10 @@ During the startup of a service whose **importance** is **1**, if the service ex
Calling **SetParameter** or **GetParameter** fails when correct parameters are passed.
**System Type**
liteos-a
**Possible Cause**
Permission verification has been enabled for **SetParameter** and **GetParameter**. If the UID of the caller is greater than **1000**, that is, the caller does not have the API call permission, calling an API will fail even if correct parameters are passed.
......@@ -58,7 +60,6 @@ Permission verification has been enabled for **SetParameter** and **GetParameter
No action is required.
### ueventd Service Failed to Obtain a Socket upon Startup
**Symptom**
......@@ -71,15 +72,14 @@ After the ueventd service is started, the error message "Failed to get uevent so
**Possible Cause**
The ueventd service is started on demand. Upon startup, it first needs to check the environment variables for **fd** of the socket created by the init process. The preceding error information will be displayed if the ueventd service fails to obtain environment variables. The possible causes are as follows:
The ueventd service is started on demand. Upon startup, it first needs to check the environment variables for **fd** of the socket created by the init process. The preceding error information will be displayed if the ueventd service fails to obtain environment variables. The possible causes are as follows:
1. No socket has been configured for the ueventd service in the **.cfg** file. As a result, the init process does not create a socket for the ueventd service, and no socket ID is present in environment variables.
2. If a socket has been configured for the ueventd service in the **.cfg** file, it is probable that the ueventd service is also configured in another **.cfg** file but no socket is designated for it.
**Solution**
For case 1, configure a socket for the ueventd service in the **.cfg** file. For details, see [Development Guidelines](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-boot-init.md#development-guidelines).
For case 2, check all **.cfg** files for any duplicate ueventd service and delete it. Retain only one ueventd service with valid configuration.
1. For case 1, configure a socket for the ueventd service in the **.cfg** file. For details, see [Socket Configuration for the ueventd Service](../subsystems/subsys-boot-init-service.md#parameters).
2. For case 2, check all **.cfg** files for any duplicate ueventd service and delete it. Retain only one ueventd service with valid configuration.
### ueventd Service Exits Because of a Socket Polling Timeout
......@@ -103,18 +103,18 @@ The service configuration in JSON format cannot be correctly parsed, and the err
**Possible Cause**
The service configuration is not in the JSON format. This can result in a **.cfg** file parsing error, leading to a service parsing failure. For a service configured with the **ondemand** attribute, the **critical** attribute is set to **1**, or the first value in the **critical** attribute array is set to **1**. When the **ondemand** attribute is configured, the service is started on demand by default. The service exits when it is idle. However, when the **critical** attribute is configured, the service is regarded as a critical system service and is not allowed to exit. Therefore, a conflict occurs if both attributes are configured the same service.
When the **ondemand** attribute is configured, a service is started on demand by default. This attribute, however, is mutually exclusive with the **critical** attribute. If both of them are configured, a conflict will occur, resulting in a failure to resolve the service.
**Solution**
Check whether the service needs to be started on demand. If not, do not configure the **ondemand** attribute. If yes, do not configure the **critical** attribute along with the **ondemand** attribute. To limit the number of times that a critical service exits abnormally, set the first value in the **critical** attribute array to **0** and then add a limitation on the exit times. For example, **"critical": [0, 15, 5]** means that, if a service exits for more than 15 times within 5s, the service will not be started and the system will not be restarted.
1. If a service does not need to be started on demand, leave the **ondemand** attribute unspecified.
2. If a service needs to be started on demand, leave the **critical** attribute unspecified or disable the **critical** attribute after you configure the **ondemand** attribute.
### Parallel Startup Is Not Effective for Services Configured with the ondemand Attribute
**Symptom**
Services configured with the **ondemand** attribute are not started in the parallel startup phase, regardless of whether **start-mode** is set to **boot**, **normal**, or the default value.
Services configured with the **ondemand** attribute are not started in the parallel startup phase, regardless of the **start-mode** settings.
**Possible Cause**
......@@ -132,17 +132,17 @@ When an SA service is configured with the **ondemand** attribute, the samgr proc
**Possible Cause**
At the initial implementation of on-demand startup, **SystemAbilityManager::CheckSystemAbility(int32_t systemAbilityId)** is used for all SA services. To distinguish SA services that are started on demand, **LoadSystemAbility(int32_t systemAbilityId, const sptr& callback)** provided by the samgr process is added. If an SA service is not started on demand, it is probable that the original API is used by mistake.
At the initial implementation of on-demand startup for SA services, **SystemAbilityManager::CheckSystemAbility(int32_t systemAbilityId)** is used for all SA services. To distinguish SA services that are started on demand, **LoadSystemAbility(int32_t systemAbilityId, const sptr& callback)** provided by the samgr process is added. If an SA service is not started on demand, it is probable that the original API is used by mistake.
**Solution**
Use **LoadSystemAbility(int32_t systemAbilityId, const sptr& callback)** for any SA service that needs to be started on demand.
### Improper DAC Configuration
### Improper caps Configuration
**Symptom**
Improper DAC configuration leads to a configuration error. The error information is as follows:
Improper caps configuration leads to a configuration error. The error information is as follows:
```
4.619955] [pid=1 0][Init][ERROR][init_capability.c:119]service=multimodalinput not support caps = CAP_DC_OVERRIDE caps 41
[ 4.620014] [pid=1 0][Init][ERROR][init_service_manager.c:818]GetServiceSecon secon section not found, skip
......@@ -151,65 +151,45 @@ Improper DAC configuration leads to a configuration error. The error information
```
**Possible Cause**
1. Max attributes are present in the **caps** configuration.
2. Parsing of attributes carrying CAP and non-CAP prefixes is not supported.
3. The **const** attribute configuration is invalid.
**Solution**
1. The caps configuration is not supported by the kernel.
2. The configuration in the **.cfg** file is incorrect.
1. Enable parsing of attributes carrying CAP and non-CAP prefixes.
2. Remove max attributes from the **caps** configuration.
3. Add a correct **const** attribute file.
**System Version**
### Invalid critical Attribute Configuration
**Symptom**
The configuration of the **critical** attribute does not take effect.
**Possible Cause**
1. The format of the **critical** attribute is valid.
2. The services configured with the **critical** attribute are not started.
3. The modified configuration file is not effective.
OpenHarmony-3.0-LTS
**Solution**
1. Correct the format of the **critical** attribute.
2. Start the services configured with the **critical** attribute.
3. Modify the configuration file based on the device type. The configuration file is **init.cfg** for Hi3516 and **init.without_two_stages.cfg** for RK3568.
1. For case 1, leave **caps** unspecified.
2. For case 2, correctly configure **caps** by referring to the definition of the **capStrCapNum** data structure in **base/startup/init_lite/services/init/init_capability.c**.
### On-demand Startup Not Supported for Socket Processes
### Sandbox Not Enabled
**Symptom**
On-demand startup is not supported for socket processes.
After **hdc shell param get const.sandbox** is run, it is found that the value of **const.sandbox** is not **enable**.
**Possible Cause**
The **DISABLE_INIT_TWO_STAGES** macro setting is invalid for on-demand startup of the ueventd process.
None.
**Solution**
Enable **socket** in **startUeventd** so that socket validity check is added to the socket creation function.
Set **const.sandbox** to **enable** in **base/startup/init_lite/services/etc/param/ohos.para**. For details, see [Sandbox Management](../subsystems/subsys-boot-init-sandbox.md).
### Small System Compilation Alarm
### How to Check the Sandbox Mounting Status
**Symptom**
The alarm information is as follows:
warning: implicit declaration of function 'usleep' is invalid in C99
warning: implicit declaration of function 'setgroups' is invalid in C99
None.
**Possible Cause**
The header file is incorrect or the *GNU***SOURCE** macro is disabled.
None.
**Solution**
Check whether the corresponding header file is correct. If yes, check whether the *GNU***SOURCE** macro is enabled.
Enter the hdc shell mode on the device. Then, run the **sandbox -s service_name** command to move the current service to the sandbox, and run shell commands such as **ls** to view the sandbox directory. For details, see the [sandbox command description](../subsystems/subsys-boot-init-plugin.md).
## Application Spawning
......@@ -239,13 +219,13 @@ Applications fail to be started by running the cold start command.
**Possible Cause**
1. The cold start does not take effect.
2. The cold start command is incorrect.
1. Cold start is not enabled.
2. The parameter of the cold start command is incorrect.
**Solution**
1. Enable cold start by setting **param set appspawn.cold.boot true**.
2. Make sure that the cold start command is correct.
1. For case 1, run **param get appspawn.cold.boot** to check the cold start switch and run **param set appspawn.cold.boot true** to enable cold start.
2. For case 2, correct the parameter of the cold start command.
### Failed to Create the Application Sandbox
......@@ -266,3 +246,5 @@ The system UI freezes at the OpenHarmony startup animation, the calculator appli
1. Check the error information in the hilog file, and correct the corresponding JSON files.
2. Verify the PID of the application, the code logic of the sandbox creation process, and the JSON configuration.
For details, see [Application Sandbox Development Procedure](../subsystems/subsys-boot-appspawn.md#development-procedure).
# init Configuration File
## Overview
### Function
The init configuration file is in JSON format and is used to configure commands and services required for system startup. Upon system startup, the Init process parses the init configuration file and runs the commands in it to start the corresponding services.
### Basic Concepts
1. Group configuration file: A group configuration file is named in the format of **device.xxxx.group.cfg**. It consists of three parts, **jobs**, **services**, and **groups**. It is available only for the standard system. Such a file is used to configure the jobs and services that can be executed. The partition that holds the file is determined based on the **bootgroup** attribute in cmdline. Currently, the following groups are supported:
- ​device.boot.group: default configuration, which is used to trigger all jobs and services in the configuration file.
- device.charge.group: charge mode, which is used to trigger only the allowed jobs and services in the configuration file.
2. Startup configuration file: **init.cfg** file, which consists of three parts, **jobs**, **services**, and **import**.
- services (for the Linux kernel only): native services supported by the system. For details about the service configuration, see [Service Management](subsys-boot-init-service.md).
- jobs: collection of commands to be executed. For details about jobs, see [Job Management](subsys-boot-init-jobs.md).
- import (for the Linux kernel only). command used to import **.cfg** files. It helps reduce the size of **.cfg** files for implementing different functions.
### Constraints
Only the small system and standard system are supported.
## How to Develop
### Use Cases
Upon startup, the init process first initializes the system and then parses the configuration file. The system classifies the configuration files into three types:
1. init.cfg: default configuration file, which is defined by the init process and parsed first.
2. /system/etc/init/*.cfg: configuration file defined by each subsystem.
3. /vendor/etc/init/*.cfg: configuration file defined by vendors.
If you need to add a configuration file, define its content as you want and copy it to the corresponding directory.
### How to Develop
1. Define the configuration file.
```
{
"import" : [ ],
"jobs" : [ ],
"services" : [ ]
}
```
2. Copy the configuration file to the corresponding directory based on the system type.
For the standard system:
```
ohos_prebuilt_etc("misc.cfg") {
source = "//base/startup/init_lite/services/etc/misc.cfg"
relative_install_dir = "init"
part_name = "init"
}
```
For the small system:
```
copy("init_configs") {
sources = [ "init_liteos_a_3516dv300.cfg" ]
outputs = [ "$root_out_dir/config/init.cfg" ]
}
```
### Development Example
The following is a template for defining a **.cfg** file.
```
{
"import" : [
"/etc/example1.cfg",
"/etc/example2.cfg"
],
"jobs" : [{
"name" : "jobName1",
"cmds" : [
"start serviceName",
"mkdir dir1"
]
}, {
"name" : "jobName2",
"cmds" : [
"chmod 0755 dir1",
"chown root root dir1"
]
}
],
"services" : [{
"name" : "serviceName",
"path" : ["/system/bin/serviceName"]
}
]
}
```
1. .cfg file: configuration file written in the JSON format. If the services or commands in it do not take effect, check whether the content format is correct.
2. import: command used to import **.cfg** files. The files are parsed immediately after their path is parsed.
3. example1.cfg: **.cfg** file to be imported.
4. serviceName: service name, which is user-defined.
5. /system/bin/serviceName: full path and parameters of the executable file of the current service, in array format.
6. jobName1: job name, which is user-defined.
此差异已折叠。
# Plug-in Management
## Overview
### Basic Concepts
- Introduction to begetctl
For details, see [begetctl Commands](#table14737791480).
- bootchart plug-in
The bootchart plug-in is an open source tool used to evaluate system performance during Linux startup. It automatically collects information such as the CPU usage, disk throughput, and process status, and displays the evaluation result in graphics to facilitate system startup optimization.
### Constraints
bootchart is available only for the standard system, and begetctl is available for both the small system and the standard system.
## How to Develop
### Parameters
**Table 1** Description of begetctl commands
| Command| Format and Example| Description|
| :---------- | :---------- |:--------|
| init group test [stage] | init group test | For details about **stage**, see **ServiceStatus**.|
| param ls [-r] [name] | Displays system parameters.<br>Example:<br>begetctl param ls persist.sys.usb | N/A|
| param get [name] | Obtains system parameter information.<br>Example:<br>begetctl param get<br>param get| N/A|
| param set name value| Sets system parameters.<br>Example:<br>begetctl param set ohos.servicectrl.display 1<br>param set ohos.servicectrl.display 1| N/A|
| param wait name [value] [timeout] | Waits for system parameters.<br>Example:<br>begetctl param wait persist.sys.usb.config hdc<br>param wait persist.sys.usb.config hdc| The default value of **timeout** is **30**.|
| param dump [verbose] | Dumps system parameter information.<br>Example:<br>begetctl param dump<br>param dump| N/A|
| param shell [name] | Enters the param shell.<br>Example:<br>begetctl param shell<br>param shell| N/A|
| timer_stop servicename | Stops the service timer.<br>Example:<br>begetctl timer_stop appspawn | The value of **servicename** can contain a maximum of 96 characters.|
| timer_start servicename timeout | Starts the service timer.<br>Example:<br>begetctl timer_start appspawn | The value of **servicename** can contain a maximum of 96 characters. The default value of **timeout** is **10**.|
| start_service servicename | Starts a service.<br>Example:<br>begetctl start_service appspawn<br>start_service appspawn| N/A|
| stop_service servicename | Stops a service.<br>Example:<br>begetctl stop_service appspawn<br>stop_service appspawn| N/A|
| service_control start servicename | Starts a service.<br>Example:<br>begetctl service_control start appspawn<br>service_control start appspawn| N/A|
| service_control stop servicename | Stops a service.<br>Example:<br>begetctl service_control stop appspawn<br>service_control stop appspawn | N/A|
| misc_daemon --write_logo xxx.rgb | Writes the startup logo.<br>Example:<br>begetctl misc_daemon --write_logo logo.rgb<br>misc_daemon --write_logo logo.rgb| The maximum size of an RGB file is **1024*2038**. Only Hi3516D V300 is supported.|
| reboot | Restarts the system.<br>Example:<br>begetctl reboot<br>reboot|N/A|
| reboot shutdown | Shuts down the system.<br>Example:<br>begetctl reboot shutdown<br>reboot shutdown|N/A|
| reboot suspend | Suspends the system.<br>Example:<br>begetctl reboot suspend<br>reboot suspend| N/A|
| reboot updater | Restarts the system and enters updater.<br>Example:<br>begetctl reboot updater<br>reboot updater| N/A|
| reboot updater[:options] | Restarts the system and enters updater.<br>Example:<br>begetctl reboot updater<br>reboot updater| N/A|
| reboot flashd | Restarts the system and enters flashd.<br>Example:<br>begetctl reboot flashd<br>reboot flashd| N/A|
| reboot flashd[:options] | Restarts the system and enters flashd.<br>Example:<br>begetctl reboot flashd<br>reboot flashd| N/A|
| reboot charging | Restarts the system and enters charging.<br>Example:<br>begetctl reboot charging<br>reboot charging| N/A|
| reboot loader | Restarts the system and enters the burning mode.<br>Example:<br>begetctl reboot loader<br>reboot loader| N/A|
| bootchart stop | Stops chart analysis.<br>Example:<br>begetctl bootchart stop | Only rk3568 is supported.|
| bootchart start | Starts chart analysis.<br>Example:<br>begetctl bootchart start | N/A|
| bootchart disable | Disables chart analysis.<br>Example:<br>begetctl bootchart disable | N/A|
| bootchart enable | Enables chart analysis.<br>Example:<br>begetctl bootchart enable | N/A|
| sandbox -s service_name | Moves a service into the sandbox.<br>Example:<br>sandbox -s foundation | N/A|
| sandbox -p process_name | Moves a process into the sandbox.<br>Example:<br>sandbox -p /bin/sh | N/A|
| sandbox -n sandbox_name | Enters the configured system or chipset sandbox.<br>Example:<br>sandbox -n system | N/A|
| sandbox -h | sandbox command help | N/A|
## How to Develop
### Available APIs
**Table 1** Description of APIs
| API| Description|
| ---------- | ---------- |
| void PluginExecCmdByName(const char *name, const char *cmdContent) | Starts the plug-in by name.|
| void PluginExecCmdByCmdIndex(int index, const char *cmdContent) | Starts the plug-in by index.|
| int PluginExecCmd(const char *name, int argc, const char **argv) | Starts the plug-in by command.|
| int AddCmdExecutor(const char *cmdName, CmdExecutor execCmd) | Adds the plug-in installation command.|
### How to Develop
Add a plug-in. The following uses bootchart as an example:
1. Install the **.so** file and define an independent file to implement the following functions:
```c
static int bootchartEarlyHook(int stage, int prio, void *cookie)
{
char enable[4] = {}; // 4 enable size
uint32_t size = sizeof(enable);
SystemReadParam("persist.init.bootchart.enabled", enable, &size);
if (strcmp(enable, "1") != 0) {
PLUGIN_LOGI("bootchart disabled.");
return 0;
}
InitModuleMgrInstall("libbootchart");
PLUGIN_LOGI("bootchart enabled.");
return 0;
}
MODULE_CONSTRUCTOR(void)
{
// Depends on parameter service
InitAddPostPersistParamLoadHook(0, bootchartEarlyHook);
}
```
2. Compile the static library **libbootchart_static** and add it to the **static_modules** group.
```
group("static_modules") {
if (!defined(ohos_lite)) {
deps = [ ":libbootchart_static" ]
}
}
```
3. Initialize the bootchart plug-in.
```c
static int BootchartInit(void)
{
if (g_executorId == -1) {
g_executorId = AddCmdExecutor("bootchart", DoBootchartCmd);
PLUGIN_LOGI("BootchartInit executorId %d", g_executorId);
}
return 0;
}
MODULE_CONSTRUCTOR(void)
{
PLUGIN_LOGI("DoBootchartStart now ...");
BootchartInit();
}
```
4. Exit the bootchart plug-in.
```c
MODULE_DESTRUCTOR(void)
{
PLUGIN_LOGI("DoBootchartStop now ...");
DoBootchartStop();
BootchartExit();
}
```
5. Run the bootchart command.
```c
static int DoBootchartCmd(int id, const char *name, int argc, const char **argv)
{
PLUGIN_LOGI("DoBootchartCmd argc %d %s", argc, name);
...
return 0;
}
```
### Development Example
Prerequisites
1. Prepare the bootchart test environment. Specifically, install Python and pycairo by running **pip install pycairo** on Linux.
2. Decompress **bootchart-master.tar**.
tar -zxvf bootchart-master.tar
Procedure
1. Start the system.
2. Run the **begetctl bootchart enable** command.
3. Restart the system.
4. Run the **begetctl bootchart stop** command.
5. Run the **begetctl bootchart disable** command.
6. Export the following files from the **/data/bootchart** directory and save them to the **bootchart** folder:<br>
header<br>
proc_diskstats.log<br>
proc_ps.log<br>
proc_stat.log<br>
7. Run the **tar -zcvf bootchart.tgz *** command to compress the **bootchart.tgz** file (available only for Linux) and copy the compressed file to the **linux:bootchart-master** directory.
8. Run the following command in the **bootchart-master** directory:
```
python3 pybootchartgui.py -f pdf bootchart.tgz
```
Expected Result
<br>A **bootchart.pdf** file is generated in the **bootchart-master** directory.
# Sandbox Management
## Overview
### Function
OpenHarmony supports two types of sandbox, namely, system sandbox and chipset sandbox.
### Basic Concepts
The system sandbox and chipset sandbox are created in the init module. Native services choose to enter the system sandbox or chipset sandbox based on their functions. Sandbox components can be isolated through the **mount** attribute if **mount-bind-paths** or **mount-bind-files** is set for them in configuration files such as **system-sandbox.json** and **chipset-sandbox.json**. In addition, a sandbox debugging tool is provided to facilitate sandbox debugging, verification, and optimization. For details about commands, see [Description of begetctl Commands](subsys-boot-init-plugin.md#parameters).
### Constraints
The sandbox management module is available only for the standard system.
## How to Develop
### Parameters
**Table 1** Parameters in the sandbox configuration file
| JSON Prefix| Description|
| ---------- | ---------- |
| sandbox-root | Root directory of the sandbox.|
| mount-bind-paths | Directory to mount.|
| mount-bind-files | File to mount.|
| src-path | Source path of the directory or file to mount.|
| sandbox-path | Target path in the sandbox.|
| sandbox-flags | Mount flag. The default value is **bind rec**.|
| target-name | Directory to link.|
| link-name | Target link in the sandbox.|
**Table 2** Description of sandbox configuration files
| Sandbox Configuration File| Description|
| -------- | -------- |
| chipset-sandbox64.json | Chipset sandbox configuration file for the 64-bit system|
| chipset-sandbox.json | Chipset sandbox configuration file for the 32-bit system|
| system-sandbox64.json | System sandbox configuration file for the 64-bit system|
| system-sandbox.json | System sandbox configuration file for the 32-bit system|
### Available APIs
Logical storage structure of the sandbox:
```c++
// Main functions
// name is "system" or "chipset"
bool InitSandboxWithName(const char *name); // Parsing to the JSON structure
typedef struct {
mountlist_t *mounts; // Directory to mount
mountlist_t *fileMounts; // File to mount
linklist_t *links; // Directory to link
char *rootPath; // Root path of the sandbox: /mnt/sandbox/system|vendor|xxx
char name[MAX_BUFFER_LEN]; // Sandbox name, for example, system sandbox or chipset sandbox
bool isCreated; // Sandbox creation flag
int ns; // namespace
} sandbox_t;
```
### How to Develop
1. Create a sandbox.
- Create a system or chipset sandbox and configure the corresponding **system-sandbox.json** or **chipset-sandbox.json** file. For details about how to configure the JSON file, see [Sandbox JSON File Configuration](#sandbox).
- By default, the sandbox function of a service is enabled. If you do not want to move the service to the sandbox, set **sandbox** to **0** in the **.cfg** file. Otherwsie, set **sandbox** to **1**.
```
"sandbox" : 1
```
2. Modify the JSON file configuration of the sandbox.
- Go to the **/system/etc/sandbox/** directory, and run **cat system-sandbox.json** and **cat chipset-sandbox.json**.
If you are using a 64-bit system, run **cat system-sandbox64.json** and **cat chipset-sandbox64.json** instead.
- Modify the sandbox configuration files in the **base/startup/init_lite/interfaces/innerkits/sandbox** directory. After that, restart the system.
### Development Example
Sandbox JSON File Configuration
```json
{
"sandbox-root" : "/mnt/sandbox/system",
"mount-bind-paths" : [{
"src-path" : "/system/lib/ndk",
"sandbox-path" : "/system/lib/ndk",
"sandbox-flags" : [ "bind", "rec", "private" ]
}],
"mount-bind-files" : [{
"src-path" : "/system/lib/ld-musl-aarch64.so.1",
"sandbox-path" : "/system/lib/ld-musl-aarch64.so.1",
"sandbox-flags" : [ "bind", "rec", "private" ]
}],
"symbol-links" : [{
"target-name" : "/vendor/lib",
"link-name" : "/lib"
}]
}
```
## FAQs
### Failed to Create a Sandbox
**Symptom**
**Sandbox %s has not been created.** is printed in the dmesg or hilog.
**Cause Analysis**
Creating a sandbox failed because of a mounting and linking error.
**Solution**
1. Check whether the JSON file is correctly configured.
2. Check whether the created sandbox is supported.
此差异已折叠。
# Parameter Management
## Overview
### Function
The parameter management module, namely, sysparam, provides an easy-to-use key-value pair access interface for system services to configure service functions based on their own system parameters.
### Basic Concepts
Figure 1 System parameter operation primitives
![System parameter operation primitives](figure/system-parameter-operation-primitives.png)
**Table 1** Description of system parameter operation primitives
| Operation Primitive| Description|
| -------- | -------- |
| get | Obtains the value of a system parameter. |
| set | Sets the value of a system parameter. |
| wait | Waits for value change of a system parameter synchronously.|
| watch | Observes value change of a system parameter asynchronously.|
#### System Parameter Definition
- Naming format
A system parameter name consists of multiple segments in dotted notation. Each segment can be a string that consists of letters, digits, and underscores (_). The total length cannot exceed 96 bytes. System parameter names are categorized into the following two types.
**Table 2** System parameter names
| Type| Name| Example| Description|
| -------- | -------- | -------- | -------- |
| Name| Parameter Name | const.product.**name** | Complete system parameter name. It does not end with a period (.). |
| Directory| Parameter Directory | const.product **.** | Name of the directory storing system parameters with the same prefix. It ends with a period (.).|
- Type
System parameters are categorized into three types.
**Table 3** System parameter types
| Type| Prefix| Description|
| -------- | -------- | -------- |
| Constant| const. | Constant parameter, which will not be changed once a value is assigned. The value can contain a maximum of 4,096 bytes (including the terminator).|
| Writable| Others| Writable parameter, which will be lost after system restart. The value can contain a maximum of 96 bytes (including the terminator).|
| Persistent| persist. | Writable and persistent parameter, which will not be lost after system restart. The value can contain a maximum of 96 bytes (including the terminator).|
The general naming format is as follows:
```
[ const | persist ].$sub_system.$desc
```
**$sub_system** is the name of the subsystem or module.
**$desc** indicates the description of a system parameter. The description can contain multiple segments in dotted notation.
#### Definition Rules
Each subsystem defines the system parameters of its own modules, including the system parameter name, default value, and access permission information.
- System parameter value definition file
- The system parameter value definition file ends with the **.para** extension. An example of the file format is as follows:
```shell
# This is comment
const.product.name=OHOS-PRODUCT
const.os.version.api=26
const.telephony.enable=false|true
const.test.withblank=My Value
const.test.withcomment=MyValue # This should be ommitted
const.test.multiline="This is a multiline parameter.
Line2 value.
Last line."
```
- You must use a complete system parameter command when assigning a value for a system parameter. The following table describes the value assignment modes.
**Table 4** Value assignment modes
| Type| Example| Description|
| -------- | -------- | -------- |
| String | const.product.name=OHOS-PRODUCT | A multi-line string must be enclosed in double quotation marks ("").|
| Number | const.os.version.api=26 | Numbers do not need to be enclosed in quotation marks.|
| Boolean | const.telephony.enable=false | A Boolean value can be **0**, **1**, **false**, or **true**.|
- DAC definition file
Currently, access permissions of system parameters are managed in Discretionary Access Control (DAC) mode. The access permission definition file ends with the **.para.dac** extension. The following is an example:
```java
const.product.="root:root:660"
```
As shown above, we can use **parameter directory** to define the same access permission for system parameters with the same prefix. The DAC information is divided into three segments, user, group, and UGO rule information, which are separated using a semicolon (:).
The following figure shows the structure of the UGO rule information.
**Figure 2** UGO rule information
![UGO rule](figure/dac-definition.png)
- Loading sequence
The following table provides the sequence of loading system parameters.
**Table 5** System parameter loading sequence
| Type| Path| Description|
| -------- | -------- | -------- |
| Kernel parameters | /proc/cmdline | Convert some values of kernel parameters into system parameters. Specifically, convert all **ohospara.xxx=valXXX** parameters to **ohos.boot.xxx=valXXX** parameters.|
| OS system parameters| /system/etc/param/ohos_const/*.para | Load the definition file containing OS constants preferentially. |
| Vendor parameters| /vendor/etc/param/*.para | Load the system parameters defined by vendors with the secondary priority. |
| System parameters| /system/etc/param/*.para | Load the parameters defined by each subsystem. If a system parameter already exists, ignore it.|
| Persistent parameters| /data/parameters/ | If persistent parameters exist, load them at last. Persistent parameters will overwrite the default system parameters that have been loaded.|
### Constraints
The service management module is available only for the mini system and standard system.
## How to Develop
### Use Cases
You can set specific system parameters as needed to meet your service demand.
### Available APIs
- Shell commands
You can operate system parameters directly by using shell commands. This operation mode is available only for the standard system. The following table lists the shell commands.
**Table 6** Description of shell commands
| Command| Description|
| -------- | -------- |
| param get [**key**] | Obtains the system parameter value of the specified key. If no key name is specified, all system parameter values will be returned.|
| param set **key value** | Sets the specified value for the specified key.|
| param wait **key** **value** | Waits for the system parameter value of the specified key to match the specified value. Fuzzy match is supported. For example, ***** indicates any value, and **val*** indicates matching of only the first three val characters.|
| param watch | Observes value change of a system parameter asynchronously.|
- syspara APIs
The following table lists the APIs used to obtain system parameter values. The return result is a const string and the free operation is not supported.
**Table 7** Description of syspara APIs
| API| Description|
| -------- | -------- |
| int&nbsp;GetParameter(const&nbsp;char\*&nbsp;key,&nbsp;const&nbsp;char\*&nbsp;def,&nbsp;char\*&nbsp;value,&nbsp;unsigned&nbsp;int&nbsp;len) | Obtains system parameters.|
| int&nbsp;SetParameter(const&nbsp;char\*&nbsp;key,&nbsp;const&nbsp;char\*&nbsp;value) | Sets or updates system parameters.|
| const&nbsp;char\*&nbsp;GetDeviceType(void) | Obtains the device type.|
| const&nbsp;char\*&nbsp;GetManufacture(void) | Obtains the device manufacturer.|
| const&nbsp;char\*&nbsp;GetBrand(void) | Obtains the device brand.|
| const&nbsp;char\*&nbsp;GetMarketName(void) | Obtains the device marketing name.|
| const&nbsp;char\*&nbsp;GetProductSeries(void) | Obtains the device series name.|
| const&nbsp;char\*&nbsp;GetProductModel(void) | Obtains the device authentication model.|
| const&nbsp;char\*&nbsp;GetSoftwareModel(void) | Obtains the device software model.|
| const&nbsp;char\*&nbsp;GetHardwareModel(void) | Obtains the device hardware model.|
| const&nbsp;char\*&nbsp;GetHardwareProfile(void) | Obtains the device hardware profile.|
| const&nbsp;char\*&nbsp;GetSerial(void) | Obtains the device serial number (SN).|
| const&nbsp;char\*&nbsp;GetOSFullName(void) | Obtains the operating system name.|
| const&nbsp;char\*&nbsp;GetDisplayVersion(void) | Obtains the software version visible to users.|
| const&nbsp;char\*&nbsp;GetBootloaderVersion(void) | Obtains the bootloader version of this device.|
| const&nbsp;char\*&nbsp;GetSecurityPatchTag(void) | Obtains the security patch tag.|
| const&nbsp;char\*&nbsp;GetAbiList(void) | Obtains the list of application binary interfaces (ABIs) supported on this device.|
| int&nbsp;GetSdkApiVersion(void) | Obtains the SDK API level that matches the current system software.|
| int&nbsp;GetFirstApiVersion(void) | Obtains the first SDK API level of the system software.|
| const&nbsp;char\*&nbsp;GetIncrementalVersion(void) | Obtains the incremental version.|
| const&nbsp;char\*&nbsp;GetVersionId(void) | Obtains the version ID.|
| const&nbsp;char\*&nbsp;GetBuildType(void) | Obtains the build type.|
| const&nbsp;char\*&nbsp;GetBuildUser(void) | Obtains the build account user name.|
| const&nbsp;char\*&nbsp;GetBuildHost(void) | Obtains the build host name.|
| const&nbsp;char\*&nbsp;GetBuildTime(void) | Obtains the build time.|
| const&nbsp;char\*&nbsp;GetBuildRootHash(void) | Obtains the buildroot hash value of this version.|
| const&nbsp;char\*&nbsp;GetOsReleaseType(void) | Obtains the system release type.|
| int&nbsp;GetDevUdid(char&nbsp;\*udid,&nbsp;int&nbsp;size) | Obtains the device identifier (UDID).|
| const char *AclGetSerial(void); | Obtains the device SN (with ACL check).|
| int AclGetDevUdid(char *udid, int size); | Obtains the UDID (with ACL check).|
### How to Develop
1. System parameter definition
You can define default system parameters and implement permission control on them by configuring the subsystem or product **.para** and **.para.dac** files.
​ On a standard system, use the **ohos_prebuilt_para** template to install the configuration file to the **/etc/param/** directory. The following is an example of the GN script:
```go
import("//base/startup/init_lite/services/etc/param/param_fixer.gni")
ohos_prebuilt_para("ohos.para") {
source = "//base/startup/init_lite/services/etc/ohos.para"
part_name = "init"
module_install_dir = "etc/param"
}
ohos_prebuilt_para("ohos.para.dac") {
source = "//base/startup/init_lite/services/etc/ohos.para.dac"
part_name = "init"
module_install_dir = "etc/param"
}
```
On a small system, run the **copy** command to copy the corresponding system parameter definition file to the **system/etc/param** directory.
```go
copy("ohos.para") {
sources = [ "//base/startup/init_lite/services/etc/param/ohos.para" ]
outputs = [ "$root_out_dir/system/etc/param/ohos.para" ]
}
copy("ohos.para.dac") {
sources = [ "//base/startup/init_lite/services/etc/param/ohos.para.dac" ]
outputs = [ "$root_out_dir/system/etc/param/ohos.para.dac" ]
}
```
On a mini system, convert all defined default system parameters into header files through **action** and compile them into the system.
```go
action("lite_const_param_to") {
script = "//base/startup/init_lite/scripts/param_cfg_to_code.py"
args = [
"--source",
rebase_path(
"//base/startup/init_lite/services/etc_lite/param/ohos_const/ohospara"),
"--dest_dir",
rebase_path("$root_out_dir/gen/init_lite/"),
"--priority",
"0",
]
outputs = [ "$target_gen_dir/${target_name}_param_cfg_to_code.log" ]
}
```
2. Development example
```
// set && get
char key1[] = "rw.sys.version";
char value1[] = "10.1.0";
int ret = SetParameter(key1, value1);
char valueGet1[128] = {0};
ret = GetParameter(key1, "version=10.1.0", valueGet1, 128);
// get sysparm
char* value1 = GetDeviceType();
printf("Product type =%s\n", value1);
char* value2 = GetManufacture();
printf("Manufacture =%s\n", value2);
char* value3 = GetBrand();
printf("GetBrand =%s\n", value3);
char* value4 = GetMarketName();
printf("MarketName =%s\n", value4);
char* value5 = GetProductSeries();
printf("ProductSeries =%s\n", value5);
char* value6 = GetProductModel();
printf("ProductModel =%s\n", value6);
char* value7 = GetSoftwareModel();
printf("SoftwareModel =%s\n", value7);
char* value8 = GetHardwareModel();
printf("HardwareModel =%s\n", value8);
char* value9 = GetHardwareProfile();
printf("Software profile =%s\n", value9);
char* value10 = GetSerial();
printf("Serial =%s\n", value10);
char* value11 = GetOSFullName();
printf("OS name =%s\n", value11);
char* value12 = GetDisplayVersion();
printf("Display version =%s\n", value12);
char* value13 = GetBootloaderVersion();
printf("bootloader version =%s\n", value13);
char* value14 = GetSecurityPatchTag();
printf("secure patch level =%s\n", value14);
char* value15 = GetAbiList();
printf("abi list =%s\n", value15);
int value16 = GetFirstApiVersion();
printf("first api level =%d\n", value16);
char* value17 = GetIncrementalVersion();
printf("Incremental version = %s\n", value17);
char* value18 = GetVersionId();
printf("formal id =%s\n", value18);
char* value19 = GetBuildType();
printf("build type =%s\n", value19);
char* value20 = GetBuildUser();
printf("build user =%s\n", value20);
char* value21 = GetBuildHost();
printf("Build host = %s\n", value21);
char* value22 = GetBuildTime();
printf("build time =%s\n", value22);
char* value23 = GetBuildRootHash();
printf("build root later..., %s\n", value23);
char* value24 = GetOsReleaseType();
printf("OS release type =%s\n", value24);
char* value25 = GetOsReleaseType();
printf("OS release type =%s\n", value25);
char value26[65] = {0};
GetDevUdid(value26, 65);
printf("device udid =%s\n", value26);
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册