Contiki-NG
process.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2005, Swedish Institute of Computer Science
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  */
32 
33 /**
34  * \addtogroup threads
35  * @{
36  */
37 
38 /**
39  * \defgroup process Contiki processes
40  *
41  * A process in Contiki consists of a single protothread.
42  *
43  * @{
44  */
45 
46 /**
47  * \file
48  * Header file for the Contiki process interface.
49  * \author
50  * Adam Dunkels <adam@sics.se>
51  *
52  */
53 #ifndef PROCESS_H_
54 #define PROCESS_H_
55 
56 #include "sys/pt.h"
57 #include "sys/cc.h"
58 
59 typedef unsigned char process_event_t;
60 typedef void * process_data_t;
61 typedef unsigned char process_num_events_t;
62 
63 /**
64  * \name Return values
65  * @{
66  */
67 
68 /**
69  * \brief Return value indicating that an operation was successful.
70  *
71  * This value is returned to indicate that an operation
72  * was successful.
73  */
74 #define PROCESS_ERR_OK 0
75 /**
76  * \brief Return value indicating that the event queue was full.
77  *
78  * This value is returned from process_post() to indicate
79  * that the event queue was full and that an event could
80  * not be posted.
81  */
82 #define PROCESS_ERR_FULL 1
83 /* @} */
84 
85 #define PROCESS_NONE NULL
86 
87 #ifndef PROCESS_CONF_NUMEVENTS
88 #define PROCESS_CONF_NUMEVENTS 32
89 #endif /* PROCESS_CONF_NUMEVENTS */
90 
91 #define PROCESS_EVENT_NONE 0x80
92 #define PROCESS_EVENT_INIT 0x81
93 #define PROCESS_EVENT_POLL 0x82
94 #define PROCESS_EVENT_EXIT 0x83
95 #define PROCESS_EVENT_SERVICE_REMOVED 0x84
96 #define PROCESS_EVENT_CONTINUE 0x85
97 #define PROCESS_EVENT_MSG 0x86
98 #define PROCESS_EVENT_EXITED 0x87
99 #define PROCESS_EVENT_TIMER 0x88
100 #define PROCESS_EVENT_COM 0x89
101 #define PROCESS_EVENT_MAX 0x8a
102 
103 #define PROCESS_BROADCAST NULL
104 #define PROCESS_ZOMBIE ((struct process *)0x1)
105 
106 /**
107  * \name Process protothread functions
108  * @{
109  */
110 
111 /**
112  * Define the beginning of a process.
113  *
114  * This macro defines the beginning of a process, and must always
115  * appear in a PROCESS_THREAD() definition. The PROCESS_END() macro
116  * must come at the end of the process.
117  *
118  * \hideinitializer
119  */
120 #define PROCESS_BEGIN() PT_BEGIN(process_pt)
121 
122 /**
123  * Define the end of a process.
124  *
125  * This macro defines the end of a process. It must appear in a
126  * PROCESS_THREAD() definition and must always be included. The
127  * process exits when the PROCESS_END() macro is reached.
128  *
129  * \hideinitializer
130  */
131 #define PROCESS_END() PT_END(process_pt)
132 
133 /**
134  * Wait for an event to be posted to the process.
135  *
136  * This macro blocks the currently running process until the process
137  * receives an event.
138  *
139  * \hideinitializer
140  */
141 #define PROCESS_WAIT_EVENT() PROCESS_YIELD()
142 
143 /**
144  * Wait for an event to be posted to the process, with an extra
145  * condition.
146  *
147  * This macro is similar to PROCESS_WAIT_EVENT() in that it blocks the
148  * currently running process until the process receives an event. But
149  * PROCESS_WAIT_EVENT_UNTIL() takes an extra condition which must be
150  * true for the process to continue.
151  *
152  * \param c The condition that must be true for the process to continue.
153  * \sa PT_WAIT_UNTIL()
154  *
155  * \hideinitializer
156  */
157 #define PROCESS_WAIT_EVENT_UNTIL(c) PROCESS_YIELD_UNTIL(c)
158 
159 /**
160  * Yield the currently running process.
161  *
162  * \hideinitializer
163  */
164 #define PROCESS_YIELD() PT_YIELD(process_pt)
165 
166 /**
167  * Yield the currently running process until a condition occurs.
168  *
169  * This macro is different from PROCESS_WAIT_UNTIL() in that
170  * PROCESS_YIELD_UNTIL() is guaranteed to always yield at least
171  * once. This ensures that the process does not end up in an infinite
172  * loop and monopolizing the CPU.
173  *
174  * \param c The condition to wait for.
175  *
176  * \hideinitializer
177  */
178 #define PROCESS_YIELD_UNTIL(c) PT_YIELD_UNTIL(process_pt, c)
179 
180 /**
181  * Wait for a condition to occur.
182  *
183  * This macro does not guarantee that the process yields, and should
184  * therefore be used with care. In most cases, PROCESS_WAIT_EVENT(),
185  * PROCESS_WAIT_EVENT_UNTIL(), PROCESS_YIELD() or
186  * PROCESS_YIELD_UNTIL() should be used instead.
187  *
188  * \param c The condition to wait for.
189  *
190  * \hideinitializer
191  */
192 #define PROCESS_WAIT_UNTIL(c) PT_WAIT_UNTIL(process_pt, c)
193 #define PROCESS_WAIT_WHILE(c) PT_WAIT_WHILE(process_pt, c)
194 
195 /**
196  * Exit the currently running process.
197  *
198  * \hideinitializer
199  */
200 #define PROCESS_EXIT() PT_EXIT(process_pt)
201 
202 /**
203  * Spawn a protothread from the process.
204  *
205  * \param pt The protothread state (struct pt) for the new protothread
206  * \param thread The call to the protothread function.
207  * \sa PT_SPAWN()
208  *
209  * \hideinitializer
210  */
211 #define PROCESS_PT_SPAWN(pt, thread) PT_SPAWN(process_pt, pt, thread)
212 
213 /**
214  * Yield the process for a short while.
215  *
216  * This macro yields the currently running process for a short while,
217  * thus letting other processes run before the process continues.
218  *
219  * \hideinitializer
220  */
221 #define PROCESS_PAUSE() do { \
222  process_post(PROCESS_CURRENT(), PROCESS_EVENT_CONTINUE, NULL); \
223  PROCESS_WAIT_EVENT_UNTIL(ev == PROCESS_EVENT_CONTINUE); \
224 } while(0)
225 
226 /** @} end of protothread functions */
227 
228 /**
229  * \name Poll and exit handlers
230  * @{
231  */
232 /**
233  * Specify an action when a process is polled.
234  *
235  * \note This declaration must come immediately before the
236  * PROCESS_BEGIN() macro.
237  *
238  * \param handler The action to be performed.
239  *
240  * \hideinitializer
241  */
242 #define PROCESS_POLLHANDLER(handler) if(ev == PROCESS_EVENT_POLL) { handler; }
243 
244 /**
245  * Specify an action when a process exits.
246  *
247  * \note This declaration must come immediately before the
248  * PROCESS_BEGIN() macro.
249  *
250  * \param handler The action to be performed.
251  *
252  * \hideinitializer
253  */
254 #define PROCESS_EXITHANDLER(handler) if(ev == PROCESS_EVENT_EXIT) { handler; }
255 
256 /** @} */
257 
258 /**
259  * \name Process declaration and definition
260  * @{
261  */
262 
263 /**
264  * Define the body of a process.
265  *
266  * This macro is used to define the body (protothread) of a
267  * process. The process is called whenever an event occurs in the
268  * system, A process always start with the PROCESS_BEGIN() macro and
269  * end with the PROCESS_END() macro.
270  *
271  * \hideinitializer
272  */
273 #define PROCESS_THREAD(name, ev, data) \
274 static PT_THREAD(process_thread_##name(struct pt *process_pt, \
275  process_event_t ev, \
276  process_data_t data))
277 
278 /**
279  * Declare the name of a process.
280  *
281  * This macro is typically used in header files to declare the name of
282  * a process that is implemented in the C file.
283  *
284  * \hideinitializer
285  */
286 #define PROCESS_NAME(name) extern struct process name
287 
288 /**
289  * Declare a process.
290  *
291  * This macro declares a process. The process has two names: the
292  * variable of the process structure, which is used by the C program,
293  * and a human readable string name, which is used when debugging.
294  * A configuration option allows removal of the readable name to save RAM.
295  *
296  * \param name The variable name of the process structure.
297  * \param strname The string representation of the process' name.
298  *
299  * \hideinitializer
300  */
301 #if PROCESS_CONF_NO_PROCESS_NAMES
302 #define PROCESS(name, strname) \
303  PROCESS_THREAD(name, ev, data); \
304  struct process name = { NULL, \
305  process_thread_##name }
306 #else
307 #define PROCESS(name, strname) \
308  PROCESS_THREAD(name, ev, data); \
309  struct process name = { NULL, strname, \
310  process_thread_##name }
311 #endif
312 
313 /** @} */
314 
315 struct process {
316  struct process *next;
317 #if PROCESS_CONF_NO_PROCESS_NAMES
318 #define PROCESS_NAME_STRING(process) ""
319 #else
320  const char *name;
321 #define PROCESS_NAME_STRING(process) (process)->name
322 #endif
323  PT_THREAD((* thread)(struct pt *, process_event_t, process_data_t));
324  struct pt pt;
325  unsigned char state, needspoll;
326 };
327 
328 /**
329  * \name Functions called from application programs
330  * @{
331  */
332 
333 /**
334  * Start a process.
335  *
336  * \param p A pointer to a process structure.
337  *
338  * \param data An argument pointer that can be passed to the new
339  * process
340  *
341  */
342 void process_start(struct process *p, process_data_t data);
343 
344 /**
345  * Post an asynchronous event.
346  *
347  * This function posts an asynchronous event to one or more
348  * processes. The handing of the event is deferred until the target
349  * process is scheduled by the kernel. An event can be broadcast to
350  * all processes, in which case all processes in the system will be
351  * scheduled to handle the event.
352  *
353  * \param ev The event to be posted.
354  *
355  * \param data The auxiliary data to be sent with the event
356  *
357  * \param p The process to which the event should be posted, or
358  * PROCESS_BROADCAST if the event should be posted to all processes.
359  *
360  * \retval PROCESS_ERR_OK The event could be posted.
361  *
362  * \retval PROCESS_ERR_FULL The event queue was full and the event could
363  * not be posted.
364  */
365 int process_post(struct process *p, process_event_t ev, process_data_t data);
366 
367 /**
368  * Post a synchronous event to a process.
369  *
370  * \param p A pointer to the process' process structure.
371  *
372  * \param ev The event to be posted.
373  *
374  * \param data A pointer to additional data that is posted together
375  * with the event.
376  */
377 void process_post_synch(struct process *p,
378  process_event_t ev, process_data_t data);
379 
380 /**
381  * \brief Cause a process to exit
382  * \param p The process that is to be exited
383  *
384  * This function causes a process to exit. The process can
385  * either be the currently executing process, or another
386  * process that is currently running.
387  *
388  * \sa PROCESS_CURRENT()
389  */
390 void process_exit(struct process *p);
391 
392 
393 /**
394  * Get a pointer to the currently running process.
395  *
396  * This macro get a pointer to the currently running
397  * process. Typically, this macro is used to post an event to the
398  * current process with process_post().
399  *
400  * \hideinitializer
401  */
402 #define PROCESS_CURRENT() process_current
403 extern struct process *process_current;
404 
405 /**
406  * Switch context to another process
407  *
408  * This function switch context to the specified process and executes
409  * the code as if run by that process. Typical use of this function is
410  * to switch context in services, called by other processes. Each
411  * PROCESS_CONTEXT_BEGIN() must be followed by the
412  * PROCESS_CONTEXT_END() macro to end the context switch.
413  *
414  * Example:
415  \code
416  PROCESS_CONTEXT_BEGIN(&test_process);
417  etimer_set(&timer, CLOCK_SECOND);
418  PROCESS_CONTEXT_END(&test_process);
419  \endcode
420  *
421  * \param p The process to use as context
422  *
423  * \sa PROCESS_CONTEXT_END()
424  * \sa PROCESS_CURRENT()
425  */
426 #define PROCESS_CONTEXT_BEGIN(p) {\
427 struct process *tmp_current = PROCESS_CURRENT();\
428 process_current = p
429 
430 /**
431  * End a context switch
432  *
433  * This function ends a context switch and changes back to the
434  * previous process.
435  *
436  * \param p The process used in the context switch
437  *
438  * \sa PROCESS_CONTEXT_START()
439  */
440 #define PROCESS_CONTEXT_END(p) process_current = tmp_current; }
441 
442 /**
443  * \brief Allocate a global event number.
444  * \return The allocated event number
445  *
446  * In Contiki, event numbers above 128 are global and may
447  * be posted from one process to another. This function
448  * allocates one such event number.
449  *
450  * \note There currently is no way to deallocate an allocated event
451  * number.
452  */
453 process_event_t process_alloc_event(void);
454 
455 /** @} */
456 
457 /**
458  * \name Functions called from device drivers
459  * @{
460  */
461 
462 /**
463  * Request a process to be polled.
464  *
465  * This function typically is called from an interrupt handler to
466  * cause a process to be polled.
467  *
468  * \param p A pointer to the process' process structure.
469  */
470 void process_poll(struct process *p);
471 
472 /** @} */
473 
474 /**
475  * \name Functions called by the system and boot-up code
476  * @{
477  */
478 
479 /**
480  * \brief Initialize the process module.
481  *
482  * This function initializes the process module and should
483  * be called by the system boot-up code.
484  */
485 void process_init(void);
486 
487 /**
488  * Run the system once - call poll handlers and process one event.
489  *
490  * This function should be called repeatedly from the main() program
491  * to actually run the Contiki system. It calls the necessary poll
492  * handlers, and processes one event. The function returns the number
493  * of events that are waiting in the event queue so that the caller
494  * may choose to put the CPU to sleep when there are no pending
495  * events.
496  *
497  * \return The number of events that are currently waiting in the
498  * event queue.
499  */
500 int process_run(void);
501 
502 
503 /**
504  * Check if a process is running.
505  *
506  * This function checks if a specific process is running.
507  *
508  * \param p The process.
509  * \retval Non-zero if the process is running.
510  * \retval Zero if the process is not running.
511  */
512 int process_is_running(struct process *p);
513 
514 /**
515  * Number of events waiting to be processed.
516  *
517  * \return The number of events that are currently waiting to be
518  * processed.
519  */
520 int process_nevents(void);
521 
522 /** @} */
523 
524 extern struct process *process_list;
525 
526 #define PROCESS_LIST() process_list
527 
528 #endif /* PROCESS_H_ */
529 
530 /** @} */
531 /** @} */
void process_post_synch(struct process *p, process_event_t ev, process_data_t data)
Post a synchronous event to a process.
Definition: process.c:362
Protothreads implementation.
int process_is_running(struct process *p)
Check if a process is running.
Definition: process.c:383
void process_exit(struct process *p)
Cause a process to exit.
Definition: process.c:202
void process_init(void)
Initialize the process module.
Definition: process.c:208
void process_poll(struct process *p)
Request a process to be polled.
Definition: process.c:371
#define PT_THREAD(name_args)
Declaration of a protothread.
Definition: pt.h:99
process_event_t process_alloc_event(void)
Allocate a global event number.
Definition: process.c:93
int process_nevents(void)
Number of events waiting to be processed.
Definition: process.c:316
int process_post(struct process *p, process_event_t ev, process_data_t data)
Post an asynchronous event.
Definition: process.c:322
Default definitions of C compiler quirk work-arounds.
int process_run(void)
Run the system once - call poll handlers and process one event.
Definition: process.c:302
void process_start(struct process *p, process_data_t data)
Start a process.
Definition: process.c:99