1 /*
2  * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 #include "esp_err.h"
9 #include <stdint.h>
10 #include <stdbool.h>
11 #include "esp_private/spi_common_internal.h"
12 #include "sdkconfig.h"
13 
14 #include "esp_flash.h"
15 
16 /** Internal API, don't use in the applications */
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 
23 /** @brief Initialise the default SPI flash chip
24  *
25  * Called by OS startup code. You do not need to call this in your own applications.
26  */
27 esp_err_t esp_flash_init_default_chip(void);
28 
29 /**
30  *  Enable OS-level SPI flash protections in IDF
31  *
32  *  Called by OS startup code. You do not need to call this in your own applications.
33  *
34  * @return ESP_OK if success, otherwise failed. See return value of ``esp_flash_init_os_functions``.
35  */
36 esp_err_t esp_flash_app_init(void);
37 
38 /**
39  *  Disable (or enable) OS-level SPI flash protections in IDF
40  *
41  *  Called by the IDF internal code (e.g. coredump). You do not need to call this in your own applications.
42  *
43  * @return always ESP_OK.
44  */
45 esp_err_t esp_flash_app_disable_protect(bool disable);
46 
47 /**
48  *  Initialize OS-level functions for a specific chip.
49  *
50  * @param chip The chip to init os functions.
51  * @param host_id Which SPI host to use, 1 for SPI1, 2 for SPI2 (HSPI), 3 for SPI3 (VSPI)
52  * @param dev_handle SPI bus lock device handle to acquire during flash operations
53  *
54  * @return
55  *      - ESP_OK if success
56  *      - ESP_ERR_INVALID_ARG if host_id is invalid
57  */
58 esp_err_t esp_flash_init_os_functions(esp_flash_t *chip, int host_id, spi_bus_lock_dev_handle_t dev_handle);
59 
60 /**
61  * @brief Deinitialize OS-level functions
62  *
63  * @param chip              The chip to deinit os functions
64  * @param out_dev_handle    The SPI bus lock passed from `esp_flash_init_os_functions`. The caller should deinitialize
65  *                          the lock.
66  * @return always ESP_OK.
67  */
68 esp_err_t esp_flash_deinit_os_functions(esp_flash_t* chip, spi_bus_lock_dev_handle_t* out_dev_handle);
69 
70 /**
71  * @brief Initialize the bus lock on the SPI1 bus. Should be called if drivers (including esp_flash)
72  * wants to use SPI1 bus.
73  *
74  * @note When using legacy spi flash API, the bus lock will not be available on SPI1 bus.
75  *
76  * @return esp_err_t always ESP_OK.
77  */
78 esp_err_t esp_flash_init_main_bus_lock(void);
79 
80 /**
81  *  Initialize OS-level functions for the main flash chip.
82  *
83  * @param chip The chip to init os functions. Only pointer to the default chip is supported now.
84  *
85  * @return always ESP_OK
86  */
87 esp_err_t esp_flash_app_enable_os_functions(esp_flash_t* chip);
88 
89 /**
90  *  Disable OS-level functions for the main flash chip during special phases (e.g. coredump)
91  *
92  * @param chip The chip to init os functions. Only "esp_flash_default_chip" is supported now.
93  *
94  * @return always ESP_OK
95  */
96 esp_err_t esp_flash_app_disable_os_functions(esp_flash_t* chip);
97 
98 
99 
100 #ifdef __cplusplus
101 }
102 #endif
103