[dvsim] Correct argparse usage statement and help

Argparse prefers positional arguments follow after optional arguments
but nargs * causes the positional argument entered as described in the
usage to be consumed by the arbitrary list of args.
* changed usage message to reflect the usage as described by our docs,
  it looses detail but argparse just doesn't have the flexibility to
  keep it
* fixed the message that described incorrect invocation that started me
  down this path
* added a message to the help that describes appropriate invocation

Signed-off-by: Drew Macrae <drewmacrae@google.com>

rules/opentitan_test.bzl

diff --git a/rules/opentitan_test.bzl b/rules/opentitan_test.bzl
index 11e349c..a23511e 100644
--- a/rules/opentitan_test.bzl
+++ b/rules/opentitan_test.bzl
@@ -55,6 +55,7 @@
     required_args = [
         "-i",
         "chip_sw_{name}",
+        "--",
     ]
     required_data = [
         dvsim_config,
@@ -63,7 +64,7 @@
     ]
     required_tags = ["dv"]
     kwargs.update(
-        args = required_args + args,
+        args = args + required_args,
         data = required_data + data,
         local = local,
         otp = otp,

util/dvsim/dvsim.py

diff --git a/util/dvsim/dvsim.py b/util/dvsim/dvsim.py
index bf2bb69..9badcbe 100755
--- a/util/dvsim/dvsim.py
+++ b/util/dvsim/dvsim.py
@@ -267,12 +267,22 @@
 
 
 def parse_args():
+    cfg_metavar = "<cfg-hjson-file>"
     parser = argparse.ArgumentParser(
         description=wrapped_docstring(),
-        formatter_class=argparse.RawDescriptionHelpFormatter)
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        # #12377 [dvsim] prints invalid usage when constructed by argparse
+        # Disable it pending more verbose and automatic solution and document in
+        # help message
+        usage='%(prog)s {} [-h] [options]'.format(cfg_metavar),
+        epilog="Either place the positional argument ahead of the optional args:\n" \
+            "eg. `dvsim.py {} -i ITEM ITEM` \n" \
+            "or end a sequence of optional args with `--`:\n" \
+            "eg. `dvsim.py -i ITEM ITEM -- {}`\n".format(cfg_metavar,cfg_metavar)
+    )
 
     parser.add_argument("cfg",
-                        metavar="<cfg-hjson-file>",
+                        metavar=cfg_metavar,
                         help="""Configuration hjson file.""")
 
     parser.add_argument("--version",
@@ -297,7 +307,8 @@
                               'the things that can be run, then exit. The '
                               'list can be filtered with a space-separated '
                               'of categories from: {}.'.format(
-                                  ', '.join(_LIST_CATEGORIES))))
+                                  ', '.join(_LIST_CATEGORIES)))
+    )
 
     whatg = parser.add_argument_group('Choosing what to run')