From 913e2cdb249a31df362d34b5ec1a834d05f921cb Mon Sep 17 00:00:00 2001
From: John Andersen <john.s.andersen@intel.com>
Date: Wed, 28 Jun 2017 14:59:11 -0700
Subject: [PATCH] samples: net Documented QEMU_INSTANCE usage

Signed-off-by: John Andersen <john.s.andersen@intel.com>
---
 doc/subsystems/networking/qemu_setup.rst | 31 ++++++++++++++++++++++++
 samples/net/common/Makefile.ipstack      |  2 ++
 scripts/Makefile.qemu                    |  2 ++
 3 files changed, 35 insertions(+)

diff --git a/doc/subsystems/networking/qemu_setup.rst b/doc/subsystems/networking/qemu_setup.rst
index b0d851123c9..40679b74eab 100644
--- a/doc/subsystems/networking/qemu_setup.rst
+++ b/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
diff --git a/samples/net/common/Makefile.ipstack b/samples/net/common/Makefile.ipstack
index 81aef24de3c..501273fbdee 100644
--- a/samples/net/common/Makefile.ipstack
+++ b/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
 
diff --git a/scripts/Makefile.qemu b/scripts/Makefile.qemu
index b0bba796b34..9a943248b52 100644
--- a/scripts/Makefile.qemu
+++ b/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),)