From b52b4ea2cc1280b8d134e233aaa19b28528ea5b6 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 20 Feb 2018 10:30:02 +1100 Subject: [PATCH] spi_flash: Update docs --- components/spi_flash/README.rst | 59 ++++++++------- components/spi_flash/include/esp_spi_flash.h | 75 ++++++++++++-------- 2 files changed, 79 insertions(+), 55 deletions(-) diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index 6de4e92815..ef40150499 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -18,14 +18,14 @@ SPI flash access APIs This is the set of APIs for working with data in flash: -- ``spi_flash_read`` used to read data from flash to RAM -- ``spi_flash_write`` used to write data from RAM to flash -- ``spi_flash_erase_sector`` used to erase individual sectors of flash -- ``spi_flash_erase_range`` used to erase range of addresses in flash -- ``spi_flash_get_chip_size`` returns flash chip size, in bytes, as configured in menuconfig +- :cpp:func:`spi_flash_read` used to read data from flash to RAM +- :cpp:func:`spi_flash_write` used to write data from RAM to flash +- :cpp:func:`spi_flash_erase_sector` used to erase individual sectors of flash +- :cpp:func:`spi_flash_erase_range` used to erase range of addresses in flash +- :cpp:func:`spi_flash_get_chip_size` returns flash chip size, in bytes, as configured in menuconfig Generally, try to avoid using the raw SPI flash functions in favour of -partition-specific functions. +:ref:`partition-specific functions `. SPI Flash Size -------------- @@ -35,8 +35,8 @@ image header, flashed at offset 0x1000. By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct -size. Alternatively, it is possible to generate a fixed flash size by disabling -detection in ``make menuconfig`` (under Serial Flasher Config). +size. Alternatively, it is possible to generate a fixed flash size by setting +:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. If it is necessary to override the configured flash size at runtime, is is possible to set the ``chip_size`` member of ``g_rom_flashchip`` structure. This @@ -47,10 +47,14 @@ Concurrency Constraints ----------------------- Because the SPI flash is also used for firmware execution (via the instruction & -data caches), these caches much be disabled while reading/writing/erasing. This +data caches), these caches must be disabled while reading/writing/erasing. This means that both CPUs must be running code from IRAM and only reading data from DRAM while flash write operations occur. +If you use the APIs documented here, then this happens automatically and +transparently. However note that it will have some performance impact on other +tasks in the system. + Refer to the :ref:`application memory layout ` documentation for an explanation of the differences between IRAM, DRAM and flash cache. @@ -99,6 +103,8 @@ handler reads from the flash cache during a flash operation, it will cause a crash due to Illegal Instruction exception (for code which should be in IRAM) or garbage data to be read (for constant data which should be in DRAM). +.. _flash-partition-apis: + Partition table APIs -------------------- @@ -109,20 +115,21 @@ More information about partition tables can be found :doc:`here