This is an automated email from the ASF dual-hosted git repository. archer pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 2615513a45fd79e198209f324a8285f1fc75b903 Author: Filipe Cavalcanti <[email protected]> AuthorDate: Thu Mar 26 11:24:23 2026 -0300 docs: add CMake documentation for RISC-V Espressif devices Update NuttX documentation with CMake usage instructions for Espressif devices. Signed-off-by: Filipe Cavalcanti <[email protected]> --- Documentation/platforms/risc-v/esp32c3/index.rst | 69 +++++++++++++++++++++ Documentation/platforms/risc-v/esp32c6/index.rst | 78 +++++++++++++++++++++++ Documentation/platforms/risc-v/esp32h2/index.rst | 74 +++++++++++++++++++++- Documentation/platforms/risc-v/esp32p4/index.rst | 79 ++++++++++++++++++++++++ 4 files changed, 298 insertions(+), 2 deletions(-) diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst index 24ac4e407f3..bc2ad608463 100644 --- a/Documentation/platforms/risc-v/esp32c3/index.rst +++ b/Documentation/platforms/risc-v/esp32c3/index.rst @@ -178,6 +178,75 @@ Now opening the serial port with a terminal emulator should show the NuttX conso nsh> uname -a NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 19:58:56 risc-v esp32c3-devkit +Building with CMake +------------------- + +General CMake usage (out-of-tree build, ``menuconfig`` target, and so on) is described in +:doc:`/quickstart/compiling_cmake`. The ESP32-C3 common arch enables post-build steps that +produce ``nuttx.bin`` (and related images) under the **CMake binary directory**; the build +log also prints suggested ``esptool.py`` command lines for your layout. + +Example (NuttX shell defconfig, Ninja generator):: + + $ cd nuttx + $ cmake -B build -DBOARD_CONFIG=esp32c3-devkit:nsh -GNinja + $ cmake --build build + +To reconfigure the tree after changing options (same as other NuttX CMake boards):: + + $ cmake --build build -t menuconfig + $ cmake --build build + +Persistent HAL cache (``NXTMPDIR``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pass ``-DNXTMPDIR=ON`` at **configure** time to reuse a persistent clone of the +``esp-hal-3rdparty`` repository under ``nuttx/../nxtmpdir/esp-hal-3rdparty``. CMake checks +the expected revision; if it does not match, the cache directory is refreshed. This cuts +repeat configure/build time when the HAL checkout would otherwise be re-fetched into the +binary directory. + +Example:: + + $ cmake -B build -DBOARD_CONFIG=esp32c3-devkit:nsh -DNXTMPDIR=ON -GNinja + $ cmake --build build + +MCUBoot: building the 2nd-stage bootloader (``-t bootloader``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For configurations that use MCUboot, build the bootloader the same way as +with Make, but via the CMake target:: + + $ cmake --build build -t bootloader + +The image is installed as ``mcuboot-esp32c3.bin`` in the NuttX **source** directory (not +inside ``build/``). + +.. note:: + + Flashing paths differ from the pure-Make flow: the application image is under your CMake + build directory (for example ``build/nuttx.bin``), while MCUboot binaries live next to + ``nuttx`` sources. + +Target flashing (``-t flash``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After a successful CMake build, you can flash the chip with the ``flash`` custom target. +This is the CMake-side equivalent of the Make ``FLASH`` logic in +``tools/espressif/Config.mk``. + +**Serial port:** you must set ``ESPTOOL_PORT`` to a non-empty value (for example +``/dev/ttyUSB0``). If it is unset or empty, the flash step fails. + +Example:: + + $ export ESPTOOL_PORT=/dev/ttyUSB0 + $ cmake --build build -t flash + +Or for a single invocation:: + + $ ESPTOOL_PORT=/dev/ttyUSB0 cmake --build build -t flash + Debugging ========= diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst b/Documentation/platforms/risc-v/esp32c6/index.rst index 7a58a99390f..4d748e8fc16 100644 --- a/Documentation/platforms/risc-v/esp32c6/index.rst +++ b/Documentation/platforms/risc-v/esp32c6/index.rst @@ -178,8 +178,86 @@ Now opening the serial port with a terminal emulator should show the NuttX conso nsh> uname -a NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 19:42:41 risc-v esp32c6-devkitc +Building with CMake +------------------- + +General CMake usage (out-of-tree build, ``menuconfig`` target, and so on) is described in +:doc:`/quickstart/compiling_cmake`. The ESP32-C6 common arch enables post-build steps that +produce ``nuttx.bin`` (and related images) under the **CMake binary directory**; the build +log also prints suggested ``esptool.py`` command lines for your layout. + +Example (NuttX shell defconfig, Ninja generator):: + + $ cd nuttx + $ cmake -B build -DBOARD_CONFIG=esp32c6-devkitc:nsh -GNinja + $ cmake --build build + +To reconfigure the tree after changing options (same as other NuttX CMake boards):: + + $ cmake --build build -t menuconfig + $ cmake --build build + +Persistent HAL cache (``NXTMPDIR``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pass ``-DNXTMPDIR=ON`` at **configure** time to reuse a persistent clone of the +``esp-hal-3rdparty`` repository under ``nuttx/../nxtmpdir/esp-hal-3rdparty``. CMake checks +the expected revision; if it does not match, the cache directory is refreshed. This cuts +repeat configure/build time when the HAL checkout would otherwise be re-fetched into the +binary directory. + +Example:: + + $ cmake -B build -DBOARD_CONFIG=esp32c6-devkitc:nsh -DNXTMPDIR=ON -GNinja + $ cmake --build build + +MCUBoot: building the 2nd-stage bootloader (``-t bootloader``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For configurations that use MCUboot, build the bootloader the same way as +with Make, but via the CMake target:: + + $ cmake --build build -t bootloader + +The image is installed as ``mcuboot-esp32c6.bin`` in the NuttX **source** directory (not +inside ``build/``). + +.. note:: + + Flashing paths differ from the pure-Make flow: the application image is under your CMake + build directory (for example ``build/nuttx.bin``), while MCUboot binaries live next to + ``nuttx`` sources. Use the ``esptool.py`` hints printed at the end of the build, or the + same offsets as documented for ``make flash`` with ``ESPTOOL_BINDIR``. + +Target flashing (``-t flash``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After a successful CMake build, you can flash the chip with the ``flash`` custom target. +This is the CMake-side equivalent of the Make ``FLASH`` logic in +``tools/espressif/Config.mk``. + +**Serial port:** you must set ``ESPTOOL_PORT`` to a non-empty value (for example +``/dev/ttyUSB0``). If it is unset or empty, the flash step fails. + +Example:: + + $ export ESPTOOL_PORT=/dev/ttyUSB0 + $ cmake --build build -t flash + +Or for a single invocation:: + + $ ESPTOOL_PORT=/dev/ttyUSB0 cmake --build build -t flash + .. _esp32c6_debug: +CMake limitations +^^^^^^^^^^^^^^^^^^ + +The following is **not** supported when building with CMake yet; use the Make-based build instead: + +* **ULP / LP core** — Low-power coprocessor support (``CONFIG_ESPRESSIF_USE_LP_CORE``) is + not wired up for CMake (ULP/LP integration is TODO). + Debugging ========= diff --git a/Documentation/platforms/risc-v/esp32h2/index.rst b/Documentation/platforms/risc-v/esp32h2/index.rst index 8b8936a441a..12a7d64f588 100644 --- a/Documentation/platforms/risc-v/esp32h2/index.rst +++ b/Documentation/platforms/risc-v/esp32h2/index.rst @@ -134,11 +134,11 @@ where: Flashing NSH Example -------------------- -This example shows how to build and flash the ``nsh`` defconfig for the ESP32-H2-DevKitM-1 board:: +This example shows how to build and flash the ``nsh`` defconfig for the ESP32-H2-DevKit board:: $ cd nuttx $ make distclean - $ ./tools/configure.sh esp32h2-devkitc:nsh + $ ./tools/configure.sh esp32h2-devkit:nsh $ make -j$(nproc) When the build is complete, the firmware can be flashed to the board using the command:: @@ -179,6 +179,76 @@ Now opening the serial port with a terminal emulator should show the NuttX conso nsh> uname -a NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 20:16:34 risc-v esp32h2-devkit +Building with CMake +------------------- + +General CMake usage (out-of-tree build, ``menuconfig`` target, and so on) is described in +:doc:`/quickstart/compiling_cmake`. The ESP32-H2 common arch enables post-build steps that +produce ``nuttx.bin`` (and related images) under the **CMake binary directory**; the build +log also prints suggested ``esptool.py`` command lines for your layout. + +Example (NuttX shell defconfig, Ninja generator):: + + $ cd nuttx + $ cmake -B build -DBOARD_CONFIG=esp32h2-devkit:nsh -GNinja + $ cmake --build build + +To reconfigure the tree after changing options (same as other NuttX CMake boards):: + + $ cmake --build build -t menuconfig + $ cmake --build build + +Persistent HAL cache (``NXTMPDIR``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pass ``-DNXTMPDIR=ON`` at **configure** time to reuse a persistent clone of the +``esp-hal-3rdparty`` repository under ``nuttx/../nxtmpdir/esp-hal-3rdparty``. CMake checks +the expected revision; if it does not match, the cache directory is refreshed. This cuts +repeat configure/build time when the HAL checkout would otherwise be re-fetched into the +binary directory. + +Example:: + + $ cmake -B build -DBOARD_CONFIG=esp32h2-devkit:nsh -DNXTMPDIR=ON -GNinja + $ cmake --build build + +MCUBoot: building the 2nd-stage bootloader (``-t bootloader``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For configurations that use MCUboot, build the bootloader the same way as +with Make, but via the CMake target:: + + $ cmake --build build -t bootloader + +The image is installed as ``mcuboot-esp32h2.bin`` in the NuttX **source** directory (not +inside ``build/``). + +.. note:: + + Flashing paths differ from the pure-Make flow: the application image is under your CMake + build directory (for example ``build/nuttx.bin``), while MCUboot binaries live next to + ``nuttx`` sources. Use the ``esptool.py`` hints printed at the end of the build, or the + same offsets as documented for ``make flash`` with ``ESPTOOL_BINDIR``. + +Target flashing (``-t flash``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After a successful CMake build, you can flash the chip with the ``flash`` custom target. +This is the CMake-side equivalent of the Make ``FLASH`` logic in +``tools/espressif/Config.mk``. + +**Serial port:** you must set ``ESPTOOL_PORT`` to a non-empty value (for example +``/dev/ttyUSB0``). If it is unset or empty, the flash step fails. + +Example:: + + $ export ESPTOOL_PORT=/dev/ttyUSB0 + $ cmake --build build -t flash + +Or for a single invocation:: + + $ ESPTOOL_PORT=/dev/ttyUSB0 cmake --build build -t flash + Debugging ========= diff --git a/Documentation/platforms/risc-v/esp32p4/index.rst b/Documentation/platforms/risc-v/esp32p4/index.rst index 616c7b08bdc..7a4b6bbdcab 100644 --- a/Documentation/platforms/risc-v/esp32p4/index.rst +++ b/Documentation/platforms/risc-v/esp32p4/index.rst @@ -114,6 +114,85 @@ Where ``<port>`` is the serial/USB port connected to your board. Please check `Supported Boards`_ for the actual commands. +Building with CMake +------------------- + +General CMake usage (out-of-tree build, ``menuconfig`` target, and so on) is described in +:doc:`/quickstart/compiling_cmake`. The ESP32-P4 arch uses the shared Espressif RISC-V +integration, which enables post-build steps that produce ``nuttx.bin`` (and related images) +under the **CMake binary directory**; the build log also prints suggested ``esptool.py`` +command lines for your layout (including the ESP32-P4 image offset when applicable). + +Example (NuttX shell defconfig, Ninja generator):: + + $ cd nuttx + $ cmake -B build -DBOARD_CONFIG=esp32p4-function-ev-board:nsh -GNinja + $ cmake --build build + +To reconfigure the tree after changing options (same as other NuttX CMake boards):: + + $ cmake --build build -t menuconfig + $ cmake --build build + +Persistent HAL cache (``NXTMPDIR``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pass ``-DNXTMPDIR=ON`` at **configure** time to reuse a persistent clone of the +``esp-hal-3rdparty`` repository under ``nuttx/../nxtmpdir/esp-hal-3rdparty``. CMake checks +the expected revision; if it does not match, the cache directory is refreshed. This cuts +repeat configure/build time when the HAL checkout would otherwise be re-fetched into the +binary directory. + +Example:: + + $ cmake -B build -DBOARD_CONFIG=esp32p4-function-ev-board:nsh -DNXTMPDIR=ON -GNinja + $ cmake --build build + +MCUBoot: building the 2nd-stage bootloader (``-t bootloader``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For configurations that use MCUboot, build the bootloader the same way as +with Make, but via the CMake target:: + + $ cmake --build build -t bootloader + +The image is installed as ``mcuboot-esp32p4.bin`` in the NuttX **source** directory (not +inside ``build/``). + +.. note:: + + Flashing paths differ from the pure-Make flow: the application image is under your CMake + build directory (for example ``build/nuttx.bin``), while MCUboot binaries live next to + ``nuttx`` sources. Use the ``esptool.py`` hints printed at the end of the build, or the + same offsets as documented for ``make flash`` with ``ESPTOOL_BINDIR``. + +Target flashing (``-t flash``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After a successful CMake build, you can flash the chip with the ``flash`` custom target. +This is the CMake-side equivalent of the Make ``FLASH`` logic in +``tools/espressif/Config.mk``. + +**Serial port:** you must set ``ESPTOOL_PORT`` to a non-empty value (for example +``/dev/ttyUSB0``). If it is unset or empty, the flash step fails. + +Example:: + + $ export ESPTOOL_PORT=/dev/ttyUSB0 + $ cmake --build build -t flash + +Or for a single invocation:: + + $ ESPTOOL_PORT=/dev/ttyUSB0 cmake --build build -t flash + +CMake limitations +^^^^^^^^^^^^^^^^^^ + +The following is **not** supported when building with CMake yet; use the Make-based build instead: + +* **ULP / LP core** — Low-power coprocessor support (``CONFIG_ESPRESSIF_USE_LP_CORE``) is + not wired up for CMake (ULP/LP integration is TODO). + .. _esp32p4_debug: Debugging
