Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/1558719/?format=api
{ "id": 1558719, "url": "http://patchwork.ozlabs.org/api/patches/1558719/?format=api", "web_url": "http://patchwork.ozlabs.org/project/uboot/patch/20211123180354.615946-13-sjg@chromium.org/", "project": { "id": 18, "url": "http://patchwork.ozlabs.org/api/projects/18/?format=api", "name": "U-Boot", "link_name": "uboot", "list_id": "u-boot.lists.denx.de", "list_email": "u-boot@lists.denx.de", "web_url": null, "scm_url": null, "webscm_url": null, "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20211123180354.615946-13-sjg@chromium.org>", "list_archive_url": null, "date": "2021-11-23T18:03:49", "name": "[12/17] binman: Update the section documentation", "commit_ref": "3f495f18a756c786d39c487061df37ea4b5e1ecd", "pull_url": null, "state": "accepted", "archived": false, "hash": "7999a29441d78b985e56baeca8101ee3eb82d92a", "submitter": { "id": 6170, "url": "http://patchwork.ozlabs.org/api/people/6170/?format=api", "name": "Simon Glass", "email": "sjg@chromium.org" }, "delegate": { "id": 3184, "url": "http://patchwork.ozlabs.org/api/users/3184/?format=api", "username": "sjg", "first_name": "Simon", "last_name": "Glass", "email": "sjg@chromium.org" }, "mbox": "http://patchwork.ozlabs.org/project/uboot/patch/20211123180354.615946-13-sjg@chromium.org/mbox/", "series": [ { "id": 273476, "url": "http://patchwork.ozlabs.org/api/series/273476/?format=api", "web_url": "http://patchwork.ozlabs.org/project/uboot/list/?series=273476", "date": "2021-11-23T18:03:37", "name": "binman: Various tidy-ups and refactors", "version": 1, "mbox": "http://patchwork.ozlabs.org/series/273476/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/1558719/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/1558719/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<u-boot-bounces@lists.denx.de>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@bilbo.ozlabs.org", "Authentication-Results": [ "bilbo.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=chromium.org header.i=@chromium.org header.a=rsa-sha256\n header.s=google header.b=jyAqTeur;\n\tdkim-atps=neutral", "ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de\n (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de;\n envelope-from=u-boot-bounces@lists.denx.de; receiver=<UNKNOWN>)", "phobos.denx.de;\n dmarc=pass (p=none dis=none) header.from=chromium.org", "phobos.denx.de;\n spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de", "phobos.denx.de;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=chromium.org header.i=@chromium.org\n header.b=\"jyAqTeur\";\n\tdkim-atps=neutral", "phobos.denx.de;\n dmarc=pass (p=none dis=none) header.from=chromium.org", "phobos.denx.de;\n spf=pass smtp.mailfrom=sjg@chromium.org" ], "Received": [ "from phobos.denx.de (phobos.denx.de\n [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange X25519 server-signature RSA-PSS (4096 bits))\n\t(No client certificate requested)\n\tby bilbo.ozlabs.org (Postfix) with ESMTPS id 4HzBsm2cNzz9ssD\n\tfor <incoming@patchwork.ozlabs.org>; Wed, 24 Nov 2021 05:06:36 +1100 (AEDT)", "from h2850616.stratoserver.net (localhost [IPv6:::1])\n\tby phobos.denx.de (Postfix) with ESMTP id 990E083774;\n\tTue, 23 Nov 2021 19:05:54 +0100 (CET)", "by phobos.denx.de (Postfix, from userid 109)\n id 0BC7383711; Tue, 23 Nov 2021 19:04:47 +0100 (CET)", "from mail-oi1-x22b.google.com (mail-oi1-x22b.google.com\n [IPv6:2607:f8b0:4864:20::22b])\n (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits))\n (No client certificate requested)\n by phobos.denx.de (Postfix) with ESMTPS id 1A84F836DC\n for <u-boot@lists.denx.de>; Tue, 23 Nov 2021 19:04:29 +0100 (CET)", "by mail-oi1-x22b.google.com with SMTP id bj13so46210416oib.4\n for <u-boot@lists.denx.de>; Tue, 23 Nov 2021 10:04:29 -0800 (PST)", "from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net.\n [67.190.101.114])\n by smtp.gmail.com with ESMTPSA id c8sm2357514otk.40.2021.11.23.10.04.26\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Tue, 23 Nov 2021 10:04:26 -0800 (PST)" ], "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,\n DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,\n SPF_PASS autolearn=ham autolearn_force=no version=3.4.2", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org;\n s=google;\n h=from:to:cc:subject:date:message-id:in-reply-to:references\n :mime-version:content-transfer-encoding;\n bh=e1C80HIjz+Ip3yNReWT15MvWG+M9Sl2dprG0B/dKMjo=;\n b=jyAqTeurdNOKll1IR8zp1zxESBYYZ70lv2IV5IP4KoWwhpey5eaGs8ycAAW+SiYG79\n LXM7eeYejDHXt/X+xhVl3A0ZVFK6aFJpLl9lLIt8se4/PL65+qEXct+JpwlxGRMFrHpO\n 8wFgUZwMr3/74094I7wlQV554p1VLfVziVbAU=", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20210112;\n h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to\n :references:mime-version:content-transfer-encoding;\n bh=e1C80HIjz+Ip3yNReWT15MvWG+M9Sl2dprG0B/dKMjo=;\n b=q+cQLZu/wfBUkbWWJvdvtyXZp0JKv8bCSvp8Gai0nRn4MbWGm/NNrsYTuiiToOmtRh\n 7qInHHlJnTC/0eB6kmz0Ot5WSriJqZ9JIxlkoP1+ZeBOg2t1diAdRDcQpH3VJAm/OaQV\n i0VLyXdKVLfhRpTnPtyhr1oG+30EzHuew7h3i7gr2WxzdTKcRPhMyDIb+IbvHrSxG9tn\n S8zGOZue+x3LOYGS5c7SNtU3H1jC4Y8YlDQZ3HqlV7s6FLQ9g/XXxHoBx5d7iKHZ+d7s\n qW1L1n59+alt2yKcTjYYn9C+riNzVys3fdSki8oSc6WIxDbYWeBefE9aUdNN0ngJICAO\n tysg==", "X-Gm-Message-State": "AOAM5308jyK38gt9bwWRsWAr99KWKKwRPAgY3xarJ1zLDdKf4Q16vE8w\n HzP+A5Db1cfvxjj4t4dCwBcIzcPteP259g==", "X-Google-Smtp-Source": "\n ABdhPJwvjiV95Z3CLwHjYxHpsLXN7NBSeJ/hnT1vnx008l8og3FpS/ypJT69e9E845WICpnvPq8oGw==", "X-Received": "by 2002:a05:6808:1283:: with SMTP id\n a3mr4545556oiw.29.1637690666928;\n Tue, 23 Nov 2021 10:04:26 -0800 (PST)", "From": "Simon Glass <sjg@chromium.org>", "To": "U-Boot Mailing List <u-boot@lists.denx.de>", "Cc": "Tom Rini <trini@konsulko.com>,\n\tSimon Glass <sjg@chromium.org>", "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", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "u-boot@lists.denx.de", "X-Mailman-Version": "2.1.37", "Precedence": "list", "List-Id": "U-Boot discussion <u-boot.lists.denx.de>", "List-Unsubscribe": "<https://lists.denx.de/options/u-boot>,\n <mailto:u-boot-request@lists.denx.de?subject=unsubscribe>", "List-Archive": "<https://lists.denx.de/pipermail/u-boot/>", "List-Post": "<mailto:u-boot@lists.denx.de>", "List-Help": "<mailto:u-boot-request@lists.denx.de?subject=help>", "List-Subscribe": "<https://lists.denx.de/listinfo/u-boot>,\n <mailto:u-boot-request@lists.denx.de?subject=subscribe>", "Errors-To": "u-boot-bounces@lists.denx.de", "Sender": "\"U-Boot\" <u-boot-bounces@lists.denx.de>", "X-Virus-Scanned": "clamav-milter 0.103.2 at phobos.denx.de", "X-Virus-Status": "Clean" }, "content": "Expand this to explain subclassing better and also to tidy up formatting\nfor rST.\n\nFix a few pylint warnings to avoid dropping the score.\n\nSigned-off-by: Simon Glass <sjg@chromium.org>\n---\n\n tools/binman/entries.rst | 149 +++++++++++++++++++++++++++-------\n tools/binman/etype/section.py | 148 +++++++++++++++++++++++++++------\n 2 files changed, 242 insertions(+), 55 deletions(-)", "diff": "diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst\nindex dcac700c461..748277c1cde 100644\n--- a/tools/binman/entries.rst\n+++ b/tools/binman/entries.rst\n@@ -799,39 +799,130 @@ This entry holds firmware for an external platform-specific coprocessor.\n Entry: section: Entry that contains other entries\n -------------------------------------------------\n \n-Properties / Entry arguments: (see binman README for more information):\n- pad-byte: Pad byte to use when padding\n- sort-by-offset: True if entries should be sorted by offset, False if\n- they must be in-order in the device tree description\n-\n- end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)\n-\n- skip-at-start: Number of bytes before the first entry starts. These\n- effectively adjust the starting offset of entries. For example,\n- if this is 16, then the first entry would start at 16. An entry\n- with offset = 20 would in fact be written at offset 4 in the image\n- file, since the first 16 bytes are skipped when writing.\n- name-prefix: Adds a prefix to the name of every entry in the section\n- when writing out the map\n- align_default: Default alignment for this section, if no alignment is\n- given in the entry\n-\n-Properties:\n- allow_missing: True if this section permits external blobs to be\n- missing their contents. The second will produce an image but of\n- course it will not work.\n-\n-Properties:\n- _allow_missing: True if this section permits external blobs to be\n- missing their contents. The second will produce an image but of\n- course it will not work.\n+A section is an entry which can contain other entries, thus allowing\n+hierarchical images to be created. See 'Sections and hierarchical images'\n+in the binman README for more information.\n+\n+The base implementation simply joins the various entries together, using\n+various rules about alignment, etc.\n+\n+Subclassing\n+~~~~~~~~~~~\n+\n+This class can be subclassed to support other file formats which hold\n+multiple entries, such as CBFS. To do this, override the following\n+functions. The documentation here describes what your function should do.\n+For example code, see etypes which subclass `Entry_section`, or `cbfs.py`\n+for a more involved example::\n+\n+ $ grep -l \\(Entry_section tools/binman/etype/*.py\n+\n+ReadNode()\n+ Call `super().ReadNode()`, then read any special properties for the\n+ section. Then call `self.ReadEntries()` to read the entries.\n+\n+ Binman calls this at the start when reading the image description.\n+\n+ReadEntries()\n+ Read in the subnodes of the section. This may involve creating entries\n+ of a particular etype automatically, as well as reading any special\n+ properties in the entries. For each entry, entry.ReadNode() should be\n+ called, to read the basic entry properties. The properties should be\n+ added to `self._entries[]`, in the correct order, with a suitable name.\n+\n+ Binman calls this at the start when reading the image description.\n+\n+BuildSectionData(required)\n+ Create the custom file format that you want and return it as bytes.\n+ This likely sets up a file header, then loops through the entries,\n+ adding them to the file. For each entry, call `entry.GetData()` to\n+ obtain the data. If that returns None, and `required` is False, then\n+ this method must give up and return None. But if `required` is True then\n+ it should assume that all data is valid.\n+\n+ Binman calls this when packing the image, to find out the size of\n+ everything. It is called again at the end when building the final image.\n+\n+SetImagePos(image_pos):\n+ Call `super().SetImagePos(image_pos)`, then set the `image_pos` values\n+ for each of the entries. This should use the custom file format to find\n+ the `start offset` (and `image_pos`) of each entry. If the file format\n+ uses compression in such a way that there is no offset available (other\n+ than reading the whole file and decompressing it), then the offsets for\n+ affected entries can remain unset (`None`). The size should also be set\n+ if possible.\n+\n+ Binman calls this after the image has been packed, to update the\n+ location that all the entries ended up at.\n+\n+ReadChildData(child, decomp):\n+ The default version of this may be good enough, if you are able to\n+ implement SetImagePos() correctly. But that is a bit of a bypass, so\n+ you can override this method to read from your custom file format. It\n+ should read the entire entry containing the custom file using\n+ `super().ReadData(True)`, then parse the file to get the data for the\n+ given child, then return that data.\n+\n+ If your file format supports compression, the `decomp` argument tells\n+ you whether to return the compressed data (`decomp` is False) or to\n+ uncompress it first, then return the uncompressed data (`decomp` is\n+ True). This is used by the `binman extract -U` option.\n+\n+ Binman calls this when reading in an image, in order to populate all the\n+ entries with the data from that image (`binman ls`).\n+\n+WriteChildData(child):\n+ Binman calls this after `child.data` is updated, to inform the custom\n+ file format about this, in case it needs to do updates.\n+\n+ The default version of this does nothing and probably needs to be\n+ overridden for the 'binman replace' command to work. Your version should\n+ use `child.data` to update the data for that child in the custom file\n+ format.\n+\n+ Binman calls this when updating an image that has been read in and in\n+ particular to update the data for a particular entry (`binman replace`)\n+\n+Properties / Entry arguments\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+See :ref:`develop/package/binman:Image description format` for more\n+information.\n+\n+align-default\n+ Default alignment for this section, if no alignment is given in the\n+ entry\n+\n+pad-byte\n+ Pad byte to use when padding\n+\n+sort-by-offset\n+ True if entries should be sorted by offset, False if they must be\n+ in-order in the device tree description\n+\n+end-at-4gb\n+ Used to build an x86 ROM which ends at 4GB (2^32)\n+\n+name-prefix\n+ Adds a prefix to the name of every entry in the section when writing out\n+ the map\n+\n+skip-at-start\n+ Number of bytes before the first entry starts. These effectively adjust\n+ the starting offset of entries. For example, if this is 16, then the\n+ first entry would start at 16. An entry with offset = 20 would in fact\n+ be written at offset 4 in the image file, since the first 16 bytes are\n+ skipped when writing.\n \n Since a section is also an entry, it inherits all the properies of entries\n too.\n \n-A section is an entry which can contain other entries, thus allowing\n-hierarchical images to be created. See 'Sections and hierarchical images'\n-in the binman README for more information.\n+Note that the `allow_missing` member controls whether this section permits\n+external blobs to be missing their contents. The option will produce an\n+image but of course it will not work. It is useful to make sure that\n+Continuous Integration systems can build without the binaries being\n+available. This is set by the `SetAllowMissing()` method, if\n+`--allow-missing` is passed to binman.\n \n \n \ndiff --git a/tools/binman/etype/section.py b/tools/binman/etype/section.py\nindex 76e5eb19648..2e01dccc6db 100644\n--- a/tools/binman/etype/section.py\n+++ b/tools/binman/etype/section.py\n@@ -24,34 +24,130 @@ from patman.tools import ToHexSize\n class Entry_section(Entry):\n \"\"\"Entry that contains other entries\n \n- Properties / Entry arguments: (see binman README for more information):\n- pad-byte: Pad byte to use when padding\n- sort-by-offset: True if entries should be sorted by offset, False if\n- they must be in-order in the device tree description\n-\n- end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)\n-\n- skip-at-start: Number of bytes before the first entry starts. These\n- effectively adjust the starting offset of entries. For example,\n- if this is 16, then the first entry would start at 16. An entry\n- with offset = 20 would in fact be written at offset 4 in the image\n- file, since the first 16 bytes are skipped when writing.\n- name-prefix: Adds a prefix to the name of every entry in the section\n- when writing out the map\n- align_default: Default alignment for this section, if no alignment is\n- given in the entry\n-\n- Properties:\n- allow_missing: True if this section permits external blobs to be\n- missing their contents. The second will produce an image but of\n- course it will not work.\n+ A section is an entry which can contain other entries, thus allowing\n+ hierarchical images to be created. See 'Sections and hierarchical images'\n+ in the binman README for more information.\n+\n+ The base implementation simply joins the various entries together, using\n+ various rules about alignment, etc.\n+\n+ Subclassing\n+ ~~~~~~~~~~~\n+\n+ This class can be subclassed to support other file formats which hold\n+ multiple entries, such as CBFS. To do this, override the following\n+ functions. The documentation here describes what your function should do.\n+ For example code, see etypes which subclass `Entry_section`, or `cbfs.py`\n+ for a more involved example::\n+\n+ $ grep -l \\(Entry_section tools/binman/etype/*.py\n+\n+ ReadNode()\n+ Call `super().ReadNode()`, then read any special properties for the\n+ section. Then call `self.ReadEntries()` to read the entries.\n+\n+ Binman calls this at the start when reading the image description.\n+\n+ ReadEntries()\n+ Read in the subnodes of the section. This may involve creating entries\n+ of a particular etype automatically, as well as reading any special\n+ properties in the entries. For each entry, entry.ReadNode() should be\n+ called, to read the basic entry properties. The properties should be\n+ added to `self._entries[]`, in the correct order, with a suitable name.\n+\n+ Binman calls this at the start when reading the image description.\n+\n+ BuildSectionData(required)\n+ Create the custom file format that you want and return it as bytes.\n+ This likely sets up a file header, then loops through the entries,\n+ adding them to the file. For each entry, call `entry.GetData()` to\n+ obtain the data. If that returns None, and `required` is False, then\n+ this method must give up and return None. But if `required` is True then\n+ it should assume that all data is valid.\n+\n+ Binman calls this when packing the image, to find out the size of\n+ everything. It is called again at the end when building the final image.\n+\n+ SetImagePos(image_pos):\n+ Call `super().SetImagePos(image_pos)`, then set the `image_pos` values\n+ for each of the entries. This should use the custom file format to find\n+ the `start offset` (and `image_pos`) of each entry. If the file format\n+ uses compression in such a way that there is no offset available (other\n+ than reading the whole file and decompressing it), then the offsets for\n+ affected entries can remain unset (`None`). The size should also be set\n+ if possible.\n+\n+ Binman calls this after the image has been packed, to update the\n+ location that all the entries ended up at.\n+\n+ ReadChildData(child, decomp):\n+ The default version of this may be good enough, if you are able to\n+ implement SetImagePos() correctly. But that is a bit of a bypass, so\n+ you can override this method to read from your custom file format. It\n+ should read the entire entry containing the custom file using\n+ `super().ReadData(True)`, then parse the file to get the data for the\n+ given child, then return that data.\n+\n+ If your file format supports compression, the `decomp` argument tells\n+ you whether to return the compressed data (`decomp` is False) or to\n+ uncompress it first, then return the uncompressed data (`decomp` is\n+ True). This is used by the `binman extract -U` option.\n+\n+ Binman calls this when reading in an image, in order to populate all the\n+ entries with the data from that image (`binman ls`).\n+\n+ WriteChildData(child):\n+ Binman calls this after `child.data` is updated, to inform the custom\n+ file format about this, in case it needs to do updates.\n+\n+ The default version of this does nothing and probably needs to be\n+ overridden for the 'binman replace' command to work. Your version should\n+ use `child.data` to update the data for that child in the custom file\n+ format.\n+\n+ Binman calls this when updating an image that has been read in and in\n+ particular to update the data for a particular entry (`binman replace`)\n+\n+ Properties / Entry arguments\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+ See :ref:`develop/package/binman:Image description format` for more\n+ information.\n+\n+ align-default\n+ Default alignment for this section, if no alignment is given in the\n+ entry\n+\n+ pad-byte\n+ Pad byte to use when padding\n+\n+ sort-by-offset\n+ True if entries should be sorted by offset, False if they must be\n+ in-order in the device tree description\n+\n+ end-at-4gb\n+ Used to build an x86 ROM which ends at 4GB (2^32)\n+\n+ name-prefix\n+ Adds a prefix to the name of every entry in the section when writing out\n+ the map\n+\n+ skip-at-start\n+ Number of bytes before the first entry starts. These effectively adjust\n+ the starting offset of entries. For example, if this is 16, then the\n+ first entry would start at 16. An entry with offset = 20 would in fact\n+ be written at offset 4 in the image file, since the first 16 bytes are\n+ skipped when writing.\n \n Since a section is also an entry, it inherits all the properies of entries\n too.\n \n- A section is an entry which can contain other entries, thus allowing\n- hierarchical images to be created. See 'Sections and hierarchical images'\n- in the binman README for more information.\n+ Note that the `allow_missing` member controls whether this section permits\n+ external blobs to be missing their contents. The option will produce an\n+ image but of course it will not work. It is useful to make sure that\n+ Continuous Integration systems can build without the binaries being\n+ available. This is set by the `SetAllowMissing()` method, if\n+ `--allow-missing` is passed to binman.\n \"\"\"\n def __init__(self, section, etype, node, test=False):\n if not test:\n@@ -98,9 +194,9 @@ class Entry_section(Entry):\n \"\"\"Raises an error for this section\n \n Args:\n- msg: Error message to use in the raise string\n+ msg (str): Error message to use in the raise string\n Raises:\n- ValueError()\n+ ValueError: always\n \"\"\"\n raise ValueError(\"Section '%s': %s\" % (self._node.path, msg))\n \n", "prefixes": [ "12/17" ] }