Home | History | Annotate | only in /system/core/init
Up to higher level directory
NameDateSize
action.cpp06-Dec-201612.5K
action.h06-Dec-20164.2K
Android.mk06-Dec-20162.7K
bootchart.cpp06-Dec-20168.1K
bootchart.h06-Dec-2016826
builtins.cpp06-Dec-201632.2K
builtins.h06-Dec-2016978
compare-bootcharts.py06-Dec-20165.3K
devices.cpp06-Dec-201626.7K
devices.h06-Dec-20161K
grab-bootchart.sh06-Dec-2016636
import_parser.cpp06-Dec-20161.6K
import_parser.h06-Dec-20161.3K
init.cpp06-Dec-201622.6K
init.h06-Dec-20161.2K
init_parser.cpp06-Dec-20164.6K
init_parser.h06-Dec-20161.7K
init_parser_test.cpp06-Dec-20164.2K
keychords.cpp06-Dec-20163.4K
keychords.h06-Dec-2016760
keyword_map.h06-Dec-20162.6K
log.cpp06-Dec-20162.1K
log.h06-Dec-20161.2K
MODULE_LICENSE_APACHE206-Dec-20160
NOTICE06-Dec-201610.4K
parser/06-Dec-2016
parser.cpp06-Dec-20163.1K
parser.h06-Dec-20161.1K
perfboot.py06-Dec-201615.8K
property_service.cpp06-Dec-201615.9K
property_service.h06-Dec-20161.1K
readme.txt06-Dec-201619K
service.cpp06-Dec-201626.3K
service.h06-Dec-20167.5K
signal_handler.cpp06-Dec-20162.1K
signal_handler.h06-Dec-2016726
ueventd.cpp06-Dec-20164.1K
ueventd.h06-Dec-20161,013
ueventd_keywords.h06-Dec-2016356
ueventd_parser.cpp06-Dec-20166K
ueventd_parser.h06-Dec-2016925
util.cpp06-Dec-201614.8K
util.h06-Dec-20162.1K
util_test.cpp06-Dec-20161.2K
watchdogd.cpp06-Dec-20162K
watchdogd.h06-Dec-2016727

readme.txt

      1 Android Init Language
      2 ---------------------
      3 
      4 The Android Init Language consists of five broad classes of statements,
      5 which are Actions, Commands, Services, Options, and Imports.
      6 
      7 All of these are line-oriented, consisting of tokens separated by
      8 whitespace.  The c-style backslash escapes may be used to insert
      9 whitespace into a token.  Double quotes may also be used to prevent
     10 whitespace from breaking text into multiple tokens.  The backslash,
     11 when it is the last character on a line, may be used for line-folding.
     12 
     13 Lines which start with a # (leading whitespace allowed) are comments.
     14 
     15 Actions and Services implicitly declare a new section.  All commands
     16 or options belong to the section most recently declared.  Commands
     17 or options before the first section are ignored.
     18 
     19 Actions and Services have unique names.  If a second Action is defined
     20 with the same name as an existing one, its commands are appended to
     21 the commands of the existing action.  If a second Service is defined
     22 with the same name as an existing one, it is ignored and an error
     23 message is logged.
     24 
     25 
     26 Init .rc Files
     27 --------------
     28 The init language is used in plaintext files that take the .rc file
     29 extension.  These are typically multiple of these in multiple
     30 locations on the system, described below.
     31 
     32 /init.rc is the primary .rc file and is loaded by the init executable
     33 at the beginning of its execution.  It is responsible for the initial
     34 set up of the system.  It imports /init.${ro.hardware}.rc which is the
     35 primary vendor supplied .rc file.
     36 
     37 During the mount_all command, the init executable loads all of the
     38 files contained within the /{system,vendor,odm}/etc/init/ directories.
     39 These directories are intended for all Actions and Services used after
     40 file system mounting.
     41 
     42 One may specify paths in the mount_all command line to have it import
     43 .rc files at the specified paths instead of the default ones listed above.
     44 This is primarily for supporting factory mode and other non-standard boot
     45 modes.  The three default paths should be used for the normal boot process.
     46 
     47 The intention of these directories is as follows
     48    1) /system/etc/init/ is for core system items such as
     49       SurfaceFlinger, MediaService, and logcatd.
     50    2) /vendor/etc/init/ is for SoC vendor items such as actions or
     51       daemons needed for core SoC functionality.
     52    3) /odm/etc/init/ is for device manufacturer items such as
     53       actions or daemons needed for motion sensor or other peripheral
     54       functionality.
     55 
     56 All services whose binaries reside on the system, vendor, or odm
     57 partitions should have their service entries placed into a
     58 corresponding init .rc file, located in the /etc/init/
     59 directory of the partition where they reside.  There is a build
     60 system macro, LOCAL_INIT_RC, that handles this for developers.  Each
     61 init .rc file should additionally contain any actions associated with
     62 its service.
     63 
     64 An example is the logcatd.rc and Android.mk files located in the
     65 system/core/logcat directory.  The LOCAL_INIT_RC macro in the
     66 Android.mk file places logcatd.rc in /system/etc/init/ during the
     67 build process.  Init loads logcatd.rc during the mount_all command and
     68 allows the service to be run and the action to be queued when
     69 appropriate.
     70 
     71 This break up of init .rc files according to their daemon is preferred
     72 to the previously used monolithic init .rc files.  This approach
     73 ensures that the only service entries that init reads and the only
     74 actions that init performs correspond to services whose binaries are in
     75 fact present on the file system, which was not the case with the
     76 monolithic init .rc files.  This additionally will aid in merge
     77 conflict resolution when multiple services are added to the system, as
     78 each one will go into a separate file.
     79 
     80 There are two options "early" and "late" in mount_all command
     81 which can be set after optional paths. With "--early" set, the
     82 init executable will skip mounting entries with "latemount" flag
     83 and triggering fs encryption state event. With "--late" set,
     84 init executable will only mount entries with "latemount" flag but skip
     85 importing rc files. By default, no option is set, and mount_all will
     86 mount_all will process all entries in the given fstab.
     87 
     88 Actions
     89 -------
     90 Actions are named sequences of commands.  Actions have a trigger which
     91 is used to determine when the action should occur.  When an event
     92 occurs which matches an action's trigger, that action is added to
     93 the tail of a to-be-executed queue (unless it is already on the
     94 queue).
     95 
     96 Each action in the queue is dequeued in sequence and each command in
     97 that action is executed in sequence.  Init handles other activities
     98 (device creation/destruction, property setting, process restarting)
     99 "between" the execution of the commands in activities.
    100 
    101 Actions take the form of:
    102 
    103 on <trigger> [&& <trigger>]*
    104    <command>
    105    <command>
    106    <command>
    107 
    108 
    109 Services
    110 --------
    111 Services are programs which init launches and (optionally) restarts
    112 when they exit.  Services take the form of:
    113 
    114 service <name> <pathname> [ <argument> ]*
    115    <option>
    116    <option>
    117    ...
    118 
    119 
    120 Options
    121 -------
    122 Options are modifiers to services.  They affect how and when init
    123 runs the service.
    124 
    125 critical
    126   This is a device-critical service. If it exits more than four times in
    127   four minutes, the device will reboot into recovery mode.
    128 
    129 disabled
    130   This service will not automatically start with its class.
    131   It must be explicitly started by name.
    132 
    133 setenv <name> <value>
    134   Set the environment variable <name> to <value> in the launched process.
    135 
    136 socket <name> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ]
    137   Create a unix domain socket named /dev/socket/<name> and pass
    138   its fd to the launched process.  <type> must be "dgram", "stream" or "seqpacket".
    139   User and group default to 0.
    140   'seclabel' is the SELinux security context for the socket.
    141   It defaults to the service security context, as specified by seclabel or
    142   computed based on the service executable file security context.
    143 
    144 user <username>
    145   Change to username before exec'ing this service.
    146   Currently defaults to root.  (??? probably should default to nobody)
    147   As of Android M, processes should use this option even if they
    148   require linux capabilities.  Previously, to acquire linux
    149   capabilities, a process would need to run as root, request the
    150   capabilities, then drop to its desired uid.  There is a new
    151   mechanism through fs_config that allows device manufacturers to add
    152   linux capabilities to specific binaries on a file system that should
    153   be used instead. This mechanism is described on
    154   http://source.android.com/devices/tech/config/filesystem.html.  When
    155   using this new mechanism, processes can use the user option to
    156   select their desired uid without ever running as root.
    157 
    158 group <groupname> [ <groupname> ]*
    159   Change to groupname before exec'ing this service.  Additional
    160   groupnames beyond the (required) first one are used to set the
    161   supplemental groups of the process (via setgroups()).
    162   Currently defaults to root.  (??? probably should default to nobody)
    163 
    164 seclabel <seclabel>
    165   Change to 'seclabel' before exec'ing this service.
    166   Primarily for use by services run from the rootfs, e.g. ueventd, adbd.
    167   Services on the system partition can instead use policy-defined transitions
    168   based on their file security context.
    169   If not specified and no transition is defined in policy, defaults to the init context.
    170 
    171 oneshot
    172   Do not restart the service when it exits.
    173 
    174 class <name>
    175   Specify a class name for the service.  All services in a
    176   named class may be started or stopped together.  A service
    177   is in the class "default" if one is not specified via the
    178   class option.
    179 
    180 onrestart
    181   Execute a Command (see below) when service restarts.
    182 
    183 writepid <file...>
    184   Write the child's pid to the given files when it forks. Meant for
    185   cgroup/cpuset usage.
    186 
    187 
    188 Triggers
    189 --------
    190 Triggers are strings which can be used to match certain kinds of
    191 events and used to cause an action to occur.
    192 
    193 Triggers are subdivided into event triggers and property triggers.
    194 
    195 Event triggers are strings triggered by the 'trigger' command or by
    196 the QueueEventTrigger() function within the init executable.  These
    197 take the form of a simple string such as 'boot' or 'late-init'.
    198 
    199 Property triggers are strings triggered when a named property changes
    200 value to a given new value or when a named property changes value to
    201 any new value.  These take the form of 'property:<name>=<value>' and
    202 'property:<name>=*' respectively.  Property triggers are additionally
    203 evaluated and triggered accordingly during the initial boot phase of
    204 init.
    205 
    206 An Action can have multiple property triggers but may only have one
    207 event trigger.
    208 
    209 For example:
    210 'on boot && property:a=b' defines an action that is only executed when
    211 the 'boot' event trigger happens and the property a equals b.
    212 
    213 'on property:a=b && property:c=d' defines an action that is executed
    214 at three times,
    215    1) During initial boot if property a=b and property c=d
    216    2) Any time that property a transitions to value b, while property
    217       c already equals d.
    218    3) Any time that property c transitions to value d, while property
    219       a already equals b.
    220 
    221 
    222 Commands
    223 --------
    224 
    225 bootchart_init
    226    Start bootcharting if configured (see below).
    227    This is included in the default init.rc.
    228 
    229 chmod <octal-mode> <path>
    230    Change file access permissions.
    231 
    232 chown <owner> <group> <path>
    233    Change file owner and group.
    234 
    235 class_start <serviceclass>
    236    Start all services of the specified class if they are
    237    not already running.
    238 
    239 class_stop <serviceclass>
    240    Stop and disable all services of the specified class if they are
    241    currently running.
    242 
    243 class_reset <serviceclass>
    244    Stop all services of the specified class if they are
    245    currently running, without disabling them. They can be restarted
    246    later using class_start.
    247 
    248 copy <src> <dst>
    249    Copies a file. Similar to write, but useful for binary/large
    250    amounts of data.
    251 
    252 domainname <name>
    253    Set the domain name.
    254 
    255 enable <servicename>
    256    Turns a disabled service into an enabled one as if the service did not
    257    specify disabled.
    258    If the service is supposed to be running, it will be started now.
    259    Typically used when the bootloader sets a variable that indicates a specific
    260    service should be started when needed. E.g.
    261      on property:ro.boot.myfancyhardware=1
    262         enable my_fancy_service_for_my_fancy_hardware
    263 
    264 exec [ <seclabel> [ <user> [ <group> ]* ] ] -- <command> [ <argument> ]*
    265    Fork and execute command with the given arguments. The command starts
    266    after "--" so that an optional security context, user, and supplementary
    267    groups can be provided. No other commands will be run until this one
    268    finishes. <seclabel> can be a - to denote default.
    269 
    270 export <name> <value>
    271    Set the environment variable <name> equal to <value> in the
    272    global environment (which will be inherited by all processes
    273    started after this command is executed)
    274 
    275 hostname <name>
    276    Set the host name.
    277 
    278 ifup <interface>
    279    Bring the network interface <interface> online.
    280 
    281 insmod <path>
    282    Install the module at <path>
    283 
    284 load_all_props
    285    Loads properties from /system, /vendor, et cetera.
    286    This is included in the default init.rc.
    287 
    288 load_persist_props
    289    Loads persistent properties when /data has been decrypted.
    290    This is included in the default init.rc.
    291 
    292 loglevel <level>
    293    Sets the kernel log level to level. Properties are expanded within <level>.
    294 
    295 mkdir <path> [mode] [owner] [group]
    296    Create a directory at <path>, optionally with the given mode, owner, and
    297    group. If not provided, the directory is created with permissions 755 and
    298    owned by the root user and root group. If provided, the mode, owner and group
    299    will be updated if the directory exists already.
    300 
    301 mount_all <fstab> [ <path> ]* [--<option>]
    302    Calls fs_mgr_mount_all on the given fs_mgr-format fstab and imports .rc files
    303    at the specified paths (e.g., on the partitions just mounted) with optional
    304    options "early" and "late".
    305    Refer to the section of "Init .rc Files" for detail.
    306 
    307 mount <type> <device> <dir> [ <flag> ]* [<options>]
    308    Attempt to mount the named device at the directory <dir>
    309    <device> may be of the form mtd@name to specify a mtd block
    310    device by name.
    311    <flag>s include "ro", "rw", "remount", "noatime", ...
    312    <options> include "barrier=1", "noauto_da_alloc", "discard", ... as
    313    a comma separated string, eg: barrier=1,noauto_da_alloc
    314 
    315 powerctl
    316    Internal implementation detail used to respond to changes to the
    317    "sys.powerctl" system property, used to implement rebooting.
    318 
    319 restart <service>
    320    Like stop, but doesn't disable the service.
    321 
    322 restorecon <path> [ <path> ]*
    323    Restore the file named by <path> to the security context specified
    324    in the file_contexts configuration.
    325    Not required for directories created by the init.rc as these are
    326    automatically labeled correctly by init.
    327 
    328 restorecon_recursive <path> [ <path> ]*
    329    Recursively restore the directory tree named by <path> to the
    330    security contexts specified in the file_contexts configuration.
    331 
    332 rm <path>
    333    Calls unlink(2) on the given path. You might want to
    334    use "exec -- rm ..." instead (provided the system partition is
    335    already mounted).
    336 
    337 rmdir <path>
    338    Calls rmdir(2) on the given path.
    339 
    340 setprop <name> <value>
    341    Set system property <name> to <value>. Properties are expanded
    342    within <value>.
    343 
    344 setrlimit <resource> <cur> <max>
    345    Set the rlimit for a resource.
    346 
    347 start <service>
    348    Start a service running if it is not already running.
    349 
    350 stop <service>
    351    Stop a service from running if it is currently running.
    352 
    353 swapon_all <fstab>
    354    Calls fs_mgr_swapon_all on the given fstab file.
    355 
    356 symlink <target> <path>
    357    Create a symbolic link at <path> with the value <target>
    358 
    359 sysclktz <mins_west_of_gmt>
    360    Set the system clock base (0 if system clock ticks in GMT)
    361 
    362 trigger <event>
    363    Trigger an event.  Used to queue an action from another
    364    action.
    365 
    366 umount <path>
    367    Unmount the filesystem mounted at that path.
    368 
    369 verity_load_state
    370    Internal implementation detail used to load dm-verity state.
    371 
    372 verity_update_state <mount_point>
    373    Internal implementation detail used to update dm-verity state and
    374    set the partition.<mount_point>.verified properties used by adb remount
    375    because fs_mgr can't set them directly itself.
    376 
    377 wait <path> [ <timeout> ]
    378    Poll for the existence of the given file and return when found,
    379    or the timeout has been reached. If timeout is not specified it
    380    currently defaults to five seconds.
    381 
    382 write <path> <content>
    383    Open the file at <path> and write a string to it with write(2).
    384    If the file does not exist, it will be created. If it does exist,
    385    it will be truncated. Properties are expanded within <content>.
    386 
    387 
    388 Imports
    389 -------
    390 The import keyword is not a command, but rather its own section and is
    391 handled immediately after the .rc file that contains it has finished
    392 being parsed.  It takes the below form:
    393 
    394 import <path>
    395    Parse an init config file, extending the current configuration.
    396    If <path> is a directory, each file in the directory is parsed as
    397    a config file. It is not recursive, nested directories will
    398    not be parsed.
    399 
    400 There are only two times where the init executable imports .rc files,
    401    1) When it imports /init.rc during initial boot
    402    2) When it imports /{system,vendor,odm}/etc/init/ or .rc files at specified
    403       paths during mount_all
    404 
    405 
    406 Properties
    407 ----------
    408 Init provides information about the services that it is responsible
    409 for via the below properties.
    410 
    411 init.svc.<name>
    412    State of a named service ("stopped", "stopping", "running", "restarting")
    413 
    414 
    415 Bootcharting
    416 ------------
    417 This version of init contains code to perform "bootcharting": generating log
    418 files that can be later processed by the tools provided by www.bootchart.org.
    419 
    420 On the emulator, use the -bootchart <timeout> option to boot with bootcharting
    421 activated for <timeout> seconds.
    422 
    423 On a device, create /data/bootchart/start with a command like the following:
    424 
    425   adb shell 'echo $TIMEOUT > /data/bootchart/start'
    426 
    427 Where the value of $TIMEOUT corresponds to the desired bootcharted period in
    428 seconds. Bootcharting will stop after that many seconds have elapsed.
    429 You can also stop the bootcharting at any moment by doing the following:
    430 
    431   adb shell 'echo 1 > /data/bootchart/stop'
    432 
    433 Note that /data/bootchart/stop is deleted automatically by init at the end of
    434 the bootcharting. This is not the case with /data/bootchart/start, so don't
    435 forget to delete it when you're done collecting data.
    436 
    437 The log files are written to /data/bootchart/. A script is provided to
    438 retrieve them and create a bootchart.tgz file that can be used with the
    439 bootchart command-line utility:
    440 
    441   sudo apt-get install pybootchartgui
    442   # grab-bootchart.sh uses $ANDROID_SERIAL.
    443   $ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh
    444 
    445 One thing to watch for is that the bootchart will show init as if it started
    446 running at 0s. You'll have to look at dmesg to work out when the kernel
    447 actually started init.
    448 
    449 
    450 Comparing two bootcharts
    451 ------------------------
    452 A handy script named compare-bootcharts.py can be used to compare the
    453 start/end time of selected processes. The aforementioned grab-bootchart.sh
    454 will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart.
    455 If two such barballs are preserved on the host machine under different
    456 directories, the script can list the timestamps differences. For example:
    457 
    458 Usage: system/core/init/compare-bootcharts.py base_bootchart_dir
    459        exp_bootchart_dir
    460 
    461 process: baseline experiment (delta)
    462  - Unit is ms (a jiffy is 10 ms on the system)
    463 ------------------------------------
    464 /init: 50 40 (-10)
    465 /system/bin/surfaceflinger: 4320 4470 (+150)
    466 /system/bin/bootanimation: 6980 6990 (+10)
    467 zygote64: 10410 10640 (+230)
    468 zygote: 10410 10640 (+230)
    469 system_server: 15350 15150 (-200)
    470 bootanimation ends at: 33790 31230 (-2560)
    471 
    472 
    473 Systrace
    474 --------
    475 Systrace [1] can be used for obtaining performance analysis reports during boot
    476 time on userdebug or eng builds.
    477 Here is an example of trace events of "wm" and "am" categories:
    478 
    479   $ANDROID_BUILD_TOP/external/chromium-trace/systrace.py wm am --boot
    480 
    481 This command will cause the device to reboot. After the device is rebooted and
    482 the boot sequence has finished, the trace report is obtained from the device
    483 and written as trace.html on the host by hitting Ctrl+C.
    484 
    485 LIMITATION
    486 Recording trace events is started after persistent properties are loaded, so
    487 the trace events that are emitted before that are not recorded. Several
    488 services such as vold, surfaceflinger, and servicemanager are affected by this
    489 limitation since they are started before persistent properties are loaded.
    490 Zygote initialization and the processes that are forked from the zygote are not
    491 affected.
    492 
    493 [1] http://developer.android.com/tools/help/systrace.html
    494 
    495 
    496 Debugging init
    497 --------------
    498 By default, programs executed by init will drop stdout and stderr into
    499 /dev/null. To help with debugging, you can execute your program via the
    500 Android program logwrapper. This will redirect stdout/stderr into the
    501 Android logging system (accessed via logcat).
    502 
    503 For example
    504 service akmd /system/bin/logwrapper /sbin/akmd
    505 
    506 For quicker turnaround when working on init itself, use:
    507 
    508   mm -j
    509   m ramdisk-nodeps
    510   m bootimage-nodeps
    511   adb reboot bootloader
    512   fastboot boot $ANDROID_PRODUCT_OUT/boot.img
    513 
    514 Alternatively, use the emulator:
    515 
    516   emulator -partition-size 1024 -verbose -show-kernel -no-window
    517 
    518 You might want to call klog_set_level(6) after the klog_init() call
    519 so you see the kernel logging in dmesg (or the emulator output).
    520