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

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

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

Actions take the form of:

on <trigger>

on <trigger> [&& <trigger>]*

   <command>

   <command>

   <command>

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

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>

   it will be truncated. Properties are expanded within <content>.

Properties

----------

Init updates some system properties to provide some insight into

what it's doing:

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

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.

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", "running", "restarting")

   State of a named service ("stopped", "stopping", "running", "restarting")

Bootcharting