v01d commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480195487
##########
File path: Documentation/guides/simulator.rst
##########
@@ -0,0 +1,145 @@
+.. include:: /substitutions.rst
+.. _simulator:
+
+Simulator
+=========
+
+Apache NuttX has a simulator that can run as a regular program on Linux, Mac,
and Windows computers.
+It's useful for debugging operating system features that aren't associated
with particular
+device drivers— for instance the TCP/IP stack itself, a web interface or API
for your
+application, or other communication protocols. It's also handy for trying out
Apache NuttX without
+having a piece of embedded hardware.
+
+This guide assumes you're on Linux. It works on Windows and Mac too— if you
know how,
+submit a PR the NuttX Companion to update this guide!
+
+Compiling
+---------
+
+#. Configure the Simulator
+
+ There are a lot of simulator configurations available that set you up to
test various
+ operating system features.
+
+ Here we'll use the ``sim:tcpblaster`` configuration because it comes with
networking
+ that is ready to use.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh sim:tcpblaster
+
+#. Compile
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+Running
+-------
+
+#. Give the Simulator Privileges
+
+ On recent Linux distributions, you need to give the ``nuttx`` program the
capabilities
+ (similar to permissions) to access the network:
+
+ .. code-block:: bash
+
+ $ sudo setcap cap_net_admin+ep ./nuttx
+
+#. Run the simulator:
+
+ .. code-block:: bash
+
+ $ ./nuttx
+
+#. Bring Up the Network Interfaces
+
+ On Apache NuttX:
+
+ .. code-block:: bash
+
+ nsh> ifup eth0
+
+ On Linux, first you need to find your main network interface— this will
usually either
+ be an ethernet or wireless network adapter. Do this:
+
+ .. code-block:: bash
+
+ $ ifconfig
+ lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
+ inet 127.0.0.1 netmask 255.0.0.0
+ inet6 ::1 prefixlen 128 scopeid 0x10<host>
+ loop txqueuelen 1000 (Local Loopback)
+ RX packets 5846 bytes 614351 (614.3 KB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 5846 bytes 614351 (614.3 KB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ wlp0s20f3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
+ inet 192.168.1.209 netmask 255.255.255.0 broadcast
192.168.1.255
+ inet6 fe80::1161:c26b:af05:d784 prefixlen 64 scopeid
0x20<link>
+ ether 24:41:8c:a8:30:d1 txqueuelen 1000 (Ethernet)
+ RX packets 219369 bytes 176416490 (176.4 MB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 108399 bytes 27213617 (27.2 MB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+ ``lo0`` is the Loopback Interface, so ``wlp0s20f3`` is the wireless
interface. Note
+ that it has an IP address on the local net. There may be other interfaces
listed, you'll
+ need to pick the one that's right for your system.
+
+ Then, on Linux do this to set up the tap network interface and route that
will let
+ the Apache Nuttx simulator access the network:
+
+ .. code-block:: bash
+
+ $ sudo ./tools/simhostroute.sh wlp0s20f3 on
+ $ ping -c 1 10.0.1.2 # nuttx system
+ PING 10.0.1.2 (10.0.1.2) 56(84) bytes of data.
+ 64 bytes from 10.0.1.2: icmp_seq=1 ttl=64 time=7.52 ms
+
+ --- 10.0.1.2 ping statistics ---
+ 1 packets transmitted, 1 received, 0% packet loss, time 0ms
+ rtt min/avg/max/mdev = 7.529/7.529/7.529/0.000 m
+
+#. Test that Apache NuttX can access the Internet
+
+ First let's ping the network interface of our Linux host to prove we can
see the
+ gateway to the Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 10.0.1.1
+ nsh> ping -c 1 10.0.1.1
+ PING 10.0.1.1 56 bytes of data
+ 56 bytes from 10.0.1.1: icmp_seq=0 time=0 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Now let's ping one of Google's DNS servers to prove we can access the rest
of the
+ Internet:
+
+ .. code-block:: bash
+
+ nsh> ping -c 1 8.8.8.8
+ PING 8.8.8.8 56 bytes of data
+ 56 bytes from 8.8.8.8: icmp_seq=0 time=10 ms
+ 1 packets transmitted, 1 received, 0% packet loss, time 1010 ms
+
+ Success!
+
+Stopping
+--------
+
+The only really effective way to stop the simulator is kill it from another
terminal:
+
+ .. code-block:: bash
+
+ $ pkill nuttx
Review comment:
The most direct way is to call "poweroff" within nuttx. But if you don't
have a prompt, you need to kill as you shown so this can be a second
instruction.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
