Fix the bug related to the empty version list
[bertos.git] / bertos / kern / msg.h
1 /**
2  * \file
3  * <!--
4  * This file is part of BeRTOS.
5  *
6  * Bertos is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
19  *
20  * As a special exception, you may use this file as part of a free software
21  * library without restriction.  Specifically, if other files instantiate
22  * templates or use macros or inline functions from this file, or you compile
23  * this file and link it with other files to produce an executable, this
24  * file does not by itself cause the resulting executable to be covered by
25  * the GNU General Public License.  This exception does not however
26  * invalidate any other reasons why the executable file might be covered by
27  * the GNU General Public License.
28  *
29  * Copyright 2004 Develer S.r.l. (http://www.develer.com/)
30  * Copyright 1999,2001 Bernie Innocenti <bernie@codewiz.org>
31  *
32  * -->
33  *
34  *
35  * This module implements a common system for executing
36  * a user defined action calling a hook function.
37  *
38  * \version $Id$
39  *
40  * \author Bernie Innocenti <bernie@codewiz.org>
41  *
42  * \brief Simple inter-process messaging system
43  *
44  * Handle queues of messages associated an action.
45  *
46  * A message port is an abstraction used to exchange information
47  * asynchronously between processes or other entities such as
48  * interrupts and call-back functions.
49  *
50  * This form of IPC is higher-level than bare signals and
51  * semaphores, because it sets a policy for exchanging
52  * structured data with well-defined synchronization and
53  * ownership semantics.
54  *
55  * Before using it, a message port must be initialized by
56  * calling msg_initPort(), which associates the port with
57  * an Event object, which can be setup to signal a process
58  * or invoke a call-back hook.
59  *
60  * A process or interrupt routine can deliver messages to any
61  * message port by calling msg_put().  By sending a message,
62  * the sender temporarly or permanently transfers ownership
63  * of its associated data to the receiver.
64  *
65  * Queuing a message to a port automatically triggers the
66  * associated Event to notify the receiver.  When the
67  * receiver wakes up, it usually invokes msg_get() to pick
68  * the next message from the port.
69  *
70  * Message ports can hold any number of pending messages,
71  * and receivers usually process them in FIFO order.
72  * Other scheduling policies are possible, but not implemented
73  * in this API.
74  *
75  * After the receiver has done processing a message, it replies
76  * it back to the sender with msg_reply(), which transfer
77  * ownership back to the original sender.  Replies are delivered
78  * to a reply port, which is nothing more than another MsgPort
79  * structure designated by the sender.
80  *
81  * Returning messages to senders is not mandatory, but it provides
82  * a convenient way to provide some kind of result and simplify
83  * the resource allocation scheme at the same time.
84  *
85  * When using signals to receive messages in a process, you
86  * call sig_wait() in an event-loop to wake up when messages
87  * are delivered to any of your ports.  When your process
88  * wakes up with the port signal active, multiple messages
89  * may already have queued up at the message port, and the
90  * process must process them all before returning to sleep.
91  * Signals don't keep a nesting count.
92  *
93  * A simple message loop works like this:
94  *
95  * \code
96  *      // Our message port.
97  *      static MsgPort test_port;
98  *
99  *      // A test message with two parameters and a result.
100  *      typedef struct
101  *      {
102  *              Msg msg;
103  *
104  *              int x, y;
105  *              int result;
106  *      } TestMsg;
107  *
108  *
109  *  static cpu_stack_t sender_stack[CONFIG_KERN_MINSTACKSIZE / sizeof(cpu_stack_t)];
110  *
111  *      // A process that sends two messages and waits for replies.
112  *      static void sender_proc(void)
113  *      {
114  *              MsgPort test_reply_port;
115  *              TestMsg msg1;
116  *              TestMsg msg2;
117  *              Msg *reply;
118  *
119  *              msg_initPort(&test_reply_port,
120  *                      event_createSignal(proc_current(), SIG_SINGLE);
121  *
122  *              // Fill-in first message and send it out.
123  *              msg1.x = 3;
124  *              msg1.y = 2;
125  *              msg1.msg.replyPort = &test_reply_port;
126  *              msg_put(&test_port, &msg1.msg);
127  *
128  *              // Fill-in second message and send it out too.
129  *              msg2.x = 5;
130  *              msg2.y = 4;
131  *              msg2.msg.replyPort = &test_reply_port;
132  *              msg_put(&test_port, &msg2.msg);
133  *
134  *              // Wait for a reply...
135  *              sig_wait(SIG_SINGLE);
136  *
137         reply = containerof(msg_get(&test_reply_port), TestMsg, msg);
138  *              ASSERT(reply != NULL);
139  *              ASSERT(reply->result == 5);
140  *
141  *              // Get reply to second message.
142  *              while (!(reply = containerof(msg_get(&test_reply_port), TestMsg, msg)))
143  *              {
144  *                      // Not yet, be patient and wait some more.
145  *                      sig_wait(SIG_SINGLE);
146  *              }
147  *
148  *              ASSERT(reply->result == 9);
149  *      }
150  *
151  *
152  *      // Receive messages and do something boring with them.
153  *      static void receiver_proc(void)
154  *      {
155  *              msg_initPort(&test_port,
156  *                      event_createSignal(proc_current(), SIG_EXAMPLE);
157  *
158  *              proc_new(sender_proc, NULL,sizeof(sender_stack), sender_stack);
159  *
160  *              for (;;)
161  *              {
162  *                      sigmask_t sigs = sig_wait(SIG_EXAMPLE | more_signals);
163  *
164  *                      if (sigs & SIG_EXAMPLE)
165  *                      {
166  *                              TestMsg *emsg;
167  *                              while((emsg = containerof(msg_get(&test_port), TestMsg, msg)))
168  *                              {
169  *                                      // Do something with the message
170  *                                      emsg->result = emsg->x + emsg->y;
171  *                                      msg_reply(emsg->msg);
172  *                              }
173  *                      }
174  *              }
175  *      }
176  * \endcode
177  */
178
179
180 #ifndef KERN_MSG_H
181 #define KERN_MSG_H
182
183 #include <mware/event.h>
184 #include <struct/list.h>
185 #include <kern/proc.h>
186
187 typedef struct MsgPort
188 {
189         List  queue;   /**< Messages queued at this port. */
190         Event event;   /**< Event to trigger when a message arrives. */
191 } MsgPort;
192
193
194 typedef struct Msg
195 {
196         Node     link;      /**< Link into message port queue. */
197         MsgPort *replyPort; /**< Port to which the msg is to be replied. */
198         /* User data may follow */
199 } Msg;
200
201
202 /**
203  * Lock a message port.
204  *
205  * This is required before reading or manipulating
206  * any field of the MsgPort structure.
207  *
208  * \note Ports may be locked multiple times and each
209  *       call to msg_lockPort() must be paired with
210  *       a corresponding call to msg_unlockPort().
211  *
212  * \todo Add a configurable policy for locking against
213  *       interrupts and locking with semaphorse.
214  *
215  * \see msg_unlockPort()
216  */
217 INLINE void msg_lockPort(UNUSED_ARG(MsgPort *, port))
218 {
219         proc_forbid();
220 }
221
222 /**
223  * Unlock a message port.
224  *
225  * \see msg_lockPort()
226  */
227 INLINE void msg_unlockPort(UNUSED_ARG(MsgPort *, port))
228 {
229         proc_permit();
230 }
231
232
233 /** Initialize a message port */
234 INLINE void msg_initPort(MsgPort *port, Event event)
235 {
236         LIST_INIT(&port->queue);
237         port->event = event;
238 }
239
240 /** Queue \a msg into \a port, triggering the associated event */
241 INLINE void msg_put(MsgPort *port, Msg *msg)
242 {
243         msg_lockPort(port);
244         ADDTAIL(&port->queue, &msg->link);
245         msg_unlockPort(port);
246
247         event_do(&port->event);
248 }
249
250 /**
251  * Get the first message from the queue of \a port.
252  *
253  * \return Pointer to the message or NULL if the port was empty.
254  */
255 INLINE Msg *msg_get(MsgPort *port)
256 {
257         Msg *msg;
258
259         msg_lockPort(port);
260         msg = (Msg *)list_remHead(&port->queue);
261         msg_unlockPort(port);
262
263         return msg;
264 }
265
266 /** Peek the first message in the queue of \a port, or NULL if the port is empty. */
267 INLINE Msg *msg_peek(MsgPort *port)
268 {
269         Msg *msg;
270
271         msg_lockPort(port);
272         msg = (Msg *)port->queue.head.succ;
273         if (LIST_EMPTY(&port->queue))
274                 msg = NULL;
275         msg_unlockPort(port);
276
277         return msg;
278 }
279
280 /** Send back (reply) \a msg to its sender. */
281 INLINE void msg_reply(Msg *msg)
282 {
283         msg_put(msg->replyPort, msg);
284 }
285
286 int msg_testRun(void);
287 int msg_testSetup(void);
288 int msg_testTearDown(void);
289
290 #endif /* KERN_MSG_H */