You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2023/11/06 21:42:22 UTC
(nuttx) branch master updated (59107e5573 -> 4d65d9908b)
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
from 59107e5573 esp32s3: Fix issue regarding IRAM-enabled ISRs by fixing the linker
new 200f709092 Documentation: migrate "NxTerm Example" from wiki
new caef223268 Documentation: migrate "CNxConsole Keyboard Input" from wiki
new 1f9e17f5c7 Documentation: add SystemView configuration instructions
new 8a8111c2fc Documentation: migrate "CONFIG_NET_GUARDSIZE" from wiki
new 2d8c4e6645 Documentation: migrate "SLIP Configuration" from wiki
new 1c6e5cc0c4 Documentation: migrate "Work Queue Deadlocks" from wiki
new 4d65d9908b Documentation: migrate "Auto-Mounter" from wiki
The 7 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../applications/examples/nxterm/index.rst | 174 +++++++++++++++++++++
.../applications/examples/nxterm/nxtermexample.png | Bin 0 -> 15366 bytes
.../applications/graphics/nxwm/cnxconsole.rst | 133 ++++++++++++++++
Documentation/applications/graphics/nxwm/index.rst | 6 +
.../components/drivers/special/segger.rst | 62 +++++++-
Documentation/components/net/index.rst | 3 +
Documentation/components/net/netguardsize.rst | 74 +++++++++
Documentation/components/net/slip.rst | 50 ++++++
Documentation/components/net/wqueuedeadlocks.rst | 174 +++++++++++++++++++++
Documentation/guides/automounter.rst | 69 ++++++++
Documentation/guides/index.rst | 1 +
11 files changed, 742 insertions(+), 4 deletions(-)
create mode 100644 Documentation/applications/examples/nxterm/nxtermexample.png
create mode 100644 Documentation/applications/graphics/nxwm/cnxconsole.rst
create mode 100644 Documentation/components/net/netguardsize.rst
create mode 100644 Documentation/components/net/slip.rst
create mode 100644 Documentation/components/net/wqueuedeadlocks.rst
create mode 100644 Documentation/guides/automounter.rst
(nuttx) 02/07: Documentation: migrate "CNxConsole Keyboard Input" from wiki
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit caef2232684488157fa874e26dd4fb87c3474b48
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 10:57:58 2023 +0100
Documentation: migrate "CNxConsole Keyboard Input" from wiki
link: https://cwiki.apache.org/confluence/display/NUTTX/CNxConsole+Keyboard+Input
---
.../applications/graphics/nxwm/cnxconsole.rst | 133 +++++++++++++++++++++
Documentation/applications/graphics/nxwm/index.rst | 6 +
2 files changed, 139 insertions(+)
diff --git a/Documentation/applications/graphics/nxwm/cnxconsole.rst b/Documentation/applications/graphics/nxwm/cnxconsole.rst
new file mode 100644
index 0000000000..b3ce36f1e4
--- /dev/null
+++ b/Documentation/applications/graphics/nxwm/cnxconsole.rst
@@ -0,0 +1,133 @@
+=========================
+CNxConsole Keyboard Input
+=========================
+
+**Players**
+
+Let's look at the major players in the keyboard data transfer. This is much more
+complex than you might initially think:
+
+**Special Drivers**
+NxConsole Device. The NX console input comes through a special device driver that
+is registered at ``/dev/nxcon0`` as part of early initialization.
+
+**Kernel Threads**
+
+* **NX Server Thread** The NX Server is the graphics server command. It receives
+ messages from various sources, performs graphics actions, and forwards graphic
+ event messages to the correct window. Most of the time, the NX Server Thread was
+ waiting on a message queue to receive the next graphics event.
+
+* **NxConsole Threads** Each NxConsole has a thread that was started when each
+ ``NxWM::CNxConsole`` instance was created by NxWM. Each ``NxWM::CNxConsole``
+ thread opens the NxConsole driver at ``/dev/nxcon0`` and redirects stdin,
+ stdout, and stderr to/from that special device. Normally, the ``NxWM::CNxConsole``
+ thread is stopped, just waiting on read for keyboard input to complete.
+
+**Application Threads**
+
+* **NxWidgets Window Event Handler Thread** ``CNxServer::listener()`` is an
+ application thread started by NxWidgets each time a new window is opened.
+ It receives window messages from the NX server and dispatches the messages
+ accordingly.
+
+* **Keyboard Listener Thread** ``CKeyboard::listener()`` is an application thread
+ that is started by NxWM. It just listens for keyboard input and forwards it through
+ the graphics routing system.
+
+Now here is the sequence of events to get keyboard input from the stdin device to
+the correct NxConsole.
+
+#. Application Space / NxWidgets Window Event Handler Thread
+ Let's start with the initial state of the NX Server Thread. Initially, it will
+ just want for messages from the NX Server.
+
+ * ``NxWidgets/libnxwidgets/src/cnxserver.cxx``
+ ``CNxServer::listener()`` is it window listener thread. It just calls
+ ``nx_eventhandler()`` to receive and process server events. There is one
+ such listener thread per window.
+
+ * ``nuttx/libnx/nxwm/nx_eventhandler``
+ ``nx_eventhandler()`` waits to receive a message from the NX server. Each
+ window has its own message queue; each window instance has its own
+ ``nx_eventhandler()`` waiting for messages.
+
+#. Application Space / Keyboard Listener Thread
+
+ Here are the immediate events that happen when the keyboard data is entered.
+ The Keyboard Listener Thread wakes up and forwards the Keyboard data to the
+ the NX Server. Only the NX Server knows which window should get the keyboard input.
+
+ * ``NxWidgets\nxwm\src\ckeyboard.cxx``
+ ``CKeyboard::listener()`` is a tiny thread that is started by NxWM that just
+ listens for keyboard input. It opens the keyboard device and waits on a ``read()``
+ from the keyboard device to receive the next keyboard input. When data is
+ returned by reading from the keyboard device, ``CKeyboard::listener()``
+ calls ``nx_kbdin()``
+
+ * ``nuttx\libnx\nxmu\nx_kbdin.c``
+ This library function just hides the NX server messaging implementation.
+ It sends the ``NX_SVRMSG_KBDIN`` to the NX server thread.
+
+#. Kernel Space / NX Server
+
+ The NX Server wakes up, receives the keyboard message, and forwards it to the
+ appropriate window.
+
+ * ``nuttx/graphics/nxmu/nxmu/nxmu_server.c``
+ The receipt of the ``NX_SVRMSG_KBDIN`` message wakes up the NX server
+ thread. The NX server thread decodes the message and calls ``nxmu_kbdin()``.
+
+ * ``nuttx/graphics/nxconsole/nxmu_kbdin.c``
+ ``nxmu_kbdin()`` simply sends the ``NX_CLIMSG_KBDIN`` to the appropriate
+ windows client via the client message queue associated with the window.
+
+#. Application Space / NxWidgets Window Event Handler Thread
+
+ The Windows client wakes up when the keyboard message is received. It forwards
+ the keyboard data to ``/dev/nxcon0/`` so that is can be available to the
+ NxConsole window.
+
+ * ``nuttx/libnx/nxwm/nx_eventhandler``
+ The ``nx_eventhandler()`` logic running in the ``CNxServer::listener()``
+ thread receives the ``NX_CLIMSG_KBDIN`` message and dispatches it to the
+ kbdin callback method. In this case that callback method maps to
+ ``CCallback::newKeyboardEvent()``.
+
+ * ``NxWidgets/libnxwidgets/src/ccallback.cxx``
+ For normal keyboard input, ``CCallback::newKeyboardEvent()`` directs the
+ Keyboard to the widget with focus via the ``CWidgetControl::newKeyboardEvent()``
+ method. But the story is different for the NxConsole window. This case,
+ ``CCallback::newKeyboardEvent()``, calls ``nxcon_kbdin()``.
+
+ * ``nuttx/graphics/nxconsole/nxcon_kbdin.c``
+ ``nxcon_kbdin()`` adds the keyboard data to a circular buffer and wakes up
+ any reads on the ``/dev/nxcon0`` input device.
+
+
+ NOTE: Here is a violation of the Application and Kernel Space boundaries.
+ ``nxcon_kbdin.c`` built into Kernel Space but it is called from Application
+ Space. The solution is to (1) move ``nxcon_kbdin()`` to ``libnx/`` and (2) it
+ should then communicate with the ``/dev/nxcon9`` driver via ioctl calls.
+ This will become a problem some day.
+
+#. Kernel Space / NxConsole Thread
+
+ Finally,
+ * ``nuttx/graphics/nxconsole/nxcon_kbdin.c``
+ The receipt and enqueuing of keyboard data by ``nxcon_kbdin()`` wakes up
+ any threads waiting in the ``nxcon_read()`` method. This is how the
+ NxConsole gets its keyboard input.
+
+
+**Mouse Input**
+Almost everything said here applies to mouse/touchscreen input as well. If we
+were to replace the names keyboard to mouse, kbdin to mousein, etc. you have a
+pretty good description of how mouse/touchscreen input works.
+
+The mouse/touchscreen input is a little simpler, however: The main simplication
+is that the additional complexities of the NxConsole and its special input device
+do not apply. Mouse/touchscreen inut as always steered to widgets when the
+callback is received in ``CCallback::newMouseEvent`` by an unconditional call to
+``CWidgetControl::newMouseEvent``. There is a "fork in the road" at the
+corresponding point in the logic of ``CCallback::newKeyboardEvent``
diff --git a/Documentation/applications/graphics/nxwm/index.rst b/Documentation/applications/graphics/nxwm/index.rst
index 910a9ea256..54b5214c50 100644
--- a/Documentation/applications/graphics/nxwm/index.rst
+++ b/Documentation/applications/graphics/nxwm/index.rst
@@ -28,6 +28,12 @@ as you want. (keybard input still comes through serial).
Note 1: NwWM requires ``NuttX-7.19`` or above to work with the current
``NxWidgets-1.18`` release.
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+ :caption: Contents
+
+ cnxconsole.rst
Doxygen
-------
(nuttx) 04/07: Documentation: migrate "CONFIG_NET_GUARDSIZE" from wiki
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 8a8111c2fc5c62dfee85662587fd92bbb9c08d2d
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 14:54:25 2023 +0100
Documentation: migrate "CONFIG_NET_GUARDSIZE" from wiki
link: https://cwiki.apache.org/confluence/display/NUTTX/CONFIG_NET_GUARDSIZE
---
Documentation/components/net/index.rst | 1 +
Documentation/components/net/netguardsize.rst | 74 +++++++++++++++++++++++++++
2 files changed, 75 insertions(+)
diff --git a/Documentation/components/net/index.rst b/Documentation/components/net/index.rst
index c7063af281..3a31a492b6 100644
--- a/Documentation/components/net/index.rst
+++ b/Documentation/components/net/index.rst
@@ -7,6 +7,7 @@ Network Support
sixlowpan.rst
socketcan.rst
+ netguardsize.rst
``net`` Directory Structure ::
diff --git a/Documentation/components/net/netguardsize.rst b/Documentation/components/net/netguardsize.rst
new file mode 100644
index 0000000000..3939485f0f
--- /dev/null
+++ b/Documentation/components/net/netguardsize.rst
@@ -0,0 +1,74 @@
+====================
+CONFIG_NET_GUARDSIZE
+====================
+
+Global Option for All Drivers
+=============================
+
+``CONFIG_NET_GUARD_SIZE`` is global option. It is added to the allocated size of
+each driver packet buffer. Currently it is a very small value, defaulting to only
+two bytes. So it is not a memory hog and should be added to the packetsize for
+all drivers for commonality. But why?
+
+It should (eventually) be larger and common for all drivers. We need to look at
+how it is used today and how it might be used tomorrow. There is a probably a lot
+more involved than you might be initially considering.
+
+Packet Receipt
+==============
+
+For packet receipt, it is necessary for some hardware, but not for others. Often
+the hardware will DMA a 2 byte FCS at the end of the packet or possibly other
+hardware-specific info. But that is only part of the whole story.
+``CONFIG_NET_GUARDSIZE`` is not just for hardware packet receipt.
+
+Packet Transmission
+===================
+
+There are several issues for packet transmission. These are less well defined
+and need further study, but we need to keep all of the driver packet definitions
+in place until we understand how we are going to handle these things:
+
+* Memory Overrun Bugs
+
+ There was in the past, a bug that caused write past the end of the buffer by
+ a couple of bytes during TX message formatting. I don't know if that bug still
+ exists, but the minimum, two-byte ``CONFIG_NET_GUARDSIZE`` was sufficient to
+ eliminate the bug. That is why it has the name GUARD: Its primary purpose is
+ to protect from overrunning the packet buffer and corrupting the following memory.
+
+ I do no know if we have any such bugs today. Perhaps they still do?
+ Perhaps they do not? Having such a guard is a good thing for reliability in
+ any case.
+
+* Variable size IP/TCP headers
+
+ There is a limitation in the way IP packets are formatted now. Basically they
+ are formatted like this:
+
+ #. When the packet is received a pointer to the location of the payload is
+ set (d_appdata). This is an offset into the packet buffer For TCP, that
+ accounts for the MAC/Ethernet header, the minimum IPv4/IPv6 header size,
+ and the minimum TCP header size.
+
+ #. The TCP payload is written at that location,
+ #. The correctly sized IPv4/IPv6 headers and the correctly sized TCP header
+ are added below the payload, and finally
+ #. The MAC/Ethernet header as added.
+
+ The start offset of the packet in the packet is no longer zero, but some
+ variable offset into the packet buffer. That new start offset would have
+ to be passed to driver in order to send the packet.
+
+ The key to making this all work is:
+
+ * Keep ``CONFIG_NET_GUARDSIZE`` in all driver buffers, and
+ * Set the ``CONFIG_NET_GUARDSIZE`` to the maximum size of IPv4/IPv6 and TCP options
+ (depending on which IP version is enabled and if TCP is enabled)
+ * Extend the driver interface to accept data offset into the driver's packet buffer.
+
+* Variable MSS
+
+ Closely related to this is the MSS which is the maximum size of the payload.
+ Currently that is a constant because it assumes the minimum header lengths.
+ It should be variable, depending on the actual header sizes.
(nuttx) 07/07: Documentation: migrate "Auto-Mounter" from wiki
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 4d65d9908bedada0fdc5451d749621c2d5511722
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 15:47:06 2023 +0100
Documentation: migrate "Auto-Mounter" from wiki
link: https://cwiki.apache.org/confluence/display/NUTTX/Auto-Mounter
---
Documentation/guides/automounter.rst | 69 ++++++++++++++++++++++++++++++++++++
Documentation/guides/index.rst | 1 +
2 files changed, 70 insertions(+)
diff --git a/Documentation/guides/automounter.rst b/Documentation/guides/automounter.rst
new file mode 100644
index 0000000000..45a2afe275
--- /dev/null
+++ b/Documentation/guides/automounter.rst
@@ -0,0 +1,69 @@
+============
+Auto-Mounter
+============
+
+General Description
+===================
+NuttX implements an auto-mounter than can make working with SD cards or other
+removable media easier. With the auto-mounter, the file system will be
+automatically mounted when media is inserted and automatically unmounted when
+the media is removed.
+
+The auto is enable by selecting in the NuttX configuration::
+
+ CONFIG_FS_AUTOMOUNTER=y
+
+
+WARNING: SD cards should never be removed without first unmounting them. This
+is to avoid data and possible corruption of the file system. Certainly this is
+the case if you are writing to the SD card at the time of the removal. If you
+use the SD card for read-only access, however, then I cannot think of any
+reason why removing the card without mounting would be harmful.
+
+For applications that write to the removable media, the automatic unmount is
+still beneficial (as opposed to leaving a broken mount in place) although
+should not be relied upon for a proper solution.
+
+Board-Specific Support
+======================
+
+Like many components of NuttX, the auto-mounter has a upper-half/lower-half
+architecture:
+
+* **Upper half** The upper half is the file ``fs/fs_automount.c``. This upper
+ half performs the basic automount activities. It responds to media
+ insertion and removal events by mounting and unmounting the file system on
+ the media. This includes logic to handle unmount retries: The unmount cannot
+ be performed while applications have open files on the media. In this case,
+ the auto-mounter will periodically retry the unmount until all of the
+ applications close there references to files on the non-existent media.
+
+* **Lower Half** The lower half is defined by a standard interface. That
+ interface definition is in the header file ``include/nuttx/fs/automount.h``.
+ The lower half interface provides: (1) mount information including file
+ system type, block driver path, and mount point path, (2) mount and unmount
+ retry delays, and (3) and callbacks to attach to and management the media
+ insertion / removal interrupts.
+
+Example Implementation
+======================
+
+There is an example implementation of this lower half interface at
+``boards/arm/sama5/sama5d4-ek/src/sam_automount.c``. The ``boards/arm/sama5/sama5d4-ek/Kconfig``
+as the board-specific configuration for the auto-mounter. You can see
+the configuration settings in the ``boards/arm/sama5/sama5d4-ek/configs/nsh/defconfig``
+and ``boards/arm/sama5/sama5d4-ek/configs/nxwm/defconfig`` configuration files::
+
+ CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT=y
+ CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_FSTYPE="vfat"
+ CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_BLKDEV="/dev/mmcsd0"
+ CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_MOUNTPOINT="/mnt/sdcard"
+ CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_DDELAY=1000
+ CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_UDELAY=2000
+
+These setting determine the values in the lower half interface. The interrupt is
+provided by a PIO pin defined in ``boards/arm/sama5/sama5d4-ek/src/sama5e4-ek.h`` and
+the implementation of the interface and callbacks is in
+``boards/arm/sama5/sama5d4-ek/src/sam_automount.c``.
+
+
diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
index 34e12f375d..ebc074bfd9 100644
--- a/Documentation/guides/index.rst
+++ b/Documentation/guides/index.rst
@@ -25,3 +25,4 @@ Guides
gdbwithpython.rst
ofloader.rst
testingtcpip.rst
+ automounter.rst
(nuttx) 03/07: Documentation: add SystemView configuration instructions
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 1f9e17f5c7eff4d28dc19f0b56c5256ae06f0e5b
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 14:11:57 2023 +0100
Documentation: add SystemView configuration instructions
---
.../components/drivers/special/segger.rst | 62 ++++++++++++++++++++--
1 file changed, 58 insertions(+), 4 deletions(-)
diff --git a/Documentation/components/drivers/special/segger.rst b/Documentation/components/drivers/special/segger.rst
index 37835720ee..29097de3b8 100644
--- a/Documentation/components/drivers/special/segger.rst
+++ b/Documentation/components/drivers/special/segger.rst
@@ -2,9 +2,63 @@
Segger RTT drivers
==================
+.. note:: Segger drivers works only with J-Link debug probes.
+ Sometimes it's possible to replace vendor-specific debug interface
+ with J-Link OB firmware. For details look at
+ `Segger website <https://www.segger.com/downloads/jlink>`_
+
Supported Segger drivers:
-- serial over RTT - ``CONFIG_SERIAL_RTTx``,
-- console over RTT - ``CONFIG_SERIAL_RTT_CONSOLE_CHANNEL``
-- Segger SystemView - ``CONFIG_SEGGER_SYSVIEW``
-- Note RTT - ``CONFIG_NOTE_RTT``
+* Serial over RTT - ``CONFIG_SERIAL_RTTx``,
+* Console over RTT - ``CONFIG_SERIAL_RTT_CONSOLE_CHANNEL``
+* Segger SystemView - ``CONFIG_SEGGER_SYSVIEW``
+* Note RTT - ``CONFIG_NOTE_RTT``
+
+Segger SystemView
+=================
+
+Steps to enable SystemView support:
+
+#. Make sure your architecture supports a high-performance counter.
+ In most cases it will be:
+
+ :menuselection:`CONFIG_ARCH_PERF_EVENTS=y`
+
+ In that case, the the architecture logic must initialize the perf counter
+ with ``up_perf_init()``.
+
+#. Enable instrumentation support:
+
+ :menuselection:`CONFIG_SCHED_INSTRUMENTATION=y`
+
+#. Configure instrumentation support. Available options for SystemView are:
+
+ :menuselection:`CONFIG_SCHED_INSTRUMENTATION_SWITCH=y`
+
+ :menuselection:`CONFIG_SCHED_INSTRUMENTATION_SYSCALL=y`
+
+ :menuselection:`CONFIG_SCHED_INSTRUMENTATION_IRQHANDLER=y`
+
+#. Make sure that ``CONFIG_TASK_NAME_SIZE > 0``, otherwise task/thread
+ names will not be displayed correctly
+
+#. Enable Note Driver support and disable Note RAM driver:
+
+ :menuselection:`CONFIG_DRIVERS_NOTE=y`
+
+ :menuselection:`CONFIG_DRIVERS_NOTERAM=n`
+
+#. Enable Note RTT and Segger SystemView support:
+
+ :menuselection:`CONFIG_NOTE_RTT=y`
+
+ :menuselection:`CONFIG_SEGGER_SYSVIEW=y`
+
+#. Configure RTT channel and RTT buffer size for SystemView:
+
+ :menuselection:`CONFIG_SEGGER_SYSVIEW_RTT_CHANNEL=0`
+
+ :menuselection:`CONFIG_SEGGER_SYSVIEW_RTT_BUFFER_SIZE=1024`
+
+ In case SystemView returns buffer overflow errors, you should increase
+ ``CONFIG_NOTE_RTT_BUFFER_SIZE_UP``.
(nuttx) 06/07: Documentation: migrate "Work Queue Deadlocks" from wiki
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 1c6e5cc0c47be99bd34cf23afed755b9ab2fe566
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 15:40:38 2023 +0100
Documentation: migrate "Work Queue Deadlocks" from wiki
link: https://cwiki.apache.org/confluence/display/NUTTX/Work+Queue+Deadlocks
---
Documentation/components/net/index.rst | 1 +
Documentation/components/net/wqueuedeadlocks.rst | 174 +++++++++++++++++++++++
2 files changed, 175 insertions(+)
diff --git a/Documentation/components/net/index.rst b/Documentation/components/net/index.rst
index c9bf369964..7573e02b09 100644
--- a/Documentation/components/net/index.rst
+++ b/Documentation/components/net/index.rst
@@ -9,6 +9,7 @@ Network Support
socketcan.rst
netguardsize.rst
slip.rst
+ wqueuedeadlocks.rst
``net`` Directory Structure ::
diff --git a/Documentation/components/net/wqueuedeadlocks.rst b/Documentation/components/net/wqueuedeadlocks.rst
new file mode 100644
index 0000000000..4f274d3dea
--- /dev/null
+++ b/Documentation/components/net/wqueuedeadlocks.rst
@@ -0,0 +1,174 @@
+====================
+Work Queue Deadlocks
+====================
+
+Use of Work Queues
+==================
+
+Most network drivers use a work queue to handle network events. This is done for
+two reason: (1) Most of the example code to leverage from does it that way, and (2)
+it is easier and is a more efficient use memory resources to use the work queue
+rather than creating a dedicated task/thread to service the network.
+
+High and Low Priority Work Queues
+=================================
+
+There are two work queues: A single, high priority work queue that is intended
+only to service the back end interrupt processing in a semi-normal, tasking
+context. And low priority work queue(s) that are similar but as then name implies
+are lower in priority and not dedicated for time-critical back end interrupt
+processing.
+
+Downsides of Work Queues
+========================
+
+There are two important downsides to the use of work queues. First, the work queues
+are inherently non-deterministic. The time delay from the point at which you
+schedule work and the time at which the work is performed in highly random and
+that delay is due not only to the strict priority scheduling but also to what
+work as been queued ahead of you.
+
+Why do you bother to use an RTOS if you rely on non-deterministic work queues to do
+most of the work?
+
+A second problem is related: Only one work queue job can be performed at a time.
+That job should be brief so that it can make the work queue available again for
+the next work queue job as soon as possible. And that job should never block
+waiting for resources! If the job blocks, then it blocks the entire work queue
+and makes the whole work queue unavailable for the duration of the wait.
+
+Networking on Work Queues
+=========================
+
+As mentioned, most network drivers use a work queue to handle network events.
+(some are even configurable to use high priority work queue... YIKES!). Most
+network operations are not really suited for execution on a work queue: The
+networking operations can be quite extended and also can block waiting for for
+the availability of resources. So, at a minimum, networking should never use
+the high priority work queue.
+
+Deadlocks
+=========
+
+If there is only a single instance of a work queue, then it is easy to create a
+deadlock on the work queue if a work job blocks on the work queue. Here is the
+generic work queue deadlock scenario:
+
+* A job runs on a work queue and waits for the availability of a resource.
+* The operation that provides that resource also runs on the same work queue.
+* But since the work queue is blocked waiting for the resource, the job that
+ provides the resource cannot run and a deadlock results.
+
+IOBs
+====
+
+IOBs (I/O Blocks) are small I/O buffers that can be linked together in chains to
+efficiently buffer variable sized network packet data. This is a much more
+efficient use of buffering space than full packet buffers since the packets
+content is often much smaller than the full packet size (the MSS).
+
+The network allocates IOBs to support TCP and UDP read-ahead buffering and write
+buffering. Read-head buffering is used when TCP/UDP data is received and there is
+no receiver in place waiting to accept the data. In this case, the received
+payload is buffered in the IOB-based, read-ahead buffers. When the application
+next calls ``revc()`` or ``recvfrom()``, the date will be removed from the read-ahead
+buffer and returned to the caller immediately.
+
+Write-buffering refers to the similar feature on the outgoing side. When application
+calls ``send()`` or ``sendto()`` and the driver is not available to accept the new packet
+data, then data is buffered in IOBs in the write buffer chain. When the network
+driver is finally available to take more data, then packet data is removed from
+the write-buffer and provided to the driver.
+
+The IOBs are allocated with a fixed size. A fixed number of IOBs are pre-allocated
+when the system starts. If the network runs out of IOBs, additional IOBs will not
+be allocated dynamically, rather, the IOB allocator, ``iob_alloc()`` will block waiting
+until an IOB is finally returned to pool of free IOBs. There is also a non-blocking
+IOB allocator, ``iob_tryalloc()``.
+
+Under conditions of high utilization, such as sending large amount of data at high
+rates or receiving large amounts of data at high rates, it is inevitable that the
+system will run out of pre-allocated IOBs. For read-ahead buffering, the packets
+are simply dropped in this case. For TCP this means that there will be a subsequent
+timeout on the remote peer because no ACK will be received and the remote peer will
+eventually re-transmit the packet. UDP is a lossy transfer and handling of lost or
+dropped datagrams must be included in any UDP design.
+
+For write-buffering, there are three possible behaviors that can occur when the
+IOB pool has been exhausted: First, if there are no available IOBs at the beginning
+of a ``send()`` or ``sendto()`` transfer, then the operation will block until IOBs are again
+available if ``O_NONBLOCK`` is not selected. This delay can can be a substantial amount
+of time.
+
+Second, if ``O_NONBLOCK`` is selected, the send will, of course, return immediatly,
+failing with errno set ``EAGAIN`` if we cannot allocate the first IOB for the transfer.
+
+The third behavior occurs if the we run out of IOBs in the middle of the transfer.
+Then the send operation will not wait but will instead send then number of bytes that
+it has successfully buffered. Applications should always check the return value from
+``send()`` or ``sendto()``. If it a is a byte count less then the requested transfer
+size, then the send function should be called again.
+
+The blocking iob_alloc() call is also the a common cause of work queue deadlocks.
+The scenario again is:
+
+* Some logic in the OS runs on a work queue and blocks waiting for an IOB to
+ become available,
+* The logic that releases the IOB also runs on the same work queue, but
+* That logic that provides the IOB cannot execute, however, because the other job
+ is blocked waiting for the IOB on the same work queue.
+
+Alternatives to Work Queues
+===========================
+
+To avoid network deadlocks here is the rule: Never run the network on a singleton
+work queue!
+
+Most network implementation do just that! Here are a couple of alternatives:
+
+#. Use Multiple Low Priority Work Queues
+ Unlike the high priority work queues, the low priority work queues utilize a
+ thread pool. The number of threads in the pool is controlled by the
+ ``CONFIG_SCHED_LPNTHREADS``. If ``CONFIG_SCHED_LPNTHREADS`` is greater than one,
+ then such deadlocks should not be possible: In that case, if a thread is busy with
+ some other job (even if it is only waiting for a resource), then the job will be
+ assigned to a different thread and the deadlock will be broken. The cost of the
+ additional low priority work queue thread is primarily the memory set aside for
+ the thread's stack.
+
+#. Use a Dedicated Network Thread
+ The best solution would be to write a custom kernel thread to handle driver
+ network operations. This would be the highest performing and the most manageable.
+ It would also, however, but substantially more work.
+
+#. Interactions with Network Locks
+ The network lock is a re-entrant mutex that enforces mutually exclusive access to
+ the network. The network lock can also cause deadlocks and can also interact with
+ the work queues to degrade performance. Consider this scenario:
+
+ * Some network logic, perhaps running on on the application thread, takes the network
+ lock then waits for an IOB to become available (on the application thread, not a
+ work queue).
+ * Some network related event runs on the work queue but is blocked waiting for
+ the network lock.
+ * Another job is queued behind that network job. This is the one that provides the
+ IOB, but it cannot run because the other thread is blocked waiting for the network
+ lock on the work queue.
+
+ But the network will not be unlocked because the application logic holds the network
+ lock and is waiting for the IOB which can never be released.
+
+ Within the network, this deadlock condition is avoided using a special function
+ ``net_ioballoc()``. ``net_ioballoc()`` is a wrapper around the blocking ``iob_alloc()``
+ that momentarily releases the network lock while waiting for the IOB to become available.
+
+ Similarly, the network functions ``net_lockedait()`` and ``net_timedait()`` are wrappers
+ around ``nxsem_wait()`` ``nxsem_timedwait()``, respectively, and also release the network
+ lock for the duration of the wait.
+
+ Caution should be used with any of these wrapper functions. Because the network lock is
+ relinquished during the wait, there could changes in the network state that occur before
+ the lock is recovered. Your design should account for this possibility.
+
+
+
(nuttx) 01/07: Documentation: migrate "NxTerm Example" from wiki
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 200f709092beb94a239a1df8e5c45a486fc52470
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 10:56:55 2023 +0100
Documentation: migrate "NxTerm Example" from wiki
link: https://cwiki.apache.org/confluence/display/NUTTX/NxTerm+Example
---
.../applications/examples/nxterm/index.rst | 174 +++++++++++++++++++++
.../applications/examples/nxterm/nxtermexample.png | Bin 0 -> 15366 bytes
2 files changed, 174 insertions(+)
diff --git a/Documentation/applications/examples/nxterm/index.rst b/Documentation/applications/examples/nxterm/index.rst
index 5deb2d749f..de3744d99a 100644
--- a/Documentation/applications/examples/nxterm/index.rst
+++ b/Documentation/applications/examples/nxterm/index.rst
@@ -2,6 +2,9 @@
``nxterm`` Display NuttShell (NSH) as NX Console
================================================
+.. figure:: nxtermexample.png
+ :align: center
+
This directory contains yet another version of the NuttShell (NSH). This version
uses the NX console device defined in ``include/nuttx/nx/nxterm.h`` for output.
the result is that the NSH input still come from the standard console input
@@ -45,3 +48,174 @@ The following configuration options can be selected to customize the test:
- ``CONFIG_EXAMPLES_NXTERM_SERVERPRIO`` – The server priority. Default: ``120``.
- ``CONFIG_EXAMPLES_NXTERM_LISTENERPRIO`` – The priority of the event listener
thread. Default: ``80``.
+
+Initialization
+==============
+
+NX Server
+---------
+
+The NxTerm example initializes the NX Server through the following steps:
+
+* Calls ``boardctl(BOARDIOC_NX_START, 0)`` to start the NX server, then
+* Calls ``nx_connect()`` to connect to the NX server.
+* It also creates a separate thread at entry ``nxterm_listener()`` to listen for
+ NX server events.
+
+Window Creation
+---------------
+
+The Nxterm Example then initializes the Windows:
+
+* Calls ``nxtk_openwindow()`` to create a bordered window,
+* Calls ``nxtk_setposition()`` and ``nxtk_setsize()`` to position the window in
+ the display,
+* Calls ``nxtk_opentoolbar()`` to create a toolbar sub-window on the main window
+ (This toolbar window is not used by the example, it is just for illustration).
+
+A more practical use case for, say, a handheld device with a single NxTerm display
+would be to use the background window. The background is a window like any other
+with these special properties: It cannot be moved; it is always positioned at (0,0).
+It cannot be resized; it is always the full size of the display. And it cannot be
+raised, it is always the lowest windows in the z-axis.
+
+NxTerm Driver
+-------------
+
+And binds the Nxterm driver to the permit drawing in the window. This is done when it:
+
+* Calls ``boardctl(BOARDIOC_NXTERM, (uintptr_t)&nxcreate)``
+
+Console Task
+------------
+
+Finally, it sets up the NxTerm and starts the console task:
+
+* Opens the NxTerm driver,
+* It then re-directs stdout and stderr to the NxTerm driver. This will cause all
+ standard output to be rendered into the main windows, and
+* It then starts a separate console daemon that inherits the re-directed output
+ and exits.
+
+Character I/O
+=============
+
+Normal Keyboard Input
+---------------------
+
+Keyboard and mouse inputs are received by the application through window callbacks,
+just like with the Xorg X server. Some listener needs to inject the keyboard input
+via ``nx_kbdin()`` (``libs/libnx/nx_kbdin.c``) which sends a message containing the
+keyboard input to the NX server. The NX server will forward that keyboard input to
+the window that has focus.
+
+The Window application listens for NX server events by calling ``nx_eventhandler()``
+(``libs/libnx/nx_eventhandler``) on another listener thread. If the window has
+focus when the key press is entered, ``nx_eventhandler()`` will forward the key
+press information to the registered window event handler.
+
+In ``apps/examples/nxterm``, ``nxterm_listener.c`` is the thread that drives
+``nx_eventhandler()``. The window NX keyboard callback is the function ``nxwndo_kbdin()``
+in ``nxterm_wndo.c``. That callback function is just a stub that writes the keyboard
+data to stdout. It is a stub because keyboard input is not received from the NxTerm
+in this example.
+
+The apps/examples/nxterm/ Kludge
+--------------------------------
+
+``apps/examples/nxterm`` does not do things in the normal way. NSH does not receive
+keyboard input from NX; it gets keyboard input directly from the default stdin which
+is probably not a keyboard at all but more likely the host PC serial console. This is
+okay because only a single window is used and that example does not need the help of
+NX to select the window that has focus.
+
+Re-direction of stdout and stderr
+---------------------------------
+
+stdin in and stderr are re-directed to the NxTerm character driver in ``nxterm_main.c``
+just before starting the console task. That logic looks like this:
+
+.. code-block:: C
+
+ /* Now re-direct stdout and stderr so that they use the NX console driver.
+ * Note that stdin is retained (file descriptor 0, probably the serial
+ * console).
+ */
+
+ printf("nxterm_main: Starting the console task\n");
+
+ fflush(stdout);
+ fflush(stderr);
+
+ fclose(stdout);
+ fclose(stderr);
+
+ dup2(fd, 1);
+ dup2(fd, 2);
+
+Note that stdin is not re-directed in this example! This means that keyboard
+input does not come from the NxTerm driver but, rather, from whatever input
+device was previously configured for stdin, often a serial console.
+
+There is a configuration option that determines if NxTerm receives keyboard
+input or not: ``CONFIG_NXTERM_NXKBDIN``, For this NxTerm example, that option can be disabled.
+
+What Is BOARDIOC_NXTERM_IOCTL and Where Is It Used?
+---------------------------------------------------
+
+The ``boardctl()`` command ``BOARDIOC_NXTERM_IOCTL`` allows an application to
+inject keyboard data into NX for forwarding to the window with focus.
+In ``apps/examples/nxterm``, the ``BOARDIOC_NXTERM_IOCTL`` is only called for the
+case of a redraw event. A redraw event may happen when a window above the current
+window is moved and the text is exposed.
+
+If you use only a single window for the NxTerm example, then that window will
+always have focus. It will always have focus and will never be redrawn and the
+``BOARDIOC_NXTERM_IOCTL`` will never be used (Unless, perhaps, you choose to implement
+pop-up error messages or menus on top of the NxTerm window).
+
+Redraw callbacks will not be received even in a multi-window configuration if you
+use per-window frame buffers, either. In that case, the system will automatically
+redraw windows as needed using the per-window frame buffer shadow memory. This is
+controlled by the option ``CONFIG_NX_RAMBACKED``. This option is recommended for
+performance reasons if you have sufficient memory to support it.
+
+Character Data Flow: Keyboard to Display
+=========================================
+
+Character Data Flow in apps/examples/nxterm
+-------------------------------------------
+
+* Character input driver receives input
+* NSH receives input on stdin and processes it (stdin is not redirected)
+* Data is output to stdout (redirected to the NxTerm driver)
+
+In this simple, single-window case, ``BOARDIOC_NXTERM_IOCTL`` will never be used.
+
+Character Data Flow in the Generic Window Case
+----------------------------------------------
+
+See, for an example, ``apps/graphics/nxwm/src/cnxterm.cxx``. In this case, the
+behavior will change, depending on the selection of ``CONFIG_NXTERM_NXKBDIN``:
+If ``CONFIG_NXTERM_NXKBDIN`` is not selected, then the behavior will be similar
+to ``apps/examples/nxterm``; stdin will not be redirected an keyboard input will
+come directly from the the system console.
+
+But is ``CONFIG_NXTERM_NXKBDIN`` is select, NSH's stdin will be re-redirected to
+the to the NxTerm character driver. Keyboard input will arrive on stdin from the
+NxTerm driver rather than from the system console. The following sequence describes
+the keyboard input in this latter case:
+
+* Character input driver receives input,
+* Some keyboard listener thread receives input and injects it into NX via
+ a call to ``nx_kbdin()``,
+* NX sends an event to the registered ``kbdin()`` method of the window that has
+ focus, providing the keyboard input to the window application. In this case,
+ the window application of interest is the window bound to the NxTerm character
+ driver by the application. The ``kbin()`` callback provides the focused keyboard
+ input to the NxTerm driver via ``boardctl(BOARDIOC_NXTERM_IOCTL, (uintptr_t)&iocargs)``,
+* The NxTerm character driver receives keyboard data, buffers it, and provides
+ that keyboard input for the next read operation,
+* NSH receives input on stdin which was re-directed to the NxTerm character driver.
+ NSH processes the input, and
+* ,NSH outputs data to stdout which was re-directed to the NxTerm character driver.
diff --git a/Documentation/applications/examples/nxterm/nxtermexample.png b/Documentation/applications/examples/nxterm/nxtermexample.png
new file mode 100644
index 0000000000..2233548879
Binary files /dev/null and b/Documentation/applications/examples/nxterm/nxtermexample.png differ
(nuttx) 05/07: Documentation: migrate "SLIP Configuration" from wiki
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 2d8c4e6645ed494231b4f4a6ce586ffc74ff81a7
Author: raiden00pl <ra...@railab.me>
AuthorDate: Mon Nov 6 15:00:36 2023 +0100
Documentation: migrate "SLIP Configuration" from wiki
link: https://cwiki.apache.org/confluence/display/NUTTX/SLIP+Configuration
---
Documentation/components/net/index.rst | 1 +
Documentation/components/net/slip.rst | 50 ++++++++++++++++++++++++++++++++++
2 files changed, 51 insertions(+)
diff --git a/Documentation/components/net/index.rst b/Documentation/components/net/index.rst
index 3a31a492b6..c9bf369964 100644
--- a/Documentation/components/net/index.rst
+++ b/Documentation/components/net/index.rst
@@ -8,6 +8,7 @@ Network Support
sixlowpan.rst
socketcan.rst
netguardsize.rst
+ slip.rst
``net`` Directory Structure ::
diff --git a/Documentation/components/net/slip.rst b/Documentation/components/net/slip.rst
new file mode 100644
index 0000000000..41b7252f9c
--- /dev/null
+++ b/Documentation/components/net/slip.rst
@@ -0,0 +1,50 @@
+====
+SLIP
+====
+
+SLIP Configuration
+==================
+
+#. Configure and build NuttX with SLIP enabled in the configuration. Load this
+ into FLASH and start the device.
+
+#. Connect to a Linux box using a serial cable. This dicussion assumes that the
+ serial device is ``/dev/ttyS0`` on both the target and the Linux box.
+
+#. Reset on the target side and attach SLIP on the Linux side:
+
+ .. code-block:: bash
+
+ $ modprobe slip
+ $ slattach -L -p slip -s 57600 /dev/ttyS0 &
+
+ This should create an interface with a name like sl0, or sl1, etc. Add -d to
+ get debug output. This will show the interface name.
+
+ NOTE: The -L option is included to suppress use of hardware flow control.
+ This is necessary only if you are not supporting hardware flow control on
+ the target.
+
+ NOTE: The Linux slip module hard-codes its MTU size to 296. So you might
+ as well set ``CONFIG_NET_ETH_MTU`` to 296 as well.
+
+#. After turning over the line to the SLIP driver, you must configure the
+ network interface. Again, you do this using the standard ifconfig and
+ route commands. Assume that we have connected to a host PC with address
+ 192.168.0.101 from your target with address 10.0.0.2. On the Linux PC
+ you would execute the following as root (assuming the SLIP is attached
+ to device sl0):
+
+ .. code-block:: bash
+
+ $ ifconfig sl0 10.0.0.1 pointopoint 10.0.0.2 up
+ $ route add 10.0.0.2 dev sl0
+
+#. For monitoring/debugging traffic:
+
+ .. code-block:: bash
+
+ $ tcpdump -n -nn -i sl0 -x -X -s 1500
+
+ NOTE: If hardware handshake is not available, then you might try the
+ slattach option-L which is supposed to enable "3-wire operation."