1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 import xdc.runtime.Error;
18
19 /*!
20 * ======== IThreadSupport ========
21 * Interface for OS specific back-end.
22 *
23 * The {@link xdc.runtime.knl} package contains modules that provide typical
24 * OS services. These xdc.runtime.knl modules require proxies to be
25 * bound to an OS specific delegate. This specifies the interface to
26 * be implemented by the OS specific delegate for
27 * {@link xdc.runtime.knl.Thread} module.
28 *
29 * Refer to {@link xdc.runtime.knl.Thread} for more details on the APIs.
30 */
31 interface IThreadSupport
32 {
33 /*! Thread priorities which are mapped to OS specific value by Proxy */
34 enum Priority {
35 Priority_INVALID,
36 Priority_LOWEST,
37 Priority_BELOW_NORMAL,
38 Priority_NORMAL,
39 Priority_ABOVE_NORMAL,
40 Priority_HIGHEST
41 };
42
43 /*! Invalid OS priority value */
44 const Int INVALID_OS_PRIORITY = 0;
45
46 /*!
47 * The error status for {@link #getPriority} when an error is captured in
48 * the Error.Block.
49 */
50 const Int GETPRI_FAILED = -2;
51
52 /*! Status returned by {@link #compareOsPriorities} when an error occurs */
53 enum CompStatus {
54 CompStatus_ERROR = -2,
55 CompStatus_LOWER = -1,
56 CompStatus_EQUAL = 0,
57 CompStatus_HIGHER = 1
58 };
59
60 /*! typedef for function that gets called when the Thread runs. */
61 typedef Void (*RunFxn)(IArg);
62
63 /*! Struct to hold thread statistics from {@link #stat} */
64 struct Stat {
65 SizeT stackSize;
66 SizeT stackUsed;
67 }
68
69 /*!
70 * ======== self ========
71 * Acquire the currently executing thread's handle.
72 *
73 * Refer to {@link xdc.runtime.knl.Thread#self} for more details.
74 *
75 * @param(eb) Pointer to Error.Block
76 * @a(returns) Handle in case of success; null for error;
77 */
78 Handle self(Error.Block* eb);
79
80 /*!
81 * ======== start ========
82 * Start threads running.
83 *
84 * Refer to {@link xdc.runtime.knl.Thread#start} for more details.
85 *
86 * @param(eb) Pointer to Error.Block
87 * @a(returns) true for success; false for failure
88 */
89 Bool start(Error.Block* eb);
90
91 /*!
92 * ======== yield ========
93 * Yield the currently scheduled thread.
94 *
95 * Refer to {@link xdc.runtime.knl.Thread#yield} for more details.
96 *
97 * @param(eb) Pointer to Error.Block
98 * @a(returns) true for success; false for failure
99 */
100 Bool yield(Error.Block* eb);
101
102 /*!
103 * ======== compareOsPriorities ========
104 * Compare two priority values and find out which one represents a
105 * higher priority.
106 *
107 * Refer to {@link xdc.runtime.knl.Thread#compareOsPriorities} for more
108 * details.
109 *
110 * @p(blist)
111 * -{@link #CompStatus_ERROR} if an error occured
112 * -{@link #CompStatus_LOWER} if p1 is lower than p2
113 * -{@link #CompStatus_EQUAL} if p1=p2
114 * -{@link #CompStatus_HIGHER} if p1 is higher than p2
115 * details.
116 * @p
117 *
118 * @param(p1) priority one
119 * @param(p2) priority two
120 * @param(eb) Pointer to Error.Block
121 * @a(returns) Refer to description above
122 */
123 Int compareOsPriorities(Int p1, Int p2, Error.Block *eb);
124
125 /*!
126 * ======== sleep ========
127 * Sleep for certain number of microseconds
128 *
129 * Refer to {@link xdc.runtime.knl.Thread#sleep} for more details.
130 *
131 * @param(timeout) timeout in microseconds
132 * @param(eb) Pointer to Error.Block
133 * @a(returns) true for success; false for failure
134 */
135 Bool sleep(UInt timeout, Error.Block *eb);
136
137 instance:
138
139 /*! Thread function argument. Default is NULL. */
140 config IArg arg = null;
141
142 /*!
143 * ======== priority ========
144 * Thread priority
145 *
146 * Thread defines several constants which allows applications to select
147 * a priority in an OS independent way. Priority_LOWEST,
148 * Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and
149 * Priority_HIGHEST. These values get mapped to OS specific priorities
150 * by the OS specific delegate.
151 */
152 config Priority priority = Priority_NORMAL;
153
154 /*!
155 * ======== osPriority ========
156 * OS specific thread priority
157 *
158 * Used to specify an OS specific value for priority. If set this value
159 * takes precedence over {@link #priority}.
160 */
161 config Int osPriority = INVALID_OS_PRIORITY;
162
163 /*! Thread stack size. If left at zero, OS default is used */
164 config SizeT stackSize = 0;
165
166 /*! User-specified thread local storage data. */
167 config Ptr tls = null;
168
169 /*!
170 * ======== create ========
171 * Create a Thread object.
172 *
173 * This function spawns a new thread calling the function fxn.
174 *
175 * @param(fxn) function for new thread to begin execution
176 */
177 create(RunFxn fxn);
178
179 /*!
180 * ======== join ========
181 * Join on a Thread.
182 *
183 * Refer to {@link xdc.runtime.knl.Thread#join} for more details.
184 *
185 * @param(eb) Pointer to Error.Block
186 * @a(returns) true for success; false for failure
187 */
188 Bool join(Error.Block* eb);
189
190 /*!
191 * ======== getPriority ========
192 * Obtain a thread's priority.
193 *
194 * Refer to {@link xdc.runtime.knl.Thread#getPriority} for more details.
195 *
196 * @param(eb) Pointer to Error.Block
197 * @a(returns) thread priority in case of success; Priority_INVALID in
198 * case of error;
199 */
200 Priority getPriority(Error.Block* eb);
201
202 /*!
203 * ======== setPriority ========
204 * Set a thread's priority.
205 *
206 * Refer to {@link xdc.runtime.knl.Thread#setPriority} for more details.
207 *
208 * @param(newPri) new thread priority
209 * @param(eb) Pointer to Error.Block
210 * @a(returns) true for success; false for failure
211 */
212 Bool setPriority(Priority newPri, Error.Block* eb);
213
214 /*!
215 * ======== getOsPriority ========
216 * Obtain a thread's os specific priority.
217 *
218 * For OSes that support dynamic priority boosting, the value returned
219 * is the base priority of the thread.
220 *
221 * Refer to {@link xdc.runtime.knl.Thread#getOsPriority} for more details.
222 *
223 * @param(eb) Pointer to Error.Block
224 * @a(returns) thread priority in case of success; GETPRI_FAILED in
225 * case of error;
226 */
227 Int getOsPriority(Error.Block *eb);
228
229 /*!
230 * ======== setOsPriority ========
231 * Set a thread's priority.
232 *
233 * This API sets the base priority of the thread on OSes that
234 * support dynamic priority boosting
235 *
236 * Refer to {@link xdc.runtime.knl.Thread#setOsPriority} for more details.
237 *
238 * @param(newPri) new thread priority
239 * @param(eb) Pointer to Error.Block
240 * @a(returns) true for success; false for failure
241 */
242 Bool setOsPriority(Int newPri, Error.Block *eb);
243
244 /*!
245 * ======== getOsHandle ========
246 * Get the OS thread handle
247 *
248 * @a(returns) null in case of error
249 */
250 Ptr getOsHandle();
251
252 /*!
253 * ======== getTls ========
254 * Obtain a thread's local storage pointer
255 *
256 * @a(returns) null in case of error
257 */
258 Ptr getTls();
259
260 /*!
261 * ======== setTls ========
262 * Set a thread's local storage pointer.
263 *
264 * @param(tls) thread tls
265 */
266 Void setTls(Ptr tls);
267
268
269 /*!
270 * ======== stat ========
271 * Obtain a thread's stats
272 *
273 * @param(buf) Pointer to Stat
274 * @param(eb) Pointer to Error.Block
275 * @a(returns) true for success; false for failure
276 */
277 Bool stat(Stat* buf, Error.Block* eb);
278
279 }
280 281 282
283