Document command-line options for simple_switch_grpc

Fixes #831

src/bm_sim/target_parser.cpp

@@ -184,7 +184,9 @@ TargetParserBasic::get_flag_option(const std::string &name, bool *v) const {
 TargetParserBasicWithDynModules::TargetParserBasicWithDynModules() {
 #ifdef BM_ENABLE_MODULES
     add_string_option(load_modules_option,
-                      "Load the given .so files (comma-separated) as modules.");
+                      "Load the given .so files (comma-separated) as modules. "
+                      "This is useful when you want to use dynamic libraries "
+                      "to provide extern type implementations at runtime.");
 #endif  // BM_ENABLE_MODULES
 }
 

targets/simple_switch/main.cpp

@@ -42,10 +42,10 @@ main(int argc, char* argv[]) {
   bm::TargetParserBasicWithDynModules simple_switch_parser;
   simple_switch_parser.add_flag_option(
       "enable-swap",
-      "enable JSON swapping at runtime");
+      "Enable JSON swapping at runtime");
   simple_switch_parser.add_uint_option(
       "drop-port",
-      "choose drop port number (default is 511)");
+      "Choose drop port number (default is 511)");
 
   bm::OptionsParser parser;
   parser.parse(argc, argv, &simple_switch_parser);

targets/simple_switch_grpc/README.md

@@ -36,6 +36,43 @@ Github or the p4-dev mailing list.
     [sudo] make install  # if desired
     ```
 
+## Running simple_switch_grpc
+
+For information on how to run simple_switch_grpc, use `simple_switch_grpc
+--help`. In particular, take a look at the target-specific command-line options
+at the end of the help message. These command-line options are specific to
+simple_switch_grpc (to be precise, some of them are shared with the
+simple_switch binary). When invoking simple_switch_grpc, these options will need
+to be separated from standard bmv2 options using `--`.
+
+Most users will invoke simple_switch_grpc as follows:
+```
+simple_switch_grpc --skip-p4 \
+    -i <PORT1>@<IFACE1> -i <PORT2>@<IFACE2> <more ports> \
+    -- --grpc-server-addr <IP>:<TCP PORT> --cpu-port <CPU_PORT>
+```
+
+* `--skip-p4` is a standard bmv2 command-line option. It means that no JSON file
+  is provided when starting simple_switch_grpc and bmv2 will not initially be
+  able to process packets (i.e. all packets will be dropped). You will need to
+  provide a P4 "pipeline" (including a JSON file and a P4Info message) with the
+  P4Runtime `SetForwardingPipelineConfig` RPC. **This is the recommended way to
+  use simple_switch_grpc.**
+* `--grpc-server-addr` is used to provide a socket address on which the
+  P4Runtime server will be run (e.g. localhost:1234, 192.168.1.1:31416,
+  [::1]:27182, ...). It will default to 0.0.0.0:50051.
+* `--cpu-port` is used to provide a CPU port number and enable P4Runtime
+  packet-in / packet-out support. **We recommend that you use this option** as
+  otherwise you will not be able to receive / send packets using the P4Runtime
+  `StreamChannel` bi-directional stream. Packets sent to this port in ingress
+  will be sent to the P4Runtime controller, while packets received from the
+  controller will be injected in the pipeline on this port. When using standard
+  v1model.p4, the value must fit within 9 bits (as the `egress_spec` field in
+  `standard_metadata_t` has type `bit<9>`). 0 is not a valid value. Do not use
+  511 as it is reserved for the "drop port" by default. If you need to use 511
+  for the CPU port, you will need to provide a new drop port value using the
+  `--drop-port` command-line option.
+
 ## Tentative gNMI support with sysrepo
 
 We are working on supporting gNMI and OpenConfig YANG models as part of the

targets/simple_switch_grpc/main.cpp

@@ -30,20 +30,30 @@ main(int argc, char* argv[]) {
   bm::TargetParserBasicWithDynModules simple_switch_parser;
   simple_switch_parser.add_flag_option(
       "disable-swap",
-      "disable JSON swapping at runtime");
+      "Disable JSON swapping at runtime; this is not recommended when using "
+      "P4Runtime!");
   simple_switch_parser.add_string_option(
       "grpc-server-addr",
-      "bind gRPC server to given address [default is 0.0.0.0:50051]");
+      "Bind gRPC server to given address [default is 0.0.0.0:50051]");
   simple_switch_parser.add_uint_option(
       "cpu-port",
-      "set CPU port, will be used for packet-in / packet-out; "
-      "do not add an interface with this port number");
+      "Choose a numerical value for the CPU port, it will be used for "
+      "packet-in / packet-out. Do not add an interface with this port number, "
+      "and 0 is not a valid value. "
+      "When using standard v1model.p4, this value must fit within 9 bits. "
+      "If you do not use this command-line option, "
+      "P4Runtime packet IO functionality will not be available: you will not "
+      "be able to receive / send packets using the P4Runtime StreamChannel "
+      "bi-directional stream.");
   simple_switch_parser.add_uint_option(
       "drop-port",
-      "choose drop port number (default is 511)");
+      "Choose a numerical value for the drop port (default is 511). "
+      "When using standard v1model.p4, this value must fit within 9 bits. "
+      "You will need to use this command-line option when you wish to use port "
+      "511 as a valid dataplane port or as the CPU port.");
   simple_switch_parser.add_string_option(
       "dp-grpc-server-addr",
-      "use a gRPC channel to inject and receive dataplane packets; "
+      "Use a gRPC channel to inject and receive dataplane packets; "
       "bind this gRPC server to given address, e.g. 0.0.0.0:50052");
 
   bm::OptionsParser parser;