testing/ostest: split the fork test into task_fork, vfork and fork

[casaroli]

Summary

This is the apps half of apache/nuttx#19540, and it must merge first. Companion PR: apache/nuttx#19562, whose CI cannot go green until this one lands, because NuttX PRs build against apps master and three things here call fork() unconditionally.

NuttX implements fork() and vfork() as the same function, and is gaining three separate primitives: task_fork() (shares memory, private stack copy, both running), vfork() (shares memory, parent suspended until _exit()/exec()) and POSIX fork() (child gets its own copy). This PR works against NuttX with or without that change, so no test coverage is lost across the transition.

ostest's "vfork" test was never testing vfork(). It has the child write a global and the parent observe the write — the defining property of sharing, not of vfork(), whose defining property is that the parent is suspended and whose contract forbids the child to write anything at all. It is renamed to task_fork.c, unchanged, because that is the primitive it has always described. It is also the clearest single piece of evidence for the proposal: the test upstream has run for years is a task_fork() test wearing vfork()'s name.

vfork.c is rewritten to test what vfork() promises. The child does only what POSIX permits — it calls _exit(42) and nothing else, not even exit(), which would run atexit handlers and flush stdio in the parent's address space. Since the child may not write memory and the parent cannot run while the child lives, the observable is the child's exit status: had the parent not been suspended, it would have reached waitpid() while the child was still alive. Where child status is not retained — ostest_main() sets SA_NOCLDWAIT for the whole run, deliberately — ECHILD is accepted as equally good evidence, since it says the child was already gone when the parent asked.

fork.c is new and tests POSIX fork(): the child's writes to .data, .bss and the heap are invisible to the parent and vice versa, a pointer to a stack local taken before the fork names the same object in both, and the child does everything a vfork() child may not — calls malloc() and printf(), and returns from the function that called fork().

All three run at the top of user_main(). They exercise the lowest-level machinery in the suite — address environments, stack setup, the architecture's register context — so a fault in one takes the process down instead of reporting a failure. Learning that in seconds rather than after everything else has passed matters when a port is being brought up.

The other in-tree callers are audited for which primitive they actually meant:

• testing/drivers/nand_sim wants a daemon that outlives its caller and shares its memory — task_fork().
• interpreters/python's _posixsubprocess and netutils/libwebsockets' LWS_HAVE_WORKING_VFORK want the fork-then-exec path — vfork().
• python's os.fork() and libwebsockets' LWS_HAVE_FORK mean real fork() and stay on CONFIG_ARCH_HAVE_FORK, so they become absent rather than silently wrong.
• testing/fs/fdsantest's vfork case follows vfork().

Two third-party suites need their source lists narrowed, because they call fork() from code compiled unconditionally:

• system/libuv — test-fork.c and test-pipe-close-stdout-read-stdin.c are filtered out of the test-*.c glob. Every test they define is already excluded from the task list on NuttX by 0001-libuv-port-for-nuttx.patch, so they were dead code compiled only because fork() happened to be declared. Nothing is lost.
• testing/ltp — the open_posix_testsuite is filtered through LTP's existing BLACKWORDS mechanism, which already drops tests for absent features and is already conditioned on configuration symbols. Where fork() is not provided this drops 278 of 1943 test files; the pattern [^v_]fork( spares vfork() and task_fork(). Where fork() is provided — everywhere, today — nothing is dropped, so it is a no-op against current master.

That 278-file loss is the honest price of the change: those tests exercise fork(), and on a target without fork() they cannot link. They return per architecture as real fork() lands.

Two other fork() mentions need nothing: games/NXDoom's is inside #if 0 /* UNUSED */, and system/syslogd already uses posix_spawn().

interpreters/bas is deliberately left alone. Its SHELL and EDIT statements want the same treatment as the others, but checkpatch.sh checks the whole of any file a patch touches, and bas_statement.c produces 1681 pre-existing findings before this patch is applied at all — a one-newline commit against master fails CI identically. Migrating BAS has to follow a style cleanup of that file, and neither belongs here. The consequence is small: CONFIG_EXAMPLES_BAS_SHELL is EXPERIMENTAL and already depends on ARCH_HAVE_FORK, so it becomes unselectable rather than misbehaving.

Impact

Against today's NuttX, ostest builds and runs exactly the fork test it runs now. task_fork.c is that test, byte for byte, under the name of the primitive it describes. A NuttX without CONFIG_ARCH_HAVE_TASK_FORK is the pre-split one, and only there does CONFIG_ARCH_HAVE_FORK stand in, with task_fork() mapped to fork().

vfork_test() and fork_test() have no such fallback, deliberately. Both check semantics a pre-split NuttX does not describe — the parent suspension and the private copy — so mapping them onto CONFIG_ARCH_HAVE_FORK would add tests to configurations that never had one. That is not free: vfork.c costs about 470 bytes of .text on armv7-m at -Os, which put lm3s6965-ek:qemu-protected over its 128 KiB user flash region. They activate on the symbol that announces the primitive, CONFIG_ARCH_HAVE_VFORK.

task_fork.c keys on CONFIG_TASK_FORK, not on the capability symbol. On the NuttX side ARCH_HAVE_TASK_FORK says the architecture can clone a task while TASK_FORK says the build asked for it, and task_fork() is only declared under the latter. Gating the test on the capability alone would fail to compile a TASK_FORK=n build. CONFIG_TESTING_NAND_SIM gains the same dependency; it called fork() unconditionally before and would not have linked on a target without it.

The whole compatibility layer is one #if pair and a task_fork() -> fork() shim in ostest.h, plus the matching build-file conditions. A small follow-up removes it once the NuttX side is in; that follow-up must not merge before the NuttX PR.

Testing

Host: macOS 15 (Darwin 25.5.0) on Apple Silicon. QEMU 11.0.3, xPack riscv-none-elf-gcc 14.2.0-3, Arm GNU arm-none-eabi-gcc 14.2.Rel1.

Against unmodified NuttX master (5a7f1b5005) — the case this PR must not break

rv-virt:nsh64, ostest: config has only CONFIG_ARCH_HAVE_FORK=y, as expected — neither new symbol exists. nm on the image shows task_fork_test built, vfork_test and fork_test absent — exactly the intent. Run: task_fork_test: Child 5 ran successfully, ostest_main: Exiting with status 0.

lm3s6965-ek:qemu-protected, the size-constrained configuration this PR must not overflow: builds clean, 596 bytes free of the 128 KiB uflash region against a 708-byte baseline on apps master.

The LTP filter, verified

Built rv-virt:citest (the CI config that enables LTP) against the NuttX PR branch and mapped every object back to its source:

fork-using LTP sources that produced an object: 0 (of 278)
other LTP objects built:                        896
implicit-declaration errors for fork():         0

Against the NuttX PR branch

Full ostest suite to exit status 0 on rv-virt:nsh64 (FLAT), rv-virt:pnsh64 (PROTECTED), rv-virt:knsh64 (KERNEL), qemu-armv7a:nsh, qemu-armv8a:nsh and qemu-intel64:nsh, with task_fork_test and vfork_test passing and fork_test correctly absent — no architecture provides POSIX fork() at that point in the series. sim:ostest also builds and passes both.

fork_test() itself is verified by the per-architecture PRs that follow, which are what turn CONFIG_ARCH_HAVE_FORK back on. It has been run to completion on RISC-V, arm64, armv7-a and x86_64 kernel builds on the development branch those PRs are cut from — fork_test: Parent and child had independent memory — so it is not being added untested; it is simply not reachable until the first up_addrenv_fork() lands.

Style

../nuttx/tools/checkpatch.sh -c -u -m -g <base>..HEAD, the exact command .github/workflows/check.yml runs — ✔️ All checks pass, with codespell, cvt2utf, cmake-format and nxstyle all installed.

[jerpelea]

please replace
Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com
with
Assisted-by: Claude Opus 5 (1M context) noreply@anthropic.com

[xiaoxiang781216]

why need CONFIG_FORK_IS_TASK_FORK

[casaroli]

This is a retro compatibility flag disabled by default. It is available to alias fork() to task_fork() in non MMU systems, in case someone depends on the exact current NuttX behavior without needing to update their program source code.

[casaroli]

it's config FORK_IS_TASK_FORK in arch/Kconfig in apache/nuttx#19562 — default n, depends on TASK_FORK && !ARCH_HAVE_FORK

[xiaoxiang781216]

why need check CONFIG_ARCH_HAVE_FORK/CONFIG_ARCH_HAVE_TASK_FORK

[casaroli]

This is required for this to merge before the nuttx PR. We can remove this with a follow up pr after the companion pr in nuttx gets merged

[xiaoxiang781216]

why need the above mapping?
it's better to just check CONFIG_ARCH_TASK_FORK/CONFIG_ARCH_FORK/CONFIG_ARCH_VFORK.

[casaroli]

This is required for this to merge before the nuttx PR. We can remove this with a follow up pr after the companion pr in nuttx gets merged

[xiaoxiang781216]

remove

[casaroli]

replaced this with nested ifeq. This is required for this to merge before the nuttx PR. We can remove this with a follow up pr when the companion pr in nuttx gets merged

[xiaoxiang781216]

why need check CONFIG_ARCH_HAVE_VFORK for fork test

[casaroli]

if we do only CONFIG_ARCH_HAVE_FORK then all architectures will build that today, and lm3s6965-ek:qemu-protected is already almost over budget, it would not fit in .text. We can remove this with a follow up pr after the companion pr in nuttx gets merged.

In fact, we will need to decide how we deal with lm3s6965-ek:qemu-protected in the companion PR because I think .text will overflow there.

[xiaoxiang781216]

already done in Makefile, why need check again?

[casaroli]

done

[xiaoxiang781216]

remove too

[casaroli]

done

[casaroli]

Follow up pr #3685