PROJECT_NAME = "ESP32 Programming Guide"
-INPUT = ../components/esp32/include/esp_wifi.h ../components/driver/include/driver ../components/bt/include ../components/nvs_flash/include ../components/log/include ../components/vfs/include
+INPUT = ../components/esp32/include/esp_wifi.h \
+ ../components/driver/include/driver \
+ ../components/bt/include \
+ ../components/nvs_flash/include \
+ ../components/log/include \
+ ../components/vfs/include \
+ ../components/spi_flash/include
WARN_NO_PARAMDOC = YES
Application Example
-------------------
-`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+Two examples are provided in ESP-IDF examples directory:
+
+- `07_nvs_rw_value <https://github.com/espressif/esp-idf/tree/master/examples/07_nvs_rw_value>`_ demostrates how to read and write integer values
+- `08_nvs_rw_blob <https://github.com/espressif/esp-idf/tree/master/examples/08_nvs_rw_blob>`_ demostrates how to read and write variable length binary values
API Reference
-------------
--- /dev/null
+.. include:: ../../components/spi_flash/README.rst
+
+Application Example
+-------------------
+
+`Instructions`_
+
+.. _Instructions: template.html
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+ * `spi_flash/include/esp_spi_flash.h <https://github.com/espressif/esp-idf/blob/master/components/spi_flash/include/esp_spi_flash.h>`_
+ * `spi_flash/include/esp_partition.h <https://github.com/espressif/esp-idf/blob/master/components/spi_flash/include/esp_partition.h>`_
+
+Macros
+^^^^^^
+
+.. doxygendefine:: ESP_ERR_FLASH_BASE
+.. doxygendefine:: ESP_ERR_FLASH_OP_FAIL
+.. doxygendefine:: ESP_ERR_FLASH_OP_TIMEOUT
+.. doxygendefine:: SPI_FLASH_SEC_SIZE
+.. doxygendefine:: ESP_PARTITION_SUBTYPE_OTA
+
+Type Definitions
+^^^^^^^^^^^^^^^^
+
+.. doxygentypedef:: spi_flash_mmap_handle_t
+.. doxygentypedef:: esp_partition_iterator_t
+
+Enumerations
+^^^^^^^^^^^^
+
+.. doxygenenum:: spi_flash_mmap_memory_t
+.. doxygenenum:: esp_partition_type_t
+.. doxygenenum:: esp_partition_subtype_t
+
+Structures
+^^^^^^^^^^
+
+.. doxygenstruct:: esp_partition_t
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: spi_flash_init
+.. doxygenfunction:: spi_flash_get_chip_size
+.. doxygenfunction:: spi_flash_erase_sector
+.. doxygenfunction:: spi_flash_erase_range
+.. doxygenfunction:: spi_flash_write
+.. doxygenfunction:: spi_flash_read
+.. doxygenfunction:: spi_flash_mmap
+.. doxygenfunction:: spi_flash_munmap
+.. doxygenfunction:: spi_flash_mmap_dump
+.. doxygenfunction:: esp_partition_find
+.. doxygenfunction:: esp_partition_find_first
+.. doxygenfunction:: esp_partition_get
+.. doxygenfunction:: esp_partition_next
+.. doxygenfunction:: esp_partition_iterator_release
+.. doxygenfunction:: esp_partition_read
+.. doxygenfunction:: esp_partition_write
+.. doxygenfunction:: esp_partition_erase_range
+.. doxygenfunction:: esp_partition_mmap
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This XSL transform converts Doxygen XML output for a header file into Sphinx/Breathe compatible list of APIs -->
+<!-- Usage: xsltproc doxygen_xml_to_rst.xslt xml/esp__xxxx_8h.xml -->
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <xsl:output method="text" encoding="UTF-8"/>
+ <xsl:template match="/">
+ <xsl:text>Macros
</xsl:text>
+ <xsl:text>^^^^^^

</xsl:text>
+ <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='define']">
+ <xsl:text>.. doxygendefine:: </xsl:text>
+ <xsl:value-of select="name"/>
+ <xsl:text>
</xsl:text>
+ </xsl:for-each>
+ <xsl:text>
</xsl:text>
+
+ <xsl:text>Type Definitions
</xsl:text>
+ <xsl:text>^^^^^^^^^^^^^^^^

</xsl:text>
+ <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='typedef']">
+ <xsl:text>.. doxygentypedef:: </xsl:text>
+ <xsl:value-of select="name"/>
+ <xsl:text>
</xsl:text>
+ </xsl:for-each>
+ <xsl:text>
</xsl:text>
+
+ <xsl:text>Enumerations
</xsl:text>
+ <xsl:text>^^^^^^^^^^^^

</xsl:text>
+ <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='enum']">
+ <xsl:text>.. doxygenenum:: </xsl:text>
+ <xsl:value-of select="name"/>
+ <xsl:text>
</xsl:text>
+ </xsl:for-each>
+ <xsl:text>
</xsl:text>
+
+ <!-- TODO: figure out why structures are listed as innerclass instances -->
+ <xsl:text>Structures
</xsl:text>
+ <xsl:text>^^^^^^^^^^

</xsl:text>
+ <xsl:for-each select="doxygen/compounddef/innerclass">
+ <xsl:text>.. doxygenstruct:: </xsl:text>
+ <xsl:value-of select="."/>
+ <xsl:text>
</xsl:text>
+ </xsl:for-each>
+ <xsl:text>
</xsl:text>
+
+ <xsl:text>Functions
</xsl:text>
+ <xsl:text>^^^^^^^^^

</xsl:text>
+ <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='function']">
+ <xsl:text>.. doxygenfunction:: </xsl:text>
+ <xsl:value-of select="name"/>
+ <xsl:text>
</xsl:text>
+ </xsl:for-each>
+ <xsl:text>
</xsl:text>
+
+ </xsl:template>
+</xsl:stylesheet>
Startup code called from the reset vector determines the boot mode by checking ``GPIO_STRAP_REG`` register for bootstrap pin states. Depending on the reset reason, the following takes place:
-1. Reset from deep sleep: if the value in ``RTC_CNTL_STORE6_REG`` is non-zero, and CRC value of RTC memory in ``RTC_CNTL_STORE7_REG`` is valid, use ``RTC_CNTL_STORE6_REG`` as an entry point address and jump immediately to it. If ``RTC_CNTL_STORE6_REG`` is zero, or ``RTC_CNTL_STORE7_REG`` contains invalid CRC, or once the code called via ``RTC_CNTL_STORE6_REG`` returns, proceed with boot as if it was a power-on reset. **Note**: to run customized code at this point, a deep sleep stub mechanism is provided. Please see deep sleep documentation for this: deep-sleep-stub_.
+1. Reset from deep sleep: if the value in ``RTC_CNTL_STORE6_REG`` is non-zero, and CRC value of RTC memory in ``RTC_CNTL_STORE7_REG`` is valid, use ``RTC_CNTL_STORE6_REG`` as an entry point address and jump immediately to it. If ``RTC_CNTL_STORE6_REG`` is zero, or ``RTC_CNTL_STORE7_REG`` contains invalid CRC, or once the code called via ``RTC_CNTL_STORE6_REG`` returns, proceed with boot as if it was a power-on reset. **Note**: to run customized code at this point, a deep sleep stub mechanism is provided. Please see :doc:`deep sleep <deep-sleep-stub>` documentation for this.
2. For power-on reset, software SOC reset, and watchdog SOC reset: check the ``GPIO_STRAP_REG`` register if UART or SDIO download mode is requested. If this is the case, configure UART or SDIO, and wait for code to be downloaded. Otherwise, proceed with boot as if it was due to software CPU reset.
When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header.
-Second stage bootloader reads the partition table found at offset 0x8000. For more information about partition tables, see partition-tables_. It finds factory and OTA partitions, and decides which one to boot based on data found in *OTA info* partition.
+Second stage bootloader reads the partition table found at offset 0x8000. See :doc:`partition tables <partition-tables>` documentation for more information. The bootloader finds factory and OTA partitions, and decides which one to boot based on data found in *OTA info* partition.
For the selected partition, second stage bootloader copies data and code sections which are mapped into IRAM and DRAM to their load addresses. For sections which have load addresses in DROM and IROM regions, flash MMU is configured to provide the correct mapping. Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application. Once code is loaded and flash MMU is set up, second stage bootloader jumps to the application entry point found in the binary image header.
RTC fast memory
^^^^^^^^^^^^^^^
-The code which has to run after wake-up from deep sleep mode has to be placed into RTC memory. Please check detailed description in deep-sleep-stub_.
+The code which has to run after wake-up from deep sleep mode has to be placed into RTC memory. Please check detailed description in :doc:`deep sleep <deep-sleep-stub>` documentation.
DRAM (data RAM)
^^^^^^^^^^^^^^^
RTC slow memory
^^^^^^^^^^^^^^^
-Global and static variables used by code which runs from RTC memory (i.e. deep sleep stub code) must be placed into RTC slow memory. Please check the detailed description in deep-sleep-stub_.
+Global and static variables used by code which runs from RTC memory (i.e. deep sleep stub code) must be placed into RTC slow memory. Please check detailed description in :doc:`deep sleep <deep-sleep-stub>` documentation.
-.. _deep-sleep-stub: deep-sleep-stub.rst
-.. _partition-tables: partition-tables.rst
api/gpio
api/uart
api/ledc
-
+ SPI Flash and Partition APIs <api/spi_flash>
Logging <api/log>
Non-Volatile Storage <api/nvs_flash>
Virtual Filesystem <api/vfs>
- Efuses are used to store the secure bootloader key (in efuse block 2), and also a single Efuse bit (ABS_DONE_0) is burned (written to 1) to permanently enable secure boot on the chip. For more details about efuse, see the (forthcoming) chapter in the Technical Reference Manual.
-- To understand the secure boot process, first familiarise yourself with the standard `esp-idf boot process`.
+- To understand the secure boot process, first familiarise yourself with the standard :doc:`ESP-IDF boot process <../general-notes>`.
- Both stages of the boot process (initial software bootloader load, and subsequent partition & app loading) are verified by the secure boot process, in a "chain of trust" relationship.
2. The software bootloader image is built by esp-idf with secure boot support enabled and the public key (signature verification) portion of the secure boot signing key compiled in. This software bootloader image is flashed at offset 0x1000.
3. On first boot, the software bootloader follows the following process to enable secure boot:
- - Hardware secure boot support generates a device secure bootloader key (generated via hardware RNG, then stored read/write protected in efuse), and a secure digest. The digest is derived from the key, an IV, and the bootloader image contents.
- - The secure digest is flashed at offset 0x0 in the flash.
- - Depending on Secure Boot Configuration, efuses are burned to disable JTAG and the ROM BASIC interpreter (it is strongly recommended these options are turned on.)
- - Bootloader permanently enables secure boot by burning the ABS_DONE_0 efuse. The software bootloader then becomes protected (the chip will only boot a bootloader image if the digest matches.)
+
+ - Hardware secure boot support generates a device secure bootloader key (generated via hardware RNG, then stored read/write protected in efuse), and a secure digest. The digest is derived from the key, an IV, and the bootloader image contents.
+ - The secure digest is flashed at offset 0x0 in the flash.
+ - Depending on Secure Boot Configuration, efuses are burned to disable JTAG and the ROM BASIC interpreter (it is strongly recommended these options are turned on.)
+ - Bootloader permanently enables secure boot by burning the ABS_DONE_0 efuse. The software bootloader then becomes protected (the chip will only boot a bootloader image if the digest matches.)
4. On subsequent boots the ROM bootloader sees that the secure boot efuse is burned, reads the saved digest at 0x0 and uses hardware secure boot support to compare it with a newly calculated digest. If the digest does not match then booting will not continue. The digest and comparison are performed entirely by hardware, and the calculated digest is not readable by software. For technical details see `Hardware Secure Boot Support`.
- Image signature is 68 bytes - a 4 byte version word (currently zero), followed by a 64 bytes of signature data. These 68 bytes are appended to an app image or partition table data.
-.. _esp-idf boot process: ../boot-process.rst
.. _RFC6979: https://tools.ietf.org/html/rfc6979
projects / esp-idf / commitdiff