• Eugeniu Rosca's avatar
    cmd: Add 'bcb' command to read/modify/write BCB fields · db7b7a05
    Eugeniu Rosca authored
    'Bootloader Control Block' (BCB) is a well established term/acronym in
    the Android namespace which refers to a location in a dedicated raw
    (i.e. FS-unaware) flash (e.g. eMMC) partition, usually called "misc",
    which is used as media for exchanging messages between Android userspace
    (particularly recovery [1]) and an Android-capable bootloader.
    
    On higher level, this allows implementing a subset of Android Bootloader
    Requirements [2], amongst which is the Android-specific bootloader
    flow [3]. Regardless how the latter is implemented in U-Boot ([3] being
    the most memorable example), reading/writing/dumping the BCB fields in
    the development process from inside the U-Boot is a convenient feature.
    Hence, make it available to the users.
    
    Some usage examples of the new command recorded on R-Car H3ULCB-KF
    ('>>>' is an overlay on top of the original console output):
    
    => bcb
    bcb - Load/set/clear/test/dump/store Android BCB fields
    
    Usage:
    bcb load  <dev> <part>       - load  BCB from mmc <dev>:<part>
    bcb set   <field> <val>      - set   BCB <field> to <val>
    bcb clear [<field>]          - clear BCB <field> or all fields
    bcb test  <field> <op> <val> - test  BCB <field> against <val>
    bcb dump  <field>            - dump  BCB <field>
    bcb store                    - store BCB back to mmc
    
    Legend:
    <dev>   - MMC device index containing the BCB partition
    <part>  - MMC partition index or name containing the BCB
    <field> - one of {command,status,recovery,stage,reserved}
    <op>    - the binary operator used in 'bcb test':
              '=' returns true if <val> matches the string stored in <field>
              '~' returns true if <val> matches a subset of <field>'s string
    <val>   - string/text provided as input to bcb {set,test}
              NOTE: any ':' character in <val> will be replaced by line feed
              during 'bcb set' and used as separator by upper layers
    
    => bcb dump command
    Error: Please, load BCB first!
     >>> Users must specify mmc device and partition before any other call
    
    => bcb load 1 misc
    => bcb load 1 1
     >>> The two calls are equivalent (assuming "misc" has index 1)
    
    => bcb dump command
    00000000: 62 6f 6f 74 6f 6e 63 65 2d 73 68 65 6c 6c 00 72    bootonce-shell.r
    00000010: 79 00 72 00 00 00 00 00 00 00 00 00 00 00 00 00    y.r.............
     >>> The output is in binary/string format for convenience
     >>> The output size matches the size of inspected BCB field
     >>> (32 bytes in case of 'command')
    
    => bcb test command = bootonce-shell && echo true
    true
    => bcb test command = bootonce-shell- && echo true
    => bcb test command = bootonce-shel && echo true
     >>> The '=' operator returns 'true' on perfect match
    
    => bcb test command ~ bootonce-shel && echo true
    true
    => bcb test command ~ bootonce-shell && echo true
    true
     >>> The '~' operator returns 'true' on substring match
    
    => bcb set command recovery
    => bcb dump command
    00000000: 72 65 63 6f 76 65 72 79 00 73 68 65 6c 6c 00 72    recovery.shell.r
    00000010: 79 00 72 00 00 00 00 00 00 00 00 00 00 00 00 00    y.r.............
     >>> The new value is NULL-terminated and stored in the BCB field
    
    => bcb set recovery "msg1:msg2:msg3"
    => bcb dump recovery
    00000040: 6d 73 67 31 0a 6d 73 67 32 0a 6d 73 67 33 00 00    msg1.msg2.msg3..
    00000050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
    00000060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
     >>> --- snip ---
     >>> Every ':' is replaced by line-feed '\n' (0xA). The latter is used
     >>> as separator between individual commands by Android userspace
    
    => bcb store
     >>> Flush/store the BCB structure to MMC
    
    [1] https://android.googlesource.com/platform/bootable/recovery
    [2] https://source.android.com/devices/bootloader
    [3] https://patchwork.ozlabs.org/patch/746835/
    
    
        ("[U-Boot,5/6] Initial support for the Android Bootloader flow")
    
    Signed-off-by: default avatarEugeniu Rosca <erosca@de.adit-jv.com>
    db7b7a05