From patchwork Sun Jul 7 13:34:19 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eugeniu Rosca X-Patchwork-Id: 1128665 X-Patchwork-Delegate: trini@ti.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.denx.de (client-ip=81.169.180.215; helo=lists.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="U26gksP/"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 45hV3x5Y5mz9s7T for ; Sun, 7 Jul 2019 23:36:45 +1000 (AEST) Received: by lists.denx.de (Postfix, from userid 105) id 2721BC21DFA; Sun, 7 Jul 2019 13:36:24 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on lists.denx.de X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=FREEMAIL_FROM, KHOP_BIG_TO_CC, T_DKIM_INVALID autolearn=unavailable autolearn_force=no version=3.4.0 Received: from lists.denx.de (localhost [IPv6:::1]) by lists.denx.de (Postfix) with ESMTP id 581C8C21DD3; Sun, 7 Jul 2019 13:35:51 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id 3EF20C21D8A; Sun, 7 Jul 2019 13:35:33 +0000 (UTC) Received: from mail-wr1-f49.google.com (mail-wr1-f49.google.com [209.85.221.49]) by lists.denx.de (Postfix) with ESMTPS id 3271AC21CB6 for ; Sun, 7 Jul 2019 13:35:27 +0000 (UTC) Received: by mail-wr1-f49.google.com with SMTP id n9so5097458wrr.4 for ; Sun, 07 Jul 2019 06:35:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=553URjkpVk3u7nsu/l93DbpfmHZdYqZ7+fNfi2GhXXQ=; b=U26gksP/rNIMrRZCKWccmDDdSYa+3KzaLwrGm5e2YExjBnyXASAdmjhLGxi4vNl6++ WUcjw7deByCJgWkyilKLpV4oSNLm4kvKJro1kvYXz79PSv7DjLeQA1fcbNE4iXYGy5aa 9ga1dZAnuH2sszDASXnevOJipoui7vPtXqVJHM2ZmVsBwFqwnuM0h34nqN56qEpNADAJ 2Tcr2e28X37OjFRE9PJPJhgWJEvlrL8RxPX4hXL4JbdfArs1zCbvAUtA/KomoFgxQyw3 lZg+J0/m0fAEeavZ4ouwiifrRS2AI1loJR54/JFcYdjoNWe/kbLtVZL/hE2grTDOv2Bn WCNw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=553URjkpVk3u7nsu/l93DbpfmHZdYqZ7+fNfi2GhXXQ=; b=d+/t2XjfX1vodKFXmSoBQloCDjEIBQik7aZwf2NTmxg7JJeMnz1WU22jglCrKXp6Vs QHfzCGt1ssekNk1DwK8Kd2SfWGEF2mp177ZmWPdF8QI/HDH/OW7tJvEiKTP42VtgSodm RS8wYBnbCqN5cr8nVAT/ZOtbFyhb2C9tRbyTD88zHQXJFmMYtBAHGDm3h+Da+bZYYOO6 XhER9NAu3+Ayrr0BUOUOmo1ylqCN4l334zrtZ8m0Kceaq7NgY9N/YNBg8ZmcPVczJorB ckm/V9qASdDu+Swty7S95rQ+l7Ah/BqGm1Qjki2x6qNwjtB0Wxyd9RHMzNcK6TvuKKSu rz/A== X-Gm-Message-State: APjAAAXvdu2A1QvPEFjjN6LQgLgZIA0vIKCdrZ5axw/9FWJzIqLQDvTm H6CqznWpeu9pYiFteGTgjd+ozxEbQly2+A== X-Google-Smtp-Source: APXvYqzlGIYdOae8zaVJf4RAG5uEVCN2bSTlwK8e+IjZUqe6S8S2ONdWtxWbG8iufmyznYX3Xy6LxQ== X-Received: by 2002:a5d:6406:: with SMTP id z6mr13658148wru.280.1562506526690; Sun, 07 Jul 2019 06:35:26 -0700 (PDT) Received: from localhost.localdomain (ipb218f489.dynamic.kabel-deutschland.de. [178.24.244.137]) by smtp.gmail.com with ESMTPSA id u186sm11196759wmu.26.2019.07.07.06.35.25 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Sun, 07 Jul 2019 06:35:26 -0700 (PDT) From: Eugeniu Rosca X-Google-Original-From: Eugeniu Rosca To: u-boot@lists.denx.de, Simon Glass , Sam Protsenko , Heinrich Schuchardt , AKASHI Takahiro , Igor Opaniuk , Marek Vasut , Alex Kiernan , Alex Deymo , Praneeth Bajjuri , Alistair Strachan , Joe Hershberger , Michal Simek , Chris Packham , Miquel Raynal , Mario Six , Adam Ford , Stefan Roese , Tom Rini Date: Sun, 7 Jul 2019 15:34:19 +0200 Message-Id: <20190707133419.8335-5-erosca@de.adit-jv.com> X-Mailer: git-send-email 2.22.0 In-Reply-To: <20190707133419.8335-1-erosca@de.adit-jv.com> References: <20190707133419.8335-1-erosca@de.adit-jv.com> MIME-Version: 1.0 Cc: Eugeniu Rosca , Eugeniu Rosca Subject: [U-Boot] [PATCH v4 4/4] doc: android: add BCB overview and usage X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.18 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" Document the BCB concept and U-Boot command, touching below aspects: - give an overview of BCB w/o duplicating public documentation - describe the main BCB use-cases which concern U-Boot - reflect current support status in U-Boot - mention any relevant U-Boot build-time tunables - precisely exemplify one or more use-cases Signed-off-by: Eugeniu Rosca --- v4: - This is carved out from https://patchwork.ozlabs.org/patch/1104245/ ("[v3,3/3] doc: relocate/rename Android README and add BCB overview") with no modifications. --- doc/android/bcb.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 doc/android/bcb.txt diff --git a/doc/android/bcb.txt b/doc/android/bcb.txt new file mode 100644 index 000000000000..7b7177cacf21 --- /dev/null +++ b/doc/android/bcb.txt @@ -0,0 +1,89 @@ +Android Bootloader Control Block (BCB) + +The purpose behind this file is to: + - give an overview of BCB w/o duplicating public documentation + - describe the main BCB use-cases which concern U-Boot + - reflect current support status in U-Boot + - mention any relevant U-Boot build-time tunables + - precisely exemplify one or more use-cases + +Additions and fixes are welcome! + + +1. OVERVIEW +--------------------------------- +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, BCB provides a way to implement a subset of Android +Bootloader Requirements [2], amongst which are: + - Android-specific bootloader flow [3] + - Get the "reboot reason" (and act accordingly) [4] + - Get/pass a list of commands from/to recovery [1] + - TODO + + +2. 'BCB'. SHELL COMMAND OVERVIEW +----------------------------------- +The 'bcb' command provides a CLI to facilitate the development of the +requirements enumerated above. Below is the command's help message: + +=> bcb +bcb - Load/set/clear/test/dump/store Android BCB fields + +Usage: +bcb load - load BCB from mmc : +bcb set - set BCB to +bcb clear [] - clear BCB or all fields +bcb test - test BCB against +bcb dump - dump BCB +bcb store - store BCB back to mmc + +Legend: + - MMC device index containing the BCB partition + - MMC partition index or name containing the BCB + - one of {command,status,recovery,stage,reserved} + - the binary operator used in 'bcb test': + '=' returns true if matches the string stored in + '~' returns true if matches a subset of 's string + - string/text provided as input to bcb {set,test} + NOTE: any ':' character in will be replaced by line feed + during 'bcb set' and used as separator by upper layers + + +3. 'BCB'. EXAMPLE OF GETTING REBOOT REASON +----------------------------------- +if bcb load 1 misc; then + # valid BCB found + if bcb test command = bootonce-bootloader; then + bcb clear command; bcb store; + # do the equivalent of AOSP ${fastbootcmd} + # i.e. call fastboot + else if bcb test command = boot-recovery; then + bcb clear command; bcb store; + # do the equivalent of AOSP ${recoverycmd} + # i.e. do anything required for booting into recovery + else + # boot Android OS normally + fi +else + # corrupted/non-existent BCB + # report error or boot non-Android OS (platform-specific) +fi + + +4. ENABLE ON YOUR BOARD +----------------------------------- +The following Kconfig options must be enabled: +CONFIG_PARTITIONS=y +CONFIG_MMC=y +CONFIG_BCB=y + +[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") +[4] https://source.android.com/devices/bootloader/boot-reason