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 /** @} */