[U-Boot] [PATCH 1/2] include: android_bl_msg.h: Initial import
Sam Protsenko
semen.protsenko at linaro.org
Wed May 8 14:26:04 UTC 2019
Hi Eugeniu,
Please see my comments below. Overall, we will need to think it over
and merge 3 patch series somehow (this one, the one for A/B support
from Ruslan, and one internal patch series Ruslan sent for reboot
reason support). I will provide more details a bit later, working on
this right now.
On Mon, Apr 8, 2019 at 1:02 AM Eugeniu Rosca <roscaeugeniu at gmail.com> wrote:
>
> Import the bootloader_message.h (former bootloader.h) from AOSP.
>
> Repository: https://android.googlesource.com/platform/bootable/recovery
> Commit: 8e0821e6907d6016c19565b83319aff90ad1a034
> Author: Tao Bao <tbao at google.com>
> Date: Wed Apr 3 23:48:21 2019 +0000
>
> The bootloader_message.h basically defines the flash layout of a
> dedicated partition (usually called 'misc') and is needed in U-Boot
> in order to be able to implement a subset of Android Bootloader
> Requirements [1], specifically dealing with:
> - Communication between the bootloader and recovery
> - Handling of A/B (Seamless) System Updates [2]
>
> With respect to the in-tree vs out-of-tree file differences:
> - license matches https://patchwork.ozlabs.org/patch/1003998/
> - filename is changed to android_bl_msg.h, as per Simon's comment [3]
> - the struct/macro names have been shaped by [3-4], where the two main
> criterias are:
> - Improve the syntax/readability in the global U-Boot namespace
> - Minimize the future integration/update efforts from the source.
> Particularly, the __UBOOT__ macro helps with isolating the
> U-Boot-unrelated parts (e.g. includes/function prototypes/etc)
>
> [1] https://source.android.com/devices/bootloader
> [2] https://source.android.com/devices/tech/ota/ab/
> [3] https://patchwork.ozlabs.org/patch/1003998/#2046141
> [4] https://patchwork.ozlabs.org/patch/1003998/#2144955
>
> Signed-off-by: Eugeniu Rosca <erosca at de.adit-jv.com>
> ---
> include/android_bl_msg.h | 273 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 273 insertions(+)
> create mode 100644 include/android_bl_msg.h
>
> diff --git a/include/android_bl_msg.h b/include/android_bl_msg.h
> new file mode 100644
> index 000000000000..c48a1de2762b
> --- /dev/null
> +++ b/include/android_bl_msg.h
> @@ -0,0 +1,273 @@
> +// SPDX-License-Identifier: BSD-2-Clause
> +/*
> + * This file was taken from the AOSP Project.
> + * Repository: https://android.googlesource.com/platform/bootable/recovery/
> + * File: bootloader_message/include/bootloader_message/bootloader_message.h
> + * Commit: see U-Boot commit importing/updating the file in-tree
> + *
> + * Copyright (C) 2008 The Android Open Source Project
> + *
> + * Licensed under the Apache License, Version 2.0 (the "License");
> + * you may not use this file except in compliance with the License.
> + * You may obtain a copy of the License at
> + *
> + * http://www.apache.org/licenses/LICENSE-2.0
> + *
> + * Unless required by applicable law or agreed to in writing, software
> + * distributed under the License is distributed on an "AS IS" BASIS,
> + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> + * See the License for the specific language governing permissions and
> + * limitations under the License.
> + */
> +
> +#ifndef _BOOTLOADER_MESSAGE_H
> +#define _BOOTLOADER_MESSAGE_H
> +
> +#ifndef __UBOOT__
> +#include <assert.h>
> +#include <stddef.h>
> +#include <stdint.h>
> +#else
> +#include <compiler.h>
> +#include <linux/sizes.h>
> +#endif
> +
> +#ifdef __UBOOT__
> +/* U-Boot-specific types for improved syntax/readability */
> +typedef struct bootloader_message andr_bl_msg;
> +typedef struct bootloader_message_ab andr_bl_msg_ab;
> +typedef struct bootloader_control andr_bl_control;
I would argue against creating user types for structures. It breaks
next rule from Linux kernel coding style (which we use in U-Boot):
"It’s a mistake to use typedef for structures and pointers."
Which more important, it breaks that rule outside of this file. Also,
as you mentioned before, it's probably wise to keep this file as close
as possible to original, as we will need to update it at some point.
> +#endif
> +
> +// Spaces used by misc partition are as below:
> +// 0 - 2K For bootloader_message
> +// 2K - 16K Used by Vendor's bootloader (the 2K - 4K range may be optionally used
> +// as bootloader_message_ab struct)
> +// 16K - 64K Used by uncrypt and recovery to store wipe_package for A/B devices
> +// Note that these offsets are admitted by bootloader,recovery and uncrypt, so they
> +// are not configurable without changing all of them.
> +
> +#ifndef __UBOOT__
This stuff is very nice. I guess we can upstream it further to AOSP,
then this file will be almost the same in AOSP and in U-Boot.
> +static const size_t BOOTLOADER_MESSAGE_OFFSET_IN_MISC = 0;
> +static const size_t WIPE_PACKAGE_OFFSET_IN_MISC = 16 * 1024;
> +#else
> +#define ANDROID_MISC_BM_OFFSET 0
> +#define ANDROID_MISC_WIPE_OFFSET SZ_16K
> +#endif
> +
> +/* Bootloader Message (2-KiB)
> + *
> + * This structure describes the content of a block in flash
> + * that is used for recovery and the bootloader to talk to
> + * each other.
> + *
> + * The command field is updated by linux when it wants to
> + * reboot into recovery or to update radio or bootloader firmware.
> + * It is also updated by the bootloader when firmware update
> + * is complete (to boot into recovery for any final cleanup)
> + *
> + * The status field was used by the bootloader after the completion
> + * of an "update-radio" or "update-hboot" command, which has been
> + * deprecated since Froyo.
> + *
> + * The recovery field is only written by linux and used
> + * for the system to send a message to recovery or the
> + * other way around.
> + *
> + * The stage field is written by packages which restart themselves
> + * multiple times, so that the UI can reflect which invocation of the
> + * package it is. If the value is of the format "#/#" (eg, "1/3"),
> + * the UI will add a simple indicator of that status.
> + *
> + * We used to have slot_suffix field for A/B boot control metadata in
> + * this struct, which gets unintentionally cleared by recovery or
> + * uncrypt. Move it into struct bootloader_message_ab to avoid the
> + * issue.
> + */
> +struct bootloader_message {
> + char command[32];
> + char status[32];
> + char recovery[768];
> +
> + // The 'recovery' field used to be 1024 bytes. It has only ever
> + // been used to store the recovery command line, so 768 bytes
> + // should be plenty. We carve off the last 256 bytes to store the
> + // stage string (for multistage packages) and possible future
> + // expansion.
> + char stage[32];
> +
> + // The 'reserved' field used to be 224 bytes when it was initially
> + // carved off from the 1024-byte recovery field. Bump it up to
> + // 1184-byte so that the entire bootloader_message struct rounds up
> + // to 2048-byte.
> + char reserved[1184];
> +};
> +
> +/**
> + * We must be cautious when changing the bootloader_message struct size,
> + * because A/B-specific fields may end up with different offsets.
> + */
> +#ifndef __UBOOT__
> +#if (__STDC_VERSION__ >= 201112L) || defined(__cplusplus)
> +static_assert(sizeof(struct bootloader_message) == 2048,
> + "struct bootloader_message size changes, which may break A/B devices");
> +#endif
> +#endif
> +
> +/**
> + * The A/B-specific bootloader message structure (4-KiB).
> + *
> + * We separate A/B boot control metadata from the regular bootloader
> + * message struct and keep it here. Everything that's A/B-specific
> + * stays after struct bootloader_message, which should be managed by
> + * the A/B-bootloader or boot control HAL.
> + *
> + * The slot_suffix field is used for A/B implementations where the
> + * bootloader does not set the androidboot.ro.boot.slot_suffix kernel
> + * commandline parameter. This is used by fs_mgr to mount /system and
> + * other partitions with the slotselect flag set in fstab. A/B
> + * implementations are free to use all 32 bytes and may store private
> + * data past the first NUL-byte in this field. It is encouraged, but
> + * not mandatory, to use 'struct bootloader_control' described below.
> + *
> + * The update_channel field is used to store the Omaha update channel
> + * if update_engine is compiled with Omaha support.
> + */
> +struct bootloader_message_ab {
> + struct bootloader_message message;
> + char slot_suffix[32];
> + char update_channel[128];
> +
> + // Round up the entire struct to 4096-byte.
> + char reserved[1888];
> +};
> +
> +/**
> + * Be cautious about the struct size change, in case we put anything post
> + * bootloader_message_ab struct (b/29159185).
> + */
> +#ifndef __UBOOT__
> +#if (__STDC_VERSION__ >= 201112L) || defined(__cplusplus)
> +static_assert(sizeof(struct bootloader_message_ab) == 4096,
> + "struct bootloader_message_ab size changes");
> +#endif
> +#endif
> +
> +#define BOOT_CTRL_MAGIC 0x42414342 /* Bootloader Control AB */
> +#define BOOT_CTRL_VERSION 1
> +
> +struct slot_metadata {
> + // Slot priority with 15 meaning highest priority, 1 lowest
> + // priority and 0 the slot is unbootable.
> + uint8_t priority : 4;
> + // Number of times left attempting to boot this slot.
> + uint8_t tries_remaining : 3;
> + // 1 if this slot has booted successfully, 0 otherwise.
> + uint8_t successful_boot : 1;
> + // 1 if this slot is corrupted from a dm-verity corruption, 0
> + // otherwise.
> + uint8_t verity_corrupted : 1;
> + // Reserved for further use.
> + uint8_t reserved : 7;
> +} __attribute__((packed));
> +
> +/* Bootloader Control AB
> + *
> + * This struct can be used to manage A/B metadata. It is designed to
> + * be put in the 'slot_suffix' field of the 'bootloader_message'
> + * structure described above. It is encouraged to use the
> + * 'bootloader_control' structure to store the A/B metadata, but not
> + * mandatory.
> + */
> +struct bootloader_control {
> + // NUL terminated active slot suffix.
> + char slot_suffix[4];
> + // Bootloader Control AB magic number (see BOOT_CTRL_MAGIC).
> + uint32_t magic;
> + // Version of struct being used (see BOOT_CTRL_VERSION).
> + uint8_t version;
> + // Number of slots being managed.
> + uint8_t nb_slot : 3;
> + // Number of times left attempting to boot recovery.
> + uint8_t recovery_tries_remaining : 3;
> + // Ensure 4-bytes alignment for slot_info field.
> + uint8_t reserved0[2];
> + // Per-slot information. Up to 4 slots.
> + struct slot_metadata slot_info[4];
> + // Reserved for further use.
> + uint8_t reserved1[8];
> + // CRC32 of all 28 bytes preceding this field (little endian
> + // format).
> + uint32_t crc32_le;
> +} __attribute__((packed));
> +
> +#ifndef __UBOOT__
> +#if (__STDC_VERSION__ >= 201112L) || defined(__cplusplus)
> +static_assert(sizeof(struct bootloader_control) ==
> + sizeof(((struct bootloader_message_ab *)0)->slot_suffix),
> + "struct bootloader_control has wrong size");
> +#endif
> +#endif
> +
> +#ifndef __UBOOT__
> +#ifdef __cplusplus
> +
> +#include <string>
> +#include <vector>
> +
> +// Return the block device name for the bootloader message partition and waits
> +// for the device for up to 10 seconds. In case of error returns the empty
> +// string.
> +std::string get_bootloader_message_blk_device(std::string* err);
> +
> +// Read bootloader message into boot. Error message will be set in err.
> +bool read_bootloader_message(bootloader_message* boot, std::string* err);
> +
> +// Read bootloader message from the specified misc device into boot.
> +bool read_bootloader_message_from(bootloader_message* boot, const std::string& misc_blk_device,
> + std::string* err);
> +
> +// Write bootloader message to BCB.
> +bool write_bootloader_message(const bootloader_message& boot, std::string* err);
> +
> +// Write bootloader message to the specified BCB device.
> +bool write_bootloader_message_to(const bootloader_message& boot,
> + const std::string& misc_blk_device, std::string* err);
> +
> +// Write bootloader message (boots into recovery with the options) to BCB. Will
> +// set the command and recovery fields, and reset the rest.
> +bool write_bootloader_message(const std::vector<std::string>& options, std::string* err);
> +
> +// Update bootloader message (boots into recovery with the options) to BCB. Will
> +// only update the command and recovery fields.
> +bool update_bootloader_message(const std::vector<std::string>& options, std::string* err);
> +
> +// Update bootloader message (boots into recovery with the |options|) in |boot|. Will only update
> +// the command and recovery fields.
> +bool update_bootloader_message_in_struct(bootloader_message* boot,
> + const std::vector<std::string>& options);
> +
> +// Clear BCB.
> +bool clear_bootloader_message(std::string* err);
> +
> +// Writes the reboot-bootloader reboot reason to the bootloader_message.
> +bool write_reboot_bootloader(std::string* err);
> +
> +// Read the wipe package from BCB (from offset WIPE_PACKAGE_OFFSET_IN_MISC).
> +bool read_wipe_package(std::string* package_data, size_t size, std::string* err);
> +
> +// Write the wipe package into BCB (to offset WIPE_PACKAGE_OFFSET_IN_MISC).
> +bool write_wipe_package(const std::string& package_data, std::string* err);
> +
> +#else
> +
> +#include <stdbool.h>
> +
> +// C Interface.
> +bool write_bootloader_message(const char* options);
> +bool write_reboot_bootloader(void);
> +
> +#endif // ifdef __cplusplus
> +#endif
> +
> +#endif // _BOOTLOADER_MESSAGE_H
> --
> 2.21.0
>
More information about the U-Boot
mailing list