diff --git a/init/readme.txt b/init/readme.txt index d70c6f3e2..bf440c2b7 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 @@ 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 -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 @@ that action is executed in sequence. Init handles other activities Actions take the form of: -on +on [&& ]* @@ -117,25 +145,36 @@ writepid 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. -= - Triggers of this form occur when the property is set - to the specific 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:=' and +'property:=*' 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 @@ hostname ifup Bring the network interface online. -import - Parse an init config file, extending the current configuration. - If 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 Install the module at @@ -304,19 +337,30 @@ write it will be truncated. Properties are expanded within . +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 + Parse an init config file, extending the current configuration. + If 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. - State of a named service ("stopped", "running", "restarting") + State of a named service ("stopped", "stopping", "running", "restarting") Bootcharting