From b52b4ea2cc1280b8d134e233aaa19b28528ea5b6 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
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 <flash-partition-apis>`.
 
 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 <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 </api-guides/par
 This component provides APIs to enumerate partitions found in the partition table
 and perform operations on them. These functions are declared in ``esp_partition.h``:
 
-- ``esp_partition_find`` used to search partition table for entries with
+- :cpp:func:`esp_partition_find` used to search partition table for entries with
   specific type, returns an opaque iterator
-- ``esp_partition_get`` returns a structure describing the partition, for the given iterator
-- ``esp_partition_next`` advances iterator to the next partition found
-- ``esp_partition_iterator_release`` releases iterator returned by ``esp_partition_find``
-- ``esp_partition_find_first`` is a convenience function which returns structure
+- :cpp:func:`esp_partition_get` returns a structure describing the partition, for the given iterator
+- :cpp:func:`esp_partition_next` advances iterator to the next partition found
+- :cpp:func:`esp_partition_iterator_release` releases iterator returned by ``esp_partition_find``
+- :cpp:func:`esp_partition_find_first` is a convenience function which returns structure
   describing the first partition found by esp_partition_find
-- ``esp_partition_read``, ``esp_partition_write``, ``esp_partition_erase_range``
-  are equivalent to ``spi_flash_read``, ``spi_flash_write``,
-  ``spi_flash_erase_range``, but operate within partition boundaries
+- :cpp:func:`esp_partition_read`, :cpp:func:`esp_partition_write`, :cpp:func:`esp_partition_erase_range`
+  are equivalent to :cpp:func:`spi_flash_read`, :cpp:func:`spi_flash_write`,
+  :cpp:func:`spi_flash_erase_range`, but operate within partition boundaries
 
-Most application code should use ``esp_partition_*`` APIs instead of lower level
-``spi_flash_*`` APIs. Partition APIs do bounds checking and calculate correct
-offsets in flash based on data stored in partition table.
+.. note::
+    Most application code should use these ``esp_partition_*`` APIs instead of lower level
+    ``spi_flash_*`` APIs. Partition APIs do bounds checking and calculate correct
+    offsets in flash based on data stored in partition table.
 
 SPI Flash Encryption
 --------------------
@@ -151,14 +158,14 @@ Decryption is performed at hardware level.
 
 Memory mapping APIs are declared in ``esp_spi_flash.h`` and ``esp_partition.h``:
 
-- ``spi_flash_mmap`` maps a region of physical flash addresses into instruction space or data space of the CPU
-- ``spi_flash_munmap`` unmaps previously mapped region
-- ``esp_partition_mmap`` maps part of a partition into the instruction space or data space of the CPU
+- :cpp:func:`spi_flash_mmap` maps a region of physical flash addresses into instruction space or data space of the CPU
+- :cpp:func:`spi_flash_munmap` unmaps previously mapped region
+- :cpp:func:`esp_partition_mmap` maps part of a partition into the instruction space or data space of the CPU
 
-Differences between ``spi_flash_mmap`` and ``esp_partition_mmap`` are as follows:
+Differences between :cpp:func:`spi_flash_mmap` and :cpp:func:`esp_partition_mmap` are as follows:
 
-- ``spi_flash_mmap`` must be given a 64KB aligned physical address
-- ``esp_partition_mmap`` may be given an arbitrary offset within the partition,
+- :cpp:func:`spi_flash_mmap` must be given a 64KB aligned physical address
+- :cpp:func:`esp_partition_mmap` may be given any arbitrary offset within the partition,
   it will adjust returned pointer to mapped memory as necessary
 
 Note that because memory mapping happens in 64KB blocks, it may be possible to
diff --git a/components/spi_flash/include/esp_spi_flash.h b/components/spi_flash/include/esp_spi_flash.h
index 8dee9d341e..05e0382f69 100644
--- a/components/spi_flash/include/esp_spi_flash.h
+++ b/components/spi_flash/include/esp_spi_flash.h
@@ -77,12 +77,16 @@ esp_err_t spi_flash_erase_range(size_t start_address, size_t size);
 /**
  * @brief  Write data to Flash.
  *
- * @note If source address is in DROM, this function will return
- *       ESP_ERR_INVALID_ARG.
+ * @note For fastest write performance, write a 4 byte aligned size at a
+ * 4 byte aligned offset in flash from a source buffer in DRAM. Varying any of
+ * these parameters will still work, but will be slower due to buffering.
  *
- * @param  dest_addr destination address in Flash. Must be a multiple of 4 bytes.
- * @param  src       pointer to the source buffer.
- * @param  size      length of data, in bytes. Must be a multiple of 4 bytes.
+ * @note Writing more than 8KB at a time will be split into multiple
+ * write operations to avoid disrupting other tasks in the system.
+ *
+ * @param  dest_addr Destination address in Flash.
+ * @param  src       Pointer to the source buffer.
+ * @param  size      Length of data, in bytes.
  *
  * @return esp_err_t
  */
@@ -103,9 +107,9 @@ esp_err_t spi_flash_write(size_t dest_addr, const void *src, size_t size);
  * absolute best performance, both dest_addr and size arguments should
  * be multiples of 32 bytes.
  *
- * @param  dest_addr destination address in Flash. Must be a multiple of 16 bytes.
- * @param  src       pointer to the source buffer.
- * @param  size      length of data, in bytes. Must be a multiple of 16 bytes.
+ * @param  dest_addr Destination address in Flash. Must be a multiple of 16 bytes.
+ * @param  src       Pointer to the source buffer.
+ * @param  size      Length of data, in bytes. Must be a multiple of 16 bytes.
  *
  * @return esp_err_t
  */
@@ -114,10 +118,22 @@ esp_err_t spi_flash_write_encrypted(size_t dest_addr, const void *src, size_t si
 /**
  * @brief  Read data from Flash.
  *
+ * @note For fastest read performance, all parameters should be
+ * 4 byte aligned. If source address and read size are not 4 byte
+ * aligned, read may be split into multiple flash operations. If
+ * destination buffer is not 4 byte aligned, a temporary buffer will
+ * be allocated on the stack.
+ *
+ * @note Reading more than 16KB of data at a time will be split
+ * into multiple reads to avoid disruption to other tasks in the
+ * system. Consider using spi_flash_mmap() to read large amounts
+ * of data.
+ *
  * @param  src_addr source address of the data in Flash.
  * @param  dest     pointer to the destination buffer
  * @param  size     length of data
  *
+ *
  * @return esp_err_t
  */
 esp_err_t spi_flash_read(size_t src_addr, void *dest, size_t size);
@@ -155,19 +171,20 @@ typedef uint32_t spi_flash_mmap_handle_t;
 /**
  * @brief Map region of flash memory into data or instruction address space
  *
- * This function allocates sufficient number of 64k MMU pages and configures
- * them to map request region of flash memory into data address space or into
- * instruction address space. It may reuse MMU pages which already provide
- * required mapping. As with any allocator, there is possibility of fragmentation
- * of address space if mmap/munmap are heavily used. To troubleshoot issues with
- * page allocation, use spi_flash_mmap_dump function.
+ * This function allocates sufficient number of 64kB MMU pages and configures
+ * them to map the requested region of flash memory into the address space.
+ * It may reuse MMU pages which already provide the required mapping.
+ *
+ * As with any allocator, if mmap/munmap are heavily used then the address space
+ * may become fragmented. To troubleshoot issues with page allocation, use
+ * spi_flash_mmap_dump() function.
  *
  * @param src_addr  Physical address in flash where requested region starts.
  *                  This address *must* be aligned to 64kB boundary
- *                  (SPI_FLASH_MMU_PAGE_SIZE).
- * @param size  Size of region which has to be mapped. This size will be rounded
- *              up to a 64k boundary.
- * @param memory  Memory space where the region should be mapped
+ *                  (SPI_FLASH_MMU_PAGE_SIZE)
+ * @param size  Size of region to be mapped. This size will be rounded
+ *              up to a 64kB boundary
+ * @param memory  Address space where the region should be mapped (data or instruction)
  * @param out_ptr  Output, pointer to the mapped memory region
  * @param out_handle  Output, handle which should be used for spi_flash_munmap call
  *
@@ -179,17 +196,16 @@ esp_err_t spi_flash_mmap(size_t src_addr, size_t size, spi_flash_mmap_memory_t m
 /**
  * @brief Map sequences of pages of flash memory into data or instruction address space
  *
- * This function allocates sufficient number of 64k MMU pages and configures
- * them to map the indicated pages of flash memory contiguously into data address 
- * space or into instruction address space. In this respect, it works in a similar
- * way as spi_flash_mmap but it allows mapping a (maybe non-contiguous) set of pages
- * into a contiguous region of memory.
+ * This function allocates sufficient number of 64kB MMU pages and configures
+ * them to map the indicated pages of flash memory contiguously into address space.
+ * In this respect, it works in a similar way as spi_flash_mmap() but it allows mapping
+ * a (maybe non-contiguous) set of pages into a contiguous region of memory.
  *
- * @param pages An array of numbers indicating the 64K pages in flash to be mapped
- *              contiguously into memory. These indicate the indexes of the 64K pages,
+ * @param pages An array of numbers indicating the 64kB pages in flash to be mapped
+ *              contiguously into memory. These indicate the indexes of the 64kB pages,
  *              not the byte-size addresses as used in other functions.
- * @param pagecount  Size of the pages array
- * @param memory  Memory space where the region should be mapped
+ * @param pagecount  Number of entries in the pages array
+ * @param memory  Address space where the region should be mapped (instruction or data)
  * @param out_ptr  Output, pointer to the mapped memory region
  * @param out_handle  Output, handle which should be used for spi_flash_munmap call
  *
@@ -226,7 +242,7 @@ void spi_flash_mmap_dump();
 /**
  * @brief Given a memory address where flash is mapped, return the corresponding physical flash offset.
  *
- * Cache address does not have have been assigned via spi_flash_mmap(), any address in flash map space can be looked up.
+ * Cache address does not have have been assigned via spi_flash_mmap(), any address in memory mapped flash space can be looked up.
  *
  * @param cached Pointer to flashed cached memory.
  *
@@ -248,7 +264,7 @@ size_t spi_flash_cache2phys(const void *cached);
  * phys_offs is not 4-byte aligned, then reading from the returned pointer will result in a crash.
  *
  * @param phys_offs Physical offset in flash memory to look up.
- * @param memory Memory type to look up a flash cache address mapping for (IROM or DROM)
+ * @param memory Address space type to look up a flash cache address mapping for (instruction or data)
  *
  * @return
  * - NULL if the physical address is invalid or not mapped to flash cache of the specified memory type.
@@ -264,6 +280,7 @@ bool spi_flash_cache_enabled();
 
 /**
  * @brief SPI flash critical section enter function.
+ *
  */
 typedef void (*spi_flash_guard_start_func_t)(void);
 /**