Merge "init: Update readme.txt to reflect recent changes to init."

init/readme.txt

@@ -2,8 +2,8 @@
 Android Init Language
 ---------------------
 
-The Android Init Language consists of four broad classes of statements,
+The Android Init Language consists of five broad classes of statements,
-which are Actions, Commands, Services, and Options.
+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 @@ 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 or Service
+Actions and Services have unique names.  If a second Action is defined
-is declared with the same name as an existing one, it is ignored as
+with the same name as an existing one, its commands are appended to
-an error.  (??? should we override instead)
+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 @@ that action is executed in sequence.  Init handles other activities
 
 Actions take the form of:
 
-on <trigger>
+on <trigger> [&& <trigger>]*
    <command>
    <command>
    <command>
@@ -117,25 +145,36 @@ writepid <file...>
 
 Triggers
 --------
-Triggers are strings which can be used to match certain kinds
+Triggers are strings which can be used to match certain kinds of
-of events and used to cause an action to occur.
+events and used to cause an action to occur.
 
-boot
+Triggers are subdivided into event triggers and property triggers.
-   This is the first trigger that will occur when init starts
-   (after /init.conf is loaded)
 
-<name>=<value>
+Event triggers are strings triggered by the 'trigger' command or by
-   Triggers of this form occur when the property <name> is set
+the QueueEventTrigger() function within the init executable.  These
-   to the specific value <value>.
+take the form of a simple string such as 'boot' or 'late-init'.
 
-   One can also test multiple properties to execute a group
+Property triggers are strings triggered when a named property changes
-   of commands. For example:
+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
+An Action can have multiple property triggers but may only have one
-       setprop test.c 1
+event trigger.
 
-   The above stub sets test.c to 1 only when
+For example:
-   both test.a=1 and test.b=1
+'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 @@ hostname <name>
 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 @@ write <path> <content>
    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
+Init provides information about the services that it is responsible
-what it's doing:
+for via the below properties.
-
-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.svc.<name>
-   State of a named service ("stopped", "running", "restarting")
+   State of a named service ("stopped", "stopping", "running", "restarting")
 
 
 Bootcharting