Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: fix broken links, formatting, add SPI flash and partition APIs

Browse source
This commit is contained in:
Ivan Grokhotkov 2016-11-16 21:33:04 +08:00
parent 8713155e66
commit ca202cbb46
7 changed files with 145 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/Doxyfile
View file

@ -1,6 +1,12 @@
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

5
docs/api/nvs_flash.rst
View file

@ -3,7 +3,10 @@
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
-------------

67
docs/api/spi_flash.rst Normal file
View file

@ -0,0 +1,67 @@
.. 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

56
docs/doxygen_xml_to_rst.xslt Normal file
View file

@ -0,0 +1,56 @@
<?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&#xA;</xsl:text>
<xsl:text>^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='define']">
<xsl:text>.. doxygendefine:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<xsl:text>Type Definitions&#xA;</xsl:text>
<xsl:text>^^^^^^^^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='typedef']">
<xsl:text>.. doxygentypedef:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<xsl:text>Enumerations&#xA;</xsl:text>
<xsl:text>^^^^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='enum']">
<xsl:text>.. doxygenenum:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<!-- TODO: figure out why structures are listed as innerclass instances -->
<xsl:text>Structures&#xA;</xsl:text>
<xsl:text>^^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/innerclass">
<xsl:text>.. doxygenstruct:: </xsl:text>
<xsl:value-of select="."/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
<xsl:text>Functions&#xA;</xsl:text>
<xsl:text>^^^^^^^^^&#xA;&#xA;</xsl:text>
<xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='function']">
<xsl:text>.. doxygenfunction:: </xsl:text>
<xsl:value-of select="name"/>
<xsl:text>&#xA;</xsl:text>
</xsl:for-each>
<xsl:text>&#xA;</xsl:text>
</xsl:template>
</xsl:stylesheet>

10
docs/general-notes.rst
View file

@ -21,7 +21,7 @@ After SoC reset, PRO CPU will start running immediately, executing reset vector
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.
@ -38,7 +38,7 @@ In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the seco
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.
@ -95,7 +95,7 @@ Note that the code outside ``0x40000000 — 0x40400000`` region may not be reach
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)
^^^^^^^^^^^^^^^
@ -118,10 +118,8 @@ By default, constant data is placed by the linker into a 4 MB region (``0x3F4000
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

2
docs/index.rst
View file

@ -97,7 +97,7 @@ Contents:
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>

12
docs/security/secure-boot.rst
View file

@ -14,7 +14,7 @@ Background
- 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.
@ -30,10 +30,11 @@ This is a high level overview of the secure boot process. Step by step instructi
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`.
@ -175,5 +176,4 @@ Deterministic ECDSA as specified by `RFC6979`.
- 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