bcb.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. Android Bootloader Control Block (BCB)
  3. ======================================
  4. The purpose behind this file is to:
  5. * give an overview of BCB w/o duplicating public documentation
  6. * describe the main BCB use-cases which concern U-Boot
  7. * reflect current support status in U-Boot
  8. * mention any relevant U-Boot build-time tunables
  9. * precisely exemplify one or more use-cases
  10. Additions and fixes are welcome!
  11. Overview
  12. --------
  13. Bootloader Control Block (BCB) is a well established term/acronym in
  14. the Android namespace which refers to a location in a dedicated raw
  15. (i.e. FS-unaware) flash (e.g. eMMC) partition, usually called ``misc``,
  16. which is used as media for exchanging messages between Android userspace
  17. (particularly recovery [1]_) and an Android-capable bootloader.
  18. On higher level, BCB provides a way to implement a subset of Android
  19. Bootloader Requirements [2]_, amongst which are:
  20. * Android-specific bootloader flow [3]_
  21. * Get the "reboot reason" (and act accordingly) [4]_
  22. * Get/pass a list of commands from/to recovery [1]_
  23. * TODO
  24. 'bcb'. Shell command overview
  25. -----------------------------
  26. The ``bcb`` command provides a CLI to facilitate the development of the
  27. requirements enumerated above. Below is the command's help message::
  28. => bcb
  29. bcb - Load/set/clear/test/dump/store Android BCB fields
  30. Usage:
  31. bcb load <dev> <part> - load BCB from mmc <dev>:<part>
  32. bcb set <field> <val> - set BCB <field> to <val>
  33. bcb clear [<field>] - clear BCB <field> or all fields
  34. bcb test <field> <op> <val> - test BCB <field> against <val>
  35. bcb dump <field> - dump BCB <field>
  36. bcb store - store BCB back to mmc
  37. Legend:
  38. <dev> - MMC device index containing the BCB partition
  39. <part> - MMC partition index or name containing the BCB
  40. <field> - one of {command,status,recovery,stage,reserved}
  41. <op> - the binary operator used in 'bcb test':
  42. '=' returns true if <val> matches the string stored in <field>
  43. '~' returns true if <val> matches a subset of <field>'s string
  44. <val> - string/text provided as input to bcb {set,test}
  45. NOTE: any ':' character in <val> will be replaced by line feed
  46. during 'bcb set' and used as separator by upper layers
  47. 'bcb'. Example of getting reboot reason
  48. ---------------------------------------
  49. .. code-block:: bash
  50. if bcb load 1 misc; then
  51. # valid BCB found
  52. if bcb test command = bootonce-bootloader; then
  53. bcb clear command; bcb store;
  54. # do the equivalent of AOSP ${fastbootcmd}
  55. # i.e. call fastboot
  56. else if bcb test command = boot-recovery; then
  57. bcb clear command; bcb store;
  58. # do the equivalent of AOSP ${recoverycmd}
  59. # i.e. do anything required for booting into recovery
  60. else
  61. # boot Android OS normally
  62. fi
  63. else
  64. # corrupted/non-existent BCB
  65. # report error or boot non-Android OS (platform-specific)
  66. fi
  67. Enable on your board
  68. --------------------
  69. The following Kconfig options must be enabled::
  70. CONFIG_PARTITIONS=y
  71. CONFIG_MMC=y
  72. CONFIG_BCB=y
  73. .. [1] https://android.googlesource.com/platform/bootable/recovery
  74. .. [2] https://source.android.com/devices/bootloader
  75. .. [3] https://patchwork.ozlabs.org/patch/746835/
  76. ("[U-Boot,5/6] Initial support for the Android Bootloader flow")
  77. .. [4] https://source.android.com/devices/bootloader/boot-reason