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 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
>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.