source: rtems/c/src/exec/score/include/rtems/score/coremsg.h @ 3bb9542c

Last change on this file since 3bb9542c was 3bb9542c, checked in by Joel Sherrill <joel.sherrill@…>, on 08/09/01 at 21:08:50

2001-08-09 Joel Sherrill <joel@…>

  • c/src/exec/itron/src/snd_mbx.c, c/src/exec/itron/src/tsnd_mbf.c c/src/exec/posix/src/mqueuesendsupp.c, c/src/exec/rtems/src/msgqsubmit.c, c/src/exec/score/include/rtems/score/coremsg.h, c/src/exec/score/inline/rtems/score/coremsg.inl, c/src/exec/score/src/coremsgsubmit.c: Unblocking message queue operations should NOT use _Thread_Executing for return status since it is permissible to invoke message send operations from an ISR. This was reported by Suvrat Gupta <suvrat@…>.
  • Property mode set to 100644
File size: 8.2 KB
Line 
1/*  coremsg.h
2 *
3 *  This include file contains all the constants and structures associated
4 *  with the Message queue Handler.
5 *
6 *  COPYRIGHT (c) 1989-1999.
7 *  On-Line Applications Research Corporation (OAR).
8 *
9 *  The license and distribution terms for this file may be
10 *  found in the file LICENSE in this distribution or at
11 *  http://www.OARcorp.com/rtems/license.html.
12 *
13 *  $Id$
14 */
15 
16#ifndef __RTEMS_CORE_MESSAGE_QUEUE_h
17#define __RTEMS_CORE_MESSAGE_QUEUE_h
18 
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23#include <limits.h>
24#include <rtems/score/thread.h>
25#include <rtems/score/threadq.h>
26#include <rtems/score/priority.h>
27#include <rtems/score/watchdog.h>
28 
29/*
30 *  The following type defines the callout which the API provides
31 *  to support global/multiprocessor operations on message_queues.
32 */
33 
34typedef void ( *CORE_message_queue_API_mp_support_callout )(
35                 Thread_Control *,
36                 Objects_Id
37             );
38
39/*
40 *  The following defines the data types needed to manipulate
41 *  the contents of message buffers.
42 *
43 *  NOTE:  The buffer field is normally longer than a single unsigned32.
44 *         but since messages are variable length we just make a ptr to 1. 
45 */
46 
47typedef struct {
48    unsigned32  size;
49    unsigned32  buffer[1];
50} CORE_message_queue_Buffer;
51 
52/*
53 *  The following records define the organization of a message
54 *  buffer.
55 */
56 
57typedef struct {
58  Chain_Node                 Node;
59  int                        priority;
60  CORE_message_queue_Buffer  Contents;
61}   CORE_message_queue_Buffer_control;
62
63/*
64 *  Blocking disciplines for a message_queue.
65 */
66
67typedef enum {
68  CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
69  CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
70}   CORE_message_queue_Disciplines;
71
72/*
73 *  The following enumerated type details the modes in which a message
74 *  may be submitted to a message queue.  The message may be posted
75 *  in a send or urgent fashion.
76 *
77 *  NOTE:  All other values are message priorities.  Numerically smaller
78 *         priorities indicate higher priority messages.
79 *
80 */
81
82#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
83#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
84 
85typedef int CORE_message_queue_Submit_types;
86
87/*
88 *  Core Message queue handler return statuses.
89 */
90 
91typedef enum {
92  CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
93  CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
94  CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
95  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
96  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
97  CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
98  CORE_MESSAGE_QUEUE_STATUS_TIMEOUT
99}   CORE_message_queue_Status;
100
101/*
102 *  The following defines the control block used to manage the
103 *  attributes of each message queue.
104 */
105
106typedef struct {
107  CORE_message_queue_Disciplines  discipline;
108}   CORE_message_queue_Attributes;
109 
110/*
111 *  The following defines the type for a Notification handler.  A notification
112 *  handler is invoked when the message queue makes a 0->1 transition on
113 *  pending messages.
114 */
115
116typedef void (*CORE_message_queue_Notify_Handler)( void * );
117
118/*
119 *  The following defines the control block used to manage each
120 *  counting message_queue.
121 */
122 
123typedef struct {
124  Thread_queue_Control               Wait_queue;
125  CORE_message_queue_Attributes      Attributes;
126  unsigned32                         maximum_pending_messages;
127  unsigned32                         number_of_pending_messages;
128  unsigned32                         maximum_message_size;
129  Chain_Control                      Pending_messages;
130  CORE_message_queue_Buffer         *message_buffers;
131  CORE_message_queue_Notify_Handler  notify_handler;
132  void                              *notify_argument;
133  Chain_Control                      Inactive_messages;
134}   CORE_message_queue_Control;
135
136/*
137 *  _CORE_message_queue_Initialize
138 *
139 *  DESCRIPTION:
140 *
141 *  This routine initializes the message_queue based on the parameters passed.
142 */
143
144boolean _CORE_message_queue_Initialize(
145  CORE_message_queue_Control    *the_message_queue,
146  Objects_Classes                the_class,
147  CORE_message_queue_Attributes *the_message_queue_attributes,
148  unsigned32                     maximum_pending_messages,
149  unsigned32                     maximum_message_size,
150  Thread_queue_Extract_callout   proxy_extract_callout
151);
152 
153/*
154 *  _CORE_message_queue_Close
155 *
156 *  DESCRIPTION:
157 *
158 *  This function closes a message by returning all allocated space and
159 *  flushing the message_queue's task wait queue.
160 */
161 
162void _CORE_message_queue_Close(
163  CORE_message_queue_Control *the_message_queue,
164  Thread_queue_Flush_callout  remote_extract_callout,
165  unsigned32                  status
166);
167
168/*
169 *  _CORE_message_queue_Flush
170 *
171 *  DESCRIPTION:
172 *
173 *  This function flushes the message_queue's pending message queue.  The
174 *  number of messages flushed from the queue is returned.
175 *
176 */
177
178unsigned32 _CORE_message_queue_Flush(
179  CORE_message_queue_Control *the_message_queue
180);
181
182/*
183 *  _CORE_message_queue_Flush_support
184 *
185 *  DESCRIPTION:
186 *
187 *  This routine flushes all outstanding messages and returns
188 *  them to the inactive message chain.
189 */
190 
191unsigned32 _CORE_message_queue_Flush_support(
192  CORE_message_queue_Control *the_message_queue
193);
194 
195/*
196 *  _CORE_message_queue_Flush_waiting_threads
197 *
198 *  DESCRIPTION:
199 *
200 *  This function flushes the threads which are blocked on this
201 *  message_queue's pending message queue.  They are unblocked whether
202 *  blocked sending or receiving.
203 */
204
205void _CORE_message_queue_Flush_waiting_threads(
206  CORE_message_queue_Control *the_message_queue
207);
208
209/*
210 *  _CORE_message_queue_Broadcast
211 *
212 *  DESCRIPTION:
213 *
214 *  This function sends a message for every thread waiting on the queue and
215 *  returns the number of threads made ready by the message.
216 *
217 */
218 
219CORE_message_queue_Status _CORE_message_queue_Broadcast(
220  CORE_message_queue_Control                *the_message_queue,
221  void                                      *buffer,
222  unsigned32                                 size,
223  Objects_Id                                 id,
224  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
225  unsigned32                                *count
226);
227
228/*
229 *  _CORE_message_queue_Submit
230 *
231 *  DESCRIPTION:
232 *
233 *  This routine implements the send and urgent message functions. It
234 *  processes a message that is to be submitted to the designated
235 *  message queue.  The message will either be processed as a
236 *  send message which it will be inserted at the rear of the queue
237 *  or it will be processed as an urgent message which will be inserted
238 *  at the front of the queue.
239 *
240 */
241 
242CORE_message_queue_Status _CORE_message_queue_Submit(
243  CORE_message_queue_Control                *the_message_queue,
244  void                                      *buffer,
245  unsigned32                                 size,
246  Objects_Id                                 id,
247  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
248  CORE_message_queue_Submit_types            submit_type,
249  boolean                                    wait,
250  Watchdog_Interval                          timeout
251);
252
253/*
254 *  _CORE_message_queue_Seize
255 *
256 *  DESCRIPTION:
257 *
258 *  This kernel routine dequeues a message, copies the message buffer to
259 *  a given destination buffer, and frees the message buffer to the
260 *  inactive message pool.  The thread will be blocked if wait is TRUE,
261 *  otherwise an error will be given to the thread if no messages are available.
262 *
263 *  NOTE: Returns message priority via return are in TCB.
264 */
265 
266void _CORE_message_queue_Seize(
267  CORE_message_queue_Control      *the_message_queue,
268  Objects_Id                       id,
269  void                            *buffer,
270  unsigned32                      *size,
271  boolean                          wait,
272  Watchdog_Interval                timeout
273);
274
275/*
276 *  _CORE_message_queue_Insert_message
277 *
278 *  DESCRIPTION:
279 *
280 *  This kernel routine inserts the specified message into the
281 *  message queue.  It is assumed that the message has been filled
282 *  in before this routine is called.
283 */
284
285void _CORE_message_queue_Insert_message(
286  CORE_message_queue_Control        *the_message_queue,
287  CORE_message_queue_Buffer_control *the_message,
288  CORE_message_queue_Submit_types    submit_type
289);
290
291#ifndef __RTEMS_APPLICATION__
292#include <rtems/score/coremsg.inl>
293#endif
294
295#ifdef __cplusplus
296}
297#endif
298 
299#endif
300/*  end of include file */
301
Note: See TracBrowser for help on using the repository browser.