cooja_mt.h

00001 /*
00002  * Copyright (c) 2004, 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  * Author: Adam Dunkels <adam@sics.se>
00032  *
00033  * $Id: cooja_mt.h,v 1.1 2006/09/29 14:32:38 fros4943 Exp $
00034  */
00035 /*
00036  * This file is ripped from mt.h of the Contiki Multi-threading library.
00037  * Fredrik Osterlind <fros@sics.se>
00038  */
00039 #ifndef __COOJA_MT_H__
00040 #define __COOJA_MT_H__
00041 
00042 #include "contiki.h"
00043 
00044 
00045 /**
00046  * An opaque structure that is used for holding the state of a thread.
00047  *
00048  * The structure should be defined in the "mtarch.h" file. This
00049  * structure typically holds the entire stack for the thread.
00050  */
00051 struct cooja_mtarch_thread;
00052 
00053 /**
00054  * Initialize the architecture specific support functions for the
00055  * multi-thread library.
00056  *
00057  * This function is implemented by the architecture specific functions
00058  * for the multi-thread library and is called by the mt_init()
00059  * function as part of the initialization of the library. The
00060  * mtarch_init() function can be used for, e.g., starting preemtion
00061  * timers or other architecture specific mechanisms required for the
00062  * operation of the library.
00063  */
00064 void cooja_mtarch_init(void);
00065 
00066 /**
00067  * Uninstall library and clean up.
00068  *
00069  */
00070 void cooja_mtarch_remove(void);
00071 
00072 /**
00073  * Setup the stack frame for a thread that is being started.
00074  *
00075  * This function is called by the mt_start() function in order to set
00076  * up the architecture specific stack of the thread to be started.
00077  *
00078  * \param thread A pointer to a struct mtarch_thread for the thread to
00079  * be started.
00080  *
00081  * \param function A pointer to the function that the thread will
00082  * start executing the first time it is scheduled to run.
00083  *
00084  * \param data A pointer to the argument that the function should be
00085  * passed.
00086  */
00087 void cooja_mtarch_start(struct cooja_mtarch_thread *thread,
00088                   void (* function)(void *data),
00089                   void *data);
00090 
00091 /**
00092  * Yield the processor.
00093  *
00094  * This function is called by the mt_yield() function, which is called
00095  * from the running thread in order to give up the processor.
00096  *
00097  */
00098 void cooja_mtarch_yield(void);
00099 
00100 /**
00101  * Start executing a thread.
00102  *
00103  * This function is called from mt_exec() and the purpose of the
00104  * function is to start execution of the thread. The function should
00105  * switch in the stack of the thread, and does not return until the
00106  * thread has explicitly yielded (using mt_yield()) or until it is
00107  * preempted.
00108  *
00109  */
00110 void cooja_mtarch_exec(struct cooja_mtarch_thread *thread);
00111 
00112 
00113 /** @} */
00114 
00115 
00116 #include "cooja_mtarch.h"
00117 
00118 struct cooja_mt_thread {
00119   int state;
00120   process_event_t *evptr;
00121   process_data_t *dataptr;
00122   struct cooja_mtarch_thread thread;
00123 };
00124 
00125 /**
00126  * No error.
00127  *
00128  * \hideinitializer
00129  */
00130 #define MT_OK 1
00131 
00132 /**
00133  * Initializes the multithreading library.
00134  *
00135  */
00136 void cooja_mt_init(void);
00137 
00138 /**
00139  * Uninstalls library and cleans up.
00140  *
00141  */
00142 void cooja_mt_remove(void);
00143 
00144 
00145 /**
00146  * Starts a multithreading thread.
00147  *
00148  * \param thread Pointer to an mt_thread struct that must have been
00149  * previously allocated by the caller.
00150  *
00151  * \param function A pointer to the entry function of the thread that is
00152  * to be set up.
00153  *
00154  * \param data A pointer that will be passed to the entry function.
00155  *
00156  */
00157 void cooja_mt_start(struct cooja_mt_thread *thread, void (* function)(void *), void *data);
00158 
00159 /**
00160  * Execute parts of a thread.
00161  *
00162  * This function is called by a Contiki process and runs a
00163  * thread. The function does not return until the thread has yielded,
00164  * or is preempted.
00165  *
00166  * \note The thread must first be initialized with the mt_init() function.
00167  *
00168  * \param thread A pointer to a struct mt_thread block that must be
00169  * allocated by the caller.
00170  *
00171  */
00172 void cooja_mt_exec(struct cooja_mt_thread *thread);
00173 
00174 /**
00175  * Post an event to a thread.
00176  *
00177  * This function posts an event to a thread. The thread will be
00178  * scheduled if the thread currently is waiting for the posted event
00179  * number. If the thread is not waiting for the event, this function
00180  * does nothing.
00181  *
00182  * \note The thread must first be initialized with the mt_init() function.
00183  *
00184  * \param thread A pointer to a struct mt_thread block that must be
00185  * allocated by the caller.
00186  *
00187  * \param s The event that is posted to the thread.
00188  *
00189  * \param data An opaque pointer to a user specified structure
00190  * containing additonal information, or NULL if no additional
00191  * information is needed.
00192  */
00193 /*void mt_exec_event(struct mt_thread *thread, process_event_t s,
00194   process_data_t data);*/
00195 
00196 /**
00197  * Voluntarily give up the processor.
00198  *
00199  * This function is called by a running thread in order to give up
00200  * control of the CPU.
00201  *
00202  */
00203 void cooja_mt_yield(void);
00204 
00205 /**
00206  * Post an event to another process.
00207  *
00208  * This function is called by a running thread and will emit a signal
00209  * to another Contiki process. This will cause the currently executing
00210  * thread to yield.
00211  *
00212  * \param p The process receiving the signal, or PROCESS_BROADCAST
00213  * for a broadcast event.
00214  *
00215  * \param ev The event to be posted.
00216  *
00217  * \param data A pointer to a message that is to be delivered together
00218  * with the signal.
00219  *
00220  */
00221 /*void mt_post(struct process *p, process_event_t ev, process_data_t data);*/
00222 
00223 /**
00224  * Block and wait for an event to occur.
00225  *
00226  * This function can be called by a running thread in order to block
00227  * and wait for an event. The function returns when an event has
00228  * occured. The event number and the associated data are placed in the
00229  * variables pointed to by the function arguments.
00230  *
00231  * \param ev A pointer to a process_event_t variable. The variable
00232  * will be filled with the number event that woke the thread.
00233  *
00234  * \param data A pointer to a process_data_t variable. The variable
00235  * will be filled with the data associated with the event that woke
00236  * the thread.
00237  *
00238  */
00239 /*void mt_wait(process_event_t *ev, process_data_t *data);*/
00240 
00241 /**
00242  * Exit a thread.
00243  *
00244  * This function is called from within an executing thread in order to
00245  * exit the thread. The function never returns.
00246  *
00247  */
00248 void cooja_mt_exit(void);
00249 
00250 /** @} */
00251 /** @} */
00252 #endif /* __MT_H__ */

Generated on Mon Apr 11 14:23:43 2011 for Contiki 2.5 by  doxygen 1.6.1