From e8a3d4ee1cb70c15c7f323b981f8511a28899d39 Mon Sep 17 00:00:00 2001 From: Marco Casaroli Date: Tue, 29 Sep 2026 21:05:54 +0200 Subject: [PATCH] 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 --- .../esp32s3/boards/esp32s3-devkit/index.rst | 33 +++++++++++++- .../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 `. + +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 `. + 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 ` and :ref:`esp32s3-devkit: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 ` and :ref:`esp32s3-devkit: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