1 /***************************************************************************//**
2 * @file
3 * @brief Flash controller module (MSC) peripheral API
4 * @author Energy Micro AS
5 * @version 3.0.0
6 *******************************************************************************
7 * @section License
8 * <b>(C) Copyright 2012 Energy Micro AS, http://www.energymicro.com</b>
9 *******************************************************************************
10 *
11 * Permission is granted to anyone to use this software for any purpose,
12 * including commercial applications, and to alter it and redistribute it
13 * freely, subject to the following restrictions:
14 *
15 * 1. The origin of this software must not be misrepresented; you must not
16 * claim that you wrote the original software.
17 * 2. Altered source versions must be plainly marked as such, and must not be
18 * misrepresented as being the original software.
19 * 3. This notice may not be removed or altered from any source distribution.
20 *
21 * DISCLAIMER OF WARRANTY/LIMITATION OF REMEDIES: Energy Micro AS has no
22 * obligation to support this Software. Energy Micro AS is providing the
23 * Software "AS IS", with no express or implied warranties of any kind,
24 * including, but not limited to, any implied warranties of merchantability
25 * or fitness for any particular purpose or warranties against infringement
26 * of any proprietary rights of a third party.
27 *
28 * Energy Micro AS will not be liable for any consequential, incidental, or
29 * special damages, or any other relief, or for any claim by any third party,
30 * arising from your use of this Software.
31 *
32 ******************************************************************************/
33 #ifndef __EM_MSC_H
34 #define __EM_MSC_H
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39
40 #include <stdint.h>
41 #include <stdbool.h>
42
43 #include "em_part.h"
44 #include "em_bitband.h"
45
46
47 /***************************************************************************//**
48 * @addtogroup EM_Library
49 * @{
50 ******************************************************************************/
51
52 /***************************************************************************//**
53 * @addtogroup MSC
54 * @brief Flash controller (MSC) peripheral API
55 * @{
56 ******************************************************************************/
57
58 /*******************************************************************************
59 ************************* DEFINES *****************************************
60 ******************************************************************************/
61
62 /**
63 * @brief
64 * The timeout used while waiting for the flash to become ready after
65 * a write. This number indicates the number of iterations to perform before
66 * issuing a timeout.
67 * @note
68 * This timeout is set very large (in the order of 100x longer than
69 * necessary). This is to avoid any corner cases.
70 *
71 */
72 #define MSC_PROGRAM_TIMEOUT 10000000ul
73
74 /*******************************************************************************
75 ************************* TYPEDEFS ****************************************
76 ******************************************************************************/
77
78 /** Return codes for writing/erasing the flash */
79 typedef enum
80 {
81 mscReturnOk = 0, /**< Flash write/erase successful. */
82 mscReturnInvalidAddr = -1, /**< Invalid address. Write to an address that is not flash. */
83 mscReturnLocked = -2, /**< Flash address is locked. */
84 mscReturnTimeOut = -3, /**< Timeout while writing to flash. */
85 mscReturnUnaligned = -4 /**< Unaligned access to flash. */
86 } msc_Return_TypeDef;
87
88
89 #if defined (_EFM32_GIANT_FAMILY)
90 /** Strategy for prioritized bus access */
91 typedef enum {
92 mscBusStrategyCPU = MSC_READCTRL_BUSSTRATEGY_CPU, /**< Prioritize CPU bus accesses */
93 mscBusStrategyDMA = MSC_READCTRL_BUSSTRATEGY_DMA, /**< Prioritize DMA bus accesses */
94 mscBusStrategyDMAEM1 = MSC_READCTRL_BUSSTRATEGY_DMAEM1, /**< Prioritize DMAEM1 for bus accesses */
95 mscBusStrategyNone = MSC_READCTRL_BUSSTRATEGY_NONE /**< No unit has bus priority */
96 } mscBusStrategy_Typedef;
97 #endif
98
99 /*******************************************************************************
100 ************************* PROTOTYPES **************************************
101 ******************************************************************************/
102
103 void MSC_Deinit(void);
104 void MSC_Init(void);
105
106 /***************************************************************************//**
107 * @brief
108 * Clear one or more pending MSC interrupts.
109 *
110 * @param[in] flags
111 * Pending MSC intterupt source to clear. Use a bitwise logic OR combination
112 * of valid interrupt flags for the MSC module (MSC_IF_nnn).
113 ******************************************************************************/
MSC_IntClear(uint32_t flags)114 __STATIC_INLINE void MSC_IntClear(uint32_t flags)
115 {
116 MSC->IFC = flags;
117 }
118
119 /***************************************************************************//**
120 * @brief
121 * Disable one or more MSC interrupts.
122 *
123 * @param[in] flags
124 * MSC interrupt sources to disable. Use a bitwise logic OR combination of
125 * valid interrupt flags for the MSC module (MSC_IF_nnn).
126 ******************************************************************************/
MSC_IntDisable(uint32_t flags)127 __STATIC_INLINE void MSC_IntDisable(uint32_t flags)
128 {
129 MSC->IEN &= ~(flags);
130 }
131
132
133 /***************************************************************************//**
134 * @brief
135 * Enable one or more MSC interrupts.
136 *
137 * @note
138 * Depending on the use, a pending interrupt may already be set prior to
139 * enabling the interrupt. Consider using MSC_IntClear() prior to enabling
140 * if such a pending interrupt should be ignored.
141 *
142 * @param[in] flags
143 * MSC interrupt sources to enable. Use a bitwise logic OR combination of
144 * valid interrupt flags for the MSC module (MSC_IF_nnn).
145 ******************************************************************************/
MSC_IntEnable(uint32_t flags)146 __STATIC_INLINE void MSC_IntEnable(uint32_t flags)
147 {
148 MSC->IEN |= flags;
149 }
150
151
152 /***************************************************************************//**
153 * @brief
154 * Get pending MSV interrupt flags.
155 *
156 * @note
157 * The event bits are not cleared by the use of this function.
158 *
159 * @return
160 * MSC interrupt sources pending. A bitwise logic OR combination of valid
161 * interrupt flags for the MSC module (MSC_IF_nnn).
162 ******************************************************************************/
MSC_IntGet(void)163 __STATIC_INLINE uint32_t MSC_IntGet(void)
164 {
165 return(MSC->IF);
166 }
167
168
169 /***************************************************************************//**
170 * @brief
171 * Set one or more pending MSC interrupts from SW.
172 *
173 * @param[in] flags
174 * MSC interrupt sources to set to pending. Use a bitwise logic OR combination of
175 * valid interrupt flags for the MSC module (MSC_IF_nnn).
176 ******************************************************************************/
MSC_IntSet(uint32_t flags)177 __STATIC_INLINE void MSC_IntSet(uint32_t flags)
178 {
179 MSC->IFS = flags;
180 }
181
182
183 #if defined(_EFM32_TINY_FAMILY) || defined(_EFM32_GIANT_FAMILY)
184 /***************************************************************************//**
185 * @brief
186 * Starts measuring cache hit ratio.
187 * @details
188 * This function starts the performance counters. It is defined inline to
189 * minimize the impact of this code on the measurement itself.
190 ******************************************************************************/
MSC_StartCacheMeasurement(void)191 __STATIC_INLINE void MSC_StartCacheMeasurement(void)
192 {
193 /* Clear CMOF and CHOF to catch these later */
194 MSC->IFC = MSC_IF_CHOF | MSC_IF_CMOF;
195
196 /* Start performance counters */
197 MSC->CMD = MSC_CMD_STARTPC;
198 }
199
200
201 /***************************************************************************//**
202 * @brief
203 * Stops measuring the hit rate.
204 * @note
205 * This function is defined inline to minimize the impact of this
206 * code on the measurement itself.
207 * This code only works for relatively short sections of code. If you wish
208 * to measure longer sections of code you need to implement a IRQ Handler for
209 * The CHOF and CMOF overflow interrupts. Theses overflows needs to be
210 * counted and included in the total.
211 * The functions can then be implemented as follows:
212 * @verbatim
213 * volatile uint32_t hitOverflows
214 * volatile uint32_t missOverflows
215 *
216 * void MSC_IRQHandler(void)
217 * {
218 * uint32_t flags;
219 * flags = MSC->IF;
220 * if (flags & MSC_IF_CHOF)
221 * {
222 * MSC->IFC = MSC_IF_CHOF;
223 * hitOverflows++;
224 * }
225 * if (flags & MSC_IF_CMOF)
226 * {
227 * MSC->IFC = MSC_IF_CMOF;
228 * missOverflows++;
229 * }
230 * }
231 *
232 * void startPerformanceCounters(void)
233 * {
234 * hitOverflows = 0;
235 * missOverflows = 0;
236 *
237 * MSC_IntEnable(MSC_IF_CHOF | MSC_IF_CMOF);
238 * NVIC_EnableIRQ(MSC_IRQn);
239 *
240 * MSC_StartCacheMeasurement();
241 * }
242 * @endverbatim
243 * @return
244 * Returns -1 if there has been no cache accesses.
245 * Returns -2 if there has been an overflow in the performance counters.
246 * If not, it will return the percentage of hits versus misses.
247 ******************************************************************************/
MSC_GetCacheMeasurement(void)248 __STATIC_INLINE int32_t MSC_GetCacheMeasurement(void)
249 {
250 int32_t total;
251 /* Stop the counter before computing the hit-rate */
252 MSC->CMD = MSC_CMD_STOPPC;
253
254 /* Check for overflows in performance counters */
255 if (MSC->IF & (MSC_IF_CHOF | MSC_IF_CMOF))
256 return -2;
257
258 /* Because the hits and misses are volatile, we need to split this up into
259 * two statements to avoid a compiler warning regarding the order of volatile
260 * accesses. */
261 total = MSC->CACHEHITS;
262 total += MSC->CACHEMISSES;
263
264 /* To avoid a division by zero. */
265 if (total == 0)
266 return -1;
267
268 return (MSC->CACHEHITS * 100) / total;
269 }
270
271
272 /***************************************************************************//**
273 * @brief
274 * Flush the contents of the instruction cache.
275 ******************************************************************************/
MSC_FlushCache(void)276 __STATIC_INLINE void MSC_FlushCache(void)
277 {
278 MSC->CMD = MSC_CMD_INVCACHE;
279 }
280
281
282 /***************************************************************************//**
283 * @brief
284 * Enable or disable instruction cache functionality
285 * @param[in] enable
286 * Enable instruction cache. Default is on.
287 ******************************************************************************/
MSC_EnableCache(bool enable)288 __STATIC_INLINE void MSC_EnableCache(bool enable)
289 {
290 BITBAND_Peripheral(&(MSC->READCTRL), _MSC_READCTRL_IFCDIS_SHIFT, ~enable);
291 }
292
293
294 /***************************************************************************//**
295 * @brief
296 * Enable or disable instruction cache functionality in IRQs
297 * @param[in] enable
298 * Enable instruction cache. Default is on.
299 ******************************************************************************/
MSC_EnableCacheIRQs(bool enable)300 __STATIC_INLINE void MSC_EnableCacheIRQs(bool enable)
301 {
302 BITBAND_Peripheral(&(MSC->READCTRL), _MSC_READCTRL_ICCDIS_SHIFT, ~enable);
303 }
304
305
306 /***************************************************************************//**
307 * @brief
308 * Enable or disable instruction cache flushing when writing to flash
309 * @param[in] enable
310 * Enable automatic cache flushing. Default is on.
311 ******************************************************************************/
MSC_EnableAutoCacheFlush(bool enable)312 __STATIC_INLINE void MSC_EnableAutoCacheFlush(bool enable)
313 {
314 BITBAND_Peripheral(&(MSC->READCTRL), _MSC_READCTRL_AIDIS_SHIFT, ~enable);
315 }
316 #endif
317
318
319 #if defined(_EFM32_GIANT_FAMILY)
320 /***************************************************************************//**
321 * @brief
322 * Configure which unit should get priority on system bus.
323 * @param[in] mode
324 * Unit to prioritize bus accesses for.
325 ******************************************************************************/
MSC_BusStrategy(mscBusStrategy_Typedef mode)326 __STATIC_INLINE void MSC_BusStrategy(mscBusStrategy_Typedef mode)
327 {
328 MSC->READCTRL = (MSC->READCTRL & ~(_MSC_READCTRL_BUSSTRATEGY_MASK))|mode;
329 }
330 #endif
331
332 #ifdef __CC_ARM /* MDK-ARM compiler */
333 msc_Return_TypeDef MSC_WriteWord(uint32_t *address, void const *data, int numBytes);
334 msc_Return_TypeDef MSC_ErasePage(uint32_t *startAddress);
335 #if defined (_EFM32_GIANT_FAMILY)
336 msc_Return_TypeDef MSC_MassErase(void);
337 #endif
338 #endif /* __CC_ARM */
339
340 #ifdef __ICCARM__ /* IAR compiler */
341 __ramfunc msc_Return_TypeDef MSC_WriteWord(uint32_t *address, void const *data, int numBytes);
342 __ramfunc msc_Return_TypeDef MSC_ErasePage(uint32_t *startAddress);
343 #if defined (_EFM32_GIANT_FAMILY)
344 __ramfunc msc_Return_TypeDef MSC_MassErase(void);
345 #endif
346 #endif /* __ICCARM__ */
347
348 #ifdef __GNUC__ /* GCC based compilers */
349 #ifdef __CROSSWORKS_ARM /* Rowley Crossworks */
350 msc_Return_TypeDef MSC_WriteWord(uint32_t *address, void const *data, int numBytes) __attribute__ ((section(".fast")));
351 msc_Return_TypeDef MSC_ErasePage(uint32_t *startAddress) __attribute__ ((section(".fast")));
352 #if defined (_EFM32_GIANT_FAMILY)
353 msc_Return_TypeDef MSC_MassErase(void) __attribute__ ((section(".fast")));
354 #endif
355 #else /* Sourcery G++ */
356 msc_Return_TypeDef MSC_WriteWord(uint32_t *address, void const *data, int numBytes) __attribute__ ((section(".ram")));
357 msc_Return_TypeDef MSC_ErasePage(uint32_t *startAddress) __attribute__ ((section(".ram")));
358 #if defined (_EFM32_GIANT_FAMILY)
359 msc_Return_TypeDef MSC_MassErase(void) __attribute__ ((section(".ram")));
360 #endif
361
362 #endif /* __GNUC__ */
363 #endif /* __CROSSWORKS_ARM */
364
365 /** @} (end addtogroup MSC) */
366 /** @} (end addtogroup EM_Library) */
367
368 #ifdef __cplusplus
369 }
370 #endif
371
372 #endif /* __EM_MSC_H */
373