7aac6c5cb8
nuttx implements fork() and vfork() as the same function, and is gaining the three separate primitives its issue #19540 describes: task_fork() (shares memory, private stack copy, both running), vfork() (shares memory, parent suspended) and POSIX fork() (child gets its own copy). This is the apps side of that, and it lands first: it works against nuttx with or without the split, so the tests keep running across the transition rather than silently compiling out. ostest's "vfork" test was never testing vfork(). It has the child write a global and the parent observe the write -- which is 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. 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. The observable is therefore the child's exit status rather than a memory write. Where child status is not retained -- ostest_main() sets SA_NOCLDWAIT for the whole run, deliberately -- waitpid() returning ECHILD is accepted as equally good evidence: 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() rather than in the middle. 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, and finding that out in seconds rather than after everything else has passed is the difference between a usable iteration and a coffee break when a port is being brought up. The other in-tree callers are audited for which primitive they actually meant. nand_sim wants a daemon that outlives its caller and shares its memory, which is task_fork(). bas's SHELL and EDIT statements, python's _posixsubprocess and libwebsockets' feature macros want the fork-then-exec path, which vfork() serves; python's os.fork() and libwebsockets' LWS_HAVE_FORK stay on fork() proper. fdsantest's vfork case follows vfork(). Two third-party suites need their source lists narrowed, because they call fork() from code that is 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 -- the nine fork_* entries and pipe_close_stdout_read_stdin -- so they were dead code being compiled only because fork() happened to be declared. * testing/ltp -- the open_posix_testsuite is filtered through the 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 is written to spare vfork() and task_fork(), which remain available. Where fork() is provided -- which today is everywhere -- nothing is dropped. Compatibility: the nuttx symbols this keys on do not exist yet. task_fork.c is built where CONFIG_TASK_FORK says task_fork() was built and, on a nuttx that has no CONFIG_ARCH_HAVE_TASK_FORK at all -- which is the pre-split one -- where CONFIG_ARCH_HAVE_FORK does. Today's fork() *is* task_fork(), so the test that has always covered that primitive keeps running, under its own name, and no coverage is lost across the transition. Both spellings are needed because CONFIG_TASK_FORK is optional on the nuttx side: ARCH_HAVE_TASK_FORK says the architecture can clone a task, TASK_FORK says this build asked for it. A follow-up removes the fallback once the split has landed. vfork_test() and fork_test() deliberately have no such fallback. Both check semantics a pre-split nuttx does not describe -- the parent suspension and the private copy -- and ARCH_HAVE_VFORK is the evidence that the split has landed. Mapping them onto ARCH_HAVE_FORK would also add a test to configurations that never had one, which is not free: vfork.c costs about 470 bytes of .text on armv7-m at -Os, and that is what put lm3s6965-ek:qemu-protected over its 128 KiB user flash region. Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com> Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .github | ||
| audioutils | ||
| benchmarks | ||
| boot | ||
| builtin | ||
| canutils | ||
| cmake | ||
| crypto | ||
| database | ||
| examples | ||
| fsutils | ||
| games | ||
| graphics | ||
| import | ||
| include | ||
| industry | ||
| inertial | ||
| interpreters | ||
| logging | ||
| lte | ||
| math | ||
| mlearning | ||
| netutils | ||
| nshlib | ||
| platform | ||
| sdr | ||
| system | ||
| tee | ||
| testing | ||
| tools | ||
| videoutils | ||
| wireless | ||
| .asf.yaml | ||
| .codespell-ignore-lines | ||
| .codespellrc | ||
| .gitignore | ||
| Application.mk | ||
| CMakeLists.txt | ||
| config.nims | ||
| Directory.mk | ||
| LICENSE | ||
| Make.defs | ||
| Makefile | ||
| NOTICE | ||
| README.md | ||
Application Folder
Contents
- General
- Directory Location
- Built-In Applications
- NuttShell (NSH) Built-In Commands
- Synchronous Built-In Commands
- Application Configuration File
- Example Built-In Application
- Building NuttX with Board-Specific Pieces Outside the Source Tree
General
This folder provides various applications found in sub-directories. These
applications are not inherently a part of NuttX but are provided to help you
develop your own applications. The apps/ directory is a break away part of
the configuration that you may choose to use or not.
Directory Location
The default application directory used by the NuttX build should be named
apps/ (or apps-x.y.z/ where x.y.z is the NuttX version number). This
apps/ directory should appear in the directory tree at the same level as the
NuttX directory. Like:
.
|- nuttx
|
`- apps
If all of the above conditions are TRUE, then NuttX will be able to find the application directory. If your application directory has a different name or is located at a different position, then you will have to inform the NuttX build system of that location. There are several ways to do that:
- You can define
CONFIG_APPS_DIRto be the full path to your application directory in the NuttX configuration file. - You can provide the path to the application directory on the command line
like:
make APPDIR=<path>ormake CONFIG_APPS_DIR=<path> - When you configure NuttX using
tools/configure.sh, you can provide that path to the application directory on the configuration command line like:./configure.sh -a <app-dir> <board-name>:<config-name>
Built-In Applications
NuttX also supports applications that can be started using a name string. In this case, application entry points with their requirements are gathered together in two files:
builtin/builtin_proto.h– Entry points, prototype functionbuiltin/builtin_list.h– Application specific information and requirements
The build occurs in several phases as different build targets are executed: (1) context, (2) depend, and (3) default (all). Application information is collected during the make context build phase.
To execute an application function:
exec_builtin() is defined in the apps/include/builtin/builtin.h.
NuttShell (NSH) Built-In Commands
One use of builtin applications is to provide a way of invoking your custom application through the NuttShell (NSH) command line. NSH will support a seamless method invoking the applications, when the following option is enabled in the NuttX configuration file:
CONFIG_NSH_BUILTIN_APPS=y
Applications registered in the apps/builtin/builtin_list.h file will then be
accessible from the NSH command line. If you type help at the NSH prompt, you
will see a list of the registered commands.
Synchronous Built-In Commands
By default, built-in commands started from the NSH command line will run asynchronously with NSH. If you want to force NSH to execute commands then wait for the command to execute, you can enable that feature by adding the following to the NuttX configuration file:
CONFIG_SCHED_WAITPID=y
The configuration option enables support for the waitpid() RTOS interface.
When that interface is enabled, NSH will use it to wait, sleeping until the
built-in command executes to completion.
Of course, even with CONFIG_SCHED_WAITPID=y defined, specific commands can
still be forced to run asynchronously by adding the ampersand (&) after the
NSH command.
Application Configuration File
The NuttX configuration uses kconfig-frontends tools and the NuttX
configuration file (.config) file. For example, the NuttX .config may have:
CONFIG_EXAMPLES_HELLO=y
This will select the apps/examples/hello in the following way:
- The top-level make will include
apps/examples/Make.defs apps/examples/Make.defswill setCONFIGURED_APPS += $(APPDIR)/examples/hellolike this:
ifneq ($(CONFIG_EXAMPLES_HELLO),)
CONFIGURED_APPS += $(APPDIR)/examples/hello
endif
Example Built-In Application
An example application skeleton can be found under the examples/hello
sub-directory. This example shows how a builtin application can be added to the
project. One must:
-
Create sub-directory as: progname
-
In this directory there should be:
- A
Make.defsfile that would be included by theapps/Makefile - A
Kconfigfile that would be used by the configuration tool (see the filekconfig-language.txtin the NuttX tools repository). ThisKconfigfile should be included by theapps/Kconfigfile - A
Makefile, and - The application source code.
- A
-
The application source code should provide the entry point:
main() -
Set the requirements in the file:
Makefile, specifically the lines:PROGNAME = progname PRIORITY = SCHED_PRIORITY_DEFAULT STACKSIZE = 768 ASRCS = asm source file list as a.asm b.asm ... CSRCS = C source file list as foo1.c foo2.c .. -
The
Make.defsfile should include a line like:ifneq ($(CONFIG_PROGNAME),) CONFIGURED_APPS += progname endif
Building NuttX with Board-Specific Pieces Outside the Source Tree
Q: Has anyone come up with a tidy way to build NuttX with board- specific pieces outside the source tree?
A: Here are three:
-
There is a make target called
make export. It will build NuttX, then bundle all of the header files, libraries, startup objects, and other build components into a.zipfile. You can move that.zipfile into any build environment you want. You can even build NuttX under a DOSCMDwindow.This make target is documented in the top level
nuttx/README.txt. -
You can replace the entire
apps/directory. If there is nothing in theapps/directory that you need, you can defineCONFIG_APPS_DIRin your.configfile so that it points to a different, custom application directory.You can copy any pieces that you like from the old apps/directory to your custom apps directory as necessary.
This is documented in
NuttX/boards/README.txtandNuttX Porting Guideonline at https://cwiki.apache.org/confluence/display/NUTTX/Porting+Guide. -
If you like the random collection of stuff in the
apps/directory but just want to expand the existing components with your own, external sub-directory then there is an easy way to that too: You just create a symbolic link in theapps/directory that redirects to your application sub-directory.In order to be incorporated into the build, the directory that you link under the
apps/directory should contain (1) aMakefilethat supports thecleananddistcleantargets (see otherMakefiles for examples), and (2) a tinyMake.defsfile that simply adds the custom build directories to the variableCONFIGURED_APPSlike:CONFIGURED_APPS += my_directory1 my_directory2The
apps/Makefilewill always automatically check for the existence of subdirectories containing aMakefileand aMake.defsfile. TheMakefilewill be used only to support cleaning operations. The Make.defs file provides the set of directories to be built; these directories must also contain aMakefile. ThatMakefilemust be able to build the sources and add the objects to theapps/libapps.aarchive. (see otherMakefiles for examples). It should support the all, install, context, and depend targets.apps/Makefiledoes not depend on any hardcoded lists of directories. Instead, it does a wildcard search to find all appropriate directories. This means that to install a new application, you simply have to copy the directory (or link it) into theapps/directory. If the new directory includes aMakefileandMake.defsfile, then it will automatically be included in the build.If the directory that you add also includes a
Kconfigfile, then it will automatically be included in the NuttX configuration system as well.apps/Makefileuses a tool atapps/tools/mkkconfig.shthat dynamically builds theapps/Kconfigfile at pre-configuration time.You could, for example, create a script called
install.shthat installs a custom application, configuration, and board specific directory:a) Copy
MyBoarddirectory toboards/MyBoard. b) Add a symbolic link toMyApplicationatapps/external. c) Configure NuttX, usually by:tools/configure.sh MyBoard:MyConfigurationUse of the name
apps/externalis suggested because that name is included in the.gitignorefile and will save you some nuisance when working with GIT.
Export restrictions
This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.
The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this Apache Software Foundation distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.
The following provides more details on the included cryptographic software: https://tls.mbed.org/supported-ssl-ciphersuites. https://github.com/intel/tinycrypt