From patchwork Sun Mar 7 19:31:44 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1448741 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=i20PGi6v; 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 4DtsBG2Z67z9sW5 for ; Mon, 8 Mar 2021 06:35:02 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 5B17C828A4; Sun, 7 Mar 2021 20:32:43 +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="i20PGi6v"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 8BE6C8283C; 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-x235.google.com (mail-oi1-x235.google.com [IPv6:2607:f8b0:4864:20::235]) (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 93AB3827E3 for ; Sun, 7 Mar 2021 20:32:10 +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-x235.google.com with SMTP id d20so8739508oiw.10 for ; Sun, 07 Mar 2021 11:32:10 -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=tbXG2J6/OCBhJT6SaEia/fuYhZFv+r/sIzP8dWFJuPo=; b=i20PGi6vzri0BHcouzUGMbITh4rxKC7y/jVFV/KEVdHSdq1QVdKI9B4rOaRdyGdtg5 tLBvLK2lnzuVr+ZPItkG2euooGDMSsqNe/Jm6Cf+9ms9H+KFZLHXV/kdekmXkul/EG7B lLRxgK35vldcR18vzPiq9FJwV5GomOCsIuP5E= 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=tbXG2J6/OCBhJT6SaEia/fuYhZFv+r/sIzP8dWFJuPo=; b=MVNBYr3M10lwb+UGb+vc6QS9mEH6RyZi2kYqnAiN9DqKIE29SwVI1BBTMbQu01ctEi RjfwObebH3me7k9TxkcNg2ZprEUd7c6jh2Km7gMbXpVlSF1htkEFwce7CC3xd0Oyrczz q59mrp9NhlTwjAkB4LzCkM2qnxu5rGzaI80vEt43ZgaJQWxqUyDlTmefCMu+MX5CiFfX JBBProLezAeR800aHiPaI4EBEal6i7r4eBxGh4UzJGENuRZp/t3FHTzIH5zEkMuJOBv0 uxDfDsGkGk5vHUq+ZHlXE4xBFDejM0RS5rovvYa36f6NqRuhCVwsDfqKUQY068f1XiI2 /NOw== X-Gm-Message-State: AOAM530tyZxt8NHm/l/w/KfDcUHje7CKKHj0tN3XnMtPvJPMm3Eewts4 ldSGcro6EVgZ5xLPwJTusBp0xetrpIEe32nm X-Google-Smtp-Source: ABdhPJw7JkwVedkt1zby5J7c+HGYgpCsEuKgSJHdCG7orzB+zdjd9ivVWkZYfzuBuDJ2d9nsrP3Xzg== X-Received: by 2002:aca:ba02:: with SMTP id k2mr15394077oif.60.1615145528684; Sun, 07 Mar 2021 11:32:08 -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.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 07 Mar 2021 11:32:08 -0800 (PST) From: Simon Glass To: U-Boot Mailing List Cc: Simon Glass Subject: [PATCH 17/20] binman: Rearrange documentation into headings Date: Sun, 7 Mar 2021 12:31:44 -0700 Message-Id: <20210307193148.1513733-18-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 Collect the material into different top-level headings to make it easier to read. Signed-off-by: Simon Glass --- tools/binman/README.rst | 523 ++++++++++++++++++++-------------------- 1 file changed, 266 insertions(+), 257 deletions(-) diff --git a/tools/binman/README.rst b/tools/binman/README.rst index 8d06aa91287..9348a3e8e1d 100644 --- a/tools/binman/README.rst +++ b/tools/binman/README.rst @@ -2,7 +2,7 @@ # Copyright (c) 2016 Google, Inc Introduction ------------- +============ Firmware often consists of several components which must be packaged together. For example, we may have SPL, U-Boot, a device tree and an environment area @@ -137,6 +137,9 @@ the boundaries between building input files (mkimage) and packaging then into a final image (binman). +Using binman +============ + Example use of binman in U-Boot ------------------------------- @@ -230,8 +233,111 @@ You can use other, more specific CONFIG options - see 'Automatic .dtsi inclusion' below. +Access to binman entry offsets at run time (symbols) +---------------------------------------------------- + +Binman assembles images and determines where each entry is placed in the image. +This information may be useful to U-Boot at run time. For example, in SPL it +is useful to be able to find the location of U-Boot so that it can be executed +when SPL is finished. + +Binman allows you to declare symbols in the SPL image which are filled in +with their correct values during the build. For example:: + + binman_sym_declare(ulong, u_boot_any, image_pos); + +declares a ulong value which will be assigned to the image-pos of any U-Boot +image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. +You can access this value with something like:: + + ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); + +Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming +that the whole image has been loaded, or is available in flash. You can then +jump to that address to start U-Boot. + +At present this feature is only supported in SPL and TPL. In principle it is +possible to fill in such symbols in U-Boot proper, as well, but a future C +library is planned for this instead, to read from the device tree. + +As well as image-pos, it is possible to read the size of an entry and its +offset (which is the start position of the entry within its parent). + +A small technical note: Binman automatically adds the base address of the image +(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the +image is loaded to its linked address, the value will be correct and actually +point into the image. + +For example, say SPL is at the start of the image and linked to start at address +80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos +for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded +to 80108000, with SPL at 80108000 and U-Boot at 80110000. + +For x86 devices (with the end-at-4gb property) this base address is not added +since it is assumed that images are XIP and the offsets already include the +address. + + +Access to binman entry offsets at run time (fdt) +------------------------------------------------ + +Binman can update the U-Boot FDT to include the final position and size of +each entry in the images it processes. The option to enable this is -u and it +causes binman to make sure that the 'offset', 'image-pos' and 'size' properties +are set correctly for every entry. Since it is not necessary to specify these in +the image definition, binman calculates the final values and writes these to +the device tree. These can be used by U-Boot at run-time to find the location +of each entry. + +Alternatively, an FDT map entry can be used to add a special FDT containing +just the information about the image. This is preceded by a magic string so can +be located anywhere in the image. An image header (typically at the start or end +of the image) can be used to point to the FDT map. See fdtmap and image-header +entries for more information. + + +Map files +--------- + +The -m option causes binman to output a .map file for each image that it +generates. This shows the offset and size of each entry. For example:: + + Offset Size Name + 00000000 00000028 main-section + 00000000 00000010 section@0 + 00000000 00000004 u-boot + 00000010 00000010 section@1 + 00000000 00000004 u-boot + +This shows a hierarchical image with two sections, each with a single entry. The +offsets of the sections are absolute hex byte offsets within the image. The +offsets of the entries are relative to their respective sections. The size of +each entry is also shown, in bytes (hex). The indentation shows the entries +nested inside their sections. + + +Passing command-line arguments to entries +----------------------------------------- + +Sometimes it is useful to pass binman the value of an entry property from the +command line. For example some entries need access to files and it is not +always convenient to put these filenames in the image definition (device tree). + +The-a option supports this:: + + -a= + +where:: + + is the property to set + is the value to set it to + +Not all properties can be provided this way. Only some entries support it, +typically for filenames. + + Image description format ------------------------- +======================== The binman node is called 'binman'. An example image description is shown below:: @@ -528,6 +634,157 @@ allow-repack: image description to be stored in the FDT and fdtmap. +Hashing Entries +--------------- + +It is possible to ask binman to hash the contents of an entry and write that +value back to the device-tree node. For example:: + + binman { + u-boot { + hash { + algo = "sha256"; + }; + }; + }; + +Here, a new 'value' property will be written to the 'hash' node containing +the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole +sections can be hased if desired, by adding the 'hash' node to the section. + +The has value can be chcked at runtime by hashing the data actually read and +comparing this has to the value in the device tree. + + +Expanded entries +---------------- + +Binman automatically replaces 'u-boot' with an expanded version of that, i.e. +'u-boot-expanded'. This means that when you write:: + + u-boot { + }; + +you actually get:: + + u-boot { + type = "u-boot-expanded'; + }; + +which in turn expands to:: + + u-boot { + type = "section"; + + u-boot-nodtb { + }; + + u-boot-dtb { + }; + }; + +U-Boot's various phase binaries actually comprise two or three pieces. +For example, u-boot.bin has the executable followed by a devicetree. + +With binman we want to be able to update that devicetree with full image +information so that it is accessible to the executable. This is tricky +if it is not clear where the devicetree starts. + +The above feature ensures that the devicetree is clearly separated from the +U-Boot executable and can be updated separately by binman as needed. It can be +disabled with the --no-expanded flag if required. + +The same applies for u-boot-spl and u-boot-spl. In those cases, the expansion +includes the BSS padding, so for example:: + + spl { + type = "u-boot-spl" + }; + +you actually get:: + + spl { + type = "u-boot-expanded'; + }; + +which in turn expands to:: + + spl { + type = "section"; + + u-boot-spl-nodtb { + }; + + u-boot-spl-bss-pad { + }; + + u-boot-spl-dtb { + }; + }; + +Of course we should not expand SPL if it has no devicetree. Also if the BSS +padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS), +the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned +entry type is controlled by the UseExpanded() method. In the SPL case it checks +the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree. + +For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All +entry args are provided by the U-Boot Makefile. + + +Compression +----------- + +Binman support compression for 'blob' entries (those of type 'blob' and +derivatives). To enable this for an entry, add a 'compress' property:: + + blob { + filename = "datafile"; + compress = "lz4"; + }; + +The entry will then contain the compressed data, using the 'lz4' compression +algorithm. Currently this is the only one that is supported. The uncompressed +size is written to the node in an 'uncomp-size' property, if -u is used. + +Compression is also supported for sections. In that case the entire section is +compressed in one block, including all its contents. This means that accessing +an entry from the section required decompressing the entire section. Also, the +size of a section indicates the space that it consumes in its parent section +(and typically the image). With compression, the section may contain more data, +and the uncomp-size property indicates that, as above. The contents of the +section is compressed first, before any padding is added. This ensures that the +padding itself is not compressed, which would be a waste of time. + + +Automatic .dtsi inclusion +------------------------- + +It is sometimes inconvenient to add a 'binman' node to the .dts file for each +board. This can be done by using #include to bring in a common file. Another +approach supported by the U-Boot build system is to automatically include +a common header. You can then put the binman node (and anything else that is +specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header +file. + +Binman will search for the following files in arch//dts:: + + -u-boot.dtsi where is the base name of the .dts file + -u-boot.dtsi + -u-boot.dtsi + -u-boot.dtsi + u-boot.dtsi + +U-Boot will only use the first one that it finds. If you need to include a +more general file you can do that from the more specific file using #include. +If you are having trouble figuring out what is going on, you can uncomment +the 'warning' line in scripts/Makefile.lib to see what it has found:: + + # Uncomment for debugging + # This shows all the files that were considered and the one that we chose. + # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw) + + Entry Documentation ------------------- @@ -537,6 +794,9 @@ see README.entries. This is generated from the source code using: binman entry-docs >tools/binman/README.entries +Managing images +=============== + Listing images -------------- @@ -653,27 +913,9 @@ by increasing the -v/--verbosity from the default of 1: You can use BINMAN_VERBOSE=5 (for example) when building to select this. -Hashing Entries ---------------- - -It is possible to ask binman to hash the contents of an entry and write that -value back to the device-tree node. For example:: - - binman { - u-boot { - hash { - algo = "sha256"; - }; - }; - }; - -Here, a new 'value' property will be written to the 'hash' node containing -the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole -sections can be hased if desired, by adding the 'hash' node to the section. - -The has value can be chcked at runtime by hashing the data actually read and -comparing this has to the value in the device tree. +Technical details +================= Order of image creation ----------------------- @@ -750,239 +992,6 @@ what happens in this stage. final step. -Automatic .dtsi inclusion -------------------------- - -It is sometimes inconvenient to add a 'binman' node to the .dts file for each -board. This can be done by using #include to bring in a common file. Another -approach supported by the U-Boot build system is to automatically include -a common header. You can then put the binman node (and anything else that is -specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header -file. - -Binman will search for the following files in arch//dts:: - - -u-boot.dtsi where is the base name of the .dts file - -u-boot.dtsi - -u-boot.dtsi - -u-boot.dtsi - u-boot.dtsi - -U-Boot will only use the first one that it finds. If you need to include a -more general file you can do that from the more specific file using #include. -If you are having trouble figuring out what is going on, you can uncomment -the 'warning' line in scripts/Makefile.lib to see what it has found:: - - # Uncomment for debugging - # This shows all the files that were considered and the one that we chose. - # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw) - - -Access to binman entry offsets at run time (symbols) ----------------------------------------------------- - -Binman assembles images and determines where each entry is placed in the image. -This information may be useful to U-Boot at run time. For example, in SPL it -is useful to be able to find the location of U-Boot so that it can be executed -when SPL is finished. - -Binman allows you to declare symbols in the SPL image which are filled in -with their correct values during the build. For example:: - - binman_sym_declare(ulong, u_boot_any, image_pos); - -declares a ulong value which will be assigned to the image-pos of any U-Boot -image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. -You can access this value with something like:: - - ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); - -Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming -that the whole image has been loaded, or is available in flash. You can then -jump to that address to start U-Boot. - -At present this feature is only supported in SPL and TPL. In principle it is -possible to fill in such symbols in U-Boot proper, as well, but a future C -library is planned for this instead, to read from the device tree. - -As well as image-pos, it is possible to read the size of an entry and its -offset (which is the start position of the entry within its parent). - -A small technical note: Binman automatically adds the base address of the image -(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the -image is loaded to its linked address, the value will be correct and actually -point into the image. - -For example, say SPL is at the start of the image and linked to start at address -80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos -for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded -to 80108000, with SPL at 80108000 and U-Boot at 80110000. - -For x86 devices (with the end-at-4gb property) this base address is not added -since it is assumed that images are XIP and the offsets already include the -address. - - -Access to binman entry offsets at run time (fdt) ------------------------------------------------- - -Binman can update the U-Boot FDT to include the final position and size of -each entry in the images it processes. The option to enable this is -u and it -causes binman to make sure that the 'offset', 'image-pos' and 'size' properties -are set correctly for every entry. Since it is not necessary to specify these in -the image definition, binman calculates the final values and writes these to -the device tree. These can be used by U-Boot at run-time to find the location -of each entry. - -Alternatively, an FDT map entry can be used to add a special FDT containing -just the information about the image. This is preceded by a magic string so can -be located anywhere in the image. An image header (typically at the start or end -of the image) can be used to point to the FDT map. See fdtmap and image-header -entries for more information. - - -Expanded entries ----------------- - -Binman automatically replaces 'u-boot' with an expanded version of that, i.e. -'u-boot-expanded'. This means that when you write:: - - u-boot { - }; - -you actually get:: - - u-boot { - type = "u-boot-expanded'; - }; - -which in turn expands to:: - - u-boot { - type = "section"; - - u-boot-nodtb { - }; - - u-boot-dtb { - }; - }; - -U-Boot's various phase binaries actually comprise two or three pieces. -For example, u-boot.bin has the executable followed by a devicetree. - -With binman we want to be able to update that devicetree with full image -information so that it is accessible to the executable. This is tricky -if it is not clear where the devicetree starts. - -The above feature ensures that the devicetree is clearly separated from the -U-Boot executable and can be updated separately by binman as needed. It can be -disabled with the --no-expanded flag if required. - -The same applies for u-boot-spl and u-boot-spl. In those cases, the expansion -includes the BSS padding, so for example:: - - spl { - type = "u-boot-spl" - }; - -you actually get:: - - spl { - type = "u-boot-expanded'; - }; - -which in turn expands to:: - - spl { - type = "section"; - - u-boot-spl-nodtb { - }; - - u-boot-spl-bss-pad { - }; - - u-boot-spl-dtb { - }; - }; - - -Of course we should not expand SPL if it has no devicetree. Also if the BSS -padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS), -the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned -entry type is controlled by the UseExpanded() method. In the SPL case it checks -the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree. - -For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All -entry args are provided by the U-Boot Makefile. - - -Compression ------------ - -Binman support compression for 'blob' entries (those of type 'blob' and -derivatives). To enable this for an entry, add a 'compress' property:: - - blob { - filename = "datafile"; - compress = "lz4"; - }; - -The entry will then contain the compressed data, using the 'lz4' compression -algorithm. Currently this is the only one that is supported. The uncompressed -size is written to the node in an 'uncomp-size' property, if -u is used. - -Compression is also supported for sections. In that case the entire section is -compressed in one block, including all its contents. This means that accessing -an entry from the section required decompressing the entire section. Also, the -size of a section indicates the space that it consumes in its parent section -(and typically the image). With compression, the section may contain more data, -and the uncomp-size property indicates that, as above. The contents of the -section is compressed first, before any padding is added. This ensures that the -padding itself is not compressed, which would be a waste of time. - - -Map files ---------- - -The -m option causes binman to output a .map file for each image that it -generates. This shows the offset and size of each entry. For example:: - - Offset Size Name - 00000000 00000028 main-section - 00000000 00000010 section@0 - 00000000 00000004 u-boot - 00000010 00000010 section@1 - 00000000 00000004 u-boot - -This shows a hierarchical image with two sections, each with a single entry. The -offsets of the sections are absolute hex byte offsets within the image. The -offsets of the entries are relative to their respective sections. The size of -each entry is also shown, in bytes (hex). The indentation shows the entries -nested inside their sections. - - -Passing command-line arguments to entries ------------------------------------------ - -Sometimes it is useful to pass binman the value of an entry property from the -command line. For example some entries need access to files and it is not -always convenient to put these filenames in the image definition (device tree). - -The-a option supports this:: - - -a= - -where:: - - is the property to set - is the value to set it to - -Not all properties can be provided this way. Only some entries support it, -typically for filenames. - - External tools -------------- @@ -1050,8 +1059,8 @@ Then, you can run the tests under cross-compilation:: You can also use gcc-i686-linux-gnu similar to the above. -Advanced Features / Technical docs ----------------------------------- +Writing new entries and debugging +--------------------------------- The behaviour of entries is defined by the Entry class. All other entries are a subclass of this. An important subclass is Entry_blob which takes binary