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 <[email protected]> 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 <[email protected]> --- .../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.
