source: rtems/cpukit/score/include/rtems/score/coremsg.h @ d4dc7c8

4.115
Last change on this file since d4dc7c8 was 20f02c6, checked in by Ralf Corsepius <ralf.corsepius@…>, on 11/28/09 at 05:58:54

Whitespace removal.

  • Property mode set to 100644
File size: 15.9 KB
Line 
1/**
2 *  @file  rtems/score/coremsg.h
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the Message queue Handler.
6 */
7
8/*
9 *  COPYRIGHT (c) 1989-2009.
10 *  On-Line Applications Research Corporation (OAR).
11 *
12 *  The license and distribution terms for this file may be
13 *  found in the file LICENSE in this distribution or at
14 *  http://www.rtems.com/license/LICENSE.
15 *
16 *  $Id$
17 */
18
19#ifndef _RTEMS_SCORE_COREMSG_H
20#define _RTEMS_SCORE_COREMSG_H
21
22/**
23 *  @defgroup ScoreMessageQueue Message Queue Handler
24 *
25 *  This handler encapsulates functionality which provides the foundation
26 *  Message Queue services used in all of the APIs supported by RTEMS.
27 */
28/**@{*/
29
30#include <limits.h>
31#include <rtems/score/thread.h>
32#include <rtems/score/threadq.h>
33#include <rtems/score/priority.h>
34#include <rtems/score/watchdog.h>
35
36#if defined(RTEMS_POSIX_API)
37  #define RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY
38#endif
39
40#if defined(RTEMS_POSIX_API)
41  #define RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION
42#endif
43
44#if defined(RTEMS_POSIX_API)
45  #define RTEMS_SCORE_COREMSG_ENABLE_BLOCKING_SEND
46#endif
47
48#ifdef __cplusplus
49extern "C" {
50#endif
51
52/**
53 *  @brief  Message Queue MP Callback Prototype
54 *
55 *  The following type defines the callout which the API provides
56 *  to support global/multiprocessor operations on message_queues.
57 */
58typedef void ( *CORE_message_queue_API_mp_support_callout )(
59                 Thread_Control *,
60                 Objects_Id
61             );
62
63/**
64 *  @brief Message Buffer Contents Management Structure
65 *
66 *  The following defines the data types needed to manipulate
67 *  the contents of message buffers.
68 *
69 *  @note  The buffer field is normally longer than a single uint32_t
70 *         but since messages are variable length we just make a ptr to 1.
71 */
72typedef struct {
73  /** This field is the size of this message. */
74  size_t      size;
75  /** This field contains the actual message. */
76  uint32_t    buffer[1];
77} CORE_message_queue_Buffer;
78
79/**
80 *  @brief Message Structure
81 *
82 *  The following records define the organization of a message
83 *  buffer.
84 */
85typedef struct {
86  /** This element allows this structure to be placed on chains. */
87  Chain_Node                 Node;
88  #if defined(RTEMS_SCORE_COREMSG_ENABLE_MESSAGE_PRIORITY)
89    /** This field is the priority of this message. */
90    int                        priority;
91  #endif
92  /** This field points to the contents of the message. */
93  CORE_message_queue_Buffer  Contents;
94}   CORE_message_queue_Buffer_control;
95
96/**
97 *  @brief Message Queue Blocking Disciplines
98 *
99 *  This enumerated types defines the possible blocking disciplines
100 *  for a message queue.
101 */
102typedef enum {
103  /** This value indicates that blocking tasks are in FIFO order. */
104  CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
105  /** This value indicates that blocking tasks are in priority order. */
106  CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
107}   CORE_message_queue_Disciplines;
108
109/**
110 *  @brief Message Priority for Appending
111 *
112 *  This is the priority constant used when appending messages onto
113 *  a message queue.
114 */
115#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
116
117/**
118 *  @brief Message Priority for Prepending
119 *
120 *  This is the priority constant used when prepending messages onto
121 *  a message queue.
122 */
123#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
124
125/**
126 *  @brief Message Insertion Operation Types
127 *
128 *  The following type details the modes in which a message
129 *  may be submitted to a message queue.  The message may be posted
130 *  in a send or urgent fashion.
131 *
132 *  @note  All other values are message priorities.  Numerically smaller
133 *         priorities indicate higher priority messages.
134 */
135typedef int CORE_message_queue_Submit_types;
136
137/**
138 *  @brief Core Message Queue Return Statuses
139 *
140 *  This enumerated type defines the possible set of Core Message
141 *  Queue handler return statuses.
142 */
143typedef enum {
144  /** This value indicates the operation completed sucessfully. */
145  CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
146  /** This value indicates that the message was too large for this queue. */
147  CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
148  /** This value indicates that there are too many messages pending. */
149  CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
150  /** This value indicates that a receive was unsuccessful. */
151  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
152  /** This value indicates that a blocking send was unsuccessful. */
153  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
154  /** This value indicates that the message queue being blocked upon
155   *  was deleted while the thread was waiting.
156   */
157  CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
158  /** This value indicates that the thread had to timeout while waiting
159   *  to receive a message because one did not become available.
160   */
161  CORE_MESSAGE_QUEUE_STATUS_TIMEOUT,
162  /** This value indicates that a blocking receive was unsuccessful. */
163  CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
164}   CORE_message_queue_Status;
165
166/**
167 *  @brief Core Message Queue Last Status
168 *
169 *  This is the last status value.
170 */
171#define CORE_MESSAGE_QUEUE_STATUS_LAST CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
172
173/**
174 *  @brief Message Queue Attributes Type
175 *
176 *  The following defines the control block used to manage the
177 *  attributes of each message queue.
178 */
179typedef struct {
180  /** This field specifies the order in which blocking tasks will be ordered. */
181  CORE_message_queue_Disciplines  discipline;
182}   CORE_message_queue_Attributes;
183
184#if defined(RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION)
185  /**
186   *  @brief Message Queue Notification Callback Prototype
187   *
188   *  The following defines the type for a Notification handler.  A
189   *  notification handler is invoked when the message queue makes a
190   *  0->1 transition on pending messages.
191   */
192  typedef void (*CORE_message_queue_Notify_Handler)( void * );
193#endif
194
195/**
196 *  @brief Core Message Queue Control Structure
197 *
198 *  The following defines the control block used to manage each
199 *  Message Queue
200 */
201typedef struct {
202  /** This field is the Waiting Queue used to manage the set of tasks
203   *  which are blocked waiting to receive a message from this queue.
204   */
205  Thread_queue_Control               Wait_queue;
206  /** This element is the set of attributes which define this instance's
207   *  behavior.
208   */
209  CORE_message_queue_Attributes      Attributes;
210  /** This element is maximum number of messages which may be pending
211   *  at any given time.
212   */
213  uint32_t                           maximum_pending_messages;
214  /** This element is the number of messages which are currently pending.
215   */
216  uint32_t                           number_of_pending_messages;
217  /** This is the size in bytes of the largest message which may be
218   *  sent via this queue.
219   */
220  size_t                             maximum_message_size;
221  /** This chain is the set of pending messages.  It may be ordered by
222   *  message priority or in FIFO order.
223   */
224  Chain_Control                      Pending_messages;
225  /** This is the address of the memory allocated for message buffers.
226   *  It is allocated are part of message queue initialization and freed
227   *  as part of destroying it.
228   */
229  CORE_message_queue_Buffer         *message_buffers;
230  #if defined(RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION)
231    /** This is the routine invoked when the message queue transitions
232     *  from zero (0) messages pending to one (1) message pending.
233     */
234    CORE_message_queue_Notify_Handler  notify_handler;
235    /** This field is the argument passed to the @ref notify_argument. */
236    void                              *notify_argument;
237  #endif
238  /** This chain is the set of inactive messages.  A message is inactive
239   *  when it does not contain a pending message.
240   */
241  Chain_Control                      Inactive_messages;
242}   CORE_message_queue_Control;
243
244/**
245 *  @brief Initialize a Message Queue
246 *
247 *  This routine initializes @a the_message_queue based on the parameters passed.
248 *
249 *  @param[in] the_message_queue points to the message queue to initialize
250 *  @param[in] the_message_queue_attributes points to the attributes that
251 *         will be used with this message queue instance
252 *  @param[in] maximum_pending_messages is the maximum number of messages
253 *         that will be allowed to pend at any given time
254 *  @param[in] maximum_message_size is the size of largest message that
255 *         may be sent to this message queue instance
256 *
257 *  @return true if the message queue can be initialized.  In general,
258 *         false will only be returned if memory for the pending
259 *         messages cannot be allocated.
260 */
261bool _CORE_message_queue_Initialize(
262  CORE_message_queue_Control    *the_message_queue,
263  CORE_message_queue_Attributes *the_message_queue_attributes,
264  uint32_t                       maximum_pending_messages,
265  size_t                         maximum_message_size
266);
267
268/**
269 *  @brief Close a Message Queue
270 *
271 *  This function closes a message by returning all allocated space and
272 *  flushing @a the_message_queue's task wait queue.
273 *
274 *  @param[in] the_message_queue points to the message queue to close
275 *  @param[in] remote_extract_callout is the routine to call for each thread
276 *         that is extracted from the set of waiting threads
277 *  @param[in] status is the status that each waiting thread will return
278 *         from it's blocking service
279 */
280void _CORE_message_queue_Close(
281  CORE_message_queue_Control *the_message_queue,
282  Thread_queue_Flush_callout  remote_extract_callout,
283  uint32_t                    status
284);
285
286/**
287 *  @brief Flush Pending Messages
288 *
289 *  This function flushes @a the_message_queue's pending message queue.  The
290 *  number of messages flushed from the queue is returned.
291 *
292 *  @param[in] the_message_queue points to the message queue to flush
293 *
294 *  @return This method returns the number of message pending messages flushed.
295 */
296uint32_t   _CORE_message_queue_Flush(
297  CORE_message_queue_Control *the_message_queue
298);
299
300/**
301 *  @brief Flush Messages Support Routine
302 *
303 *  This routine flushes all outstanding messages and returns
304 *  them to the inactive message chain.
305 *
306 *  @param[in] the_message_queue points to the message queue to flush
307 *
308 *  @return This method returns the number of message pending messages flushed.
309 */
310uint32_t   _CORE_message_queue_Flush_support(
311  CORE_message_queue_Control *the_message_queue
312);
313
314#if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
315  /**
316   *  @brief Flush Waiting Threads.
317   *
318   *  This function flushes the threads which are blocked on
319   *  @a the_message_queue's pending message queue.  They are
320   *  unblocked whether blocked sending or receiving.
321   *
322   *  @param[in] the_message_queue points to the message queue to flush
323   */
324  void _CORE_message_queue_Flush_waiting_threads(
325    CORE_message_queue_Control *the_message_queue
326  );
327#endif
328
329/**
330 *  @brief Broadcast a Message to the Message Queue
331 *
332 *  This function sends a message for every thread waiting on the queue and
333 *  returns the number of threads made ready by the message.
334 *
335 *  @param[in] the_message_queue points to the message queue
336 *  @param[in] buffer is the starting address of the message to broadcast
337 *  @param[in] size is the size of the message being broadcast
338 *  @param[in] id is the RTEMS object Id associated with this message queue.
339 *         It is used when unblocking a remote thread.
340 *  @param[in] api_message_queue_mp_support is the routine to invoke if
341 *         a thread that is unblocked is actually a remote thread.
342 *  @param[out] count points to the variable that will contain the
343 *         number of tasks that are sent this message
344 *  @return @a *count will contain the number of messages sent
345 *  @return indication of the successful completion or reason for failure
346 */
347CORE_message_queue_Status _CORE_message_queue_Broadcast(
348  CORE_message_queue_Control                *the_message_queue,
349  const void                                *buffer,
350  size_t                                     size,
351  Objects_Id                                 id,
352  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
353  uint32_t                                  *count
354);
355
356/**
357 *  @brief Submit a Message to the Message Queue
358 *
359 *  This routine implements the send and urgent message functions. It
360 *  processes a message that is to be submitted to the designated
361 *  message queue.  The message will either be processed as a
362 *  send message which it will be inserted at the rear of the queue
363 *  or it will be processed as an urgent message which will be inserted
364 *  at the front of the queue.
365 *
366 *  @param[in] the_message_queue points to the message queue
367 *  @param[in] buffer is the starting address of the message to send
368 *  @param[in] size is the size of the message being send
369 *  @param[in] id is the RTEMS object Id associated with this message queue.
370 *         It is used when unblocking a remote thread.
371 *  @param[in] api_message_queue_mp_support is the routine to invoke if
372 *         a thread that is unblocked is actually a remote thread.
373 *  @param[in] submit_type determines whether the message is prepended,
374 *         appended, or enqueued in priority order.
375 *  @param[in] wait indicates whether the calling thread is willing to block
376 *         if the message queue is full.
377 *  @param[in] timeout is the maximum number of clock ticks that the calling
378 *         thread is willing to block if the message queue is full.
379 *  @return indication of the successful completion or reason for failure
380 */
381CORE_message_queue_Status _CORE_message_queue_Submit(
382  CORE_message_queue_Control                *the_message_queue,
383  const void                                *buffer,
384  size_t                                     size,
385  Objects_Id                                 id,
386  CORE_message_queue_API_mp_support_callout  api_message_queue_mp_support,
387  CORE_message_queue_Submit_types            submit_type,
388  bool                                       wait,
389  Watchdog_Interval                          timeout
390);
391
392/**
393 *  @brief Size a Message from the Message Queue
394 *
395 *  This kernel routine dequeues a message, copies the message buffer to
396 *  a given destination buffer, and frees the message buffer to the
397 *  inactive message pool.  The thread will be blocked if wait is true,
398 *  otherwise an error will be given to the thread if no messages are available.
399 *
400 *  @param[in] the_message_queue points to the message queue
401 *  @param[in] id is the RTEMS object Id associated with this message queue.
402 *         It is used when unblocking a remote thread.
403 *  @param[in] buffer is the starting address of the message buffer to
404 *         to be filled in with a message
405 *  @param[in] size is the size of the @a buffer and indicates the maximum
406 *         size message that the caller can receive.
407 *  @param[in] wait indicates whether the calling thread is willing to block
408 *         if the message queue is empty.
409 *  @param[in] timeout is the maximum number of clock ticks that the calling
410 *         thread is willing to block if the message queue is empty.
411 *
412 *  @return indication of the successful completion or reason for failure
413 *  @note Returns message priority via return are in TCB.
414 */
415void _CORE_message_queue_Seize(
416  CORE_message_queue_Control      *the_message_queue,
417  Objects_Id                       id,
418  void                            *buffer,
419  size_t                          *size_p,
420  bool                             wait,
421  Watchdog_Interval                timeout
422);
423
424/**
425 *  This kernel routine inserts the specified message into the
426 *  message queue.  It is assumed that the message has been filled
427 *  in before this routine is called.
428 *
429 *  @param[in] the_message_queue points to the message queue
430 *  @param[in] the_message is the message to enqueue
431 *  @param[in] submit_type determines whether the message is prepended,
432 *         appended, or enqueued in priority order.
433 */
434void _CORE_message_queue_Insert_message(
435  CORE_message_queue_Control        *the_message_queue,
436  CORE_message_queue_Buffer_control *the_message,
437  CORE_message_queue_Submit_types    submit_type
438);
439
440#ifndef __RTEMS_APPLICATION__
441#include <rtems/score/coremsg.inl>
442#endif
443
444#ifdef __cplusplus
445}
446#endif
447
448/**@}*/
449
450#endif
451/*  end of include file */
Note: See TracBrowser for help on using the repository browser.