summaryrefslogtreecommitdiffstats
path: root/cpukit/score/include/rtems/score/coremsg.h
blob: a1789ab111370dfabe56a7a1a4439886e3b5267b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
/** 
 *  @file coremsg.h
 *
 *  This include file contains all the constants and structures associated
 *  with the Message queue Handler.
 */

/*
 *  COPYRIGHT (c) 1989-2004.
 *  On-Line Applications Research Corporation (OAR).
 *
 *  The license and distribution terms for this file may be
 *  found in the file LICENSE in this distribution or at
 *  http://www.rtems.com/license/LICENSE.
 *
 *  $Id$
 */

#ifndef __RTEMS_CORE_MESSAGE_QUEUE_h
#define __RTEMS_CORE_MESSAGE_QUEUE_h

/**
 *  @defgroup ScoreMessageQueue Message Queue Handler
 *
 *  This group contains functionality which provides the foundation
 *  Message Queue services used in all of the APIs supported by RTEMS.
 */
/**@{*/

#ifdef __cplusplus
extern "C" {
#endif

#include <limits.h>
#include <rtems/score/thread.h>
#include <rtems/score/threadq.h>
#include <rtems/score/priority.h>
#include <rtems/score/watchdog.h>

/**
 *  The following type defines the callout which the API provides
 *  to support global/multiprocessor operations on message_queues.
 */
typedef void ( *CORE_message_queue_API_mp_support_callout )(
                 Thread_Control *,
                 Objects_Id
             );

/**
 *  The following defines the data types needed to manipulate
 *  the contents of message buffers.
 *
 *  @note  The buffer field is normally longer than a single uint32_t
 *         but since messages are variable length we just make a ptr to 1.
 */
typedef struct {
  /** This field is the size of this message. */
  uint32_t    size;
  /** This field contains the actual message. */
  uint32_t    buffer[1];
} CORE_message_queue_Buffer;

/**
 *  The following records define the organization of a message
 *  buffer.
 */
typedef struct {
  /** This element allows this structure to be placed on chains. */
  Chain_Node                 Node;
  /** This field is the priority of this message. */
  int                        priority;
  /** This field points to the contents of the message. */
  CORE_message_queue_Buffer  Contents;
}   CORE_message_queue_Buffer_control;

/**
 *  Blocking disciplines for a message queue.
 */
typedef enum {
  /** This value indicates that pending messages are in FIFO order. */
  CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
  /** This value indicates that pending messages are in priority order. */
  CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
}   CORE_message_queue_Disciplines;

/** 
 *  This is the priority constant used when appending messages onto
 *  a message queue.
 */
#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX

/** 
 *  This is the priority constant used when prepending messages onto
 *  a message queue.
 */
#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN

/**
 *  The following enumerated type details the modes in which a message
 *  may be submitted to a message queue.  The message may be posted
 *  in a send or urgent fashion.
 *
 *  @note  All other values are message priorities.  Numerically smaller
 *         priorities indicate higher priority messages.
 */
typedef int CORE_message_queue_Submit_types;

/**
 *  Core Message queue handler return statuses.
 */
typedef enum {
  /** This value indicates the operation completed sucessfully. */
  CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
  /** This value indicates that the message was too large for this queue. */
  CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
  /** This value indicates that there are too many messages pending. */
  CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
  /** This value indicates that a receive was unsuccessful. */
  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
  /** This value indicates that a blocking send was unsuccessful. */
  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
  /** This value indicates that the message queue being blocked upon
   *  was deleted while the thread was waiting.
   */
  CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
  /** This value indicates that the thread had to timeout while waiting
   *  to receive a message because one did not become available.
   */
  CORE_MESSAGE_QUEUE_STATUS_TIMEOUT,
  /** This value indicates that a blocking receive was unsuccessful. */
  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
}   CORE_message_queue_Status;

/**
 *  The following defines the control block used to manage the
 *  attributes of each message queue.
 */
typedef struct {
  /** This field specifies the order in which blocking tasks will be ordered. */
  CORE_message_queue_Disciplines  discipline;
}   CORE_message_queue_Attributes;

/**
 *  The following defines the type for a Notification handler.  A notification
 *  handler is invoked when the message queue makes a 0->1 transition on
 *  pending messages.
 */
typedef void (*CORE_message_queue_Notify_Handler)( void * );

/**
 *  The following defines the control block used to manage each
 *  counting message_queue.
 */
typedef struct {
  /** This field is the Waiting Queue used to manage the set of tasks
   *  which are blocked waiting to receive a message from this queue.
   */
  Thread_queue_Control               Wait_queue;
  /** This element is the set of attributes which define this instance's
   *  behavior.
   */
  CORE_message_queue_Attributes      Attributes;
  /** This element is maximum number of messages which may be pending
   *  at any given time.
   */
  uint32_t                           maximum_pending_messages;
  /** This element is the number of messages which are currently pending.
   */
  uint32_t                           number_of_pending_messages;
  /** This is the size in bytes of the largest message which may be
   *  sent via this queue.
   */
  uint32_t                           maximum_message_size;
  /** This chain is the set of pending messages.  It may be ordered by
   *  message priority or in FIFO order.
   */
  Chain_Control                      Pending_messages;
  /** This is the address of the memory allocated for message buffers.
   *  It is allocated are part of message queue initialization and freed
   *  as part of destroying it.
   */
  CORE_message_queue_Buffer         *message_buffers;
  /** This is the routine invoked when the message queue transitions 
   *  from zero (0) messages pending to one (1) message pending.
   */
  CORE_message_queue_Notify_Handler  notify_handler;
  /** This field is the argument passed to the @ref notify_argument. */
  void                              *notify_argument;
  /** This chain is the set of inactive messages.  A message is inactive
   *  when it does not contain a pending message.
   */
  Chain_Control                      Inactive_messages;
}   CORE_message_queue_Control;

/**
 *  This routine initializes the message_queue based on the parameters passed.
 *
 *  @param the_message_queue (in) points to the message queue to initialize
 *  @param the_message_queue_attributes (in) points to the attributes that
 *         will be used with this message queue instance
 *  @param maximum_pending_messages (in) is the maximum number of messages
 *         that will be allowed to pend at any given time
 *  @param maximum_message_size (in) is the size of largest message that
 *         may be sent to this message queue instance
 *
 *  @return TRUE if the message queue can be initialized.  In general,
 *         FALSE will only be returned if memory for the pending 
 *         messages cannot be allocated.
 */
boolean _CORE_message_queue_Initialize(
  CORE_message_queue_Control    *the_message_queue,
  CORE_message_queue_Attributes *the_message_queue_attributes,
  uint32_t                       maximum_pending_messages,
  uint32_t                       maximum_message_size
);

/**
 *  This function closes a message by returning all allocated space and
 *  flushing the message_queue's task wait queue.
 *
 *  @param the_message_queue (in) points to the message queue to close
 *  @param remote_extract_callout (in) is the routine to call for each thread
 *         that is extracted from the set of waiting threads
 *  @param status (in) is the status that each waiting thread will return
 *         from it's blocking service
 */
void _CORE_message_queue_Close(
  CORE_message_queue_Control *the_message_queue,
  Thread_queue_Flush_callout  remote_extract_callout,
  uint32_t                    status
);

/**
 *  This function flushes the message_queue's pending message queue.  The
 *  number of messages flushed from the queue is returned.
 *
 *  @param the_message_queue (in) points to the message queue to flush
 *  @return the number of message pending messages flushed
 */
uint32_t   _CORE_message_queue_Flush(
  CORE_message_queue_Control *the_message_queue
);

/**
 *  This routine flushes all outstanding messages and returns
 *  them to the inactive message chain.
 *
 *  @param the_message_queue (in) points to the message queue to flush
 *  @return the number of message pending messages flushed
 */
uint32_t   _CORE_message_queue_Flush_support(
  CORE_message_queue_Control *the_message_queue
);

/**
 *  This function flushes the threads which are blocked on this
 *  message_queue's pending message queue.  They are unblocked whether
 *  blocked sending or receiving.
 *
 *  @param the_message_queue (in) points to the message queue to flush
 */
void _CORE_message_queue_Flush_waiting_threads(
  CORE_message_queue_Control *the_message_queue
);

/**
 *  This function sends a message for every thread waiting on the queue and
 *  returns the number of threads made ready by the message.
 *
 *  @param the_message_queue (in) points to the message queue
 *  @param buffer (in) is the starting address of the message to broadcast
 *  @param size (in) is the size of the message being broadcast
 *  @param id (in) is the RTEMS object Id associated with this message queue.
 *         It is used when unblocking a remote thread.
 *  @param api_message_queue_mp_support (in) is the routine to invoke if 
 *         a thread that is unblocked is actually a remote thread.
 *  @param count (out) points to the variable that will contain the
 *         number of tasks that are sent this message
 *  @return @a *count will contain the number of messages sent
 *  @return indication of the successful completion or reason for failure
 */
CORE_message_queue_Status _CORE_message_queue_Broadcast(
  CORE_message_queue_Control                *the_message_queue,
  void                                      *buffer,
  uint32_t                                   size,
  Objects_Id                                 id,
  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
  uint32_t                                  *count
);

/**
 *  This routine implements the send and urgent message functions. It
 *  processes a message that is to be submitted to the designated
 *  message queue.  The message will either be processed as a
 *  send message which it will be inserted at the rear of the queue
 *  or it will be processed as an urgent message which will be inserted
 *  at the front of the queue.
 *
 *  @param the_message_queue (in) points to the message queue
 *  @param buffer (in) is the starting address of the message to send
 *  @param size (in) is the size of the message being send
 *  @param id (in) is the RTEMS object Id associated with this message queue.
 *         It is used when unblocking a remote thread.
 *  @param api_message_queue_mp_support (in) is the routine to invoke if 
 *         a thread that is unblocked is actually a remote thread.
 *  @param submit_type (in) determines whether the message is prepended,
 *         appended, or enqueued in priority order.
 *  @param wait (in) indicates whether the calling thread is willing to block
 *         if the message queue is full.
 *  @param timeout (in) is the maximum number of clock ticks that the calling
 *         thread is willing to block if the message queue is full.
 *  @return indication of the successful completion or reason for failure
 */
CORE_message_queue_Status _CORE_message_queue_Submit(
  CORE_message_queue_Control                *the_message_queue,
  void                                      *buffer,
  uint32_t                                   size,
  Objects_Id                                 id,
  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
  CORE_message_queue_Submit_types            submit_type,
  boolean                                    wait,
  Watchdog_Interval                          timeout
);

/**
 *  This kernel routine dequeues a message, copies the message buffer to
 *  a given destination buffer, and frees the message buffer to the
 *  inactive message pool.  The thread will be blocked if wait is TRUE,
 *  otherwise an error will be given to the thread if no messages are available.
 *
 *  @param the_message_queue (in) points to the message queue
 *  @param id (in) is the RTEMS object Id associated with this message queue.
 *         It is used when unblocking a remote thread.
 *  @param buffer (in) is the starting address of the message buffer to
 *         to be filled in with a message
 *  @param size (in) is the size of the @a buffer and indicates the maximum
 *         size message that the caller can receive.
 *  @param wait (in) indicates whether the calling thread is willing to block
 *         if the message queue is empty.
 *  @param timeout (in) is the maximum number of clock ticks that the calling
 *         thread is willing to block if the message queue is empty.
 * 
 *  @return indication of the successful completion or reason for failure
 *  @note Returns message priority via return are in TCB.
 */
void _CORE_message_queue_Seize(
  CORE_message_queue_Control      *the_message_queue,
  Objects_Id                       id,
  void                            *buffer,
  uint32_t                        *size,
  boolean                          wait,
  Watchdog_Interval                timeout
);

/**
 *  This kernel routine inserts the specified message into the
 *  message queue.  It is assumed that the message has been filled
 *  in before this routine is called.
 *
 *  @param the_message_queue (in) points to the message queue
 *  @param the_message (in) is the message to enqueue
 *  @param submit_type (in) determines whether the message is prepended,
 *         appended, or enqueued in priority order.
 */
void _CORE_message_queue_Insert_message(
  CORE_message_queue_Control        *the_message_queue,
  CORE_message_queue_Buffer_control *the_message,
  CORE_message_queue_Submit_types    submit_type
);

#ifndef __RTEMS_APPLICATION__
#include <rtems/score/coremsg.inl>
#endif

#ifdef __cplusplus
}
#endif

/**@}*/

#endif
/*  end of include file */