Contiki 2.6

mt.h

Go to the documentation of this file.
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: mt.h,v 1.6 2008/10/14 12:46:39 nvt-se Exp $
00034  */
00035 
00036 /** \addtogroup sys
00037  * @{
00038  */
00039 
00040 /**
00041  * \defgroup mt Multi-threading library
00042  *
00043  * The event driven Contiki kernel does not provide multi-threading
00044  * by itself - instead, preemptive multi-threading is implemented
00045  * as a library that optionally can be linked with applications. This
00046  * library consists of two parts: a platform independent part, which is
00047  * the same for all platforms on which Contiki runs, and a platform
00048  * specific part, which must be implemented specifically for the
00049  * platform that the multi-threading library should run.
00050  *
00051  * @{
00052  */
00053 
00054 /**
00055  * \defgroup mtarch Architecture support for multi-threading
00056  * @{
00057  *
00058  * The Contiki multi-threading library requires some architecture
00059  * specific support for setting up and switching stacks. This support
00060  * requires four stack manipulation functions to be implemented:
00061  * mtarch_start(), which sets up the stack frame for a new thread,
00062  * mtarch_exec(), which switches in the stack of a thread,
00063  * mtarch_yield(), which restores the kernel stack from a thread's
00064  * stack and mtarch_stop(), which cleans up the stack of a thread.
00065  * Additionally, two functions for controlling the preemption
00066  * (if any) must be implemented: mtarch_pstart() and mtarch_pstop().
00067  * If no preemption is used, these functions can be implemented as
00068  * empty functions. Finally, the function mtarch_init() is called by
00069  * mt_init(), and can be used for initialization of timer interrupts,
00070  * or any other mechanisms required for correct operation of the
00071  * architecture specific support functions while mtarch_remove() is
00072  * called by mt_remove() to clean up those resources.
00073  *
00074  */
00075 
00076 /**
00077  * \file
00078  * Header file for the preemptive multitasking library for Contiki.
00079  * \author
00080  * Adam Dunkels <adam@sics.se>
00081  *
00082  */
00083 #ifndef __MT_H__
00084 #define __MT_H__
00085 
00086 #include "contiki.h"
00087 
00088 
00089 /**
00090  * An opaque structure that is used for holding the state of a thread.
00091  *
00092  * The structure should be defined in the "mtarch.h" file. This
00093  * structure typically holds the entire stack for the thread.
00094  */
00095 struct mtarch_thread;
00096 
00097 /**
00098  * Initialize the architecture specific support functions for the
00099  * multi-thread library.
00100  *
00101  * This function is implemented by the architecture specific functions
00102  * for the multi-thread library and is called by the mt_init()
00103  * function as part of the initialization of the library. The
00104  * mtarch_init() function can be used for, e.g., starting preemption
00105  * timers or other architecture specific mechanisms required for the
00106  * operation of the library.
00107  */
00108 void mtarch_init(void);
00109 
00110 /**
00111  * Uninstall library and clean up.
00112  *
00113  */
00114 void mtarch_remove(void);
00115 
00116 /**
00117  * Setup the stack frame for a thread that is being started.
00118  *
00119  * This function is called by the mt_start() function in order to set
00120  * up the architecture specific stack of the thread to be started.
00121  *
00122  * \param thread A pointer to a struct mtarch_thread for the thread to
00123  * be started.
00124  *
00125  * \param function A pointer to the function that the thread will
00126  * start executing the first time it is scheduled to run.
00127  *
00128  * \param data A pointer to the argument that the function should be
00129  * passed.
00130  */
00131 void mtarch_start(struct mtarch_thread *thread,
00132                   void (* function)(void *data),
00133                   void *data);
00134 
00135 /**
00136  * Start executing a thread.
00137  *
00138  * This function is called from mt_exec() and the purpose of the
00139  * function is to start execution of the thread. The function should
00140  * switch in the stack of the thread, and does not return until the
00141  * thread has explicitly yielded (using mt_yield()) or until it is
00142  * preempted.
00143  *
00144  * \param thread A pointer to a struct mtarch_thread for the thread to
00145  * be executed.
00146  *
00147  */
00148 void mtarch_exec(struct mtarch_thread *thread);
00149 
00150 /**
00151  * Yield the processor.
00152  *
00153  * This function is called by the mt_yield() function, which is called
00154  * from the running thread in order to give up the processor.
00155  *
00156  */
00157 void mtarch_yield(void);
00158 
00159 /**
00160  * Clean up the stack of a thread.
00161  *
00162  * This function is called by the mt_stop() function in order to clean
00163  * up the architecture specific stack of the thread to be stopped.
00164  *
00165  * \note If the stack is wholly contained in struct mtarch_thread this
00166  * function may very well be empty.
00167  *
00168  * \param thread A pointer to a struct mtarch_thread for the thread to
00169  * be stopped.
00170  *
00171  */
00172 void mtarch_stop(struct mtarch_thread *thread);
00173 
00174 void mtarch_pstart(void);
00175 void mtarch_pstop(void);
00176 
00177 /** @} */
00178 
00179 
00180 #include "mtarch.h"
00181 
00182 struct mt_thread {
00183   int state;
00184   process_event_t *evptr;
00185   process_data_t *dataptr;
00186   struct mtarch_thread thread;
00187 };
00188 
00189 /**
00190  * No error.
00191  *
00192  * \hideinitializer
00193  */
00194 #define MT_OK 1
00195 
00196 /**
00197  * Initializes the multithreading library.
00198  *
00199  */
00200 void mt_init(void);
00201 
00202 /**
00203  * Uninstalls library and cleans up.
00204  *
00205  */
00206 void mt_remove(void);
00207 
00208 
00209 /**
00210  * Starts a multithreading thread.
00211  *
00212  * \param thread Pointer to an mt_thread struct that must have been
00213  * previously allocated by the caller.
00214  *
00215  * \param function A pointer to the entry function of the thread that is
00216  * to be set up.
00217  *
00218  * \param data A pointer that will be passed to the entry function.
00219  *
00220  */
00221 void mt_start(struct mt_thread *thread, void (* function)(void *), void *data);
00222 
00223 /**
00224  * Execute parts of a thread.
00225  *
00226  * This function is called by a Contiki process and runs a
00227  * thread. The function does not return until the thread has yielded,
00228  * or is preempted.
00229  *
00230  * \note The thread library must first be initialized with the mt_init()
00231  * function.
00232  *
00233  * \param thread A pointer to a struct mt_thread block that must be
00234  * allocated by the caller.
00235  *
00236  */
00237 void mt_exec(struct mt_thread *thread);
00238 
00239 /**
00240  * Voluntarily give up the processor.
00241  *
00242  * This function is called by a running thread in order to give up
00243  * control of the CPU.
00244  *
00245  */
00246 void mt_yield(void);
00247 
00248 /**
00249  * Exit a thread.
00250  *
00251  * This function is called from within an executing thread in order to
00252  * exit the thread. The function never returns.
00253  *
00254  */
00255 void mt_exit(void);
00256 
00257 /**
00258  * Stop a thread.
00259  *
00260  * This function is called by a Contiki process in order to clean up a
00261  * thread. The struct mt_thread block may then be discarded by the caller.
00262  *
00263  * \param thread A pointer to a struct mt_thread block that must be
00264  * allocated by the caller.
00265  *
00266  */
00267 void mt_stop(struct mt_thread *thread);
00268 
00269 /** @} */
00270 /** @} */
00271 #endif /* __MT_H__ */