From patchwork Tue Nov 23 18:03:49 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1558719 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.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=jyAqTeur; dkim-atps=neutral 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=) 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 bilbo.ozlabs.org (Postfix) with ESMTPS id 4HzBsm2cNzz9ssD for ; Wed, 24 Nov 2021 05:06:36 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 990E083774; Tue, 23 Nov 2021 19:05:54 +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="jyAqTeur"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 0BC7383711; Tue, 23 Nov 2021 19:04:47 +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.8 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-oi1-x22b.google.com (mail-oi1-x22b.google.com [IPv6:2607:f8b0:4864:20::22b]) (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 1A84F836DC for ; Tue, 23 Nov 2021 19:04:29 +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-x22b.google.com with SMTP id bj13so46210416oib.4 for ; Tue, 23 Nov 2021 10:04:29 -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=e1C80HIjz+Ip3yNReWT15MvWG+M9Sl2dprG0B/dKMjo=; b=jyAqTeurdNOKll1IR8zp1zxESBYYZ70lv2IV5IP4KoWwhpey5eaGs8ycAAW+SiYG79 LXM7eeYejDHXt/X+xhVl3A0ZVFK6aFJpLl9lLIt8se4/PL65+qEXct+JpwlxGRMFrHpO 8wFgUZwMr3/74094I7wlQV554p1VLfVziVbAU= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=e1C80HIjz+Ip3yNReWT15MvWG+M9Sl2dprG0B/dKMjo=; b=q+cQLZu/wfBUkbWWJvdvtyXZp0JKv8bCSvp8Gai0nRn4MbWGm/NNrsYTuiiToOmtRh 7qInHHlJnTC/0eB6kmz0Ot5WSriJqZ9JIxlkoP1+ZeBOg2t1diAdRDcQpH3VJAm/OaQV i0VLyXdKVLfhRpTnPtyhr1oG+30EzHuew7h3i7gr2WxzdTKcRPhMyDIb+IbvHrSxG9tn S8zGOZue+x3LOYGS5c7SNtU3H1jC4Y8YlDQZ3HqlV7s6FLQ9g/XXxHoBx5d7iKHZ+d7s qW1L1n59+alt2yKcTjYYn9C+riNzVys3fdSki8oSc6WIxDbYWeBefE9aUdNN0ngJICAO tysg== X-Gm-Message-State: AOAM5308jyK38gt9bwWRsWAr99KWKKwRPAgY3xarJ1zLDdKf4Q16vE8w HzP+A5Db1cfvxjj4t4dCwBcIzcPteP259g== X-Google-Smtp-Source: ABdhPJwvjiV95Z3CLwHjYxHpsLXN7NBSeJ/hnT1vnx008l8og3FpS/ypJT69e9E845WICpnvPq8oGw== X-Received: by 2002:a05:6808:1283:: with SMTP id a3mr4545556oiw.29.1637690666928; Tue, 23 Nov 2021 10:04:26 -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 c8sm2357514otk.40.2021.11.23.10.04.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Nov 2021 10:04:26 -0800 (PST) From: Simon Glass To: U-Boot Mailing List Cc: Tom Rini , Simon Glass Subject: [PATCH 12/17] binman: Update the section documentation Date: Tue, 23 Nov 2021 11:03:49 -0700 Message-Id: <20211123180354.615946-13-sjg@chromium.org> X-Mailer: git-send-email 2.34.0.rc2.393.gf8c9666880-goog In-Reply-To: <20211123180354.615946-1-sjg@chromium.org> References: <20211123180354.615946-1-sjg@chromium.org> MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.37 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.103.2 at phobos.denx.de X-Virus-Status: Clean Expand this to explain subclassing better and also to tidy up formatting for rST. Fix a few pylint warnings to avoid dropping the score. Signed-off-by: Simon Glass Signed-off-by: Simon Glass --- tools/binman/entries.rst | 149 +++++++++++++++++++++++++++------- tools/binman/etype/section.py | 148 +++++++++++++++++++++++++++------ 2 files changed, 242 insertions(+), 55 deletions(-) diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst index dcac700c461..748277c1cde 100644 --- a/tools/binman/entries.rst +++ b/tools/binman/entries.rst @@ -799,39 +799,130 @@ This entry holds firmware for an external platform-specific coprocessor. Entry: section: Entry that contains other entries ------------------------------------------------- -Properties / Entry arguments: (see binman README for more information): - pad-byte: Pad byte to use when padding - sort-by-offset: True if entries should be sorted by offset, False if - they must be in-order in the device tree description - - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) - - skip-at-start: Number of bytes before the first entry starts. These - effectively adjust the starting offset of entries. For example, - if this is 16, then the first entry would start at 16. An entry - with offset = 20 would in fact be written at offset 4 in the image - file, since the first 16 bytes are skipped when writing. - name-prefix: Adds a prefix to the name of every entry in the section - when writing out the map - align_default: Default alignment for this section, if no alignment is - given in the entry - -Properties: - allow_missing: True if this section permits external blobs to be - missing their contents. The second will produce an image but of - course it will not work. - -Properties: - _allow_missing: True if this section permits external blobs to be - missing their contents. The second will produce an image but of - course it will not work. +A section is an entry which can contain other entries, thus allowing +hierarchical images to be created. See 'Sections and hierarchical images' +in the binman README for more information. + +The base implementation simply joins the various entries together, using +various rules about alignment, etc. + +Subclassing +~~~~~~~~~~~ + +This class can be subclassed to support other file formats which hold +multiple entries, such as CBFS. To do this, override the following +functions. The documentation here describes what your function should do. +For example code, see etypes which subclass `Entry_section`, or `cbfs.py` +for a more involved example:: + + $ grep -l \(Entry_section tools/binman/etype/*.py + +ReadNode() + Call `super().ReadNode()`, then read any special properties for the + section. Then call `self.ReadEntries()` to read the entries. + + Binman calls this at the start when reading the image description. + +ReadEntries() + Read in the subnodes of the section. This may involve creating entries + of a particular etype automatically, as well as reading any special + properties in the entries. For each entry, entry.ReadNode() should be + called, to read the basic entry properties. The properties should be + added to `self._entries[]`, in the correct order, with a suitable name. + + Binman calls this at the start when reading the image description. + +BuildSectionData(required) + Create the custom file format that you want and return it as bytes. + This likely sets up a file header, then loops through the entries, + adding them to the file. For each entry, call `entry.GetData()` to + obtain the data. If that returns None, and `required` is False, then + this method must give up and return None. But if `required` is True then + it should assume that all data is valid. + + Binman calls this when packing the image, to find out the size of + everything. It is called again at the end when building the final image. + +SetImagePos(image_pos): + Call `super().SetImagePos(image_pos)`, then set the `image_pos` values + for each of the entries. This should use the custom file format to find + the `start offset` (and `image_pos`) of each entry. If the file format + uses compression in such a way that there is no offset available (other + than reading the whole file and decompressing it), then the offsets for + affected entries can remain unset (`None`). The size should also be set + if possible. + + Binman calls this after the image has been packed, to update the + location that all the entries ended up at. + +ReadChildData(child, decomp): + The default version of this may be good enough, if you are able to + implement SetImagePos() correctly. But that is a bit of a bypass, so + you can override this method to read from your custom file format. It + should read the entire entry containing the custom file using + `super().ReadData(True)`, then parse the file to get the data for the + given child, then return that data. + + If your file format supports compression, the `decomp` argument tells + you whether to return the compressed data (`decomp` is False) or to + uncompress it first, then return the uncompressed data (`decomp` is + True). This is used by the `binman extract -U` option. + + Binman calls this when reading in an image, in order to populate all the + entries with the data from that image (`binman ls`). + +WriteChildData(child): + Binman calls this after `child.data` is updated, to inform the custom + file format about this, in case it needs to do updates. + + The default version of this does nothing and probably needs to be + overridden for the 'binman replace' command to work. Your version should + use `child.data` to update the data for that child in the custom file + format. + + Binman calls this when updating an image that has been read in and in + particular to update the data for a particular entry (`binman replace`) + +Properties / Entry arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`develop/package/binman:Image description format` for more +information. + +align-default + Default alignment for this section, if no alignment is given in the + entry + +pad-byte + Pad byte to use when padding + +sort-by-offset + True if entries should be sorted by offset, False if they must be + in-order in the device tree description + +end-at-4gb + Used to build an x86 ROM which ends at 4GB (2^32) + +name-prefix + Adds a prefix to the name of every entry in the section when writing out + the map + +skip-at-start + Number of bytes before the first entry starts. These effectively adjust + the starting offset of entries. For example, if this is 16, then the + first entry would start at 16. An entry with offset = 20 would in fact + be written at offset 4 in the image file, since the first 16 bytes are + skipped when writing. Since a section is also an entry, it inherits all the properies of entries too. -A section is an entry which can contain other entries, thus allowing -hierarchical images to be created. See 'Sections and hierarchical images' -in the binman README for more information. +Note that the `allow_missing` member controls whether this section permits +external blobs to be missing their contents. The option will produce an +image but of course it will not work. It is useful to make sure that +Continuous Integration systems can build without the binaries being +available. This is set by the `SetAllowMissing()` method, if +`--allow-missing` is passed to binman. diff --git a/tools/binman/etype/section.py b/tools/binman/etype/section.py index 76e5eb19648..2e01dccc6db 100644 --- a/tools/binman/etype/section.py +++ b/tools/binman/etype/section.py @@ -24,34 +24,130 @@ from patman.tools import ToHexSize class Entry_section(Entry): """Entry that contains other entries - Properties / Entry arguments: (see binman README for more information): - pad-byte: Pad byte to use when padding - sort-by-offset: True if entries should be sorted by offset, False if - they must be in-order in the device tree description - - end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32) - - skip-at-start: Number of bytes before the first entry starts. These - effectively adjust the starting offset of entries. For example, - if this is 16, then the first entry would start at 16. An entry - with offset = 20 would in fact be written at offset 4 in the image - file, since the first 16 bytes are skipped when writing. - name-prefix: Adds a prefix to the name of every entry in the section - when writing out the map - align_default: Default alignment for this section, if no alignment is - given in the entry - - Properties: - allow_missing: True if this section permits external blobs to be - missing their contents. The second will produce an image but of - course it will not work. + A section is an entry which can contain other entries, thus allowing + hierarchical images to be created. See 'Sections and hierarchical images' + in the binman README for more information. + + The base implementation simply joins the various entries together, using + various rules about alignment, etc. + + Subclassing + ~~~~~~~~~~~ + + This class can be subclassed to support other file formats which hold + multiple entries, such as CBFS. To do this, override the following + functions. The documentation here describes what your function should do. + For example code, see etypes which subclass `Entry_section`, or `cbfs.py` + for a more involved example:: + + $ grep -l \(Entry_section tools/binman/etype/*.py + + ReadNode() + Call `super().ReadNode()`, then read any special properties for the + section. Then call `self.ReadEntries()` to read the entries. + + Binman calls this at the start when reading the image description. + + ReadEntries() + Read in the subnodes of the section. This may involve creating entries + of a particular etype automatically, as well as reading any special + properties in the entries. For each entry, entry.ReadNode() should be + called, to read the basic entry properties. The properties should be + added to `self._entries[]`, in the correct order, with a suitable name. + + Binman calls this at the start when reading the image description. + + BuildSectionData(required) + Create the custom file format that you want and return it as bytes. + This likely sets up a file header, then loops through the entries, + adding them to the file. For each entry, call `entry.GetData()` to + obtain the data. If that returns None, and `required` is False, then + this method must give up and return None. But if `required` is True then + it should assume that all data is valid. + + Binman calls this when packing the image, to find out the size of + everything. It is called again at the end when building the final image. + + SetImagePos(image_pos): + Call `super().SetImagePos(image_pos)`, then set the `image_pos` values + for each of the entries. This should use the custom file format to find + the `start offset` (and `image_pos`) of each entry. If the file format + uses compression in such a way that there is no offset available (other + than reading the whole file and decompressing it), then the offsets for + affected entries can remain unset (`None`). The size should also be set + if possible. + + Binman calls this after the image has been packed, to update the + location that all the entries ended up at. + + ReadChildData(child, decomp): + The default version of this may be good enough, if you are able to + implement SetImagePos() correctly. But that is a bit of a bypass, so + you can override this method to read from your custom file format. It + should read the entire entry containing the custom file using + `super().ReadData(True)`, then parse the file to get the data for the + given child, then return that data. + + If your file format supports compression, the `decomp` argument tells + you whether to return the compressed data (`decomp` is False) or to + uncompress it first, then return the uncompressed data (`decomp` is + True). This is used by the `binman extract -U` option. + + Binman calls this when reading in an image, in order to populate all the + entries with the data from that image (`binman ls`). + + WriteChildData(child): + Binman calls this after `child.data` is updated, to inform the custom + file format about this, in case it needs to do updates. + + The default version of this does nothing and probably needs to be + overridden for the 'binman replace' command to work. Your version should + use `child.data` to update the data for that child in the custom file + format. + + Binman calls this when updating an image that has been read in and in + particular to update the data for a particular entry (`binman replace`) + + Properties / Entry arguments + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + See :ref:`develop/package/binman:Image description format` for more + information. + + align-default + Default alignment for this section, if no alignment is given in the + entry + + pad-byte + Pad byte to use when padding + + sort-by-offset + True if entries should be sorted by offset, False if they must be + in-order in the device tree description + + end-at-4gb + Used to build an x86 ROM which ends at 4GB (2^32) + + name-prefix + Adds a prefix to the name of every entry in the section when writing out + the map + + skip-at-start + Number of bytes before the first entry starts. These effectively adjust + the starting offset of entries. For example, if this is 16, then the + first entry would start at 16. An entry with offset = 20 would in fact + be written at offset 4 in the image file, since the first 16 bytes are + skipped when writing. Since a section is also an entry, it inherits all the properies of entries too. - A section is an entry which can contain other entries, thus allowing - hierarchical images to be created. See 'Sections and hierarchical images' - in the binman README for more information. + Note that the `allow_missing` member controls whether this section permits + external blobs to be missing their contents. The option will produce an + image but of course it will not work. It is useful to make sure that + Continuous Integration systems can build without the binaries being + available. This is set by the `SetAllowMissing()` method, if + `--allow-missing` is passed to binman. """ def __init__(self, section, etype, node, test=False): if not test: @@ -98,9 +194,9 @@ class Entry_section(Entry): """Raises an error for this section Args: - msg: Error message to use in the raise string + msg (str): Error message to use in the raise string Raises: - ValueError() + ValueError: always """ raise ValueError("Section '%s': %s" % (self._node.path, msg))