2 * -------------------------------------------
3 * MSP432 DriverLib - v3_10_00_09
4 * -------------------------------------------
6 * --COPYRIGHT--,BSD,BSD
7 * Copyright (c) 2014, Texas Instruments Incorporated
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
14 * * Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
17 * * Redistributions in binary form must reproduce the above copyright
18 * notice, this list of conditions and the following disclaimer in the
19 * documentation and/or other materials provided with the distribution.
21 * * Neither the name of Texas Instruments Incorporated nor the names of
22 * its contributors may be used to endorse or promote products derived
23 * from this software without specific prior written permission.
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
26 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
27 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
29 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
32 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
34 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
35 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 //*****************************************************************************
42 //! \addtogroup mpu_api
45 //*****************************************************************************
48 //*****************************************************************************
50 // If building with a C++ compiler, make all of the definitions in this header
53 //*****************************************************************************
62 //*****************************************************************************
64 // Flags that can be passed to MPU_enableModule.
66 //*****************************************************************************
67 #define MPU_CONFIG_PRIV_DEFAULT MPU_CTRL_PRIVDEFENA_Msk
68 #define MPU_CONFIG_HARDFLT_NMI MPU_CTRL_HFNMIENA_Msk
69 #define MPU_CONFIG_NONE 0
71 //*****************************************************************************
73 // Flags for the region size to be passed to MPU_setRegion.
75 //*****************************************************************************
76 #define MPU_RGN_SIZE_32B (4 << 1)
77 #define MPU_RGN_SIZE_64B (5 << 1)
78 #define MPU_RGN_SIZE_128B (6 << 1)
79 #define MPU_RGN_SIZE_256B (7 << 1)
80 #define MPU_RGN_SIZE_512B (8 << 1)
82 #define MPU_RGN_SIZE_1K (9 << 1)
83 #define MPU_RGN_SIZE_2K (10 << 1)
84 #define MPU_RGN_SIZE_4K (11 << 1)
85 #define MPU_RGN_SIZE_8K (12 << 1)
86 #define MPU_RGN_SIZE_16K (13 << 1)
87 #define MPU_RGN_SIZE_32K (14 << 1)
88 #define MPU_RGN_SIZE_64K (15 << 1)
89 #define MPU_RGN_SIZE_128K (16 << 1)
90 #define MPU_RGN_SIZE_256K (17 << 1)
91 #define MPU_RGN_SIZE_512K (18 << 1)
93 #define MPU_RGN_SIZE_1M (19 << 1)
94 #define MPU_RGN_SIZE_2M (20 << 1)
95 #define MPU_RGN_SIZE_4M (21 << 1)
96 #define MPU_RGN_SIZE_8M (22 << 1)
97 #define MPU_RGN_SIZE_16M (23 << 1)
98 #define MPU_RGN_SIZE_32M (24 << 1)
99 #define MPU_RGN_SIZE_64M (25 << 1)
100 #define MPU_RGN_SIZE_128M (26 << 1)
101 #define MPU_RGN_SIZE_256M (27 << 1)
102 #define MPU_RGN_SIZE_512M (28 << 1)
104 #define MPU_RGN_SIZE_1G (29 << 1)
105 #define MPU_RGN_SIZE_2G (30 << 1)
106 #define MPU_RGN_SIZE_4G (31 << 1)
108 //*****************************************************************************
110 // Flags for the permissions to be passed to MPU_setRegion.
112 //*****************************************************************************
113 #define MPU_RGN_PERM_EXEC 0x00000000
114 #define MPU_RGN_PERM_NOEXEC 0x10000000
115 #define MPU_RGN_PERM_PRV_NO_USR_NO 0x00000000
116 #define MPU_RGN_PERM_PRV_RW_USR_NO 0x01000000
117 #define MPU_RGN_PERM_PRV_RW_USR_RO 0x02000000
118 #define MPU_RGN_PERM_PRV_RW_USR_RW 0x03000000
119 #define MPU_RGN_PERM_PRV_RO_USR_NO 0x05000000
120 #define MPU_RGN_PERM_PRV_RO_USR_RO 0x06000000
122 //*****************************************************************************
124 // Flags for the sub-region to be passed to MPU_setRegion.
126 //*****************************************************************************
127 #define MPU_SUB_RGN_DISABLE_0 0x00000100
128 #define MPU_SUB_RGN_DISABLE_1 0x00000200
129 #define MPU_SUB_RGN_DISABLE_2 0x00000400
130 #define MPU_SUB_RGN_DISABLE_3 0x00000800
131 #define MPU_SUB_RGN_DISABLE_4 0x00001000
132 #define MPU_SUB_RGN_DISABLE_5 0x00002000
133 #define MPU_SUB_RGN_DISABLE_6 0x00004000
134 #define MPU_SUB_RGN_DISABLE_7 0x00008000
136 //*****************************************************************************
138 // Flags to enable or disable a region, to be passed to MPU_setRegion.
140 //*****************************************************************************
141 #define MPU_RGN_ENABLE 1
142 #define MPU_RGN_DISABLE 0
144 #define NVIC_MPU_TYPE_DREGION_S 8
146 //*****************************************************************************
148 // API Function prototypes
150 //*****************************************************************************
152 //*****************************************************************************
154 //! Enables and configures the MPU for use.
156 //! \param mpuConfig is the logical OR of the possible configurations.
158 //! This function enables the Cortex-M memory protection unit. It also
159 //! configures the default behavior when in privileged mode and while handling
160 //! a hard fault or NMI. Prior to enabling the MPU, at least one region must
161 //! be set by calling MPU_setRegion() or else by enabling the default region for
162 //! privileged mode by passing the \b MPU_CONFIG_PRIV_DEFAULT flag to
163 //! MPU_enableModule(). Once the MPU is enabled, a memory management fault is
164 //! generated for memory access violations.
166 //! The \e mpuConfig parameter should be the logical OR of any of the
169 //! - \b MPU_CONFIG_PRIV_DEFAULT enables the default memory map when in
170 //! privileged mode and when no other regions are defined. If this option
171 //! is not enabled, then there must be at least one valid region already
172 //! defined when the MPU is enabled.
173 //! - \b MPU_CONFIG_HARDFLT_NMI enables the MPU while in a hard fault or NMI
174 //! exception handler. If this option is not enabled, then the MPU is
175 //! disabled while in one of these exception handlers and the default
176 //! memory map is applied.
177 //! - \b MPU_CONFIG_NONE chooses none of the above options. In this case,
178 //! no default memory map is provided in privileged mode, and the MPU is
179 //! not enabled in the fault handlers.
183 //*****************************************************************************
184 extern void MPU_enableModule(uint32_t mpuConfig);
186 //*****************************************************************************
188 //! Disables the MPU for use.
190 //! This function disables the Cortex-M memory protection unit. When the
191 //! MPU is disabled, the default memory map is used and memory management
192 //! faults are not generated.
196 //*****************************************************************************
197 extern void MPU_disableModule(void);
199 //*****************************************************************************
201 //! Gets the count of regions supported by the MPU.
203 //! This function is used to get the total number of regions that are supported
204 //! by the MPU, including regions that are already programmed.
206 //! \return The number of memory protection regions that are available
207 //! for programming using MPU_setRegion().
209 //*****************************************************************************
210 extern uint32_t MPU_getRegionCount(void);
212 //*****************************************************************************
214 //! Enables a specific region.
216 //! \param region is the region number to enable. Valid values are between
217 //! 0 and 7 inclusively.
219 //! This function is used to enable a memory protection region. The region
220 //! should already be configured with the MPU_setRegion() function. Once
221 //! enabled, the memory protection rules of the region are applied and access
222 //! violations cause a memory management fault.
226 //*****************************************************************************
227 extern void MPU_enableRegion(uint32_t region);
229 //*****************************************************************************
231 //! Disables a specific region.
233 //! \param region is the region number to disable. Valid values are between
234 //! 0 and 7 inclusively.
236 //! This function is used to disable a previously enabled memory protection
237 //! region. The region remains configured if it is not overwritten with
238 //! another call to MPU_setRegion(), and can be enabled again by calling
239 //! MPU_enableRegion().
243 //*****************************************************************************
244 extern void MPU_disableRegion(uint32_t region);
246 //*****************************************************************************
248 //! Sets up the access rules for a specific region.
250 //! \param region is the region number to set up.
251 //! \param addr is the base address of the region. It must be aligned
252 //! according to the size of the region specified in flags.
253 //! \param flags is a set of flags to define the attributes of the region.
255 //! This function sets up the protection rules for a region. The region has
256 //! a base address and a set of attributes including the size. The base
257 //! address parameter, \e addr, must be aligned according to the size, and
258 //! the size must be a power of 2.
260 //! \param region is the region number to set. Valid values are between
261 //! 0 and 7 inclusively.
263 //! The \e flags parameter is the logical OR of all of the attributes
264 //! of the region. It is a combination of choices for region size,
265 //! execute permission, read/write permissions, disabled sub-regions,
266 //! and a flag to determine if the region is enabled.
268 //! The size flag determines the size of a region and must be one of the
271 //! - \b MPU_RGN_SIZE_32B
272 //! - \b MPU_RGN_SIZE_64B
273 //! - \b MPU_RGN_SIZE_128B
274 //! - \b MPU_RGN_SIZE_256B
275 //! - \b MPU_RGN_SIZE_512B
276 //! - \b MPU_RGN_SIZE_1K
277 //! - \b MPU_RGN_SIZE_2K
278 //! - \b MPU_RGN_SIZE_4K
279 //! - \b MPU_RGN_SIZE_8K
280 //! - \b MPU_RGN_SIZE_16K
281 //! - \b MPU_RGN_SIZE_32K
282 //! - \b MPU_RGN_SIZE_64K
283 //! - \b MPU_RGN_SIZE_128K
284 //! - \b MPU_RGN_SIZE_256K
285 //! - \b MPU_RGN_SIZE_512K
286 //! - \b MPU_RGN_SIZE_1M
287 //! - \b MPU_RGN_SIZE_2M
288 //! - \b MPU_RGN_SIZE_4M
289 //! - \b MPU_RGN_SIZE_8M
290 //! - \b MPU_RGN_SIZE_16M
291 //! - \b MPU_RGN_SIZE_32M
292 //! - \b MPU_RGN_SIZE_64M
293 //! - \b MPU_RGN_SIZE_128M
294 //! - \b MPU_RGN_SIZE_256M
295 //! - \b MPU_RGN_SIZE_512M
296 //! - \b MPU_RGN_SIZE_1G
297 //! - \b MPU_RGN_SIZE_2G
298 //! - \b MPU_RGN_SIZE_4G
300 //! The execute permission flag must be one of the following:
302 //! - \b MPU_RGN_PERM_EXEC enables the region for execution of code
303 //! - \b MPU_RGN_PERM_NOEXEC disables the region for execution of code
305 //! The read/write access permissions are applied separately for the
306 //! privileged and user modes. The read/write access flags must be one
307 //! of the following:
309 //! - \b MPU_RGN_PERM_PRV_NO_USR_NO - no access in privileged or user mode
310 //! - \b MPU_RGN_PERM_PRV_RW_USR_NO - privileged read/write, user no access
311 //! - \b MPU_RGN_PERM_PRV_RW_USR_RO - privileged read/write, user read-only
312 //! - \b MPU_RGN_PERM_PRV_RW_USR_RW - privileged read/write, user read/write
313 //! - \b MPU_RGN_PERM_PRV_RO_USR_NO - privileged read-only, user no access
314 //! - \b MPU_RGN_PERM_PRV_RO_USR_RO - privileged read-only, user read-only
316 //! The region is automatically divided into 8 equally-sized sub-regions by
317 //! the MPU. Sub-regions can only be used in regions of size 256 bytes
318 //! or larger. Any of these 8 sub-regions can be disabled, allowing for
319 //! creation of ``holes'' in a region which can be left open, or overlaid
320 //! by another region with different attributes. Any of the 8 sub-regions
321 //! can be disabled with a logical OR of any of the following flags:
323 //! - \b MPU_SUB_RGN_DISABLE_0
324 //! - \b MPU_SUB_RGN_DISABLE_1
325 //! - \b MPU_SUB_RGN_DISABLE_2
326 //! - \b MPU_SUB_RGN_DISABLE_3
327 //! - \b MPU_SUB_RGN_DISABLE_4
328 //! - \b MPU_SUB_RGN_DISABLE_5
329 //! - \b MPU_SUB_RGN_DISABLE_6
330 //! - \b MPU_SUB_RGN_DISABLE_7
332 //! Finally, the region can be initially enabled or disabled with one of
333 //! the following flags:
335 //! - \b MPU_RGN_ENABLE
336 //! - \b MPU_RGN_DISABLE
338 //! As an example, to set a region with the following attributes: size of
339 //! 32 KB, execution enabled, read-only for both privileged and user, one
340 //! sub-region disabled, and initially enabled; the \e flags parameter would
341 //! have the following value:
344 //! (MPU_RGN_SIZE_32K | MPU_RGN_PERM_EXEC | MPU_RGN_PERM_PRV_RO_USR_RO |
345 //! MPU_SUB_RGN_DISABLE_2 | MPU_RGN_ENABLE)
348 //! \note This function writes to multiple registers and is not protected
349 //! from interrupts. It is possible that an interrupt which accesses a
350 //! region may occur while that region is in the process of being changed.
351 //! The safest way to handle this is to disable a region before changing it.
352 //! Refer to the discussion of this in the API Detailed Description section.
356 //*****************************************************************************
357 extern void MPU_setRegion(uint32_t region, uint32_t addr, uint32_t flags);
359 //*****************************************************************************
361 //! Gets the current settings for a specific region.
363 //! \param region is the region number to get. Valid values are between
364 //! 0 and 7 inclusively.
365 //! \param addr points to storage for the base address of the region.
366 //! \param pflags points to the attribute flags for the region.
368 //! This function retrieves the configuration of a specific region. The
369 //! meanings and format of the parameters is the same as that of the
370 //! MPU_setRegion() function.
372 //! This function can be used to save the configuration of a region for later
373 //! use with the MPU_setRegion() function. The region's enable state is
374 //! preserved in the attributes that are saved.
378 //*****************************************************************************
379 extern void MPU_getRegion(uint32_t region, uint32_t *addr, uint32_t *pflags);
381 //*****************************************************************************
383 //! Registers an interrupt handler for the memory management fault.
385 //! \param intHandler is a pointer to the function to be called when the
386 //! memory management fault occurs.
388 //! This function sets and enables the handler to be called when the MPU
389 //! generates a memory management fault due to a protection region access
392 //! \sa Interrupt_registerInterrupt() for important information about
393 //! registering interrupt handlers.
397 //*****************************************************************************
398 extern void MPU_registerInterrupt(void (*intHandler)(void));
400 //*****************************************************************************
402 //! Unregisters an interrupt handler for the memory management fault.
404 //! This function disables and clears the handler to be called when a
405 //! memory management fault occurs.
407 //! \sa Interrupt_registerInterrupt() for important information about
408 //! registering interrupt handlers.
412 //*****************************************************************************
413 extern void MPU_unregisterInterrupt(void);
415 //*****************************************************************************
417 //! Enables the interrupt for the memory management fault.
421 //*****************************************************************************
422 extern void MPU_enableInterrupt(void);
424 //*****************************************************************************
426 //! Disables the interrupt for the memory management fault.
430 //*****************************************************************************
431 extern void MPU_disableInterrupt(void);
433 //*****************************************************************************
435 // Mark the end of the C bindings section for C++ compilers.
437 //*****************************************************************************
442 //*****************************************************************************
444 // Close the Doxygen group.
447 //*****************************************************************************