nuttx/nuttx-update
1
2
Fork 1
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Documentation: improve documentation about ESP32 family

Browse source 
In particular, sections regarding the toolchain setup and usage
were updated, as well as the bootloader options. Also, minor issues
were fixed.
This commit is contained in:
Tiago Medicci Serrano 2024-04-19 12:41:51 -03:00 committed by Xiang Xiao
parent 92cd1c3742
commit 5ff6362d0f
6 changed files with 327 additions and 252 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

121
Documentation/platforms/risc-v/esp32c3/index.rst
View file

@ -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=<port> ESPTOOL_BINDIR=./
However, this is also included in the build process and we can build and flash with::
make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins
Where ``<port>`` 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 ``<port>`` 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 <https://docs.mcuboot.com/design.html>`_ and the
`MCUboot Espressif port documentation <https://docs.mcuboot.com/readme-espressif.html>`_ for
@ -279,7 +274,7 @@ Supported Boards
================
.. toctree::
:glob:
:maxdepth: 1
:glob:
:maxdepth: 1
boards/*/*
boards/*/*

82
Documentation/platforms/risc-v/esp32c6/index.rst
View file

@ -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=<port> ESPTOOL_BINDIR=./
However, this is also included in the build process and we can build and flash with::
make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins
Where ``<port>`` 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 ``<port>`` 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/*/*

76
Documentation/platforms/risc-v/esp32h2/index.rst
View file

@ -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 <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ and
`container <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ 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=<port> ESPTOOL_BINDIR=./
However, this is also included in the build process and we can build and flash with::
make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins
Where ``<port>`` 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 ``<port>`` 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/*/*

60
Documentation/platforms/xtensa/esp32/index.rst
View file

@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html#xtensa-esp32-elf>`__
for Xtensa architecture and `OpenOCD <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html#openocd-esp32>`__
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 <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ 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

68
Documentation/platforms/xtensa/esp32s2/index.rst
View file

@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/tools/idf-tools.html#xtensa-esp32-elf>`__
for Xtensa architecture and `OpenOCD <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/tools/idf-tools.html#openocd-esp32>`__
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 <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ 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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/linux-macos-setup.html>`_.
These steps are given in the setup guide in
`ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html>`_.
Flashing
========

172
Documentation/platforms/xtensa/esp32s3/index.rst
View file

@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/tools/idf-tools.html#xtensa-esp32s3-elf>`__
for Xtensa architecture and `OpenOCD <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/tools/idf-tools.html#openocd-esp32>`__
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 <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ 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 <https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html>`_.
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=<port>
where ``<port>`` 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 <https://github.com/espressif/esp-nuttx-bootloader>`_. 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=<port> ESPTOOL_BINDIR=<dir>
$ 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=<port> ESPTOOL_BINDIR=./
where ``<port>`` 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/*/*