doc/android/aprop.txt

Android persistent Properties command overview

1. OVERVIEW
---------------------------------
Android system properties are widely used among Android native services
to control runtime behaviour or pass information between processes.
Android's Init deamon can also trigger actions upon property changes [1]
Some of these properties will persist accross reboots.
They are stored in mmc, usually on the userdata partition [2]

Persistent properties contain useful information which we might want to
inspect for debugging.

One of particular interest is "persist.sys.boot.reason", which allows to
determine the boot reason without relying on BCB.

DISCLAIMER: this is *debug* command. Should not be used in production.
Also probably won't work in production as userdata is usually encrypted.


2. 'APROP'. SHELL COMMAND OVERVIEW
-----------------------------------

The 'aprop' command provides a CLI to facilitate the development of the
requirements enumerated above. Below is the command's help message:

=> aprop
aprop - Load/get/set/test/dump/store Android persistent properties

Usage:
aprop load  <dev> <part>     - load properties from mmc <dev>:<part>
aprop get   <key>            - retrieves the <val> for <key>
aprop set   <key> <val>      - sets <key> to <val>
aprop test  <key> <op> <val> - test <key> agains <val>
aprop dump                   - dump all properties in <key>=<val> format
aprop store                  - store all properties back to mmc
Legend:
<dev>   - MMC device index containing the aprop partition
<part>  - MMC partition index or name containing the property file
<key>   - string/text representing a property key
<val>   - string/text representing a property value
<op>    - the binary operator used in 'aprop test':
          '=' returns true if <val> matches <key>'s value
          '~' returns true if <val> matches a subset of <key>'s value


3. 'APROP'. EXAMPLE OF GETTING BOOT REASON
-----------------------------------
if aprop load 0 userdata; then
    # valid persist property file found
    if aprop test persist.sys.bootreason = recovery; then
        aprop set persist.sys.bootreason "none"; aprop store;
        # do the equivalent of AOSP ${recoverycmd}
        # i.e. do anything required for booting into recovery
    else
        # boot Android OS normally
    fi
else
    # encrypted/corrupted/non-existent property file
    # continue boot Android OS or report error (platform-specific)
fi


4. ENABLE ON YOUR BOARD
-----------------------------------
The following Kconfig options must be enabled:
CONFIG_PARTITIONS=y
CONFIG_MMC=y
CONFIG_APROP=y

Additionally, filesystem read/write support for the partition
must be enabled. Usually, the partition is in EXT4:
CONFIG_FS_EXT4=y
CONFIG_EXT4_WRITE=y

[1] https://android.googlesource.com/platform/system/core/+/master/init/README.md
[2] https://android.googlesource.com/platform/system/core/+/refs/heads/master/init/persistent_properties.cpp#42