From patchwork Sun Mar 7 19:31:47 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1448742 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.a=rsa-sha256 header.s=google header.b=D7wXUyb3; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4DtsBS5Mm6z9sW5 for ; Mon, 8 Mar 2021 06:35:12 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 7E28E827AA; Sun, 7 Mar 2021 20:32:45 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="D7wXUyb3"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 3D8DE82842; Sun, 7 Mar 2021 20:32:19 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-oi1-x230.google.com (mail-oi1-x230.google.com [IPv6:2607:f8b0:4864:20::230]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 1B076827F9 for ; Sun, 7 Mar 2021 20:32:13 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-oi1-x230.google.com with SMTP id u198so3796838oia.4 for ; Sun, 07 Mar 2021 11:32:13 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Ga05eGr6MykF+F9ohLkTgUoipc1bHYG6ZMfwJdXZ0P8=; b=D7wXUyb3D2U4SX4OazfnMjlXAYsInbIai/Tt+TvhNl4L2XhKeoU1wH0wZHgzuiWfRL HNxWDrxyYze+YCtQdAEKfN7Rxe/DIDu1gYHZPzDdnxgHWsjx+JeR7XRCuIKc651j4QNl 23K7JZAcuBupYl0dks1rFxjPQKJefqiybjaPU= 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=Ga05eGr6MykF+F9ohLkTgUoipc1bHYG6ZMfwJdXZ0P8=; b=XFas4Q+PXvKCSR/MuGrMzWlRzjrY9v99T6sYMubw0fz5ZujBTm1XiIOziUJKMGsQjZ 7qxsD9kVRaXI21jAZiO4Vz8+jeLDvebQjZUEOE/oOSqZ+YEcj0OEWee+Ypr+TB8qjeFK Kiha/xVVHRjxFEI6KlmwcyHfQ9wR/xEBLNjczIIB6+Yh3ZF8ag/B+YbdyPHuThza6dpu hQk1Wqi1QglDsVFMp7obmG7zkJvV8KCYfKIEr/ekTiVie6N8JvTK2Be/IKk2TFA+6uuC pool4ROv4rSsW+4wAODpLaOgWmzVilZmj+whPkvv5u7J3+QgcRSASAsf2SufL98882Q8 v3og== X-Gm-Message-State: AOAM530IPXe1f87SIseCpl0idDvdnfH8F9Kp5qZj9aGI8PMiptdBGFAf KDK5BzCDFbXsMdKLNpwcMS3cGm9llWl4pTTL X-Google-Smtp-Source: ABdhPJyFaG3euvWd/tpM78uD/uUHhpV1zUT9KmnbVtSGAJ9ZPS539j3Rh8m4IbyoWtzYKBmS1YkDWA== X-Received: by 2002:aca:f44d:: with SMTP id s74mr7628400oih.168.1615145531701; Sun, 07 Mar 2021 11:32:11 -0800 (PST) Received: from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id z8sm891074otp.14.2021.03.07.11.32.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 07 Mar 2021 11:32:11 -0800 (PST) From: Simon Glass To: U-Boot Mailing List Cc: Simon Glass Subject: [PATCH 20/20] binman: Update various pieces of the documentation Date: Sun, 7 Mar 2021 12:31:47 -0700 Message-Id: <20210307193148.1513733-21-sjg@chromium.org> X-Mailer: git-send-email 2.30.1.766.gb4fecdf3b7-goog In-Reply-To: <20210307193148.1513733-1-sjg@chromium.org> References: <20210307193148.1513733-1-sjg@chromium.org> MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 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" X-Virus-Scanned: clamav-milter 0.102.4 at phobos.denx.de X-Virus-Status: Clean A few sections are a little out of date now. Update them. Signed-off-by: Simon Glass --- tools/binman/README.rst | 72 ++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/tools/binman/README.rst b/tools/binman/README.rst index 5df5de4d8e3..680a1c38a8d 100644 --- a/tools/binman/README.rst +++ b/tools/binman/README.rst @@ -9,39 +9,43 @@ For example, we may have SPL, U-Boot, a device tree and an environment area grouped together and placed in MMC flash. When the system starts, it must be able to find these pieces. -So far U-Boot has not provided a way to handle creating such images in a -general way. Each SoC does what it needs to build an image, often packing or -concatenating images in the U-Boot build system. - -Binman aims to provide a mechanism for building images, from simple -SPL + U-Boot combinations, to more complex arrangements with many parts. +Building firmware should be separate from packaging it. Many of the complexities +of modern firmware build systems come from trying to do both at once. With +binman, you build all the pieces that are needed, using whatever assortment of +projects and build systems are needed, then use binman to stitch everything +together. What it does ------------ Binman reads your board's device tree and finds a node which describes the -required image layout. It uses this to work out what to place where. The -output file normally contains the device tree, so it is in principle possible -to read an image and extract its constituent parts. +required image layout. It uses this to work out what to place where. + +Binman provides a mechanism for building images, from simple SPL + U-Boot +combinations, to more complex arrangements with many parts. It also allows +users to inspect images, extract and replace binaries within them, repacking if +needed. Features -------- -So far binman is pretty simple. It supports binary blobs, such as 'u-boot', -'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can -place entries at a fixed location in the image, or fit them together with -suitable padding and alignment. It provides a way to process binaries before -they are included, by adding a Python plug-in. The device tree is available -to U-Boot at run-time so that the images can be interpreted. +Apart from basic padding, alignment and positioning features, Binman supports +hierarchical images, compression, hashing and dealing with the binary blobs +which are a sad trend in open-source firmware at present. -Binman can update the device tree with the final location of everything when it -is done. Entry positions can be provided to U-Boot SPL as run-time symbols, -avoiding device-tree code overhead. +Executable binaries can access the location of other binaries in an image by +using special linker symbols (zero-overhead but somewhat limited) or by reading +the devicetree description of the image. -Binman can also support incorporating filesystems in the image if required. -For example x86 platforms may use CBFS in some cases. +Binman is designed primarily for use with U-Boot and associated binaries such +as ARM Trusted Firmware, but it is suitable for use with other projects, such +as Zephyr. Binman also provides facilities useful in Chromium OS, such as CBFS, +vblocks and and the like. + +Binman provides a way to process binaries before they are included, by adding a +Python plug-in. Binman is intended for use with U-Boot but is designed to be general enough to be useful in other image-packaging situations. @@ -50,11 +54,11 @@ to be useful in other image-packaging situations. Motivation ---------- -Packaging of firmware is quite a different task from building the various -parts. In many cases the various binaries which go into the image come from -separate build systems. For example, ARM Trusted Firmware is used on ARMv8 -devices but is not built in the U-Boot tree. If a Linux kernel is included -in the firmware image, it is built elsewhere. +As mentioned above, packaging of firmware is quite a different task from +building the various parts. In many cases the various binaries which go into +the image come from separate build systems. For example, ARM Trusted Firmware +is used on ARMv8 devices but is not built in the U-Boot tree. If a Linux kernel +is included in the firmware image, it is built elsewhere. It is of course possible to add more and more build rules to the U-Boot build system to cover these cases. It can shell out to other Makefiles and @@ -215,17 +219,12 @@ Binman has a few other options which you can see by running 'binman -h'. Enabling binman for a board --------------------------- -At present binman is invoked from a rule in the main Makefile. Typically you -will have a rule like:: - - ifneq ($(CONFIG_ARCH_),) - u-boot-.bin: checkbinman FORCE - $(call if_changed,binman) - endif +At present binman is invoked from a rule in the main Makefile. You should be +able to enable CONFIG_BINMAN to enable this rule. -This assumes that u-boot-.bin is a target, and is the final file -that you need to produce. You can make it a target by adding it to INPUTS-y -either in the main Makefile or in a config.mk file in your arch subdirectory. +The output file is typically named image.bin and is located in the output +directory. If input files are needed to you add these to INPUTS-y either in the +main Makefile or in a config.mk file in your arch subdirectory. Once binman is executed it will pick up its instructions from a device-tree file, typically -u-boot.dtsi, where is your CONFIG_SYS_SOC value. @@ -1141,7 +1140,8 @@ To do Some ideas: - Use of-platdata to make the information available to code that is unable - to use device tree (such as a very small SPL image) + to use device tree (such as a very small SPL image). For now, limited info is + available via linker symbols - Allow easy building of images by specifying just the board name - Support building an image for a board (-b) more completely, with a configurable build directory