components/bootloader_support/include_priv/bootloader_flash.h

   1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14 #ifndef __BOOTLOADER_FLASH_H
  15 #define __BOOTLOADER_FLASH_H
  16
  17 #include <stddef.h>
  18 #include <stdbool.h>
  19 #include <stdint.h>
  20 #include <esp_err.h>
  21 #include "esp_spi_flash.h"
  22
  23 #define FLASH_SECTOR_SIZE 0x1000
  24
  25 /* Provide a Flash API for bootloader_support code,
  26    that can be used from bootloader or app code.
  27
  28    This header is available to source code in the bootloader &
  29    bootloader_support components only.
  30 */
  31
  32 /**
  33  * @brief Map a region of flash to data memory
  34  *
  35  * @important In bootloader code, only one region can be bootloader_mmaped at once. The previous region must be bootloader_munmapped before another region is mapped.
  36  *
  37  * @important In app code, these functions are not thread safe.
  38  *
  39  * Call bootloader_munmap once for each successful call to bootloader_mmap.
  40  *
  41  * In esp-idf app, this function maps directly to spi_flash_mmap.
  42  *
  43  * @param offset - Starting flash offset to map to memory.
  44  * @param length - Length of data to map.
  45  *
  46  * @return Pointer to mapped data memory (at src_addr), or NULL
  47  * if an allocation error occured.
  48  */
  49 const void *bootloader_mmap(uint32_t src_addr, uint32_t size);
  50
  51
  52 /**
  53  * @brief Unmap a previously mapped region of flash
  54  *
  55  * Call bootloader_munmap once for each successful call to bootloader_mmap.
  56  */
  57 void bootloader_munmap(const void *mapping);
  58
  59 /**
  60  * @brief  Read data from Flash.
  61  *
  62  *
  63  * @note All of src, dest and size have to be 4-byte aligned.
  64  *
  65  * @param  src   source address of the data in Flash.
  66  * @param  dest  pointer to the destination buffer
  67  * @param  size  length of data
  68  * @param  allow_decrypt If true and flash encryption is enabled, data on flash
  69  *         will be decrypted transparently as part of the read.
  70  *
  71  * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
  72  * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
  73  */
  74 esp_err_t bootloader_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt);
  75
  76
  77 /**
  78  * @brief  Write data to Flash.
  79  *
  80  * @note All of dest_addr, src and size have to be 4-byte aligned. If write_encrypted is set, dest_addr and size must be 32-byte aligned.
  81  *
  82  * Note: In bootloader, when write_encrypted == true, the src buffer is encrypted in place.
  83  *
  84  * @param  dest_addr Destination address to write in Flash.
  85  * @param  src Pointer to the data to write to flash
  86  * @param  size Length of data in bytes.
  87  * @param  write_encrypted If true, data will be written encrypted on flash.
  88  *
  89  * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
  90  * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
  91  */
  92 esp_err_t bootloader_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted);
  93
  94 /**
  95  * @brief  Erase the Flash sector.
  96  *
  97  * @param  sector  Sector number, the count starts at sector 0, 4KB per sector.
  98  *
  99  * @return esp_err_t
 100  */
 101 esp_err_t bootloader_flash_erase_sector(size_t sector);
 102
 103 #endif