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
36 package ti.sysbios.rts.gnu;
37
38 import xdc.rov.ViewInfo;
39
40 import xdc.runtime.Error;
41 import xdc.runtime.Assert;
42
43 import ti.sysbios.knl.Task;
44 import ti.sysbios.knl.Semaphore;
45
46 /*!
47 * ======== ReentSupport ========
48 * Newlib RTS library re-entrancy support module
49 *
50 * The Reentrancy Support module implements locking APIs for the Newlib
51 * libraries and provides an overloaded implementation of the library's
52 * __getreent() function to make the C runtime library calls re-entrant and
53 * thread safe.
54 *
55 * The C runtime library (newlib libc/libm) functions internally call
56 * __getreent() to get the address of the currently executing thread's
57 * reentrancy structure.
58 *
59 * The __getreent() function allocates storage for the reentrancy structure
60 * when it is called for the very first time within a thread context. Any
61 * subsequent calls to __getreent() within the same thread context read the
62 * current thread's stored context to determine the previously allocated
63 * reentrancy structure's address and return it.
64 *
65 * When a thread is deleted, the DeleteHook is called and will free any memory
66 * that was allocated to store the reentrancy structure associated with the
67 * thread.
68 *
69 * The C runtime library calls locking APIs to ensure thread safety. The
70 * locking APIs are defined in the sys/lock.h header in the version of Newlib
71 * distributed with SYS/BIOS. This module provides an implementation for these
72 * locking APIs.
73 *
74 * Reentrancy support is enabled by default if tasking is enabled
75 * and can be disabled by adding the following code to the application's
76 * config script.
77 *
78 * @p(code)
79 * var ReentSupport = xdc.useModule('ti.sysbios.rts.gnu.ReentSupport');
80 *
81 * // 'true' to enable Task level reentrancy support (default)
82 * // 'false' to disable Task level reentrancy support
83 * ReentSupport.enableReentSupport = false;
84 * @p
85 *
86 * Note: Calling C runtime functions from SWI and HWI threads
87 * is not supported and will generate an exception if
88 * reentrancy support is enabled.
89 *
90 */
91
92 @Template ("./ReentSupport.xdt")
93 @ModuleStartup
94
95 module ReentSupport
96 {
97 /*!
98 * ======== ModuleView ========
99 * @_nodoc
100 */
101 metaonly struct ModuleView {
102 Bool enableReentSupport;
103 }
104
105 /*!
106 * ======== rovViewInfo ========
107 * @_nodoc
108 */
109 @Facet
110 metaonly config ViewInfo.Instance rovViewInfo =
111 ViewInfo.create({
112 viewMap: [
113 [
114 'Module',
115 {
116 type: ViewInfo.MODULE,
117 viewInitFxn: 'viewInitModule',
118 structName: 'ModuleView'
119 }
120 ],
121 ]
122 });
123
124 /*!
125 * ======== enableReentSupport ========
126 * Enable re-entrancy support
127 */
128 config Bool enableReentSupport = true;
129
130
131
132 /*! Asserted in ReentSupport_getReent() */
133 config Assert.Id A_badThreadType = {
134 msg: "A_badThreadType: Cannot call a C runtime library API from a Hwi or Swi thread."
135 };
136
137 internal:
138
139
140
141 142 143 144 145 146 147
148 Ptr getReent();
149
150 151 152 153
154 Void initGlobalReent();
155
156 157 158 159 160 161 162 163 164
165 Void taskCreateHook(Task.Handle task, Error.Block *eb);
166
167 168 169 170 171 172 173
174 Void taskDeleteHook(Task.Handle task);
175
176 177 178 179 180 181 182
183 Void taskRegHook(Int id);
184
185
186
187 struct Module_State {
188 Int taskHId;
189 Semaphore.Handle lock;
190 };
191 }