NuttX implemented fork() and vfork() as the same function. Both were 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 is not fork(). It is vfork()-with-a-private-stack under fork()'s name,
and the history says so: today's fork() is NuttX's old vfork(), renamed in
c33d1c9c97 (2023) without any change of behaviour. The failure was silent --
a program written against POSIX fork() compiled, ran, and had its child's
writes land in the parent's variables.
Separate them into three primitives, chosen by which function the caller
called rather than by what the hardware happens to be:
fork() child gets its own copy of the parent's memory at the same
virtual addresses; runs concurrently. Only where an address
environment can be duplicated -- elsewhere it is not declared
at all, so calling it is a build error naming the function.
vfork() child shares the parent's memory; parent suspended until the
child _exit()s or exec()s. Implementable everywhere.
task_fork() the historical behaviour under an honest name: shares memory,
private stack copy, both running. Non-POSIX, in sched.h.
Below libc there are now three syscalls -- up_task_fork(), up_vfork() and
up_fork(). The per-arch register snapshot is common to all three; each
architecture's entry points share one sequence and differ only in a
FORK_TYPE_* selector (include/nuttx/fork.h) handed to nxtask_setup_fork(),
which is the single place the memory semantics are decided.
The vfork() parent suspension moves out of libc into nxtask_start_vfork(),
released from nxsched_release_tcb(). Two things follow: the parent is
resumed at exec(), since exec_swap() has already handed the child's pid to
the loaded program by the time the vfork stub exits, and vfork() no longer
depends on CONFIG_SCHED_WAITPID.
Releasing there requires one fix in nxtask_exit(). It raises rtcb->lockcount
directly rather than through sched_lock() while it tears the TCB down, so the
nxsem_post() that wakes the vfork() parent queues it on g_pendingtasks -- and
the matching raw lockcount-- does not merge that list the way sched_unlock()
would, leaving the parent stranded with nothing left to move it off. A
nxsched_merge_pending() after the decrement publishes it. The call is a
no-op while pre-emption is still disabled, and up_exit() re-reads this_task()
afterwards, so a change of the ready-to-run head is honoured. Without it
vfork() deadlocks on any configuration where no other task happens to call
sched_unlock() afterwards -- rv-virt:nsh64 and rv-virt:pnsh64, for instance,
where NSH is blocked in waitpid() holding the lock.
fork() is built on a new addrenv_fork(), backed by an up_addrenv_fork() hook
that duplicates an address environment into freshly allocated pages mapped at
the same virtual addresses -- unlike up_addrenv_clone(), which copies only
the representation and leaves both pointing at the same page tables. The
child then adopts the parent's stack geometry rather than being given a
relocated copy: a pointer to a stack local taken before fork() must name the
same object in the child that it named in the parent, and the parent's stack
is already in the duplicate, with its contents, at the parent's address.
No architecture implements up_addrenv_fork() yet, so this commit leaves
fork() unavailable everywhere. That is the intended state. It withdraws
fork() from ARCH_ARM, flat ARCH_ARM64, ARCH_RISCV, ARCH_SIM and ARCH_X86_64,
where until now it named the sharing primitive; per-architecture patches
restore it, with POSIX semantics, as up_addrenv_fork() lands. Nothing is
lost in the meantime: task_fork() is that same sharing primitive under its
own name, and CONFIG_FORK_IS_TASK_FORK (default n) aliases fork() back to it
for legacy code, on exactly the configurations that had fork() before.
Kconfig: ARCH_HAVE_TASK_FORK and ARCH_HAVE_VFORK inherit ARCH_HAVE_FORK's
select lines, conditions included, so no configuration gains machinery;
ARCH_HAVE_FORK is redefined to mean "can provide POSIX fork() semantics" and
derives from the new ARCH_HAVE_ADDRENV_FORK.
There is one deliberate departure from "verbatim". ARCH_ARM selected the
fork family unconditionally, BUILD_KERNEL included, and that has never
worked: on a kernel build the architecture's fork entry point sees the
kernel's return address and stack pointer rather than the caller's, so the
child resumes at a kernel address. On qemu-armv7a:knsh master faults in
ostest's task_fork case with "Child did not run" and then a data abort;
without the condition this change faults the same way through vfork().
ARCH_ARM64 and ARCH_X86_64 already carried "if !BUILD_KERNEL" for exactly
this reason -- ARM was the outlier. Conditioning it turns a runtime fault
into an honest absence, which is the whole point of the change; arch/arm
takes the condition off again in the patch that adds its saved-syscall-frame
path. Only the MMU-capable ARM ports are affected, since Cortex-M cannot
build BUILD_KERNEL at all.
Also fixes two latent syntax errors found on the way: a missing comma in
riscv_fork.c and mips_fork.c, both in *_FRAMEPOINTER && !SAVE_GP branches
that are never compiled today.
Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>
Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Apache NuttX is a real-time operating system (RTOS) with an emphasis on
standards compliance and small footprint. Scalable from 8-bit to 64-bit
microcontroller environments, the primary governing standards in NuttX are POSIX
and ANSI standards. Additional standard APIs from Unix and other common RTOSs
(such as VxWorks) are adopted for functionality not available under these
standards, or for functionality that is not appropriate for deeply-embedded
environments (such as fork()).
For brevity, many parts of the documentation will refer to Apache NuttX as simply NuttX.
Getting Started
First time on NuttX? Read the Getting Started guide!
If you don't have a board available, NuttX has its own simulator that you can run on terminal.
Alternatively, you can build the documentation yourself by following the Documentation Build Instructions.
The old NuttX documentation is still available in the Apache wiki.
Supported Boards
NuttX supports a wide variety of platforms. See the full list on the Supported Platforms page.
Contributing
If you wish to contribute to the NuttX project, read the Contributing guidelines for information on Git usage, coding standard, workflow and the NuttX principles.
License
The code in this repository is under either the Apache 2 license, or a license compatible with the Apache 2 license. See the License Page for more information.
a229e8b87e
