source: rtems/doc/itron3.0/mailbox.t @ 086a898a

4.104.114.84.95
Last change on this file since 086a898a was 086a898a, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 7:47:37 PM

Added copyright.

  • Property mode set to 100644
File size: 5.8 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  This is the chapter from the RTEMS ITRON User's Guide that
7@c  documents the services provided by the mailbox
8@c  manager.
9@c
10@c  $Id$
11@c
12
13
14@chapter Mailbox Manager
15
16@section Introduction
17
18The
19mailbox manager is basically a linked list, hidden by the super core message queue and consists of a control block, a private structure. The control block comprises of the create mailbox structure, the message structure and the reference mailbox structure.
20
21The services provided by the mailbox manager are:
22
23@itemize @bullet
24@item @code{cre_mbx} - Create Mailbox
25@item @code{del_mbx} - Delete Mailbox
26@item @code{snd_msg} - Send Message to Mailbox
27@item @code{rcv_msg} - Receive Message from Mailbox
28@item @code{prcv_msg} - Poll and Receive Message from Mailbox
29@item @code{trcv_msg} - Receive Message from Mailbox with Timeout
30@item @code{ref_mbx} - Reference Mailbox Status
31@end itemize
32
33
34@section Background
35
36@section Operations
37
38@section System Calls
39
40This section details the mailbox manager's services.
41A subsection is dedicated to each of this manager's services
42and describes the calling sequence, related constants, usage,
43and status codes.
44
45
46@c
47@c  cre_mbx
48@c
49
50@page
51
52@subsection cre_mbx - Create Mailbox
53
54@subheading CALLING SEQUENCE:
55
56@ifset is-C
57@example
58ER cre_mbx(
59  ID mbxid,
60  T_CMBX* pk_cmbx
61);
62@end example
63@end ifset
64
65@ifset is-Ada
66@end ifset
67
68@subheading STATUS CODES:
69
70@code{E_OK} - Normal completion@*
71@code{E_NOMEM} - Insufficient memory@*
72@code{E_ID} - Invalid ID number@*
73@code{E_RSATR} - Reserved attribute@*
74@code{E_OBJ} - Invalid object state@*
75@code{E_OACV} - Object access violation@*
76@code{E_PAR} - Parameter error
77
78
79@subheading DESCRIPTION:
80
81Allocated a control area/buffer space for mailbox with some ID.
82                User area:      +ve ids
83                System area:    -ve ids
84User may specify if its FIFO or priority level queue.
85Assumes shared memory b/w communicating processes.
86Initializes core message queue for this mbox.
87
88@subheading NOTES:
89
90NONE
91
92
93@c
94@c  del_mbx
95@c
96
97@page
98
99@subsection del_mbx - Delete Mailbox
100
101@subheading CALLING SEQUENCE:
102
103@ifset is-C
104@example
105ER del_mbx(
106  ID mbxid
107);
108@end example
109@end ifset
110
111@ifset is-Ada
112@end ifset
113
114@subheading STATUS CODES:
115
116@code{E_OK} - Normal completion@*
117@code{E_ID} - Invalid ID number@*
118@code{E_NOEXS} - Object does not exist@*
119@code{E_OACV} - Object access violation
120
121@subheading DESCRIPTION:
122
123Specified by the ID, cleans up all data structures and control blocks.
124
125@subheading NOTES:
126
127NONE
128
129
130@c
131@c  snd_msg
132@c
133
134@page
135
136@subsection snd_msg - Send Message to Mailbox
137
138@subheading CALLING SEQUENCE:
139
140@ifset is-C
141@example
142ER snd_msg(
143  ID mbxid,
144  T_MSG *pk_msg
145);
146@end example
147@end ifset
148
149@ifset is-Ada
150@end ifset
151
152@subheading STATUS CODES:
153
154@code{E_OK} - Normal completion@*
155@code{E_ID} - Invalid ID number@*
156@code{E_NOEXS} - Object does not exist@*
157@code{E_OACV} - Object access violation@*
158@code{E_QOVR} - Queueing or nesting overflow
159
160@subheading DESCRIPTION:
161
162Sends the address of message to mbox having a given id, any waiting tasks (blocked tasks) will be woken up. It supports non-blocking send.
163
164@subheading NOTES:
165
166NONE
167
168
169@c
170@c  rcv_msg
171@c
172
173@page
174
175@subsection rcv_msg - Receive Message from Mailbox
176
177@subheading CALLING SEQUENCE:
178
179@ifset is-C
180@example
181ER rcv_msg(
182  T_MSG **ppk_msg,
183  ID mbxid
184);
185@end example
186@end ifset
187
188@ifset is-Ada
189@end ifset
190
191@subheading STATUS CODES:
192
193@code{E_OK} - Normal completion@*
194@code{E_ID} - Invalid ID number@*
195@code{E_NOEXS} - Object does not exist@*
196@code{E_OACV} - Object access violation@*
197@code{E_PAR} - Parameter error@*
198@code{E_DLT} - The object being waited for was deleted@*
199@code{E_RLWAI} - WAIT state was forcibly released@*
200@code{E_CTX} - Context error
201
202@subheading DESCRIPTION:
203
204If there is no message then receiver blocks, if not empty then it takes the first message of the queue.
205
206@subheading NOTES:
207
208NONE
209
210
211@c
212@c  prcv_msg
213@c
214
215@page
216
217@subsection prcv_msg - Poll and Receive Message from Mailbox
218
219@subheading CALLING SEQUENCE:
220
221@ifset is-C
222@example
223ER prcv_msg(
224  T_MSG **ppk_msg,
225  ID mbxid
226);
227@end example
228@end ifset
229
230@ifset is-Ada
231@end ifset
232
233@subheading STATUS CODES:
234
235@code{E_OK} - Normal completion@*
236@code{E_ID} - Invalid ID number@*
237@code{E_NOEXS} - Object does not exist@*
238@code{E_OACV} - Object access violation@*
239@code{E_PAR} - Parameter error@*
240@code{E_DLT} - The object being waited for was deleted@*
241@code{E_RLWAI} - WAIT state was forcibly released@*
242@code{E_CTX} - Context error@*
243
244@subheading DESCRIPTION:
245
246Poll and receive message from mailbox.
247
248@subheading NOTES:
249
250NONE
251
252
253@c
254@c  trcv_msg
255@c
256
257@page
258
259@subsection trcv_msg - Receive Message from Mailbox with Timeout
260
261@subheading CALLING SEQUENCE:
262
263@ifset is-C
264@example
265ER trcv_msg(
266  T_MSG **ppk_msg,
267  ID mbxid,
268  TMO tmout
269);
270@end example
271@end ifset
272
273@ifset is-Ada
274@end ifset
275
276@subheading STATUS CODES:
277
278@code{E_OK} - Normal completion@*
279@code{E_ID} - Invalid ID number@*
280@code{E_NOEXS} - Object does not exist@*
281@code{E_OACV} - Object access violation@*
282@code{E_PAR} - Parameter error@*
283@code{E_DLT} - The object being waited for was deleted@*
284@code{E_RLWAI} - WAIT state was forcibly released@*
285@code{E_CTX} - Context error
286
287@subheading DESCRIPTION:
288
289Blocking receive with a maximum timeout.
290
291@subheading NOTES:
292
293NONE
294
295
296@c
297@c  ref_mbx
298@c
299
300@page
301
302@subsection ref_mbx - Reference Mailbox Status
303
304@subheading CALLING SEQUENCE:
305
306@ifset is-C
307@example
308ER ref_mbx(
309  T_RMBX *pk_rmbx,
310  ID mbxid
311);
312@end example
313@end ifset
314
315@ifset is-Ada
316@end ifset
317
318@subheading STATUS CODES:
319
320@code{E_OK} - Normal completion@*
321@code{E_ID} - Invalid ID number@*
322@code{E_NOEXS} - Object does not exist@*
323@code{E_OACV} - Object access violation@*
324@code{E_PAR} - Parameter error
325
326@subheading DESCRIPTION:
327
328Supports non-blocking receive. If there are no messages, it returns -1. Also returns id of the next process waiting on a message.
329
330@subheading NOTES:
331
332NONE
333
334
Note: See TracBrowser for help on using the repository browser.