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

4.104.115
Last change on this file since d81b56bd was d81b56bd, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 2, 2009 at 10:04:42 PM

2009-07-02 Joel Sherrill <joel.sherrill@…>

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