module ti.sysbios.family.arm.MPU

Memory Protection Unit (MPU) Manager

This module manages the Memory Protect Unit (MPU) present in many ARM Cortex-R and Cortex-M devices. It enables the application to partition the memory into different regions and set protection attributes for each region. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/MPU.xdc
#include <ti/sysbios/family/arm/MPU.h>
Functions
Void 
Void 
Void 
Bool 
Void 
MPU_setRegion// Sets the MPU region attributes(UInt8 regionId, Ptr regionBaseAddr, MPU_RegionSize regionSize, MPU_RegionAttrs *attrs);
Functions common to all target modules
Typedefs
typedef struct
typedef struct
typedef enum
Constants
extern const Assert_Id 
extern const Assert_Id 
extern const Assert_Id 
extern const MPU_RegionAttrs 
extern const Bool 
extern const Bool 
Variables
MPU_deviceRegs// ; // linked as extern ti_sysbios_family_arm_MPU_deviceRegs
 
DETAILS
This module manages the Memory Protect Unit (MPU) present in many ARM Cortex-R and Cortex-M devices. It enables the application to partition the memory into different regions and set protection attributes for each region.
The number of memory regions supported is device specific and may vary on different devices. The Cortex-R4F based RM48L5XX devices for instance support 16 memory regions.
Programming a memory region requires specifying the base address and size of the region, and the region's protection attributes. It is also possible to overlap different memory regions with higher region numbers enjoying higher priority than lower region numbers i.e. region 15 has a higher priority than region 14, and if both were overlapping, the overlapped memory region's attributes would be defined by region 15's entry.
The protection attributes for each region include attributes such as memory type (strongly-ordered, device or normal), shareability, cacheability and read-write access permission.
MEMORY REGION ATTRIBUTES
Memory regions can be configured as different memory types by setting the bufferable, cacheable and tex (type extension) fields of the RegionAttrs structure which is passed as an argument to MPU_setRegion() function. The three memory types supported by the hardware are "Normal" (cacheable), "Device" and "Strongly-ordered" memory. "Device" and "Strongly-ordered" memory types are recommended for mapping peripheral address space like memory-mapped registers. These two types ensure that the memory accesses to the peripheral memory are not performed speculatively, are not repeated and are performed in order. The "Normal" memory type is recommended for mapping memory regions storing application code and data.
Here are some common settings for the bufferable, cacheable and tex fields to define different memory region types:
  ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  + Memory Type                             | bufferable | cacheable | tex +
  ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  + Shareable Strongly-ordered memory       |    false   |   false   |  0  +
  +-----------------------------------------+------------+-----------+-----+
  + Shareable Device memory                 |    true    |   false   |  0  +
  +-----------------------------------------+------------+-----------+-----+
  + Outer & Inner Non-cacheable             |    false   |   false   |  1  +
  +-----------------------------------------+------------+-----------+-----+
  + Outer & Inner Write-back Write-allocate |    true    |   true    |  1  +
  + cacheable                               |            |           |     +
  ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
For an exhaustive list of all different memory type settings and a detailed explanation of the memory region attributes, please read the 'Protected Memory System Architecture (PMSA)' chapter of the ARM v7AR Architecture Reference Manual.
CHANGING SHAREABILITY ATTRIBUTES OF A CACHEABLE MEMORY REGION
If changing the shareability attribute of a cacheable memory region, it is possible for coherency problems to arise. In order to avoid possible coherency errors, the below sequence should be followed to change the shareability attributes of the memory region: - Make the memory region Non-cacheable and outer-shareable - Clean and invalidate the memory region from the cache - Change the shareability attribute to the desired value
EXAMPLES
Example showing how to set attributes for a given memory region using *.cfg script:
  var MPU = xdc.useModule('ti.sysbios.family.arm.MPU');

  // Mark memory region as normal outer and inner write-back
  // and write-through cacheable
  var attrs = new MPU.RegionAttrs();
  MPU.initRegionAttrsMeta(attrs);
  attrs.enable = true;
  attrs.bufferable = true;
  attrs.cacheable = true;
  attrs.shareable = false;
  attrs.noExecute = false;
  attrs.accPerm = 6;  // Read-only at PL1 and PL0
  attrs.tex = 1;

  // Set attributes for memory region of size 4MB starting at address 0x0
  // using MPU region Id 0 to store the attributes.
  MPU.setRegionMeta(0, 0x00000000, MPU.RegionSize_4M, attrs);

Calling Context

Function Hwi Swi Task Main Startup
disable Y Y Y Y Y
enable Y Y Y Y Y
initRegionAttrs Y Y Y Y Y
isEnabled Y Y Y Y Y
setRegion Y Y Y Y Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup.
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup.
 
enum MPU_RegionSize
C synopsis target-domain
typedef enum MPU_RegionSize {
    MPU_RegionSize_32,
    MPU_RegionSize_64,
    MPU_RegionSize_128,
    MPU_RegionSize_256,
    MPU_RegionSize_512,
    MPU_RegionSize_1K,
    MPU_RegionSize_2K,
    MPU_RegionSize_4K,
    MPU_RegionSize_8K,
    MPU_RegionSize_16K,
    MPU_RegionSize_32K,
    MPU_RegionSize_64K,
    MPU_RegionSize_128K,
    MPU_RegionSize_256K,
    MPU_RegionSize_512K,
    MPU_RegionSize_1M,
    MPU_RegionSize_2M,
    MPU_RegionSize_4M,
    MPU_RegionSize_8M,
    MPU_RegionSize_16M,
    MPU_RegionSize_32M,
    MPU_RegionSize_64M,
    MPU_RegionSize_128M,
    MPU_RegionSize_256M,
    MPU_RegionSize_512M,
    MPU_RegionSize_1G,
    MPU_RegionSize_2G,
    MPU_RegionSize_4G
} MPU_RegionSize;
 
 
struct MPU_DeviceRegs

Memory Protection Unit (MPU) registers. Symbol "MPU_deviceRegs" is a physical device

C synopsis target-domain
typedef struct MPU_DeviceRegs {
    UInt32 TYPE;
    // 0xD90 Type Register
    UInt32 CTRL;
    // 0xD94 Control Register
    UInt32 RNR;
    // 0xD98 Region Register
    UInt32 RBAR;
    // 0xD9C Region Base Address Register
    UInt32 RASR;
    // 0xDA0 Region Attribute and Size Register
    UInt32 RBAR_A1;
    // 0xDA4 MPU Alias 1
    UInt32 RASR_A1;
    // 0xDA8 MPU Alias 1
    UInt32 RBAR_A2;
    // 0xDAC MPU Alias 2
    UInt32 RASR_A2;
    // 0xDB0 MPU Alias 2
    UInt32 RBAR_A3;
    // 0xDB4 MPU Alias 3
    UInt32 RASR_A3;
    // 0xDB8 MPU Alias 3
} MPU_DeviceRegs;
 
 
struct MPU_RegionAttrs

Structure for setting the region attributes

C synopsis target-domain
typedef struct MPU_RegionAttrs {
    Bool enable;
    // is MPU region enabled
    Bool bufferable;
    // is memory region bufferable (B)
    Bool cacheable;
    // is memory region cacheable (C)
    Bool shareable;
    // is memory region shareable (S)
    Bool noExecute;
    // is memory region not executable (XN)
    UInt8 accPerm;
    // access permission bits value 0-7 (AP[2:0])
    UInt8 tex;
    // memory region attr type extension field (TEX[2:0])
    UInt8 subregionDisableMask;
    // disable mask for all 8 subregions
} MPU_RegionAttrs;
 
DETAILS
The B (Bufferable), C (Cacheable), TEX (Type extension), S (Shareable), XN (No execute or Execute never) and AP (Access permission) bits in the memory region entry define the memory region attributes.
See the 'Memory region attributes' section in the 'Protected Memory System Architecture (PMSA)' of the ARM v7-AR Architecture Reference Manual for more details.
 
config MPU_A_invalidRegionId  // module-wide

Assert raised when an invalid region number is passed to MPU_setRegion()

C synopsis target-domain
extern const Assert_Id MPU_A_invalidRegionId;
 
 
config MPU_A_nullPointer  // module-wide

Assert raised when a pointer is null

C synopsis target-domain
extern const Assert_Id MPU_A_nullPointer;
 
 
config MPU_A_unalignedBaseAddr  // module-wide

Assert raised when region's base address is not aligned to the region's size

C synopsis target-domain
extern const Assert_Id MPU_A_unalignedBaseAddr;
 
 
config MPU_defaultAttrs  // module-wide

Default region attributes structure

C synopsis target-domain
extern const MPU_RegionAttrs MPU_defaultAttrs;
 
DETAILS
The default attributes structure marks the memory region as outer and inner non-cacheable and non-shareable, with read-write access in privileged mode (PL1) only.
 
config MPU_enableBackgroundRegion  // module-wide

Configuration parameter to enable background region

C synopsis target-domain
extern const Bool MPU_enableBackgroundRegion;
 
DETAILS
If the MPU is enabled and background region is also enabled, any privileged access that does not map to any MPU memory region is handled using the default memory map.
 
config MPU_enableMPU  // module-wide

Configuration parameter to enable MPU. Disabled by default

C synopsis target-domain
extern const Bool MPU_enableMPU;
 
 
extern MPU_deviceRegs
C synopsis target-domain
MPU_DeviceRegs MPU_deviceRegs; // linked as extern ti_sysbios_family_arm_MPU_deviceRegs
 
 
MPU_disable()  // module-wide

Disables the MPU

C synopsis target-domain
Void MPU_disable();
 
DETAILS
If the MPU is already disabled, then simply return. Otherwise this function does the following:
  • If the L1 data cache is enabled, write back invalidate all of L1 data cache.
  • If the L1 program cache is enabled, invalidate all of L1 program cache.
NOTE
This function does not change the cache L1 data/program settings.
 
MPU_enable()  // module-wide

Enables the MPU

C synopsis target-domain
Void MPU_enable();
 
DETAILS
If the MPU is already enabled, then simply return. Otherwise this function does the following:
  • If the L1 program cache is enabled, invalidate all of L1 program cache.
This function enables the MPU on the core it is called from.
NOTE
This function does not change the L1 data/program cache settings.
 
MPU_initRegionAttrs()  // module-wide

Initializes the region attribute structure

C synopsis target-domain
Void MPU_initRegionAttrs(MPU_RegionAttrs *regionAttrs);
 
ARGUMENTS
attrs — Pointer to region attribute struct
 
MPU_isEnabled()  // module-wide

Determines if the MPU is enabled

C synopsis target-domain
Bool MPU_isEnabled();
 
 
MPU_setRegion()  // module-wide

Sets the MPU region attributes

C synopsis target-domain
Void MPU_setRegion(UInt8 regionId, Ptr regionBaseAddr, MPU_RegionSize regionSize, MPU_RegionAttrs *attrs);
 
ARGUMENTS
regionId — MPU region number
regionBaseAddr — MPU region base address
regionSize — MPU region size
attrs — Protection attributes
SEE
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId MPU_Module_id();
// Get this module's unique id
 
Bool MPU_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle MPU_Module_heap();
// The heap from which this module allocates memory
 
Bool MPU_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 MPU_Module_getMask();
// Returns the diagnostics mask for this module
 
Void MPU_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/sysbios/family/arm/MPU.xdc
var MPU = xdc.useModule('ti.sysbios.family.arm.MPU');
module-wide constants & types
    values of type MPU.RegionSize// 
        const MPU.RegionSize_32;
        const MPU.RegionSize_64;
        const MPU.RegionSize_128;
        const MPU.RegionSize_256;
        const MPU.RegionSize_512;
        const MPU.RegionSize_1K;
        const MPU.RegionSize_2K;
        const MPU.RegionSize_4K;
        const MPU.RegionSize_8K;
        const MPU.RegionSize_16K;
        const MPU.RegionSize_32K;
        const MPU.RegionSize_64K;
        const MPU.RegionSize_128K;
        const MPU.RegionSize_256K;
        const MPU.RegionSize_512K;
        const MPU.RegionSize_1M;
        const MPU.RegionSize_2M;
        const MPU.RegionSize_4M;
        const MPU.RegionSize_8M;
        const MPU.RegionSize_16M;
        const MPU.RegionSize_32M;
        const MPU.RegionSize_64M;
        const MPU.RegionSize_128M;
        const MPU.RegionSize_256M;
        const MPU.RegionSize_512M;
        const MPU.RegionSize_1G;
        const MPU.RegionSize_2G;
        const MPU.RegionSize_4G;
 
        obj.TYPE// 0xD90 Type Register = UInt32  ...
        obj.CTRL// 0xD94 Control Register = UInt32  ...
        obj.RNR// 0xD98 Region Register = UInt32  ...
        obj.RBAR// 0xD9C Region Base Address Register = UInt32  ...
        obj.RASR// 0xDA0 Region Attribute and Size Register = UInt32  ...
        obj.RBAR_A1// 0xDA4 MPU Alias 1 = UInt32  ...
        obj.RASR_A1// 0xDA8 MPU Alias 1 = UInt32  ...
        obj.RBAR_A2// 0xDAC MPU Alias 2 = UInt32  ...
        obj.RASR_A2// 0xDB0 MPU Alias 2 = UInt32  ...
        obj.RBAR_A3// 0xDB4 MPU Alias 3 = UInt32  ...
        obj.RASR_A3// 0xDB8 MPU Alias 3 = UInt32  ...
 
        obj.enable// is MPU region enabled = Bool  ...
        obj.bufferable// is memory region bufferable (B) = Bool  ...
        obj.cacheable// is memory region cacheable (C) = Bool  ...
        obj.shareable// is memory region shareable (S) = Bool  ...
        obj.noExecute// is memory region not executable (XN) = Bool  ...
        obj.accPerm// access permission bits value 0-7 (AP[2:0]) = UInt8  ...
module-wide config parameters
        msg: "A_invalidRegionId: MPU Region number passed is invalid."
    };
        msg: "A_nullPointer: Pointer is null"
    };
        msg: "A_unalignedBaseAddr: MPU region base address not aligned to size."
    };
        enable: true,
        bufferable: false,
        cacheable: false,
        shareable: false,
        noExecute: false,
        accPerm: 1,
        tex: 1,
        subregionDisableMask: 0
    };
 
module-wide functions
    MPU.setRegionMeta// Statically sets the MPU region attributes(UInt8 regionId, Ptr regionBaseAddr, MPU.RegionSize regionSize, MPU.RegionAttrs attrs) returns Void
 
 
enum MPU.RegionSize
Configuration settings
values of type MPU.RegionSize
    const MPU.RegionSize_32;
    const MPU.RegionSize_64;
    const MPU.RegionSize_128;
    const MPU.RegionSize_256;
    const MPU.RegionSize_512;
    const MPU.RegionSize_1K;
    const MPU.RegionSize_2K;
    const MPU.RegionSize_4K;
    const MPU.RegionSize_8K;
    const MPU.RegionSize_16K;
    const MPU.RegionSize_32K;
    const MPU.RegionSize_64K;
    const MPU.RegionSize_128K;
    const MPU.RegionSize_256K;
    const MPU.RegionSize_512K;
    const MPU.RegionSize_1M;
    const MPU.RegionSize_2M;
    const MPU.RegionSize_4M;
    const MPU.RegionSize_8M;
    const MPU.RegionSize_16M;
    const MPU.RegionSize_32M;
    const MPU.RegionSize_64M;
    const MPU.RegionSize_128M;
    const MPU.RegionSize_256M;
    const MPU.RegionSize_512M;
    const MPU.RegionSize_1G;
    const MPU.RegionSize_2G;
    const MPU.RegionSize_4G;
 
C SYNOPSIS
 
struct MPU.DeviceRegs

Memory Protection Unit (MPU) registers. Symbol "MPU_deviceRegs" is a physical device

Configuration settings
var obj = new MPU.DeviceRegs;
 
    obj.TYPE = UInt32  ...
    // 0xD90 Type Register
    obj.CTRL = UInt32  ...
    // 0xD94 Control Register
    obj.RNR = UInt32  ...
    // 0xD98 Region Register
    obj.RBAR = UInt32  ...
    // 0xD9C Region Base Address Register
    obj.RASR = UInt32  ...
    // 0xDA0 Region Attribute and Size Register
    obj.RBAR_A1 = UInt32  ...
    // 0xDA4 MPU Alias 1
    obj.RASR_A1 = UInt32  ...
    // 0xDA8 MPU Alias 1
    obj.RBAR_A2 = UInt32  ...
    // 0xDAC MPU Alias 2
    obj.RASR_A2 = UInt32  ...
    // 0xDB0 MPU Alias 2
    obj.RBAR_A3 = UInt32  ...
    // 0xDB4 MPU Alias 3
    obj.RASR_A3 = UInt32  ...
    // 0xDB8 MPU Alias 3
 
C SYNOPSIS
 
struct MPU.RegionAttrs

Structure for setting the region attributes

Configuration settings
var obj = new MPU.RegionAttrs;
 
    obj.enable = Bool  ...
    // is MPU region enabled
    obj.bufferable = Bool  ...
    // is memory region bufferable (B)
    obj.cacheable = Bool  ...
    // is memory region cacheable (C)
    obj.shareable = Bool  ...
    // is memory region shareable (S)
    obj.noExecute = Bool  ...
    // is memory region not executable (XN)
    obj.accPerm = UInt8  ...
    // access permission bits value 0-7 (AP[2:0])
    obj.tex = UInt8  ...
    // memory region attr type extension field (TEX[2:0])
    obj.subregionDisableMask = UInt8  ...
    // disable mask for all 8 subregions
 
DETAILS
The B (Bufferable), C (Cacheable), TEX (Type extension), S (Shareable), XN (No execute or Execute never) and AP (Access permission) bits in the memory region entry define the memory region attributes.
See the 'Memory region attributes' section in the 'Protected Memory System Architecture (PMSA)' of the ARM v7-AR Architecture Reference Manual for more details.
C SYNOPSIS
 
config MPU.A_invalidRegionId  // module-wide

Assert raised when an invalid region number is passed to MPU_setRegion()

Configuration settings
MPU.A_invalidRegionId = Assert.Desc {
    msg: "A_invalidRegionId: MPU Region number passed is invalid."
};
 
C SYNOPSIS
 
config MPU.A_nullPointer  // module-wide

Assert raised when a pointer is null

Configuration settings
MPU.A_nullPointer = Assert.Desc {
    msg: "A_nullPointer: Pointer is null"
};
 
C SYNOPSIS
 
config MPU.A_unalignedBaseAddr  // module-wide

Assert raised when region's base address is not aligned to the region's size

Configuration settings
MPU.A_unalignedBaseAddr = Assert.Desc {
    msg: "A_unalignedBaseAddr: MPU region base address not aligned to size."
};
 
C SYNOPSIS
 
config MPU.defaultAttrs  // module-wide

Default region attributes structure

Configuration settings
MPU.defaultAttrs = MPU.RegionAttrs {
    enable: true,
    bufferable: false,
    cacheable: false,
    shareable: false,
    noExecute: false,
    accPerm: 1,
    tex: 1,
    subregionDisableMask: 0
};
 
DETAILS
The default attributes structure marks the memory region as outer and inner non-cacheable and non-shareable, with read-write access in privileged mode (PL1) only.
C SYNOPSIS
 
config MPU.enableBackgroundRegion  // module-wide

Configuration parameter to enable background region

Configuration settings
MPU.enableBackgroundRegion = Bool true;
 
DETAILS
If the MPU is enabled and background region is also enabled, any privileged access that does not map to any MPU memory region is handled using the default memory map.
C SYNOPSIS
 
config MPU.enableMPU  // module-wide

Configuration parameter to enable MPU. Disabled by default

Configuration settings
MPU.enableMPU = Bool false;
 
C SYNOPSIS
 
metaonly config MPU.common$  // module-wide

Common module configuration parameters

Configuration settings
MPU.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
 
metaonly config MPU.rovViewInfo  // module-wide
Configuration settings
MPU.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly MPU.initRegionAttrsMeta()  // module-wide

Initializes the region attribute structure

Configuration settings
MPU.initRegionAttrsMeta(MPU.RegionAttrs* regionAttrs) returns Void
 
ARGUMENTS
attrs — Pointer to region attribute struct
 
metaonly MPU.setRegionMeta()  // module-wide

Statically sets the MPU region attributes

Configuration settings
MPU.setRegionMeta(UInt8 regionId, Ptr regionBaseAddr, MPU.RegionSize regionSize, MPU.RegionAttrs attrs) returns Void
 
ARGUMENTS
regionId — MPU region number
regionBaseAddr — MPU region base address
regionSize — MPU region size
attrs — Protection attributes
SEE
generated on Tue, 09 Oct 2018 20:57:49 GMT