1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 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
214 @CustomHeader
215 module MemProtect
216 {
217 }