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 If the A/B metadata partition has a backup bootloader_message block that is used
  35 to ensure one is always valid even in the event of interruption when writing, it
  36 can be enabled in your board configuration file::
  37
  38     CONFIG_ANDROID_AB_BACKUP_OFFSET=0x1000
  39
  40 Command usage
  41 -------------
  42
  43 .. code-block:: none
  44
  45     ab_select <slot_var_name> <interface> <dev[:part_number|#part_name]>
  46
  47 for example::
  48
  49     => ab_select slot_name mmc 1:4
  50
  51 or::
  52
  53     => ab_select slot_name mmc 1#misc
  54
  55 Result::
  56
  57     => printenv slot_name
  58     slot_name=a
  59
  60 Based on this slot information, the current boot partition should be defined,
  61 and next kernel command line parameters should be generated:
  62
  63 * ``androidboot.slot_suffix=``
  64 * ``root=``
  65
  66 For example::
  67
  68     androidboot.slot_suffix=_a root=/dev/mmcblk1p12
  69
  70 A/B metadata is organized according to AOSP reference [2]_. On the first system
  71 start with A/B enabled, when ``misc`` partition doesn't contain required data,
  72 the default A/B metadata will be created and written to ``misc`` partition.
  73
  74 References
  75 ----------
  76
  77 .. [1] https://source.android.com/devices/tech/ota/ab
  78 .. [2] https://android.googlesource.com/platform/bootable/recovery/+/refs/tags/android-10.0.0_r25/bootloader_message/include/bootloader_message/bootloader_message.h