478 lines
17 KiB
Plaintext
478 lines
17 KiB
Plaintext
|
|
Android Init Language
|
|
---------------------
|
|
|
|
The Android Init Language consists of five broad classes of statements,
|
|
which are Actions, Commands, Services, Options, and Imports.
|
|
|
|
All of these are line-oriented, consisting of tokens separated by
|
|
whitespace. The c-style backslash escapes may be used to insert
|
|
whitespace into a token. Double quotes may also be used to prevent
|
|
whitespace from breaking text into multiple tokens. The backslash,
|
|
when it is the last character on a line, may be used for line-folding.
|
|
|
|
Lines which start with a # (leading whitespace allowed) are comments.
|
|
|
|
Actions and Services implicitly declare a new section. All commands
|
|
or options belong to the section most recently declared. Commands
|
|
or options before the first section are ignored.
|
|
|
|
Actions and Services have unique names. If a second Action is defined
|
|
with the same name as an existing one, its commands are appended to
|
|
the commands of the existing action. If a second Service is defined
|
|
with the same name as an existing one, it is ignored and an error
|
|
message is logged.
|
|
|
|
|
|
Init .rc Files
|
|
--------------
|
|
The init language is used in plaintext files that take the .rc file
|
|
extension. These are typically multiple of these in multiple
|
|
locations on the system, described below.
|
|
|
|
/init.rc is the primary .rc file and is loaded by the init executable
|
|
at the beginning of its execution. It is responsible for the initial
|
|
set up of the system. It imports /init.${ro.hardware}.rc which is the
|
|
primary vendor supplied .rc file.
|
|
|
|
During the mount_all command, the init executable loads all of the
|
|
files contained within the /{system,vendor,odm}/etc/init/ directories.
|
|
These directories are intended for all Actions and Services used after
|
|
file system mounting.
|
|
|
|
The intention of these directories is as follows
|
|
1) /system/etc/init/ is for core system items such as
|
|
SurfaceFlinger and MediaService.
|
|
2) /vendor/etc/init/ is for SoC vendor items such as actions or
|
|
daemons needed for core SoC functionality.
|
|
3) /odm/etc/init/ is for device manufacturer items such as
|
|
actions or daemons needed for motion sensor or other peripheral
|
|
functionality.
|
|
|
|
|
|
Actions
|
|
-------
|
|
Actions are named sequences of commands. Actions have a trigger which
|
|
is used to determine when the action should occur. When an event
|
|
occurs which matches an action's trigger, that action is added to
|
|
the tail of a to-be-executed queue (unless it is already on the
|
|
queue).
|
|
|
|
Each action in the queue is dequeued in sequence and each command in
|
|
that action is executed in sequence. Init handles other activities
|
|
(device creation/destruction, property setting, process restarting)
|
|
"between" the execution of the commands in activities.
|
|
|
|
Actions take the form of:
|
|
|
|
on <trigger> [&& <trigger>]*
|
|
<command>
|
|
<command>
|
|
<command>
|
|
|
|
|
|
Services
|
|
--------
|
|
Services are programs which init launches and (optionally) restarts
|
|
when they exit. Services take the form of:
|
|
|
|
service <name> <pathname> [ <argument> ]*
|
|
<option>
|
|
<option>
|
|
...
|
|
|
|
|
|
Options
|
|
-------
|
|
Options are modifiers to services. They affect how and when init
|
|
runs the service.
|
|
|
|
critical
|
|
This is a device-critical service. If it exits more than four times in
|
|
four minutes, the device will reboot into recovery mode.
|
|
|
|
disabled
|
|
This service will not automatically start with its class.
|
|
It must be explicitly started by name.
|
|
|
|
setenv <name> <value>
|
|
Set the environment variable <name> to <value> in the launched process.
|
|
|
|
socket <name> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ]
|
|
Create a unix domain socket named /dev/socket/<name> and pass
|
|
its fd to the launched process. <type> must be "dgram", "stream" or "seqpacket".
|
|
User and group default to 0.
|
|
'seclabel' is the SELinux security context for the socket.
|
|
It defaults to the service security context, as specified by seclabel or
|
|
computed based on the service executable file security context.
|
|
|
|
user <username>
|
|
Change to username before exec'ing this service.
|
|
Currently defaults to root. (??? probably should default to nobody)
|
|
As of Android M, processes should use this option even if they
|
|
require linux capabilities. Previously, to acquire linux
|
|
capabilities, a process would need to run as root, request the
|
|
capabilities, then drop to its desired uid. There is a new
|
|
mechanism through fs_config that allows device manufacturers to add
|
|
linux capabilities to specific binaries on a file system that should
|
|
be used instead. This mechanism is described on
|
|
http://source.android.com/devices/tech/config/filesystem.html. When
|
|
using this new mechanism, processes can use the user option to
|
|
select their desired uid without ever running as root.
|
|
|
|
group <groupname> [ <groupname> ]*
|
|
Change to groupname before exec'ing this service. Additional
|
|
groupnames beyond the (required) first one are used to set the
|
|
supplemental groups of the process (via setgroups()).
|
|
Currently defaults to root. (??? probably should default to nobody)
|
|
|
|
seclabel <seclabel>
|
|
Change to 'seclabel' before exec'ing this service.
|
|
Primarily for use by services run from the rootfs, e.g. ueventd, adbd.
|
|
Services on the system partition can instead use policy-defined transitions
|
|
based on their file security context.
|
|
If not specified and no transition is defined in policy, defaults to the init context.
|
|
|
|
oneshot
|
|
Do not restart the service when it exits.
|
|
|
|
class <name>
|
|
Specify a class name for the service. All services in a
|
|
named class may be started or stopped together. A service
|
|
is in the class "default" if one is not specified via the
|
|
class option.
|
|
|
|
onrestart
|
|
Execute a Command (see below) when service restarts.
|
|
|
|
writepid <file...>
|
|
Write the child's pid to the given files when it forks. Meant for
|
|
cgroup/cpuset usage.
|
|
|
|
|
|
Triggers
|
|
--------
|
|
Triggers are strings which can be used to match certain kinds of
|
|
events and used to cause an action to occur.
|
|
|
|
Triggers are subdivided into event triggers and property triggers.
|
|
|
|
Event triggers are strings triggered by the 'trigger' command or by
|
|
the QueueEventTrigger() function within the init executable. These
|
|
take the form of a simple string such as 'boot' or 'late-init'.
|
|
|
|
Property triggers are strings triggered when a named property changes
|
|
value to a given new value or when a named property changes value to
|
|
any new value. These take the form of 'property:<name>=<value>' and
|
|
'property:<name>=*' respectively. Property triggers are additionally
|
|
evaluated and triggered accordingly during the initial boot phase of
|
|
init.
|
|
|
|
An Action can have multiple property triggers but may only have one
|
|
event trigger.
|
|
|
|
For example:
|
|
'on boot && property:a=b' defines an action that is only executed when
|
|
the 'boot' event trigger happens and the property a equals b.
|
|
|
|
'on property:a=b && property:c=d' defines an action that is executed
|
|
at three times,
|
|
1) During initial boot if property a=b and property c=d
|
|
2) Any time that property a transitions to value b, while property
|
|
c already equals d.
|
|
3) Any time that property c transitions to value d, while property
|
|
a already equals b.
|
|
|
|
|
|
Commands
|
|
--------
|
|
|
|
bootchart_init
|
|
Start bootcharting if configured (see below).
|
|
This is included in the default init.rc.
|
|
|
|
chmod <octal-mode> <path>
|
|
Change file access permissions.
|
|
|
|
chown <owner> <group> <path>
|
|
Change file owner and group.
|
|
|
|
class_start <serviceclass>
|
|
Start all services of the specified class if they are
|
|
not already running.
|
|
|
|
class_stop <serviceclass>
|
|
Stop and disable all services of the specified class if they are
|
|
currently running.
|
|
|
|
class_reset <serviceclass>
|
|
Stop all services of the specified class if they are
|
|
currently running, without disabling them. They can be restarted
|
|
later using class_start.
|
|
|
|
copy <src> <dst>
|
|
Copies a file. Similar to write, but useful for binary/large
|
|
amounts of data.
|
|
|
|
domainname <name>
|
|
Set the domain name.
|
|
|
|
enable <servicename>
|
|
Turns a disabled service into an enabled one as if the service did not
|
|
specify disabled.
|
|
If the service is supposed to be running, it will be started now.
|
|
Typically used when the bootloader sets a variable that indicates a specific
|
|
service should be started when needed. E.g.
|
|
on property:ro.boot.myfancyhardware=1
|
|
enable my_fancy_service_for_my_fancy_hardware
|
|
|
|
exec [ <seclabel> [ <user> [ <group> ]* ] ] -- <command> [ <argument> ]*
|
|
Fork and execute command with the given arguments. The command starts
|
|
after "--" so that an optional security context, user, and supplementary
|
|
groups can be provided. No other commands will be run until this one
|
|
finishes. <seclabel> can be a - to denote default.
|
|
|
|
export <name> <value>
|
|
Set the environment variable <name> equal to <value> in the
|
|
global environment (which will be inherited by all processes
|
|
started after this command is executed)
|
|
|
|
hostname <name>
|
|
Set the host name.
|
|
|
|
ifup <interface>
|
|
Bring the network interface <interface> online.
|
|
|
|
insmod <path>
|
|
Install the module at <path>
|
|
|
|
load_all_props
|
|
Loads properties from /system, /vendor, et cetera.
|
|
This is included in the default init.rc.
|
|
|
|
load_persist_props
|
|
Loads persistent properties when /data has been decrypted.
|
|
This is included in the default init.rc.
|
|
|
|
loglevel <level>
|
|
Sets the kernel log level to level. Properties are expanded within <level>.
|
|
|
|
mkdir <path> [mode] [owner] [group]
|
|
Create a directory at <path>, optionally with the given mode, owner, and
|
|
group. If not provided, the directory is created with permissions 755 and
|
|
owned by the root user and root group. If provided, the mode, owner and group
|
|
will be updated if the directory exists already.
|
|
|
|
mount_all <fstab>
|
|
Calls fs_mgr_mount_all on the given fs_mgr-format fstab.
|
|
|
|
mount <type> <device> <dir> [ <flag> ]* [<options>]
|
|
Attempt to mount the named device at the directory <dir>
|
|
<device> may be of the form mtd@name to specify a mtd block
|
|
device by name.
|
|
<flag>s include "ro", "rw", "remount", "noatime", ...
|
|
<options> include "barrier=1", "noauto_da_alloc", "discard", ... as
|
|
a comma separated string, eg: barrier=1,noauto_da_alloc
|
|
|
|
powerctl
|
|
Internal implementation detail used to respond to changes to the
|
|
"sys.powerctl" system property, used to implement rebooting.
|
|
|
|
restart <service>
|
|
Like stop, but doesn't disable the service.
|
|
|
|
restorecon <path> [ <path> ]*
|
|
Restore the file named by <path> to the security context specified
|
|
in the file_contexts configuration.
|
|
Not required for directories created by the init.rc as these are
|
|
automatically labeled correctly by init.
|
|
|
|
restorecon_recursive <path> [ <path> ]*
|
|
Recursively restore the directory tree named by <path> to the
|
|
security contexts specified in the file_contexts configuration.
|
|
|
|
rm <path>
|
|
Calls unlink(2) on the given path. You might want to
|
|
use "exec -- rm ..." instead (provided the system partition is
|
|
already mounted).
|
|
|
|
rmdir <path>
|
|
Calls rmdir(2) on the given path.
|
|
|
|
setprop <name> <value>
|
|
Set system property <name> to <value>. Properties are expanded
|
|
within <value>.
|
|
|
|
setrlimit <resource> <cur> <max>
|
|
Set the rlimit for a resource.
|
|
|
|
start <service>
|
|
Start a service running if it is not already running.
|
|
|
|
stop <service>
|
|
Stop a service from running if it is currently running.
|
|
|
|
swapon_all <fstab>
|
|
Calls fs_mgr_swapon_all on the given fstab file.
|
|
|
|
symlink <target> <path>
|
|
Create a symbolic link at <path> with the value <target>
|
|
|
|
sysclktz <mins_west_of_gmt>
|
|
Set the system clock base (0 if system clock ticks in GMT)
|
|
|
|
trigger <event>
|
|
Trigger an event. Used to queue an action from another
|
|
action.
|
|
|
|
verity_load_state
|
|
Internal implementation detail used to load dm-verity state.
|
|
|
|
verity_update_state <mount_point>
|
|
Internal implementation detail used to update dm-verity state and
|
|
set the partition.<mount_point>.verified properties used by adb remount
|
|
because fs_mgr can't set them directly itself.
|
|
|
|
wait <path> [ <timeout> ]
|
|
Poll for the existence of the given file and return when found,
|
|
or the timeout has been reached. If timeout is not specified it
|
|
currently defaults to five seconds.
|
|
|
|
write <path> <content>
|
|
Open the file at <path> and write a string to it with write(2).
|
|
If the file does not exist, it will be created. If it does exist,
|
|
it will be truncated. Properties are expanded within <content>.
|
|
|
|
|
|
Imports
|
|
-------
|
|
The import keyword is not a command, but rather its own section and is
|
|
handled immediately after the .rc file that contains it has finished
|
|
being parsed. It takes the below form:
|
|
|
|
import <path>
|
|
Parse an init config file, extending the current configuration.
|
|
If <path> is a directory, each file in the directory is parsed as
|
|
a config file. It is not recursive, nested directories will
|
|
not be parsed.
|
|
|
|
There are only two times where the init executable imports .rc files,
|
|
1) When it imports /init.rc during initial boot
|
|
2) When it imports /{system,vendor,odm}/etc/init/ during mount_all
|
|
|
|
|
|
Properties
|
|
----------
|
|
Init provides information about the services that it is responsible
|
|
for via the below properties.
|
|
|
|
init.svc.<name>
|
|
State of a named service ("stopped", "stopping", "running", "restarting")
|
|
|
|
|
|
Bootcharting
|
|
------------
|
|
This version of init contains code to perform "bootcharting": generating log
|
|
files that can be later processed by the tools provided by www.bootchart.org.
|
|
|
|
On the emulator, use the -bootchart <timeout> option to boot with bootcharting
|
|
activated for <timeout> seconds.
|
|
|
|
On a device, create /data/bootchart/start with a command like the following:
|
|
|
|
adb shell 'echo $TIMEOUT > /data/bootchart/start'
|
|
|
|
Where the value of $TIMEOUT corresponds to the desired bootcharted period in
|
|
seconds. Bootcharting will stop after that many seconds have elapsed.
|
|
You can also stop the bootcharting at any moment by doing the following:
|
|
|
|
adb shell 'echo 1 > /data/bootchart/stop'
|
|
|
|
Note that /data/bootchart/stop is deleted automatically by init at the end of
|
|
the bootcharting. This is not the case with /data/bootchart/start, so don't
|
|
forget to delete it when you're done collecting data.
|
|
|
|
The log files are written to /data/bootchart/. A script is provided to
|
|
retrieve them and create a bootchart.tgz file that can be used with the
|
|
bootchart command-line utility:
|
|
|
|
sudo apt-get install pybootchartgui
|
|
# grab-bootchart.sh uses $ANDROID_SERIAL.
|
|
$ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh
|
|
|
|
One thing to watch for is that the bootchart will show init as if it started
|
|
running at 0s. You'll have to look at dmesg to work out when the kernel
|
|
actually started init.
|
|
|
|
|
|
Comparing two bootcharts
|
|
------------------------
|
|
A handy script named compare-bootcharts.py can be used to compare the
|
|
start/end time of selected processes. The aforementioned grab-bootchart.sh
|
|
will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart.
|
|
If two such barballs are preserved on the host machine under different
|
|
directories, the script can list the timestamps differences. For example:
|
|
|
|
Usage: system/core/init/compare-bootcharts.py base_bootchart_dir
|
|
exp_bootchart_dir
|
|
|
|
process: baseline experiment (delta)
|
|
- Unit is ms (a jiffy is 10 ms on the system)
|
|
------------------------------------
|
|
/init: 50 40 (-10)
|
|
/system/bin/surfaceflinger: 4320 4470 (+150)
|
|
/system/bin/bootanimation: 6980 6990 (+10)
|
|
zygote64: 10410 10640 (+230)
|
|
zygote: 10410 10640 (+230)
|
|
system_server: 15350 15150 (-200)
|
|
bootanimation ends at: 33790 31230 (-2560)
|
|
|
|
|
|
Systrace
|
|
--------
|
|
Systrace [1] can be used for obtaining performance analysis reports during boot
|
|
time on userdebug or eng builds.
|
|
Here is an example of trace events of "wm" and "am" categories:
|
|
|
|
$ANDROID_BUILD_TOP/external/chromium-trace/systrace.py wm am --boot
|
|
|
|
This command will cause the device to reboot. After the device is rebooted and
|
|
the boot sequence has finished, the trace report is obtained from the device
|
|
and written as trace.html on the host by hitting Ctrl+C.
|
|
|
|
LIMITATION
|
|
Recording trace events is started after persistent properties are loaded, so
|
|
the trace events that are emitted before that are not recorded. Several
|
|
services such as vold, surfaceflinger, and servicemanager are affected by this
|
|
limitation since they are started before persistent properties are loaded.
|
|
Zygote initialization and the processes that are forked from the zygote are not
|
|
affected.
|
|
|
|
[1] http://developer.android.com/tools/help/systrace.html
|
|
|
|
|
|
Debugging init
|
|
--------------
|
|
By default, programs executed by init will drop stdout and stderr into
|
|
/dev/null. To help with debugging, you can execute your program via the
|
|
Android program logwrapper. This will redirect stdout/stderr into the
|
|
Android logging system (accessed via logcat).
|
|
|
|
For example
|
|
service akmd /system/bin/logwrapper /sbin/akmd
|
|
|
|
For quicker turnaround when working on init itself, use:
|
|
|
|
mm -j
|
|
m ramdisk-nodeps
|
|
m bootimage-nodeps
|
|
adb reboot bootloader
|
|
fastboot boot $ANDROID_PRODUCT_OUT/boot.img
|
|
|
|
Alternatively, use the emulator:
|
|
|
|
emulator -partition-size 1024 -verbose -show-kernel -no-window
|
|
|
|
You might want to call klog_set_level(6) after the klog_init() call
|
|
so you see the kernel logging in dmesg (or the emulator output).
|