module ti.sysbios.hal.MemProtect
index URL

Memory protection manager

SYS/BIOS Memory Protection Extensions (MPE) add memory protection capability to the SYS/BIOS kernel. With this extension enabled (see BIOS.mpeEnabled), an application can restrict the memory and peripherals a Task can access, thereby creating a sandbox. The access restricted tasks run in unprivileged mode and are therefore also restricted in terms of the type of CPU instructions they can execute. For example, an access restricted or unprivileged task cannot disable interrupts directly. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/MemProtect.xdc
#include <ti/sysbios/hal/MemProtect.h>
Functions common to all target modules
MemProtect_Module_getMask// Returns the diagnostics mask for this module, MemProtect_Module_hasMask// Test whether this module has a diagnostics mask, MemProtect_Module_heap// The heap from which this module allocates memory, MemProtect_Module_id// Get this module's unique id, MemProtect_Module_setMask// Set the diagnostics mask for this module, MemProtect_Module_startupDone// Test if this module has completed startup
 
DETAILS
SYS/BIOS Memory Protection Extensions (MPE) add memory protection capability to the SYS/BIOS kernel. With this extension enabled (see BIOS.mpeEnabled), an application can restrict the memory and peripherals a Task can access, thereby creating a sandbox. The access restricted tasks run in unprivileged mode and are therefore also restricted in terms of the type of CPU instructions they can execute. For example, an access restricted or unprivileged task cannot disable interrupts directly.
SYS/BIOS MPE can be used to enhance the security of applications by compartmentalizing the application into mutually isolated tasks. In the simplest configuration, the security critical portions of the application can be moved to privileged tasks and the rest of the application can be run as unprivileged tasks. In a more advanced configuration, multiple mutually isolated tasks may be used to compartmentalize the application at a finer level of granularity.
SYS/BIOS MPE introduces the notion of execution domains. A Domain is a protected environment for the kernel and tasks to execute within and has an Access Control List (ACL) that is defined at the time of creating the domain. The kernel and privileged tasks execute in a special domain that allows them to access the entire address space. User Task domains are more restrictive and allow a user task to only access memory regions explicitly owned by the domain or memory regions that are public and accessible to all domains.
A domain can be created in main() or a privileged task only. A User Task is assigned to an existing domain at the time of its creation. A User Task may create more threads which inherit its domain. A User Task cannot assign any other domain to the tasks it creates.
This module contains APIs used to create and/or construct domains at runtime.

Calling Context

Function Hwi Swi Task Main Startup
MemProtect_constructDomain N N Y Y N
MemProtect_destructDomain N N Y Y N
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 after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
C SYNOPSIS
  #include <ti/sysbios/hal/MemProtect.h>

Macros 

  // Access Privilege Flags
  #define MemProtect_USER_READ
  #define MemProtect_USER_WRITE
  #define MemProtect_USER_EXEC

  #define MemProtect_PRIV_READ
  #define MemProtect_PRIV_WRITE
  #define MemProtect_PRIV_EXEC

  // Memory Type Flags
  #define MemProtect_DEVICE
  #define MemProtect_DEVICE_UNBUFFERED
  #define MemProtect_NONCACHEABLE
  #define MemProtect_WRITEBACK
  #define MemProtect_WRITETHROUGH
  #define MemProtect_WRITEALLOCATE
  #define MemProtect_SHAREABLE

  // ACL Helper Macros
  #define MemProtect_NUM_KERNEL_ACL_ENTRIES
  #define MemProtect_NUM_USER_ACL_ENTRIES
  #define MemProtect_NUM_ACL_ENTRIES

Typedefs 

  typedef struct MemProtect_Acl {
      Ptr    baseAddress;
      SizeT  length;
      UInt32 flags;
  } MemProtect_Acl;

  typedef MemProtect_Struct *MemProtect_Handle;

Functions 

  Int MemProtect_constructDomain(MemProtect_Struct *obj, struct MemProtect_Acl *acl, UInt16 aclLength)
 
  Void MemProtect_destructDomain(MemProtect_Struct *obj)
MEMPROTECT FUNCTIONS

MemProtect_constructDomain()

Construct an execution domain with given access control permissions
  Int MemProtect_constructDomain(MemProtect_Struct *obj, struct MemProtect_Acl *acl, UInt16 aclLength)

ARGUMENTS 

  obj - Pointer to a statically created MemProtect object of type MemProtect_Struct
  acl - Pointer to an array of ACL entries. ACL entries are of type MemProtect_Acl
  aclLength - Length of ACL entry array

RETURNS

Returns 0 on success. A negative return value indicates an error occurred.

DETAILS

This function constructs an execution domain with the access permissions specified by the Access Control List (ACL) passed to it.

MemProtect_destructDomain()

Destruct execution domain
  Int MemProtect_destructDomain(MemProtect_Struct *obj)

ARGUMENTS 

  obj - Pointer to a statically created MemProtect object of type MemProtect_Struct

RETURNS

Returns 0 on success. A negative return value indicates an error occurred.

DETAILS

This function destructs a previously constructed execution domain.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId MemProtect_Module_id();
// Get this module's unique id
 
Bool MemProtect_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle MemProtect_Module_heap();
// The heap from which this module allocates memory
 
Bool MemProtect_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 MemProtect_Module_getMask();
// Returns the diagnostics mask for this module
 
Void MemProtect_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/sysbios/hal/MemProtect.xdc
var MemProtect = xdc.useModule('ti.sysbios.hal.MemProtect');
module-wide config parameters
    MemProtect.common$// Common module configuration parameters = Types.Common$ undefined;
 
 
metaonly config MemProtect.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
MemProtect.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.
generated on Thu, 23 May 2019 00:22:17 GMT