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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-mail-boxes.html] - Blame information for rev 581

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 
>Mail boxes</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="Semaphores"
26 
HREF="kernel-semaphores.html"><LINK
27 
REL="NEXT"
28 
TITLE="Event Flags"
29 
HREF="kernel-flags.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-semaphores.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-flags.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-MAIL-BOXES">Mail boxes</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN1425"
87 
></A
88 
><H2
89 
>Name</H2
90 
>cyg_mbox_create, cyg_mbox_delete, cyg_mbox_get, cyg_mbox_timed_get, cyg_mbox_tryget, cyg_mbox_peek_item, cyg_mbox_put, cyg_mbox_timed_put, cyg_mbox_tryput, cyg_mbox_peek, cyg_mbox_waiting_to_get, cyg_mbox_waiting_to_put&nbsp;--&nbsp;Synchronization primitive</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN1439"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN1440"><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_mbox_create</CODE
119 
>(cyg_handle_t* handle, cyg_mbox* mbox);</CODE
120 
></P
121 
><P
122 
><CODE
123 
><CODE
124 
CLASS="FUNCDEF"
125 
>void cyg_mbox_delete</CODE
126 
>(cyg_handle_t mbox);</CODE
127 
></P
128 
><P
129 
><CODE
130 
><CODE
131 
CLASS="FUNCDEF"
132 
>void* cyg_mbox_get</CODE
133 
>(cyg_handle_t mbox);</CODE
134 
></P
135 
><P
136 
><CODE
137 
><CODE
138 
CLASS="FUNCDEF"
139 
>void* cyg_mbox_timed_get</CODE
140 
>(cyg_handle_t mbox, cyg_tick_count_t abstime);</CODE
141 
></P
142 
><P
143 
><CODE
144 
><CODE
145 
CLASS="FUNCDEF"
146 
>void* cyg_mbox_tryget</CODE
147 
>(cyg_handle_t mbox);</CODE
148 
></P
149 
><P
150 
><CODE
151 
><CODE
152 
CLASS="FUNCDEF"
153 
>cyg_count32 cyg_mbox_peek</CODE
154 
>(cyg_handle_t mbox);</CODE
155 
></P
156 
><P
157 
><CODE
158 
><CODE
159 
CLASS="FUNCDEF"
160 
>void* cyg_mbox_peek_item</CODE
161 
>(cyg_handle_t mbox);</CODE
162 
></P
163 
><P
164 
><CODE
165 
><CODE
166 
CLASS="FUNCDEF"
167 
>cyg_bool_t cyg_mbox_put</CODE
168 
>(cyg_handle_t mbox, void* item);</CODE
169 
></P
170 
><P
171 
><CODE
172 
><CODE
173 
CLASS="FUNCDEF"
174 
>cyg_bool_t cyg_mbox_timed_put</CODE
175 
>(cyg_handle_t mbox, void* item, cyg_tick_count_t abstime);</CODE
176 
></P
177 
><P
178 
><CODE
179 
><CODE
180 
CLASS="FUNCDEF"
181 
>cyg_bool_t cyg_mbox_tryput</CODE
182 
>(cyg_handle_t mbox, void* item);</CODE
183 
></P
184 
><P
185 
><CODE
186 
><CODE
187 
CLASS="FUNCDEF"
188 
>cyg_bool_t cyg_mbox_waiting_to_get</CODE
189 
>(cyg_handle_t mbox);</CODE
190 
></P
191 
><P
192 
><CODE
193 
><CODE
194 
CLASS="FUNCDEF"
195 
>cyg_bool_t cyg_mbox_waiting_to_put</CODE
196 
>(cyg_handle_t mbox);</CODE
197 
></P
198 
><P
199 
></P
200 
></DIV
201 
></DIV
202 
><DIV
203 
CLASS="REFSECT1"
204 
><A
205 
NAME="KERNEL-MAIL-BOXES-DESCRIPTION"
206 
></A
207 
><H2
208 
>Description</H2
209 
><P
210 
>Mail boxes are a synchronization primitive. Like semaphores they
211 
can be used by a consumer thread to wait until a certain event has
212 
occurred, but the producer also has the ability to transmit some data
213 
along with each event. This data, the message, is normally a pointer
214 
to some data structure. It is stored in the mail box itself, so the
215 
producer thread that generates the event and provides the data usually
216 
does not have to block until some consumer thread is ready to receive
217 
the event. However a mail box will only have a finite capacity,
218 
typically ten slots. Even if the system is balanced and events are
219 
typically consumed at least as fast as they are generated, a burst of
220 
events can cause the mail box to fill up and the generating thread
221 
will block until space is available again. This behaviour is very
222 
different from semaphores, where it is only necessary to maintain a
223 
counter and hence an overflow is unlikely.
224 
      </P
225 
><P
226 
>Before a mail box can be used it must be created with a call to
227 
<TT
228 
CLASS="FUNCTION"
229 
>cyg_mbox_create</TT
230 
>. Each mail box has a unique
231 
handle which will be returned via the first argument and which should
232 
be used for subsequent operations.
233 
<TT
234 
CLASS="FUNCTION"
235 
>cyg_mbox_create</TT
236 
> also requires an area of memory
237 
for the kernel structure, which is provided by the
238 
<SPAN
239 
CLASS="STRUCTNAME"
240 
>cyg_mbox</SPAN
241 
> second argument. If a mail box is
242 
no longer required then <TT
243 
CLASS="FUNCTION"
244 
>cyg_mbox_delete</TT
245 
> can be
246 
used. This will simply discard any messages that remain posted.
247 
      </P
248 
><P
249 
>The main function for waiting on a mail box is
250 
<TT
251 
CLASS="FUNCTION"
252 
>cyg_mbox_get</TT
253 
>. If there is a pending message
254 
because of a call to <TT
255 
CLASS="FUNCTION"
256 
>cyg_mbox_put</TT
257 
> then
258 
<TT
259 
CLASS="FUNCTION"
260 
>cyg_mbox_get</TT
261 
> will return immediately with the
262 
message that was put into the mail box. Otherwise this function
263 
will block until there is a put operation. Exceptionally the thread
264 
can instead be unblocked by a call to
265 
<TT
266 
CLASS="FUNCTION"
267 
>cyg_thread_release</TT
268 
>, in which case
269 
<TT
270 
CLASS="FUNCTION"
271 
>cyg_mbox_get</TT
272 
> will return a null pointer. It is
273 
assumed that there will never be a call to
274 
<TT
275 
CLASS="FUNCTION"
276 
>cyg_mbox_put</TT
277 
> with a null pointer, because it
278 
would not be possible to distinguish between that and a release
279 
operation. Messages are always retrieved in the order in which they
280 
were put into the mail box, and there is no support for messages
281 
with different priorities.
282 
      </P
283 
><P
284 
>There are two variants of <TT
285 
CLASS="FUNCTION"
286 
>cyg_mbox_get</TT
287 
>. The
288 
first, <TT
289 
CLASS="FUNCTION"
290 
>cyg_mbox_timed_get</TT
291 
> will wait until either
292 
a message is available or until a number of clock ticks have occurred.
293 
If no message is posted within the timeout then a null pointer will be
294 
returned. <TT
295 
CLASS="FUNCTION"
296 
>cyg_mbox_tryget</TT
297 
> is a non-blocking
298 
operation which will either return a message if one is available or a
299 
null pointer.
300 
      </P
301 
><P
302 
>New messages are placed in the mail box by calling
303 
<TT
304 
CLASS="FUNCTION"
305 
>cyg_mbox_put</TT
306 
> or one of its variants. The main put
307 
function takes two arguments, a handle to the mail box and a
308 
pointer for the message itself. If there is a spare slot in the
309 
mail box then the new message can be placed there immediately, and
310 
if there is a waiting thread it will be woken up so that it can
311 
receive the message. If the mail box is currently full then
312 
<TT
313 
CLASS="FUNCTION"
314 
>cyg_mbox_put</TT
315 
> will block until there has been a
316 
get operation and a slot is available. The
317 
<TT
318 
CLASS="FUNCTION"
319 
>cyg_mbox_timed_put</TT
320 
> variant imposes a time limit
321 
on the put operation, returning false if the operation cannot be
322 
completed within the specified number of clock ticks. The
323 
<TT
324 
CLASS="FUNCTION"
325 
>cyg_mbox_tryput</TT
326 
> variant is non-blocking,
327 
returning false if there are no free slots available and the message
328 
cannot be posted without blocking.
329 
      </P
330 
><P
331 
>There are a further four functions available for examining the current
332 
state of a mailbox. The results of these functions must be used with
333 
care because usually the state can change at any time as a result of
334 
activity within other threads, but they may prove occasionally useful
335 
during debugging or in special situations.
336 
<TT
337 
CLASS="FUNCTION"
338 
>cyg_mbox_peek</TT
339 
> returns a count of the number of
340 
messages currently stored in the mail box.
341 
<TT
342 
CLASS="FUNCTION"
343 
>cyg_mbox_peek_item</TT
344 
> retrieves the first message,
345 
but it remains in the mail box until a get operation is performed.
346 
<TT
347 
CLASS="FUNCTION"
348 
>cyg_mbox_waiting_to_get</TT
349 
> and
350 
<TT
351 
CLASS="FUNCTION"
352 
>cyg_mbox_waiting_to_put</TT
353 
> indicate whether or not
354 
there are currently threads blocked in a get or a put operation on a
355 
given mail box.
356 
      </P
357 
><P
358 
>The number of slots in each mail box is controlled by a
359 
configuration option
360 
<TT
361 
CLASS="VARNAME"
362 
>CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</TT
363 
>, with a default
364 
value of 10. All mail boxes are the same size.
365 
      </P
366 
></DIV
367 
><DIV
368 
CLASS="REFSECT1"
369 
><A
370 
NAME="KERNEL-MAIL-BOXES-CONTEXT"
371 
></A
372 
><H2
373 
>Valid contexts</H2
374 
><P
375 
><TT
376 
CLASS="FUNCTION"
377 
>cyg_mbox_create</TT
378 
> is typically called during
379 
system initialization but may also be called in thread context.
380 
The remaining functions are normally called only during thread
381 
context. Of special note is <TT
382 
CLASS="FUNCTION"
383 
>cyg_mbox_put</TT
384 
> which
385 
can be a blocking operation when the mail box is full, and which
386 
therefore must never be called from DSR context. It is permitted to
387 
call <TT
388 
CLASS="FUNCTION"
389 
>cyg_mbox_tryput</TT
390 
>,
391 
<TT
392 
CLASS="FUNCTION"
393 
>cyg_mbox_tryget</TT
394 
>, and the information functions
395 
from DSR context but this is rarely useful.
396 
      </P
397 
></DIV
398 
><DIV
399 
CLASS="NAVFOOTER"
400 
><HR
401 
ALIGN="LEFT"
402 
WIDTH="100%"><TABLE
403 
SUMMARY="Footer navigation table"
404 
WIDTH="100%"
405 
BORDER="0"
406 
CELLPADDING="0"
407 
CELLSPACING="0"
408 
><TR
409 
><TD
410 
WIDTH="33%"
411 
ALIGN="left"
412 
VALIGN="top"
413 
><A
414 
HREF="kernel-semaphores.html"
415 
ACCESSKEY="P"
416 
>Prev</A
417 
></TD
418 
><TD
419 
WIDTH="34%"
420 
ALIGN="center"
421 
VALIGN="top"
422 
><A
423 
HREF="ecos-ref.html"
424 
ACCESSKEY="H"
425 
>Home</A
426 
></TD
427 
><TD
428 
WIDTH="33%"
429 
ALIGN="right"
430 
VALIGN="top"
431 
><A
432 
HREF="kernel-flags.html"
433 
ACCESSKEY="N"
434 
>Next</A
435 
></TD
436 
></TR
437 
><TR
438 
><TD
439 
WIDTH="33%"
440 
ALIGN="left"
441 
VALIGN="top"
442 
>Semaphores</TD
443 
><TD
444 
WIDTH="34%"
445 
ALIGN="center"
446 
VALIGN="top"
447 
><A
448 
HREF="kernel.html"
449 
ACCESSKEY="U"
450 
>Up</A
451 
></TD
452 
><TD
453 
WIDTH="33%"
454 
ALIGN="right"
455 
VALIGN="top"
456 
>Event Flags</TD
457 
></TR
458 
></TABLE
459 
></DIV
460 
></BODY
461 
></HTML
462 
>

powered by: WebSVN 2.1.0

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