Index of every page on this site: llms.txt
All skills
domesticmouse avatar

/nuttx-architecture

@606a5d5
Run it yourself

Architectural guide and development workflows for the Apache NuttX RTOS (`nuttx`) and application suite (`apps`) repositories. Use this skill when navigating, configuring, building, debugging, or adding drivers, boards, kernel features, or user-space applications in NuttX.

  • 4 files
  • 26.2 KB
  • Updated 4 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/domesticmouse/skills/nuttx-architecture

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈73 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈5k more on demand in 3 files.

Description uses 3.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈294 characters, or 3.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

1. Core Architectural Principles (nuttx/INVIOLABLES.md)

  1. Strict POSIX & ANSI Compliance: Prefer standard POSIX APIs (open, read, write, ioctl, poll, pthread, BSD sockets, POSIX timers/mqueues) over custom APIs.
  2. 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/ or nuttx/boards/): SoC- or board-specific hardware implementation passed to the upper half via an ops vtable.
    • Internal Porting Interface (up_*): Defined in nuttx/include/nuttx/arch.h for CPU/SoC operations and nuttx/include/nuttx/board.h for board-level initialization.
  3. Three Build Modes:
    • CONFIG_BUILD_FLAT: Unprotected flat address space (single binary).
    • CONFIG_BUILD_PROTECTED: MPU-isolated user (apps) and kernel (nuttx) spaces bridged via nuttx/syscall/.
    • CONFIG_BUILD_KERNEL: MMU-isolated virtual address spaces (nuttx/sched/addrenv/); user processes loaded dynamically via nuttx/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)

  1. Ensure nuttx/.config does not exist from a previous Make build (make -C nuttx distclean if needed).
  2. Configure a <board>:<config> target (e.g., sim:nsh):
    cmake -S nuttx -B build -DBOARD_CONFIG=sim:nsh -GNinja
  3. Build:
    cmake --build build
  4. Reconfigure via menuconfig (if needed):
    cmake --build build -t menuconfig

Option B: GNU Make

  1. Configure <board>:<config>:
    cd nuttx && ./tools/configure.sh sim:nsh
    (List all available board configs with ./tools/configure.sh -L.)
  2. Build:
    make -C nuttx -j$(sysctl -n hw.ncpu 2>/dev/null || nproc)
  3. 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

  1. 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).
  2. Keep hardware register manipulation strictly in nuttx/arch/<arch>/src/<chip>/ and board pin/clock wiring in nuttx/boards/<arch>/<chip>/<board>/src/.
  3. Expose portable upper-half driver logic in nuttx/drivers/<subsystem>/ and wire it into Kconfig, Make.defs, and CMakeLists.txt.

Adding a New Board (e.g., Renesas RA4M1)

  1. Register in nuttx/boards/Kconfig in 3 places:
    • config ARCH_BOARD_<BOARD_UPPER> inside the target board choice block (select ARCH_HAVE_LEDS if the board has controllable LEDs).
    • default "<board-name>" if ARCH_BOARD_<BOARD_UPPER> under config ARCH_BOARD.
    • if ARCH_BOARD_<BOARD_UPPER> / source "boards/<arch>/<chip>/<board-name>/Kconfig" / endif at the bottom.
  2. Create nuttx/boards/<arch>/<chip>/<board-name>/ containing:
    • Kconfig and CMakeLists.txt
    • include/board.h (clocks, pin muxing, active-high/low LED definitions, GPIO/PWM mappings)
    • scripts/Make.defs and scripts/<board-name>.ld
    • src/ (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
  3. Add Documentation: Create nuttx/Documentation/platforms/<arch>/<chip>/boards/<board-name>/index.rst covering MCU specs, pin mappings (LEDs, UART, PWM, GPIO), and flashing instructions.
  4. Validate: Run checkpatch.sh on all .c/.h files, verify config discovery with ./nuttx/tools/configure.sh -L | grep <board-name>, and compile-check both CONFIG_ARCH_LEDS and CONFIG_USERLED_LOWER + driver branches.
  5. See Board Porting & RA4M1 Reference for the complete step-by-step guide, RA4M1 specifics (R7FA4M1ABxxFP/FM/FL, ra4m1_pinmap.h, .id_code section), and standalone compiler verification when kconfiglib/kconfig-conf is not installed.

Adding a User-Space Built-In Application

  1. Create apps/<category>/<appname>/ with:
    • Kconfig (defining CONFIG_<CATEGORY>_<APPNAME>)
    • Make.defs (appending CONFIGURED_APPS += $(APPDIR)/<category>/<appname> when enabled)
    • Makefile (setting PROGNAME, PRIORITY, STACKSIZE, MAINSRC, and including $(APPDIR)/Application.mk)
    • CMakeLists.txt (calling nuttx_add_application(...))
  2. 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).

  1. Run checkpatch.sh before finishing any code changes:
    ./nuttx/tools/checkpatch.sh -f <path/to/modified_file.c> <path/to/header.h>
    (Note: Only pass .c and .h files if cmake-format is not installed on the host, as checkpatch.sh invokes cmake-format on CMakeLists.txt.) Or check the latest git commit / working tree diff:
    git -C nuttx diff | ./nuttx/tools/checkpatch.sh -
  2. Verify Configuration Discovery:
    ./nuttx/tools/configure.sh -L | grep <board-name>
  3. Verify Compilation: Build the affected board config (or sim:nsh for generic kernel/app changes) and ensure zero compiler warnings. If kconfiglib or kconfig-conf is unavailable on the host, run the standalone arm-none-eabi-gcc -fsyntax-only -Wall -Werror verification documented in Board Porting & RA4M1 Reference.

5. Detailed References

Load these references on demand when working in specific areas:

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 606a5d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 weeks ago

README badge

README badge for domesticmouse/skills/nuttx-architecture