[PATCH 1/3] buildtools/dpdk-cmdline-gen: support optional parameters

[Bruce Richardson <bruce.richardson@intel.com>]

Sometimes a user may want to have a command which takes an optional
parameter. For commands with an optional constant string, this is no
issue, as it can be configured as two separate commands, e.g.

start
start tx_first.

However, if we want to have a variable parameter on the command, we hit
issues, because variable tokens do not form part of the generated
command names used for function and result-struct naming. To avoid
duplicate name issues, we add a special syntax to allow the user to
indicate that a particular variable parameter should be included in the
name. Any leading variable names starting with a "__" will be included
in command naming.

This then allows us to have:

start
start tx_first
start tx_first <UINT16>__n

without hitting any naming conflicts.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 buildtools/dpdk-cmdline-gen.py    |  9 ++++++++-
 doc/guides/prog_guide/cmdline.rst | 13 +++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/buildtools/dpdk-cmdline-gen.py b/buildtools/dpdk-cmdline-gen.py
index bf1253d949..faee4ffca7 100755
--- a/buildtools/dpdk-cmdline-gen.py
+++ b/buildtools/dpdk-cmdline-gen.py
@@ -40,7 +40,12 @@ def process_command(lineno, tokens, comment):
     name_tokens = []
     for t in tokens:
         if t.startswith("<"):
-            break
+            # stop processing the name building at a variable token,
+            # UNLESS the token name starts with "__"
+            t_type, t_name = t[1:].split(">")
+            if not t_name.startswith("__"):
+                break
+            t = t_name[2:]   # strip off the leading '__'
         name_tokens.append(t)
     name = "_".join(name_tokens)
 
@@ -51,6 +56,8 @@ def process_command(lineno, tokens, comment):
         if t.startswith("<"):
             t_type, t_name = t[1:].split(">")
             t_val = "NULL"
+            if t_name.startswith("__"):
+                t_name = t_name[2:]
         else:
             t_type = "STRING"
             t_name = t
diff --git a/doc/guides/prog_guide/cmdline.rst b/doc/guides/prog_guide/cmdline.rst
index b804d7a328..fc32d727dc 100644
--- a/doc/guides/prog_guide/cmdline.rst
+++ b/doc/guides/prog_guide/cmdline.rst
@@ -155,6 +155,19 @@ To get at the results structure for each command above,
 the ``parsed_result`` parameter should be cast to ``struct cmd_quit_result``
 or ``struct cmd_show_port_stats_result`` respectively.
 
+.. note::
+
+  In some cases, the user may want to have an optional variable parameter at the end of a command.
+  Such a variable parameter would not normally be included in the ``<cmdname>`` string,
+  leading to duplicate definition errors.
+  To work around this,
+  any variable token with a name prefixed by ``'__'`` will be included in the cmdname string,
+  with the prefix removed.
+  Using this, it is possible to have commands, such as:
+  ``start tx_first`` and ``start tx_first <UINT16>__n``, without them conflicting.
+  The resulting code generated will expect functions called ``cmd_start_tx_first_parsed``
+  and ``cmd_start_tx_first_n_parsed`` respectively.
+
 Integrating with the Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.40.1