diff --git a/zh-cn/device-dev/subsystems/subsys-boot-appspawn-standard.md b/zh-cn/device-dev/subsystems/subsys-boot-appspawn-standard.md new file mode 100644 index 0000000000000000000000000000000000000000..70383aef279665cffc6ae3c78376627efcf82718 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-boot-appspawn-standard.md @@ -0,0 +1,166 @@ +# appspawn标准系统应用孵化组件 + +- [概述](#section56901555910) + - [功能简介](#section56901555911) + - [基本概念](#section56901555912) +- [开发指导](#section56901555913) + - [接口说明](#section56901555914) + - [开发实例](#section56901555915) +- [常见问题](#section56901555916) + - [冷启动失败](#section56901555917) + +## 概述 + +appspawn被init启动后，等待接收进程间消息，根据消息内容启动应用服务并赋予其对应权限。 + +### 功能简介 + +- 安全控制 + - 支持为app设置SELinux标签 + +- 应用进程控制 + + - 支持为app设置AccessToken + - 支持重启前，appspawn停止后，可同时停止所有已孵化的app进程 + +- 冷启动 + - 支持应用通过aa命令冷启动应用 + + ``` + param set appspawn.cold.boot true // 打开冷启动状态 + aa start -d 12345 -a $name -b $package -C + 参考： + aa start -d 12345 -a ohos.acts.startup.sysparam.function.MainAbility -b ohos.acts.startup.sysparam.function -C + +### 基本概念 + +appspawn注册的服务名称为“appspawn”, appspawn 通过监听本地socket，接收来自客户端的请求消息，消息格式定义如下： + +**表 1** 字段说明 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

字段名

+

说明

+

processName

+

即将启动的应用服务进程名，最大256字节。

+

bundleName

+

即将启动的应用程序包名，最大256字节。

+

soPath

+

应用程序指定的动态库的路径，最大256字节。

+

uid

+

即将启动的应用进程的uid，必须为正值。

+

gid

+

即将启动的应用进程的gid，必须为正值。

+

gidTable

+

即将启动的应用进程组信息，长度由gidCount指定，最大支持64个进程组，必须为正值。

+

gidCount

+

即将启动的应用进程组个数。

+

accessTokenId

+

应用进程权限控制的token id。

+

apl

+

应用进程权限控制的apl，最大32字节。

+
+ +## 开发指导 + + 通过 “base/startup/appspawn_standard/interfaces/innerkits/include/client_socket.h“ 头文件查看 + +### 接口说明 + +**表 2** 字段说明 + + + + + + + + + + + + + + + + + + + + +

字段名

+

说明

+

CreateClient

+

创建client。

+

CloseClient

+

关闭client。

+

ConnectSocket

+

向appspawn服务发起连接请求。

+

WriteSocketMessage

+

发送消息到appspawn服务。

+

ReadSocketMessage

+

接收来自appspawn服务的消息。

+
+ +### 开发实例 + +``` + std::shared_ptr clientSocket = std::make_unique("AppSpawn"); + if (clientSocket == nullptr) { + return -1; + } + if (clientSocket->CreateClient() != ERR_OK) { + return -1; + } + if (clientSocket->ConnectSocket() != ERR_OK) { + return -1;; + } + // property 构造AppProperty + clientSocket->WriteSocketMessage((void *)&property, sizeof(AppSpawn::AppProperty)); + // 读结果 + int pid; + clientSocket->ReadSocketMessage((void *)&pid, sizeof(pid)); + // 如果失败，返回pid如果小于等于0，则错误，否则返回应用的进程id +``` + +## 常见问题 + +### 冷启动失败 + +- **现象描述** + 通过命令冷启动应用失败 + +- **解决方法** + 1. 确认是否打开冷启动设置 + 2. 确认冷启动命令是否正确 \ No newline at end of file diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init.md b/zh-cn/device-dev/subsystems/subsys-boot-init.md index 74c194c86f7c55af11c419daabab6b8a622119b7..5aa012b9520f3e0cb3166cbd6c348557bf3bca87 100755 --- a/zh-cn/device-dev/subsystems/subsys-boot-init.md +++ b/zh-cn/device-dev/subsystems/subsys-boot-init.md @@ -1,88 +1,103 @@ # init启动引导组件 -- [init启动引导的配置文件](#section56901555917) -- [开发指导](#section15371931131117) -- [开发实例](#section173413113565) +- [功能说明](#section56901555916) + - [init启动引导的配置文件](#section56901555917) + - [init服务启动控制(仅标准系统以上提供)](#section56901555918) + - [init服务并行控制(仅标准系统以上提供)](#section56901555919) + - [init 按需启动(仅标准系统以上提供)](#section56901555920) + - [init 进程启动&回收能力增强](#section56901555921) + - [init FD代持(仅标准系统以上提供)](#section56901555922) + - [init job](#section56901555923) +- [开发指导](#section56901555924) +- [开发实例](#section56901555925) +- [常见问题](#section56901555926) + - [服务不存在](#section56901555927) + - [请求其他服务代持fd，init有报错](#section56901555928) + - [服务没有配置ondemand 选项](#section56901555929) -init启动引导组件负责在系统启动阶段启动关键服务进程。 若用户需要新增随开机自启动的系统服务，可添加新的配置文件xxx.cfg，系统会自动分析对应的cfg文件，并按照cfg文件启动对应的服务。 +## 功能说明 -## init启动引导的配置文件 + init启动引导组件负责在系统启动阶段启动关键服务进程。 若用户需要新增随开机自启动的系统服务，可添加新的配置文件xxx.cfg，系统会自动分析对应的cfg文件，并按照cfg文件启动对应的服务。 -init启动引导组件配置文件包含了所有需要由init进程启动的系统关键服务的服务名、可执行文件路径、权限和其他信息，烧写单板后可在“/etc/“目录下找到，文件名称为init.cfg，采用json格式，文件大小目前限制在100KB以内。 +- init启动引导的配置文件 -init进程启动后读取/etc/init.cfg，然后解析其json格式内容，并根据解析结果依次加载系统服务。 + init启动引导组件配置文件包含了所有需要由init进程启动的系统关键服务的服务名、可执行文件路径、权限和其他信息，烧写单板后可在“/etc/“目录下找到，文件名称为init.cfg，采用json格式，文件大小目前限制在100KB以内。 -各模块需要添加关键服务时，也可以添加模块对应的cfg文件，编译时拷贝文件到/system/etc/init目录下，init进程会解析改cfg文件，并启动对应的服务。 + init进程启动后读取/etc/init.cfg，然后解析其json格式内容，并根据解析结果依次加载系统服务。 -## init服务启动控制(仅标准系统以上提供) + 各模块需要添加关键服务时，也可以添加模块对应的cfg文件，编译时拷贝文件到/system/etc/init目录下，init进程会解析改cfg文件，并启动对应的服务。 -init会根据用户的服务配置，把服务分成三类，在不同的阶段进行启动。 +- init服务启动控制(仅标准系统以上提供) -- “boot”类型：对应系统中需要优先启动的服务，这类服务在init完成init阶段后启动。 -- “normal”类型：默认配置，对应系统中的普通服务，这类服务在init命令执行完成后启动。 -- "condition"类型：对应有特殊要求的服务，可以直接通过start xxx 命令执行启动，一般在条件job或者在init的某个阶段使用命令启动。 + init会根据用户的服务配置，把服务分成三类，在不同的阶段进行启动。 -## init服务并行控制(仅标准系统以上提供) + - “boot”类型：对应系统中需要优先启动的服务，这类服务在init完成init阶段后启动。 + - “normal”类型：默认配置，对应系统中的普通服务，这类服务在init命令执行完成后启动。 + - "condition"类型：对应有特殊要求的服务，可以直接通过start xxx 命令执行启动，一般在条件job或者在init的某个阶段使用命令启动。 -init提供服务并行处理能力，启动服务在不同的阶段执行job的能力。 +- init服务并行控制(仅标准系统以上提供) -- “on-start”：在服务进程被fock后执行，不同服务的on-start job可以并行执行（在服务的子进程中执行，只对改进程产生影响）。 -- “on-stop”：在服务停止时执行。 -- "on-restart"：在服务重启时执行。 + init提供服务并行处理能力，启动服务在不同的阶段执行job的能力。 -## init 按需启动(仅标准系统以上提供) + - “on-start”：在服务进程被fock后执行，不同服务的on-start job可以并行执行（在服务的子进程中执行，只对改进程产生影响）。 + - “on-stop”：在服务停止时执行。 + - "on-restart"：在服务重启时执行。 -由init管理的服务支持按需启动，按需启动的服务不会在系统启动过程中主动被拉起，而是当某些事件发生时才会被init按需拉起，触发服务启动的事件可能是被init监听的相关socket有消息上报、samgr收到客户端的请求需要拉起SA服务等情况。 +- init 按需启动(仅标准系统以上提供) -"ondemand" 属性是按需启动的服务的标志，一个服务配置了该属性值为true的时候，服务不再需要配置start命令来拉起，而是被监听的相应事件发生时才会被拉起。 + 由init管理的服务支持按需启动，按需启动的服务不会在系统启动过程中主动被拉起，而是当某些事件发生时才会被init按需拉起，触发服务启动的事件可能是被init监听的相关socket有消息上报、samgr收到客户端的请求需要拉起SA服务等情况。 -* SA进程按需启动 -1. 应用请求SA句柄时samgr需识别SA所属进程是否可动态拉起 -2. 如需拉起，则需阻塞请求，等init拉起SA进程并注册SA后再返回所请求的SA句柄 + "ondemand" 属性是按需启动的服务的标志，一个服务配置了该属性值为true的时候，服务不再需要配置start命令来拉起，而是被监听的相应事件发生时才会被拉起。 -* socket进程按需启动 -1. init在pre-fork阶段为socket类进程创建好socket，init中监听创建好的socket上的网络事件 -2. socket上有报文事件后，init拉起socket进程进行报文处理，init进程取消socket数据的监听，由socket进程处理 -3. socket进程无报文处理后，可以自动退出，退出后init回收该子进程并重新监听socket网络数据 + - SA进程按需启动 + 1. 应用请求SA句柄时samgr需识别SA所属进程是否可动态拉起 + 2. 如需拉起，则需阻塞请求，等init拉起SA进程并注册SA后再返回所请求的SA句柄 -* 热插拔服务进程按需启动 -ueventd的监听到热插拔事件后，可触发系统参数变化，业务进程可根据系统参数的变化进行热插拔事件按需启动处理。 + - socket进程按需启动 + 1. init在pre-fork阶段为socket类进程创建好socket，init中监听创建好的socket上的网络事件 + 2. socket上有报文事件后，init拉起socket进程进行报文处理，init进程取消socket数据的监听，由socket进程处理 + 3. socket进程无报文处理后，可以自动退出，退出后init回收该子进程并重新监听socket网络数据 -## init 进程启动&回收能力增强 + - 热插拔服务进程按需启动 + 1. ueventd的监听到热插拔事件后，可触发系统参数变化，业务进程可根据系统参数的变化进行热插拔事件按需启动处理。 -进程启动时，支持在配置文件中配置服务进程的绑核、优先级、MAC信息以及AccessToken信息。 -- init提供修改*.cfg配置文件， 为服务进程提供cpu绑核功能 -- init提供修改*.cfg配置文件， 为服务进程提供优先级设置 -- init提供修改*.cfg配置文件， 为服务提供设置AccessToken, 为系统服务进程设置其分布式Capability能力（仅标准系统以上提供）。 -- init提供修改*.cfg配置文件， 为服务提供抑制机制。 +- init 进程启动&回收能力增强 -## init FD代持(仅标准系统以上提供) + 进程启动时，支持在配置文件中配置服务进程的绑核、优先级、MAC信息以及AccessToken信息。 -FD代持是按需启动的一个辅助扩展机制，按需启动进程可以保持退出前的fd状态句柄不丢失。按需启动进程退出前可将fd发送给init代持，再次启动后再从init获取fd。 + - init提供修改*.cfg配置文件， 为服务进程提供cpu绑核功能 + - init提供修改*.cfg配置文件， 为服务进程提供优先级设置 + - init提供修改*.cfg配置文件， 为服务提供设置AccessToken, 为系统服务进程设置其分布式Capability能力（仅标准系统以上提供）。 + - init提供修改*.cfg配置文件， 为服务提供抑制机制。 -init提供了相关接口供服务调用，服务进程退出前调用接口将fd通过支持IPC通信的socket发送给init代持，待该服务重新启动时，init将持有的该服务相关的fd句柄通过同样的方式返回给服务。 +- init FD代持(仅标准系统以上提供) -## init job + FD代持是按需启动的一个辅助扩展机制，按需启动进程可以保持退出前的fd状态句柄不丢失。按需启动进程退出前可将fd发送给init代持，再次启动后再从init获取fd。 -init提供job能力，一个job就是一组命令的集合。job可以在init.cfg中配置，也可以在模块的自定义cfg中配置。init解析程序会把相同名字job的命令合并到一个job中。同一名字的job只能保证init.cfg中的命令优先执行，其他cfg间的命令执行顺序不保证。 + init提供了相关接口供服务调用，服务进程退出前调用接口将fd通过支持IPC通信的socket发送给init代持，待该服务重新启动时，init将持有的该服务相关的fd句柄通过同样的方式返回给服务。 -- 普通job：一般是init启动的固定阶段，如“pre-init“，”init“，”post-init“等，这类job在init启动的固定阶段执行。 -- 自定义job：用户自定义的job，这类job按照一定的规则进行触发。 - - job：用户任意定义，可以通过trigger命令执行。 - - 控制job(仅标准系统以上提供)：按条件触发处理的能力。在job中可以设置触发条件，当对应的属性值满足设置的条件时，就会触发job执行。触发条件支持&&和||操作，可以根据不同的属性就行组合。 +- init job -## 开发指导 + init提供job能力，一个job就是一组命令的集合。job可以在init.cfg中配置，也可以在模块的自定义cfg中配置。init解析程序会把相同名字job的命令合并到一个job中。同一名字的job只能保证init.cfg中的命令优先执行，其他cfg间的命令执行顺序不保证。 -1. 配置jobs数组。 + - 普通job：一般是init启动的固定阶段，如“pre-init“，”init“，”post-init“等，这类job在init启动的固定阶段执行。 - init启动引导组件将系统启动分为三个阶段，这三个阶段： + - 自定义job：用户自定义的job，这类job按照一定的规则进行触发。 + - job：用户任意定义，可以通过trigger命令执行。 + - 控制job(仅标准系统以上提供)：按条件触发处理的能力。在job中可以设置触发条件，当对应的属性值满足设置的条件时，就会触发job执行。触发条件支持&&和||操作，可以根据不同的属性就行组合。 - - “pre-init”阶段：启动系统服务之前需要先执行的操作，例如挂载文件系统、创建文件夹、修改权限等。 - - “init”阶段：系统服务启动阶段。 - - “post-init”阶段：系统服务启动完后还需要执行的操作。 +## 开发指导 - ``` - "jobs" : [{ + 1. 配置jobs数组。 + + init启动引导组件将系统启动分为三个阶段，这三个阶段： + + - “pre-init”阶段：启动系统服务之前需要先执行的操作，例如挂载文件系统、创建文件夹、修改权限等。 + - “init”阶段：系统服务启动阶段。 + - “post-init”阶段：系统服务启动完后还需要执行的操作。 + +``` +"jobs" : [{ "name" : "pre-init", "cmds" : [ "mkdir /testdir", @@ -100,31 +115,100 @@ init提供job能力，一个job就是一组命令的集合。job可以在init.cf "cmds" : [] } ] - ``` - -表 1 执行job介绍 - -| job名 | 说明 | -| --------- | ------------------------------------------------------------ | -| pre-init | 最先执行的job，如果开发者的进程在启动之前需要首先执行一些操作（例如创建文件夹），可以把操作放到pre-init中先执行。 | -| init | 中间执行的job，例如服务启动。 | -| post-init | 最后被执行的job，如果开发者的进程在启动完成之后需要有一些处理（如驱动初始化后再挂载设备），可以把这类操作放到该job执行。 | - -表 2 命令集说明 +``` -| 命令 | 命令格式和示例 | 说明 | -| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| mkdir | mkdir 目标文件夹如：mkdir /storage/myDirectory | 创建文件夹命令，mkdir和目标文件夹之间有且只能有一个空格。 | -| chmod | chmod 权限 目标如：chmod 0600 /storage/myFile.txtchmod 0750 /storage/myDir | 修改权限命令，chmod权限目标之间间隔有且仅有一个空格，权限必须为0xxx格式。 | -| chown | chown uid gid 目标如：chown 900 800 /storage/myDirchown 100 100 /storage/myFile.txt | 修改属组命令，chown uid gid目标之间间隔有且仅有一个空格。 | -| mount | mount fileSystemType src dst flags data如：mount vfat /dev/mmcblk0 /sdc rw,umask=000mount jffs2 /dev/mtdblock3 /storage nosuid | 挂载命令，各参数之间有且仅有一个空格。flags当前仅支持nodev、noexec、nosuid、rdonly，data为可选字段。 | -| start | start serviceName如：start foundationstart shell | 启动服务命令，start后面跟着service名称，该service名称必须能够在services数组中找到。 | -| loadcfg | loadcfg filePath如：loadcfg /patch/fstab.cfg | 加载其他cfg文件命令。后面跟着的目标文件大小不得超过50KB，且目前仅支持加载/patch/fstab.cfg，其他文件路径和文件名均不支持。/patch/fstab.cfg文件的每一行都是一条命令，命令类型和格式必须符合本表格描述，命令条数不得超过20条。 | +**表 1** 执行job介绍 + + + + + + + + + + + + + + +

job名

+

说明

+

pre-init

+

最先执行的job，如果开发者的进程在启动之前需要首先执行一些操作（例如创建文件夹），可以把操作放到pre-init中先执行。

+

init

+

中间执行的job，例如服务启动。

+

post-init

+

最后被执行的job，如果开发者的进程在启动完成之后需要有一些处理（如驱动初始化后再挂载设备），可以把这类操作放到该job执行。单个job最多支持30条命令（当前仅支持start/mkdir/chmod/chown/mount/loadcfg），命令名称和后面的参数（参数长度≤128字节）之间有且只能有一个空格。

+
+**表 2** 命令集说明 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

命令

+

命令格式和示例

+

说明

+

mkdir

+

mkdir 目标文件夹

+

如：mkdir /storage/myDirectory

+

创建文件夹命令，mkdir和目标文件夹之间有且只能有一个空格。

+

chmod

+

chmod 权限 目标

+

如：chmod 0600 /storage/myFile.txt

+

chmod 0750 /storage/myDir

+

修改权限命令，chmod权限目标之间间隔有且仅有一个空格，权限必须为0xxx格式。

+

chown

+

chown uid gid 目标

+

如：chown 900 800 /storage/myDir

+

chown 100 100 /storage/myFile.txt

+

修改属组命令，chown uid gid目标之间间隔有且仅有一个空格。

+

mount

+

mount fileSystemType src dst flags data

+

如：mount vfat /dev/mmcblk0 /sdc rw,umask=000

+

mount jffs2 /dev/mtdblock3 /storage nosuid

+

挂载命令，各参数之间有且仅有一个空格。flags当前仅支持nodev、noexec、nosuid、rdonly，data为可选字段。

+

start

+

start serviceName

+

如：start foundation

+

start shell

+

启动服务命令，start后面跟着service名称，该service名称必须能够在services数组中找到。

+

loadcfg

+

loadcfg filePath

+

如：loadcfg /patch/fstab.cfg

+

加载其他cfg文件命令。后面跟着的目标文件大小不得超过50KB，且目前仅支持加载/patch/fstab.cfg，其他文件路径和文件名均不支持。/patch/fstab.cfg文件的每一行都是一条命令，命令类型和格式必须符合本表格描述，命令条数不得超过20条。

+
-2. 配置services数组，service集合（数组形式），包含了init进程需要启动的所有系统服务（最多支持100个）。 + 2. 配置services数组，service集合（数组形式），包含了init进程需要启动的所有系统服务（最多支持100个）。 - ``` +``` "services" : [{ "name" : "service1", "path" : ["/bin/process1", "param1", "param2"], @@ -157,13 +241,11 @@ init提供job能力，一个job就是一组命令的集合。job可以在init.cf "apl" : "normal", "d-caps" : [ ] }] - ``` - - **表 3** service字段说明 +``` - +**表 3** service字段说明 -

字段名

+ @@ -210,7 +292,7 @@ init提供job能力，一个job就是一组命令的集合。job可以在init.cf - @@ -246,9 +328,18 @@ init提供job能力，一个job就是一组命令的集合。job可以在init.cf

字段名

说明

critical

critical服务启动失败后， 需要M秒内重新拉起， 拉起失败N次后， 直接重启系统， N默认为4， M默认20。（仅标准系统以上提供 "critical" : [0, 2, 10]）

+

critical服务启动失败后， 需要M秒内重新拉起， 拉起失败N次后， 直接重启系统， N默认为4， M默认20。（仅标准系统以上提供 "critical" : [0, 2, 10]; 类型为int型数组)

0：不使能；

1：使能。
-## 开发实例 + **表 4** 接口介绍 + + | 函数名 | 函数解释 |参数解释 | + | :---------- | :---------- |:--------| + | int *ServiceGetFd(const char *serviceName, size_t *outfdCount) | 获取init代持的fd | 返回值：成功返回fd数组指针，失败返回NULL。备注：需手动释放
参数：
serviceName: 服务名
outfdCount: 返回的fd数组长度 | + | int ServiceSaveFd(const char *serviceName, int *fds, int fdCount) | 请求init代持fd | 返回值：成功返回0，失败返回-1
参数：
serviceName: 服务名
fds: 需要init代持的fd数组指针
fdCount: fd数组长度 + | int ServiceControlWithExtra(const char *serviceName, int action, const char *extArgv[], int extArgc) | 配置服务参数 | 返回值：成功返回0，失败返回-1
参数:
serviceName: 服务名
action: 服务行为（"start", "stop", "restart"）
extArgv: 参数数组
extArgc: 参数个数 + | int ServiceControl(const char *serviceName, int action) | 控制服务行为 | 返回值：成功返回0，失败返回-1
参数：
serviceName: 服务名
action: 服务行为（"start"， "stop", "restart") -init启动引导程序，此处以要新增一个名为MySystemApp的系统服务为例进行说明，使用如下配置： +## 开发实例 + + init启动引导程序，此处以要新增一个名为MySystemApp的系统服务为例进行说明，使用如下配置： ``` { @@ -294,4 +385,34 @@ init启动引导程序，此处以要新增一个名为MySystemApp的系统服 1. 启动后使用task -a（liteos-a版本）或ps命令（linux版本）查看是否MySystemApp系统服务进程已启动。 2. 使用kill命令将上述新增的MySystemApp进程杀死，观察该进程是否会被重新拉起（此处应该为重新拉起）。 -3. 使用kill命令将上述新增的MySystemApp进程杀死，观察是否会导致单板重启（此处应该为不重启）。 \ No newline at end of file +3. 使用kill命令将上述新增的MySystemApp进程杀死，观察是否会导致单板重启（此处应该为不重启）。 + +## 常见问题 + +### 服务不存在 + +- **现象描述** + + 内核Log打印 "Failed get servName" + +- **解决方法** + 1. 确认服务是否在cfg中正确配置 + 2. 服务的cfg文件是否正常加载 + 3. cfg文件格式是否正确 + +### 请求其他服务代持fd，init有报错 + +- **现象描述** + + 内核Log打印 "Service \' xxx \'(pid = xxx) is not valid or request with unexpected process(pid = xxx)" + +- **解决方法** + 只支持代持本服务的fd， 不允许让其他服务代持fd + +### 服务没有配置ondemand 选项 + +- **现象描述** + 内核Log打印 "service : %s had started already" + +- **解决方法** + 服务对应的.cfg文件正确配置如： "ondemand" : true \ No newline at end of file