// Copyright 2018-2019 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef _SPI_FLASH_H
#define _SPI_FLASH_H

#include <stdint.h>
#include <stddef.h>

#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

#define ESP_ERR_FLASH_BASE        0x10010
#define ESP_ERR_FLASH_OP_FAIL     (ESP_ERR_FLASH_BASE + 1)
#define ESP_ERR_FLASH_OP_TIMEOUT  (ESP_ERR_FLASH_BASE + 2)

#define SPI_FLASH_SEC_SIZE        4096    /**< SPI Flash sector size */

#define SPI_READ_BUF_MAX          64

#ifdef CONFIG_ENABLE_FLASH_MMAP
/**
 * @brief Enumeration which specifies memory space requested in an mmap call
 */
typedef enum {
    SPI_FLASH_MMAP_DATA,    /**< map to data memory (Vaddr0), allows byte-aligned access, 4 MB total */
    SPI_FLASH_MMAP_INST,    /**< map to instruction memory (Vaddr1-3), allows only 4-byte-aligned access, 11 MB total */
} spi_flash_mmap_memory_t;

/**
 * @brief Opaque handle for memory region obtained from spi_flash_mmap.
 */
typedef uint32_t spi_flash_mmap_handle_t;
#endif

/**
 * @brief  Erase the Flash sector.
 *
 * @param  sector  Sector number, the count starts at sector 0, 4KB per sector.
 *
 * @return esp_err_t
 */
esp_err_t spi_flash_erase_sector(size_t sector);

/**
 * @brief  Erase a range of flash sectors
 *
 * @param  start_address  Address where erase operation has to start.
 *                                  Must be 4kB-aligned
 * @param  size  Size of erased range, in bytes. Must be divisible by 4kB.
 *
 * @return esp_err_t
 */
esp_err_t spi_flash_erase_range(size_t start_address, size_t size);

/**
 * @brief  Write data to Flash.
 *
 * @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.
 *
 * @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
 */
esp_err_t spi_flash_write(size_t dest_addr, const void *src, size_t size);

/**
 * @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);

#ifdef CONFIG_ENABLE_FLASH_MMAP

/**
 * @brief Map region of flash memory into data or instruction address space
 *
 * 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 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
 *
 * @return  ESP_OK on success, ESP_ERR_NO_MEM if pages can not be allocated
 */
esp_err_t spi_flash_mmap(size_t src_addr, size_t size, spi_flash_mmap_memory_t memory,
                         const void** out_ptr, spi_flash_mmap_handle_t* out_handle);

/**
 * @brief Release region previously obtained using spi_flash_mmap
 *
 * @note Calling this function will not necessarily unmap memory region.
 *       Region will only be unmapped when there are no other handles which
 *       reference this region. In case of partially overlapping regions
 *       it is possible that memory will be unmapped partially.
 *
 * @param handle  Handle obtained from spi_flash_mmap
 */
void spi_flash_munmap(spi_flash_mmap_handle_t handle);

#endif /* CONFIG_ENABLE_FLASH_MMAP */

#ifdef __cplusplus
}
#endif

#endif /* _SPI_FLASH_H */