granicus.if.org Git - esp-idf/blob - components/spi_flash/include/spi_flash_chip_driver.h

   1 // Copyright 2015-2019 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
  15 #pragma once
  16 #include "esp_flash.h"
  17
  18 struct esp_flash_t;
  19 typedef struct esp_flash_t esp_flash_t;
  20
  21 typedef struct spi_flash_chip_t spi_flash_chip_t;
  22 /** @brief SPI flash chip driver definition structure.
  23  *
  24  * The chip driver structure contains chip-specific pointers to functions to perform SPI flash operations, and some
  25  * chip-specific numeric values.
  26  *
  27  * @note This is not a public API. These functions are called from the public API (declared in
  28  * esp_flash.h). They assume the caller has already validated arguments and enabled relevant protections
  29  * (disabling flash cache, prevent concurrent SPI access, etc.)
  30  *
  31  * Do not call chip driver functions directly in other contexts.
  32  *
  33  * A generic driver for generic chips and its related operations are defined in
  34  * spi_flash_chip_generic.h which can be used as building blocks for written
  35  * new/specific SPI flash chip drivers.
  36  *
  37  * @note All of these functions may be called with SPI flash cache disabled, so must only ever access IRAM/DRAM/ROM.
  38  */
  39 struct spi_flash_chip_t {
  40     const char *name; ///< Name of the chip driver
  41     /* Probe to detect if a supported SPI flash chip is found.
  42      *
  43      * Attempts to configure 'chip' with these operations and probes for a matching SPI flash chip.
  44      *
  45      * Auto-detection of a SPI flash chip calls this function in turn on each registered driver (see esp_flash_registered_flash_drivers).
  46      *
  47      * ID - as read by spi_flash_generic_read_id() - is supplied so each probe
  48      * function doesn't need to unnecessarily read ID, but probe is permitted
  49      * to interrogate flash in any non-destructive way.
  50      *
  51      * It is permissible for the driver to modify the 'chip' structure if probing succeeds (specifically, to assign something to the
  52      * driver_data pointer if that is useful for the driver.)
  53      *
  54      * @return ESP_OK if probing was successful, an error otherwise. Driver may
  55      * assume that returning ESP_OK means it has claimed this chip.
  56      */
  57     esp_err_t (*probe)(esp_flash_t *chip, uint32_t flash_id);
  58
  59     esp_err_t (*reset)(esp_flash_t *chip);
  60
  61
  62     /* Detect SPI flash size
  63      *
  64      * Interrogate the chip to detect its size.
  65      */
  66     esp_err_t (*detect_size)(esp_flash_t *chip, uint32_t *size);
  67
  68     /* Erase the entire chip
  69
  70        Caller has verified the chip is not write protected.
  71      */
  72     esp_err_t (*erase_chip)(esp_flash_t *chip);
  73
  74     /* Erase a sector of the chip. Sector size is specified in the 'sector_size' field.
  75
  76        sector_address is an offset in bytes.
  77
  78        Caller has verified that this sector should be non-write-protected.
  79      */
  80     esp_err_t (*erase_sector)(esp_flash_t *chip, uint32_t sector_address);
  81
  82     /* Erase a multi-sector block of the chip. Block size is specified in the 'block_erase_size' field.
  83        sector_address is an offset in bytes.
  84
  85        Caller has verified that this block should be non-write-protected.
  86      */
  87     esp_err_t (*erase_block)(esp_flash_t *chip, uint32_t block_address);
  88
  89     uint32_t sector_size; /* Sector is minimum erase size */
  90     uint32_t block_erase_size; /* Optimal (fastest) block size for multi-sector erases on this chip */
  91
  92     /* Read the write protect status of the entire chip. */
  93     esp_err_t (*get_chip_write_protect)(esp_flash_t *chip, bool *write_protected);
  94
  95     /* Set the write protect status of the entire chip. */
  96     esp_err_t (*set_chip_write_protect)(esp_flash_t *chip, bool write_protect_chip);
  97
  98     /* Number of individually write protectable regions on this chip. Range 0-63. */
  99     uint8_t num_protectable_regions;
 100     /* Pointer to an array describing each protectable region. Should have num_protectable_regions elements. */
 101     const esp_flash_region_t *protectable_regions;
 102     /* Get a bitmask describing all protectable regions on the chip. Each bit represents one entry in the
 103        protectable_regions array, ie bit (1<<N) is set then the region at array entry N is write protected. */
 104     esp_err_t (*get_protected_regions)(esp_flash_t *chip, uint64_t *regions);
 105
 106     /* Set protectable regions on the chip. Each bit represents on entry in the protectable regions array. */
 107     esp_err_t (*set_protected_regions)(esp_flash_t *chip, uint64_t regions);
 108
 109     /* Read data from the chip.
 110      *
 111      * Before calling this function, the caller will have called chip->drv->set_read_mode(chip) in order to configure the chip's read mode correctly.
 112      */
 113     esp_err_t (*read)(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length);
 114
 115     /* Write any amount of data to the chip.
 116      */
 117     esp_err_t (*write)(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
 118
 119
 120     /* Use the page program command to write data to the chip.
 121      *
 122      * This function is expected to be called by chip->drv->write (if the
 123      * chip->drv->write implementation doesn't call it then it can be left as NULL.)
 124      *
 125      * - The length argument supplied to this function is at most 'page_size' bytes.
 126      *
 127      * - The region between 'address' and 'address + length' will not cross a page_size aligned boundary (the write
 128      *   implementation is expected to split such a write into two before calling page_program.)
 129      */
 130     esp_err_t (*program_page)(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
 131
 132     /* Page size as written by the page_program function. Usually 256 bytes. */
 133     uint32_t page_size;
 134
 135     /* Perform an encrypted write to the chip, using internal flash encryption hardware. */
 136     esp_err_t (*write_encrypted)(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
 137
 138     /* Set the write enable flag. This function is called internally by other functions in this structure, before a destructive
 139        operation takes place. */
 140     esp_err_t (*set_write_protect)(esp_flash_t *chip, bool write_protect);
 141
 142     /* Wait for the SPI flash chip to be idle (any write operation to be complete.) This function is both called from the higher-level API functions, and from other functions in this structure.
 143
 144        timeout_ms should be a timeout (in milliseconds) before the function returns ESP_ERR_TIMEOUT. This is useful to avoid hanging
 145        if the chip is otherwise unresponsive (ie returns all 0xFF or similar.)
 146     */
 147     esp_err_t (*wait_idle)(esp_flash_t *chip, unsigned timeout_ms);
 148
 149     /* Configure both the SPI host and the chip for the read mode specified in chip->read_mode.
 150      *
 151      * This function is called by the higher-level API before the 'read' function is called.
 152      *
 153      * Can return ESP_ERR_FLASH_UNSUPPORTED_HOST or ESP_ERR_FLASH_UNSUPPORTED_CHIP if the specified mode is unsupported.
 154      */
 155     esp_err_t (*set_read_mode)(esp_flash_t *chip);
 156 };
 157
 158 /* Pointer to an array of pointers to all known drivers for flash chips. This array is used
 159    by esp_flash_init() to detect the flash chip driver, if none is supplied by the caller.
 160
 161    Array is terminated with a NULL pointer.
 162
 163    This pointer can be overwritten with a pointer to a new array, to update the list of known flash chips.
 164  */
 165 extern const spi_flash_chip_t **esp_flash_registered_chips;