mpu_api.h

 
/** \addtogroup hal */
/** @{*/
/* mbed Microcontroller Library
 * Copyright (c) 2018-2018 ARM Limited
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef MBED_MPU_API_H
#define MBED_MPU_API_H
 
#include "device.h"
#include <stdbool.h>
#include "cmsis.h"
 
#include <mstd_cstddef>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if DEVICE_MPU
 
/**
 * \defgroup hal_mpu MPU hal
 *
 * The MPU hal provides a simple MPU API to enhance device security by preventing
 * execution from ram.
 *
 * # Defined behavior
 * * The function ::mbed_mpu_init is safe to call repeatedly - Verified by mpu_init_test
 * * The function ::mbed_mpu_free disables MPU protection - Verified by mpu_free_test
 * * Execution from RAM results in a fault when execute never is enabled.
 *      This RAM includes heap, stack, data and zero init - Verified by mpu_fault_test_data,
 *      mpu_fault_test_bss, mpu_fault_test_stack and mpu_fault_test_heap.
 * * Writing to ROM results in a fault when write never is enabled - Not verified
 *
 * # Undefined behavior
 * * Calling any function other than ::mbed_mpu_init before the initialization of the MPU.
 *
 * @see hal_mpu_tests
 *
 * @{
 */
 
/**
 * \defgroup hal_mpu_tests MPU hal tests
 * The MPU test validates proper implementation of the MPU hal.
 *
 * To run the MPU hal tests use the command:
 *
 *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-mpu*
 */
 
#if !defined(MBED_MPU_CUSTOM)
 
#ifdef MBED_CONF_TARGET_MPU_ROM_END
#define MBED_MPU_ROM_END             MBED_CONF_TARGET_MPU_ROM_END
#else
#define MBED_MPU_ROM_END             (0x10000000 - 1)
#endif
 
#ifdef MBED_CONF_TARGET_MPU_RAM_START
#define MBED_MPU_RAM_START             MBED_CONF_TARGET_MPU_RAM_START
#else
// Default to the end of ROM
#define MBED_MPU_RAM_START           (MBED_MPU_ROM_END + 1)
#endif
 
#if ((__ARM_ARCH_8M_BASE__ == 1U) || (__ARM_ARCH_8M_MAIN__ == 1U) || (__ARM_ARCH_8_1M_MAIN__ == 1U))
/// On ARMv8 cores, MPU regions must use one of 8 global "attribute registers", which give the attributes
/// for one or more memory regions. This enum gives the attribute registers (i.e. the first arg to
/// \c ARM_MPU_SetMemAttr() ) that are defined by Mbed.
/// The application is free to use attribute registers above this number.
enum mbed_mpu_attr_index {
    /// Normal memory, write-through (i.e. writes are always sent immediately to main memory)
    MBED_MPU_ATTR_INDEX_NORMAL_WRITE_THROUGH = 0,
 
    /// Normal memory, write-back (i.e. writes may only write to the cache immediately, and get synced to main memory later)
    MBED_MPU_ATTR_INDEX_NORMAL_WRITE_BACK = 1,
 
    /// Non-cacheable: Reads and writes hit main memory directly.
    /// Note that this is still normal memory, not device, so the CPU can still reorder accesses.
    MBED_MPU_ATTR_INDEX_NON_CACHEABLE = 2,
};
#endif
 
/// Number of MPU regions that will be used by Mbed OS's MPU configuration.
/// The application is generally free to use regions above this number.
static MSTD_CONSTEXPR_OBJ_11 size_t mbed_used_mpu_regions =
#if ((__ARM_ARCH_8M_BASE__ == 1U) || (__ARM_ARCH_8M_MAIN__ == 1U) || (__ARM_ARCH_8_1M_MAIN__ == 1U))
    4
#else
    3
#if MBED_MPU_RAM_START < 0x20000000
    + 1
#endif
#endif
#if __DCACHE_PRESENT
    + 1
#endif
#if MBED_MPU_HAS_RAM_FUNCTION_REGION
    + 1
#endif
    ;
#endif
 
/**
 * Initialize the MPU
 *
 * Initialize or re-initialize the memory protection unit.
 * After initialization or re-initialization, ROM and RAM protection
 * are both enabled.
 */
void mbed_mpu_init(void);
 
/**
 * Enable or disable ROM MPU protection
 *
 * This function is used to mark all of ROM as read and execute only.
 * When enabled writes to ROM cause a fault.
 *
 * By default writes to ROM are disabled.
 *
 * @param disable true to disable writes to ROM, false otherwise
 */
void mbed_mpu_enable_rom_wn(bool disable);
 
/**
 * Enable or disable ram MPU protection
 *
 * This function is used to mark all of RAM as execute never.
 * When enabled code is only allowed to execute from flash.
 *
 * By default execution from RAM is disabled.
 *
 * @param disable true to disable execution from RAM, false otherwise
 */
void mbed_mpu_enable_ram_xn(bool disable);
 
/** Deinitialize the MPU
 *
 * Powerdown the MPU in preparation for powerdown, reset or jumping to another application.
 */
void mbed_mpu_free(void);
 
/**@}*/
 
#else
 
#define mbed_mpu_init()
 
#define mbed_mpu_enable_rom_wn(enable) (void)enable
 
#define mbed_mpu_enable_ram_xn(enable) (void)enable
 
#define mbed_mpu_free()
 
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif
 
/** @}*/