ChibiOS  21.6.0
hal_efl_lld.c
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_efl_lld.c
19  * @brief PLATFORM Embedded Flash subsystem low level driver source.
20  *
21  * @addtogroup HAL_EFL
22  * @{
23  */
24 
25 #include "hal.h"
26 
27 #if (HAL_USE_EFL == TRUE) || defined(__DOXYGEN__)
28 
29 /*===========================================================================*/
30 /* Driver local definitions. */
31 /*===========================================================================*/
32 
33 /*===========================================================================*/
34 /* Driver exported variables. */
35 /*===========================================================================*/
36 
37 /**
38  * @brief EFL1 driver identifier.
39  */
40 #if (PLATFORM_EFL_USE_EFL1 == TRUE) || defined(__DOXYGEN__)
41 EFlashDriver EFLD1;
42 #endif
43 
44 /*===========================================================================*/
45 /* Driver local variables and types. */
46 /*===========================================================================*/
47 
48 static const flash_descriptor_t efl_lld_descriptor = {
49  .attributes = FLASH_ATTR_ERASED_IS_ONE |
50  FLASH_ATTR_MEMORY_MAPPED |
51  FLASH_ATTR_ECC_CAPABLE |
52  FLASH_ATTR_ECC_ZERO_LINE_CAPABLE,
53  .page_size = 0,
54  .sectors_count = 0,
55  .sectors = NULL,
56  .sectors_size = 0,
57  .address = (uint8_t *)0,
58  .size = 0
59 };
60 
61 /*===========================================================================*/
62 /* Driver local functions. */
63 /*===========================================================================*/
64 
65 /*===========================================================================*/
66 /* Driver interrupt handlers. */
67 /*===========================================================================*/
68 
69 /*===========================================================================*/
70 /* Driver exported functions. */
71 /*===========================================================================*/
72 
73 /**
74  * @brief Low level Embedded Flash driver initialization.
75  *
76  * @notapi
77  */
78 void efl_lld_init(void) {
79 
80 #if PLATFORM_EFL_USE_EFL1 == TRUE
81  /* Driver initialization.*/
82  eflObjectInit(&EFLD1);
83 #endif
84 }
85 
86 /**
87  * @brief Configures and activates the Embedded Flash peripheral.
88  *
89  * @param[in] eflp pointer to a @p EFlashDriver structure
90  *
91  * @notapi
92  */
93 void efl_lld_start(EFlashDriver *eflp) {
94 
95  if (eflp->state == FLASH_STOP) {
96  /* Enables the peripheral.*/
97 #if PLATFORM_EFL_USE_EFL1 == TRUE
98  if (&EFLD1 == eflp) {
99 
100  }
101 #endif
102  }
103  /* Configures the peripheral.*/
104 
105 }
106 
107 /**
108  * @brief Deactivates the Embedded Flash peripheral.
109  *
110  * @param[in] eflp pointer to a @p EFlashDriver structure
111  *
112  * @notapi
113  */
114 void efl_lld_stop(EFlashDriver *eflp) {
115 
116  if (eflp->state == FLASH_READY) {
117  /* Resets the peripheral.*/
118 
119  /* Disables the peripheral.*/
120 #if PLATFORM_EFL_USE_EFL1 == TRUE
121  if (&EFLD1 == eflp) {
122 
123  }
124 #endif
125  }
126 }
127 
128 /**
129  * @brief Gets the flash descriptor structure.
130  *
131  * @param[in] instance pointer to a @p EFlashDriver instance
132  * @return A flash device descriptor.
133  *
134  * @notapi
135  */
136 const flash_descriptor_t *efl_lld_get_descriptor(void *instance) {
137 
138  (void)instance;
139 
140  return &efl_lld_descriptor;
141 }
142 
143 /**
144  * @brief Read operation.
145  *
146  * @param[in] instance pointer to a @p EFlashDriver instance
147  * @param[in] offset flash offset
148  * @param[in] n number of bytes to be read
149  * @param[out] rp pointer to the data buffer
150  * @return An error code.
151  * @retval FLASH_NO_ERROR if there is no erase operation in progress.
152  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.
153  * @retval FLASH_ERROR_READ if the read operation failed.
154  * @retval FLASH_ERROR_HW_FAILURE if access to the memory failed.
155  *
156  * @notapi
157  */
158 flash_error_t efl_lld_read(void *instance, flash_offset_t offset,
159  size_t n, uint8_t *rp) {
160  EFlashDriver *devp = (EFlashDriver *)instance;
161  flash_error_t err = FLASH_NO_ERROR;
162 
163  osalDbgCheck((instance != NULL) && (rp != NULL) && (n > 0U));
164  osalDbgCheck(((size_t)offset + n) <= (size_t)efl_lld_descriptor.size);
165  osalDbgAssert((devp->state == FLASH_READY) || (devp->state == FLASH_ERASE),
166  "invalid state");
167 
168  /* No reading while erasing.*/
169  if (devp->state == FLASH_ERASE) {
170  return FLASH_BUSY_ERASING;
171  }
172 
173  /* FLASH_READY state while the operation is performed.*/
174  devp->state = FLASH_READ;
175 
176  /* IMPLEMENT */
177 
178  /* Ready state again.*/
179  devp->state = FLASH_READY;
180 
181  return err;
182 
183 }
184 
185 /**
186  * @brief Program operation.
187  * @note The device supports ECC, it is only possible to write erased
188  * pages once except when writing all zeroes.
189  *
190  * @param[in] instance pointer to a @p EFlashDriver instance
191  * @param[in] offset flash offset
192  * @param[in] n number of bytes to be programmed
193  * @param[in] pp pointer to the data buffer
194  * @return An error code.
195  * @retval FLASH_NO_ERROR if there is no erase operation in progress.
196  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.
197  * @retval FLASH_ERROR_PROGRAM if the program operation failed.
198  * @retval FLASH_ERROR_HW_FAILURE if access to the memory failed.
199  *
200  * @notapi
201  */
202 flash_error_t efl_lld_program(void *instance, flash_offset_t offset,
203  size_t n, const uint8_t *pp) {
204  EFlashDriver *devp = (EFlashDriver *)instance;
205  flash_error_t err = FLASH_NO_ERROR;
206 
207  osalDbgCheck((instance != NULL) && (pp != NULL) && (n > 0U));
208  osalDbgCheck(((size_t)offset + n) <= (size_t)efl_lld_descriptor.size);
209 
210  osalDbgAssert((devp->state == FLASH_READY) || (devp->state == FLASH_ERASE),
211  "invalid state");
212 
213  /* No programming while erasing.*/
214  if (devp->state == FLASH_ERASE) {
215  return FLASH_BUSY_ERASING;
216  }
217 
218  /* FLASH_PGM state while the operation is performed.*/
219  devp->state = FLASH_PGM;
220 
221  /* IMPLEMENT */
222 
223  /* Ready state again.*/
224  devp->state = FLASH_READY;
225 
226  return err;
227 }
228 
229 /**
230  * @brief Starts a whole-device erase operation.
231  * @note This function only erases bank 2 if it is present. Bank 1 is not
232  * touched because it is where the program is running on.
233  * Pages on bank 1 can be individually erased.
234  *
235  * @param[in] instance pointer to a @p EFlashDriver instance
236  * @return An error code.
237  * @retval FLASH_NO_ERROR if there is no erase operation in progress.
238  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.
239  * @retval FLASH_ERROR_HW_FAILURE if access to the memory failed.
240  *
241  * @notapi
242  */
243 flash_error_t efl_lld_start_erase_all(void *instance) {
244  EFlashDriver *devp = (EFlashDriver *)instance;
245 
246  osalDbgCheck(instance != NULL);
247  osalDbgAssert((devp->state == FLASH_READY) || (devp->state == FLASH_ERASE),
248  "invalid state");
249 
250  /* No erasing while erasing.*/
251  if (devp->state == FLASH_ERASE) {
252  return FLASH_BUSY_ERASING;
253  }
254 
255  /* FLASH_PGM state while the operation is performed.*/
256  devp->state = FLASH_ERASE;
257 
258  /* IMPLEMENT */
259 
260  return FLASH_NO_ERROR;
261 }
262 
263 /**
264  * @brief Starts an sector erase operation.
265  *
266  * @param[in] instance pointer to a @p EFlashDriver instance
267  * @param[in] sector sector to be erased
268  * @return An error code.
269  * @retval FLASH_NO_ERROR if there is no erase operation in progress.
270  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.
271  * @retval FLASH_ERROR_HW_FAILURE if access to the memory failed.
272  *
273  * @notapi
274  */
275 flash_error_t efl_lld_start_erase_sector(void *instance,
276  flash_sector_t sector) {
277  EFlashDriver *devp = (EFlashDriver *)instance;
278 
279  osalDbgCheck(instance != NULL);
280  osalDbgCheck(sector < efl_lld_descriptor.sectors_count);
281  osalDbgAssert((devp->state == FLASH_READY) || (devp->state == FLASH_ERASE),
282  "invalid state");
283 
284  /* No erasing while erasing.*/
285  if (devp->state == FLASH_ERASE) {
286  return FLASH_BUSY_ERASING;
287  }
288 
289  /* FLASH_PGM state while the operation is performed.*/
290  devp->state = FLASH_ERASE;
291 
292  /* IMPLEMENT */
293 
294  return FLASH_NO_ERROR;
295 }
296 
297 /**
298  * @brief Queries the driver for erase operation progress.
299  *
300  * @param[in] instance pointer to a @p EFlashDriver instance
301  * @param[out] msec recommended time, in milliseconds, that
302  * should be spent before calling this
303  * function again, can be @p NULL
304  * @return An error code.
305  * @retval FLASH_NO_ERROR if there is no erase operation in progress.
306  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.
307  * @retval FLASH_ERROR_ERASE if the erase operation failed.
308  * @retval FLASH_ERROR_HW_FAILURE if access to the memory failed.
309  *
310  * @api
311  */
312 flash_error_t efl_lld_query_erase(void *instance, uint32_t *msec) {
313  EFlashDriver *devp = (EFlashDriver *)instance;
314  flash_error_t err = FLASH_NO_ERROR;
315 
316  (void)msec;
317 
318  /* If there is an erase in progress then the device must be checked.*/
319  if (devp->state == FLASH_ERASE) {
320 
321  /* IMPLEMENT */
322 
323  }
324 
325  return err;
326 }
327 
328 /**
329  * @brief Returns the erase state of a sector.
330  *
331  * @param[in] instance pointer to a @p EFlashDriver instance
332  * @param[in] sector sector to be verified
333  * @return An error code.
334  * @retval FLASH_NO_ERROR if the sector is erased.
335  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.
336  * @retval FLASH_ERROR_VERIFY if the verify operation failed.
337  * @retval FLASH_ERROR_HW_FAILURE if access to the memory failed.
338  *
339  * @notapi
340  */
341 flash_error_t efl_lld_verify_erase(void *instance, flash_sector_t sector) {
342  EFlashDriver *devp = (EFlashDriver *)instance;
343  flash_error_t err = FLASH_NO_ERROR;
344 
345  osalDbgCheck(instance != NULL);
346  osalDbgCheck(sector < efl_lld_descriptor.sectors_count);
347  osalDbgAssert((devp->state == FLASH_READY) || (devp->state == FLASH_ERASE),
348  "invalid state");
349 
350  /* No verifying while erasing.*/
351  if (devp->state == FLASH_ERASE) {
352  return FLASH_BUSY_ERASING;
353  }
354 
355  /* IMPLEMENT */
356 
357  /* Ready state again.*/
358  devp->state = FLASH_READY;
359 
360  return err;
361 }
362 
363 #endif /* HAL_USE_EFL == TRUE */
364 
365 /** @} */
hal.h
HAL subsystem header.
efl_lld_query_erase
flash_error_t efl_lld_query_erase(void *instance, uint32_t *msec)
Queries the driver for erase operation progress.
Definition: hal_efl_lld.c:312
efl_lld_verify_erase
flash_error_t efl_lld_verify_erase(void *instance, flash_sector_t sector)
Returns the erase state of a sector.
Definition: hal_efl_lld.c:341
hal_efl_driver
Structure representing an embedded flash driver.
Definition: hal_efl.h:97
flash_descriptor_t
Type of a flash device descriptor.
Definition: hal_flash.h:137
efl_lld_init
void efl_lld_init(void)
Low level Embedded Flash driver initialization.
Definition: hal_efl_lld.c:78
efl_lld_start_erase_sector
flash_error_t efl_lld_start_erase_sector(void *instance, flash_sector_t sector)
Starts an sector erase operation.
Definition: hal_efl_lld.c:275
flash_descriptor_t::size
uint32_t size
Flash size.
Definition: hal_flash.h:170
FLASH_ATTR_ECC_ZERO_LINE_CAPABLE
#define FLASH_ATTR_ECC_ZERO_LINE_CAPABLE
The device is able to overwrite zero to a line.
Definition: hal_flash.h:65
flash_descriptor_t::attributes
uint32_t attributes
Device_attributes.
Definition: hal_flash.h:141
efl_lld_stop
void efl_lld_stop(EFlashDriver *eflp)
Deactivates the Embedded Flash peripheral.
Definition: hal_efl_lld.c:114
EFLD1
EFlashDriver EFLD1
EFL1 driver identifier.
Definition: hal_efl_lld.c:41
flash_sector_t
uint32_t flash_sector_t
Type of a flash sector number.
Definition: hal_flash.h:118
efl_lld_program
flash_error_t efl_lld_program(void *instance, flash_offset_t offset, size_t n, const uint8_t *pp)
Program operation.
Definition: hal_efl_lld.c:202
efl_lld_read
flash_error_t efl_lld_read(void *instance, flash_offset_t offset, size_t n, uint8_t *rp)
Read operation.
Definition: hal_efl_lld.c:158
osalDbgCheck
#define osalDbgCheck(c)
Function parameters check.
Definition: osal.h:284
efl_lld_start
void efl_lld_start(EFlashDriver *eflp)
Configures and activates the Embedded Flash peripheral.
Definition: hal_efl_lld.c:93
flash_descriptor_t::sectors_count
flash_sector_t sectors_count
Number of sectors in the device.
Definition: hal_flash.h:149
flash_error_t
flash_error_t
Type of a flash error code.
Definition: hal_flash.h:99
FLASH_ATTR_ERASED_IS_ONE
#define FLASH_ATTR_ERASED_IS_ONE
Defines one as the erased bit state.
Definition: hal_flash.h:39
osalDbgAssert
#define osalDbgAssert(c, remark)
Condition assertion.
Definition: osal.h:264
FLASH_ATTR_MEMORY_MAPPED
#define FLASH_ATTR_MEMORY_MAPPED
The memory is accessible in a memory mapped mode.
Definition: hal_flash.h:43
flash_offset_t
uint32_t flash_offset_t
Type of a flash offset.
Definition: hal_flash.h:113
efl_lld_get_descriptor
const flash_descriptor_t * efl_lld_get_descriptor(void *instance)
Gets the flash descriptor structure.
Definition: hal_efl_lld.c:136
FLASH_ATTR_ECC_CAPABLE
#define FLASH_ATTR_ECC_CAPABLE
The memory is protected by an ECC mechanism.
Definition: hal_flash.h:59
eflObjectInit
void eflObjectInit(EFlashDriver *eflp)
Initializes a generic EFlashDriver object.
Definition: hal_efl.c:79
efl_lld_start_erase_all
flash_error_t efl_lld_start_erase_all(void *instance)
Starts a whole-device erase operation.
Definition: hal_efl_lld.c:243