docs: spi_flash: Add flash encryption ops, remove boilerplate

diff --git a/components/spi_flash/include/esp_partition.h b/components/spi_flash/include/esp_partition.h
index b149e1023402b3c0c309c222b2cda3083ca2a5e4..28f8551dcb624adbf718fad1da8cb2f52322be9c 100644 (file)
--- a/components/spi_flash/include/esp_partition.h
+++ b/components/spi_flash/include/esp_partition.h
@@ -191,6 +191,13 @@ esp_err_t esp_partition_read(const esp_partition_t* partition,
  * Before writing data to flash, corresponding region of flash needs to be erased.
  * This can be done using esp_partition_erase_range function.
  *
+ * Partitions marked with an encryption flag will automatically be
+ * written via the spi_flash_write_encrypted() function. If writing to
+ * an encrypted partition, all write offsets and lengths must be
+ * multiples of 16 bytes. See the spi_flash_write_encrypted() function
+ * for more details. Unencrypted partitions do not have this
+ * restriction.
+ *
  * @param partition Pointer to partition structure obtained using
  *                  esp_partition_find_first or esp_partition_get.
  *                  Must be non-NULL.

diff --git a/components/spi_flash/include/esp_spi_flash.h b/components/spi_flash/include/esp_spi_flash.h
index 32ab3a685303f2124998cfb4c04e6470760aa45a..3761ec665de28a1fd11cc246dae947e6a95af668 100644 (file)
--- a/components/spi_flash/include/esp_spi_flash.h
+++ b/components/spi_flash/include/esp_spi_flash.h
@@ -92,12 +92,14 @@ esp_err_t spi_flash_write(size_t dest_addr, const void *src, size_t size);
  *
  * @note Flash encryption must be enabled for this function to work.
  *
- * @note Destination flash address and length must be 16-byte
- * aligned. Due to hardware limitations, this function is more
- * efficient if both these arguments are 32-byte aligned. This is
- * because the encryption engine natively deals with 32-byte rows of
- * two AES blocks. Writing half a row (16 bytes) requires reading out
- * the other 16 bytes and re-encrypting them back to the same value.
+ * @note Flash encryption must be enabled when calling this function.
+ * If flash encryption is disabled, the function returns
+ * ESP_ERR_INVALID_STATE.  Use esp_flash_encryption_enabled()
+ * function to determine if flash encryption is enabled.
+ *
+ * @note Both dest_addr and size must be multiples of 16 bytes. For
+ * 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.
@@ -125,7 +127,7 @@ esp_err_t spi_flash_read(size_t src_addr, void *dest, size_t size);
  * If flash encryption is enabled, this function will transparently decrypt data as it is read.
  * If flash encryption is not enabled, this function behaves the same as spi_flash_read().
  *
- * See @ref esp_flash_encryption_enabled() for a function to check if flash encryption is enabled.
+ * See esp_flash_encryption_enabled() for a function to check if flash encryption is enabled.
  *
  * @param  src   source address of the data in Flash.
  * @param  dest  pointer to the destination buffer
@@ -133,7 +135,7 @@ esp_err_t spi_flash_read(size_t src_addr, void *dest, size_t size);
  *
  * @return esp_err_t
  */
-esp_err_t spi_flash_read_encrypted(size_t src, void *dstv, size_t size);
+esp_err_t spi_flash_read_encrypted(size_t src, void *dest, size_t size);
 
 /**
  * @brief Enumeration which specifies memory space requested in an mmap call

diff --git a/docs/api/storage/spi_flash.rst b/docs/api/storage/spi_flash.rst
index ab03b38faaa3c6032c2c3347042921bb0bd6c94e..2530db6d4245ec2102b56626a77ed8870f855200 100644 (file)
--- a/docs/api/storage/spi_flash.rst
+++ b/docs/api/storage/spi_flash.rst
@@ -1,12 +1,5 @@
 .. include:: ../../../components/spi_flash/README.rst
 
-Application Example
--------------------
-
-`Instructions`_
-
-.. _Instructions: ../template.html
-
 API Reference
 -------------
 
@@ -15,6 +8,7 @@ Header Files
 
   * :component_file:`spi_flash/include/esp_spi_flash.h`
   * :component_file:`spi_flash/include/esp_partition.h`
+  * :component_file:`esp32/include/esp_flash_encrypt.h`
 
 Macros
 ^^^^^^
@@ -51,7 +45,9 @@ Functions
 .. doxygenfunction:: spi_flash_erase_sector
 .. doxygenfunction:: spi_flash_erase_range
 .. doxygenfunction:: spi_flash_write
+.. doxygenfunction:: spi_flash_write_encrypted
 .. doxygenfunction:: spi_flash_read
+.. doxygenfunction:: spi_flash_read_encrypted
 .. doxygenfunction:: spi_flash_mmap
 .. doxygenfunction:: spi_flash_munmap
 .. doxygenfunction:: spi_flash_mmap_dump
@@ -64,4 +60,5 @@ Functions
 .. doxygenfunction:: esp_partition_write
 .. doxygenfunction:: esp_partition_erase_range
 .. doxygenfunction:: esp_partition_mmap
+.. doxygenfunction:: esp_flash_encryption_enabled