source: rtems/c/src/exec/rtems/headers/message.h @ b06e68ef

4.104.114.84.95
Last change on this file since b06e68ef was b06e68ef, checked in by Joel Sherrill <joel.sherrill@…>, on 08/17/95 at 19:51:51

Numerous miscellaneous features incorporated from Tony Bennett
(tbennett@…) including the following major additions:

+ variable length messages
+ named devices
+ debug monitor
+ association tables/variables

  • Property mode set to 100644
File size: 12.4 KB
RevLine 
[ac7d5ef0]1/*  message.h
2 *
3 *  This include file contains all the constants and structures associated
4 *  with the Message Queue Manager.  This manager provides a mechanism for
5 *  communication and synchronization between tasks using messages.
6 *
7 *  Directives provided are:
8 *
9 *     + create a queue
10 *     + get ID of a queue
11 *     + delete a queue
12 *     + put a message at the rear of a queue
13 *     + put a message at the front of a queue
14 *     + broadcast N messages to a queue
15 *     + receive message from a queue
16 *     + flush all messages on a queue
17 *
18 *
19 *  COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994.
20 *  On-Line Applications Research Corporation (OAR).
21 *  All rights assigned to U.S. Government, 1994.
22 *
23 *  This material may be reproduced by or for the U.S. Government pursuant
24 *  to the copyright license under the clause at DFARS 252.227-7013.  This
25 *  notice must appear in all copies of this file and its derivatives.
26 *
27 *  $Id$
28 */
29
30#ifndef __RTEMS_MESSAGE_QUEUE_h
31#define __RTEMS_MESSAGE_QUEUE_h
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37#include <rtems/chain.h>
38#include <rtems/object.h>
39#include <rtems/threadq.h>
40
41/*
42 *  The following defines the data types needed to manipulate
43 *  the contents of message buffers.
[b06e68ef]44 *  Since msgs are variable length we just make a ptr to 1.
[ac7d5ef0]45 */
46
47typedef struct {
[b06e68ef]48    unsigned32  size;
49
50#ifndef __cplusplus
51                               /* NOTE:   [0] is gcc specific,
52                                *   but specifically disallowed by ANSI STD C++
53                                * g++ warns about it, so we #ifdef it out to
54                                * get rid of warnings when compiled by g++.
55                                */
56    unsigned32  buffer[0];
57#endif
58
59} Message_queue_Buffer;
[ac7d5ef0]60
61/*
62 *  The following records define the organization of a message
63 *  buffer.
64 */
65
66typedef struct {
67  Chain_Node           Node;
68  Message_queue_Buffer Contents;
69}   Message_queue_Buffer_control;
70
71/*
72 *  The following records define the control block used to manage
73 *  each message queue.
74 */
75
76typedef struct {
77  Objects_Control      Object;
78  Thread_queue_Control Wait_queue;
[b06e68ef]79  rtems_attribute      attribute_set;
[ac7d5ef0]80  unsigned32           maximum_pending_messages;
81  unsigned32           number_of_pending_messages;
[b06e68ef]82  unsigned32           maximum_message_size;
[ac7d5ef0]83  Chain_Control        Pending_messages;
[b06e68ef]84  Message_queue_Buffer *message_buffers;
85  Chain_Control        Inactive_messages;
[ac7d5ef0]86}   Message_queue_Control;
87
88/*
89 *  The following defines the information control block used to
90 *  manage this class of objects.
91 */
92
93EXTERN Objects_Information  _Message_queue_Information;
94
95/*
96 *  The following enumerated type details the modes in which a message
97 *  may be submitted to a message queue.  The message may be posted
98 *  in a send or urgent fashion.
99 */
100
101typedef enum {
102  MESSAGE_QUEUE_SEND_REQUEST   = 0,
103  MESSAGE_QUEUE_URGENT_REQUEST = 1
104}  Message_queue_Submit_types;
105
106/*
107 *  _Message_queue_Manager_initialization
108 *
109 *  DESCRIPTION:
110 *
111 *  This routine performs the initialization necessary for this manager.
112 */
113
114void _Message_queue_Manager_initialization(
[b06e68ef]115  unsigned32 maximum_message_queues
[ac7d5ef0]116);
117
118/*
119 *  rtems_message_queue_create
120 *
121 *  DESCRIPTION:
122 *
123 *  This routine implements the rtems_message_queue_create directive.  The
124 *  message queue will have the name name.  If the attribute_set indicates
125 *  that the message queue is to be limited in the number of messages
126 *  that can be outstanding, then count indicates the maximum number of
127 *  messages that will be held.  It returns the id of the created
128 *  message queue in ID.
129 */
130
131rtems_status_code rtems_message_queue_create(
[b06e68ef]132  Objects_Name     name,
133  unsigned32       count,
134  unsigned32       max_message_size,
[ac7d5ef0]135  rtems_attribute  attribute_set,
[b06e68ef]136  Objects_Id      *id
[ac7d5ef0]137);
138
139/*
140 *  rtems_message_queue_ident
141 *
142 *  DESCRIPTION:
143 *
144 *  This routine implements the rtems_message_queue_ident directive.
145 *  This directive returns the message queue ID associated with NAME.
146 *  If more than one message queue is named name, then the message
147 *  queue to which the ID belongs is arbitrary.  node indicates the
148 *  extent of the search for the ID of the message queue named name.
149 *  The search can be limited to a particular node or allowed to
150 *  encompass all nodes.
151 */
152
153rtems_status_code rtems_message_queue_ident(
154  Objects_Name  name,
155  unsigned32    node,
156  Objects_Id   *id
157);
158
159/*
160 *  rtems_message_queue_delete
161 *
162 *  DESCRIPTION:
163 *
164 *  This routine implements the rtems_message_queue_delete directive.  The
165 *  message queue indicated by ID is deleted.
166 */
167
168rtems_status_code rtems_message_queue_delete(
169  Objects_Id id
170);
171
172/*
173 *  rtems_message_queue_send
174 *
175 *  DESCRIPTION:
176 *
177 *  This routine implements the rtems_message_queue_send directive.
178 *  This directive sends the message buffer to the message queue
179 *  indicated by ID.  If one or more tasks is blocked waiting
180 *  to receive a message from this message queue, then one will
181 *  receive the message.  The task selected to receive the
182 *  message is based on the task queue discipline algorithm in
183 *  use by this particular message queue.  If no tasks are waiting,
184 *  then the message buffer will be placed at the rear of the
185 *  chain of pending messages for this message queue.
186 */
187
188rtems_status_code rtems_message_queue_send(
189  Objects_Id            id,
[b06e68ef]190  void                 *buffer,
191  unsigned32            size
[ac7d5ef0]192);
193
194/*
195 *  rtems_message_queue_urgent
196 *
197 *  DESCRIPTION:
198 *
199 *  This routine implements the rtems_message_queue_send directive.
200 *  This directive sends the message buffer to the message queue
201 *  indicated by ID.  If one or more tasks is blocked waiting
202 *  to receive a message from this message queue, then one will
203 *  receive the message.  The task selected to receive the
204 *  message is based on the task queue discipline algorithm in
205 *  use by this particular message queue.  If no tasks are waiting,
206 *  then the message buffer will be placed at the rear of the
207 *  chain of pending messages for this message queue.
208 */
209
210rtems_status_code rtems_message_queue_urgent(
211  Objects_Id            id,
[b06e68ef]212  void                 *buffer,
213  unsigned32            size
[ac7d5ef0]214);
215
216/*
217 *  rtems_message_queue_broadcast
218 *
219 *  DESCRIPTION:
220 *
221 *  This routine implements the rtems_message_queue_send directive.
222 *  This directive sends the message buffer to the message queue
223 *  indicated by ID.  If one or more tasks is blocked waiting
224 *  to receive a message from this message queue, then one will
225 *  receive the message.  The task selected to receive the
226 *  message is based on the task queue discipline algorithm in
227 *  use by this particular message queue.  If no tasks are waiting,
228 *  then the message buffer will be placed at the rear of the
229 *  chain of pending messages for this message queue.
230 */
231
232rtems_status_code rtems_message_queue_broadcast(
233  Objects_Id            id,
234  void                 *buffer,
[b06e68ef]235  unsigned32            size,
[ac7d5ef0]236  unsigned32           *count
237);
238
239/*
240 *  rtems_message_queue_receive
241 *
242 *  DESCRIPTION:
243 *
244 *  This routine implements the rtems_message_queue_receive directive.
245 *  This directive is invoked when the calling task wishes to receive
246 *  a message from the message queue indicated by ID.  The received
247 *  message is to be placed in buffer.  If no messages are outstanding
248 *  and the option_set indicates that the task is willing to block,
249 *  then the task will be blocked until a message arrives or until,
250 *  optionally, timeout clock ticks have passed.
251 */
252
253rtems_status_code rtems_message_queue_receive(
254  Objects_Id            id,
255  void                 *buffer,
[b06e68ef]256  unsigned32           *size_p,
[ac7d5ef0]257  unsigned32            option_set,
[b06e68ef]258  rtems_interval        timeout
[ac7d5ef0]259);
260
261/*
262 *  rtems_message_queue_flush
263 *
264 *  DESCRIPTION:
265 *
266 *  This routine implements the rtems_message_queue_flush directive.
267 *  This directive takes all outstanding messages for the message
268 *  queue indicated by ID and returns them to the inactive message
269 *  chain.  The number of messages flushed is returned in COUNT.
270 */
271
272rtems_status_code rtems_message_queue_flush(
273  Objects_Id  id,
274  unsigned32 *count
275);
276
277/*
278 *  _Message_queue_Copy_buffer
279 *
280 *  DESCRIPTION:
281 *
282 *  This routine copies the contents of the source message buffer
283 *  to the destination message buffer.
284 */
285
286STATIC INLINE void _Message_queue_Copy_buffer (
[b06e68ef]287  void      *source,
288  void      *destination,
289  unsigned32 size
[ac7d5ef0]290);
291
292/*
293 *  _Message_queue_Seize
294 *
295 *  DESCRIPTION:
296 *
297 *  This routine attempts to receive a message from the_message_queue.
298 *  If a message is available or if the RTEMS_NO_WAIT option is enabled in
299 *  option_set, then the routine returns.  Otherwise, the calling task
300 *  is blocked until a message is available.  If a message is returned
301 *  to the task, then buffer will contain its contents.
302 */
303
304boolean _Message_queue_Seize(
305  Message_queue_Control *the_message_queue,
306  unsigned32             option_set,
[b06e68ef]307  void                  *buffer,
308  unsigned32            *size_p
[ac7d5ef0]309);
310
311/*
312 *  _Message_queue_Flush_support
313 *
314 *  DESCRIPTION:
315 *
316 *  This routine flushes all outstanding messages and returns
317 *  them to the inactive message chain.
318 */
319
320unsigned32 _Message_queue_Flush_support(
321  Message_queue_Control *the_message_queue
322);
323
324/*
325 *  _Message_queue_Submit
326 *
327 *  DESCRIPTION:
328 *
329 *  This routine provides the common foundation for the
330 *  rtems_message_queue_send and rtems_message_queue_urgent directives.
331 */
332
333rtems_status_code _Message_queue_Submit(
334  Objects_Id                  id,
[b06e68ef]335  void                       *buffer,
336  unsigned32                  size,
[ac7d5ef0]337  Message_queue_Submit_types  submit_type
338);
339
340/*
341 *  _Message_queue_Allocate_message_buffer
342 *
343 *  DESCRIPTION:
344 *
345 *  This function allocates a message buffer from the inactive
346 *  message buffer chain.
347 */
348
349STATIC INLINE Message_queue_Buffer_control *
[b06e68ef]350  _Message_queue_Allocate_message_buffer (
351   Message_queue_Control *the_message_queue
352);
[ac7d5ef0]353
354/*
355 *  _Message_queue_Free_message_buffer
356 *
357 *  DESCRIPTION:
358 *
359 *  This routine frees a message buffer to the inactive
360 *  message buffer chain.
361 */
362
363STATIC INLINE void _Message_queue_Free_message_buffer (
[b06e68ef]364  Message_queue_Control        *the_message_queue,
[ac7d5ef0]365  Message_queue_Buffer_control *the_message
366);
367
368/*
369 *  _Message_queue_Get_pending_message
370 *
371 *  DESCRIPTION:
372 *
373 *  This function removes the first message from the_message_queue
374 *  and returns a pointer to it.
375 */
376
377STATIC INLINE
378  Message_queue_Buffer_control *_Message_queue_Get_pending_message (
379  Message_queue_Control *the_message_queue
380);
381
382/*
383 *  _Message_queue_Append
384 *
385 *  DESCRIPTION:
386 *
387 *  This routine places the_message at the rear of the outstanding
388 *  messages on the_message_queue.
389 */
390
391STATIC INLINE void _Message_queue_Append (
392  Message_queue_Control        *the_message_queue,
393  Message_queue_Buffer_control *the_message
394);
395
396/*
397 *  _Message_queue_Prepend
398 *
399 *  DESCRIPTION:
400 *
401 *  This routine places the_message at the rear of the outstanding
402 *  messages on the_message_queue.
403 */
404
405STATIC INLINE void _Message_queue_Prepend (
406  Message_queue_Control        *the_message_queue,
407  Message_queue_Buffer_control *the_message
408);
409
410/*
411 *  _Message_queue_Is_null
412 *
413 *  DESCRIPTION:
414 *
415 *  This function places the_message at the rear of the outstanding
416 *  messages on the_message_queue.
417 */
418
419STATIC INLINE boolean _Message_queue_Is_null (
420  Message_queue_Control *the_message_queue
421);
422
423/*
424 *  _Message_queue_Allocate
425 *
426 *  DESCRIPTION:
427 *
428 *  This function allocates a message queue control block from
429 *  the inactive chain of free message queue control blocks.
430 */
431
[b06e68ef]432Message_queue_Control *_Message_queue_Allocate (
433    unsigned32          count,
434    unsigned32          max_message_size
435);
[ac7d5ef0]436
437/*
438 *  _Message_queue_Free
439 *
440 *  DESCRIPTION:
441 *
[b06e68ef]442 *  This routine deallocates a message queue control block into
[ac7d5ef0]443 *  the inactive chain of free message queue control blocks.
444 */
445
446STATIC INLINE void _Message_queue_Free (
447  Message_queue_Control *the_message_queue
448);
449
450/*
451 *  _Message_queue_Get
452 *
453 *  DESCRIPTION:
454 *
455 *  This function maps message queue IDs to message queue control
456 *  blocks.  If ID corresponds to a local message queue, then it
457 *  returns the_message_queue control pointer which maps to ID
458 *  and location is set to OBJECTS_LOCAL.  If the message queue ID is
459 *  global and resides on a remote node, then location is set
460 *  to OBJECTS_REMOTE, and the_message_queue is undefined.
461 *  Otherwise, location is set to OBJECTS_ERROR and
462 *  the_message_queue is undefined.
463 */
464
465STATIC INLINE Message_queue_Control *_Message_queue_Get (
466  Objects_Id         id,
467  Objects_Locations *location
468);
469
470#include <rtems/message.inl>
471#include <rtems/msgmp.h>
472
473#ifdef __cplusplus
474}
475#endif
476
477#endif
478/* end of include file */
Note: See TracBrowser for help on using the repository browser.