!boards: Simplify NuttX initialization

[linguini1]

Summary

BREAKING CHANGE

This change simplifies the NuttX initialization logic by:

• Replacing NSH_ARCHINIT with CONFIG_BOARD_LATE_INITIALIZE in defconfigs
• Removing BOARDIOC_INIT/board_app_initialize
• Ensuring that board_late_initialize performs the same function as
  board_app_initialize did so any defconfigs relying on NSH_ARCHINIT will not
  break.

This is related to #11321.

Twin PR in NuttX apps should be merged at the same time: apache/nuttx-apps#3405

Impact

Almost every single board/configuration in the NuttX source tree, since many
relied on NSH for initialization.

This is a breaking change that removes the user's ability to use BOARDIOC_INIT
as well. Users are provided with quick-fixes in the commit messages for how to
fix any breakages. BOARDIOC_FINALINIT should be used instead for applications
that truly require full control over the initialization process. For every other
application, BOARD_LATE_INITIALIZE should be enabled to have the NuttX kernel
perform initialization before launching into the app.

Testing

I will be testing on the platforms available to me (simulators and whatever
hardware I own). Testing from community members with hardware across the
architectures affected would be greatly appreciated. If you do want to help with
testing, please provide logs in the PR comments for the affected defconfigs you
tested.

Testing of applications can be seen in the twin PR: apache/nuttx-apps#3405

OS Test logs

• sim:nsh: sim-nsh.txt
• qemu-armv8a:nsh: qemu-armv8a-nsh.txt
• qemu-armv7a:nsh: qemu-armv7a-nsh.txt
• rv-virt:nsh: rv-virt-nsh.txt
• raspberrypi-4b:sd: rpi4b-sd.txt (verify SD filesystem is mounted + ostest)
• samv71-xult:nsh, samv71-xult:netnsh: See comment
• esp32c3-xiao:ble: esp32c3-xiao.txt
• Avaota A1: Avaota A1
• StarPro64: StarPro64
• Oz64: Oz64
• Espressif CI: Espressif CI

[linguini1]

Notes for reviewers on the initial draft:

1. This is obviously a huge change so it would be great to have some testing on platforms which I am not able to test on my own hardware (i.e. any STM32, the Espressif internal CI would be good to run, anyone with tricore/renesas/sparc/etc. boards).
2. Unfortunately I don't think this can be split across multiple PRs, since removing NSH_ARCHINIT relies on board_late_initialize to have identical contents to board_app_initialize. The removal of BOARDIOC_INIT might be able to get split but since this change is going to touch almost every board, it should just be done simultaneously to reduce the chance of making errors. I am open to suggestions as I realize this is a monster PR, but I can't think of a better approach.
3. I think I will eventually squash all of the commits replacing board_app_initialize -> board_late_initialize into one, since anyone bisecting later would probably treat this entire change as one unit. Please let me know if it's advisable to squash in any other way as well. For now this helps me keep track of everything while the change is under review
4. I think this should go surprisingly smoothly for most configurations; a majority of the boards that are affected had a very standard setup for app_init/late_init where they both did the exact same thing
5. Anything beyond removing BOARDIOC_INIT, board_app_initialize and NSH_ARCHINIT are outside of the scope of this PR. I will not be addressing anything else in the boot process that is independent from these changes (i.e. non-standard naming of files for boot logic, etc.)

[fdcavalcanti]

@linguini1 this is a great initiative.
Please share your process or a board example and I can do it on ESP boards.

[linguini1]

this is a great initiative. Please share your process or a board example and I can do it on ESP boards.

Hi @fdcavalcanti, if you're talking about making the changes, I think all ESP boards should be included in this patch already (xtensa/risc-v). They were actually quite easy since the board_late_init and board_app_init logic were pretty much identical.

If you're talking about how to test, the process would be to configure the build system for one of the modified ESP32 configurations (i.e. nsh) and just boot into NuttX, check that things look okay and run ostest.

Hope I understood correctly, thanks for your help!

[linguini1]

Okay, it should all be good now! Thanks so much for the testing @fdcavalcanti ! I really appreciate your help!

[cederom]

Very cool, thank you @linguini1 for this cleanup, lots of work and time, kudos!

In the next step we should create a good documentation of the whole boot process :D

[linguini1]

In the next step we should create a good documentation of the whole boot process :D

I agree. That will be on the roster soon while I work on getting my altimeter running. I have to first get the nuttx-apps twin PR merged, then do the last step which removes the BOARDIOC_INIT command altogether.

[lupyuen]

Tested OK on Arm64 + RISC-V 64-bit SBCs: Avaota-A1, StarPro64, Oz64. Thanks :-)

• Avaota-A1 Log
• StarPro64 EIC7700X Log
• Oz64 SG2000 Log

$ git clone https://github.com/linguini1/nuttx nuttx --branch byebye-archinit
$ git clone https://github.com/linguini1/nuttx-apps apps --branch byebye-archinit
...
nsh> uname -a
NuttX 0.0.0 a5b265711e Apr 29 2026 13:56:15 ...
nsh> ostest
ostest_main: Exiting with status 0

[lupyuen]

FYI I'm trying to understand the Init Sequence before and after the PR. Here's what the LLM drew, not sure if it's correct 🤔 https://docs.google.com/document/d/1o8z4JIUp88NhCPftAZ28GOHpy9ERGaxfLRgEXHd5mUo/edit?tab=t.0

sequenceDiagram
    participant Hardware as MCU/Hardware
    participant Kernel as nx_start (Kernel)
    participant Board as Board Logic (*_boot.c)
    participant AppInit as Board App Init (*_appinit.c)
    participant NSH as Application (NSH)

    Note over Hardware, NSH: BEFORE PR #18408 (Legacy Flow)
    Hardware->>Kernel: Reset / Entry Point
    Kernel->>Board: board_initialize() (Early)
    Kernel->>NSH: task_create("nsh_main")
    activate NSH
    NSH->>Kernel: boardctl(BOARDIOC_INIT)
    Kernel->>AppInit: board_app_initialize()
    AppInit->>Kernel: Register Drivers (/dev/sensor0, etc.)
    deactivate NSH
    Note over NSH: Shell becomes ready with drivers

Loading

sequenceDiagram
    participant Hardware as MCU/Hardware
    participant Kernel as nx_start (Kernel)
    participant Board as Board Logic (*_boot.c)
    participant AppInit as Board App Init (*_appinit.c)
    participant NSH as Application (NSH)

    Note over Hardware, NSH: AFTER PR #18408 (Simplified Flow)
    Hardware->>Kernel: Reset / Entry Point
    Kernel->>Board: board_initialize() (Early)
    Kernel->>Board: board_late_initialize() (New Unified Hook)
    Board->>Kernel: Register Drivers (/dev/sensor0, etc.)
    Kernel->>NSH: task_create("nsh_main")
    activate NSH
    Note over NSH: Shell starts. Drivers already registered
    deactivate NSH

Loading

[linguini1]

@michallenc and @acassis, please take look; the change requests are now resolved.

[linguini1]

Rebased onto master again due to changes with QEMU VGA support.

[lupyuen]

Tested OK on Arm64 + RISC-V 64-bit SBCs: Avaota-A1, StarPro64, Oz64. Thanks :-)

• Avaota-A1 Log
• StarPro64 EIC7700X Log
• Oz64 SG2000 Log

$ git clone https://github.com/linguini1/nuttx nuttx --branch byebye-archinit
$ git clone https://github.com/linguini1/nuttx-apps apps --branch byebye-archinit
...
nsh> uname -a
NuttX 0.0.0 7f2d327695 May  2 2026 16:13:54 ...
nsh> ostest
ostest_main: Exiting with status 0