Message ID | 20231027110117.70995-1-bruce.richardson@intel.com (mailing list archive) |
---|---|
Headers |
Return-Path: <dev-bounces@dpdk.org> X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id ACDF443215; Fri, 27 Oct 2023 13:01:25 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7EBA240263; Fri, 27 Oct 2023 13:01:25 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.8]) by mails.dpdk.org (Postfix) with ESMTP id 8FDD44025E for <dev@dpdk.org>; Fri, 27 Oct 2023 13:01:24 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1698404485; x=1729940485; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=JQVB2/AuY79PxOa+Ln6OBcZ8bliB1rri7heZoxIGr/8=; b=lHxpRL5TjAiI80jcLpHDceOTxw27N4QEwRqgfCppRMrp5mzHqOVHQ2Ta nMw/A1KuIjY1CzFGMeZ1p99VRpllJ2tHiVI15nRF9IRuppQmbBUpe9IHY ZZlvbKmo4XoWgJMS1bK65DIis4Oa0nGb+bnjej484NJDTBhpgROBuE6NU 4Vt0cOQAXDoNp6mdTH0GmMgDLfEro9MG0Tqfyg1U1vpG2lP+FhochUN3I zME83abq4zMbYioWQpxyEzELoZl20GDDWq8WVQ3Apc1WkPDKYv6d/cO0Z C9zF9yduP4NB2SEALwvU/zo2Kuz8viK4nie+ynAP8GISnhHV3/aLBqOPs Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10875"; a="546631" X-IronPort-AV: E=Sophos;i="6.03,256,1694761200"; d="scan'208";a="546631" Received: from orsmga004.jf.intel.com ([10.7.209.38]) by fmvoesa102.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2023 04:01:24 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10875"; a="883157793" X-IronPort-AV: E=Sophos;i="6.03,256,1694761200"; d="scan'208";a="883157793" Received: from silpixa00401385.ir.intel.com ([10.237.214.154]) by orsmga004.jf.intel.com with ESMTP; 27 Oct 2023 04:01:21 -0700 From: Bruce Richardson <bruce.richardson@intel.com> To: dev@dpdk.org Cc: david.marchand@redhat.com, rjarry@redhat.com, Bruce Richardson <bruce.richardson@intel.com> Subject: [PATCH v7 0/9] document and simplify use of cmdline Date: Fri, 27 Oct 2023 12:01:08 +0100 Message-Id: <20231027110117.70995-1-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230802170052.955323-1-bruce.richardson@intel.com> References: <20230802170052.955323-1-bruce.richardson@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions <dev.dpdk.org> List-Unsubscribe: <https://mails.dpdk.org/options/dev>, <mailto:dev-request@dpdk.org?subject=unsubscribe> List-Archive: <http://mails.dpdk.org/archives/dev/> List-Post: <mailto:dev@dpdk.org> List-Help: <mailto:dev-request@dpdk.org?subject=help> List-Subscribe: <https://mails.dpdk.org/listinfo/dev>, <mailto:dev-request@dpdk.org?subject=subscribe> Errors-To: dev-bounces@dpdk.org |
Series |
document and simplify use of cmdline
|
|
Message
Bruce Richardson
Oct. 27, 2023, 11:01 a.m. UTC
The DPDK commandline library is widely used by apps and examples within DPDK, but it is not documented in our programmers guide and it requires a lot of boilerplate code definitions in order to used. We can improve this situation by creating a simple python script to automatically generate the boilerplate from a list of commands. This patchset contains a new documentation chapter on cmdline library, going through step-by-step how to add commands and create the necessary token lists and parse contexts. Following that initial doc patch, the set then contains a boilerplate-generating script, as well as a set of four patches showing its use, by converting four examples to use the script instead of having the hard-coded boilerplate. Once the script is used, adding a new command becomes as simple as adding the desired command to the .list file, and then writing the required function which will be called for that command. No other boilerplate coding is necessary. Final two patches, from V5 onwards, add support for option-lists in values, and then use that support to convert over a fifth sample app - ntb. Cmdline script obviously does not cover the full range of capabilities of the commandline lib, but does cover the most used parts. The code-saving to each of the examples by auto-generating the boilerplate is significant, and probably more examples with commandlines can be converted over in future. The "cmdline" example itself, is not converted over, as it should probably remain as a simple example of direct library use without the script. v7: * Increased use of multi-line strings in python script, following feedback. v6: * rework syntax of the option lists following feedback from David. Now use "(x,y,z)" instead of "|x|y|z|", to avoid giving impression of regex support V5: * Added copyright headers to command list files * Add support for option lists * Convert examples/ntb to use script V4: * Reworked script following feedback from Robin J. - formatted code with black - used multi-line strings - replaced sys.exit(1) with proper error handling - per-command function returns lists rather than printing directly - other small cleanups * Added change to CI script so the cmdline script is in PATH * Converted VDPA example to script, saving another 100 LOC V3: * Added lots of documentation * Added support for help text for each command * Cleaned up script a little so it passes pycodestyle and most flake8 checks, when line-length is set to max 100. * Removed RFC tag, as I consider this patchset stable enough for consideration in a release. V2-RFC: * Add support for IP addresses in commands * Move to buildtools directory and make installable * Convert 3 examples to use script, and eliminate their boilerplate Bruce Richardson (9): doc/prog_guide: new chapter on cmdline library buildtools: script to generate cmdline boilerplate ci: allow use of DPDK tools when building examples examples/simple_mp: auto-generate cmdline boilerplate examples/hotplug_mp: auto-generate cmdline boilerplate examples/bond: auto-generate cmdline boilerplate examples/vdpa: auto-generate cmdline boilerplate buildtools/dpdk-cmdline-gen: support option strings examples/ntb: auto-generate cmdline boilerplate .ci/linux-build.sh | 1 + app/test/commands.c | 2 + buildtools/dpdk-cmdline-gen.py | 202 ++++++++ buildtools/meson.build | 7 + doc/guides/prog_guide/cmdline.rst | 473 ++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + examples/bond/Makefile | 12 +- examples/bond/commands.list | 6 + examples/bond/main.c | 161 +----- examples/bond/main.h | 10 - examples/bond/meson.build | 8 + examples/multi_process/hotplug_mp/Makefile | 12 +- examples/multi_process/hotplug_mp/commands.c | 147 +----- examples/multi_process/hotplug_mp/commands.h | 10 - .../multi_process/hotplug_mp/commands.list | 8 + examples/multi_process/hotplug_mp/meson.build | 9 + examples/multi_process/simple_mp/Makefile | 12 +- examples/multi_process/simple_mp/meson.build | 9 + .../multi_process/simple_mp/mp_commands.c | 106 +--- .../multi_process/simple_mp/mp_commands.h | 14 - .../multi_process/simple_mp/mp_commands.list | 6 + examples/ntb/Makefile | 12 +- examples/ntb/commands.list | 11 + examples/ntb/meson.build | 7 + examples/ntb/ntb_fwd.c | 200 +------- examples/vdpa/Makefile | 12 +- examples/vdpa/commands.list | 8 + examples/vdpa/main.c | 131 +---- examples/vdpa/meson.build | 7 + 29 files changed, 871 insertions(+), 733 deletions(-) create mode 100755 buildtools/dpdk-cmdline-gen.py create mode 100644 doc/guides/prog_guide/cmdline.rst create mode 100644 examples/bond/commands.list delete mode 100644 examples/bond/main.h delete mode 100644 examples/multi_process/hotplug_mp/commands.h create mode 100644 examples/multi_process/hotplug_mp/commands.list delete mode 100644 examples/multi_process/simple_mp/mp_commands.h create mode 100644 examples/multi_process/simple_mp/mp_commands.list create mode 100644 examples/ntb/commands.list create mode 100644 examples/vdpa/commands.list -- 2.39.2
Comments
On Fri, Oct 27, 2023 at 1:01 PM Bruce Richardson <bruce.richardson@intel.com> wrote: > > The DPDK commandline library is widely used by apps and examples within > DPDK, but it is not documented in our programmers guide and it requires > a lot of boilerplate code definitions in order to used. We can improve > this situation by creating a simple python script to automatically > generate the boilerplate from a list of commands. > > This patchset contains a new documentation chapter on cmdline library, > going through step-by-step how to add commands and create the necessary > token lists and parse contexts. > > Following that initial doc patch, the set then contains a > boilerplate-generating script, as well as a set of four patches showing > its use, by converting four examples to use the script instead of > having the hard-coded boilerplate. Once the script is used, adding a new > command becomes as simple as adding the desired command to the .list > file, and then writing the required function which will be called for > that command. No other boilerplate coding is necessary. > > Final two patches, from V5 onwards, add support for option-lists in values, > and then use that support to convert over a fifth sample app - ntb. > > Cmdline script obviously does not cover the full range of capabilities > of the commandline lib, but does cover the most used parts. The > code-saving to each of the examples by auto-generating the boilerplate > is significant, and probably more examples with commandlines can be > converted over in future. > > The "cmdline" example itself, is not converted over, as it should > probably remain as a simple example of direct library use without the > script. > > v7: > * Increased use of multi-line strings in python script, following feedback. > > v6: > * rework syntax of the option lists following feedback from David. > Now use "(x,y,z)" instead of "|x|y|z|", to avoid giving impression > of regex support > > V5: > * Added copyright headers to command list files > * Add support for option lists > * Convert examples/ntb to use script > > V4: > * Reworked script following feedback from Robin J. > - formatted code with black > - used multi-line strings > - replaced sys.exit(1) with proper error handling > - per-command function returns lists rather than printing directly > - other small cleanups > * Added change to CI script so the cmdline script is in PATH > * Converted VDPA example to script, saving another 100 LOC > > V3: > * Added lots of documentation > * Added support for help text for each command > * Cleaned up script a little so it passes pycodestyle and most flake8 > checks, when line-length is set to max 100. > * Removed RFC tag, as I consider this patchset stable enough for > consideration in a release. > > V2-RFC: > * Add support for IP addresses in commands > * Move to buildtools directory and make installable > * Convert 3 examples to use script, and eliminate their boilerplate > > > Bruce Richardson (9): > doc/prog_guide: new chapter on cmdline library > buildtools: script to generate cmdline boilerplate > ci: allow use of DPDK tools when building examples > examples/simple_mp: auto-generate cmdline boilerplate > examples/hotplug_mp: auto-generate cmdline boilerplate > examples/bond: auto-generate cmdline boilerplate > examples/vdpa: auto-generate cmdline boilerplate > buildtools/dpdk-cmdline-gen: support option strings > examples/ntb: auto-generate cmdline boilerplate > > .ci/linux-build.sh | 1 + > app/test/commands.c | 2 + > buildtools/dpdk-cmdline-gen.py | 202 ++++++++ > buildtools/meson.build | 7 + > doc/guides/prog_guide/cmdline.rst | 473 ++++++++++++++++++ > doc/guides/prog_guide/index.rst | 1 + > examples/bond/Makefile | 12 +- > examples/bond/commands.list | 6 + > examples/bond/main.c | 161 +----- > examples/bond/main.h | 10 - > examples/bond/meson.build | 8 + > examples/multi_process/hotplug_mp/Makefile | 12 +- > examples/multi_process/hotplug_mp/commands.c | 147 +----- > examples/multi_process/hotplug_mp/commands.h | 10 - > .../multi_process/hotplug_mp/commands.list | 8 + > examples/multi_process/hotplug_mp/meson.build | 9 + > examples/multi_process/simple_mp/Makefile | 12 +- > examples/multi_process/simple_mp/meson.build | 9 + > .../multi_process/simple_mp/mp_commands.c | 106 +--- > .../multi_process/simple_mp/mp_commands.h | 14 - > .../multi_process/simple_mp/mp_commands.list | 6 + > examples/ntb/Makefile | 12 +- > examples/ntb/commands.list | 11 + > examples/ntb/meson.build | 7 + > examples/ntb/ntb_fwd.c | 200 +------- > examples/vdpa/Makefile | 12 +- > examples/vdpa/commands.list | 8 + > examples/vdpa/main.c | 131 +---- > examples/vdpa/meson.build | 7 + > 29 files changed, 871 insertions(+), 733 deletions(-) > create mode 100755 buildtools/dpdk-cmdline-gen.py > create mode 100644 doc/guides/prog_guide/cmdline.rst > create mode 100644 examples/bond/commands.list > delete mode 100644 examples/bond/main.h > delete mode 100644 examples/multi_process/hotplug_mp/commands.h > create mode 100644 examples/multi_process/hotplug_mp/commands.list > delete mode 100644 examples/multi_process/simple_mp/mp_commands.h > create mode 100644 examples/multi_process/simple_mp/mp_commands.list > create mode 100644 examples/ntb/commands.list > create mode 100644 examples/vdpa/commands.list I fixed a few issues: - devtools/test-meson.builds.sh was missing some update so the new script is used when building examples out of dpdk tree, - the examples/bond patch contained a change belonging to a previous patch, - some meson.build updates contained tabs, - the documentation and the new script were not referenced in the MAINTAINERS file, - the cmdline documentation used explicitly numbered items while the coding style for the doc recommends use of #., For the series, Acked-by: David Marchand <david.marchand@redhat.com> Series applied, thanks for this nice cleanup/improvement.