spi_flash: allocate mmap pages array in internal memory

* spi_flash_mmap_pages needs pages array to be in internal memory.
  Document and check this.

* Fix a bug that spi_flash_mmap did not allocate pages array in
  internal memory.

* Minor style fixes: const-ify pages argument of spi_flash_mmap, add
  spaces around operators, mark output arguments with [out].

Closes #2229.

components/spi_flash/flash_mmap.c

@@ -127,27 +127,30 @@ esp_err_t IRAM_ATTR spi_flash_mmap(size_t src_addr, size_t size, spi_flash_mmap_
     // region which should be mapped
     int phys_page = src_addr / SPI_FLASH_MMU_PAGE_SIZE;
     int page_count = (size + SPI_FLASH_MMU_PAGE_SIZE - 1) / SPI_FLASH_MMU_PAGE_SIZE;
-    //prepare a linear pages array to feed into spi_flash_mmap_pages
-    int *pages=malloc(sizeof(int)*page_count);
-    if (pages==NULL) {
+    // prepare a linear pages array to feed into spi_flash_mmap_pages
+    int *pages = heap_caps_malloc(sizeof(int)*page_count, MALLOC_CAP_INTERNAL);
+    if (pages == NULL) {
         return ESP_ERR_NO_MEM;
     }
     for (int i = 0; i < page_count; i++) {
         pages[i] = phys_page+i;
     }
-    ret=spi_flash_mmap_pages(pages, page_count, memory, out_ptr, out_handle);
+    ret = spi_flash_mmap_pages(pages, page_count, memory, out_ptr, out_handle);
     free(pages);
     return ret;
 }
 
-esp_err_t IRAM_ATTR spi_flash_mmap_pages(int *pages, size_t page_count, spi_flash_mmap_memory_t memory,
+esp_err_t IRAM_ATTR spi_flash_mmap_pages(const int *pages, size_t page_count, spi_flash_mmap_memory_t memory,
                          const void** out_ptr, spi_flash_mmap_handle_t* out_handle)
 {
     esp_err_t ret;
     bool did_flush, need_flush = false;
     if (!page_count) {
         return ESP_ERR_INVALID_ARG;
     }
+    if (!esp_ptr_internal(pages)) {
+        return ESP_ERR_INVALID_ARG;
+    }
     for (int i = 0; i < page_count; i++) {
         if (pages[i] < 0 || pages[i]*SPI_FLASH_MMU_PAGE_SIZE >= g_rom_flashchip.chip_size) {
             return ESP_ERR_INVALID_ARG;

components/spi_flash/include/esp_spi_flash.h

@@ -185,8 +185,8 @@ typedef uint32_t spi_flash_mmap_handle_t;
  * @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
+ * @param[out] out_ptr  Output, pointer to the mapped memory region
+ * @param[out] out_handle  Output, handle which should be used for spi_flash_munmap call
  *
  * @return  ESP_OK on success, ESP_ERR_NO_MEM if pages can not be allocated
  */
@@ -204,14 +204,19 @@ esp_err_t spi_flash_mmap(size_t src_addr, size_t size, spi_flash_mmap_memory_t m
  * @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  Number of entries in the pages array
+ *              Array must be located in internal memory.
+ * @param page_count  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
+ * @param[out] out_ptr  Output, pointer to the mapped memory region
+ * @param[out] out_handle  Output, handle which should be used for spi_flash_munmap call
  *
- * @return  ESP_OK on success, ESP_ERR_NO_MEM if pages can not be allocated
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_NO_MEM if pages can not be allocated
+ *      - ESP_ERR_INVALID_ARG if pagecount is zero or pages array is not in
+ *        internal memory
  */
-esp_err_t spi_flash_mmap_pages(int *pages, size_t pagecount, spi_flash_mmap_memory_t memory,
+esp_err_t spi_flash_mmap_pages(const int *pages, size_t page_count, spi_flash_mmap_memory_t memory,
                          const void** out_ptr, spi_flash_mmap_handle_t* out_handle);