!sched/arch/libc: Give fork() and vfork() their real, separate semantics.

Documentation/guides/fork_vfork_migration.rst

@@ -0,0 +1,237 @@
+=========================================
+Migrating to separate ``fork``/``vfork``
+=========================================
+
+What changed
+============
+
+NuttX used to implement ``fork()`` and ``vfork()`` as the same function.  Both
+were thin libc wrappers around a single ``up_fork()`` syscall; ``vfork()``
+differed only by a trailing ``waitpid()``.  Underneath, the child joined the
+parent's address environment -- the same ``addrenv_join()`` that
+``pthread_create()`` uses -- and got a private *copy of the stack*.  So the
+child shared ``.data``, ``.bss`` and the heap with its parent, and ran
+concurrently with it.
+
+That was not ``fork()``.  It was ``vfork()``-with-a-private-stack published
+under ``fork()``'s name.  The history says so plainly: the ``fork()`` this
+replaces was NuttX's old ``vfork()``, renamed in 2023 without any change of
+behaviour.  And the consequence was silent: a program written against POSIX
+``fork()`` compiled and ran, and its child's writes quietly landed in the
+parent's variables.
+
+There are now two distinct primitives, and each means what its name says:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 14 30 26 30
+
+   * - API
+     - Memory
+     - Parent
+     - Availability
+   * - ``fork()``
+     - child gets **its own copy** at the same virtual addresses
+     - runs concurrently
+     - ``CONFIG_ARCH_HAVE_FORK`` -- only where an address environment can be
+       duplicated
+   * - ``vfork()``
+     - child **shares** the parent's memory
+     - **suspended** until the child ``_exit()``\ s or ``exec()``\ s
+     - ``CONFIG_ARCH_HAVE_VFORK`` -- no address environment needed
+
+.. note::
+
+   ``fork()`` is provided only where the architecture implements
+   ``up_addrenv_fork()`` and therefore selects ``CONFIG_ARCH_HAVE_FORK``; it
+   becomes available architecture by architecture as that hook lands.  Check
+   ``CONFIG_ARCH_HAVE_FORK`` in your own configuration rather than assuming
+   either way.  Where it is unset, ``vfork()`` is what the configuration
+   offers.
+
+This is a breaking change
+=========================
+
+Two things break, and they break loudly rather than quietly:
+
+**Code calling** ``fork()`` **on a target without a duplicable address
+environment no longer builds.**  ``fork()`` is not declared in ``unistd.h``
+there, so you get a compile error naming the function.  That is the intended
+outcome:  a build error is strictly better than the silent wrongness it
+replaces.  Today that is every in-tree architecture, so every caller of
+``fork()`` has to be looked at.
+
+**Code calling** ``fork()`` **on a target that does have real** ``fork()``
+**changes behaviour** -- from sharing to copying.  Code that (perhaps
+unknowingly) relied on the sharing will now see the parent and child diverge.
+
+Which replacement do I want?
+============================
+
+Answer the question "why did I call ``fork()``?".
+
+*I want the child to run a different program.*
+   Use :c:func:`posix_spawn` or ``task_spawn()``.  This is the single most
+   common reason to call ``fork()``, NuttX has always provided a better answer
+   for it, and that answer does not have the pid discontinuity that
+   ``fork()``\ +\ ``exec()`` has.  If you must keep the two-step idiom, use
+   ``vfork()`` + ``exec*()``:  that is exactly what ``vfork()`` is for, and
+   unlike ``fork()`` it needs no duplicable address environment.
+
+   .. code-block:: c
+
+      #include <unistd.h>
+
+      pid = vfork();         /* was: pid = fork(); */
+      if (pid == 0)
+        {
+          execv(path, argv); /* or _exit() on failure */
+          _exit(EXIT_FAILURE);
+        }
+
+   Note the restriction that comes with it:  between the ``vfork()`` and the
+   ``exec()`` the child shares the parent's memory and runs on the parent's
+   behalf, so it must not modify anything, must not return from the calling
+   function, and must not call anything other than ``_exit()`` or an ``exec``
+   family function.
+
+*I want a second flow of control that shares my memory.*
+   Use ``pthread_create()``.  That is the same memory relationship the old
+   ``fork()`` gave you, spelled clearly, with a normal entry point instead of a
+   function that returns twice.  There is no longer a returns-twice primitive
+   with concurrent sharing semantics:  the old behaviour was not POSIX, and
+   ``vfork()`` is not a drop-in for it -- the parent is suspended, so parent and
+   child never run concurrently.
+
+*I want a genuinely independent copy of this process.*
+   Keep calling ``fork()``, and make sure your configuration selects
+   ``CONFIG_ARCH_HAVE_FORK``.  Be aware there is no copy-on-write: the copy is
+   eager, so forking a large process needs as much free memory as the process
+   occupies and fails with ``ENOMEM`` otherwise.
+
+Configuration symbols
+=====================
+
+``CONFIG_ARCH_HAVE_VFORK``
+   Hidden.  The architecture can implement POSIX ``vfork()``.  Selected exactly
+   where ``ARCH_HAVE_FORK`` used to be, so every configuration that had the old
+   ``fork()`` has ``vfork()``.
+
+``CONFIG_ARCH_HAVE_FORK``
+   Hidden, ``depends on ARCH_ADDRENV``.  It no longer means "``fork()``
+   exists"; it means "this configuration can provide POSIX ``fork()``
+   semantics", which requires an address environment and an
+   ``up_addrenv_fork()`` to duplicate it with.
+
+Notes for architecture maintainers
+==================================
+
+The register/stack snapshot machinery is common to both primitives.  Each
+architecture exposes one entry point, ``up_fork(bool vfork)``, whose argument
+says which primitive the caller used and is handed to ``nxtask_setup_fork()``.
+That is where the memory semantics are decided: ``addrenv_join()`` for
+``vfork()``, ``addrenv_fork()`` for ``fork()``.
+
+Adding real ``fork()`` to an architecture
+-----------------------------------------
+
+Two things are needed, and the second is the one that is easy to miss.
+
+**Implement** ``up_addrenv_fork()``.  It duplicates an address environment:
+allocate fresh pages, copy the parent's contents into them, and map them at the
+*same* virtual addresses.  ``up_addrenv_clone()`` is not this -- it copies only
+the representation and leaves both processes pointing at one set of page
+tables.  Then give ``ARCH_HAVE_FORK`` a ``default y if <arch>`` line in
+``arch/Kconfig``.
+
+**Build the child from the caller's saved system call frame.**  In a kernel
+build ``fork()`` is reached through a system call, so the return address and
+stack pointer the architecture's fork entry point can observe for itself belong
+to the *kernel*, not to the caller; a child built from those resumes at a
+kernel address on a kernel stack.  The architecture must record the caller's
+exception frame when it traps -- ``xcp.sregs`` is the field that exists for
+this -- and build the child from that instead, while a kernel thread that calls
+the entry point directly still takes the ordinary path.
+
+Four architectures do it, and they are worth copying:
+
+* RISC-V: ``riscv_swint.c`` stores the frame in ``xcp.sregs``, and
+  ``riscv_fork.c`` rebuilds the child from it.
+* arm64: ``arm64_vectors.S`` hands the frame to ``dispatch_syscall()``, which
+  stores it in ``xcp.sregs``; ``arm64_fork()`` then dispatches to
+  ``arm64_fork_syscall()`` or ``arm64_fork_direct()`` according to whether
+  ``TCB_FLAG_SYSCALL`` is set, so a kernel thread that calls the entry point
+  directly still works.
+* armv7-a: ``arm_syscall.c`` stores the frame in ``xcp.sregs``, and
+  ``arm_fork()`` dispatches to ``arm_fork_syscall()`` or
+  ``arm_fork_direct()``.  The discriminator here is a saved user stack
+  pointer, ``xcp.ustkptr``, rather than ``TCB_FLAG_SYSCALL``:  armv7-a
+  dispatches a system call by re-pointing the caller's own exception frame at
+  ``dispatch_syscall()``, so the caller *is* the task that runs the kernel
+  side of the call.  What makes its snapshot useless is not the system call
+  as such but the switch to the kernel stack, which leaves the kernel-side
+  frames on a stack the child gets no copy of.  A build without a kernel
+  stack dispatches on the caller's own stack, so there the frames are copied
+  along with the caller's and ``arm_fork_direct()`` remains correct.  Because
+  ``arm_syscall()`` has already re-pointed the frame by the time
+  ``arm_fork()`` runs, its PC, CPSR and SP are the kernel's; the caller's are
+  read from where ``arm_syscall()`` put them -- ``syscall[0].sysreturn``,
+  ``syscall[0].cpsr`` and ``ustkptr``.
+* x86_64: ``x86_64_syscall()`` stores the frame in ``xcp.sregs``, and
+  ``x86_64_fork()`` dispatches to ``x86_64_fork_syscall()`` or
+  ``x86_64_fork_direct()``.  The discriminator here is ``xcp.sregs`` itself
+  being non-NULL, because raising ``TCB_FLAG_SYSCALL`` would also defer signal
+  actions -- something x86_64 has never done and its kernel-build signal path
+  does not currently survive.  Two properties of ``SYSCALL``/``SYSRET`` shape
+  the child's frame:  the instruction leaves the caller's RIP and RFLAGS in
+  RCX and R11 rather than on a stack, so they have to be moved into the RIP
+  and RFLAGS slots of the interrupt frame the child is resumed from; and the
+  hardware never records the caller's CS and SS at all -- ``SYSRETQ``
+  reconstructs them from ``IA32_STAR`` -- so the child's have to be filled in
+  with the user code and data selectors at RPL 3.  For the same reason the
+  saved frame is not copied wholesale:  only the extended state and the
+  general registers are inherited, and the segment registers and thread
+  pointer come from the frame ``up_initial_state()`` built for the child.
+
+Nothing else is required:  the ``up_fork()`` entry point and the libc wrapper
+are already there and become live automatically.
+
+Note that ``ARCH_HAVE_FORK`` is about a *per-process* address environment.  A
+protected build has one address space carved up once at boot, whether the
+boundaries are drawn by an MPU or by a fixed set of MMU mappings; its
+``up_addrenv_*()`` are stubs, and there is no mapping to duplicate at the same
+virtual addresses.  ``CONFIG_ARCH_ADDRENV`` being set is therefore not by
+itself evidence that ``fork()`` can be provided.  ``vfork()``, which shares the
+parent's memory, works there as everywhere else.
+
+Known gaps
+==========
+
+``fork()`` **is gained one architecture at a time.**  The generic machinery is
+complete -- ``addrenv_fork()``, the ``up_addrenv_fork()`` hook, the syscall, the
+libc wrapper and the ``ostest`` case -- so an architecture provides ``fork()``
+by implementing ``up_addrenv_fork()`` and selecting ``CONFIG_ARCH_HAVE_FORK``,
+with no further generic work.
+
+**A windowed ABI needs its stack rebased, not just copied.**  On Xtensa,
+giving a child a relocated copy of the parent's stack takes more than the copy:
+the register-window save areas embedded in the stack hold absolute stack
+pointers, so each one has to be rebased along with the copy, or the child
+reloads a pointer into the *parent's* stack on its very first window underflow.
+That rebasing is architecture-specific and belongs with the Xtensa entry points
+rather than here.
+
+Note also on ``waitpid()`` after ``vfork()``
+============================================
+
+The ``vfork()`` parent is now resumed when the child's TCB is torn down, so by
+the time it runs the child is completely gone.  Where the child called
+``exec()`` this makes no difference -- ``exec_swap()`` has already given the
+loaded program the child's pid, and that program is still running, so
+``waitpid()`` behaves normally.  Where the child called ``_exit()``,
+``waitpid()`` can only return its status if ``CONFIG_SCHED_CHILD_STATUS`` is
+enabled; otherwise it returns ``ECHILD``, because NuttX does not retain the
+status of a task that no longer exists.  That is a pre-existing property of
+that configuration, not a change:  the previous implementation blocked in a
+libc ``waitpid(WNOWAIT)`` and an application's own ``waitpid()`` afterwards hit
+the same wall.

Documentation/guides/index.rst

@@ -37,6 +37,7 @@ Guides
   logging_rambuffer.rst
   ipv6.rst
   integrate_newlib.rst
+  fork_vfork_migration.rst
   protected_build.rst
   platform_directories.rst
   port_drivers_to_stm32f7.rst

Documentation/implementation/memory_configurations.rst

@@ -30,7 +30,7 @@ On-Demand Paging
 
 NuttX also supports on-demand paging via ``CONFIG_PAGING``.
 On-demand paging is a method of virtual memory management and requires
-the the CPU architecutre support a MMU.
+the the CPU architecture support a MMU.
 
 In a system that uses on-demand paging, the OS responds to a page fault
 by copying data from some storage media into physical memory and setting up
@@ -410,7 +410,7 @@ of functions that:
 
 1. Have only one ``.text`` space in RAM, but
 2. Separate ``.data`` and ``.bass`` space, and are
-3. Separately linked into with the program in each address environmnet.
+3. Separately linked into with the program in each address environment.
 
 (not implemented).
 
@@ -484,7 +484,7 @@ at least in its current form.
 That full implementation of ``mmap()`` plus the minor changes
 to the NuttX ELF loader are all that are required to support fully
 share-able ``.text`` sections – as well as the memory savings
-from not carrying aroung the relocation and symbol information
+from not carrying around the relocation and symbol information
 
 (Not implemented).
 
@@ -632,10 +632,13 @@ the contemplate in any real detail:
   and swap the state into physical memory as needed?(not implemented).
 * ``mmap()``. True shared memory and true file mapping could be supported.
   I am repeating myself (not implemented).
-* ``fork()``. The ``fork()`` interface could be supported. NuttX currently
-  supports the "crippled" version, ``vfork()`` but with these process address
-  environments, the real ``fork()`` interface could be supported.
-  (not implemented).
+* ``fork()``. The real ``fork()`` interface can be supported on configurations
+  with a duplicable process address environment: an architecture implements
+  ``up_addrenv_fork()`` and selects ``CONFIG_ARCH_HAVE_FORK``. What is not
+  implemented is
+  copy-on-write:  the duplication copies the parent's pages eagerly, which
+  needs as much free memory as the parent occupies. Demand paging would fix
+  that.
 * Dynamic Stack Allocation. Completely eliminate the need for constant tuning
   of static stack sizes.(not implemented).
 * Shared Libraries. Am I repeating myself again?(not implemented).
@@ -688,8 +691,8 @@ There are two problems here:
 So how do you create new tasks/processes in such a context.
 There is only one way possible; by using an interface that takes a file name
 as an argument (rather than absolute address).
-New processes started with ``vfork()`` and ``exec()`` or with
-``posix_spawn()`` should not have any of these issues.
+New processes started with ``fork()`` or ``vfork()`` and ``exec()``, or with
+``posix_spawn()``, should not have any of these issues.
 
 
 ARM Memory Management