1    /*
     2     * Copyright (c) 2017-2020, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     */
    32    /*
    33     *  ======== MemProtect.xdc ========
    34     */
    35    package ti.sysbios.hal;
    36    
    37    /*!
    38     *  ======== MemProtect ========
    39     *  Memory protection manager.
    40     *
    41     *  SYS/BIOS Memory Protection Extensions (MPE) add memory protection capability
    42     *  to the SYS/BIOS kernel. With this extension enabled
    43     *  (see {@link ti.sysbios.BIOS#mpeEnabled BIOS.mpeEnabled}), an application can
    44     *  restrict the memory and peripherals a Task can access, thereby creating a
    45     *  sandbox. The access restricted tasks run in unprivileged mode and are
    46     *  therefore also restricted in terms of the type of CPU instructions they can
    47     *  execute. For example, an access restricted or unprivileged task cannot
    48     *  disable interrupts directly.
    49     *
    50     *  SYS/BIOS MPE can be used to enhance the security of applications by
    51     *  compartmentalizing the application into mutually isolated tasks. In the
    52     *  simplest configuration, the security critical portions of the application
    53     *  can be moved to privileged tasks and the rest of the application can be run
    54     *  as unprivileged tasks. In a more advanced configuration, multiple mutually
    55     *  isolated tasks may be used to compartmentalize the application at a finer
    56     *  level of granularity.
    57     *
    58     *  SYS/BIOS MPE introduces the notion of execution domains. A Domain is a
    59     *  protected environment for the kernel and tasks to execute within and has
    60     *  an Access Control List (ACL) that is defined at the time of creating the
    61     *  domain. The kernel and privileged tasks execute in a special domain that
    62     *  allows them to access the entire address space. User Task domains are more
    63     *  restrictive and allow a user task to only access memory regions explicitly
    64     *  owned by the domain or memory regions that are public and accessible to all
    65     *  domains.
    66     *
    67     *  A domain can be created in main() or a privileged task only. A User Task is
    68     *  assigned to an existing domain at the time of its creation. A User Task may
    69     *  create more threads which inherit its domain. A User Task cannot assign any
    70     *  other domain to the tasks it creates.
    71     *
    72     *  This module contains APIs used to create and/or construct domains at
    73     *  runtime.
    74     *
    75     *  @p(html)
    76     *  <h3> Calling Context </h3>
    77     *  <table border="1" cellpadding="3">
    78     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    79     *    </colgroup>
    80     *
    81     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    82     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    83     *    <!--                                                         -->
    84     *    <tr><td> MemProtect_constructDomain </td><td>   N   </td><td>   N   </td>
    85     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> MemProtect_destructDomain </td><td>   N    </td><td>   N   </td>
    87     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td colspan="6"> Definitions: <br />
    89     *       <ul>
    90     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    91     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    92     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    93     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    94     *           <ul>
    95     *             <li> In your module startup after this module is started
    96     *    (e.g. Hwi_Module_startupDone() returns TRUE). </li>
    97     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    98     *             <li> During main().</li>
    99     *             <li> During BIOS.startupFxns.</li>
   100     *           </ul>
   101     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   102     *           <ul>
   103     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   104     *           </ul>
   105     *       </ul>
   106     *    </td></tr>
   107     *
   108     *  </table>
   109     *  @p
   110     *
   111     *  @a(C Synopsis)
   112     *  @p(code)
   113     *  #include <ti/sysbios/hal/MemProtect.h>
   114     *  @p
   115     *
   116     *  @p(html)
   117     *  <h3> Macros </h3>
   118     *  @p
   119     *  @p(code)
   120     *  // Access Privilege Flags
   121     *  #define MemProtect_USER_READ
   122     *  #define MemProtect_USER_WRITE
   123     *  #define MemProtect_USER_EXEC
   124     *
   125     *  #define MemProtect_PRIV_READ
   126     *  #define MemProtect_PRIV_WRITE
   127     *  #define MemProtect_PRIV_EXEC
   128     *
   129     *  // Memory Type Flags
   130     *  #define MemProtect_DEVICE
   131     *  #define MemProtect_DEVICE_UNBUFFERED
   132     *  #define MemProtect_NONCACHEABLE
   133     *  #define MemProtect_WRITEBACK
   134     *  #define MemProtect_WRITETHROUGH
   135     *  #define MemProtect_WRITEALLOCATE
   136     *  #define MemProtect_SHAREABLE
   137     *
   138     *  // ACL Helper Macros
   139     *  #define MemProtect_NUM_KERNEL_ACL_ENTRIES
   140     *  #define MemProtect_NUM_USER_ACL_ENTRIES
   141     *  #define MemProtect_NUM_ACL_ENTRIES
   142     *  @p
   143     *
   144     *  @p(html)
   145     *  <h3> Typedefs </h3>
   146     *  @p
   147     *  @p(code)
   148     *  typedef struct MemProtect_Acl {
   149     *      Ptr    baseAddress;
   150     *      SizeT  length;
   151     *      UInt32 flags;
   152     *  } MemProtect_Acl;
   153     *
   154     *  typedef MemProtect_Struct *MemProtect_Handle;
   155     *  @p
   156     *
   157     *  @p(html)
   158     *  <h3> Functions </h3>
   159     *  @p
   160     *  @p(code)
   161     *  Int MemProtect_constructDomain(MemProtect_Struct *obj, struct MemProtect_Acl *acl, UInt16 aclLength)
   162     * 
   163     *  Int MemProtect_destructDomain(MemProtect_Struct *obj)
   164     *  @p
   165     *
   166     *  @a(MemProtect Functions)
   167     *
   168     *  @p(html)
   169     *  <h3> MemProtect_constructDomain() </h3>
   170     *  @p
   171     *  Construct an execution domain with given access control permissions
   172     *  @p(code)
   173     *  Int MemProtect_constructDomain(MemProtect_Struct *obj, struct MemProtect_Acl *acl, UInt16 aclLength)
   174     *  @p
   175     *  @p(html)
   176     *  <h4> ARGUMENTS </h4>
   177     *  @p(code)
   178     *  obj - Pointer to a statically created MemProtect object of type MemProtect_Struct
   179     *  acl - Pointer to an array of ACL entries. ACL entries are of type MemProtect_Acl
   180     *  aclLength - Length of ACL entry array
   181     *  @p(html)
   182     *  <h4> RETURNS </h4>
   183     *  @p
   184     *  Returns 0 on success. A negative return value indicates an error occurred.
   185     *  @p(html)
   186     *  <h4> DETAILS </h4>
   187     *  @p
   188     *  This function constructs an execution domain with the access permissions
   189     *  specified by the Access Control List (ACL) passed to it.
   190     *
   191     *  @p(html)
   192     *  <br/>
   193     *  <h3> MemProtect_destructDomain() </h3>
   194     *  @p
   195     *  Destruct execution domain
   196     *  @p(code)
   197     *  Int MemProtect_destructDomain(MemProtect_Struct *obj)
   198     *  @p
   199     *  @p(html)
   200     *  <h4> ARGUMENTS </h4>
   201     *  @p(code)
   202     *  obj - Pointer to a statically created MemProtect object of type MemProtect_Struct
   203     *  @p(html)
   204     *  <h4> RETURNS </h4>
   205     *  @p
   206     *  Returns 0 on success. A negative return value indicates an error occurred.
   207     *  @p(html)
   208     *  <h4> DETAILS </h4>
   209     *  @p
   210     *  This function destructs a previously constructed execution domain.
   211     */
   212    
   213    /* REQ_TAG(SYSBIOS-1019) */
   214    @CustomHeader
   215    module MemProtect
   216    {
   217    }