samples: net Documented QEMU_INSTANCE usage

Signed-off-by: John Andersen <john.s.andersen@intel.com>

doc/subsystems/networking/qemu_setup.rst

@@ -171,3 +171,34 @@ Terminal #2:
 
 This will start 2nd QEMU instance, and you should see logging of data sent and
 received in both.
+
+Running multiple QEMU VMs of the same sample
+********************************************
+
+If you find yourself needing to run multiple instances of the same Zephyr
+sample application, which do not need to be able to talk to each other, the
+``QEMU_INSTANCE`` argument is what you need.
+
+Start socat and tunslip6 manually (avoiding loop-x.sh scripts) for as many
+instances as you want. Use the following as a guide, replacing MAIN or OTHER.
+
+Terminal #1:
+============
+
+.. code-block:: console
+
+   $ socat PTY,link=/tmp/slip.devMAIN UNIX-LISTEN:/tmp/slip.sockMAIN
+   $ $ZEPHYR_BASE/../net-tools/tunslip6 -t tapMAIN -T -s /tmp/slip.devMAIN \
+        2001:db8::1/64
+   # Now run Zephyr
+   $ make run QEMU_INSTANCE=MAIN
+
+Terminal #2:
+============
+
+.. code-block:: console
+
+   $ socat PTY,link=/tmp/slip.devOTHER UNIX-LISTEN:/tmp/slip.sockOTHER
+   $ $ZEPHYR_BASE/../net-tools/tunslip6 -t tapOTHER -T -s /tmp/slip.devOTHER \
+        2001:db8::1/64
+   $ make run QEMU_INSTANCE=OTHER

samples/net/common/Makefile.ipstack

@@ -18,6 +18,8 @@ ifdef QEMU_NUM
 	QEMU_EXTRA_FLAGS += -serial none -serial pipe:${PIPE_BASE}-${QEMU_NUM}	\
 			    -pidfile qemu-${QEMU_NUM}.pid
 else
+	# QEMU_INSTANCE is a command line argument to make. By appending the instance
+	# name to the slip socket we can easily run more instances.
 	QEMU_EXTRA_FLAGS += -serial none -serial unix:/tmp/slip.sock$(QEMU_INSTANCE)
 endif
 

scripts/Makefile.qemu

@@ -6,6 +6,8 @@
 
 # Abstraction of 'run' goal with Qemu
 
+# QEMU_INSTANCE is a command line argument to make. By appending the instance
+# name to the pid file we can easily run more instances of the same sample.
 QEMU_FLAGS = $(QEMU_FLAGS_$(ARCH)) -pidfile qemu$(QEMU_INSTANCE).pid
 
 ifneq ($(QEMU_PTY),)