Intel® Quark™ Microcontroller Software Interface 1.4.0 Intel® Quark™ Microcontroller BSP

- Main Page
- Modules
- Data Structures
- Files

- File List

qm_flash.h
1 /*
2 * {% copyright %}
3 */
4
5 #ifndef __QM_FLASH_H__
6 #define __QM_FLASH_H__
7
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10
11 /**
12 * Flash controller.
13 *
14 * @defgroup groupFlash Flash
15 * @{
16 */
17
18 /**
19 * Flash region enum.
20 */
21 typedef enum {
22 QM_FLASH_REGION_OTP = 0, /**< Flash OTP region. */
23 QM_FLASH_REGION_SYS, /**< Flash System region. */
24 #if (QUARK_D2000)
25 QM_FLASH_REGION_DATA, /**< Flash Data region (Quark D2000 only). */
26 #endif
27 QM_FLASH_REGION_NUM /**< Total number of flash regions. */
28 } qm_flash_region_t;
29
30 /**
31 * Flash write disable / enable enum.
32 */
33 typedef enum {
34 QM_FLASH_WRITE_ENABLE = 0, /**< Flash write enable. */
35 QM_FLASH_WRITE_DISABLE /**< Flash write disable. */
36 } qm_flash_disable_t;
37
38 /**
39 * Flash configuration structure.
40 */
41 typedef struct {
42 uint8_t wait_states; /**< Read wait state. */
43
44 /**
45 * Number of clocks in a microsecond. Needed for program/erase
46 * operations.
47 */
48 uint8_t us_count;
49
50 /**
51 * Write Disable.
52 *
53 * When this is set, only a reset will enable writes to Flash again.
54 */
55 qm_flash_disable_t write_disable;
56 } qm_flash_config_t;
57
58 /**
59 * Configure a Flash controller.
60 *
61 * The configuration includes timing and behavioral settings.
62 *
63 * @note: when switching SoC to a higher frequency, flash controllers must be
64 * reconfigured to reflect settings associated with higher frequency BEFORE SoC
65 * frequency is changed. On the other hand, when switching SoC to a lower
66 * frequency, flash controller must be reconfigured only 6 NOP instructions
67 * AFTER the SoC frequency has been updated. Otherwise, flash timings will be
68 * violated.
69 *
70 * @param[in] flash Flash controller index.
71 * @param[in] cfg Flash configuration. It must not be NULL.
72 *
73 * @return Standard errno return type for QMSI.
74 * @retval 0 on success.
75 * @retval Negative @ref errno for possible error codes.
76 */
77 int qm_flash_set_config(const qm_flash_t flash,
78 const qm_flash_config_t *const cfg);
79
80 /**
81 * Write 4 bytes of data to Flash.
82 *
83 * @note: this function performs a write operation only; page erase may be
84 * needed if the page is already programmed.
85 *
86 * @param[in] flash Flash controller index.
87 * @param[in] region Flash region to address.
88 * @param[in] f_addr Address within Flash physical address space.
89 * @param[in] data Data word to write.
90 *
91 * @return Standard errno return type for QMSI.
92 * @retval 0 on success.
93 * @retval Negative @ref errno for possible error codes.
94 */
95 int qm_flash_word_write(const qm_flash_t flash, const qm_flash_region_t region,
96 uint32_t f_addr, const uint32_t data);
97
98 /**
99 * Write multiple of 4 bytes of data to Flash.
100 *
101 * The page is erased, and then written to.
102 *
103 * @note: Since this operation may take some time to complete, the caller is
104 * responsible for ensuring that the watchdog timer does not elapse in the
105 * meantime (e.g., by restarting it before calling this function).
106 *
107 * @param[in] flash Flash controller index.
108 * @param[in] reg Which Flash region to address.
109 * @param[in] f_addr Address within Flash physical address space.
110 * @param[in] page_buf Page buffer to store page during update. Must be at
111 * least QM_FLASH_PAGE_SIZE words big and must not be NULL.
112 * @param[in] data Data to write (array of words). This must not be NULL.
113 * @param[in] len Length of data to write (number of words).
114 *
115 * @return Standard errno return type for QMSI.
116 * @retval 0 on success.
117 * @retval Negative @ref errno for possible error codes.
118 */
119 int qm_flash_page_update(const qm_flash_t flash, const qm_flash_region_t reg,
120 uint32_t f_addr, uint32_t *const page_buf,
121 const uint32_t *const data, uint32_t len);
122
123 /**
124 * Write a flash page.
125 *
126 * The page is erased, and then written to.
127 *
128 * @note: Since this operation may take some time to complete, the caller is
129 * responsible for ensuring that the watchdog timer does not elapse in the
130 * meantime (e.g., by restarting it before calling this function).
131 *
132 * @param[in] flash Flash controller index.
133 * @param[in] region Which Flash region to address.
134 * @param[in] page_num Which page of flash to overwrite.
135 * @param[in] data Data to write (array of words). This must not be NULL.
136 * @param[in] len Length of data to write (number of words).
137 *
138 * @return Standard errno return type for QMSI.
139 * @retval 0 on success.
140 * @retval Negative @ref errno for possible error codes.
141 */
142 int qm_flash_page_write(const qm_flash_t flash, const qm_flash_region_t region,
143 uint32_t page_num, const uint32_t *data, uint32_t len);
144
145 /**
146 * Erase one page of Flash.
147 *
148 * @param[in] flash Flash controller index.
149 * @param[in] region Flash region to address.
150 * @param[in] page_num Page within the Flash controller to erase.
151 *
152 * @return Standard errno return type for QMSI.
153 * @retval 0 on success.
154 * @retval Negative @ref errno for possible error codes.
155 */
156 /* Having page be 32-bits, saves 6 bytes over using 8 / 16-bits. */
157 int qm_flash_page_erase(const qm_flash_t flash, const qm_flash_region_t region,
158 uint32_t page_num);
159
160 /**
161 * Perform mass erase.
162 *
163 * Perform mass erase on the specified flash controller. The mass erase may
164 * include the ROM region, if present and unlocked. Note: it is not possible
165 * to mass-erase the ROM portion separately.
166 *
167 * @note: Since this operation may take some time to complete, the caller is
168 * responsible for ensuring that the watchdog timer does not elapse in the
169 * meantime (e.g., by restarting it before calling this function).
170 *
171 * @param[in] flash Flash controller index.
172 * @param[in] include_rom If set, it also erases the ROM region.
173 *
174 * @return Standard errno return type for QMSI.
175 * @retval 0 on success.
176 * @retval Negative @ref errno for possible error codes.
177 */
178 int qm_flash_mass_erase(const qm_flash_t flash, const uint8_t include_rom);
179
180 /**
181 * Save flash context.
182 *
183 * Save the configuration of the specified flash controller.
184 *
185 * @param[in] flash Flash controller index.
186 * @param[out] ctx Flash context structure. This must not be NULL.
187 *
188 * @return Standard errno return type for QMSI.
189 * @retval 0 on success.
190 * @retval Negative @ref errno for possible error codes.
191 */
192 int qm_flash_save_context(const qm_flash_t flash,
193 qm_flash_context_t *const ctx);
194
195 /**
196 * Restore flash context.
197 *
198 * Restore the configuration of the specified flash controller.
199 * If the system clock frequency is lowered, the flash timings need to be
200 * restored. Otherwise, reading from flash will not be optimal
201 * (there will be 2 wait states instead of 0 wait states.)
202 *
203 * @param[in] flash Flash controller index.
204 * @param[in] ctx Flash context structure. This must not be NULL.
205 *
206 * @return Standard errno return type for QMSI.
207 * @retval 0 on success.
208 * @retval Negative @ref errno for possible error codes.
209 */
210 int qm_flash_restore_context(const qm_flash_t flash,
211 const qm_flash_context_t *const ctx);
212
213 /**
214 * @}
215 */
216
217 #endif /* __QM_FLASH_H__ */
qm_flash_restore_context
int qm_flash_restore_context(const qm_flash_t flash, const qm_flash_context_t *const ctx)
Restore flash context.
Definition: qm_flash.c:350
qm_flash_page_update
int qm_flash_page_update(const qm_flash_t flash, const qm_flash_region_t reg, uint32_t f_addr, uint32_t *const page_buf, const uint32_t *const data, uint32_t len)
Write multiple of 4 bytes of data to Flash.
Definition: qm_flash.c:168
QM_FLASH_WRITE_DISABLE
Flash write disable.
Definition: qm_flash.h:35
QM_FLASH_REGION_NUM
Total number of flash regions.
Definition: qm_flash.h:27
qm_flash_t
qm_flash_t
Number of Flash controllers.
Definition: qm_soc_regs.h:1141
qm_flash_mass_erase
int qm_flash_mass_erase(const qm_flash_t flash, const uint8_t include_rom)
Perform mass erase.
Definition: qm_flash.c:314
qm_flash_config_t::write_disable
qm_flash_disable_t write_disable
Write Disable.
Definition: qm_flash.h:55
qm_flash_save_context
int qm_flash_save_context(const qm_flash_t flash, qm_flash_context_t *const ctx)
Save flash context.
Definition: qm_flash.c:337
QM_FLASH_REGION_SYS
Flash System region.
Definition: qm_flash.h:23
QM_FLASH_REGION_DATA
Flash Data region (Quark D2000 only).
Definition: qm_flash.h:25
qm_flash_word_write
int qm_flash_word_write(const qm_flash_t flash, const qm_flash_region_t region, uint32_t f_addr, const uint32_t data)
Write 4 bytes of data to Flash.
Definition: qm_flash.c:43
qm_flash_context_t
Flash context type.
Definition: qm_soc_regs.h:1466
QM_FLASH_REGION_OTP
Flash OTP region.
Definition: qm_flash.h:22
qm_flash_region_t
qm_flash_region_t
Flash region enum.
Definition: qm_flash.h:21
QM_FLASH_WRITE_ENABLE
Flash write enable.
Definition: qm_flash.h:34
qm_flash_config_t::us_count
uint8_t us_count
Number of clocks in a microsecond.
Definition: qm_flash.h:48
qm_flash_config_t
Flash configuration structure.
Definition: qm_flash.h:41
qm_flash_config_t::wait_states
uint8_t wait_states
Read wait state.
Definition: qm_flash.h:42
qm_flash_page_erase
int qm_flash_page_erase(const qm_flash_t flash, const qm_flash_region_t region, uint32_t page_num)
Erase one page of Flash.
Definition: qm_flash.c:271
qm_flash_disable_t
qm_flash_disable_t
Flash write disable / enable enum.
Definition: qm_flash.h:33
qm_flash_page_write
int qm_flash_page_write(const qm_flash_t flash, const qm_flash_region_t region, uint32_t page_num, const uint32_t *data, uint32_t len)
Write a flash page.
Definition: qm_flash.c:100
qm_flash_set_config
int qm_flash_set_config(const qm_flash_t flash, const qm_flash_config_t *const cfg)
Configure a Flash controller.
Definition: qm_flash.c:22