From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 3618AC433F5 for ; Mon, 10 Jan 2022 03:21:33 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id A9FB0834E0; Mon, 10 Jan 2022 04:17:02 +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="DxrlOss9"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 3BE278197D; Mon, 10 Jan 2022 04:16:00 +0100 (CET) Received: from mail-io1-xd2c.google.com (mail-io1-xd2c.google.com [IPv6:2607:f8b0:4864:20::d2c]) (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 C7891830F4 for ; Mon, 10 Jan 2022 04:15:31 +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-io1-xd2c.google.com with SMTP id o7so15717249ioo.9 for ; Sun, 09 Jan 2022 19:15:31 -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=Scdhbw8EKdeJDV5JuXEn+pWpKNfIWIKFBbwfU42+MiE=; b=DxrlOss9B2I68UcxegsUyvtlBczscMmLwZynXKTD3LDH9apgKqT77pKhhx17wqdI8B xQ4wJ5AOjUiY2NadOpxBpt9dkwcPc1xgm/AapoBwXlW94ciSnntz3oxw4qwpe8edLL7t 3J91OcBBju+tnAOZAInILYVo+jvmWTeE937kY= 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=Scdhbw8EKdeJDV5JuXEn+pWpKNfIWIKFBbwfU42+MiE=; b=0/0ASuyDIApShSy2VaIiaGuzWVhJQ482OHycbg1v7qRvwmb1QF8IInA5lSVv3l+lHw IcLX+uR6zD6c2cEf2YBr13ujgG0lEYZsXiSTXcqX3TMeFCoFlFby4bpLTlbbvbcL1cAp zm8asiXKPapCO5Rs6c8U0pdw4LwcJCRfNa0ypBRehzKzOBfgJRYFAbPl0ex7Fe5BC93A aAPCA8E9MVQ6gay6IAWTn0rxe0fRqqQxiJvDWXycM2asQeQH0UQkswXJQgmjGiQLr66t WR7SYu3zRrwZE4Dmag9NgyUf9KjzYDAxxJ6bVgoPbSPzBpfrKnxSuXyVeRSEUWjyFiJU uZlQ== X-Gm-Message-State: AOAM530EUc5JDjQ0WfSbVvwFpjbTmUJlxAZH/mJ26gg5qA5EtxQZ7qtV qiE/R5Sgw4eiULMoUIJpXP1RbIqhb1z1+g== X-Google-Smtp-Source: ABdhPJy9B/WUfJbicTZbV0L+KHCvlH5vzimTmZCeFg3XMQ/Rw3eKFWjdjVMWNcKrBRZL41o06wFw+w== X-Received: by 2002:a05:6638:ca1:: with SMTP id x1mr1006379jad.15.1641784530280; Sun, 09 Jan 2022 19:15:30 -0800 (PST) Received: from sjg1.roam.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id d16sm3542182ioy.29.2022.01.09.19.15.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 09 Jan 2022 19:15:29 -0800 (PST) From: Simon Glass To: U-Boot Mailing List Cc: Simon Glass Subject: [PATCH v2 36/38] binman: Add a command to generate bintool docs Date: Sun, 9 Jan 2022 20:14:11 -0700 Message-Id: <20220110031413.1970836-37-sjg@chromium.org> X-Mailer: git-send-email 2.34.1.575.g55b058a8bb-goog In-Reply-To: <20220110031413.1970836-1-sjg@chromium.org> References: <20220110031413.1970836-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 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 Each bintool has some documentation which can be useful for the user. Add a new command that collects this and writes it into a .rst file. Signed-off-by: Simon Glass --- (no changes since v1) tools/binman/bintool.py | 45 +++++++++++++++++++++++++++++++++++++++++ tools/binman/cmdline.py | 3 +++ tools/binman/control.py | 14 ++++++++++++- tools/binman/ftest.py | 15 ++++++++++++++ tools/binman/main.py | 4 ++++ 5 files changed, 80 insertions(+), 1 deletion(-) diff --git a/tools/binman/bintool.py b/tools/binman/bintool.py index 34102dafa2a..e2e5660d167 100644 --- a/tools/binman/bintool.py +++ b/tools/binman/bintool.py @@ -387,6 +387,51 @@ class Bintool: tools.Run(*args) return True + @staticmethod + def WriteDocs(modules, test_missing=None): + """Write out documentation about the various bintools to stdout + + Args: + modules: List of modules to include + test_missing: Used for testing. This is a module to report + as missing + """ + print('''.. SPDX-License-Identifier: GPL-2.0+ + +Binman bintool Documentation +============================ + +This file describes the bintools (binary tools) supported by binman. Bintools +are binman's name for external executables that it runs to generate or process +binaries. It is fairly easy to create new bintools. Just add a new file to the +'btool' directory. You can use existing bintools as examples. + + +''') + modules = sorted(modules) + missing = [] + for name in modules: + module = Bintool.find_bintool_class(name) + docs = getattr(module, '__doc__') + if test_missing == name: + docs = None + if docs: + lines = docs.splitlines() + first_line = lines[0] + rest = [line[4:] for line in lines[1:]] + hdr = 'Bintool: %s: %s' % (name, first_line) + print(hdr) + print('-' * len(hdr)) + print('\n'.join(rest)) + print() + print() + else: + missing.append(name) + + if missing: + raise ValueError('Documentation is missing for modules: %s' % + ', '.join(missing)) + # pylint: disable=W0613 def fetch(self, method): """Fetch handler for a bintool diff --git a/tools/binman/cmdline.py b/tools/binman/cmdline.py index 5ccb2383885..0626b850f48 100644 --- a/tools/binman/cmdline.py +++ b/tools/binman/cmdline.py @@ -129,6 +129,9 @@ controlled by a description in the board device tree.''' build_parser.add_argument('--update-fdt-in-elf', type=str, help='Update an ELF file with the output dtb: infile,outfile,begin_sym,end_sym') + subparsers.add_parser( + 'bintool-docs', help='Write out bintool documentation (see bintool.rst)') + subparsers.add_parser( 'entry-docs', help='Write out entry documentation (see entries.rst)') diff --git a/tools/binman/control.py b/tools/binman/control.py index bbd7773c314..2daad05b804 100644 --- a/tools/binman/control.py +++ b/tools/binman/control.py @@ -140,7 +140,7 @@ def WriteEntryDocs(modules, test_missing=None): Args: modules: List of Module objects to get docs for - test_missing: Used for testing only, to force an entry's documeentation + test_missing: Used for testing only, to force an entry's documentation to show as missing even if it is present. Should be set to None in normal use. """ @@ -148,6 +148,18 @@ def WriteEntryDocs(modules, test_missing=None): Entry.WriteDocs(modules, test_missing) +def write_bintool_docs(modules, test_missing=None): + """Write out documentation for all bintools + + Args: + modules: List of Module objects to get docs for + test_missing: Used for testing only, to force an entry's documentation + to show as missing even if it is present. Should be set to None in + normal use. + """ + bintool.Bintool.WriteDocs(modules, test_missing) + + def ListEntries(image_fname, entry_paths): """List the entries in an image diff --git a/tools/binman/ftest.py b/tools/binman/ftest.py index a3454ddb104..ca200ae9f8f 100644 --- a/tools/binman/ftest.py +++ b/tools/binman/ftest.py @@ -5085,6 +5085,21 @@ fdt fdtmap Extract the devicetree blob from the fdtmap comp_util.decompress(b'1234', 'invalid') self.assertIn("Unknown algorithm 'invalid'", str(e.exception)) + def testBintoolDocs(self): + """Test for creation of bintool documentation""" + with test_util.capture_sys_output() as (stdout, stderr): + control.write_bintool_docs(control.bintool.Bintool.get_tool_list()) + self.assertTrue(len(stdout.getvalue()) > 0) + + def testBintoolDocsMissing(self): + """Test handling of missing bintool documentation""" + with self.assertRaises(ValueError) as e: + with test_util.capture_sys_output() as (stdout, stderr): + control.write_bintool_docs( + control.bintool.Bintool.get_tool_list(), 'mkimage') + self.assertIn('Documentation is missing for modules: mkimage', + str(e.exception)) + if __name__ == "__main__": unittest.main() diff --git a/tools/binman/main.py b/tools/binman/main.py index dcf20290f2b..03462e7bb8b 100755 --- a/tools/binman/main.py +++ b/tools/binman/main.py @@ -35,6 +35,7 @@ sys.pycache_prefix = os.path.relpath(our_path, srctree) # in PYTHONPATH) sys.path.insert(2, our1_path) +from binman import bintool from patman import test_util # Bring in the libfdt module @@ -129,6 +130,9 @@ def RunBinman(args): args.test_preserve_dirs, args.tests, args.toolpath) + elif args.cmd == 'bintool-docs': + control.write_bintool_docs(bintool.Bintool.get_tool_list()) + elif args.cmd == 'entry-docs': control.WriteEntryDocs(control.GetEntryModules()) -- 2.34.1.575.g55b058a8bb-goog