(nuttx) 03/03: Documentation/examples: Add pages for sandbox and pffault.

[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 a624bf27f7b1dc40fb7f6dfb2b1b33c5ca1f01a9
Author: Marco Casaroli <ma...@gmail.com>
AuthorDate: Sat Oct 17 20:25:46 2026 +0200

    Documentation/examples: Add pages for sandbox and pffault.
    
    apps/examples/sandbox and apps/examples/pffault test that a protected
    or kernel build terminates a user process that makes a forbidden
    access, and that the rest of the system keeps running. The examples
    had no documentation pages.
    
    Add a page for each: the usage, the targets and checks of sandbox, and
    the configuration options.
    
    Assisted-by: Claude Code:claude-opus-5-5
    Signed-off-by: Marco Casaroli <ma...@gmail.com>
---
 .../applications/examples/pffault/index.rst        | 27 +++++++++
 .../applications/examples/sandbox/index.rst        | 65 ++++++++++++++++++++++
 2 files changed, 92 insertions(+)

diff --git a/Documentation/applications/examples/pffault/index.rst b/Documentation/applications/examples/pffault/index.rst
new file mode 100644
index 00000000000..ee0039966a0
--- /dev/null
+++ b/Documentation/applications/examples/pffault/index.rst
@@ -0,0 +1,27 @@
+=================================
+``pffault`` User-Space Fault Test
+=================================
+
+``pffault`` makes one access to a kernel address from a user task. In a
+protected or kernel build, the access must fault, the kernel must terminate
+only this task, and the shell must keep running. ``pffault`` prints the
+access before it makes it. If the access returns, ``pffault`` prints that,
+and the build did not stop it. For a test with a control target and
+resource checks, see :doc:`../sandbox/index`.
+
+Usage::
+
+  pffault [r|w] [<address>]
+
+``w`` writes the address; any other first argument reads it. To give an
+address, give the first argument too. The default address is
+``0x3fc98000``, the base of the kernel DRAM of the ESP32-S3. Give an address
+for other chips.
+
+Configuration
+=============
+
+- ``CONFIG_EXAMPLES_PFFAULT`` -- Enable the test.
+- ``CONFIG_EXAMPLES_PFFAULT_PROGNAME``, ``CONFIG_EXAMPLES_PFFAULT_PRIORITY``
+  and ``CONFIG_EXAMPLES_PFFAULT_STACKSIZE`` -- Program name, priority and
+  stack size.
diff --git a/Documentation/applications/examples/sandbox/index.rst b/Documentation/applications/examples/sandbox/index.rst
new file mode 100644
index 00000000000..890126a9ef1
--- /dev/null
+++ b/Documentation/applications/examples/sandbox/index.rst
@@ -0,0 +1,65 @@
+============================================
+``sandbox`` Protected-Build Containment Test
+============================================
+
+``sandbox`` checks that a protected build or a kernel build contains a user
+process that makes a forbidden access: the process is terminated, and the
+rest of the system keeps running. Each target has the result that it
+expects, so the test fails a build that refuses all accesses and a build
+that permits all accesses.
+
+Usage::
+
+  sandbox [r|w] [target ...]
+
+``r`` (the default) reads the target and ``w`` writes it. With no target,
+the four named targets run:
+
+=============  ===========================  ============
+Target         Address                      Expected
+=============  ===========================  ============
+``self``       data of the process          must succeed
+``kernel``     kernel memory                must fault
+``periph``     a peripheral register        must fault
+``unmapped``   an address with no mapping   must fault
+``0x...``      a literal address            must fault
+=============  ===========================  ============
+
+``self`` is the control. Without it, a build that refuses every access
+passes all other checks. A target with no address in the configuration is
+reported and not run.
+
+For each target, ``sandbox`` starts itself again with ``posix_spawn()`` as
+a separate process, which makes the access. Before the access, that process
+allocates ``CONFIG_EXAMPLES_SANDBOX_ALLOC`` bytes, writes all of them, and
+opens a file. ``sandbox`` then checks that:
+
+- the process is terminated (or, for ``self``, exits normally),
+- another thread of ``sandbox`` kept running,
+- the memory in use, read from ``/proc/meminfo``, went up while the process
+  lived and came back after it was reaped,
+- ``/proc/<pid>/group/fd`` showed open descriptors while the process lived,
+  and the group is gone after.
+
+The exit status is the number of targets that failed. The test needs
+``CONFIG_FS_PROCFS``.
+
+Configuration
+=============
+
+- ``CONFIG_EXAMPLES_SANDBOX`` -- Enable the test.
+- ``CONFIG_EXAMPLES_SANDBOX_ALLOC`` -- Bytes that the process holds when it
+  dies. Default 65536.
+- ``CONFIG_EXAMPLES_SANDBOX_KERNEL_ADDR`` -- A mapped kernel address. A
+  protected build can leave it at 0, because ``CONFIG_NUTTX_USERSPACE``
+  gives the boundary. 0 means that the target is not available.
+- ``CONFIG_EXAMPLES_SANDBOX_PERIPH_ADDR`` -- A peripheral register that user
+  code must not reach. 0 means that the target is not available.
+- ``CONFIG_EXAMPLES_SANDBOX_UNMAPPED_ADDR`` -- An address with no mapping.
+  0 means that the target is not available.
+- ``CONFIG_EXAMPLES_SANDBOX_PROGNAME``, ``CONFIG_EXAMPLES_SANDBOX_PRIORITY``
+  and ``CONFIG_EXAMPLES_SANDBOX_STACKSIZE`` -- Program name, priority and
+  stack size.
+
+:ref:`esp32s3-devkit:kernel_oct <platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:kernel_oct>`
+enables the test with all three addresses and shows a run.