OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-thread-data.html] - Blame information for rev 588

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
2 
<!-- This material may be distributed only subject to the terms      -->
3 
<!-- and conditions set forth in the Open Publication License, v1.0  -->
4 
<!-- or later (the latest version is presently available at          -->
5 
<!-- http://www.opencontent.org/openpub/).                           -->
6 
<!-- Distribution of the work or derivative of the work in any       -->
7 
<!-- standard (paper) book form is prohibited unless prior           -->
8 
<!-- permission is obtained from the copyright holder.               -->
9 
<HTML
10 
><HEAD
11 
><TITLE
12 
>Per-thread data</TITLE
13 
><meta name="MSSmartTagsPreventParsing" content="TRUE">
14 
<META
15 
NAME="GENERATOR"
16 
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
17 
"><LINK
18 
REL="HOME"
19 
TITLE="eCos Reference Manual"
20 
HREF="ecos-ref.html"><LINK
21 
REL="UP"
22 
TITLE="The eCos Kernel"
23 
HREF="kernel.html"><LINK
24 
REL="PREVIOUS"
25 
TITLE="Thread priorities"
26 
HREF="kernel-thread-priorities.html"><LINK
27 
REL="NEXT"
28 
TITLE="Thread destructors"
29 
HREF="kernel-thread-destructors.html"></HEAD
30 
><BODY
31 
CLASS="REFENTRY"
32 
BGCOLOR="#FFFFFF"
33 
TEXT="#000000"
34 
LINK="#0000FF"
35 
VLINK="#840084"
36 
ALINK="#0000FF"
37 
><DIV
38 
CLASS="NAVHEADER"
39 
><TABLE
40 
SUMMARY="Header navigation table"
41 
WIDTH="100%"
42 
BORDER="0"
43 
CELLPADDING="0"
44 
CELLSPACING="0"
45 
><TR
46 
><TH
47 
COLSPAN="3"
48 
ALIGN="center"
49 
>eCos Reference Manual</TH
50 
></TR
51 
><TR
52 
><TD
53 
WIDTH="10%"
54 
ALIGN="left"
55 
VALIGN="bottom"
56 
><A
57 
HREF="kernel-thread-priorities.html"
58 
ACCESSKEY="P"
59 
>Prev</A
60 
></TD
61 
><TD
62 
WIDTH="80%"
63 
ALIGN="center"
64 
VALIGN="bottom"
65 
></TD
66 
><TD
67 
WIDTH="10%"
68 
ALIGN="right"
69 
VALIGN="bottom"
70 
><A
71 
HREF="kernel-thread-destructors.html"
72 
ACCESSKEY="N"
73 
>Next</A
74 
></TD
75 
></TR
76 
></TABLE
77 
><HR
78 
ALIGN="LEFT"
79 
WIDTH="100%"></DIV
80 
><H1
81 
><A
82 
NAME="KERNEL-THREAD-DATA">Per-thread data</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN660"
87 
></A
88 
><H2
89 
>Name</H2
90 
>cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data&nbsp;--&nbsp;Manipulate per-thread data</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN667"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN668"><P
100 
></P
101 
><TABLE
102 
BORDER="5"
103 
BGCOLOR="#E0E0F0"
104 
WIDTH="70%"
105 
><TR
106 
><TD
107 
><PRE
108 
CLASS="FUNCSYNOPSISINFO"
109 
>#include &lt;cyg/kernel/kapi.h&gt;
110 
        </PRE
111 
></TD
112 
></TR
113 
></TABLE
114 
><P
115 
><CODE
116 
><CODE
117 
CLASS="FUNCDEF"
118 
>cyg_ucount32 cyg_thread_new_data_index</CODE
119 
>(void);</CODE
120 
></P
121 
><P
122 
><CODE
123 
><CODE
124 
CLASS="FUNCDEF"
125 
>void cyg_thread_free_data_index</CODE
126 
>(cyg_ucount32 index);</CODE
127 
></P
128 
><P
129 
><CODE
130 
><CODE
131 
CLASS="FUNCDEF"
132 
>cyg_addrword_t cyg_thread_get_data</CODE
133 
>(cyg_ucount32 index);</CODE
134 
></P
135 
><P
136 
><CODE
137 
><CODE
138 
CLASS="FUNCDEF"
139 
>cyg_addrword_t* cyg_thread_get_data_ptr</CODE
140 
>(cyg_ucount32 index);</CODE
141 
></P
142 
><P
143 
><CODE
144 
><CODE
145 
CLASS="FUNCDEF"
146 
>void cyg_thread_set_data</CODE
147 
>(cyg_ucount32 index, cyg_addrword_t data);</CODE
148 
></P
149 
><P
150 
></P
151 
></DIV
152 
></DIV
153 
><DIV
154 
CLASS="REFSECT1"
155 
><A
156 
NAME="AEN696"
157 
></A
158 
><H2
159 
>Description</H2
160 
><P
161 
>In some applications and libraries it is useful to have some data that
162 
is specific to each thread. For example, many of the functions in the
163 
POSIX compatibility package return -1 to indicate an error and store
164 
additional information in what appears to be a global variable
165 
<TT
166 
CLASS="VARNAME"
167 
>errno</TT
168 
>. However, if multiple threads make concurrent
169 
calls into the POSIX library and if <TT
170 
CLASS="VARNAME"
171 
>errno</TT
172 
> were
173 
really a global variable then a thread would have no way of knowing
174 
whether the current <TT
175 
CLASS="VARNAME"
176 
>errno</TT
177 
> value really corresponded
178 
to the last POSIX call it made, or whether some other thread had run
179 
in the meantime and made a different POSIX call which updated the
180 
variable. To avoid such confusion <TT
181 
CLASS="VARNAME"
182 
>errno</TT
183 
> is instead
184 
implemented as a per-thread variable, and each thread has its own
185 
instance.
186 
      </P
187 
><P
188 
>The support for per-thread data can be disabled via the configuration
189 
option <TT
190 
CLASS="VARNAME"
191 
>CYGVAR_KERNEL_THREADS_DATA</TT
192 
>. If enabled, each
193 
<SPAN
194 
CLASS="STRUCTNAME"
195 
>cyg_thread</SPAN
196 
> data structure holds a small array
197 
of words. The size of this array is determined by the configuration
198 
option <TT
199 
CLASS="VARNAME"
200 
>CYGNUM_KERNEL_THREADS_DATA_MAX</TT
201 
>. When a
202 
thread is created the array is filled with zeroes.
203 
      </P
204 
><P
205 
>If an application needs to use per-thread data then it needs an index
206 
into this array which has not yet been allocated to other code. This
207 
index can be obtained by calling
208 
<TT
209 
CLASS="FUNCTION"
210 
>cyg_thread_new_data_index</TT
211 
>, and then used in
212 
subsequent calls to <TT
213 
CLASS="FUNCTION"
214 
>cyg_thread_get_data</TT
215 
>.
216 
Typically indices are allocated during system initialization and
217 
stored in static variables. If for some reason a slot in the array is
218 
no longer required and can be re-used then it can be released by calling
219 
<TT
220 
CLASS="FUNCTION"
221 
>cyg_thread_free_data_index</TT
222 
>,
223 
      </P
224 
><P
225 
>The current per-thread data in a given slot can be obtained using
226 
<TT
227 
CLASS="FUNCTION"
228 
>cyg_thread_get_data</TT
229 
>. This implicitly operates on
230 
the current thread, and its single argument should be an index as
231 
returned by <TT
232 
CLASS="FUNCTION"
233 
>cyg_thread_new_data_index</TT
234 
>. The
235 
per-thread data can be updated using
236 
<TT
237 
CLASS="FUNCTION"
238 
>cyg_thread_set_data</TT
239 
>. If a particular item of
240 
per-thread data is needed repeatedly then
241 
<TT
242 
CLASS="FUNCTION"
243 
>cyg_thread_get_data_ptr</TT
244 
> can be used to obtain the
245 
address of the data, and indirecting through this pointer allows the
246 
data to be examined and updated efficiently.
247 
      </P
248 
><P
249 
>Some packages, for example the error and POSIX packages, have
250 
pre-allocated slots in the array of per-thread data. These slots
251 
should not normally be used by application code, and instead slots
252 
should be allocated during initialization by a call to
253 
<TT
254 
CLASS="FUNCTION"
255 
>cyg_thread_new_data_index</TT
256 
>. If it is known that,
257 
for example, the configuration will never include the POSIX
258 
compatibility package then application code may instead decide to
259 
re-use the slot allocated to that package,
260 
<TT
261 
CLASS="VARNAME"
262 
>CYGNUM_KERNEL_THREADS_DATA_POSIX</TT
263 
>, but obviously
264 
this does involve a risk of strange and subtle bugs if the
265 
application's requirements ever change.
266 
      </P
267 
></DIV
268 
><DIV
269 
CLASS="REFSECT1"
270 
><A
271 
NAME="KERNEL-THREAD-DATA-CONTEXT"
272 
></A
273 
><H2
274 
>Valid contexts</H2
275 
><P
276 
>Typically <TT
277 
CLASS="FUNCTION"
278 
>cyg_thread_new_data_index</TT
279 
> is only
280 
called during initialization, but may also be called at any time in
281 
thread context. <TT
282 
CLASS="FUNCTION"
283 
>cyg_thread_free_data_index</TT
284 
>, if
285 
used at all, can also be called during initialization or from thread
286 
context. <TT
287 
CLASS="FUNCTION"
288 
>cyg_thread_get_data</TT
289 
>,
290 
<TT
291 
CLASS="FUNCTION"
292 
>cyg_thread_get_data_ptr</TT
293 
>, and
294 
<TT
295 
CLASS="FUNCTION"
296 
>cyg_thread_set_data</TT
297 
> may only be called from
298 
thread context because they implicitly operate on the current thread.
299 
      </P
300 
></DIV
301 
><DIV
302 
CLASS="NAVFOOTER"
303 
><HR
304 
ALIGN="LEFT"
305 
WIDTH="100%"><TABLE
306 
SUMMARY="Footer navigation table"
307 
WIDTH="100%"
308 
BORDER="0"
309 
CELLPADDING="0"
310 
CELLSPACING="0"
311 
><TR
312 
><TD
313 
WIDTH="33%"
314 
ALIGN="left"
315 
VALIGN="top"
316 
><A
317 
HREF="kernel-thread-priorities.html"
318 
ACCESSKEY="P"
319 
>Prev</A
320 
></TD
321 
><TD
322 
WIDTH="34%"
323 
ALIGN="center"
324 
VALIGN="top"
325 
><A
326 
HREF="ecos-ref.html"
327 
ACCESSKEY="H"
328 
>Home</A
329 
></TD
330 
><TD
331 
WIDTH="33%"
332 
ALIGN="right"
333 
VALIGN="top"
334 
><A
335 
HREF="kernel-thread-destructors.html"
336 
ACCESSKEY="N"
337 
>Next</A
338 
></TD
339 
></TR
340 
><TR
341 
><TD
342 
WIDTH="33%"
343 
ALIGN="left"
344 
VALIGN="top"
345 
>Thread priorities</TD
346 
><TD
347 
WIDTH="34%"
348 
ALIGN="center"
349 
VALIGN="top"
350 
><A
351 
HREF="kernel.html"
352 
ACCESSKEY="U"
353 
>Up</A
354 
></TD
355 
><TD
356 
WIDTH="33%"
357 
ALIGN="right"
358 
VALIGN="top"
359 
>Thread destructors</TD
360 
></TR
361 
></TABLE
362 
></DIV
363 
></BODY
364 
></HTML
365 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.