mbos.h

00001 /***********************************************************************************
00002  *  m b o s   R T O S   F O R    m b e d  (ARM CORTEX M3)
00003  *
00004  * Copyright (c) 2010 - 2011 Andrew Levido
00005  *
00006  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
00007  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00008  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
00009  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00010  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
00011  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00012  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00013  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00014  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00015  */
00016 #ifndef MBOS_H
00017 #define MBOS_H
00018 
00019 typedef unsigned int uint;
00020 
00021 /**A pre-emptive, mutlitasking real-time operating system for mbed applications.
00022  *
00023  * Allows the user to write their application in the form of independant tasks.
00024  * The operating system manages a completely separate processor context for each
00025  * task (processor registers and stack) and swaps between the tasks according to a
00026  * simple scheduling algorithm.
00027  *
00028  * Tasks are allocated a priority, and the scheduler ensures that the task
00029  * that with the highest priority that is not waiting for an event, has control of
00030  * the processor. If more than one task shares the highest priority, they will be
00031  * run sequentially in round-robin fashion.
00032  *
00033  * Each task may wait for one or more of up to 32 different events, each represented by
00034  * one bit in the event flags word. Events may be posted by another task, by a mbos
00035  * timer, or in response to some asynchronous event such as an peripheral interrupt.
00036  *
00037  * mbos implements the SysTick timer to generate a System Tick every millisecond.
00038  * Scheduling occurs once every Tick, or whenever a task blocks or an event is posted.
00039  * The user may create one-shot or continuous timers to post events to tasks.
00040  *
00041  * mbos implements a simple ceiling protocol resource locking mechanism To manage access
00042  * to system resources. Tasks may take exclusive ownership of resources for a period.
00043  *
00044  * A typical simple example with two tasks, and one timer, might look like this:
00045  * @code
00046  * // mbos Blinky demonstration.
00047  * // Task 1 toggles LED1 every second, under control of a timer. It then posts an event to
00048  * // task 2 which flashed LED2 briefly.
00049  * #include "mbed.h"                    
00050  * #include "mbos.h"
00051  *
00052  * #define TASK1_ID                1       // Id for task 1 (idle task is 0)
00053  * #define TASK1_PRIO              50      // priority for task 1
00054  * #define TASK1_STACK_SZ          32      // stack size for task 1 in words 
00055  * #define TASK2_ID                2       // Id for task 2 
00056  * #define TASK2_PRIO              60      // priority for task 2
00057  * #define TASK2_STACK_SZ          32      // stack size for task 2 in words 
00058  * #define TIMER0_ID               0       // Id for timer 0
00059  * #define TIMER0_PERIOD           1000    // Time period in milliseconds
00060  * #define TIMER0_EVENT            1       // Event flag (1 << 0)
00061  * #define T1_TO_T2_EVENT          2       // Event flag (1 << 1)
00062  *
00063  * void task1(void);                       // task function prototypes
00064  * void task2(void);
00065  *
00066  * DigitalOut led1(LED1);
00067  * DigitalOut led2(LED2);
00068  * mbos os(2, 1);                          // Instantiate mbos with 2 tasks & 1 timer    
00069  *
00070  * int main(void)
00071  * {
00072  *     // Configure tasks and timers
00073  *     os.CreateTask(TASK1_ID, TASK1_PRIO, TASK1_STACK_SZ, task1);
00074  *     os.CreateTask(TASK2_ID, TASK2_PRIO, TASK2_STACK_SZ, task2);
00075  *     os.CreateTimer(TIMER0_ID, TIMER0_EVENT, TASK1_ID);
00076  *     // Start mbos
00077  *     os.Start();
00078  *     // never  return!
00079  * }
00080  *
00081  * void task1(void)
00082  * {
00083  *     os.SetTimer(TIMER0_ID, TIMER0_PERIOD, TIMER0_PERIOD);
00084  *     while(1){
00085  *         os.WaitEvent(TIMER0_EVENT);
00086  *         led1 = !led1;
00087  *         os.SetEvent(T1_TO_T2_EVENT, TASK2_ID);
00088  *     }
00089  * }
00090  *
00091  * void task2(void)
00092  * {
00093  *     while(1){
00094  *         os.WaitEvent(T1_TO_T2_EVENT);
00095  *         led2 = 1;
00096  *         wait_ms(100);
00097  *         led2 = 0;
00098  *     }
00099  * }
00100  * @endcode
00101  */
00102 
00103 class mbos {
00104 public:
00105     /** Create an mbos object. Instantiate mbos and define the number of tasks, timers 
00106      * and resources. 
00107      *
00108      * @param ntasks The number of user tasks (1 .. 99). 
00109      * @param ntimers Optional number of timers (0 ..  100).
00110      * @param nresources Optional number of resources (0 .. 100).
00111      */
00112     mbos(uint ntasks, uint ntimers = 0, uint nresources = 0);
00113 
00114     /** Start mbos. Optionally specify the size of the stack for a user-written idle task. 
00115      * All tasks, timers and resources must be created before calling Start. 
00116      *
00117      * @param idlestacksize Size in words (>= 32) of the user-written idle task if present. 
00118      * @returns Never returns
00119      */
00120     void Start(uint idlestacksize = 32);
00121 
00122     /** Create an mbos task. Allocates and initialises data structures for the task.
00123      *
00124      * @param taskid Unique ID for the task. (1 .. ntasks).
00125      * @param priority Priority (0 .. 99) of the task. Tasks may share the same priority.
00126      * @param stacksize Size in words (>= 32) of the task's stack.
00127      * @param fun Pointer to the task function. Function must be of type static void, 
00128      * and must return nothing.
00129      */
00130     void CreateTask(uint taskid, uint priority, uint stacksz, void (*fun)(void));
00131 
00132     /** Get the ID of the current task.
00133      *
00134      * @returns The ID (0 .. 99) of the calling task.
00135      */
00136     uint GetTask(void);
00137 
00138     /** Set the priority of the current task.  Does nothing if called from the idle task.
00139      *
00140      * @param priority Priority (0 .. 99) to apply to the calling task.
00141      */
00142     void SetPriority(uint priority);
00143 
00144     /** Get the priority of the current task.
00145      *
00146      * @returns The priority (0 .. 99) of the calling task.
00147      */
00148     uint GetPriority(void);
00149 
00150     /** Wait for an event or events. Causes the current task to block, waiting for the 
00151      * specified event. Does nothing if called from the idle task, or if the event is NULL.
00152      *
00153      * @param event Event flag(s) to wait for.
00154      */
00155     void WaitEvent(uint event);
00156 
00157     /** Post an event or events to a task.
00158      * Posts the nominated event(s) to the specified task. Forces a context switch if the events
00159      * are posted successfully. Does nothing if the task is not waiting, or is not waiting for 
00160      * the posted event.
00161      *
00162      * @param event Event flag(s) to post. 
00163      * @param task The ID of the task to which to post the event(s). May not be idle task.
00164      */
00165     void SetEvent(uint event, uint task);
00166 
00167     /** Returns the event flag(s) which last caused the task to unblock.
00168      *
00169      * @returns The event flags.
00170      */
00171     uint GetEvent(void);
00172 
00173     /** Create a mbos timer. Allocates and initialises the data structures for the timer.
00174      *
00175      * @param timerid Unique ID for the timer (0 .. ntimers - 1). 
00176      * @param taskid The ID of the task to which the timer will post events. May not be 
00177      * the idle task.
00178      * @param event The event flag(s) that the timer should post on timeout. May not be NULL.
00179      */
00180     void CreateTimer(uint timerid, uint taskid, uint event);
00181 
00182     /** Starts an mbos timer. If the reload time is zero or omitted, the timer will be reset 
00183      * once it has posted a single event, after time milliseconds. If the reload time is
00184      * non-zero, this value will be loaded into the timer on time-out, and the timer will 
00185      * continue indefinitely. In this case the interval to the first event will be time, 
00186      * and the interval between subsequent events will be reloadtime.
00187      *
00188      * @param timerid The ID of the timer. 
00189      * @param time The period in milliseconds before the timer times out.
00190      * @param reload The optional time to reload into the timer when it times out.
00191      */
00192     void SetTimer(uint timerid, uint time, uint reload = 0);
00193     
00194     /** Redirects an mbos timer. Changes the task and event associated with a timer. If the timer
00195      * is running, the fun ction has no effect.
00196      *
00197      * @param timerid The ID of the timer.
00198      * @param taskid The ID of the task to which the timer will post events. May not be 
00199      * the idle task.
00200      * @param event The event flag(s) that the timer should post on timeout. May not be NULL.
00201      */
00202      void RedirectTimer(uint timerid, uint taskid, uint event); 
00203 
00204     /** Stops and clears an mbos timer.
00205      *
00206      * @param timerid The ID of the timer to clear. 
00207      */
00208     void ClearTimer(uint timerid);
00209 
00210     /** Creates an mbos resource. Allocates and initialises the data structures for the Resource.
00211      *
00212      * @param resourceid Unique ID for the resource (0 .. nresource).
00213      * @param priority Priority of the resource (normally > than that of any task using the 
00214      * resource).
00215      */
00216     void CreateResource(uint resourceid, uint priority);
00217 
00218     /** Locks an mbos resource and temporarily allocates the resource's priority to the calling 
00219      * task. 
00220      * Does nothing if the resource is already locked, or if called from the idle task.
00221      *
00222      * @param resourceid The ID of the resource to lock. 
00223      * @returns Zero if the resource was locked successfully, or the ID of the task that is
00224      * currently locking the resource, if not.
00225      */
00226     uint LockResource(uint resourceid);
00227 
00228     /** Tests whether a resource is locked or free, without changing its state.
00229      *
00230      * @param resourceid The ID of the resouce to test.
00231      * @returns Zero if the resource is free, or the ID of the task that is currently
00232      * locking the resouce , if not.
00233 
00234      */
00235     uint TestResource(uint resourceid);
00236 
00237     /** Frees a resource
00238      * Frees an mbos resource and restores the calling task's original priority. Does nothing 
00239      * if the resource is already free, if called from the idle task, or the resource was 
00240      * locked by a different task.
00241      *
00242      * @param resourceid The ID of the resource t free. 
00243      * @returns Zero if the resource was freed successfully, or the ID of the task that is
00244      * locking the resource, if not.
00245      */
00246     uint FreeResource(uint resource);
00247 
00248 private:
00249     uint* _initstack(uint *stack, void (*fun)());
00250 };
00251 #endif