module ti.sysbios.family.arm.v8m.SAU

Security Attribution Unit (SAU) Manager

This module manages the Security Attribution Unit (SAU) present in ARMv8 Cortex-V8M devices. It enables the application to partition the memory into different regions and set security attributes for each region. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/v8m/SAU.xdc
#include <ti/sysbios/family/arm/v8m/SAU.h>
Functions
Void 
SAU_configureRegion// Configure a SAU region(UInt8 regionId, Ptr regionBase, SizeT regionSize, SAU_RegionType regionTupe);
Void 
Void 
Void 
Void 
Bool 
Functions common to all target modules
Typedefs
typedef struct
typedef enum
Constants
extern const Bool 
extern const Assert_Id 
extern const Assert_Id 
extern const Assert_Id 
extern const Assert_Id 
extern const Bool 
 
DETAILS
This module manages the Security Attribution Unit (SAU) present in ARMv8 Cortex-V8M devices. It enables the application to partition the memory into different regions and set security attributes for each region.
The number of memory regions supported is device specific and may vary on different devices.
EXAMPLES
Example showing how to set attributes for a given memory region using *.cfg script:
  var SAU = xdc.useModule('ti.sysbios.family.arm.v8m.SAU');
  SAU.enableSAU = true;

  // define NSC region
  SAU.configureRegionMeta(0, 0x2C410000, 0x00010000, SAU.RegionType_NSC);
  // define NS code/data region
  SAU.configureRegionMeta(1, 0x2C420000, 0x00020000, SAU.RegionType_NS);
  // allow NS access to SCB
  SAU.configureRegionMeta(2, 0xE0000000, 0x10000000, SAU.RegionType_NS);

Calling Context

Function Hwi Swi Task Main Startup
configureRegion Y Y Y Y Y
disable Y Y Y Y Y
disableRegion Y Y Y Y Y
enable Y Y Y Y Y
enableRegion Y Y Y Y Y
isEnabled 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 SAU_RegionType
C synopsis target-domain
typedef enum SAU_RegionType {
    SAU_RegionType_NS,
    // Region is Non-Secure
    SAU_RegionType_NSC
    // Region is Secure, Non-Secure Callable
} SAU_RegionType;
 
 
struct SAU_DeviceRegs

Security Attribution Unit (SAU) registers. Symbol "SAU_deviceRegs" is the physical device

C synopsis target-domain
typedef struct SAU_DeviceRegs {
    UInt32 CTRL;
    // 0xE000EDD0 Control Register
    UInt32 TYPE;
    // 0xE000EDD4 Type Register
    UInt32 RNR;
    // 0xE000EDD8 Region Number Register
    UInt32 RBAR;
    // 0xE000EDDC Region Base Address Register
    UInt32 RLAR;
    // 0xE000EDE0 Region Base Limit Register
    UInt32 SFSR;
    // 0xE000EDE4 Secure Fault Status Register
    UInt32 SFAR;
    // 0xE000EDE8 Secure Fault Address Register
} SAU_DeviceRegs;
 
 
config SAU_A_invalidRegionId  // module-wide

Assert raised when an invalid region number is passed to SAU_configureRegion(), SAU_enableRegion(), SAU_disableRegion()

C synopsis target-domain
extern const Assert_Id SAU_A_invalidRegionId;
 
 
config SAU_A_nullPointer  // module-wide

Assert raised when a pointer is null

C synopsis target-domain
extern const Assert_Id SAU_A_nullPointer;
 
 
config SAU_A_unalignedBaseAddr  // module-wide

Assert raised when region's base address is not aligned

C synopsis target-domain
extern const Assert_Id SAU_A_unalignedBaseAddr;
 
 
config SAU_A_unalignedEndAddr  // module-wide

Assert raised when region's end address is not aligned

C synopsis target-domain
extern const Assert_Id SAU_A_unalignedEndAddr;
 
 
config SAU_allSecureWhenSauDisabled  // module-wide

Configuration parameter to set all memory type when SAU is disabled

C synopsis target-domain
extern const Bool SAU_allSecureWhenSauDisabled;
 
DETAILS
If the SAU is disabled, this parameter determines if all of memory is configured as Secure or Non Secure.
Default is all memory is marked as Secure if the SAU is disabled.
 
config SAU_enableSAU  // module-wide

Configuration parameter to enable SAU. Disabled by default

C synopsis target-domain
extern const Bool SAU_enableSAU;
 
 
SAU_configureRegion()  // module-wide

Configure a SAU region

C synopsis target-domain
Void SAU_configureRegion(UInt8 regionId, Ptr regionBase, SizeT regionSize, SAU_RegionType regionTupe);
 
ARGUMENTS
regionId — SAU region number
regionBase — SAU region base address
regionSize — SAU region size in bytes
regionType — RegionType (NS/NSC)
DETAILS
By default, the region is enabled. Call disableRegion(regionId) to disable the region.
SEE
 
SAU_disable()  // module-wide

Disables the SAU

C synopsis target-domain
Void SAU_disable();
 
DETAILS
If the SAU is already disabled, then simply return.
 
SAU_disableRegion()  // module-wide

Disable a SAU region

C synopsis target-domain
Void SAU_disableRegion(UInt8 regionId);
 
ARGUMENTS
regionId — SAU region number
 
SAU_enable()  // module-wide

Enables the SAU

C synopsis target-domain
Void SAU_enable();
 
DETAILS
If the SAU is already enabled, then simply return.
 
SAU_enableRegion()  // module-wide

Enable a SAU region

C synopsis target-domain
Void SAU_enableRegion(UInt8 regionId);
 
ARGUMENTS
regionId — SAU region number
 
SAU_isEnabled()  // module-wide

Determines if the SAU is enabled

C synopsis target-domain
Bool SAU_isEnabled();
 
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId SAU_Module_id();
// Get this module's unique id
 
Bool SAU_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle SAU_Module_heap();
// The heap from which this module allocates memory
 
Bool SAU_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 SAU_Module_getMask();
// Returns the diagnostics mask for this module
 
Void SAU_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/sysbios/family/arm/v8m/SAU.xdc
var SAU = xdc.useModule('ti.sysbios.family.arm.v8m.SAU');
module-wide constants & types
    values of type SAU.RegionType// 
 
        obj.CTRL// 0xE000EDD0 Control Register = UInt32  ...
        obj.TYPE// 0xE000EDD4 Type Register = UInt32  ...
        obj.RNR// 0xE000EDD8 Region Number Register = UInt32  ...
        obj.RBAR// 0xE000EDDC Region Base Address Register = UInt32  ...
        obj.RLAR// 0xE000EDE0 Region Base Limit Register = UInt32  ...
        obj.SFSR// 0xE000EDE4 Secure Fault Status Register = UInt32  ...
        obj.SFAR// 0xE000EDE8 Secure Fault Address Register = UInt32  ...
module-wide config parameters
        msg: "A_invalidRegionId: SAU Region number passed is invalid."
    };
        msg: "A_nullPointer: Pointer is null"
    };
        msg: "A_unalignedBaseAddr: SAU region base address not aligned."
    };
        msg: "A_unalignedEndAddr: SAU region end address not aligned."
    };
 
module-wide functions
    SAU.configureRegionMeta// Statically sets the SAU region attributes(UInt8 regionId, Ptr regionBase, SizeT regionSize, SAU.RegionType regionType) returns Void
    SAU.disableRegionMeta// disable a SAU region(UInt8 regionId) returns Void
 
 
enum SAU.RegionType
Configuration settings
values of type SAU.RegionType
    const SAU.RegionType_NS;
    // Region is Non-Secure
    const SAU.RegionType_NSC;
    // Region is Secure, Non-Secure Callable
 
C SYNOPSIS
 
struct SAU.DeviceRegs

Security Attribution Unit (SAU) registers. Symbol "SAU_deviceRegs" is the physical device

Configuration settings
var obj = new SAU.DeviceRegs;
 
    obj.CTRL = UInt32  ...
    // 0xE000EDD0 Control Register
    obj.TYPE = UInt32  ...
    // 0xE000EDD4 Type Register
    obj.RNR = UInt32  ...
    // 0xE000EDD8 Region Number Register
    obj.RBAR = UInt32  ...
    // 0xE000EDDC Region Base Address Register
    obj.RLAR = UInt32  ...
    // 0xE000EDE0 Region Base Limit Register
    obj.SFSR = UInt32  ...
    // 0xE000EDE4 Secure Fault Status Register
    obj.SFAR = UInt32  ...
    // 0xE000EDE8 Secure Fault Address Register
 
C SYNOPSIS
 
config SAU.A_invalidRegionId  // module-wide

Assert raised when an invalid region number is passed to SAU_configureRegion(), SAU_enableRegion(), SAU_disableRegion()

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

Assert raised when a pointer is null

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

Assert raised when region's base address is not aligned

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

Assert raised when region's end address is not aligned

Configuration settings
SAU.A_unalignedEndAddr = Assert.Desc {
    msg: "A_unalignedEndAddr: SAU region end address not aligned."
};
 
C SYNOPSIS
 
config SAU.allSecureWhenSauDisabled  // module-wide

Configuration parameter to set all memory type when SAU is disabled

Configuration settings
SAU.allSecureWhenSauDisabled = Bool true;
 
DETAILS
If the SAU is disabled, this parameter determines if all of memory is configured as Secure or Non Secure.
Default is all memory is marked as Secure if the SAU is disabled.
C SYNOPSIS
 
config SAU.enableSAU  // module-wide

Configuration parameter to enable SAU. Disabled by default

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

Common module configuration parameters

Configuration settings
SAU.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 SAU.rovViewInfo  // module-wide
Configuration settings
SAU.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly SAU.configureRegionMeta()  // module-wide

Statically sets the SAU region attributes

Configuration settings
SAU.configureRegionMeta(UInt8 regionId, Ptr regionBase, SizeT regionSize, SAU.RegionType regionType) returns Void
 
ARGUMENTS
regionId — SAU region number
regionBase — SAU region base address
regionSize — SAU region size in bytes
regionType — RegionType
DETAILS
By default, the region is enabled. Call disableRegionMeta(regionId) to disable the region.
SEE
 
metaonly SAU.disableRegionMeta()  // module-wide

disable a SAU region

Configuration settings
SAU.disableRegionMeta(UInt8 regionId) returns Void
 
ARGUMENTS
regionId — SAU region number
generated on Sat, 19 Sep 2020 02:06:42 GMT