comms/uniflow/benchmarks: say what --tcp-iface does, and does not, do (meta-pytorch#3900)

Summary:
Pull Request resolved: meta-pytorch#3900

Three TCP flags overlap enough to be mistaken for one another, and the one
easiest to misread had no comment at all:

- `--tcp-iface` selects the local address to bind and advertise. It does not
  choose the egress NIC -- routing does. On a host where several NICs share a
  route, traffic can leave via one device no matter what this names.
- `--tcp-bind-dev` is a bool, not a device name. It promotes whatever
  `--tcp-iface` already names into an `SO_BINDTODEVICE` pin.
- `--tcp-bind-devs` is the multi-device list, and wins over `--tcp-bind-dev`
  with no warning when both are passed.

The help text called `--tcp-iface` the "front-end interface for the TCP
transport", which reads like it picks the NIC.

This documents the address-vs-device split on the field and in `--help`, and
records on `tcpBindDevList` -- where the precedence is implemented -- that
`--tcp-iface` keeps selecting the source address when striping, so it wants to
name one of the bound devices. Pointing it at an unbound NIC advertises an
address on a device carrying no lanes: legal, and confusing.

Nothing is added for the parts already covered -- the `--tcp-bind-dev` field
comment already explains the routing trap, and the `--tcp-bind-devs` help
already covers `i%count`, one listener per device, and the peer-agreement
constraints. Restating those would only create places to drift.

Comments and help text only; no behaviour change.

Differential Revision: D117640557

Author: Peng Chen

comms/uniflow/benchmarks/main.cpp

@@ -63,6 +63,9 @@ struct CliOptions {
   size_t slabSize{0};
   int slabNum{0};
   std::vector<std::string> rdmaDevices;
+  // Selects which local IPv6 address the TCP transport binds and advertises,
+  // and nothing else. Which NIC actually carries the bytes is a separate axis
+  // -- see --tcp-bind-dev below.
   std::string tcpIface{"eth2"};
   // SO_SNDBUF/SO_RCVBUF for the TCP data connection. Defaults to the
   // TcpSocketConfig default; 0 leaves the kernel's sizing alone.
@@ -96,6 +99,10 @@ std::vector<int> parseIntList(const std::string& s) {
 
 // --tcp-bind-devs wins over --tcp-bind-dev, which is just the single-device
 // shorthand for whatever --tcp-iface names. Empty means no device binding.
+//
+// --tcp-iface keeps selecting the source address either way, so when striping
+// it wants to name one of the bound devices: pointing it at an unbound NIC
+// advertises an address on a device carrying no lanes.
 std::vector<std::string> tcpBindDevList(const CliOptions& opts) {
   std::vector<std::string> devices;
   if (!opts.tcpBindDevs.empty()) {
@@ -175,7 +182,9 @@ void printUsage(const char* prog) {
       << "  --output <path>        CSV output file path\n"
       << "  --format <fmt>         table|csv|both (default: table)\n"
       << "  --rdma-devices <list>  Comma-separated RDMA device names (default: auto-discover)\n"
-      << "  --tcp-iface <name>     Front-end interface for the TCP transport (default: eth2)\n"
+      << "  --tcp-iface <name>     Interface whose address the TCP transport binds and\n"
+      << "                         advertises (default: eth2). Selects the source address\n"
+      << "                         only -- see --tcp-bind-dev to pin the egress NIC\n"
       << "  --tcp-sockbuf <bytes>  TCP data-connection SO_SNDBUF/SO_RCVBUF (default: 0,\n"
       << "                         which leaves it unset so the kernel autotunes the\n"
       << "                         window; setting it explicitly disables autotuning)\n"