32232c56e018d3e2d487bddfb318fc840a50a96c
[bertos.git] / 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  *  PROC_DEFINE_STACK(sender_stack, KERN_MINSTACKSIZE);
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  * $WIZ$ module_name = "msg"
179  * $WIZ$ module_depends = "event", "signal", "kernel"
180  */
181
182
183 #ifndef KERN_MSG_H
184 #define KERN_MSG_H
185
186 #include <mware/event.h>
187 #include <struct/list.h>
188 #include <kern/proc.h>
189
190 typedef struct MsgPort
191 {
192         List  queue;   /**< Messages queued at this port. */
193         Event event;   /**< Event to trigger when a message arrives. */
194 } MsgPort;
195
196
197 typedef struct Msg
198 {
199         Node     link;      /**< Link into message port queue. */
200         MsgPort *replyPort; /**< Port to which the msg is to be replied. */
201         /* User data may follow */
202 } Msg;
203
204
205 /**
206  * Lock a message port.
207  *
208  * This is required before reading or manipulating
209  * any field of the MsgPort structure.
210  *
211  * \note Ports may be locked multiple times and each
212  *       call to msg_lockPort() must be paired with
213  *       a corresponding call to msg_unlockPort().
214  *
215  * \todo Add a configurable policy for locking against
216  *       interrupts and locking with semaphorse.
217  *
218  * \see msg_unlockPort()
219  */
220 INLINE void msg_lockPort(UNUSED_ARG(MsgPort *, port))
221 {
222         proc_forbid();
223 }
224
225 /**
226  * Unlock a message port.
227  *
228  * \see msg_lockPort()
229  */
230 INLINE void msg_unlockPort(UNUSED_ARG(MsgPort *, port))
231 {
232         proc_permit();
233 }
234
235
236 /** Initialize a message port */
237 INLINE void msg_initPort(MsgPort *port, Event event)
238 {
239         LIST_INIT(&port->queue);
240         port->event = event;
241 }
242
243 /** Queue \a msg into \a port, triggering the associated event */
244 INLINE void msg_put(MsgPort *port, Msg *msg)
245 {
246         msg_lockPort(port);
247         ADDTAIL(&port->queue, &msg->link);
248         msg_unlockPort(port);
249
250         event_do(&port->event);
251 }
252
253 /**
254  * Get the first message from the queue of \a port.
255  *
256  * \return Pointer to the message or NULL if the port was empty.
257  */
258 INLINE Msg *msg_get(MsgPort *port)
259 {
260         Msg *msg;
261
262         msg_lockPort(port);
263         msg = (Msg *)list_remHead(&port->queue);
264         msg_unlockPort(port);
265
266         return msg;
267 }
268
269 /** Peek the first message in the queue of \a port, or NULL if the port is empty. */
270 INLINE Msg *msg_peek(MsgPort *port)
271 {
272         Msg *msg;
273
274         msg_lockPort(port);
275         msg = (Msg *)port->queue.head.succ;
276         if (LIST_EMPTY(&port->queue))
277                 msg = NULL;
278         msg_unlockPort(port);
279
280         return msg;
281 }
282
283 /** Send back (reply) \a msg to its sender. */
284 INLINE void msg_reply(Msg *msg)
285 {
286         msg_put(msg->replyPort, msg);
287 }
288
289 int msg_testRun(void);
290 int msg_testSetup(void);
291 int msg_testTearDown(void);
292
293 #endif /* KERN_MSG_H */