arch/xtensa: Provide vfork() and fork(), and BUILD_KERNEL on the ESP32-S3

Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst

@@ -372,6 +372,63 @@ After successfully built and flashed, run on the boards's terminal::
 
 The corresponding output should show related debug information.
 
+kernel_n8r2
+-----------
+
+A KERNEL build for a module with 2 MB of PSRAM, such as the
+ESP32-S3-WROOM-1-N8R2.  The flash is quad and runs in DIO mode.
+
+The page pool is smaller than in ``kernel_oct``, and each of the text, data
+and heap regions of a process is 2 pages of 64 KiB.  A process therefore takes
+384 KiB, and a ``fork()`` needs 768 KiB while the parent and the child both
+exist.
+
+This is tight on purpose.  ``ostest`` has 115 KiB of text against a 128 KiB
+text region.  A larger program needs a module with more PSRAM, not a larger
+page pool.
+
+kernel_oct
+----------
+
+A KERNEL build for a module with octal flash and 8 MB of PSRAM, such as the
+ESP32-S3-WROOM-2-N32R8V.
+
+A KERNEL build gives each process its own address environment.  This is the
+only build mode in which ``fork()`` is available on this chip:  the child
+receives its own copy of the memory of the parent, at the same virtual
+addresses.  ``vfork()`` is available in every build mode.
+
+The page pool holds the pages of every process.  It is carved out of the
+PSRAM, and it is not kept mapped into the kernel address space.  The kernel
+reaches a page of the pool through a small scratch region, mapped for one
+operation and invalidated afterwards.
+
+Build the kernel first, then the applications, then the boot ROMFS, and then
+link the kernel again.  The ROMFS is linked into the kernel image, so a change
+to an application needs the whole chain::
+
+    make -j
+    make export
+    cd ../apps
+    ./tools/mkimport.sh -z -x ../nuttx/nuttx-export-*.tar.gz
+    make import -j
+    ./tools/mkromfsimg.sh ../nuttx/arch/xtensa/src/board/board/romfs_boot.c
+    cd ../nuttx
+    make -j
+
+Confirm that the ROMFS is in the image.  ``romfs_img`` must be a strong symbol
+of a few hundred kilobytes::
+
+    xtensa-esp32s3-elf-nm -S nuttx | grep " romfs_img$"
+
+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::
+
+    nsh> /system/bin/ostest
+
 knsh
 ----
 

arch/Kconfig

@@ -158,6 +158,7 @@ config ARCH_X86_64
 config ARCH_XTENSA
 	bool "Xtensa"
 	select ARCH_HAVE_BACKTRACE
+	select ARCH_HAVE_VFORK
 	select ARCH_HAVE_CPUINFO
 	select ARCH_HAVE_INTERRUPTSTACK
 	select ARCH_HAVE_STACKCHECK
@@ -492,6 +493,7 @@ config ARCH_HAVE_VFORK
 
 config ARCH_HAVE_FORK
 	bool
+	default y if ARCH_XTENSA && BUILD_KERNEL
 	default n
 	depends on ARCH_ADDRENV
 	---help---

arch/xtensa/Kconfig

@@ -85,6 +85,10 @@ config ARCH_CHIP_ESP32S3
 	select ARCH_HAVE_DEBUG
 	select ARCH_HAVE_FPU
 	select ARCH_HAVE_MPU
+	select ARCH_HAVE_MMU
+	select ARCH_HAVE_ADDRENV
+	select ARCH_NEED_ADDRENV_MAPPING
+	select ARCH_HAVE_ELF_EXECUTABLE
 	select ARCH_HAVE_MULTICPU
 	select ARCH_HAVE_RESET
 	select ARCH_HAVE_TEXT_HEAP

arch/xtensa/include/arch.h

@@ -45,6 +45,56 @@
  * Public Types
  ****************************************************************************/
 
+#ifdef CONFIG_ARCH_ADDRENV
+#ifndef __ASSEMBLY__
+
+/* The ESP32-S3 has no general paging MMU and no per-process page-table root.
+ * External memory (PSRAM) is reached through a single global cache-MMU remap
+ * table with separate instruction-bus (.text) and data-bus (.data/.bss/heap)
+ * address windows, at 64 KB page granularity.  An address environment is
+ * therefore described not by a page-table root (no satp/TTBR equivalent) but
+ * by the set of physical PSRAM pages that back the process plus the fixed
+ * virtual window bases.  up_addrenv_select() makes an environment active by
+ * reprogramming the cache-MMU window entries to point at these pages,
+ * invalidating the cache, and reprogramming the PMS split lines that gate
+ * WORLD1 (user) access -- with a fast path when the incoming environment is
+ * already the active one (thread<->thread, ISR, syscall).
+ */
+
+struct arch_addrenv_s
+{
+  /* Virtual bases and heap size.  Returned by up_addrenv_vtext/vdata/vheap
+   * and up_addrenv_heapsize.  .text maps through the instruction-bus window,
+   * .data/.bss and the heap through the data-bus window.
+   */
+
+  uintptr_t textvbase;
+  uintptr_t datavbase;
+  uintptr_t heapvbase;
+  size_t    heapsize;
+
+  /* Physical PSRAM page addresses backing each region -- one 64 KB page per
+   * entry, allocated from the PSRAM page pool by up_addrenv_create().
+   * Index i of a region backs virtual page i counted from that region's
+   * vbase.
+   */
+
+  uintptr_t textpages[CONFIG_ARCH_TEXT_NPAGES];
+  uintptr_t datapages[CONFIG_ARCH_DATA_NPAGES];
+  uintptr_t heappages[CONFIG_ARCH_HEAP_NPAGES];
+
+  /* Number of pages actually allocated in each region */
+
+  uint16_t  ntext;
+  uint16_t  ndata;
+  uint16_t  nheap;
+};
+
+typedef struct arch_addrenv_s arch_addrenv_t;
+
+#endif /* __ASSEMBLY__ */
+#endif /* CONFIG_ARCH_ADDRENV */
+
 /****************************************************************************
  * Public Data
  ****************************************************************************/

arch/xtensa/include/irq.h

@@ -216,7 +216,34 @@ struct xcptcontext
 
   uint32_t *regs;
 
+#ifdef CONFIG_ARCH_KERNEL_STACK
+  /* In a kernel build the kernel cannot run on the stack of the process it
+   * is working for.  That stack lives in a cache-MMU window which
+   * up_addrenv_select() reprograms, so it would move out from under the
+   * kernel the moment it touched another process's address environment --
+   * taking the exception frame and every spilled register window with it.
+   * Each thread therefore gets a small stack of its own in kernel memory,
+   * which no address environment change can disturb.
+   */
+
+  uint32_t *kstack;    /* Allocated base of the kernel stack */
+  uint32_t *ktopstk;   /* Top of the kernel stack (initial stack pointer) */
+  uint32_t *ustkptr;   /* Saved user stack pointer, while in a system call */
+  uint32_t *kstkptr;   /* Saved kernel stack pointer, while a user signal
+                        * handler runs on the user stack */
+#endif
+
 #ifdef CONFIG_LIB_SYSCALL
+  /* The exception frame of the system call currently in progress, i.e. the
+   * caller's register context as the vector saved it.  A system call body
+   * runs as ordinary C code long after the exception has been dispatched, so
+   * this is the only way for one to reach the registers of the thread that
+   * made the call -- vfork() needs the caller's stack pointer and return
+   * address to give the child a copy.
+   */
+
+  uint32_t *sregs;
+
   /* The following array holds the return address and the exc_return value
    * needed to return from each nested system call.
    */

arch/xtensa/src/Makefile

@@ -199,10 +199,20 @@ ifneq ($(CONFIG_WINDOWS_NATIVE),y)
 endif
 
 # This is part of the top-level export target
+#
+# A kernel build links its user programs outside this tree, against the
+# export package, so crt0 has to travel with it:  apps/import expects to
+# find it as startup/crt0.o.
+
+ifeq ($(CONFIG_BUILD_KERNEL),y)
+EXPORT_STARTUP_OBJS = $(STARTUP_OBJS) $(STARTUP_ELF_OBJS)
+else
+EXPORT_STARTUP_OBJS = $(STARTUP_OBJS)
+endif
 
-export_startup: $(STARTUP_OBJS)
+export_startup: $(EXPORT_STARTUP_OBJS)
 	$(Q) if [ -d "$(EXPORT_DIR)/startup" ]; then \
-		cp -f $(STARTUP_OBJS) "$(EXPORT_DIR)/startup"; \
+		cp -f $(EXPORT_STARTUP_OBJS) "$(EXPORT_DIR)/startup"; \
 	 else \
 		echo "$(EXPORT_DIR)/startup does not exist"; \
 		exit 1; \

arch/xtensa/src/common/Make.defs

@@ -39,6 +39,11 @@ CMN_CSRCS += xtensa_modifyreg8.c xtensa_modifyreg16.c xtensa_modifyreg32.c
 CMN_CSRCS += xtensa_mpu.c xtensa_nputs.c xtensa_oneshot.c xtensa_perf.c
 CMN_CSRCS += xtensa_releasestack.c xtensa_registerdump.c
 CMN_CSRCS += xtensa_swint.c xtensa_stackframe.c
+
+ifneq ($(CONFIG_ARCH_HAVE_FORK)$(CONFIG_ARCH_HAVE_VFORK),)
+CMN_CSRCS += xtensa_fork.c
+endif
+
 CMN_CSRCS += xtensa_saveusercontext.c
 CMN_CSRCS += xtensa_usestack.c xtensa_tcbinfo.c
 
@@ -81,7 +86,11 @@ ifeq ($(CONFIG_XTENSA_SEMIHOSTING_HOSTFS),y)
   CMN_CSRCS += xtensa_hostfs.c
 endif
 
-ifeq ($(CONFIG_BUILD_PROTECTED),y)
+ifeq ($(CONFIG_ARCH_KERNEL_STACK),y)
+  CMN_CSRCS += xtensa_addrenv_kstack.c
+endif
+
+ifneq ($(CONFIG_BUILD_FLAT),y)
   CMN_UASRCS += xtensa_signal_handler.S
   CMN_ASRCS  += xtensa_dispatch_syscall.S
   CMN_CSRCS  += xtensa_task_start.c xtensa_pthread_start.c

arch/xtensa/src/common/crt0.c

@@ -55,6 +55,56 @@ int main(int argc, char *argv[]);
  * Private Functions
  ****************************************************************************/
 
+#ifdef CONFIG_BUILD_KERNEL
+
+/****************************************************************************
+ * Name: sig_trampoline
+ *
+ * Description:
+ *   The user-space signal handler trampoline.  A kernel build cannot reach
+ *   the one in xtensa_signal_handler.S -- that lives in libarch, which user
+ *   programs do not link -- so it is carried here in crt0 instead, and
+ *   _start() publishes it to the kernel through ARCH_DATA_RESERVE.  The
+ *   kernel enters it from the SYS_signal_handler case of xtensa_swint().
+ *
+ *   Written as file-scope assembly rather than as a naked function because
+ *   GCC does not implement the naked attribute on Xtensa: it would emit a
+ *   window-rotating prologue and quietly invalidate the register assignments
+ *   below.
+ *
+ * Input Parameters:
+ *   a2 = sighand, the user-space signal handling function
+ *   a3, a4, a5 = signo, info and ucontext, its arguments
+ *
+ * Returned Value:
+ *   None.  This function does not return in the normal sense; it returns
+ *   via the SYS_signal_handler_return syscall.
+ *
+ ****************************************************************************/
+
+#define _SIGTRAMP_STR(x)  #x
+#define _SIGTRAMP_XSTR(x) _SIGTRAMP_STR(x)
+
+__asm__
+(
+  "  .text\n"
+  "  .global sig_trampoline\n"
+  "  .type   sig_trampoline, @function\n"
+  "  .align  4\n"
+  "sig_trampoline:\n"
+  "  mov    a6, a3\n"          /* Move signo into the callee's a2 */
+  "  mov    a7, a4\n"          /* Move info into the callee's a3 */
+  "  mov    a8, a5\n"          /* Move ucontext into the callee's a4 */
+  "  callx4 a2\n"              /* Call the signal handler */
+  "  movi   a2, " _SIGTRAMP_XSTR(SYS_signal_handler_return) "\n"
+  "  syscall\n"                /* Will not return */
+  "  .size sig_trampoline, .-sig_trampoline\n"
+);
+
+void sig_trampoline(void);
+
+#endif /* CONFIG_BUILD_KERNEL */
+
 #ifdef CONFIG_HAVE_CXXINITIALIZE
 
 /****************************************************************************