Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Examples

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.1 2006/06/17 22:41:20 adamdunkels 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_MAX             0x89
00102 
00103 #define PROCESS_BROADCAST NULL
00104 #define PROCESS_ZOMBIE ((struct process *)0x1)
00105 
00106 /**
00107  * \name Process protothread functions
00108  * @{
00109  */
00110 
00111 /**
00112  * Define the beginning of a process.
00113  *
00114  * This macro defines the beginning of a process, and must always
00115  * appear in a PROCESS_THREAD() definition. The PROCESS_END() macro
00116  * must come at the end of the process.
00117  *
00118  * \hideinitializer
00119  */
00120 #define PROCESS_BEGIN()             PT_BEGIN(process_pt)
00121 
00122 /**
00123  * Define the end of a process.
00124  *
00125  * This macro defines the end of a process. It must appear in a
00126  * PROCESS_THREAD() definition and must always be included. The
00127  * process exits when the PROCESS_END() macro is reached.
00128  *
00129  * \hideinitializer
00130  */
00131 #define PROCESS_END()               PT_END(process_pt)
00132 
00133 /**
00134  * Wait for an event to be posted to the process.
00135  *
00136  * This macro blocks the currently running process until the process
00137  * receives an event.
00138  *
00139  * \hideinitializer
00140  */
00141 #define PROCESS_WAIT_EVENT()        PROCESS_YIELD()
00142 
00143 /**
00144  * Wait for an event to be posted to the process, with an extra
00145  * condition.
00146  *
00147  * This macro is similar to PROCESS_WAIT_EVENT() in that it blocks the
00148  * currently running process until the process receives an event. But
00149  * PROCESS_WAIT_EVENT_UNTIL() takes an extra condition which must be
00150  * true for the process to continue.
00151  *
00152  * \param c The condition that must be true for the process to continue.
00153  * \sa PT_WAIT_UNTIL()
00154  *
00155  * \hideinitializer
00156  */
00157 #define PROCESS_WAIT_EVENT_UNTIL(c) PROCESS_YIELD_UNTIL(c)
00158 
00159 /**
00160  * Yield the currently running process.
00161  *
00162  * \hideinitializer
00163  */
00164 #define PROCESS_YIELD()             PT_YIELD(process_pt)
00165 
00166 /**
00167  * Yield the currently running process until a condition occurs.
00168  *
00169  * This macro is different from PROCESS_WAIT_UNTIL() in that
00170  * PROCESS_YIELD_UNTIL() is guaranteed to always yield at least
00171  * once. This ensures that the process does not end up in an infinite
00172  * loop and monopolizing the CPU.
00173  *
00174  * \param c The condition to wait for.
00175  *
00176  * \hideinitializer
00177  */
00178 #define PROCESS_YIELD_UNTIL(c)      PT_YIELD_UNTIL(process_pt, c)
00179 
00180 /**
00181  * Wait for a condition to occur.
00182  *
00183  * This macro does not guarantee that the process yields, and should
00184  * therefore be used with care. In most cases, PROCESS_WAIT_EVENT(),
00185  * PROCESS_WAIT_EVENT_UNTIL(), PROCESS_YIELD() or
00186  * PROCESS_YIELD_UNTIL() should be used instead.
00187  *
00188  * \param c The condition to wait for.
00189  *
00190  * \hideinitializer
00191  */
00192 #define PROCESS_WAIT_UNTIL(c)       PT_WAIT_UNTIL(process_pt, c)
00193 
00194 /**
00195  * Exit the currently running process.
00196  *
00197  * \hideinitializer
00198  */
00199 #define PROCESS_EXIT()              PT_EXIT(process_pt)
00200 
00201 /**
00202  * Spawn a protothread from the process.
00203  *
00204  * \param pt The protothread state (struct pt) for the new protothread
00205  * \param thread The call to the protothread function.
00206  * \sa PT_SPAWN()
00207  *
00208  * \hideinitializer
00209  */
00210 #define PROCESS_SPAWN(pt, thread)   PT_SPAWN(process_pt, pt, thread)
00211 
00212 /**
00213  * Yield the process for a short while.
00214  *
00215  * This macro yields the currently running process for a short while,
00216  * thus letting other processes run before the process continues.
00217  *
00218  * \hideinitializer
00219  */
00220 #define PROCESS_PAUSE()             do {                                \
00221   process_post(PROCESS_CURRENT(), PROCESS_EVENT_CONTINUE, NULL);        \
00222   PROCESS_WAIT_EVENT();                                                 \
00223 } while(0)
00224 
00225 /** @} end of protothread functions */
00226 
00227 /**
00228  * \name Poll and exit handlers
00229  * @{
00230  */
00231 /**
00232  * Specify an action when a process is polled.
00233  *
00234  * \note This declaration must come immediately before the
00235  * PROCESS_BEGIN() macro.
00236  *
00237  * \param handler The action to be performed.
00238  *
00239  * \hideinitializer
00240  */
00241 #define PROCESS_POLLHANDLER(handler) if(ev == PROCESS_EVENT_POLL) { handler; }
00242 
00243 /**
00244  * Specify an action when a process exits.
00245  *
00246  * \note This declaration must come immediately before the
00247  * PROCESS_BEGIN() macro.
00248  *
00249  * \param handler The action to be performed.
00250  *
00251  * \hideinitializer
00252  */
00253 #define PROCESS_EXITHANDLER(handler) if(ev == PROCESS_EVENT_EXIT) { handler; }
00254 
00255 /** @} */
00256 
00257 /**
00258  * \name Process declaration and definion
00259  * @{
00260  */
00261 
00262 /**
00263  * Define the body of a process.
00264  *
00265  * This macro is used to define the body (protothread) of a
00266  * process. The process is called whenever an event occurs in the
00267  * system, A process always start with the PROCESS_BEGIN() macro and
00268  * end with the PROCESS_END() macro.
00269  *
00270  * \hideinitializer
00271  */
00272 #define PROCESS_THREAD(name, ev, data)                          \
00273 static PT_THREAD(process_thread_##name(struct pt *process_pt,   \
00274                                        process_event_t ev,      \
00275                                        process_data_t data))
00276 
00277 #if PROCESS_LOADABLE
00278 #define PROCESS_LOAD(name) const struct process *process_load = &name;
00279 #else  /* PROCESS_LOADABLE */
00280 #define PROCESS_LOAD(name)
00281 #endif /* PROCESS_LOADABLE */
00282 extern const struct process *process_load;
00283 
00284 /**
00285  * Declare the name of a process.
00286  *
00287  * This macro is typically used in header files to declare the name of
00288  * a process that is implemented in the C file.
00289  *
00290  * \hideinitializer
00291  */
00292 #define PROCESS_NAME(name) extern struct process name
00293 
00294 /**
00295  * Declare a process that should not be automatically loaded.
00296  *
00297  * This macro is similar to the PROCESS() declaration, with the
00298  * difference that for programs that are compiled as loadable
00299  * programs, processes declared with the PROCESS_NOLOAD() declaration
00300  * will not be automatically started when the program is loaded.
00301  *
00302  * \hideinitializer
00303  */
00304 #define PROCESS_NOLOAD(name, strname)                   \
00305   PROCESS_THREAD(name, ev, data);                       \
00306   struct process name = { NULL, strname,                \
00307                           process_thread_##name };
00308 /**
00309  * Declare a process.
00310  *
00311  * This macro declares a process. The process has two names: the
00312  * variable of the process structure, which is used by the C program,
00313  * and a human readable string name, which is used when debugging.
00314  *
00315  * \note For programs that are compiled as loadable programs: the
00316  * process declared with the PROCESS() declaration will be
00317  * automatically started when the program is loaded. The
00318  * PROCESS_NOLOAD() declaration can be used to declare a process that
00319  * shouldn't be automatically loaded.
00320  *
00321  * \param name The variable name of the process structure.
00322  * \param strname The string repressentation of the process' name.
00323  *
00324  * \hideinitializer
00325  */
00326 #define PROCESS(name, strname)                  \
00327   PROCESS_NOLOAD(name, strname);                \
00328   PROCESS_LOAD(name)
00329 
00330 /** @} */
00331 
00332 struct process {
00333   struct process *next;
00334   const char *name;
00335   PT_THREAD((* thread)(struct pt *, process_event_t, process_data_t));
00336   struct pt pt;
00337   unsigned char state;
00338 };
00339 
00340 /**
00341  * \name Functions called from application programs
00342  * @{
00343  */
00344 
00345 /**
00346  * Start a process.
00347  *
00348  * \param p A pointer to a process structure.
00349  *
00350  * \param arg An argument pointer that can be passed to the new
00351  * process
00352  *
00353  */
00354 void process_start(struct process *p, char *arg);
00355 
00356 /**
00357  * Post an asynchronous event.
00358  *
00359  * This function posts an asynchronous event to one or more
00360  * processes. The handing of the event is deferred until the target
00361  * process is scheduled by the kernel. An event can be broadcast to
00362  * all processes, in which case all processes in the system will be
00363  * scheduled to handle the event.
00364  *
00365  * \param ev The event to be posted.
00366  *
00367  * \param data The auxillary data to be sent with the event
00368  *
00369  * \param p The process to which the event should be posted, or
00370  * PROCESS_BROADCAST if the event should be posted to all processes.
00371  *
00372  * \retval PROCESS_ERR_OK The event could be posted.
00373  *
00374  * \retval PROCESS_ERR_FULL The event queue was full and the event could
00375  * not be posted.
00376  */
00377 int  process_post(struct process *p, process_event_t ev, process_data_t data);
00378 
00379 /**
00380  * Post a synchronous event to a process.
00381  *
00382  * \param p A pointer to the process' process structure.
00383  *
00384  * \param ev The event to be posted.
00385  *
00386  * \param data A pointer to additional data that is posted together
00387  * with the event.
00388  */
00389 void process_post_synch(struct process *p,
00390                         process_event_t ev, process_data_t data);
00391 
00392 /**
00393  * \brief      Cause a process to exit
00394  * \param p    The process that is to be exited
00395  *
00396  *             This function causes a process to exit. The process can
00397  *             either be the currently executing process, or another
00398  *             process that is currently running.
00399  *
00400  * \sa PROCESS_CURRENT()
00401  */
00402 void process_exit(struct process *p);
00403 
00404 
00405 /**
00406  * Get a pointer to the currently running process.
00407  *
00408  * This macro get a pointer to the currently running
00409  * process. Typically, this macro is used to post an event to the
00410  * current process with process_post().
00411  *
00412  * \hideinitializer
00413  */
00414 #define PROCESS_CURRENT() process_current
00415 extern struct process *process_current;
00416 
00417 #define PROCESS_SET_FLAGS(flags)
00418 #define PROCESS_NO_BROADCAST
00419 
00420 /**
00421  * Switch context to another process
00422  *
00423  * This function switch context to the specified process and executes
00424  * the code as if run by that process. Typical use of this function is
00425  * to switch context in services, called by other processes. Each
00426  * PROCESS_CONTEXT_BEGIN() must be followed by the
00427  * PROCESS_CONTEXT_END() macro to end the context switch.
00428  *
00429  * Example:
00430  \code
00431  PROCESS_CONTEXT_BEGIN(&test_process);
00432  etimer_set(&timer, CLOCK_SECOND);
00433  PROCESS_CONTEXT_END(&test_process);
00434  \endcode
00435  *
00436  * \param p    The process to use as context
00437  *
00438  * \sa PROCESS_CONTEXT_END()
00439  * \sa PROCESS_CURRENT()
00440  */
00441 #define PROCESS_CONTEXT_BEGIN(p) {\
00442 struct process *tmp_current = PROCESS_CURRENT();\
00443 process_current = p
00444 
00445 /**
00446  * End a context switch
00447  *
00448  * This function ends a context switch and changes back to the
00449  * previous process.
00450  *
00451  * \param p    The process used in the context switch
00452  *
00453  * \sa PROCESS_CONTEXT_START()
00454  */
00455 #define PROCESS_CONTEXT_END(p) process_current = tmp_current; }
00456 
00457 /**
00458  * \brief      Allocate a global event number.
00459  * \return     The allocated event number
00460  *
00461  *             In Contiki, event numbers above 128 are global and may
00462  *             be posted from one process to another. This function
00463  *             allocates one such event number.
00464  *
00465  * \note       There currently is no way to deallocate an allocated event
00466  *             number.
00467  */
00468 process_event_t process_alloc_event(void);
00469 
00470 /** @} */
00471 
00472 /**
00473  * \name Functions called from device drivers
00474  * @{
00475  */
00476 
00477 /**
00478  * Request a process to be polled.
00479  *
00480  * This function typically is called from an interrupt handler to
00481  * cause a process to be polled.
00482  *
00483  * \param p A pointer to the process' process structure.
00484  */
00485 void process_poll(struct process *p);
00486 
00487 /** @} */
00488 
00489 /**
00490  * \name Functions called by the system and boot-up code
00491  * @{
00492  */
00493 
00494 /**
00495  * \brief      Initialize the process module.
00496  *
00497  *             This function initializes the process module and should
00498  *             be called by the system boot-up code.
00499  */
00500 void process_init(void);
00501 
00502 /**
00503  * Run the system once - call poll handlers and process one event.
00504  *
00505  * This function should be called repeatedly from the main() program
00506  * to actuall run the Contiki system. It calls the necessary poll
00507  * handlers, and processes one event. The function returns the number
00508  * of events that are waiting in the event queue so that the caller
00509  * may choose to put the CPU to sleep when there are no pending
00510  * events.
00511  *
00512  * \return The number of events that are currently waiting in the
00513  * event queue.
00514  */
00515 int process_run(void);
00516 
00517 /** @} */
00518 
00519 extern struct process *process_list;
00520 
00521 #define PROCESS_LIST() process_list
00522 
00523 #endif /* __PROCESS_H__ */
00524 
00525 /** @} */
00526 /** @} */

Generated on Thu Jun 22 17:45:43 2006 for Contiki 2.x by  doxygen 1.4.4