From nobody Sun May 19 03:12:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1554859608; cv=none; d=zoho.com; s=zohoarc; b=KrXVk7kUOFTfBrI21PI8O1Klq0GVJiLJIQT86uCaSNepP3TYypJ7RQnmSeRB0L3qZk1pDoAUl2pFVn3I8hEB3zoMaDG+wEJlFI+ExNbWE0NQNRPUlA20P8aLDAZjPiTprFAqdonhePe2FW9X16FZd1TBE9fJSDG+5m1HtIW9HzE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1554859608; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=EKyOqv9RnWSfyeCvEFiuypxyo9a00caJcett1O/Aq1Y=; b=oTVd0YTXJArShgTwt2MZVQ6es0l/x0LABk6R6YKwiVsjMCIYIbnGXsPOECBlSIo2gj4fEx/itJnxAP/BEOxlj+lp8gqfTZDGHei7fSCqm1C+G1wBGdNJUHAQYekn3AjaNebmDq6QLE5UzYRk2/gUcH90Gn9DQ88E3gTuuC0KvWo= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1554859608169943.7924555094097; Tue, 9 Apr 2019 18:26:48 -0700 (PDT) Received: from localhost ([127.0.0.1]:51661 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE20d-0000Mv-VH for importer@patchew.org; Tue, 09 Apr 2019 21:26:39 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43301) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE1yR-0007QV-Kl for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:24 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hE1yQ-00020a-HP for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:23 -0400 Received: from mx1.redhat.com ([209.132.183.28]:46548) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hE1yN-0001l2-1c; Tue, 09 Apr 2019 21:24:19 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 634CFE3DEC; Wed, 10 Apr 2019 01:24:18 +0000 (UTC) Received: from probe.bos.redhat.com (dhcp-17-206.bos.redhat.com [10.18.17.206]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6F1781084201; Wed, 10 Apr 2019 01:24:17 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org, qemu-block@nongnu.org Date: Tue, 9 Apr 2019 21:24:11 -0400 Message-Id: <20190410012413.31569-2-jsnow@redhat.com> In-Reply-To: <20190410012413.31569-1-jsnow@redhat.com> References: <20190410012413.31569-1-jsnow@redhat.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.38]); Wed, 10 Apr 2019 01:24:18 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH RFC 1/3] qemu-img: fix .hx and .texi disparity X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , Eduardo Habkost , John Snow , armbru@redhat.com, Max Reitz , Cleber Rosa Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid. There are three locations: (1) .hx file, formatted as texi (2) .hx file, formatted as human readable. (3) .texi file, as section headers, formatted as texi. You can compare the two summaries within the .hx file like so: Human-readable command summaries: `./qemu-img --help | grep 'Command syntax' -A14` Detokenized texi command summaries: `grep "@item" qemu-img-cmds.hx | sed -E 's|@var\{([^\}]*?)\}|\1|g'` You can compare the two separate texi summaries like so: Texi command summaries: `grep "@item" qemu-img-cmds.hx"` Texi command headers: grep -E "@item.*@var" qemu-img.texi | tail -14 Signed-off-by: John Snow --- qemu-img.texi | 4 ++-- qemu-img-cmds.hx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/qemu-img.texi b/qemu-img.texi index 3b6710a580..724f244ba1 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -197,7 +197,7 @@ Command description: =20 @table @option =20 -@item amend [--object @var{objectdef}] [--image-opts] [-p] [-p] [-f @var{f= mt}] [-t @var{cache}] -o @var{options} @var{filename} +@item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{f= mt}] [-t @var{cache}] -o @var{options} @var{filename} =20 Amends the image format specific @var{options} for the image file @var{filename}. Not all file formats support this operation. @@ -424,7 +424,7 @@ To enumerate information about each disk image in the a= bove chain, starting from qemu-img info --backing-chain snap2.qcow2 @end example =20 -@item map [-f @var{fmt}] [--output=3D@var{ofmt}] @var{filename} +@item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--outp= ut=3D@var{ofmt}] [-U] @var{filename} =20 Dump the metadata of image @var{filename} and its backing file chain. In particular, this commands dumps the allocation state of every sector diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx index 1526f327a5..4b47f7495d 100644 --- a/qemu-img-cmds.hx +++ b/qemu-img-cmds.hx @@ -46,7 +46,7 @@ ETEXI DEF("convert", img_convert, "convert [--object objectdef] [--image-opts] [--target-image-opts] [-U= ] [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fm= t] [-B backing_file] [-o options] [-l snapshot_param] [-S sparse_size] [-m = num_coroutines] [-W] filename [filename2 [...]] output_filename") STEXI -@item convert [--object @var{objectdef}] [--image-opts] [--target-image-op= ts] [-U] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_c= ache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-l= @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W= ] @var{filename} [@var{filename2} [...]] @var{output_filename} +@item convert [--object @var{objectdef}] [--image-opts] [--target-image-op= ts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{= src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}= ] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}= ] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename} ETEXI =20 DEF("create", img_create, --=20 2.17.2 From nobody Sun May 19 03:12:51 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1554859678; cv=none; d=zoho.com; s=zohoarc; b=CiMOEulJOgQvMX8lhXAfRRCKhPDMvcME8wxq7UrsCRDY670VhlMHNMAINjW8K1LS2caV+JoJ+FypAadU9cXuhibZbi7vTdFmUC+In8nbRbdKPlhm9Z3FdcEp6BOhdfdo52KAUuW+1aHVoY8Wncqa7ByFC1FIWV9QQD5Wa3AkMMg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1554859678; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=Gs/Fj1QH/BECqbgGYxx8lJFhQNz4AfKP7u4tCxWhYjE=; b=mlEGPob3R5+8XTrkoATo6oG7Bct6vXg1DiFL+kA5b3KavsFdErNLL/BjpvfX16aNygWeGYlOyffVkcEGEMCDidASjWqVQ/HHMvEEewscEL/j1rkPWLMYccpaqfDU566h/1LUkT5JrNCDH27ZLdqUH7tGsRKIMmeQdCGxCDct3Q4= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1554859678385289.6454890839585; Tue, 9 Apr 2019 18:27:58 -0700 (PDT) Received: from localhost ([127.0.0.1]:51669 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE21r-0000xp-D7 for importer@patchew.org; Tue, 09 Apr 2019 21:27:55 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43348) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE1yY-0007Wd-9T for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hE1yT-0002Cm-3D for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:28 -0400 Received: from mx1.redhat.com ([209.132.183.28]:55338) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hE1yO-0001pH-9F; Tue, 09 Apr 2019 21:24:20 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 8720181104; Wed, 10 Apr 2019 01:24:19 +0000 (UTC) Received: from probe.bos.redhat.com (dhcp-17-206.bos.redhat.com [10.18.17.206]) by smtp.corp.redhat.com (Postfix) with ESMTP id 813AA1001E92; Wed, 10 Apr 2019 01:24:18 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org, qemu-block@nongnu.org Date: Tue, 9 Apr 2019 21:24:12 -0400 Message-Id: <20190410012413.31569-3-jsnow@redhat.com> In-Reply-To: <20190410012413.31569-1-jsnow@redhat.com> References: <20190410012413.31569-1-jsnow@redhat.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.28]); Wed, 10 Apr 2019 01:24:19 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH RFC 2/3] pxtool: Add new qemu-img command info generation tool X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , Eduardo Habkost , John Snow , armbru@redhat.com, Max Reitz , Cleber Rosa Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Presently we use hxtool and a .hx format to generate a few things like the qemu_img subcommand dispatch table, the qemu_img help() display output, and a help output in qemu-img.texi. Unfortunately, this means that this information is duplicated in at least three places: (1) in qemu-img-cmds.hx as a human readable string (2) in qemu-img-cmds.hx as a texi string (3) in qemu-img.texi again, as a texi string We can do a little better, though: all of these sources can be generated from a single json file. Add a new small tool ("pxtool") that can do this. This tool can at least handle generating (1) and (2) from the same source without needing to reduplicate that information. Deduplicating (3) happens in the next patch. Notes: - The json format was chosen to be very "stupid", and the command line documentation is being kept one-per-line to make future diffs easier to read. - It's easy enough to generate the human-readable output from the texi output by removing '@var{foo}' with 'foo'. - The qemu-img command dispatch always calls img_cmdname, so we don't need to store this information separately, either. - The need for DEF() macros could be removed as well, but I left it in to create a minimally disruptive patch. Signed-off-by: John Snow --- Makefile | 8 +-- qemu-img-cmds.json | 165 +++++++++++++++++++++++++++++++++++++++++++++ qemu-img-cmds.hx | 102 ---------------------------- scripts/pxtool.py | 49 ++++++++++++++ 4 files changed, 218 insertions(+), 106 deletions(-) create mode 100644 qemu-img-cmds.json delete mode 100644 qemu-img-cmds.hx create mode 100755 scripts/pxtool.py diff --git a/Makefile b/Makefile index 04a0d45050..d203bb90dc 100644 --- a/Makefile +++ b/Makefile @@ -524,8 +524,8 @@ ifdef CONFIG_MPATH scsi/qemu-pr-helper$(EXESUF): LIBS +=3D -ludev -lmultipath -lmpathpersist endif =20 -qemu-img-cmds.h: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool - $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@,"GEN","$@= ") +qemu-img-cmds.h: $(SRC_PATH)/qemu-img-cmds.json $(SRC_PATH)/scripts/pxtool= .py + $(call quiet-command,$(PYTOHN) $(SRC_PATH)/scripts/pxtool.py --macros $< = > $@,"GEN","$@") =20 qemu-ga$(EXESUF): LIBS =3D $(LIBS_QGA) qemu-ga$(EXESUF): QEMU_CFLAGS +=3D -I qga/qapi-generated @@ -918,8 +918,8 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PA= TH)/scripts/hxtool qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scrip= ts/hxtool $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@= ") =20 -qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool - $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@= ") +qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.json $(SRC_PATH)/scripts/pxt= ool.py + $(call quiet-command,$(PYTON) $(SRC_PATH)/scripts/pxtool.py --texi $< > $= @,"GEN","$@") =20 docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ diff --git a/qemu-img-cmds.json b/qemu-img-cmds.json new file mode 100644 index 0000000000..35d96f92a3 --- /dev/null +++ b/qemu-img-cmds.json @@ -0,0 +1,165 @@ +{ + "amend": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-p]", + "[-q]", + "[-f @var{fmt}]", + "[-t @var{cache}]", + "-o @var{options}", + "@var{filename}" + ], + "bench": [ + "[-c @var{count}]", + "[-d @var{depth}]", + "[-f @var{fmt}]", + "[--flush-interval=3D@var{flush_interval}]", + "[-n]", + "[--no-drain]", + "[-o @var{offset}]", + "[--pattern=3D@var{pattern}]", + "[-q]", + "[-s @var{buffer_size}]", + "[-S @var{step_size}]", + "[-t @var{cache}]", + "[-w]", + "[-U]", + "@var{filename}" + ], + "check": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-q]", + "[-f @var{fmt}]", + "[--output=3D@var{ofmt}]", + "[-r [leaks | all]]", + "[-T @var{src_cache}]", + "[-U]", + "@var{filename}" + ], + "commit": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-q]", + "[-f @var{fmt}]", + "[-t @var{cache}]", + "[-b @var{base}]", + "[-d]", + "[-p]", + "@var{filename}" + ], + "compare": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-f @var{fmt}]", + "[-F @var{fmt}]", + "[-T @var{src_cache}]", + "[-p]", + "[-q]", + "[-s]", + "[-U]", + "@var{filename1}", + "@var{filename2}" + ], + "convert": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[--target-image-opts]", + "[-U]", + "[-C]", + "[-c]", + "[-p]", + "[-q]", + "[-n]", + "[-f @var{fmt}]", + "[-t @var{cache}]", + "[-T @var{src_cache}]", + "[-O @var{output_fmt}]", + "[-B @var{backing_file}]", + "[-o @var{options}]", + "[-l @var{snapshot_param}]", + "[-S @var{sparse_size}]", + "[-m @var{num_coroutines}]", + "[-W]", + "@var{filename}", + "[@var{filename2} [...]]", + "@var{output_filename}" + ], + "create": [ + "[--object @var{objectdef}]", + "[-q]", + "[-f @var{fmt}]", + "[-b @var{backing_file}]", + "[-F @var{backing_fmt}]", + "[-u]", + "[-o @var{options}]", + "@var{filename}", + "[@var{size}]" + ], + "dd": [ + "[--image-opts]", + "[-U]", + "[-f @var{fmt}]", + "[-O @var{output_fmt}]", + "[bs=3D@var{block_size}]", + "[count=3D@var{blocks}]", + "[skip=3D@var{blocks}]", + "if=3D@var{input}", + "of=3D@var{output}" + ], + "info": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-f @var{fmt}]", + "[--output=3D@var{ofmt}]", + "[--backing-chain]", + "[-U]", + "@var{filename}" + ], + "map": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-f @var{fmt}]", + "[--output=3D@var{ofmt}]", + "[-U]", + "@var{filename}" + ], + "measure": [ + "[--output=3D@var{ofmt}]", + "[-O @var{output_fmt}]", + "[-o @var{options}]", + "[--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @= var{fmt}] [-l @var{snapshot_param}] @var{filename}]" + ], + "snapshot": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-U]", + "[-q]", + "[-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}]", + "@var{filename}" + ], + "rebase": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-U]", + "[-q]", + "[-f @var{fmt}]", + "[-t @var{cache}]", + "[-T @var{src_cache}]", + "[-p]", + "[-u]", + "-b @var{backing_file}", + "[-F @var{backing_fmt}]", + "@var{filename}" + ], + "resize": [ + "[--object @var{objectdef}]", + "[--image-opts]", + "[-f @var{fmt}]", + "[--preallocation=3D@var{prealloc}]", + "[-q]", + "[--shrink]", + "@var{filename}", + "[+ | -]@var{size}" + ] +} diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx deleted file mode 100644 index 4b47f7495d..0000000000 --- a/qemu-img-cmds.hx +++ /dev/null @@ -1,102 +0,0 @@ -HXCOMM Keep the list of subcommands sorted by name. -HXCOMM Use DEFHEADING() to define headings in both help text and texi -HXCOMM Text between STEXI and ETEXI are copied to texi version and -HXCOMM discarded from C version -HXCOMM DEF(command, callback, arg_string) is used to construct -HXCOMM command structures and help message. -HXCOMM HXCOMM can be used for comments, discarded from both texi and C - -HXCOMM When amending the TEXI sections, please remember to copy the usage -HXCOMM over to the per-command sections in qemu-img.texi. - -STEXI -@table @option -ETEXI - -DEF("amend", img_amend, - "amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cach= e] -o options filename") -STEXI -@item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{f= mt}] [-t @var{cache}] -o @var{options} @var{filename} -ETEXI - -DEF("bench", img_bench, - "bench [-c count] [-d depth] [-f fmt] [--flush-interval=3Dflush_interv= al] [-n] [--no-drain] [-o offset] [--pattern=3Dpattern] [-q] [-s buffer_siz= e] [-S step_size] [-t cache] [-w] [-U] filename") -STEXI -@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-inte= rval=3D@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern= =3D@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var= {cache}] [-w] [-U] @var{filename} -ETEXI - -DEF("check", img_check, - "check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=3Do= fmt] [-r [leaks | all]] [-T src_cache] [-U] filename") -STEXI -@item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] = [--output=3D@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{f= ilename} -ETEXI - -DEF("commit", img_commit, - "commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [= -b base] [-d] [-p] filename") -STEXI -@item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}]= [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename} -ETEXI - -DEF("compare", img_compare, - "compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T src= _cache] [-p] [-q] [-s] [-U] filename1 filename2") -STEXI -@item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F= @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{f= ilename2} -ETEXI - -DEF("convert", img_convert, - "convert [--object objectdef] [--image-opts] [--target-image-opts] [-U= ] [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fm= t] [-B backing_file] [-o options] [-l snapshot_param] [-S sparse_size] [-m = num_coroutines] [-W] filename [filename2 [...]] output_filename") -STEXI -@item convert [--object @var{objectdef}] [--image-opts] [--target-image-op= ts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{= src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}= ] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}= ] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename} -ETEXI - -DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backi= ng_fmt] [-u] [-o options] filename [size]") -STEXI -@item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backi= ng_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@v= ar{size}] -ETEXI - -DEF("dd", img_dd, - "dd [--image-opts] [-U] [-f fmt] [-O output_fmt] [bs=3Dblock_size] [co= unt=3Dblocks] [skip=3Dblocks] if=3Dinput of=3Doutput") -STEXI -@item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=3D@v= ar{block_size}] [count=3D@var{blocks}] [skip=3D@var{blocks}] if=3D@var{inpu= t} of=3D@var{output} -ETEXI - -DEF("info", img_info, - "info [--object objectdef] [--image-opts] [-f fmt] [--output=3Dofmt] [= --backing-chain] [-U] filename") -STEXI -@item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--out= put=3D@var{ofmt}] [--backing-chain] [-U] @var{filename} -ETEXI - -DEF("map", img_map, - "map [--object objectdef] [--image-opts] [-f fmt] [--output=3Dofmt] [-= U] filename") -STEXI -@item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--outp= ut=3D@var{ofmt}] [-U] @var{filename} -ETEXI - -DEF("measure", img_measure, -"measure [--output=3Dofmt] [-O output_fmt] [-o options] [--size N | [--obj= ect objectdef] [--image-opts] [-f fmt] [-l snapshot_param] filename]") -STEXI -@item measure [--output=3D@var{ofmt}] [-O @var{output_fmt}] [-o @var{optio= ns}] [--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @var{f= mt}] [-l @var{snapshot_param}] @var{filename}] -ETEXI - -DEF("snapshot", img_snapshot, - "snapshot [--object objectdef] [--image-opts] [-U] [-q] [-l | -a snaps= hot | -c snapshot | -d snapshot] filename") -STEXI -@item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -= a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename} -ETEXI - -DEF("rebase", img_rebase, - "rebase [--object objectdef] [--image-opts] [-U] [-q] [-f fmt] [-t cac= he] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt] filename") -STEXI -@item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-f @var{= fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file}= [-F @var{backing_fmt}] @var{filename} -ETEXI - -DEF("resize", img_resize, - "resize [--object objectdef] [--image-opts] [-f fmt] [--preallocation= =3Dprealloc] [-q] [--shrink] filename [+ | -]size") -STEXI -@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--p= reallocation=3D@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{s= ize} -ETEXI - -STEXI -@end table -ETEXI diff --git a/scripts/pxtool.py b/scripts/pxtool.py new file mode 100755 index 0000000000..008fea839e --- /dev/null +++ b/scripts/pxtool.py @@ -0,0 +1,49 @@ +#!/usr/bin/env python + +import argparse +from collections import OrderedDict +import json +import re + +# Helpers: +def scrub_texi_string(tstring): + return re.sub(r"@var{([^{}]*?)}", r"\1", tstring) + +def human_readable_usage(usage_list): + return scrub_texi_string(" ".join(usage_list)) + +def callback_name(command): + return "img_{:s}".format(command) + +# Output modes: +def generate_def_header(conf): + """Print DEF() macros to be used by qemu-img.c""" + for command, usage_strs in conf.items(): + print("DEF(\"{}\", {}, \"{} {}\")".format( + command, + callback_name(command), + command, + human_readable_usage(usage_strs))) + +def generate_texi(conf): + """Generate texi command summary table""" + print("@table @option") + for command, usage_strs in conf.items(): + usage =3D " ".join(usage_strs) + print("@item {} {}".format(command, usage)) + print("@end table") + +if __name__ =3D=3D '__main__': + parser =3D argparse.ArgumentParser(description=3D"Generate qemu-img co= mmand information") + parser.add_argument("--macros", action=3D"store_true", dest=3D"macros") + parser.add_argument("--texi", action=3D"store_true") + parser.add_argument("commands_json") + args =3D parser.parse_args() + + with open(args.commands_json, "r") as f: + conf =3D json.load(f, object_pairs_hook=3DOrderedDict) + + if args.macros: + generate_def_header(conf) + if args.texi: + generate_texi(conf) --=20 2.17.2 From nobody Sun May 19 03:12:51 2024 Delivered-To: importer@patchew.org Received-SPF: temperror (zoho.com: Error in retrieving data from DNS) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=temperror (zoho.com: Error in retrieving data from DNS) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1554859764; cv=none; d=zoho.com; s=zohoarc; b=fV9QVa5fCBAiYvFOMHFavHd+DM3e76sPFbGBS2ZDWc+Ptw/6aMsE5Nv3NqQaUzAs0gAsZQykxznH5fgQ0uA08XbR7pk6JdDKO/6mQq8mO2PO0ObZnlkNy47Tc+7/Nqlj3dVXF/hX9fnO0c7RiiO4YRfpnuECYq6JscGF4fRdhCE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1554859764; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=6gzHb0LZpo+X1Niq3HMj5KKebl1qR1mGzHEd8fw1hTU=; b=GKayvXYLXQlgS0EJUQSJDpGTrLfkYmF6vk68utjSa7oFP979IM+DnzUyphvfGyWpOprwK/WdQSHXZw0lHZQKtkRQoUHepdP1Z9gFfnaB75NQdiaXpoOvNQ5Gtvaav+Q6Rcs0fmYZt3gN70CWjlJgmiJ/BGhhG5/w+aDC8fO05n0= ARC-Authentication-Results: i=1; mx.zoho.com; spf=temperror (zoho.com: Error in retrieving data from DNS) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1554859764646767.6818661776207; Tue, 9 Apr 2019 18:29:24 -0700 (PDT) Received: from localhost ([127.0.0.1]:51677 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE236-0001bF-C9 for importer@patchew.org; Tue, 09 Apr 2019 21:29:12 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43374) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE1yf-0007bG-LC for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hE1yd-0002gh-N8 for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:37 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37894) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hE1yP-0001sd-9E; Tue, 09 Apr 2019 21:24:21 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 9A10481235; Wed, 10 Apr 2019 01:24:20 +0000 (UTC) Received: from probe.bos.redhat.com (dhcp-17-206.bos.redhat.com [10.18.17.206]) by smtp.corp.redhat.com (Postfix) with ESMTP id A97061001E92; Wed, 10 Apr 2019 01:24:19 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org, qemu-block@nongnu.org Date: Tue, 9 Apr 2019 21:24:13 -0400 Message-Id: <20190410012413.31569-4-jsnow@redhat.com> In-Reply-To: <20190410012413.31569-1-jsnow@redhat.com> References: <20190410012413.31569-1-jsnow@redhat.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Wed, 10 Apr 2019 01:24:20 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH RFC 3/3] qemu-img.texi: use macros for command summaries X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , Eduardo Habkost , John Snow , armbru@redhat.com, Max Reitz , Cleber Rosa Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Use a macro to recall this text instead of re-entering it manually. Modify the pxtool script to create macros for each subcommand, then alter the qemu-img.texi file to recall these macros. Signed-off-by: John Snow --- qemu-img.texi | 28 ++++++++++++++-------------- scripts/pxtool.py | 4 ++++ 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/qemu-img.texi b/qemu-img.texi index 724f244ba1..c21a97e934 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -197,12 +197,12 @@ Command description: =20 @table @option =20 -@item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{f= mt}] [-t @var{cache}] -o @var{options} @var{filename} +@qemuimgcmdamend =20 Amends the image format specific @var{options} for the image file @var{filename}. Not all file formats support this operation. =20 -@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-inte= rval=3D@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern= =3D@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var= {cache}] [-w] [-U] @var{filename} +@qemuimgcmdbench =20 Run a simple sequential I/O benchmark on the specified image. If @code{-w}= is specified, a write test is performed, otherwise a read test is performed. @@ -226,7 +226,7 @@ specified as well. For write tests, by default a buffer filled with zeros is written. This ca= n be overridden with a pattern byte specified by @var{pattern}. =20 -@item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] = [--output=3D@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{f= ilename} +@qemuimgcmdcheck =20 Perform a consistency check on the disk image @var{filename}. The command = can output in the format @var{ofmt} which is either @code{human} or @code{json= }. @@ -262,7 +262,7 @@ If @code{-r} is specified, exit codes representing the = image state refer to the state after (the attempt at) repairing it. That is, a successful @code{-r = all} will yield the exit code 0, independently of the image state before. =20 -@item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}]= [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename} +@qemuimgcmdcommit =20 Commit the changes recorded in @var{filename} in its base image or backing= file. If the backing file is smaller than the snapshot, then the backing file wi= ll be @@ -284,7 +284,7 @@ all images between @var{base} and the top image will be= invalid and may return garbage data when read. For this reason, @code{-b} implies @code{-d} (so t= hat the top image stays valid). =20 -@item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F= @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{f= ilename2} +@qemuimgcmdcompare =20 Check if two images have the same content. You can compare images with different format or settings. @@ -325,7 +325,7 @@ Error on reading data =20 @end table =20 -@item convert [--object @var{objectdef}] [--image-opts] [--target-image-op= ts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{= src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}= ] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}= ] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename} +@qemuimgcmdconvert =20 Convert the disk image @var{filename} or a snapshot @var{snapshot_param} to disk image @var{output_filename} using format @var{output_fmt}. It can = be optionally compressed (@code{-c} @@ -366,7 +366,7 @@ creating compressed images. @var{num_coroutines} specifies how many coroutines work in parallel during the convert process (defaults to 8). =20 -@item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backi= ng_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@v= ar{size}] +@qemuimgcmdcreate =20 Create the new disk image @var{filename} of size @var{size} and format @var{fmt}. Depending on the file format, you can add one or more @var{opti= ons} @@ -390,7 +390,7 @@ way. The size can also be specified using the @var{size} option with @code{-o}, it doesn't need to be specified separately in this case. =20 -@item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=3D@v= ar{block_size}] [count=3D@var{blocks}] [skip=3D@var{blocks}] if=3D@var{inpu= t} of=3D@var{output} +@qemuimgcmddd =20 Dd copies from @var{input} file to @var{output} file converting it from @var{fmt} format to @var{output_fmt} format. @@ -401,7 +401,7 @@ dd will stop reading input after reading @var{blocks} i= nput blocks. =20 The size syntax is similar to dd(1)'s size syntax. =20 -@item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--out= put=3D@var{ofmt}] [--backing-chain] [-U] @var{filename} +@qemuimgcmdinfo =20 Give information about the disk image @var{filename}. Use it in particular to know the size reserved on disk which can be different @@ -424,7 +424,7 @@ To enumerate information about each disk image in the a= bove chain, starting from qemu-img info --backing-chain snap2.qcow2 @end example =20 -@item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--outp= ut=3D@var{ofmt}] [-U] @var{filename} +@qemuimgcmdmap =20 Dump the metadata of image @var{filename} and its backing file chain. In particular, this commands dumps the allocation state of every sector @@ -479,7 +479,7 @@ preallocated. For more information, consult @file{include/block/block.h} in QEMU's source code. =20 -@item measure [--output=3D@var{ofmt}] [-O @var{output_fmt}] [-o @var{optio= ns}] [--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @var{f= mt}] [-l @var{snapshot_param}] @var{filename}] +@qemuimgcmdmeasure =20 Calculate the file size required for a new image. This information can be= used to size logical volumes or SAN LUNs appropriately for the image that will = be @@ -509,11 +509,11 @@ been written to all sectors. This is the maximum siz= e that the image file can occupy with the exception of internal snapshots, dirty bitmaps, vmstate da= ta, and other advanced image format features. =20 -@item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -= a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename} +@qemuimgcmdsnapshot =20 List, apply, create or delete snapshots in image @var{filename}. =20 -@item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-f @var{= fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file}= [-F @var{backing_fmt}] @var{filename} +@qemuimgcmdrebase =20 Changes the backing file of an image. Only the formats @code{qcow2} and @code{qed} support changing the backing file. @@ -573,7 +573,7 @@ qemu-img rebase -b base.img diff.qcow2 At this point, @code{modified.img} can be discarded, since @code{base.img + diff.qcow2} contains the same information. =20 -@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--p= reallocation=3D@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{s= ize} +@qemuimgcmdresize =20 Change the disk image as if it had been created with @var{size}. =20 diff --git a/scripts/pxtool.py b/scripts/pxtool.py index 008fea839e..7ed5550b29 100755 --- a/scripts/pxtool.py +++ b/scripts/pxtool.py @@ -30,7 +30,11 @@ def generate_texi(conf): print("@table @option") for command, usage_strs in conf.items(): usage =3D " ".join(usage_strs) + macro =3D "qemuimgcmd{}".format(command) + print("@macro {}".format(macro)) print("@item {} {}".format(command, usage)) + print("@end macro") + print("@{}".format(macro)) print("@end table") =20 if __name__ =3D=3D '__main__': --=20 2.17.2