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
The following commit(s) were added to refs/heads/master by this push:
new e8a3d4ee1cb Documentation/esp32s3: Describe memory protection and the
kernel build.
e8a3d4ee1cb is described below
commit e8a3d4ee1cb70c15c7f323b981f8511a28899d39
Author: Marco Casaroli <[email protected]>
AuthorDate: Tue Sep 29 21:05:54 2026 +0200
Documentation/esp32s3: Describe memory protection and the kernel build.
The chip page did not say which build modes the ESP32-S3 supports, how a
KERNEL build uses the MMU, or what happens when user code takes a fault.
Add a section for that, with the console messages of a fault and the
options CONFIG_ESP32S3_USERFAULT_ABORT and CONFIG_ESP32S3_PAGEFAULT.
On the board page, kernel_oct said the shell needs the full path of a
program, but /system/bin is in PATH. Say that instead, describe the
isolation of a process, and show how ostest and sandbox check it. Also
add a section for ksta_softap, which had none.
Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Marco Casaroli <[email protected]>
---
.../xtensa/esp32s3/boards/esp32s3-devkit/index.rst | 33 +++++++++++++++-
Documentation/platforms/xtensa/esp32s3/index.rst | 45 ++++++++++++++++++++++
2 files changed, 76 insertions(+), 2 deletions(-)
diff --git
a/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
b/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
index 77b01e97d02..dc91b84ef12 100644
--- a/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
+++ b/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
@@ -425,9 +425,31 @@ A one byte symbol means that the linker took the stub.
Delete
``boards/xtensa/esp32s3/esp32s3-devkit/src/romfs_stub.o`` and ``libboard.a``,
then link again.
-The shell needs the full path of a program in this build mode::
+The programs are in ``/system/bin``, which is in ``PATH``, so the shell finds
+them by name.
- nsh> /system/bin/ostest
+A process runs in the unprivileged world and cannot reach kernel memory, the
+peripherals or the pages of another process. If it tries, only that process
+is terminated. See
+:ref:`Memory Protection and Build Modes <platforms/xtensa/esp32s3/index:Memory
Protection and Build Modes>`.
+
+Two programs in the ROMFS show this on the board. ``ostest`` includes the
+``fork()`` and ``vfork()`` tests::
+
+ nsh> ostest
+ ...
+ fork_test: Parent and child had independent memory
+ ...
+ ostest_main: Exiting with status 0
+
+``sandbox`` makes one allowed access and three forbidden ones: to kernel
+memory, to a peripheral register and to an address without a mapping. Each
+offender must be terminated, the caller must survive, and the memory and the
+file descriptors of the offender must be given back::
+
+ nsh> sandbox
+ ...
+ sandbox: CONTAINED - 4 target(s), every check passed
knsh
----
@@ -449,6 +471,13 @@ Flash and PSRAM).
.. warning:: The World Controller and Permission Control **do not** prevent
the application from accessing CPU System Registers.
+ksta_softap
+-----------
+
+A PROTECTED build, like ``knsh``, with Wi-Fi in station and SoftAP mode at
+the same time. It includes ``wapi``, a DHCP server and ``iperf``. The Wi-Fi
+commands are the same as in :ref:`esp32s3-devkit:sta_softap
<platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:sta_softap>`.
+
mbedtls
-------
diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst
b/Documentation/platforms/xtensa/esp32s3/index.rst
index 8b5f81f1c77..95914f0ccb1 100644
--- a/Documentation/platforms/xtensa/esp32s3/index.rst
+++ b/Documentation/platforms/xtensa/esp32s3/index.rst
@@ -876,6 +876,51 @@ Set the attribute ``__attribute__ ((section
(".ext_ram.bss")))`` to the variable
This is particularly useful when the internal RAM is not enough to hold all
the data.
+Memory Protection and Build Modes
+=================================
+
+The ESP32-S3 supports the three NuttX build modes:
+
+* **FLAT**: the kernel and the applications are one image, with no
+ protection between them.
+* **PROTECTED**: the kernel and the applications are two images. The World
+ Controller (WC) and the Permission Control (PMS) run the applications in the
+ unprivileged world, which cannot reach kernel memory or the peripherals.
+ See :ref:`esp32s3-devkit:knsh
<platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:knsh>` and
:ref:`esp32s3-devkit:ksta_softap
<platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:ksta_softap>`.
+* **KERNEL**: every program is a separate ELF file with its own address
+ environment, protected by WC and PMS in the same way. The MMU maps flash
+ and PSRAM in pages of 64 KiB. The pages of every process come from a page
+ pool in PSRAM, and the kernel switches the mappings with the process. This
+ is the only build mode with ``fork()``.
+ See :ref:`esp32s3-devkit:kernel_oct
<platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:kernel_oct>` and
:ref:`esp32s3-devkit:kernel_n8r2
<platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:kernel_n8r2>`.
+
+Faults in User Code
+-------------------
+
+In a PROTECTED or a KERNEL build, a user task that makes a forbidden access,
+or takes any other fault that cannot be serviced, receives ``SIGSEGV``. Its
+default action terminates only that task, and the rest of the system keeps
+running. This is ``CONFIG_ESP32S3_USERFAULT_ABORT``, which is enabled by
+default. A fault in kernel mode still halts the system: a kernel thread, a
+system call and an interrupt handler have no task that can safely be killed.
+
+The console names the cause of the fault::
+
+ pms_violation_isr: SIGSEGV (PMS) task sandbox: PC=42c0195f
+ pms_violation_isr: SIGSEGV (MMU entry) task sandbox: PC=42c01967
+
+``(PMS)`` is an access that the permission control refused, for example to
+kernel memory or to a peripheral. ``(MMU entry)`` is an access to an address
+that has no valid MMU entry.
+
+``CONFIG_ESP32S3_PAGEFAULT`` routes these permission faults to a dispatcher
+that can service them and restart the instruction. This is the base for
+guard pages and for growing a stack or a heap on demand. It is disabled by
+default.
+
+.. warning:: The World Controller and the Permission Control **do not**
+ prevent user code from accessing the CPU system registers.
+
.. _esp32s3_ulp:
ULP RISC-V Coprocessor
