Merge "metricsd: Make the unit tests pass."
diff --git a/init/readme.txt b/init/readme.txt
index d70c6f3..bf440c2 100644
--- a/init/readme.txt
+++ b/init/readme.txt
@@ -2,8 +2,8 @@
Android Init Language
---------------------
-The Android Init Language consists of four broad classes of statements,
-which are Actions, Commands, Services, and Options.
+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
@@ -17,9 +17,37 @@
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 or Service
-is declared with the same name as an existing one, it is ignored as
-an error. (??? should we override instead)
+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
@@ -37,7 +65,7 @@
Actions take the form of:
-on <trigger>
+on <trigger> [&& <trigger>]*
<command>
<command>
<command>
@@ -117,25 +145,36 @@
Triggers
--------
-Triggers are strings which can be used to match certain kinds
-of events and used to cause an action to occur.
+Triggers are strings which can be used to match certain kinds of
+events and used to cause an action to occur.
-boot
- This is the first trigger that will occur when init starts
- (after /init.conf is loaded)
+Triggers are subdivided into event triggers and property triggers.
-<name>=<value>
- Triggers of this form occur when the property <name> is set
- to the specific value <value>.
+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'.
- One can also test multiple properties to execute a group
- of commands. For example:
+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.
- on property:test.a=1 && property:test.b=1
- setprop test.c 1
+An Action can have multiple property triggers but may only have one
+event trigger.
- The above stub sets test.c to 1 only when
- both test.a=1 and test.b=1
+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
@@ -197,12 +236,6 @@
ifup <interface>
Bring the network interface <interface> online.
-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.
-
insmod <path>
Install the module at <path>
@@ -304,19 +337,30 @@
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 updates some system properties to provide some insight into
-what it's doing:
-
-init.action
- Equal to the name of the action currently being executed or "" if none
-
-init.command
- Equal to the command being executed or "" if none.
+Init provides information about the services that it is responsible
+for via the below properties.
init.svc.<name>
- State of a named service ("stopped", "running", "restarting")
+ State of a named service ("stopped", "stopping", "running", "restarting")
Bootcharting
