371 lines
14 KiB
C
371 lines
14 KiB
C
// Copyright 2015-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.
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include "esp_flash.h"
|
|
#include "spi_flash_chip_driver.h"
|
|
|
|
|
|
/*
|
|
* The 'chip_generic' SPI flash operations are a lowest common subset of SPI
|
|
* flash commands, that work across most chips.
|
|
*
|
|
* These can be used as-is via the esp_flash_common_chip_driver chip_drv, or
|
|
* they can be used as "base chip_drv" functions when creating a new
|
|
* spi_flash_host_driver_t chip_drv structure.
|
|
*
|
|
* All of the functions in this header are internal functions, not part of a
|
|
* public API. See esp_flash.h for the public API.
|
|
*/
|
|
|
|
/**
|
|
* @brief Generic probe function
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param flash_id expected manufacture id.
|
|
*
|
|
* @return ESP_OK if the id read from chip->drv_read_id matches (always).
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_probe(esp_flash_t *chip, uint32_t flash_id);
|
|
|
|
/**
|
|
* @brief Generic reset function
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
*
|
|
* @return ESP_OK if sending success, or error code passed from ``common_command`` or ``wait_idle`` functions of host driver.
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_reset(esp_flash_t *chip);
|
|
|
|
/**
|
|
* @brief Generic size detection function
|
|
*
|
|
* Tries to detect the size of chip by using the lower 4 bits of the chip->drv->read_id result = N, and assuming size is 2 ^ N.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param size Output of the detected size
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - ESP_ERR_FLASH_UNSUPPORTED_CHIP if the manufacturer id is not correct, which may means an error in the reading
|
|
* - or other error passed from the ``read_id`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_detect_size(esp_flash_t *chip, uint32_t *size);
|
|
|
|
/**
|
|
* @brief Erase chip by using the generic erase chip command.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``set_write_protect``, ``wait_idle`` or ``erase_chip`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_erase_chip(esp_flash_t *chip);
|
|
|
|
/**
|
|
* @brief Erase sector by using the generic sector erase command.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param start_address Start address of the sector to erase
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``set_write_protect``, ``wait_idle`` or ``erase_sector`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_erase_sector(esp_flash_t *chip, uint32_t start_address);
|
|
|
|
/**
|
|
* @brief Erase block by the generic 64KB block erase command
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param start_address Start address of the block to erase
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``set_write_protect``, ``wait_idle`` or ``erase_block`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_erase_block(esp_flash_t *chip, uint32_t start_address);
|
|
|
|
/**
|
|
* @brief Read from flash by using a read command that matches the programmed
|
|
* read mode.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param buffer Buffer to hold the data read from flash
|
|
* @param address Start address of the data on the flash
|
|
* @param length Length to read
|
|
*
|
|
* @return always ESP_OK currently
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length);
|
|
|
|
/**
|
|
* @brief Perform a page program using the page program command.
|
|
*
|
|
* @note Length of each call should not excced the limitation in
|
|
* ``chip->host->max_write_bytes``. This function is called in
|
|
* ``spi_flash_chip_generic_write`` recursively until the whole page is
|
|
* programmed. Strongly suggest to call ``spi_flash_chip_generic_write``
|
|
* instead.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param buffer Buffer holding the data to program
|
|
* @param address Start address to write to flash
|
|
* @param length Length to write, no longer than ``chip->host->max_write_bytes``.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``wait_idle`` or ``program_page`` function of host driver
|
|
*/
|
|
esp_err_t
|
|
spi_flash_chip_generic_page_program(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
|
|
|
|
/**
|
|
* @brief Perform a generic write. Split the write buffer into page program
|
|
* operations, and call chip->chip_drv->page-program() for each.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param buffer Buffer holding the data to program
|
|
* @param address Start address to write to flash
|
|
* @param length Length to write
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``wait_idle`` or ``program_page`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
|
|
|
|
/**
|
|
* @brief Perform a write using on-chip flash encryption. Not implemented yet.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param buffer Buffer holding the data to program
|
|
* @param address Start address to write to flash
|
|
* @param length Length to write
|
|
*
|
|
* @return always ESP_ERR_FLASH_UNSUPPORTED_HOST.
|
|
*/
|
|
esp_err_t
|
|
spi_flash_chip_generic_write_encrypted(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
|
|
|
|
/**
|
|
* @brief Send the write enable or write disable command and verify the expected bit (1) in
|
|
* the status register is set.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param write_protect true to enable write protection, false to send write enable.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``wait_idle``, ``read_status`` or
|
|
* ``set_write_protect`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_set_write_protect(esp_flash_t *chip, bool write_protect);
|
|
|
|
/**
|
|
* @brief Check whether WEL (write enable latch) bit is set in the Status Register read from RDSR.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param out_write_protect Output of whether the write protect is set.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``read_status`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_get_write_protect(esp_flash_t *chip, bool *out_write_protect);
|
|
|
|
/**
|
|
* @brief Read flash status via the RDSR command and wait for bit 0 (write in
|
|
* progress bit) to be cleared.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param timeout_us Time to wait before timeout, in us.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - ESP_ERR_TIMEOUT if not idle before timeout
|
|
* - or other error passed from the ``wait_idle`` or ``read_status`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_wait_idle(esp_flash_t *chip, uint32_t timeout_us);
|
|
|
|
/**
|
|
* @brief Set the specified SPI read mode according to the data in the chip
|
|
* context. Set quad enable status register bit if needed.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - ESP_ERR_TIMEOUT if not idle before timeout
|
|
* - or other error passed from the ``set_write_protect`` or ``common_command`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_set_io_mode(esp_flash_t *chip);
|
|
|
|
/**
|
|
* Get whether the Quad Enable (QE) is set.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
* @param out_quad_mode Pointer to store the output mode.
|
|
* - SPI_FLASH_QOUT: QE is enabled
|
|
* - otherwise: QE is disabled
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - or other error passed from the ``common_command`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_get_io_mode(esp_flash_t *chip, esp_flash_io_mode_t* out_quad_mode);
|
|
|
|
/**
|
|
* Generic SPI flash chip_drv, uses all the above functions for its operations.
|
|
* In default autodetection, this is used as a catchall if a more specific
|
|
* chip_drv is not found.
|
|
*/
|
|
extern const spi_flash_chip_t esp_flash_chip_generic;
|
|
|
|
/*******************************************************************************
|
|
* Utilities
|
|
*******************************************************************************/
|
|
|
|
/**
|
|
* @brief Wait for the SPI host hardware state machine to be idle.
|
|
*
|
|
* This isn't a flash chip_drv operation, but it's called by
|
|
* spi_flash_chip_generic_wait_idle() and may be useful when implementing
|
|
* alternative drivers.
|
|
*
|
|
* timeout_us will be decremented if the function needs to wait until the host hardware is idle.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - ESP_ERR_TIMEOUT if not idle before timeout
|
|
* - or other error passed from the ``set_write_protect`` or ``common_command`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_generic_wait_host_idle(esp_flash_t *chip, uint32_t *timeout_us);
|
|
|
|
/// Function pointer type for reading status register with QE bit.
|
|
typedef esp_err_t (*esp_flash_rdsr_func_t)(esp_flash_t* chip, uint32_t* out_sr);
|
|
|
|
/**
|
|
* Use RDSR2 (35H) to read bit 15-8 of the SR, and RDSR (05H) to read bit 7-0.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param out_sr Pointer to buffer to hold the status register, 16 bits.
|
|
*
|
|
* @return ESP_OK if success, otherwise error code passed from the
|
|
* `common_command` function of the host driver.
|
|
*/
|
|
esp_err_t spi_flash_common_read_status_16b_rdsr_rdsr2(esp_flash_t* chip, uint32_t* out_sr);
|
|
|
|
/**
|
|
* Use RDSR2 (35H) to read bit 15-8 of the SR.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param out_sr Pointer to buffer to hold the status register, 8 bits.
|
|
*
|
|
* @return ESP_OK if success, otherwise error code passed from the
|
|
* `common_command` function of the host driver.
|
|
*/
|
|
esp_err_t spi_flash_common_read_status_8b_rdsr2(esp_flash_t* chip, uint32_t* out_sr);
|
|
|
|
/**
|
|
* Use RDSR (05H) to read bit 7-0 of the SR.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param out_sr Pointer to buffer to hold the status register, 8 bits.
|
|
*
|
|
* @return ESP_OK if success, otherwise error code passed from the
|
|
* `common_command` function of the host driver.
|
|
*/
|
|
esp_err_t spi_flash_common_read_status_8b_rdsr(esp_flash_t* chip, uint32_t* out_sr);
|
|
|
|
/// Function pointer type for writing status register with QE bit.
|
|
typedef esp_err_t (*esp_flash_wrsr_func_t)(esp_flash_t* chip, uint32_t sr);
|
|
|
|
/**
|
|
* Use WRSR (01H) to write bit 7-0 of the SR.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param sr Value of the status register to write, 8 bits.
|
|
*
|
|
* @return ESP_OK if success, otherwise error code passed from the
|
|
* `common_command` function of the host driver.
|
|
*/
|
|
esp_err_t spi_flash_common_write_status_8b_wrsr(esp_flash_t* chip, uint32_t sr);
|
|
|
|
/**
|
|
* Use WRSR (01H) to write bit 15-0 of the SR.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param sr Value of the status register to write, 16 bits.
|
|
*
|
|
* @return ESP_OK if success, otherwise error code passed from the
|
|
* `common_command` function of the host driver.
|
|
*/
|
|
esp_err_t spi_flash_common_write_status_16b_wrsr(esp_flash_t* chip, uint32_t sr);
|
|
|
|
/**
|
|
* Use WRSR2 (31H) to write bit 15-8 of the SR.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param sr Value of the status register to write, 8 bits.
|
|
*
|
|
* @return ESP_OK if success, otherwise error code passed from the
|
|
* `common_command` function of the host driver.
|
|
*/
|
|
esp_err_t spi_flash_common_write_status_8b_wrsr2(esp_flash_t* chip, uint32_t sr);
|
|
|
|
/**
|
|
* @brief Utility function for set_read_mode chip_drv function. If required,
|
|
* set and check the QE bit in the flash chip to enable the QIO/QOUT mode.
|
|
*
|
|
* Most chip QE enable follows a common pattern, though commands to read/write
|
|
* the status register may be different, as well as the position of QE bit.
|
|
*
|
|
* Registers to actually do Quad transtions and command to be sent in reading
|
|
* should also be configured via
|
|
* spi_flash_chip_generic_config_host_io_mode().
|
|
*
|
|
* Note that the bit length and qe position of wrsr_func, rdsr_func and
|
|
* qe_sr_bit should be consistent.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use.
|
|
* @param wrsr_func Function pointer for writing the status register
|
|
* @param rdsr_func Function pointer for reading the status register
|
|
* @param qe_sr_bit status with the qe bit only.
|
|
*
|
|
* @return always ESP_OK (currently).
|
|
*/
|
|
esp_err_t spi_flash_common_set_io_mode(esp_flash_t *chip, esp_flash_wrsr_func_t wrsr_func, esp_flash_rdsr_func_t rdsr_func, uint32_t qe_sr_bit);
|
|
|
|
/**
|
|
* @brief Configure the host registers to use the specified read mode set in
|
|
* the ``chip->read_mode``.
|
|
*
|
|
* Usually called in chip_drv read() functions before actual reading
|
|
* transactions. Also prepare the command to be sent in read functions.
|
|
*
|
|
* @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
|
|
*
|
|
* @return
|
|
* - ESP_OK if success
|
|
* - ESP_ERR_FLASH_NOT_INITIALISED if chip not initialized properly
|
|
* - or other error passed from the ``configure_host_mode`` function of host driver
|
|
*/
|
|
esp_err_t spi_flash_chip_generic_config_host_io_mode(esp_flash_t *chip);
|