Merge remote-tracking branch 'upstream/master'

Author: keever50

Documentation/applications/benchmarks/cyclictest/index.rst

@@ -0,0 +1,110 @@
+================================
+``Cyclictest`` benchmark utility
+================================
+
+Cyclictest is a simple program used to measure the real-time capabilities
+of a RTOS. Originally, this program comes from the Linux ``rt-tests``.
+However, NuttX features its own cyclictest utility which is heavily inspired
+by the original program but does not use some advanced features, while adding
+features that are NuttX related.
+
+The creation of the new cyclictest arose from the fact that as of February
+2025, POSIX time functions (such as ``clock_gettime`` and ``clock_nanosleep``)
+depend on the systemtick (if the system is not compiled in the Tickless mode)
+which makes small delays practically impossible. However, if we utilize
+a hardware device timer, small periodic delays can be achieved with some ``ioctl``
+calls.
+
+The documentation needs to be revisited to see how cyclictest performs
+when NuttX is compiled in tickless mode.
+
+Replacement for ``clock_gettime`` and ``clock_nanosleep`` in NuttX
+------------------------------------------------------------------
+
+Configuring such device timer is simple: firstly, the timer's timeout is set using
+the ``TCIOC_SETTIMEOUT`` ``ioctl`` call. Then the ``TCIOC_NOTIFICATION`` ``ioctl`` call
+is performed. Afterwards, the timer can be polled using the ``poll`` function
+which returns when the timer timeouts.
+
+The thread latency wakeup can be measured using this timer by calling
+``TCIOC_GETSTATUS`` ``ioctl`` call after the ``poll`` function has returned.
+The ``ioctl`` call fills the ``timer_status_s`` struct which contains two important
+fields: ``uint32_t timeleft`` and ``uint32_t timeout``. The latency of the thread can
+then be calculated  as ``timeout - timeleft``.
+
+Usage of this program
+---------------------
+
+Despite some differences, the NuttX port stays as faithful as possible to the original
+program, keeping the most important command-line parameters the same.
+The user can choose one of two "waiting methods":
+
+- ``clock_nanosleep`` (``W_NANOSLEEP``),
+- polling the device (``W_DEVTIMER``). 
+
+The user can also choose one of two "measuring methods":
+
+- ``clock_gettime`` (``M_GETTIME``),
+- utilizing the device timer (``M_TIMER_API``).
+  
+It is possible to combine the waiting and measuring methods. As of February 2025,
+using ``W_DEVTIMER`` and ``M_TIMER_API`` produces the best results.
+However, it requires a timer device to be registered by your BSP (such as ``/dev/timer1``).
+Be also advised that when ``W_DEVTIMER`` is used, only one thread can poll the timer.
+
+Following command-line parameters can be supplied:
+
+- ``-c --clock [CLOCK]``: 0 selects ``CLOCK_REALTIME``, 1 selects ``CLOCK_MONOTONIC`` (default)
+- ``-d --distance [US]``: The distance of thread intervals. Default is 500 us.
+- ``-D --duration [TIME]``: Set the test duration in seconds. Default is 0 (endless).
+- ``-e --help``: Displays help and exits.
+- ``-h --histogram [US]``: Output the histogram data to stdout. US is the maximum value to be printed.
+- ``-H --histofall``: Same as ``-h`` except that an additional histogram column is displayed at the right that contains summary data of all thread histograms. If cyclictest runs a single thread only, the ``-H`` option is equivalent to ``-h``.
+- ``-i --interval [US]``: The thread interval. Default is 1000 us.
+- ``-l --loops [N]``: The number of measurement loops. Default is 0 (endless).
+- ``-m --measurement [METHODS]``: Sets the time measurement method. 0 selects ``clock_gettime``, 1 uses the NuttX timer API. Be advised that if 1 is selected, you need to specify a timer device (e.g. ``/dev/timer0``) in ``-T``.
+- ``-n --nanosleep [METHOD]``: Sets the waiting method: 0 selects ``clock_nanosleep``, 1 waits for the POLLIN flag on a timer device. Default is 0. Choosing 1 works only with one thread, the ``-t`` value is therefore set to 1. If METHOD 1 is selected, you need to specify a timer device (e.g. ``/dev/timer0``) in ``-T``.
+- ``-p --prio``: Sets the priority of the first thread.
+- ``-t --threads [N]``: The number of test threads to be created. Default is 1.
+- ``-T --timer-device [DEV]``: The measuring timer device. Must be specified when ``-m=1`` or ``-n=1``.
+- ``-y --policy [NAME]``: Set the scheduler policy, where NAME is fifo, rr, batch, idle, normal, other.
+
+Example usage
+-------------
+``cyclictest -p 150 -T /dev/timer1 -m 1 -n 1 -h 20 -D 100 -i 50``
+
+Since ``W_DEVTIMER`` is used, only one thread runs every 50 us.
+The measurement method is the device timer itself, specified in ``-T``.
+The test runs for 100 seconds. The priority is boosted to 150, so the
+measurement is not affected by other tasks or communication.
+
+Output of the command (tested on Microchip ATSAMV71Q21B @ 300 MHz):
+
+.. code-block:: text
+
+  # Histogram
+  000000 000000
+  000001 000000
+  000002 000000
+  000003 000000
+  000004 000000
+  000005 000000
+  000006 000000
+  000007 000000
+  000008 000000
+  000009 000000
+  000010 603045
+  000011 1395782
+  000012 000804
+  000013 000153
+  000014 000034
+  000015 000083
+  000016 000030
+  000017 000000
+  000018 000000
+  000019 000000
+  # Total: 001999931
+  # Min Latencies: 00010
+  # Avg Latencies: 00010
+  # Max Latencies: 00016
+  # Histogram Overflows: 00000

Documentation/applications/games/brickmatch/index.rst

@@ -3,7 +3,8 @@
 =========================
 
 Brickmatch is a kind puzzle game like a mix between tetris and Candy
-Crush. It is a 6x6 matrix with blocks (cells) with different colors.
+Crush. It is matrix (e.g 6x6, 8x8) with blocks (cells) with different
+colors.
 
 Your goal is to move the blocks of the board to unite three or
 more with the same color.
@@ -26,7 +27,8 @@ matrix to the right SPI pins (look your board configuration) and the
 APDS9960 to the I2C port (also connect its INT pin).
 
 If you don't have an APA102 matrix you can also play it using an LCD
-display and a digital joystick (DJOYSTICK) or the console input. 
+display or led matrix(WS2812) and a digital joystick (DJOYSTICK), gpio pins
+or the console input.
 
 Then you can configure and compile the game to play in your board,
 i.e. for ESP32-Devkitc there is already an example using the APA102::

Documentation/applications/interpreters/python/index.rst

@@ -18,10 +18,10 @@ How Does it Work?
 
 1. Python for NuttX target initially the ``rv-virt`` (RISC-V QEMU) board.
 2. Python modules are stored in `pyc <https://docs.python.org/3/glossary.html#term-bytecode>`_ (byte-code format) and are loaded from a ROMFS image at startup.
-3. Environment variables like ``PYTHONHOME`` and ``PYTHON_BASIC_REPL`` need to be set accordingly.
+3. The Python wrapper application on NuttX mounts the ROMFS partition which contains the Python modules and sets the required environment variables (``PYTHONHOME`` and ``PYTHON_BASIC_REPL``) automatically.
 
-Building Python NuttX
-=====================
+Building Python on NuttX
+========================
 
 Use the ``rv-virt:python`` config to build Python for NuttX. Note that the CMake scripts don't work for this configuration. For now, please use the makefile build instead:
 
@@ -66,10 +66,6 @@ Then, run RISC-V QEMU with the following command:
    telnetd [4:100]
 
    NuttShell (NSH) NuttX-10.4.0
-   nsh> python_mount_modules
-   Mounting ROMFS filesystem at target=/usr/local/lib/ with source=/dev/ram1
-   nsh> export PYTHONHOME /usr/local
-   nsh> export PYTHON_BASIC_REPL 1
    nsh> python
    Python 3.13.0 (main, Dec  4 2024, 17:00:42) [GCC 13.2.0] on nuttx
    Type "help", "copyright", "credits" or "license" for more information.

Documentation/components/drivers/character/index.rst

@@ -77,3 +77,4 @@ Character device drivers have these properties:
   serial.rst
   timers/index.rst
   touchscreen.rst
+  wireless/index.rst

Documentation/components/drivers/character/serial.rst

@@ -43,3 +43,8 @@ Serial Device Drivers
    ``arch/arm/src/lpc214x/lpc214x_serial.c``,
    ``arch/z16/src/z16f/z16f_serial.c``, etc.
 
+Serial Error Reporting
+----------------------
+
+It is possible to check if there are some frame, parity, overrun, break, or
+other error using the ioctl TIOCGICOUNT just like on Linux.

Documentation/components/drivers/character/timers/pwm.rst

@@ -182,6 +182,24 @@ of PWM channels should be set before this operation.
 
 The ``PWMIOC_STOPS`` command stops the pulsed output.
 
+.. c:macro:: PWMIOC_FAULTS_FETCH_AND_CLEAR
+
+The ``PWMIOC_FAULTS_FETCH_AND_CLEAR`` command clears fault inputs. Some
+faults can be latched (remain active even if the source is not active
+anymore) and have to be cleared from the software. This provides an option
+to clear faults from the application and re-enable PWM output. It can be
+also used to fetch the current faults.
+
+The call takes a pointer to ``unsigned long`` variable as an argument, a
+bitmask defining which faults are to be cleared. The driver clears these
+faults and fills the argument with the active faults prior to this clear.
+Having the argument variable equal to zero will result in no faults cleared
+but the user will get the currently active faults. If NULL is passed as
+an argument, then all currently set faults are cleared and fetch is not
+performed.
+
+This may not be supported by all drivers.
+
 Application Example
 ~~~~~~~~~~~~~~~~~~~
 

Documentation/components/drivers/character/wireless/index.rst

@@ -0,0 +1,8 @@
+==========================
+Wireless character drivers
+==========================
+
+.. toctree::
+  :maxdepth: 1
+
+  lpwan/index.rst

Documentation/components/drivers/character/wireless/lpwan/SX1262.jpg

@@ -0,0 +1,9 @@
+=====
+LPWAN
+=====
+
+.. toctree::
+  :maxdepth: 1
+
+  sx126x.rst
+