1 /*
2  * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #include <stdint.h>
8 #include "sdkconfig.h"
9 #include "esp_err.h"
10 
11 #pragma once
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 /**
18  * @brief Structure for flash dummy bits.
19  *        For some flash chips, dummy bits are configurable under different conditions.
20  */
21 typedef struct {
22     uint8_t dio_dummy;
23     uint8_t dout_dummy;
24     uint8_t qio_dummy;
25     uint8_t qout_dummy;
26     uint8_t fastrd_dummy;
27 } spi_flash_hpm_dummy_conf_t;
28 
29 typedef enum {
30     SPI_FLASH_HPM_CMD_NEEDED,      // Means that in the certain condition, flash needs to enter the high performance mode by command.
31     SPI_FLASH_HPM_DUMMY_NEEDED,    // Means that in the certain condition, flash needs to enter the high performance mode by adjusting dummy.
32     SPI_FLASH_HPM_WRITE_SR_NEEDED, // Means that in the certain condition, flash needs to enter the high performance mode by writing status register.
33     SPI_FLASH_HPM_UNNEEDED,           // Means that flash doesn't need to enter the high performance mode.
34     SPI_FLASH_HPM_BEYOND_LIMIT,       // Means that flash has no capability to meet that condition.
35 } spi_flash_requirement_t;
36 
37 typedef void (*spi_flash_hpm_enable_fn_t)(void);
38 typedef esp_err_t (*spi_flash_hpf_check_fn_t)(void);
39 typedef void (*spi_flash_get_chip_dummy_fn_t)(spi_flash_hpm_dummy_conf_t *dummy_conf);
40 typedef esp_err_t (*spi_flash_hpm_probe_fn_t)(uint32_t flash_id);
41 typedef spi_flash_requirement_t (*spi_flash_hpm_chip_requirement_check_t)(uint32_t flash_id, uint32_t freq_mhz, int voltage_mv, int temperature);
42 
43 typedef struct __attribute__((packed))
44 {
45     const char *method;      /* Flash HPM method */
46     spi_flash_hpm_probe_fn_t probe;
47     spi_flash_hpm_chip_requirement_check_t chip_hpm_requirement_check;
48     spi_flash_hpm_enable_fn_t flash_hpm_enable;
49     spi_flash_hpf_check_fn_t flash_hpf_check;
50     spi_flash_get_chip_dummy_fn_t flash_get_dummy;
51 } spi_flash_hpm_info_t;
52 
53 /**
54  * @brief Enum for user to select valid wrap size.
55  */
56 typedef enum {
57     FLASH_WRAP_SIZE_8B = 8,
58     FLASH_WRAP_SIZE_16B = 16,
59     FLASH_WRAP_SIZE_32B = 32,
60     FLASH_WRAP_SIZE_64B = 64,
61 } spi_flash_wrap_size_t;
62 
63 /**
64  * @brief Probe flash wrap method
65  *
66  * @param flash_id Flash chip ID
67  *
68  * @return ESP_OK: If succeed
69  */
70 typedef esp_err_t (*spi_flash_wrap_probe_fn_t)(uint32_t flash_id);
71 
72 /**
73  * @brief Set flash wrap
74  *
75  * @param wrap_size: wrap_size
76  *
77  * @return ESP_OK: If succeed
78  */
79 typedef esp_err_t (*spi_flash_wrap_set_fn_t)(spi_flash_wrap_size_t wrap_size);
80 
81 /**
82  * @brief Clear flash wrap.
83  *
84  * @return ESP_OK: If succeed
85  */
86 typedef esp_err_t (*spi_flash_wrap_clr_fn_t)(void);
87 
88 typedef struct __attribute__((packed))
89 {
90     const char *method;
91     spi_flash_wrap_probe_fn_t probe;
92     spi_flash_wrap_set_fn_t chip_wrap_set;
93     spi_flash_wrap_clr_fn_t chip_wrap_clr;
94 } spi_flash_wrap_info_t;
95 
96 /**
97  * Array of known flash chips and method to enable flash high performance mode.
98  *
99  * Users can override this array.
100  */
101 extern const spi_flash_hpm_info_t __attribute__((weak)) spi_flash_hpm_enable_list[];
102 
103 #ifdef __cplusplus
104 }
105 #endif
106