Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
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. */
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. */
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  */
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__ */
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
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
Flash write disable.
Definition: qm_flash.h:35
Total number of flash regions.
Definition: qm_flash.h:27
qm_flash_t
Number of Flash controllers.
Definition: qm_soc_regs.h:1141
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_disable_t write_disable
Write Disable.
Definition: qm_flash.h:55
int qm_flash_save_context(const qm_flash_t flash, qm_flash_context_t *const ctx)
Save flash context.
Definition: qm_flash.c:337
Flash System region.
Definition: qm_flash.h:23
Flash Data region (Quark D2000 only).
Definition: qm_flash.h:25
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
Flash context type.
Definition: qm_soc_regs.h:1466
Flash OTP region.
Definition: qm_flash.h:22
qm_flash_region_t
Flash region enum.
Definition: qm_flash.h:21
Flash write enable.
Definition: qm_flash.h:34
uint8_t us_count
Number of clocks in a microsecond.
Definition: qm_flash.h:48
Flash configuration structure.
Definition: qm_flash.h:41
uint8_t wait_states
Read wait state.
Definition: qm_flash.h:42
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
Flash write disable / enable enum.
Definition: qm_flash.h:33
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
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