OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-spinlocks.html] - Blame information for rev 174

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 
>Spinlocks</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="Event Flags"
26 
HREF="kernel-flags.html"><LINK
27 
REL="NEXT"
28 
TITLE="Scheduler Control"
29 
HREF="kernel-schedcontrol.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-flags.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-schedcontrol.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-SPINLOCKS">Spinlocks</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN1693"
87 
></A
88 
><H2
89 
>Name</H2
90 
>cyg_spinlock_create, cyg_spinlock_destroy, cyg_spinlock_spin, cyg_spinlock_clear, cyg_spinlock_test, cyg_spinlock_spin_intsave, cyg_spinlock_clear_intsave&nbsp;--&nbsp;Low-level Synchronization Primitive</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN1702"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN1703"><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 
>void cyg_spinlock_init</CODE
119 
>(cyg_spinlock_t* lock, cyg_bool_t locked);</CODE
120 
></P
121 
><P
122 
><CODE
123 
><CODE
124 
CLASS="FUNCDEF"
125 
>void cyg_spinlock_destroy</CODE
126 
>(cyg_spinlock_t* lock);</CODE
127 
></P
128 
><P
129 
><CODE
130 
><CODE
131 
CLASS="FUNCDEF"
132 
>void cyg_spinlock_spin</CODE
133 
>(cyg_spinlock_t* lock);</CODE
134 
></P
135 
><P
136 
><CODE
137 
><CODE
138 
CLASS="FUNCDEF"
139 
>void cyg_spinlock_clear</CODE
140 
>(cyg_spinlock_t* lock);</CODE
141 
></P
142 
><P
143 
><CODE
144 
><CODE
145 
CLASS="FUNCDEF"
146 
>cyg_bool_t cyg_spinlock_try</CODE
147 
>(cyg_spinlock_t* lock);</CODE
148 
></P
149 
><P
150 
><CODE
151 
><CODE
152 
CLASS="FUNCDEF"
153 
>cyg_bool_t cyg_spinlock_test</CODE
154 
>(cyg_spinlock_t* lock);</CODE
155 
></P
156 
><P
157 
><CODE
158 
><CODE
159 
CLASS="FUNCDEF"
160 
>void cyg_spinlock_spin_intsave</CODE
161 
>(cyg_spinlock_t* lock, cyg_addrword_t* istate);</CODE
162 
></P
163 
><P
164 
><CODE
165 
><CODE
166 
CLASS="FUNCDEF"
167 
>void cyg_spinlock_clear_intsave</CODE
168 
>(cyg_spinlock_t* lock, cyg_addrword_t istate);</CODE
169 
></P
170 
><P
171 
></P
172 
></DIV
173 
></DIV
174 
><DIV
175 
CLASS="REFSECT1"
176 
><A
177 
NAME="KERNEL-SPINLOCKS-DESCRIPTION"
178 
></A
179 
><H2
180 
>Description</H2
181 
><P
182 
>Spinlocks provide an additional synchronization primitive for
183 
applications running on SMP systems. They operate at a lower level
184 
than the other primitives such as mutexes, and for most purposes the
185 
higher-level primitives should be preferred. However there are some
186 
circumstances where a spinlock is appropriate, especially when
187 
interrupt handlers and threads need to share access to hardware, and
188 
on SMP systems the kernel implementation itself depends on spinlocks.
189 
      </P
190 
><P
191 
>Essentially a spinlock is just a simple flag. When code tries to claim
192 
a spinlock it checks whether or not the flag is already set. If not
193 
then the flag is set and the operation succeeds immediately. The exact
194 
implementation of this is hardware-specific, for example it may use a
195 
test-and-set instruction to guarantee the desired behaviour even if
196 
several processors try to access the spinlock at the exact same time.
197 
If it is not possible to claim a spinlock then the current thead spins
198 
in a tight loop, repeatedly checking the flag until it is clear. This
199 
behaviour is very different from other synchronization primitives such
200 
as mutexes, where contention would cause a thread to be suspended. The
201 
assumption is that a spinlock will only be held for a very short time.
202 
If claiming a spinlock could cause the current thread to be suspended
203 
then spinlocks could not be used inside interrupt handlers, which is
204 
not acceptable.
205 
      </P
206 
><P
207 
>This does impose a constraint on any code which uses spinlocks.
208 
Specifically it is important that spinlocks are held only for a short
209 
period of time, typically just some dozens of instructions. Otherwise
210 
another processor could be blocked on the spinlock for a long time,
211 
unable to do any useful work. It is also important that a thread which
212 
owns a spinlock does not get preempted because that might cause
213 
another processor to spin for a whole timeslice period, or longer. One
214 
way of achieving this is to disable interrupts on the current
215 
processor, and the function
216 
<TT
217 
CLASS="FUNCTION"
218 
>cyg_spinlock_spin_intsave</TT
219 
> is provided to
220 
facilitate this.
221 
      </P
222 
><P
223 
>Spinlocks should not be used on single-processor systems. Consider a
224 
high priority thread which attempts to claim a spinlock already held
225 
by a lower priority thread: it will just loop forever and the lower
226 
priority thread will never get another chance to run and release the
227 
spinlock. Even if the two threads were running at the same priority,
228 
the one attempting to claim the spinlock would spin until it was
229 
timesliced and a lot of cpu time would be wasted. If an interrupt
230 
handler tried to claim a spinlock owned by a thread, the interrupt
231 
handler would loop forever. Therefore spinlocks are only appropriate
232 
for SMP systems where the current owner of a spinlock can continue
233 
running on a different processor.
234 
      </P
235 
><P
236 
>Before a spinlock can be used it must be initialized by a call to
237 
<TT
238 
CLASS="FUNCTION"
239 
>cyg_spinlock_init</TT
240 
>. This takes two arguments, a
241 
pointer to a <TT
242 
CLASS="FUNCTION"
243 
>cyg_spinlock_t</TT
244 
> data structure, and
245 
a flag to specify whether the spinlock starts off locked or unlocked.
246 
If a spinlock is no longer required then it can be destroyed by a call
247 
to <TT
248 
CLASS="FUNCTION"
249 
>cyg_spinlock_destroy</TT
250 
>.
251 
      </P
252 
><P
253 
>There are two routines for claiming a spinlock:
254 
<TT
255 
CLASS="FUNCTION"
256 
>cyg_spinlock_spin</TT
257 
> and
258 
<TT
259 
CLASS="FUNCTION"
260 
>cyg_spinlock_spin_intsave</TT
261 
>. The former can be used
262 
when it is known the current code will not be preempted, for example
263 
because it is running in an interrupt handler or because interrupts
264 
are disabled. The latter will disable interrupts in addition to
265 
claiming the spinlock, so is safe to use in all circumstances. The
266 
previous interrupt state is returned via the second argument, and
267 
should be used in a subsequent call to
268 
<TT
269 
CLASS="FUNCTION"
270 
>cyg_spinlock_clear_intsave</TT
271 
>.
272 
      </P
273 
><P
274 
>Similarly there are two routines for releasing a spinlock:
275 
<TT
276 
CLASS="FUNCTION"
277 
>cyg_spinlock_clear</TT
278 
> and
279 
<TT
280 
CLASS="FUNCTION"
281 
>cyg_spinlock_clear_intsave</TT
282 
>. Typically
283 
the former will be used if the spinlock was claimed by a call to
284 
<TT
285 
CLASS="FUNCTION"
286 
>cyg_spinlock_spin</TT
287 
>, and the latter when
288 
<TT
289 
CLASS="FUNCTION"
290 
>cyg_spinlock_intsave</TT
291 
> was used.
292 
      </P
293 
><P
294 
>There are two additional routines.
295 
<TT
296 
CLASS="FUNCTION"
297 
>cyg_spinlock_try</TT
298 
> is a non-blocking version of
299 
<TT
300 
CLASS="FUNCTION"
301 
>cyg_spinlock_spin</TT
302 
>: if possible the lock will be
303 
claimed and the function will return <TT
304 
CLASS="LITERAL"
305 
>true</TT
306 
>; otherwise the function
307 
will return immediately with failure.
308 
<TT
309 
CLASS="FUNCTION"
310 
>cyg_spinlock_test</TT
311 
> can be used to find out whether
312 
or not the spinlock is currently locked. This function must be used
313 
with care because, especially on a multiprocessor system, the state of
314 
the spinlock can change at any time.
315 
      </P
316 
><P
317 
>Spinlocks should only be held for a short period of time, and
318 
attempting to claim a spinlock will never cause a thread to be
319 
suspended. This means that there is no need to worry about priority
320 
inversion problems, and concepts such as priority ceilings and
321 
inheritance do not apply.
322 
      </P
323 
></DIV
324 
><DIV
325 
CLASS="REFSECT1"
326 
><A
327 
NAME="KERNEL-SPINLOCKS-CONTEXT"
328 
></A
329 
><H2
330 
>Valid contexts</H2
331 
><P
332 
>All of the spinlock functions can be called from any context,
333 
including ISR and DSR context. Typically
334 
<TT
335 
CLASS="FUNCTION"
336 
>cyg_spinlock_init</TT
337 
> is only called during system
338 
initialization.
339 
      </P
340 
></DIV
341 
><DIV
342 
CLASS="NAVFOOTER"
343 
><HR
344 
ALIGN="LEFT"
345 
WIDTH="100%"><TABLE
346 
SUMMARY="Footer navigation table"
347 
WIDTH="100%"
348 
BORDER="0"
349 
CELLPADDING="0"
350 
CELLSPACING="0"
351 
><TR
352 
><TD
353 
WIDTH="33%"
354 
ALIGN="left"
355 
VALIGN="top"
356 
><A
357 
HREF="kernel-flags.html"
358 
ACCESSKEY="P"
359 
>Prev</A
360 
></TD
361 
><TD
362 
WIDTH="34%"
363 
ALIGN="center"
364 
VALIGN="top"
365 
><A
366 
HREF="ecos-ref.html"
367 
ACCESSKEY="H"
368 
>Home</A
369 
></TD
370 
><TD
371 
WIDTH="33%"
372 
ALIGN="right"
373 
VALIGN="top"
374 
><A
375 
HREF="kernel-schedcontrol.html"
376 
ACCESSKEY="N"
377 
>Next</A
378 
></TD
379 
></TR
380 
><TR
381 
><TD
382 
WIDTH="33%"
383 
ALIGN="left"
384 
VALIGN="top"
385 
>Event Flags</TD
386 
><TD
387 
WIDTH="34%"
388 
ALIGN="center"
389 
VALIGN="top"
390 
><A
391 
HREF="kernel.html"
392 
ACCESSKEY="U"
393 
>Up</A
394 
></TD
395 
><TD
396 
WIDTH="33%"
397 
ALIGN="right"
398 
VALIGN="top"
399 
>Scheduler Control</TD
400 
></TR
401 
></TABLE
402 
></DIV
403 
></BODY
404 
></HTML
405 
>

powered by: WebSVN 2.1.0

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