buildtools/cmdline: support optional parameters

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 <[email protected]>
Acked-by: Sunil Kumar Kori <[email protected]>

Author: bruce-richardson

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

doc/guides/prog_guide/cmdline.rst

@@ -159,6 +159,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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~