diff --git a/init/README.md b/init/README.md new file mode 100644 index 000000000..cef0dbc43 --- /dev/null +++ b/init/README.md @@ -0,0 +1,560 @@ +Android Init Language +--------------------- + +The Android Init Language consists of five broad classes of statements: +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 plain text 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. + +One may specify paths in the mount\_all command line to have it import +.rc files at the specified paths instead of the default ones listed above. +This is primarily for supporting factory mode and other non-standard boot +modes. The three default paths should be used for the normal boot process. + +The intention of these directories is: + + 1. /system/etc/init/ is for core system items such as + SurfaceFlinger, MediaService, and logcatd. + 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. + +All services whose binaries reside on the system, vendor, or odm +partitions should have their service entries placed into a +corresponding init .rc file, located in the /etc/init/ +directory of the partition where they reside. There is a build +system macro, LOCAL\_INIT\_RC, that handles this for developers. Each +init .rc file should additionally contain any actions associated with +its service. + +An example is the logcatd.rc and Android.mk files located in the +system/core/logcat directory. The LOCAL\_INIT\_RC macro in the +Android.mk file places logcatd.rc in /system/etc/init/ during the +build process. Init loads logcatd.rc during the mount\_all command and +allows the service to be run and the action to be queued when +appropriate. + +This break up of init .rc files according to their daemon is preferred +to the previously used monolithic init .rc files. This approach +ensures that the only service entries that init reads and the only +actions that init performs correspond to services whose binaries are in +fact present on the file system, which was not the case with the +monolithic init .rc files. This additionally will aid in merge +conflict resolution when multiple services are added to the system, as +each one will go into a separate file. + +There are two options "early" and "late" in mount\_all command +which can be set after optional paths. With "--early" set, the +init executable will skip mounting entries with "latemount" flag +and triggering fs encryption state event. With "--late" set, +init executable will only mount entries with "latemount" flag but skip +importing rc files. By default, no option is set, and mount\_all will +process all entries in the given fstab. + +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 [&& ]* + + + + + +Services +-------- +Services are programs which init launches and (optionally) restarts +when they exit. Services take the form of: + + service [ ]* +