bcb.txt 3.3 KB

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