Fork 0
mirror of https://github.com/zephyrproject-rtos/esp-idf.git synced 2024-06-19 08:53:11 +02:00

Initial public version

This commit is contained in:
Ivan Grokhotkov 2016-08-17 23:08:22 +08:00
commit bd6ea4393c
628 changed files with 224814 additions and 0 deletions

.gitignore vendored Normal file
View file

@ -0,0 +1,14 @@
# gtags
# emacs temp file suffixes

.gitmodules vendored Normal file
View file

@ -0,0 +1,3 @@
[submodule "components/esp32/lib"]
path = components/esp32/lib
url = ssh://git@github.com:espressif/esp32-wifi-lib.git

Kconfig Normal file
View file

@ -0,0 +1,63 @@
# For a description of the syntax of this configuration file,
# see kconfig/kconfig-language.txt.
mainmenu "Espressif ESP32 SDK Configuration"
menu "SDK tool configuration"
string "Compiler toolchain path/prefix"
default "xtensa-esp32-elf-"
The prefix/path that is used to call the toolchain. The default setting assumes
a crosstool-ng gcc setup that is in your PATH.
config PYTHON
string "Python 2 interpreter"
default "python"
The executable name/path that is used to run python. On some systems Python 2.x
may need to be invoked as python2.
config MEMMAP_BT
bool "Reserve space for Bluetooth stack"
default "n"
The Bluetooth stack uses memory that cannot be used as generic memory anymore. This
reserves the space for that within the memory map of the compiled binary.
bool "Reserve memory for two cores"
default "y"
The ESP32 contains two cores. If you plan to only use one, you can disable this item
to save some memory. (ToDo: Make this automatically depend on unicore support)
bool "Use TRAX tracing feature"
default "n"
The ESP32 contains a feature which allows you to trace the execution path the processor
has taken through the program. This is stored in a chunk of 32K (16K for single-processor)
of memory that can't be used for general purposes anymore. Disable this if you do not know
what this is.
bool "Use external SPI SRAM chip as main memory"
default "n"
The ESP32 can control an external SPI SRAM chip, adding the memory it contains to the
main memory map. Enable this if you have this hardware and want to use it in the same
way as on-chip RAM.
menu "Component config"

LICENSE Normal file
View file

@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
implied, including, without limitation, any warranties or conditions
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

README.buildenv Normal file
View file

@ -0,0 +1,265 @@
The build structure of the Espressif IoT Development Framework explained.
An ESP-IDF project can be seen as an almagation of a number of components.
For example, for a webserver that shows the current humidity, we would
- The ESP32 base libraries (libc, rom bindings etc)
- The WiFi drivers
- A TCP/IP stack
- The FreeRTOS operating system
- A webserver
- A driver for an humidity sensor
- Main code tying it all together
ESP-IDF makes these components explicit and configurable. To do that, when a project
is compiled, the build environment will look up all the components in the
SDK directories, the project directories and optionally custom other component
directories. It then allows the user to configure compile-time options using
a friendly text-based menu system to customize the SDK as well as other components
to the requirements of the project. After the components are customized, the
build process will compile everything into an output file, which can then be uploaded
into a board in a way that can also be defined by components.
A project in this sense is defined as a directory under which all the files required
to build it live, excluding the SDK files and the toolchain. A simple project
tree looks like this:
- myProject/ - build/
- components/ - component1/ - Makefile
- Kconfig
- src1.c
- component2/ - Makefile
- Kconfig
- src1.c
- main/ - src1.c
- src2.c
- Makefile
As we can see, a project consists of a components/ subdirectory containing its
components as well as one or more directories containing the project-specific
sources; by default a single directory called 'main' is assumed. The project
directory will also have a Makefile where the projects name as well as optionally
other options are defined. After compilation, the project directory will contain
a 'build'-directory containing all of the objects, libraries and other generated
files as well as the final binary.
Components also have a Makefile containing various definititions influencing
the build process of the component as well as the project it's used in, as
well as a Kconfig file defining the compile-time options that are settable
by means of the menu system.
Project makefile variables that can be set by the programmer:
PROJECT_NAME: Mandatory. Name for the project
BUILD_DIR_BASE: Set the directory where all objects/libraries/binaries end up in.
Defaults to $(PROJECT_PATH)/build
COMPONENT_DIRS: Search path for components. Defaults to the component/ directories
in the SDK path and the project path.
COMPONENTS: A list of component names. Defaults to all the component found in the
EXTRA_COMPONENT_DIRS: Defaults to unset. Use this to add directories to the default
SRCDIRS: Directories under the project dir containing project-specific sources.
Defaults to 'main'. These are treated as 'lite' components: they do not have
include directories that are passed to the compilation pass of all components and
they do not have a Kconfig option.
Component makefile variables that can be set by the programmer:
COMPONENT_ADD_INCLUDEDIRS: Relative path to include directories to be added to
the entire project
COMPONENT_PRIV_INCLUDEDIRS: Relative path to include directories that are only used
when compiling this specific component
COMPONENT_DEPENDS: Names of any components that need to be compiled before this component.
COMPONENT_ADD_LDFLAGS: Ld flags to add for this project. Defaults to -l$(COMPONENT_NAME).
Add libraries etc in the current directory as $(abspath libwhatever.a)
COMPONENT_EXTRA_INCLUDES: Any extra include paths. These will be prefixed with '-I' and
passed to the compiler; please put absolute paths here.
COMPONENT_SRCDIRS: Relative directories to look in for sources. Defaults to '.', the current
directory (the root of the component) only. Use this to specify any subdirectories. Note
that specifying this overwrites the default action of compiling everything in the
components root dir; to keep this behaviour please also add '.' as a directory in this
COMPONENT_OBJS: Object files to compile. Defaults to the .o variants of all .c and .S files
that are found in COMPONENT_SRCDIRS.
COMPONENT_EXTRA_CLEAN: Files that are generated using rules in the components Makefile
that also need to be cleaned
COMPONENT_BUILDRECIPE: Recipe to build the component. Optional. Defaults to building all
COMPONENT_OBJS and linking them into lib(componentname).a
COMPONENT_CLEANRECIPE: Recipe to clean the component. Optional. Defaults to removing
all built objects and libraries.
COMPONENT_BUILD_DIR: Equals the cwd of the component build, which is the build dir
of the component (where all the .o etc files should be created).
These variables are already set early on in the Makefile and the values in it will
be usable in component or project Makefiles:
CC, LD, AR, OBJCOPY: Xtensa gcc tools
HOSTCC, HOSTLD etc: Host gcc tools
LDFLAGS, CFLAGS: Set to usable values as defined in SDK Makefile
PROJECT_NAME: Name of the project, as set in project makefile
PROJECT_PATH: Path to the root of the project folder
COMPONENTS: Name of the components to be included
CONFIG_*: Values set by 'make menuconfig' also have corresponding Makefile variables.
For components, there also are these defines:
COMPONENT_PATH: Absolute path to the root of the source tree of the component we're
COMPONENT_LIBRARY: The full path to the static library the components compilation pass
is supposed to generate
How this works:
The Make process is always invoked from the project directory by the
user; invoking it anywhere else gives an error. This is what happens if
we build a binary:
The Makefile first determines how it was included. It determines it was
included as a project file in this case and will continue to figure out
various paths as well as the components available to it. It will also
collect the ldflags and includes that the components specify they need.
It does this by running a dummy Make on the components with a target that
will output these values.
The Makefile will then create targets to build the lib*.a libraries of
all components and make the elf target depend on this. The targets
invoke Make on the makefiles of the components in a subshell: this way
the components have full freedom to do whatever is necessary to build
the library without influencing other components. By default, the
component includes the utility makefile $(SDK_PATH)/make/component.mk.
This provides default targets and configurations that will work
out-of-the-box for most projects.
For components that have parts that need to be run when building of the
project is done, you can create a file called Makefile.projbuild in the
component root directory. This file will be included in the main
Makefile. For the menu, there's an equivalent: if you want to include
options not in the 'components' submenu, create a Kconfig.projbuild and
it will be included in the main menu of menuconfig. Take good care when
(re)defining stuff here: because it's included with all the other
.projbuild files, it's possible to overwrite variables or re-declare
targets defined in the SDK makefile/Kconfig and other .projbuild files
A component consists of a directory which doubles as the name for the
component: a component named 'httpd' lives in a directory called 'httpd'
Because components usually live under the project directory (although
they can also reside in an other folder), the path to this may be
something like /home/myuser/projects/myprojects/components/httpd .
One of the things that most components will have is a Makefile,
containing instructions on how to build the component. Because the
build environment tries to set reasonable defaults that will work most
of the time, a component Makefile can be pretty small. At the absolute
minimum, it will just include the SDK component makefile, which adds
component functionality:
include $(SDK_PATH)/make/component.mk
This will take all the .c and .S files in the component root and compile
them into object files, finally linking them into a library.
Subdirectories are ignored; if your project has sources in subdirectories
instead of in the root of the component, you can tell that to the build
system by setting COMPONENT_SRCDIRS:
include $(SDK_PATH)/make/component.mk
This will compile all source files in the src1/ and src2/ subdirectories
The standard component.mk logic adds all .S and .c files in the source
directories as sources to be compiled unconditionally. It is possible
to circumvent that logic and hardcode the objects to be compiled by
manually setting the COMPONENT_OBJS variable to the name of the
objects that need to be generated:
COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
include $(SDK_PATH)/make/component.mk
This can also be used in order to conditionally compile some files
dependent on the options selected in the Makefile:
bool "Enable the BAR feature."
This enables the BAR feature of the FOO component.
COMPONENT_OBJS := foo_a.o foo_b.o $(if $(CONFIG_FOO_ENABLE_BAR),foo_bar.o foo_bar_interface.o)
include $(SDK_PATH)/make/component.mk
Some components will have a situation where a source file isn't supplied
with the component itself but has to be generated from another file. Say
our component has a header file that consists of the converted binary
data of a BMP file, converted using a hypothetical tool called bmp2h. The
header file is then included in as C source file called graphics_lib.c.
graphics_lib.o: logo.h
logo.h: $(COMPONENT_PATH)/logo.bmp
bmp2h -i $^ -o $@
include $(SDK_PATH)/make/component.mk
In this example, graphics_lib.o and logo.h will be generated in the
current directory (the build directory) while logo.bmp comes with the
component and resides under the component path. Because logo.h is a
generated file, it needs to be cleaned when make clean is called which
why it is added to the COMPONENT_EXTRA_CLEAN variable.
This will work just fine, but there's one last cosmetic improvement that
can be done. The SDK make system tries to make the make process somewhat
easier on the eyes by hiding the commands (unless you run make with the
V=1 switch) and this does not do that yet. Here's an improved version
that will output in the same style as the rest of the make process:
COMPONENT_EXTRA_CLEAN := test_tjpgd_logo.h
graphics_lib.o: logo.h
logo.h: $(COMPONENT_PATH)/logo.bmp
$(vecho) BMP2H $@
$(Q) bmp2h -i $^ -o $@
include $(SDK_PATH)/make/component.mk
Obviously, there are cases where all these recipes are insufficient for a
certain component, for example when the component is basically a wrapper
around another third-party component not originally intended to be
compiled under this build system. In that case, it's possible to forego
the build system entirely by setting COMPONENT_OWNBUILDTARGET and
possibly COMPONENT_OWNCLEANTARGET and defining your own build- and clean
target. The build target can do anything as long as it creates
$(COMPONENT_LIBRARY) for the main file to link into the project binary,
and even that is not necessary: if the COMPONENT_ADD_LDFLAGS variable
is set, the component can instruct the linker to do anything else as well.

README.md Normal file
View file

@ -0,0 +1,151 @@
# Using Espressif IoT Development Framework with the ESP32
# Prerequisites
# Configuring your project
`make menuconfig`
# Compiling your project
`make app`
# Flashing the Bootloader
ESP32 has a bootloader in ROM which runs after reset, but ESP-IDF also uses a second stage software bootloader. The ROM bootloader loads the software bootloader, which then loads the firmware app of the ESP32. The software bootloader must be flashed to offset 0x5000 in the flash.
To build the software bootloader, navigate to your project's top-level directory and run:
``` shell
make bootloader
If you've configured the serial port details in `make menuconfig`, then
``` shell
make bootloader-flash
... will automatically run esptool.py to flash the image. Otherwise, you can customise the `esptool.py` command that is printed out as part of `make bootloader`.
You only need to flash the ESP32 bootloader once.
# The Partition Table
Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x4000 in the flash.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
* "Single factory app, no OTA"
* "Factory app, two OTA definitions"
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
Here is the summary printed for the "Single factory app, no OTA" configuration:
# Espressif ESP32 Partition Table
# Name, Type, SubType, Offset, Size
factory, app, factory, 0x10000, 1M
rfdata, data, rf, 0x110000, 256K
wifidata,data, wifi, 0x150000, 256K
* At a 0x10000 (64KB) offset in the flash is the app labelled "factory". The bootloader will run this app by default.
* There are also two data regions defined in the partition table for storing RF & Wifi calibration data.
Here is the summary printed for the "Factory app, two OTA definitions" configuration:
# Espressif ESP32 Partition Table
# Name, Type, SubType, Offset, Size
factory, app, factory, 0x10000, 1M
ota_0, app, ota_0, 0x110000, 1M
ota_1, app, ota_1, 0x210000, 1M
rfdata, data, rf, 0x310000, 256K
wifidata,data, wifi, 0x350000, 256K
otadata, data, ota, 0x390000, 256K
* There are now three app partition definitions.
* The type of all three are set as "app", but the subtype varies between the factory app at 0x10000 and the next two "OTA" apps.
* There is also a new "ota data" slot, which holds the data for OTA updates. The bootloader consults this data in order to know which app to execute. If "ota data" is empty, it will execute the factory app.
## Creating Custom Tables
If you choose "Custom partition table CSV" in menuconfig then you can also enter the name of a CSV file (in the project directory) to use for your partition table. The CSV file can describe any number of definitions for the table you need.
The CSV format is the same format as printed in the summaries shown above. However, not all fields are required in the CSV. For example, here is the "input" CSV for the OTA partition table:
# Name, Type, SubType, Offset, Size
factory, app, factory, 0x10000, 1M
ota_0, app, ota_0, , 1M
ota_1, app, ota_1, , 1M
rfdata, data, rf, , 256K
wifidata, data, wifi, , 256K
otadata, data, ota, , 256K
* Whitespace between fields is ignored, and so is any line starting with # (comments).
* Each non-comment line in the CSV file is a partition definition.
* Only the offset for the first partition is supplied. The gen_esp32part.py tool fills in each remaining offset to start after the preceding partition.
### Name field
Name field can be any meaningful name. It is not significant to the ESP32. Names longer than 16 characters will be truncated.
### Type field
Type field can be specified as app (0) or data (1). Or it can be a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for Espressif. If your application needs to store data, please add a custom partition type in the range 0x40-0xFE.
The bootloader ignores any types other than 0 & 1.
### Subtype
When type is "app", the subtype field can be specified as factory (0), ota_0 (0x10) ... ota_15 (0x1F) and test (0x20). Or it can be any number 0-255 (0x00-0xFF). The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot
When type is "data", the subtype field can be specified as ota (0), rf (1), wifi (2). Or it can be a number 0x00-0xFF. The bootloader ignores all data subtypes except for ota. Other "data" subtypes are reserved for Espressif use. To create custom data partition subtypes then use a custom type value, and choose any subtype 0x00-0xFF.
### Offset & Size
Only the first offset field is required (we recommend using 0x10000). Partitions with blank offsets will start after the previous partition.
App partitions have to be at offsets aligned to 0x10000 (64K). If you leave the offset field blank, the tool will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.
Sizes and offsets can be specified as decimal numbers, hex numbers with the prefix 0x, or size multipliers M or K (1024 and 1024*1024 bytes).
## Generating Binary Partition Table
The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool components/partition_table/gen_esp32part.py is used to convert between CSV and binary formats.
If you configure the partition table CSV name in `make menuconfig` and then `make partition_table`, this conversion is done for you.
To convert CSV to Binary manually:
``` shell
python components/partition_table/gen_esp32part.py --verify input_partitions.csv binary_partitions.bin
To convert binary format back to CSV:
``` shell
python components/partition_table/gen_esp32part.py --verify binary_partitions.bin input_partitions.csv
To display the contents of a binary partition table on stdout (this is how the summaries displayed when running `make partition_table` are generated:
``` shell
python components/partition_table/gen_esp32part.py binary_partitions.bin
`gen_esp32part.py` takes one optional argument, `--verify`, which will also verify the partition table during conversion (checking for overlapping partitions, unaligned partitions, etc.)
# Flashing the partition table
The command `make partition_table-flash` will flash the partition table with esptool.py. However a manual flashing command is printed as part of `make partition_table`.

bin/eclipse_windows_make.sh Executable file
View file

@ -0,0 +1,9 @@
# A wrapper for make on Windows with Eclipse
# Eclipse's output parser expects to see output of the form C:/dir/dir/file but our Make
# process uses MinGW paths of the form /c/dir/dir/file. So parse these out...
# (regexp deliberate only matches after a space character to try and avoid false-positives.)
echo "Running make in $(dirname $0)"
make $@ V=1 | sed -E "s@ /([a-z])/(.+)/@ \1:/\2/@g" | sed -E "s@-I/([a-z])/(.+)/@-I\1:/\2/@g" | sed -E "s@-L/([a-z])/(.+)/@-L\1:/\2/@g"

bin/esptool.py Executable file

File diff suppressed because it is too large Load diff

bin/gen_esp32part.py Executable file
View file

@ -0,0 +1,308 @@
#!/usr/bin/env python
# ESP32 partition table generation tool
# Converts partition tables to/from CSV and binary formats.
# See the sdkng README.md file for details about how to use this tool.
import struct
import argparse
import sys
__version__ = '1.0'
quiet = False
def status(msg):
""" Print status message to stderr """
if not quiet:
def critical(msg):
""" Print critical message to stderr """
if not quiet:
class PartitionTable(list):
def __init__(self):
super(PartitionTable, self).__init__(self)
def from_csv(cls, csv_contents):
res = PartitionTable()
lines = csv_contents.split("\n")
for line_no in range(len(lines)):
line = lines[line_no].strip()
if line.startswith("#") or len(line) == 0:
except InputError as e:
raise InputError("Error at line %d: %s" % (line_no+1, e))
except Exception:
critical("Unexpected error parsing line %d: %s" % (line_no+1, line))
# fix up missing offsets & negative sizes
last_end = 0x5000 # first offset after partition table
for e in res:
if e.offset is None:
pad_to = 0x10000 if e.type == PartitionDefinition.APP_TYPE else 4
if last_end % pad_to != 0:
last_end += pad_to - (last_end % pad_to)
e.offset = last_end
if e.size < 0:
e.size = -e.size - e.offset
last_end = e.offset + e.size
return res
def __getitem__(self, item):
""" Allow partition table access via name as well as by
numeric index. """
if isinstance(item, str):
for x in self:
if x.name == item:
return x
raise ValueError("No partition entry named '%s'" % item)
return super(PartitionTable, self).__getitem__(item)
def verify(self):
# verify each partition individually
for p in self:
# check for overlaps
last = None
for p in sorted(self):
if p.offset < 0x5000:
raise InputError("Partition offset 0x%x is below 0x5000" % p.offset)
if last is not None and p.offset < last.offset + last.size:
raise InputError("Partition at 0x%x overlaps 0x%x-0x%x" % (p.offset, last.offset, last.offset+last.size-1))
last = p
def from_binary(cls, b):
if len(b) % 32 != 0:
raise InputError("Partition table length must be a multiple of 32 bytes. Got %d bytes." % len(b))
result = cls()
for o in range(0,len(b),32):
return result
def to_binary(self):
return "".join(e.to_binary() for e in self)
def to_csv(self, simple_formatting=False):
rows = [ "# Espressif ESP32 Partition Table",
"# Name, Type, SubType, Offset, Size" ]
rows += [ x.to_csv(simple_formatting) for x in self ]
return "\n".join(rows) + "\n"
class PartitionDefinition(object):
APP_TYPE = 0x00
DATA_TYPE = 0x01
"app" : APP_TYPE,
"data" : DATA_TYPE,
"factory" : 0x00,
"test" : 0x20,
"ota" : 0x00,
"rf" : 0x01,
"wifi" : 0x02,
MAGIC_BYTES = "\xAA\x50"
APP_TYPE : 0x1000,
DATA_TYPE : 0x04,
# add subtypes for the 16 OTA slot values ("ota_XXX, etc.")
for ota_slot in range(16):
SUBTYPES[TYPES["app"]]["ota_%d" % ota_slot] = 0x10 + ota_slot
def __init__(self):
self.name = ""
self.type = None
self.subtype = None
self.offset = None
self.size = None
def from_csv(cls, line):
""" Parse a line from the CSV """
line_w_defaults = line + ",,," # lazy way to support default fields
fields = [ f.strip() for f in line_w_defaults.split(",") ]
res = PartitionDefinition()
res.name = fields[0]
res.type = res.parse_type(fields[1])
res.subtype = res.parse_subtype(fields[2])
res.offset = res.parse_address(fields[3])
res.size = res.parse_address(fields[4])
if res.size is None:
raise InputError("Size field can't be empty")
return res
def __eq__(self, other):
return self.name == other.name and self.type == other.type \
and self.subtype == other.subtype and self.offset == other.offset \
and self.size == other.size
def __repr__(self):
def maybe_hex(x):
return "0x%x" % x if x is not None else "None"
return "PartitionDefinition('%s', 0x%x, 0x%x, %s, %s)" % (self.name, self.type, self.subtype or 0,
maybe_hex(self.offset), maybe_hex(self.size))
def __str__(self):
return "Part '%s' %d/%d @ 0x%x size 0x%x" % (self.name, self.type, self.subtype, self.offset or -1, self.size or -1)
def __cmp__(self, other):
return self.offset - other.offset
def parse_type(self, strval):
if strval == "":
raise InputError("Field 'type' can't be left empty.")
return parse_int(strval, self.TYPES)
def parse_subtype(self, strval):
if strval == "":
return 0 # default
return parse_int(strval, self.SUBTYPES.get(self.type, {}))
def parse_address(self, strval):
if strval == "":
return None # PartitionTable will fill in default
return parse_int(strval)
def verify(self):
if self.type is None:
raise ValidationError("Type field is not set")
if self.subtype is None:
raise ValidationError("Subtype field is not set")
if self.offset is None:
raise ValidationError("Offset field is not set")
align = self.ALIGNMENT.get(self.type, 4)
if self.offset % align:
raise ValidationError("%s offset 0x%x is not aligned to 0x%x" % (self.name, self.offset, align))
if self.size is None:
raise ValidationError("Size field is not set")
def from_binary(cls, b):
if len(b) != 32:
raise InputError("Partition definition length must be exactly 32 bytes. Got %d bytes." % len(b))
res = cls()
(magic, res.type, res.subtype, res.offset,
res.size, res.name, reserved) = struct.unpack(cls.STRUCT_FORMAT, b)
if "\x00" in res.name: # strip null byte padding from name string
res.name = res.name[:res.name.index("\x00")]
if magic != cls.MAGIC_BYTES:
raise InputError("Invalid magic bytes (%r) for partition definition" % magic)
if reserved != 0:
critical("WARNING: Partition definition had unexpected reserved value 0x%08x. Newer binary format?" % reserved)
return res
def to_binary(self):
return struct.pack(self.STRUCT_FORMAT,
self.type, self.subtype,
self.offset, self.size,
0) # reserved
def to_csv(self, simple_formatting=False):
def addr_format(a, include_sizes):
if not simple_formatting and include_sizes:
for (val, suffix) in [ (0x100000, "M"), (0x400, "K") ]:
if a % val == 0:
return "%d%s" % (a / val, suffix)
return "0x%x" % a
def lookup_keyword(t, keywords):
for k,v in keywords.items():
if simple_formatting == False and t == v:
return k
return "%d" % t
return ",".join([ self.name,
lookup_keyword(self.type, self.TYPES),
lookup_keyword(self.subtype, self.SUBTYPES.get(self.type, {})),
addr_format(self.offset, False),
addr_format(self.size, True) ])
class InputError(RuntimeError):
def __init__(self, e):
super(InputError, self).__init__(e)
def parse_int(v, keywords={}):
"""Generic parser for integer fields - int(x,0) with provision for
k/m/K/M suffixes and 'keyword' value lookup.
for letter, multiplier in [ ("k",1024), ("m",1024*1024) ]:
if v.lower().endswith(letter):
return parse_int(v[:-1], keywords) * multiplier
return int(v, 0)
except ValueError:
if len(keywords) == 0:
raise InputError("Invalid field value %s" % v)
return keywords[v.lower()]
except KeyError:
raise InputError("Value '%s' is not valid. Known keywords: %s" % (v, ", ".join(keywords)))
def main():
global quiet
parser = argparse.ArgumentParser(description='ESP32 partition table utility')
parser.add_argument('--verify', '-v', help='Verify partition table fields', default=True, action='store_false')
parser.add_argument('--quiet', '-q', help="Don't print status messages to stderr", action='store_true')
parser.add_argument('input', help='Path to CSV or binary file to parse. Will use stdin if omitted.', type=argparse.FileType('r'), default=sys.stdin)
parser.add_argument('output', help='Path to output converted binary or CSV file. Will use stdout if omitted, unless the --display argument is also passed (in which case only the summary is printed.)',
args = parser.parse_args()
quiet = args.quiet
input = args.input.read()
input_is_binary = input[0:2] == PartitionDefinition.MAGIC_BYTES
if input_is_binary:
status("Parsing binary partition input...")
table = PartitionTable.from_binary(input)
status("Parsing CSV input...")
table = PartitionTable.from_csv(input)
if args.verify:
status("Verifying table...")
if input_is_binary:
output = table.to_csv()
output = table.to_binary()
with sys.stdout if args.output == '-' else open(args.output, 'w') as f:
if __name__ == '__main__':
except InputError as e:

View file

@ -0,0 +1,45 @@
# Bootloader component
# The bootloader is not a real component that gets linked into the project.
# Instead it is an entire standalone project ( in src/) that gets built in
# the upper projects build directory. This Makefile.projbuild provides the
# glue to build the bootloader project from the original project. It
# basically runs Make in the src/ directory but it needs to zero some variables
# the SDK makefile exports first, to not let them interfere.
.PHONY: bootloader-clean bootloader-flash bootloader
bootloader: $(BUILD_DIR_BASE)/bootloader.bin
# synchronise the project level config to the component's
# config
$(COMPONENT_PATH)/src/sdkconfig: $(PROJECT_PATH)/sdkconfig
$(Q) cp $< $@
# bootloader-flash calls flash in the bootloader dummy project
bootloader-flash: $(BOOTLOADER_BIN)

components/bootloader/src/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@

View file

@ -0,0 +1,12 @@
# This is a project Makefile. It is assumed the directory this Makefile resides in is a
# project subdirectory.
PROJECT_NAME := bootloader
COMPONENTS := esptool_py
#We cannot include the esp32 component directly but we need its includes. This is fixed by
#adding it in the main/Makefile directory.
include $(SDK_PATH)/make/project.mk

View file

@ -0,0 +1,13 @@
# Main Makefile. This is basically the same as a component makefile.
# This Makefile should, at the very least, just include $(SDK_PATH)/make/component.mk. By default,
# this will take the sources in the src/ directory, compile them and link them into
# lib(subdirectory_name).a in the build directory. This behaviour is entirely configurable,
# please read the SDK documents if you need to do this.
COMPONENT_ADD_LDFLAGS := -L $(abspath .) -lmain -T eagle.bootloader.ld -T $(SDK_PATH)/components/esp32/ld/eagle.fpga32.rom.addr.v7.ld
COMPONENT_EXTRA_INCLUDES := $(SDK_PATH)/components/esp32/include
include $(SDK_PATH)/make/component.mk

View file

@ -0,0 +1,138 @@
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef __BOOT_CONFIG_H__
#define __BOOT_CONFIG_H__
#include <stdint.h>
#ifdef __cplusplus
extern "C"
#define BOOT_VERSION "V0.1"
#define SPI_SEC_SIZE 0x1000
#define MEM_CACHE(offset) (uint8_t *)(0x3f400000 + (offset))
#define CACHE_READ_32(offset) ((uint32_t *)(0x3f400000 + (offset)))
#define PARTITION_ADD 0x4000
#define IROM_LOW 0x400D0000
#define IROM_HIGH 0x40400000
#define DROM_LOW 0x3F400000
#define DROM_HIGH 0x3F800000
/*spi mode,saved in third byte in flash */
enum {
/* spi speed*/
enum {
/*suppport flash size in esp32 */
enum {
struct flash_hdr {
char magic;
char blocks;
char spi_mode; /* flag of flash read mode in unpackage and usage in future */
char spi_speed: 4; /* low bit */
char spi_size: 4;
unsigned int entry_addr;
uint8_t encrypt_flag; /* encrypt flag */
uint8_t secury_boot_flag; /* secury boot flag */
char extra_header[14]; /* ESP32 additional header, unused by second bootloader */
/* each header of flash bin block */
struct block_hdr {
unsigned int load_addr;
unsigned int data_len;
/* OTA selection structure (two copies in the OTA data partition.)
Size of 32 bytes is friendly to flash encryption */
typedef struct {
uint32_t ota_seq;
uint8_t seq_label[24];
uint32_t crc; /* CRC32 of ota_seq field only */
} ota_select;
typedef struct {
uint32_t offset;
uint32_t size;
} partition_pos_t;
typedef struct {
uint16_t magic;
uint8_t type; /* partition Type */
uint8_t subtype; /* part_subtype */
partition_pos_t pos;
uint8_t label[16]; /* label for the partition */
uint8_t reserved[4]; /* reserved */
} partition_info_t;
#define PART_TYPE_APP 0x00
#define PART_SUBTYPE_TEST 0x20
#define PART_TYPE_DATA 0x01
#define PART_TYPE_END 0xff
#define PART_SUBTYPE_END 0xff
#define SPI_ERROR_LOG "spi flash error"
typedef struct {
partition_pos_t ota_info;
partition_pos_t factory;
partition_pos_t test;
partition_pos_t ota[16];
uint32_t app_count;
uint32_t selected_subtype;
} bootloader_state_t;
void boot_cache_redirect( uint32_t pos, size_t size );
uint32_t get_bin_len(uint32_t pos);
bool flash_encrypt(bootloader_state_t *bs);
bool secure_boot(void);
#ifdef __cplusplus
#endif /* __BOOT_CONFIG_H__ */

View file

@ -0,0 +1,89 @@
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef __BOOT_LOG_H__
#define __BOOT_LOG_H__
#ifdef __cplusplus
extern "C"
#define Black 0;30
#define Red 0;31
#define Green 0;32
#define Brown 0;33
#define Blue 0;34
#define Purple 0;35
#define Cyan 0;36
// TODO: move BOOT_LOG_LEVEL into menuconfig
//printf("\033[0;36m[NOTICE][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__);
#define log_notice(format, ...) \
ets_printf("\033[0;36m" format "\r\n", ##__VA_ARGS__);\
ets_printf("\033[0m"); \
#define log_info(format, ...) \
ets_printf("\033[1;36m" format "\r\n", ##__VA_ARGS__);\
ets_printf("\033[0m"); \
//printf("\033[0;31m[ERROR][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__);
#define log_error(format, ...) \
ets_printf("\033[0;31m[ERROR][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__);\
ets_printf("\033[0m"); \
//printf("\033[1;33m[WARN][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__);
#define log_warn(format, ...) \
ets_printf("\033[1;33m[WARN][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__);\
ets_printf("\033[0m"); \
//printf("\033[1;32m[DEBUG][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__);
#define log_debug(format, ...) \
ets_printf("\033[1;32m[DEBUG][%s][%s][%d]\n" format "\r\n", __FILE__, __FUNCTION__, __LINE__, ##__VA_ARGS__); \
ets_printf("\033[0m"); \
#ifdef __cplusplus
#endif /* __BOOT_LOGGING_H__ */

View file

@ -0,0 +1,597 @@
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#include <string.h>
#include <stdint.h>
#include <limits.h>
#include "esp_attr.h"
#include "rom/cache.h"
#include "rom/ets_sys.h"
#include "rom/spi_flash.h"
#include "rom/crc.h"
#include "soc/soc.h"
#include "soc/dport_reg.h"
#include "soc/io_mux_reg.h"
#include "soc/efuse_reg.h"
#include "soc/rtc_cntl_reg.h"
#include "soc/timers_reg.h"
#include "sdkconfig.h"
#include "bootloader_log.h"
#include "bootloader_config.h"
extern int _bss_start;
extern int _bss_end;
We arrive here after the bootloader finished loading the program from flash. The hardware is mostly uninitialized,
flash cache is down and the app CPU is in reset. We do have a stack, so we can do the initialization in C.
// TODO: make a nice header file for ROM functions instead of adding externs all over the place
extern void Cache_Flush(int);
void bootloader_main();
void unpack_load_app(const partition_pos_t *app_node);
void print_flash_info(struct flash_hdr* pfhdr);
void IRAM_ATTR set_cache_and_start_app(uint32_t drom_addr,
uint32_t drom_load_addr,
uint32_t drom_size,
uint32_t irom_addr,
uint32_t irom_load_addr,
uint32_t irom_size,
uint32_t entry_addr);
void IRAM_ATTR call_start_cpu0()
//Make page 0 access raise an exception
//Also some other unused pages so we can catch weirdness
//ToDo: this but nicer.
asm volatile (\
"movi a4,0x00000000\n" \
"movi a5,0xf\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"movi a4,0x80000000\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"movi a4,0xa0000000\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"movi a4,0xc0000000\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"movi a4,0xe0000000\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"movi a4,0x20000000\n" \
"movi a5,0x0\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"movi a4,0x40000000\n" \
"movi a5,0x2\n" \
"wdtlb a5,a4\n" \
"witlb a5,a4\n" \
"isync\n" \
//Clear bss
memset(&_bss_start, 0, (&_bss_end - &_bss_start) * sizeof(_bss_start));
/* completely reset MMU for both CPUs
(in case serial bootloader was running) */
/* (above steps probably unnecessary for most serial bootloader
usage, all that's absolutely needed is that we unmask DROM0
cache on the following two lines - normal ROM boot exits with
DROM0 cache unmasked, but serial bootloader exits with it
masked. However can't hurt to be thorough and reset
* @function : get_bin_len
* @description: get bin's length
* @inputs: pos bin locate address in flash
* @return: uint32 length of bin,if bin MAGIC error return 0
uint32_t get_bin_len(uint32_t pos)
uint32_t len = 8 + 16;
uint8_t i;
log_debug("pos %d %x\n",pos,*(uint8_t *)pos);
if(0xE9 != *(uint8_t *)pos) {
return 0;
for (i = 0; i < *(uint8_t *)(pos + 1); i++) {
len += *(uint32_t *)(pos + len + 4) + 8;
if (len % 16 != 0) {
len = (len / 16 + 1) * 16;
} else {
len += 16;
log_debug("bin length = %d\n", len);
return len;
* @function : boot_cache_redirect
* @description: Configure several pages in flash map so that `size` bytes
* starting at `pos` are mapped to 0x3f400000.
* This sets up mapping only for PRO CPU.
* @inputs: pos address in flash
* size size of the area to map, in bytes
void boot_cache_redirect( uint32_t pos, size_t size )
uint32_t pos_aligned = pos & 0xffff0000;
uint32_t count = (size + 0xffff) / 0x10000;
Cache_Read_Disable( 0 );
Cache_Flush( 0 );
log_debug( "mmu set paddr=%08x count=%d", pos_aligned, count );
cache_flash_mmu_set( 0, 0, 0x3f400000, pos_aligned, 64, count );
Cache_Read_Enable( 0 );
* @function : load_partition_table
* @description: Parse partition table, get useful data such as location of
* OTA info sector, factory app sector, and test app sector.
* @inputs: bs bootloader state structure used to save the data
* addr address of partition table in flash
* @return: return true, if the partition table is loaded (and MD5 checksum is valid)
bool load_partition_table(bootloader_state_t* bs, uint32_t addr)
partition_info_t partition;
uint32_t end = addr + 0x1000;
int index = 0;
char *partition_usage;
log_info("Partition Table:");
log_info("## Label Usage Type ST Offset Length");
while (addr < end) {
log_debug("load partition table entry from %x(%08x)", addr, MEM_CACHE(addr));
memcpy(&partition, MEM_CACHE(addr), sizeof(partition));
log_debug("type=%x subtype=%x", partition.type, partition.subtype);
partition_usage = "unknown";
if (partition.magic == PARTITION_MAGIC) { /* valid partition definition */
switch(partition.type) {
case PART_TYPE_APP: /* app partition */
switch(partition.subtype) {
case PART_SUBTYPE_FACTORY: /* factory binary */
bs->factory = partition.pos;
partition_usage = "factory app";
case PART_SUBTYPE_TEST: /* test binary */
bs->test = partition.pos;
partition_usage = "test app";
/* OTA binary */
if ((partition.subtype & ~PART_SUBTYPE_OTA_MASK) == PART_SUBTYPE_OTA_FLAG) {
bs->ota[partition.subtype & PART_SUBTYPE_OTA_MASK] = partition.pos;
partition_usage = "OTA app";
else {
partition_usage = "Unknown app";
break; /* PART_TYPE_APP */
case PART_TYPE_DATA: /* data partition */
switch(partition.subtype) {
case PART_SUBTYPE_DATA_OTA: /* ota data */
bs->ota_info = partition.pos;
partition_usage = "OTA data";
partition_usage = "RF data";
partition_usage = "WiFi data";
partition_usage = "Unknown data";