mirror of
https://github.com/apache/nuttx.git
synced 2026-10-08 06:45:19 +00:00
f6ecf80ebb
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.
This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.
What it does:
* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
its old path, so old URLs keep working. The redirect page also carries
a link's #anchor across to the new page.
Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:
index the front page
os/index OS Design
os/scheduling/index Scheduling
os/interrupts/index Interrupts
os/ipc/index IPC
os/time/index Time and timers
about/index About
developing/index Developing NuttX
ReleaseNotes/index Release notes
The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.
Nothing outside Documentation/ is touched.
How it was checked:
* Sphinx builds with -W: no warnings, and no document left outside a
toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
For every page outside the ten named above it erases what a move
touches -- link target, path, tag line, toctree block, table border --
from the whole old text and the whole new text, and requires the two
to be byte for byte identical. It also requires every sentence of a
deleted page to turn up somewhere, and every page that left its old
path to have a redirect, from a URL that existed, to where its content
went. It exits non-zero and names the page if any of that is not true,
and it tests added pages too, so forgetting to declare one cannot make
it pass.
* An independent audit checked 133 factual claims on these ten pages
against the tree, one shell command per claim: 130 confirmed, 1
refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.
The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.
Assisted-by: Claude:claude-opus-5
318 lines
8.8 KiB
ReStructuredText
318 lines
8.8 KiB
ReStructuredText
.. 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 to improve this guide!
|
|
|
|
.. todo:: Windows instructions
|
|
|
|
Prerequisites For macOS
|
|
=======================
|
|
|
|
We need ``genromfs`` to build simulators(NON GUI).
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone https://github.com/chexum/genromfs.git
|
|
$ cd genromfs
|
|
$ make
|
|
$ make install
|
|
|
|
Now Copy the built `genromfs` `exec` to /opt/local/bin.
|
|
|
|
For GUI Applications we need X11 Libraries, libx11 can also be built using Homebrew or by Installing XQuartz.
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo port install xorg-libX11
|
|
$ sudo port install xorg-server
|
|
|
|
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:nsh`` basic NuttX Shell configuration.
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd nuttx
|
|
$ ./tools/configure.sh sim:nsh
|
|
|
|
#. Compile
|
|
|
|
.. code-block:: console
|
|
|
|
$ make
|
|
|
|
#. Run the simulator:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./nuttx
|
|
|
|
NuttShell (NSH) NuttX-12.10.0
|
|
nsh> help
|
|
help usage: help [-v] [<cmd>]
|
|
|
|
[ cp exit losetup mv rmdir true
|
|
? cmp false ls mw set uname
|
|
basename dirname free mb poweroff sh unset
|
|
break dd help mkdir ps sleep usleep
|
|
cat echo hexdump mkfatfs pwd test xd
|
|
cd exec kill mh rm time
|
|
|
|
Builtin Apps:
|
|
hello nsh
|
|
|
|
nsh>
|
|
|
|
#. Stop the simulator:
|
|
|
|
.. code-block:: console
|
|
|
|
nsh> poweroff
|
|
$
|
|
$ # we're back at the Linux prompt.
|
|
|
|
.. _simulator_accessing_the_network:
|
|
|
|
Accessing the Network
|
|
=====================
|
|
|
|
#. Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
|
|
that is ready to use.
|
|
|
|
.. code-block:: console
|
|
|
|
$ make distclean
|
|
$ ./tools/configure.sh sim:tcpblaster
|
|
$ make
|
|
|
|
#. 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:: console
|
|
|
|
$ sudo setcap cap_net_admin+ep ./nuttx
|
|
|
|
#. Run the simulator:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./nuttx
|
|
|
|
#. Bring Up the Network Interfaces
|
|
|
|
On Apache NuttX:
|
|
|
|
.. code-block:: console
|
|
|
|
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:: console
|
|
|
|
$ 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:: console
|
|
|
|
$ 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:: console
|
|
|
|
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:: console
|
|
|
|
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
|
|
|
|
If it doesn't work, then you need to enable the IP forward on your computer:
|
|
|
|
.. code-block:: console
|
|
|
|
sudo sysctl -w net.ipv4.ip_forward=1
|
|
|
|
Success!
|
|
|
|
Testing / capturing TCP network traffic
|
|
=======================================
|
|
|
|
#. Start Wireshark (or tcpdump) on Linux and capture the appeared tap0 interface.
|
|
|
|
#. Optionally activate emulating packet loss on Linux:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo iptables -A INPUT -p tcp --dport 31337 -m statistic --mode random --probability 0.01 -j DROP
|
|
|
|
#. Run netcat server on Linux:
|
|
|
|
.. code-block:: console
|
|
|
|
$ netcat -l -p 31337
|
|
|
|
#. Run netcat client on Apache NuttX:
|
|
|
|
.. code-block:: console
|
|
|
|
nsh> dd if=/dev/zero of=/tmp/test.bin count=1000
|
|
nsh> netcat LINUX_HOST_IP_ADDRESS 31337 /tmp/test.bin
|
|
|
|
#. Observe TCP network traffic in Wireshark / tcpdump on Linux.
|
|
|
|
Testing NxModbus RTU on simulator
|
|
=================================
|
|
|
|
#. Create a virtual UART pair on Linux:
|
|
|
|
.. code-block:: console
|
|
|
|
$ socat PTY,link=/tmp/ttyNXB0 PTY,link=/tmp/ttyNXB1 &
|
|
$ stty -F /tmp/ttyNXB0 raw
|
|
$ stty -F /tmp/ttyNXB1 raw
|
|
|
|
#. Build NuttX with the NxModbus RTU simulator configuration:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./tools/configure.sh sim:nxmbrtu
|
|
$ make
|
|
|
|
#. Start the server instance (slave):
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./nuttx
|
|
nsh> nxmbserver -t rtu -d /tmp/ttyNXB0 -b 9600 -p none -u 1
|
|
Starting Modbus RTU server on /tmp/ttyNXB0 (baud=9600, unit=1)
|
|
Server running. Press Ctrl+C to stop.
|
|
Register map:
|
|
Coils: 1-100 (read/write)
|
|
Discrete: 1-100 (read-only)
|
|
Input regs: 1-100 (read-only, value=addr*10)
|
|
Holding regs: 1-100 (read/write, initial=addr*100)
|
|
|
|
#. In another terminal, start a second simulator instance and run the client
|
|
command (master) against the server:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./nuttx
|
|
nsh> nxmbclient -t rtu -d /tmp/ttyNXB1 -b 9600 -p none -u 1 read-holding 0 10
|
|
0 0
|
|
1 100
|
|
2 200
|
|
3 300
|
|
4 400
|
|
5 500
|
|
6 600
|
|
7 700
|
|
8 800
|
|
9 900
|
|
|
|
#. Optional write/read-back check:
|
|
|
|
.. code-block:: console
|
|
|
|
nsh> nxmbclient -t rtu -d /tmp/ttyNXB1 -b 9600 -p none -u 1 write-holding 0 123
|
|
OK
|
|
nsh> nxmbclient -t rtu -d /tmp/ttyNXB1 -b 9600 -p none -u 1 read-holding 0 1
|
|
0 123
|
|
|
|
Stopping
|
|
========
|
|
|
|
#. The normal way to stop:
|
|
|
|
.. code-block:: console
|
|
|
|
nsh> poweroff
|
|
$
|
|
$ # we're back at the Linux prompt.
|
|
|
|
If you don't have an nsh prompt, the only effective way to stop the simulator is kill it from another terminal:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pkill nuttx
|
|
|
|
#. Optionally deactivate emulating packet loss on Linux:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo iptables -D INPUT -p tcp --dport 31337 -m statistic --mode random --probability 0.01 -j DROP
|
|
|
|
#. If you do not need tap0 interface anymore, it can be disabled on Linux as follows:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo ./tools/simhostroute.sh wlan0 off
|
|
|
|
Debugging
|
|
=========
|
|
|
|
You can debug the simulator like any regular Linux program.
|