diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst index de181ca692b..0f06329e4ed 100644 --- a/Documentation/platforms/risc-v/esp32c3/index.rst +++ b/Documentation/platforms/risc-v/esp32c3/index.rst @@ -35,16 +35,16 @@ check for the current compiler version being used. For instance: .. code-block:: - ############################################################################### - # Build image for tool required by RISCV builds - ############################################################################### - FROM nuttx-toolchain-base AS nuttx-toolchain-riscv - # Download the latest RISCV GCC toolchain prebuilt by xPack - RUN mkdir riscv-none-elf-gcc && \ - curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \ - | tar -C riscv-none-elf-gcc --strip-components 1 -xz + ############################################################################### + # Build image for tool required by RISCV builds + ############################################################################### + FROM nuttx-toolchain-base AS nuttx-toolchain-riscv + # Download the latest RISCV GCC toolchain prebuilt by xPack + RUN mkdir riscv-none-elf-gcc && \ + curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ + | tar -C riscv-none-elf-gcc --strip-components 1 -xz -It uses the xPack's prebuilt toolchain based on GCC 12.3.0. +It uses the xPack's prebuilt toolchain based on GCC 13.2.0-2. Installing ---------- @@ -53,60 +53,60 @@ First, create a directory to hold the toolchain: .. code-block:: console - $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc + $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc Download and extract toolchain: .. code-block:: console - $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \ - | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz + $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ + | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz Add the toolchain to your `PATH`: .. code-block:: console - $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc + $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc You can edit your shell's rc files if you don't use bash. -Second stage bootloader and partition table -=========================================== +Second stage bootloader +======================= -The NuttX port for now relies on IDF's second stage bootloader to carry on some hardware -initializations. The binaries for the bootloader and the partition table can be found in -this repository: https://github.com/espressif/esp-nuttx-bootloader -That repository contains a dummy IDF project that's used to build the bootloader and -partition table, these are then presented as Github assets and can be downloaded -from: https://github.com/espressif/esp-nuttx-bootloader/releases -Download ``bootloader-esp32c3.bin`` and ``partition-table-esp32c3.bin`` and place them -in a folder, the path to this folder will be used later to program them. This -can be: ``../esp-bins`` +Nuttx can boot the ESP32-H2 directly using the so-called "Simple Boot". +An externally-built 2nd stage bootloader is not required in this case as all +functions required to boot the device are built within Nuttx. Simple boot does not +require any specific configuration (it is selectable by default if no other +2nd stage bootloader is used). + +If other features, like `Secure Boot and Flash Encryption`_, are required, an +externally-built 2nd stage bootloader is needed. The bootloader is built using +the ``make bootloader`` command. This command generates the firmware in the +``nuttx`` folder. The ``ESPTOOL_BINDIR`` is used in the ``make flash`` command +to specify the path to the bootloader. For compatibility among other SoCs and +future options of 2nd stage bootloaders, the commands ``make bootloader`` and +the ``ESPTOOL_BINDIR`` option (for the ``make flash``) can be used even if no +externally-built 2nd stage bootloader is being built (they will be ignored if +Simple Boot is used, for instance). Building and flashing ===================== -First make sure that ``esptool.py`` is installed. This tool is used to convert -the ELF to a compatible ESP32 image and to flash the image into the board. +First, make sure that ``esptool.py`` is installed. This tool is used to convert +the ELF to a compatible ESP32-C3 image and to flash the image into the board. It can be installed with: ``pip install esptool``. -Configure the NuttX project: ``./tools/configure.sh esp32c3-devkit:nsh`` +Configure the NuttX project: ``./tools/configure.sh esp32c3-generic:nsh`` Run ``make`` to build the project. Note that the conversion mentioned above is included in the build process. -The ``esptool.py`` command to flash all the binaries is:: +The ``esptool.py`` is used to flash all the binaries. However, this is also +included in the build process and we can build and flash with:: - esptool.py --chip esp32c3 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin + make flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ -However, this is also included in the build process and we can build and flash with:: - - make flash ESPTOOL_PORT= ESPTOOL_BINDIR=../esp-bins - -Where ```` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is -the path to the folder containing the bootloader and the partition table -for the ESP32-C3 as explained above. -Note that this step is required only one time. Once the bootloader and partition -table are flashed, we don't need to flash them again. So subsequent builds -would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX`` +Where ```` is typically ``/dev/ttyUSB0`` or similar and ``./`` is +the path to the folder containing the externally-built 2nd stage bootloader for +the ESP32-C3 as explained above. Debugging with OpenOCD ====================== @@ -119,7 +119,7 @@ integrates a USB-to-JTAG adapter. OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32c3-builtin.cfg + openocd -c 'set ESP_RTOS none' -f board/esp32c3-builtin.cfg For versions prior to ESP32-C3 ECO3, an external JTAG adapter is needed. It can be connected as follows:: @@ -213,24 +213,24 @@ of flash will not be sufficient to recover most flash contents. Prerequisites ------------- -First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary -images) and ``esptool`` (the ESP32-C3 toolkit):: +First of all, we need to install ``imgtool`` (the MCUboot utility application to manipulate binary +images):: - $ pip install imgtool esptool + $ pip install imgtool We also need to make sure that the python modules are added to ``PATH``:: - $ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc + $ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc Now, we will create a folder to store the generated keys (such as ``~/signing_keys``):: - $ mkdir ~/signing_keys && cd ~/signing_keys + $ mkdir ~/signing_keys && cd ~/signing_keys With all set up, we can now generate keys to sign the bootloader and application binary images, respectively, of the compiled project:: - $ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem - $ imgtool keygen --key app_signing_key.pem --type rsa-3072 + $ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem + $ imgtool keygen --key app_signing_key.pem --type rsa-3072 .. important:: The contents of the key files must be stored securely and kept secret. @@ -239,19 +239,14 @@ Enabling Secure Boot and Flash Encryption To enable Secure Boot for the current project, go to the project's NuttX directory, execute ``make menuconfig`` and the following steps: - 1. Enable experimental features in :menuselection:`Build Setup --> Show experimental options`; - - 2. Enable MCUboot in :menuselection:`Application Configuration --> Bootloader Utilities --> MCUboot`; - - 3. Change image type to ``MCUboot-bootable format`` in :menuselection:`System Type --> Application Image Configuration --> Application Image Format`; - - 4. Enable building MCUboot from the source code by selecting ``Build binaries from source``; - in :menuselection:`System Type --> Application Image Configuration --> Source for bootloader binaries`; - - 5. Enable Secure Boot in :menuselection:`System Type --> Application Image Configuration --> Enable hardware Secure Boot in bootloader`; - - 6. If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in - :menuselection:`System Type --> Application Image Configuration --> Enable Flash Encryption on boot`. + 1. Enable experimental features in :menuselection:`Build Setup --> Show experimental options`; + 2. Enable MCUboot in :menuselection:`Application Configuration --> Bootloader Utilities --> MCUboot`; + 3. Change image type to ``MCUboot-bootable format`` in :menuselection:`System Type --> Application Image Configuration --> Application Image Format`; + 4. Enable building MCUboot from the source code by selecting ``Build binaries from source``; + in :menuselection:`System Type --> Application Image Configuration --> Source for bootloader binaries`; + 5. Enable Secure Boot in :menuselection:`System Type --> Application Image Configuration --> Enable hardware Secure Boot in bootloader`; + 6. If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in + :menuselection:`System Type --> Application Image Configuration --> Enable Flash Encryption on boot`. Now you can design an update and confirm agent to your application. Check the `MCUboot design guide `_ and the `MCUboot Espressif port documentation `_ for @@ -279,7 +274,7 @@ Supported Boards ================ .. toctree:: - :glob: - :maxdepth: 1 + :glob: + :maxdepth: 1 - boards/*/* + boards/*/* diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst b/Documentation/platforms/risc-v/esp32c6/index.rst index 07d5bca9d43..93c845c205a 100644 --- a/Documentation/platforms/risc-v/esp32c6/index.rst +++ b/Documentation/platforms/risc-v/esp32c6/index.rst @@ -33,16 +33,16 @@ check for the current compiler version being used. For instance: .. code-block:: - ############################################################################### - # Build image for tool required by RISCV builds - ############################################################################### - FROM nuttx-toolchain-base AS nuttx-toolchain-riscv - # Download the latest RISCV GCC toolchain prebuilt by xPack - RUN mkdir riscv-none-elf-gcc && \ - curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \ - | tar -C riscv-none-elf-gcc --strip-components 1 -xz + ############################################################################### + # Build image for tool required by RISCV builds + ############################################################################### + FROM nuttx-toolchain-base AS nuttx-toolchain-riscv + # Download the latest RISCV GCC toolchain prebuilt by xPack + RUN mkdir riscv-none-elf-gcc && \ + curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ + | tar -C riscv-none-elf-gcc --strip-components 1 -xz -It uses the xPack's prebuilt toolchain based on GCC 12.3.0. +It uses the xPack's prebuilt toolchain based on GCC 13.2.0-2. Installing ---------- @@ -51,60 +51,52 @@ First, create a directory to hold the toolchain: .. code-block:: console - $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc + $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc Download and extract toolchain: .. code-block:: console - $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \ - | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz + $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ + | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz Add the toolchain to your `PATH`: .. code-block:: console - $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc + $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc You can edit your shell's rc files if you don't use bash. -Second stage bootloader and partition table -=========================================== +Second stage bootloader +======================= -The NuttX port for now relies on IDF's second stage bootloader to carry on some hardware -initializations. The binaries for the bootloader and the partition table can be found in -this repository: https://github.com/espressif/esp-nuttx-bootloader -That repository contains a dummy IDF project that's used to build the bootloader and -partition table, these are then presented as Github assets and can be downloaded -from: https://github.com/espressif/esp-nuttx-bootloader/releases -Download ``bootloader-esp32c6.bin`` and ``partition-table-esp32c6.bin`` and place them -in a folder, the path to this folder will be used later to program them. This -can be: ``../esp-bins`` +Nuttx can boot the ESP32-H2 directly using the so-called "Simple Boot". +An externally-built 2nd stage bootloader is not required in this case as all +functions required to boot the device are built within Nuttx. Simple boot does not +require any specific configuration (it is selectable by default if no other +2nd stage bootloader is used). For compatibility among other SoCs and future options +of 2nd stage bootloaders, the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` +option (for the ``make flash``) are kept (and ignored if Simple Boot is used). Building and flashing ===================== -First make sure that ``esptool.py`` is installed. This tool is used to convert +First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a compatible ESP32-C6 image and to flash the image into the board. It can be installed with: ``pip install esptool``. -Configure the NuttX project: ``./tools/configure.sh esp32c6-devkitc:nsh`` or -``./tools/configure.sh esp32c6-devkitm:nsh``Run ``make`` to build the project. -Note that the conversion mentioned above is included in the build process. -The ``esptool.py`` command to flash all the binaries is:: +Configure the NuttX project: ``./tools/configure.sh esp32c6-devkitc:nsh`` +Run ``make`` to build the project. Note that the conversion mentioned above is +included in the build process. +The ``esptool.py`` is used to flash all the binaries. However, this is also +included in the build process and we can build and flash with:: - esptool.py --chip esp32c6 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin + make flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ -However, this is also included in the build process and we can build and flash with:: - - make flash ESPTOOL_PORT= ESPTOOL_BINDIR=../esp-bins - -Where ```` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is -the path to the folder containing the bootloader and the partition table -for the ESP32-C6 as explained above. -Note that this step is required only one time. Once the bootloader and partition -table are flashed, we don't need to flash them again. So subsequent builds -would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX`` +Where ```` is typically ``/dev/ttyUSB0`` or similar and ``./`` is +the path to the folder containing the externally-built 2nd stage bootloader for +the ESP32-C6 as explained above. Debugging with OpenOCD ====================== @@ -112,12 +104,12 @@ Debugging with OpenOCD Download and build OpenOCD from Espressif, that can be found in https://github.com/espressif/openocd-esp32 -You don not need an external JTAG is to debug, the ESP32-C6 integrates a +You do not need an external JTAG to debug, the ESP32-C6 integrates a USB-to-JTAG adapter. OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32c6-builtin.cfg + openocd -c 'set ESP_RTOS none' -f board/esp32c6-builtin.cfg If you want to debug with an external JTAG adapter it can be connected as follows:: @@ -179,7 +171,7 @@ Supported Boards ================ .. toctree:: - :glob: - :maxdepth: 1 + :glob: + :maxdepth: 1 - boards/*/* + boards/*/* diff --git a/Documentation/platforms/risc-v/esp32h2/index.rst b/Documentation/platforms/risc-v/esp32h2/index.rst index de5945a746b..1c101068904 100644 --- a/Documentation/platforms/risc-v/esp32h2/index.rst +++ b/Documentation/platforms/risc-v/esp32h2/index.rst @@ -28,21 +28,21 @@ ESP32-H2 Toolchain A generic RISC-V toolchain can be used to build ESP32-H2 projects. It's recommended to use the same toolchain used by NuttX CI. Please refer to the Docker -`container `_ and +`container `_ and check for the current compiler version being used. For instance: .. code-block:: - ############################################################################### - # Build image for tool required by RISCV builds - ############################################################################### - FROM nuttx-toolchain-base AS nuttx-toolchain-riscv - # Download the latest RISCV GCC toolchain prebuilt by xPack - RUN mkdir riscv-none-elf-gcc && \ - curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \ - | tar -C riscv-none-elf-gcc --strip-components 1 -xz + ############################################################################### + # Build image for tool required by RISCV builds + ############################################################################### + FROM nuttx-toolchain-base AS nuttx-toolchain-riscv + # Download the latest RISCV GCC toolchain prebuilt by xPack + RUN mkdir riscv-none-elf-gcc && \ + curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ + | tar -C riscv-none-elf-gcc --strip-components 1 -xz -It uses the xPack's prebuilt toolchain based on GCC 12.3.0. +It uses the xPack's prebuilt toolchain based on GCC 13.2.0-2. Installing ---------- @@ -51,60 +51,52 @@ First, create a directory to hold the toolchain: .. code-block:: console - $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc + $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc Download and extract toolchain: .. code-block:: console - $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \ - | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz + $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ + | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz Add the toolchain to your `PATH`: .. code-block:: console - $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc + $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc You can edit your shell's rc files if you don't use bash. -Second stage bootloader and partition table -=========================================== +Second stage bootloader +======================= -The NuttX port for now relies on IDF's second stage bootloader to carry on some hardware -initializations. The binaries for the bootloader and the partition table can be found in -this repository: https://github.com/espressif/esp-nuttx-bootloader -That repository contains a dummy IDF project that's used to build the bootloader and -partition table, these are then presented as Github assets and can be downloaded -from: https://github.com/espressif/esp-nuttx-bootloader/releases -Download ``bootloader-esp32h2.bin`` and ``partition-table-esp32h2.bin`` and place them -in a folder, the path to this folder will be used later to program them. This -can be: ``../esp-bins`` +Nuttx can boot the ESP32-H2 directly using the so-called "Simple Boot". +An externally-built 2nd stage bootloader is not required in this case as all +functions required to boot the device are built within Nuttx. Simple boot does not +require any specific configuration (it is selectable by default if no other +2nd stage bootloader is used). For compatibility among other SoCs and future options +of 2nd stage bootloaders, the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` +option (for the ``make flash``) are kept (and ignored if Simple Boot is used). Building and flashing ===================== -First make sure that ``esptool.py`` is installed. This tool is used to convert +First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a compatible ESP32-H2 image and to flash the image into the board. It can be installed with: ``pip install esptool``. Configure the NuttX project: ``./tools/configure.sh esp32h2-devkit:nsh`` Run ``make`` to build the project. Note that the conversion mentioned above is included in the build process. -The ``esptool.py`` command to flash all the binaries is:: +The ``esptool.py`` is used to flash all the binaries. However, this is also +included in the build process and we can build and flash with:: - esptool.py --chip esp32h2 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin + make flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ -However, this is also included in the build process and we can build and flash with:: - - make flash ESPTOOL_PORT= ESPTOOL_BINDIR=../esp-bins - -Where ```` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is -the path to the folder containing the bootloader and the partition table -for the ESP32-H2 as explained above. -Note that this step is required only one time. Once the bootloader and partition -table are flashed, we don't need to flash them again. So subsequent builds -would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX`` +Where ```` is typically ``/dev/ttyUSB0`` or similar and ``./`` is +the path to the folder containing the externally-built 2nd stage bootloader for +the ESP32-H2 as explained above. Debugging with OpenOCD ====================== @@ -117,7 +109,7 @@ USB-to-JTAG adapter. OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32h2-builtin.cfg + openocd -c 'set ESP_RTOS none' -f board/esp32h2-builtin.cfg If you want to debug with an external JTAG adapter it can be connected as follows:: @@ -179,7 +171,7 @@ Supported Boards ================ .. toctree:: - :glob: - :maxdepth: 1 + :glob: + :maxdepth: 1 - boards/*/* + boards/*/* diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index f81ce33d736..dce0af96c7f 100644 --- a/Documentation/platforms/xtensa/esp32/index.rst +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -16,16 +16,61 @@ On dual-core SoCs, the two CPUs are typically named "PRO_CPU" and "APP_CPU" (for "protocol" and "application"), however for most purposes the two CPUs are interchangeable. -Toolchain -========= +ESP32 Toolchain +================== -You can use the prebuilt `toolchain `__ -for Xtensa architecture and `OpenOCD `__ -for ESP32 by Espressif. +The toolchain used to build ESP32 firmware can be either downloaded or built from the sources. +It is **highly** recommended to use (download or build) the same toolchain version that is being +used by the NuttX CI. -For flashing firmware, you will need to install ``esptool.py`` by running:: +Please refer to the Docker +`container `_ and +check for the current compiler version being used. For instance: - $ pip install esptool +.. code-block:: + + ############################################################################### + # Build image for tool required by ESP32 builds + ############################################################################### + FROM nuttx-toolchain-base AS nuttx-toolchain-esp32 + # Download the latest ESP32 GCC toolchain prebuilt by Espressif + RUN mkdir -p xtensa-esp32-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32-elf-gcc --strip-components 1 -xJ + + RUN mkdir -p xtensa-esp32s2-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s2-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s2-elf-gcc --strip-components 1 -xJ + + RUN mkdir -p xtensa-esp32s3-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ + +For ESP32, the toolchain version is based on GGC 12.2.0 (``xtensa-esp32-elf-12.2.0_20230208``) + +The prebuilt Toolchain (Recommended) +------------------------------------ + +First, create a directory to hold the toolchain: + +.. code-block:: console + + $ mkdir -p /path/to/your/toolchain/xtensa-esp32-elf-gcc + +Download and extract toolchain: + +.. code-block:: console + + $ curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32-elf-gcc --strip-components 1 -xJ + +Add the toolchain to your `PATH`: + +.. code-block:: console + + $ echo "export PATH=/path/to/your/toolchain/xtensa-esp32-elf-gcc/bin:$PATH" >> ~/.bashrc + +You can edit your shell's rc files if you don't use bash. Building from source -------------------- @@ -37,7 +82,6 @@ build the toolchain with crosstool-NG on Linux are as follows $ git clone https://github.com/espressif/crosstool-NG.git $ cd crosstool-NG - $ git checkout esp-2021r1 $ git submodule update --init $ ./bootstrap && ./configure --enable-local && make diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst index d61a41d088e..9ef5adad193 100644 --- a/Documentation/platforms/xtensa/esp32s2/index.rst +++ b/Documentation/platforms/xtensa/esp32s2/index.rst @@ -9,16 +9,61 @@ All embedded memory, external memory and peripherals are located on the data bus and/or the instruction bus of the CPU. Multiple peripherals in the system can access embedded memory via DMA. -Toolchain -========= +ESP32-S2 Toolchain +================== -You can use the prebuilt `toolchain `__ -for Xtensa architecture and `OpenOCD `__ -for ESP32-S2 by Espressif. +The toolchain used to build ESP32-S2 firmware can be either downloaded or built from the sources. +It is **highly** recommended to use (download or build) the same toolchain version that is being +used by the NuttX CI. -For flashing firmware, you will need to install ``esptool.py`` by running:: +Please refer to the Docker +`container `_ and +check for the current compiler version being used. For instance: - $ pip install esptool +.. code-block:: + + ############################################################################### + # Build image for tool required by ESP32 builds + ############################################################################### + FROM nuttx-toolchain-base AS nuttx-toolchain-esp32 + # Download the latest ESP32 GCC toolchain prebuilt by Espressif + RUN mkdir -p xtensa-esp32-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32-elf-gcc --strip-components 1 -xJ + + RUN mkdir -p xtensa-esp32s2-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s2-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s2-elf-gcc --strip-components 1 -xJ + + RUN mkdir -p xtensa-esp32s3-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ + +For ESP32-S2, the toolchain version is based on GGC 12.2.0 (``xtensa-esp32s2-elf-12.2.0_20230208``) + +The prebuilt Toolchain (Recommended) +------------------------------------ + +First, create a directory to hold the toolchain: + +.. code-block:: console + + $ mkdir -p /path/to/your/toolchain/xtensa-esp32s2-elf-gcc + +Download and extract toolchain: + +.. code-block:: console + + $ curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s2-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s2-elf-gcc --strip-components 1 -xJ + +Add the toolchain to your `PATH`: + +.. code-block:: console + + $ echo "export PATH=/path/to/your/toolchain/xtensa-esp32s2-elf-gcc/bin:$PATH" >> ~/.bashrc + +You can edit your shell's rc files if you don't use bash. Building from source -------------------- @@ -30,20 +75,19 @@ build the toolchain with crosstool-NG on Linux are as follows $ git clone https://github.com/espressif/crosstool-NG.git $ cd crosstool-NG - $ git checkout esp-2021r1 $ git submodule update --init $ ./bootstrap && ./configure --enable-local && make - $ ./ct-ng xtensa-esp32-elf + $ ./ct-ng xtensa-esp32s2-elf $ ./ct-ng build - $ chmod -R u+w builds/xtensa-esp32-elf + $ chmod -R u+w builds/xtensa-esp32s2-elf $ export PATH="crosstool-NG/builds/xtensa-esp32-elf/bin:$PATH" -Alternatively, you may follow the steps in -`ESP-IDF documentation `_. +These steps are given in the setup guide in +`ESP-IDF documentation `_. Flashing ======== diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst b/Documentation/platforms/xtensa/esp32s3/index.rst index dba6372b6a1..a1ee72b3202 100644 --- a/Documentation/platforms/xtensa/esp32s3/index.rst +++ b/Documentation/platforms/xtensa/esp32s3/index.rst @@ -16,16 +16,61 @@ On dual-core SoCs, the two CPUs are typically named "PRO_CPU" and "APP_CPU" (for "protocol" and "application"), however for most purposes the two CPUs are interchangeable. -Toolchain -========= +ESP32-S3 Toolchain +================== -You can use the prebuilt `toolchain `__ -for Xtensa architecture and `OpenOCD `__ -for ESP32-S3 by Espressif. +The toolchain used to build ESP32-S3 firmware can be either downloaded or built from the sources. +It is **highly** recommended to use (download or build) the same toolchain version that is being +used by the NuttX CI. -For flashing firmware, you will need to install ``esptool.py`` by running:: +Please refer to the Docker +`container `_ and +check for the current compiler version being used. For instance: - $ pip install esptool +.. code-block:: + + ############################################################################### + # Build image for tool required by ESP32 builds + ############################################################################### + FROM nuttx-toolchain-base AS nuttx-toolchain-esp32 + # Download the latest ESP32 GCC toolchain prebuilt by Espressif + RUN mkdir -p xtensa-esp32-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32-elf-gcc --strip-components 1 -xJ + + RUN mkdir -p xtensa-esp32s2-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s2-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s2-elf-gcc --strip-components 1 -xJ + + RUN mkdir -p xtensa-esp32s3-elf-gcc && \ + curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ + +For ESP32-S3, the toolchain version is based on GGC 12.2.0 (``xtensa-esp32s3-elf-12.2.0_20230208``) + +The prebuilt Toolchain (Recommended) +------------------------------------ + +First, create a directory to hold the toolchain: + +.. code-block:: console + + $ mkdir -p /path/to/your/toolchain/xtensa-esp32s3-elf-gcc + +Download and extract toolchain: + +.. code-block:: console + + $ curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \ + | tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ + +Add the toolchain to your `PATH`: + +.. code-block:: console + + $ echo "export PATH=/path/to/your/toolchain/xtensa-esp32s3-elf-gcc/bin:$PATH" >> ~/.bashrc + +You can edit your shell's rc files if you don't use bash. Building from source -------------------- @@ -51,36 +96,52 @@ build the toolchain with crosstool-NG on Linux are as follows These steps are given in the setup guide in `ESP-IDF documentation `_. -Flashing -======== - -Firmware for ESP32-S3 is flashed via the USB/UART or internal USB DEVICE JTAG interface using the -``esptool.py`` tool. -It's a two step process where the first converts the ELF file into a ESP32-S3 compatible binary -and the second flashes it to the board. These steps are included into the build system and you can -flash your NuttX firmware simply by running:: - - $ make flash ESPTOOL_PORT= - -where ```` is typically ``/dev/ttyUSB0`` or similar. You can change the baudrate by passing ``ESPTOOL_BAUD``. +Building and flashing NuttX +=========================== Bootloader and partitions ------------------------- -ESP32-S3 requires a bootloader to be flashed as well as a set of FLASH partitions. This is only needed the first time -(or any time you which to modify either of these). An easy way is to use prebuilt binaries for NuttX `from here `_. In there you will find instructions to rebuild these if necessary. -Once you downloaded both binaries, you can flash them by adding an ``ESPTOOL_BINDIR`` parameter, pointing to the directory where these binaries were downloaded: +Nuttx can boot the ESP32-S3 directly using the so-called "Simple Boot". An externally-built +2nd stage bootloader is not required in this case as all functions required to boot the device +are built within Nuttx. Simple boot does not require any specific configuration (it is selectable +by default if no other 2nd stage bootloader is used). -.. code-block:: console +If other features are required, an externally-built 2nd stage bootloader is needed. The bootloader +is built using the ``make bootloader`` command. This command generates the firmware in the +``nuttx`` folder. The ``ESPTOOL_BINDIR`` is used in the ``make flash`` command to specify the path +to the bootloader. For compatibility among other SoCs and future options of 2nd stage bootloaders, +the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) can be +used even if no externally-built 2nd stage bootloader is being built (they will be ignored if +Simple Boot is used, for instance):: - $ make flash ESPTOOL_PORT= ESPTOOL_BINDIR= + $ make bootloader -.. note:: It is recommended that if this is the first time you are using the board with NuttX that you perform a complete SPI FLASH erase. +.. note:: It is recommended that if this is the first time you are using the board with NuttX to + perform a complete SPI FLASH erase. - .. code-block:: console + .. code-block:: console $ esptool.py erase_flash +Building and Flashing +--------------------- + +First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a +compatible ESP32-S3 image and to flash the image into the board. +It can be installed with: ``pip install esptool``. + +It's a two-step process where the first converts the ELF file into an ESP32-S3 compatible binary +and the second flashes it to the board. These steps are included in the build system and it is +possible to build and flash the NuttX firmware simply by running:: + + $ make flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ + +where ```` is typically ``/dev/ttyUSB0`` or similar. ``ESPTOOL_BINDIR=./`` is the path of the +externally-built 2nd stage bootloader and the partition table (if applicable): when built using the +``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to +change the flash baudrate if desired. + Peripheral Support ================== @@ -169,64 +230,11 @@ using WPA2. The ``dhcpd_start`` is necessary to let your board to associate an IP to your smartphone. -Memory Map -========== - -Address Mapping ---------------- - -================== ========== ========== =============== =============== -BUS TYPE START LAST DESCRIPTION NOTES -================== ========== ========== =============== =============== -To be added -================== ========== ========== =============== =============== - -Embedded Memory ---------------- - -=========== ========== ========== =============== =============== -BUS TYPE START LAST DESCRIPTION NOTES -=========== ========== ========== =============== =============== -To be added -=========== ========== ========== =============== =============== - -Boundary Address (Embedded) ---------------------------- - -====================== ========== ========== =============== =============== -BUS TYPE START LAST DESCRIPTION NOTES -====================== ========== ========== =============== =============== -To be added -====================== ========== ========== =============== =============== - -External Memory ---------------- - -=========== ========== ========== =============== =============== -BUS TYPE START LAST DESCRIPTION NOTES -=========== ========== ========== =============== =============== -To be added -=========== ========== ========== =============== =============== - -Boundary Address (External) ---------------------------- - -To be added - -Linker Segments ---------------- - -+---------------------+------------+------------+------+------------------------------+ -| DESCRIPTION | START | END | ATTR | LINKER SEGMENT NAME | -+=====================+============+============+======+==============================+ -| To be added | | | | | -+---------------------+------------+------------+------+------------------------------+ - Supported Boards ================ .. toctree:: - :glob: - :maxdepth: 1 + :glob: + :maxdepth: 1 - boards/*/* + boards/*/*