Contiki 2.6

process.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (c) 2005, Swedish Institute of Computer Science
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the Institute nor the names of its contributors
00014  *    may be used to endorse or promote products derived from this software
00015  *    without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00018  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00021  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00023  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00024  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00025  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00026  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00027  * SUCH DAMAGE.
00028  *
00029  * This file is part of the Contiki operating system.
00030  *
00031  * @(#)$Id: process.h,v 1.17 2010/09/14 18:55:04 dak664 Exp $
00032  */
00033 
00034 /**
00035  * \addtogroup sys
00036  * @{
00037  */
00038 
00039 /**
00040  * \defgroup process Contiki processes
00041  *
00042  * A process in Contiki consists of a single \ref pt "protothread".
00043  *
00044  * @{
00045  */
00046 
00047 /**
00048  * \file
00049  * Header file for the Contiki process interface.
00050  * \author
00051  * Adam Dunkels <adam@sics.se>
00052  *
00053  */
00054 #ifndef __PROCESS_H__
00055 #define __PROCESS_H__
00056 
00057 #include "sys/pt.h"
00058 #include "sys/cc.h"
00059 
00060 typedef unsigned char process_event_t;
00061 typedef void *        process_data_t;
00062 typedef unsigned char process_num_events_t;
00063 
00064 /**
00065  * \name Return values
00066  * @{
00067  */
00068 
00069 /**
00070  * \brief      Return value indicating that an operation was successful.
00071  *
00072  *             This value is returned to indicate that an operation
00073  *             was successful.
00074  */
00075 #define PROCESS_ERR_OK        0
00076 /**
00077  * \brief      Return value indicating that the event queue was full.
00078  *
00079  *             This value is returned from process_post() to indicate
00080  *             that the event queue was full and that an event could
00081  *             not be posted.
00082  */
00083 #define PROCESS_ERR_FULL      1
00084 /* @} */
00085 
00086 #define PROCESS_NONE          NULL
00087 
00088 #ifndef PROCESS_CONF_NUMEVENTS
00089 #define PROCESS_CONF_NUMEVENTS 32
00090 #endif /* PROCESS_CONF_NUMEVENTS */
00091 
00092 #define PROCESS_EVENT_NONE            0x80
00093 #define PROCESS_EVENT_INIT            0x81
00094 #define PROCESS_EVENT_POLL            0x82
00095 #define PROCESS_EVENT_EXIT            0x83
00096 #define PROCESS_EVENT_SERVICE_REMOVED 0x84
00097 #define PROCESS_EVENT_CONTINUE        0x85
00098 #define PROCESS_EVENT_MSG             0x86
00099 #define PROCESS_EVENT_EXITED          0x87
00100 #define PROCESS_EVENT_TIMER           0x88
00101 #define PROCESS_EVENT_COM             0x89
00102 #define PROCESS_EVENT_MAX             0x8a
00103 
00104 #define PROCESS_BROADCAST NULL
00105 #define PROCESS_ZOMBIE ((struct process *)0x1)
00106 
00107 /**
00108  * \name Process protothread functions
00109  * @{
00110  */
00111 
00112 /**
00113  * Define the beginning of a process.
00114  *
00115  * This macro defines the beginning of a process, and must always
00116  * appear in a PROCESS_THREAD() definition. The PROCESS_END() macro
00117  * must come at the end of the process.
00118  *
00119  * \hideinitializer
00120  */
00121 #define PROCESS_BEGIN()             PT_BEGIN(process_pt)
00122 
00123 /**
00124  * Define the end of a process.
00125  *
00126  * This macro defines the end of a process. It must appear in a
00127  * PROCESS_THREAD() definition and must always be included. The
00128  * process exits when the PROCESS_END() macro is reached.
00129  *
00130  * \hideinitializer
00131  */
00132 #define PROCESS_END()               PT_END(process_pt)
00133 
00134 /**
00135  * Wait for an event to be posted to the process.
00136  *
00137  * This macro blocks the currently running process until the process
00138  * receives an event.
00139  *
00140  * \hideinitializer
00141  */
00142 #define PROCESS_WAIT_EVENT()        PROCESS_YIELD()
00143 
00144 /**
00145  * Wait for an event to be posted to the process, with an extra
00146  * condition.
00147  *
00148  * This macro is similar to PROCESS_WAIT_EVENT() in that it blocks the
00149  * currently running process until the process receives an event. But
00150  * PROCESS_WAIT_EVENT_UNTIL() takes an extra condition which must be
00151  * true for the process to continue.
00152  *
00153  * \param c The condition that must be true for the process to continue.
00154  * \sa PT_WAIT_UNTIL()
00155  *
00156  * \hideinitializer
00157  */
00158 #define PROCESS_WAIT_EVENT_UNTIL(c) PROCESS_YIELD_UNTIL(c)
00159 
00160 /**
00161  * Yield the currently running process.
00162  *
00163  * \hideinitializer
00164  */
00165 #define PROCESS_YIELD()             PT_YIELD(process_pt)
00166 
00167 /**
00168  * Yield the currently running process until a condition occurs.
00169  *
00170  * This macro is different from PROCESS_WAIT_UNTIL() in that
00171  * PROCESS_YIELD_UNTIL() is guaranteed to always yield at least
00172  * once. This ensures that the process does not end up in an infinite
00173  * loop and monopolizing the CPU.
00174  *
00175  * \param c The condition to wait for.
00176  *
00177  * \hideinitializer
00178  */
00179 #define PROCESS_YIELD_UNTIL(c)      PT_YIELD_UNTIL(process_pt, c)
00180 
00181 /**
00182  * Wait for a condition to occur.
00183  *
00184  * This macro does not guarantee that the process yields, and should
00185  * therefore be used with care. In most cases, PROCESS_WAIT_EVENT(),
00186  * PROCESS_WAIT_EVENT_UNTIL(), PROCESS_YIELD() or
00187  * PROCESS_YIELD_UNTIL() should be used instead.
00188  *
00189  * \param c The condition to wait for.
00190  *
00191  * \hideinitializer
00192  */
00193 #define PROCESS_WAIT_UNTIL(c)       PT_WAIT_UNTIL(process_pt, c)
00194 #define PROCESS_WAIT_WHILE(c)       PT_WAIT_WHILE(process_pt, c)
00195 
00196 /**
00197  * Exit the currently running process.
00198  *
00199  * \hideinitializer
00200  */
00201 #define PROCESS_EXIT()              PT_EXIT(process_pt)
00202 
00203 /**
00204  * Spawn a protothread from the process.
00205  *
00206  * \param pt The protothread state (struct pt) for the new protothread
00207  * \param thread The call to the protothread function.
00208  * \sa PT_SPAWN()
00209  *
00210  * \hideinitializer
00211  */
00212 #define PROCESS_PT_SPAWN(pt, thread)   PT_SPAWN(process_pt, pt, thread)
00213 
00214 /**
00215  * Yield the process for a short while.
00216  *
00217  * This macro yields the currently running process for a short while,
00218  * thus letting other processes run before the process continues.
00219  *
00220  * \hideinitializer
00221  */
00222 #define PROCESS_PAUSE()             do {                                \
00223   process_post(PROCESS_CURRENT(), PROCESS_EVENT_CONTINUE, NULL);        \
00224   PROCESS_WAIT_EVENT_UNTIL(ev == PROCESS_EVENT_CONTINUE);               \
00225 } while(0)
00226 
00227 /** @} end of protothread functions */
00228 
00229 /**
00230  * \name Poll and exit handlers
00231  * @{
00232  */
00233 /**
00234  * Specify an action when a process is polled.
00235  *
00236  * \note This declaration must come immediately before the
00237  * PROCESS_BEGIN() macro.
00238  *
00239  * \param handler The action to be performed.
00240  *
00241  * \hideinitializer
00242  */
00243 #define PROCESS_POLLHANDLER(handler) if(ev == PROCESS_EVENT_POLL) { handler; }
00244 
00245 /**
00246  * Specify an action when a process exits.
00247  *
00248  * \note This declaration must come immediately before the
00249  * PROCESS_BEGIN() macro.
00250  *
00251  * \param handler The action to be performed.
00252  *
00253  * \hideinitializer
00254  */
00255 #define PROCESS_EXITHANDLER(handler) if(ev == PROCESS_EVENT_EXIT) { handler; }
00256 
00257 /** @} */
00258 
00259 /**
00260  * \name Process declaration and definition
00261  * @{
00262  */
00263 
00264 /**
00265  * Define the body of a process.
00266  *
00267  * This macro is used to define the body (protothread) of a
00268  * process. The process is called whenever an event occurs in the
00269  * system, A process always start with the PROCESS_BEGIN() macro and
00270  * end with the PROCESS_END() macro.
00271  *
00272  * \hideinitializer
00273  */
00274 #define PROCESS_THREAD(name, ev, data)                          \
00275 static PT_THREAD(process_thread_##name(struct pt *process_pt,   \
00276                                        process_event_t ev,      \
00277                                        process_data_t data))
00278 
00279 /**
00280  * Declare the name of a process.
00281  *
00282  * This macro is typically used in header files to declare the name of
00283  * a process that is implemented in the C file.
00284  *
00285  * \hideinitializer
00286  */
00287 #define PROCESS_NAME(name) extern struct process name
00288 
00289 /**
00290  * Declare a process.
00291  *
00292  * This macro declares a process. The process has two names: the
00293  * variable of the process structure, which is used by the C program,
00294  * and a human readable string name, which is used when debugging.
00295  * A configuration option allows removal of the readable name to save RAM.
00296  *
00297  * \param name The variable name of the process structure.
00298  * \param strname The string representation of the process' name.
00299  *
00300  * \hideinitializer
00301  */
00302 #if PROCESS_CONF_NO_PROCESS_NAMES
00303 #define PROCESS(name, strname)                          \
00304   PROCESS_THREAD(name, ev, data);                       \
00305   struct process name = { NULL,                 \
00306                           process_thread_##name }
00307 #else
00308 #define PROCESS(name, strname)                          \
00309   PROCESS_THREAD(name, ev, data);                       \
00310   struct process name = { NULL, strname,                \
00311                           process_thread_##name }
00312 #endif
00313 
00314 /** @} */
00315 
00316 struct process {
00317   struct process *next;
00318 #if PROCESS_CONF_NO_PROCESS_NAMES
00319 #define PROCESS_NAME_STRING(process) ""
00320 #else
00321   const char *name;
00322 #define PROCESS_NAME_STRING(process) (process)->name
00323 #endif
00324   PT_THREAD((* thread)(struct pt *, process_event_t, process_data_t));
00325   struct pt pt;
00326   unsigned char state, needspoll;
00327 };
00328 
00329 /**
00330  * \name Functions called from application programs
00331  * @{
00332  */
00333 
00334 /**
00335  * Start a process.
00336  *
00337  * \param p A pointer to a process structure.
00338  *
00339  * \param arg An argument pointer that can be passed to the new
00340  * process
00341  *
00342  */
00343 CCIF void process_start(struct process *p, const char *arg);
00344 
00345 /**
00346  * Post an asynchronous event.
00347  *
00348  * This function posts an asynchronous event to one or more
00349  * processes. The handing of the event is deferred until the target
00350  * process is scheduled by the kernel. An event can be broadcast to
00351  * all processes, in which case all processes in the system will be
00352  * scheduled to handle the event.
00353  *
00354  * \param ev The event to be posted.
00355  *
00356  * \param data The auxiliary data to be sent with the event
00357  *
00358  * \param p The process to which the event should be posted, or
00359  * PROCESS_BROADCAST if the event should be posted to all processes.
00360  *
00361  * \retval PROCESS_ERR_OK The event could be posted.
00362  *
00363  * \retval PROCESS_ERR_FULL The event queue was full and the event could
00364  * not be posted.
00365  */
00366 CCIF int process_post(struct process *p, process_event_t ev, void* data);
00367 
00368 /**
00369  * Post a synchronous event to a process.
00370  *
00371  * \param p A pointer to the process' process structure.
00372  *
00373  * \param ev The event to be posted.
00374  *
00375  * \param data A pointer to additional data that is posted together
00376  * with the event.
00377  */
00378 CCIF void process_post_synch(struct process *p,
00379                              process_event_t ev, void* data);
00380 
00381 /**
00382  * \brief      Cause a process to exit
00383  * \param p    The process that is to be exited
00384  *
00385  *             This function causes a process to exit. The process can
00386  *             either be the currently executing process, or another
00387  *             process that is currently running.
00388  *
00389  * \sa PROCESS_CURRENT()
00390  */
00391 CCIF void process_exit(struct process *p);
00392 
00393 
00394 /**
00395  * Get a pointer to the currently running process.
00396  *
00397  * This macro get a pointer to the currently running
00398  * process. Typically, this macro is used to post an event to the
00399  * current process with process_post().
00400  *
00401  * \hideinitializer
00402  */
00403 #define PROCESS_CURRENT() process_current
00404 CCIF extern struct process *process_current;
00405 
00406 /**
00407  * Switch context to another process
00408  *
00409  * This function switch context to the specified process and executes
00410  * the code as if run by that process. Typical use of this function is
00411  * to switch context in services, called by other processes. Each
00412  * PROCESS_CONTEXT_BEGIN() must be followed by the
00413  * PROCESS_CONTEXT_END() macro to end the context switch.
00414  *
00415  * Example:
00416  \code
00417  PROCESS_CONTEXT_BEGIN(&test_process);
00418  etimer_set(&timer, CLOCK_SECOND);
00419  PROCESS_CONTEXT_END(&test_process);
00420  \endcode
00421  *
00422  * \param p    The process to use as context
00423  *
00424  * \sa PROCESS_CONTEXT_END()
00425  * \sa PROCESS_CURRENT()
00426  */
00427 #define PROCESS_CONTEXT_BEGIN(p) {\
00428 struct process *tmp_current = PROCESS_CURRENT();\
00429 process_current = p
00430 
00431 /**
00432  * End a context switch
00433  *
00434  * This function ends a context switch and changes back to the
00435  * previous process.
00436  *
00437  * \param p    The process used in the context switch
00438  *
00439  * \sa PROCESS_CONTEXT_START()
00440  */
00441 #define PROCESS_CONTEXT_END(p) process_current = tmp_current; }
00442 
00443 /**
00444  * \brief      Allocate a global event number.
00445  * \return     The allocated event number
00446  *
00447  *             In Contiki, event numbers above 128 are global and may
00448  *             be posted from one process to another. This function
00449  *             allocates one such event number.
00450  *
00451  * \note       There currently is no way to deallocate an allocated event
00452  *             number.
00453  */
00454 CCIF process_event_t process_alloc_event(void);
00455 
00456 /** @} */
00457 
00458 /**
00459  * \name Functions called from device drivers
00460  * @{
00461  */
00462 
00463 /**
00464  * Request a process to be polled.
00465  *
00466  * This function typically is called from an interrupt handler to
00467  * cause a process to be polled.
00468  *
00469  * \param p A pointer to the process' process structure.
00470  */
00471 CCIF void process_poll(struct process *p);
00472 
00473 /** @} */
00474 
00475 /**
00476  * \name Functions called by the system and boot-up code
00477  * @{
00478  */
00479 
00480 /**
00481  * \brief      Initialize the process module.
00482  *
00483  *             This function initializes the process module and should
00484  *             be called by the system boot-up code.
00485  */
00486 void process_init(void);
00487 
00488 /**
00489  * Run the system once - call poll handlers and process one event.
00490  *
00491  * This function should be called repeatedly from the main() program
00492  * to actually run the Contiki system. It calls the necessary poll
00493  * handlers, and processes one event. The function returns the number
00494  * of events that are waiting in the event queue so that the caller
00495  * may choose to put the CPU to sleep when there are no pending
00496  * events.
00497  *
00498  * \return The number of events that are currently waiting in the
00499  * event queue.
00500  */
00501 int process_run(void);
00502 
00503 
00504 /**
00505  * Check if a process is running.
00506  *
00507  * This function checks if a specific process is running.
00508  *
00509  * \param p The process.
00510  * \retval Non-zero if the process is running.
00511  * \retval Zero if the process is not running.
00512  */
00513 CCIF int process_is_running(struct process *p);
00514 
00515 /**
00516  *  Number of events waiting to be processed.
00517  *
00518  * \return The number of events that are currently waiting to be
00519  * processed.
00520  */
00521 int process_nevents(void);
00522 
00523 /** @} */
00524 
00525 CCIF extern struct process *process_list;
00526 
00527 #define PROCESS_LIST() process_list
00528 
00529 #endif /* __PROCESS_H__ */
00530 
00531 /** @} */
00532 /** @} */