1. Core Architectural Principles (nuttx/INVIOLABLES.md)
- Strict POSIX & ANSI Compliance: Prefer standard POSIX APIs (
open,read,write,ioctl,poll,pthread, BSD sockets, POSIX timers/mqueues) over custom APIs. - Modular Layering:
- Upper-Half Drivers (
nuttx/drivers/): Architecture-independent driver logic that registers VFS character/block devices (e.g.,/dev/ttyS0,/dev/spi0) and handles locking/buffering. - Lower-Half Drivers (
nuttx/arch/ornuttx/boards/): SoC- or board-specific hardware implementation passed to the upper half via an ops vtable. - Internal Porting Interface (
up_*): Defined innuttx/include/nuttx/arch.hfor CPU/SoC operations andnuttx/include/nuttx/board.hfor board-level initialization.
- Upper-Half Drivers (
- Three Build Modes:
CONFIG_BUILD_FLAT: Unprotected flat address space (single binary).CONFIG_BUILD_PROTECTED: MPU-isolated user (apps) and kernel (nuttx) spaces bridged vianuttx/syscall/.CONFIG_BUILD_KERNEL: MMU-isolated virtual address spaces (nuttx/sched/addrenv/); user processes loaded dynamically vianuttx/binfmt/.
2. Configuration & Build Workflows
Always run configuration and build commands from the nuttx/ directory (or specify -S nuttx -B build for CMake).
Option A: CMake + Ninja (Recommended for Fast Incremental Builds)
- Ensure
nuttx/.configdoes not exist from a previous Make build (make -C nuttx distcleanif needed). - Configure a
<board>:<config>target (e.g.,sim:nsh):cmake -S nuttx -B build -DBOARD_CONFIG=sim:nsh -GNinja - Build:
cmake --build build - Reconfigure via menuconfig (if needed):
cmake --build build -t menuconfig
Option B: GNU Make
- Configure
<board>:<config>:
(List all available board configs withcd nuttx && ./tools/configure.sh sim:nsh./tools/configure.sh -L.) - Build:
make -C nuttx -j$(sysctl -n hw.ncpu 2>/dev/null || nproc) - Clean / Distclean:
make -C nuttx clean # Keep .config, remove objects make -C nuttx distclean # Remove .config and all generated files
3. Common Development Tasks
Adding or Modifying a Driver
- Check
nuttx/include/nuttx/for the subsystem's upper-half interface header (e.g.,nuttx/serial/serial.h,nuttx/sensors/sensor.h,nuttx/spi/spi.h). - Keep hardware register manipulation strictly in
nuttx/arch/<arch>/src/<chip>/and board pin/clock wiring innuttx/boards/<arch>/<chip>/<board>/src/. - Expose portable upper-half driver logic in
nuttx/drivers/<subsystem>/and wire it intoKconfig,Make.defs, andCMakeLists.txt.
Adding a New Board (e.g., Renesas RA4M1)
- Register in
nuttx/boards/Kconfigin 3 places:config ARCH_BOARD_<BOARD_UPPER>inside the target boardchoiceblock (selectARCH_HAVE_LEDSif the board has controllable LEDs).default "<board-name>" if ARCH_BOARD_<BOARD_UPPER>underconfig ARCH_BOARD.if ARCH_BOARD_<BOARD_UPPER>/source "boards/<arch>/<chip>/<board-name>/Kconfig"/endifat the bottom.
- Create
nuttx/boards/<arch>/<chip>/<board-name>/containing:KconfigandCMakeLists.txtinclude/board.h(clocks, pin muxing, active-high/low LED definitions, GPIO/PWM mappings)scripts/Make.defsandscripts/<board-name>.ldsrc/(Makefile,CMakeLists.txt,<board-name>.h,<chip>_boot.c,<chip>_bringup.c,<chip>_autoleds.c,<chip>_userleds.c, and optional<chip>_gpio.c/<chip>_pwm.c)configs/nsh/defconfig
- Add Documentation: Create
nuttx/Documentation/platforms/<arch>/<chip>/boards/<board-name>/index.rstcovering MCU specs, pin mappings (LEDs, UART, PWM, GPIO), and flashing instructions. - Validate: Run
checkpatch.shon all.c/.hfiles, verify config discovery with./nuttx/tools/configure.sh -L | grep <board-name>, and compile-check bothCONFIG_ARCH_LEDSandCONFIG_USERLED_LOWER+ driver branches. - See Board Porting & RA4M1 Reference for the complete step-by-step guide, RA4M1 specifics (
R7FA4M1ABxxFP/FM/FL,ra4m1_pinmap.h,.id_codesection), and standalone compiler verification whenkconfiglib/kconfig-confis not installed.
Adding a User-Space Built-In Application
- Create
apps/<category>/<appname>/with:Kconfig(definingCONFIG_<CATEGORY>_<APPNAME>)Make.defs(appendingCONFIGURED_APPS += $(APPDIR)/<category>/<appname>when enabled)Makefile(settingPROGNAME,PRIORITY,STACKSIZE,MAINSRC, and including$(APPDIR)/Application.mk)CMakeLists.txt(callingnuttx_add_application(...))
- See Apps & NSH Reference for complete templates.
4. Validation & Coding Standard Checks
NuttX enforces a strict C89/C99 coding standard (indented GNU-style braces, block comments /* ... */, explicit FAR/CODE annotations where applicable).
- Run
checkpatch.shbefore finishing any code changes:
(Note: Only pass./nuttx/tools/checkpatch.sh -f <path/to/modified_file.c> <path/to/header.h>.cand.hfiles ifcmake-formatis not installed on the host, ascheckpatch.shinvokescmake-formatonCMakeLists.txt.) Or check the latest git commit / working tree diff:git -C nuttx diff | ./nuttx/tools/checkpatch.sh - - Verify Configuration Discovery:
./nuttx/tools/configure.sh -L | grep <board-name> - Verify Compilation: Build the affected board config (or
sim:nshfor generic kernel/app changes) and ensure zero compiler warnings. Ifkconfigliborkconfig-confis unavailable on the host, run the standalonearm-none-eabi-gcc -fsyntax-only -Wall -Werrorverification documented in Board Porting & RA4M1 Reference.
5. Detailed References
Load these references on demand when working in specific areas: