doc/android/ab.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Android A/B updates
   4 ===================
   5
   6 Overview
   7 --------
   8
   9 A/B system updates ensures modern approach for system update. This feature
  10 allows one to use two sets (or more) of partitions referred to as slots
  11 (normally slot A and slot B). The system runs from the current slot while the
  12 partitions in the unused slot can be updated [1]_.
  13
  14 A/B enablement
  15 --------------
  16
  17 The A/B updates support can be activated by specifying next options in
  18 your board configuration file::
  19
  20     CONFIG_ANDROID_AB=y
  21     CONFIG_CMD_AB_SELECT=y
  22
  23 The disk space on target device must be partitioned in a way so that each
  24 partition which needs to be updated has two or more instances. The name of
  25 each instance must be formed by adding suffixes: ``_a``, ``_b``, ``_c``, etc.
  26 For example: ``boot_a``, ``boot_b``, ``system_a``, ``system_b``, ``vendor_a``,
  27 ``vendor_b``.
  28
  29 As a result you can use ``ab_select`` command to ensure A/B boot process in your
  30 boot script. This command analyzes and processes A/B metadata stored on a
  31 special partition (e.g. ``misc``) and determines which slot should be used for
  32 booting up.
  33
  34 Command usage
  35 -------------
  36
  37 .. code-block:: none
  38
  39     ab_select <slot_var_name> <interface> <dev[:part_number|#part_name]>
  40
  41 for example::
  42
  43     => ab_select slot_name mmc 1:4
  44
  45 or::
  46
  47     => ab_select slot_name mmc 1#misc
  48
  49 Result::
  50
  51     => printenv slot_name
  52     slot_name=a
  53
  54 Based on this slot information, the current boot partition should be defined,
  55 and next kernel command line parameters should be generated:
  56
  57 * ``androidboot.slot_suffix=``
  58 * ``root=``
  59
  60 For example::
  61
  62     androidboot.slot_suffix=_a root=/dev/mmcblk1p12
  63
  64 A/B metadata is organized according to AOSP reference [2]_. On the first system
  65 start with A/B enabled, when ``misc`` partition doesn't contain required data,
  66 the default A/B metadata will be created and written to ``misc`` partition.
  67
  68 References
  69 ----------
  70
  71 .. [1] https://source.android.com/devices/tech/ota/ab
  72 .. [2] https://android.googlesource.com/platform/bootable/recovery/+/refs/tags/android-10.0.0_r25/bootloader_message/include/bootloader_message/bootloader_message.h