fsdfds
Dependencies: BLE_API mbed-dev-bin nRF51822
Fork of microbit-dal by
MicroBitFiber.h
00001 /* 00002 The MIT License (MIT) 00003 00004 Copyright (c) 2016 British Broadcasting Corporation. 00005 This software is provided by Lancaster University by arrangement with the BBC. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a 00008 copy of this software and associated documentation files (the "Software"), 00009 to deal in the Software without restriction, including without limitation 00010 the rights to use, copy, modify, merge, publish, distribute, sublicense, 00011 and/or sell copies of the Software, and to permit persons to whom the 00012 Software is furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 00023 DEALINGS IN THE SOFTWARE. 00024 */ 00025 00026 /** 00027 * Functionality definitions for the MicroBit Fiber scheduler. 00028 * 00029 * This lightweight, non-preemptive scheduler provides a simple threading mechanism for two main purposes: 00030 * 00031 * 1) To provide a clean abstraction for application languages to use when building async behaviour (callbacks). 00032 * 2) To provide ISR decoupling for EventModel events generated in an ISR context. 00033 * 00034 * TODO: Consider a split mode scheduler, that monitors used stack size, and maintains a dedicated, persistent 00035 * stack for any long lived fibers with large stack 00036 */ 00037 #ifndef MICROBIT_FIBER_H 00038 #define MICROBIT_FIBER_H 00039 00040 #include "mbed.h" 00041 #include "MicroBitConfig.h" 00042 #include "MicroBitEvent.h" 00043 #include "EventModel.h" 00044 00045 // Fiber Scheduler Flags 00046 #define MICROBIT_SCHEDULER_RUNNING 0x01 00047 00048 // Fiber Flags 00049 #define MICROBIT_FIBER_FLAG_FOB 0x01 00050 #define MICROBIT_FIBER_FLAG_PARENT 0x02 00051 #define MICROBIT_FIBER_FLAG_CHILD 0x04 00052 #define MICROBIT_FIBER_FLAG_DO_NOT_PAGE 0x08 00053 00054 /** 00055 * Thread Context for an ARM Cortex M0 core. 00056 * 00057 * This is probably overkill, but the ARMCC compiler uses a lot register optimisation 00058 * in its calling conventions, so better safe than sorry! 00059 */ 00060 struct Cortex_M0_TCB 00061 { 00062 uint32_t R0; 00063 uint32_t R1; 00064 uint32_t R2; 00065 uint32_t R3; 00066 uint32_t R4; 00067 uint32_t R5; 00068 uint32_t R6; 00069 uint32_t R7; 00070 uint32_t R8; 00071 uint32_t R9; 00072 uint32_t R10; 00073 uint32_t R11; 00074 uint32_t R12; 00075 uint32_t SP; 00076 uint32_t LR; 00077 uint32_t stack_base; 00078 }; 00079 00080 /** 00081 * Representation of a single Fiber 00082 */ 00083 struct Fiber 00084 { 00085 Cortex_M0_TCB tcb; // Thread context when last scheduled out. 00086 uint32_t stack_bottom; // The start address of this Fiber's stack. The stack is heap allocated, and full descending. 00087 uint32_t stack_top; // The end address of this Fiber's stack. 00088 uint32_t context; // Context specific information. 00089 uint32_t flags; // Information about this fiber. 00090 Fiber **queue; // The queue this fiber is stored on. 00091 Fiber *next, *prev; // Position of this Fiber on the run queue. 00092 }; 00093 00094 extern Fiber *currentFiber; 00095 00096 00097 /** 00098 * Initialises the Fiber scheduler. 00099 * Creates a Fiber context around the calling thread, and adds it to the run queue as the current thread. 00100 * 00101 * This function must be called once only from the main thread, and before any other Fiber operation. 00102 * 00103 * @param _messageBus An event model, used to direct the priorities of the scheduler. 00104 */ 00105 void scheduler_init(EventModel &_messageBus); 00106 00107 /** 00108 * Determines if the fiber scheduler is operational. 00109 * 00110 * @return 1 if the fber scheduler is running, 0 otherwise. 00111 */ 00112 int fiber_scheduler_running(); 00113 00114 /** 00115 * Exit point for all fibers. 00116 * 00117 * Any fiber reaching the end of its entry function will return here for recycling. 00118 */ 00119 void release_fiber(void); 00120 void release_fiber(void *param); 00121 00122 /** 00123 * Launches a fiber. 00124 * 00125 * @param ep the entry point for the fiber. 00126 * 00127 * @param cp the completion routine after ep has finished execution 00128 */ 00129 void launch_new_fiber(void (*ep)(void), void (*cp)(void)) 00130 #ifdef __GCC__ 00131 __attribute__((naked)) 00132 #endif 00133 ; 00134 00135 /** 00136 * Launches a fiber with a parameter 00137 * 00138 * @param ep the entry point for the fiber. 00139 * 00140 * @param cp the completion routine after ep has finished execution 00141 * 00142 * @param pm the parameter to provide to ep and cp. 00143 */ 00144 void launch_new_fiber_param(void (*ep)(void *), void (*cp)(void *), void *pm) 00145 #ifdef __GCC__ 00146 __attribute__((naked)) 00147 #endif 00148 ; 00149 00150 /** 00151 * Creates a new Fiber, and launches it. 00152 * 00153 * @param entry_fn The function the new Fiber will begin execution in. 00154 * 00155 * @param completion_fn The function called when the thread completes execution of entry_fn. 00156 * Defaults to release_fiber. 00157 * 00158 * @return The new Fiber, or NULL if the operation could not be completed. 00159 */ 00160 Fiber *create_fiber(void (*entry_fn)(void), void (*completion_fn)(void) = release_fiber); 00161 00162 00163 /** 00164 * Creates a new parameterised Fiber, and launches it. 00165 * 00166 * @param entry_fn The function the new Fiber will begin execution in. 00167 * 00168 * @param param an untyped parameter passed into the entry_fn and completion_fn. 00169 * 00170 * @param completion_fn The function called when the thread completes execution of entry_fn. 00171 * Defaults to release_fiber. 00172 * 00173 * @return The new Fiber, or NULL if the operation could not be completed. 00174 */ 00175 Fiber *create_fiber(void (*entry_fn)(void *), void *param, void (*completion_fn)(void *) = release_fiber); 00176 00177 00178 /** 00179 * Calls the Fiber scheduler. 00180 * The calling Fiber will likely be blocked, and control given to another waiting fiber. 00181 * Call this function to yield control of the processor when you have nothing more to do. 00182 */ 00183 void schedule(); 00184 00185 /** 00186 * Blocks the calling thread for the given period of time. 00187 * The calling thread will be immediateley descheduled, and placed onto a 00188 * wait queue until the requested amount of time has elapsed. 00189 * 00190 * @param t The period of time to sleep, in milliseconds. 00191 * 00192 * @note the fiber will not be be made runnable until after the elapsed time, but there 00193 * are no guarantees precisely when the fiber will next be scheduled. 00194 */ 00195 void fiber_sleep(unsigned long t); 00196 00197 /** 00198 * The timer callback, called from interrupt context once every SYSTEM_TICK_PERIOD_MS milliseconds. 00199 * This function checks to determine if any fibers blocked on the sleep queue need to be woken up 00200 * and made runnable. 00201 */ 00202 void scheduler_tick(); 00203 00204 /** 00205 * Blocks the calling thread until the specified event is raised. 00206 * The calling thread will be immediateley descheduled, and placed onto a 00207 * wait queue until the requested event is received. 00208 * 00209 * @param id The ID field of the event to listen for (e.g. MICROBIT_ID_BUTTON_A) 00210 * 00211 * @param value The value of the event to listen for (e.g. MICROBIT_BUTTON_EVT_CLICK) 00212 * 00213 * @return MICROBIT_OK, or MICROBIT_NOT_SUPPORTED if the fiber scheduler is not running, or associated with an EventModel. 00214 * 00215 * @code 00216 * fiber_wait_for_event(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK); 00217 * @endcode 00218 * 00219 * @note the fiber will not be be made runnable until after the event is raised, but there 00220 * are no guarantees precisely when the fiber will next be scheduled. 00221 */ 00222 int fiber_wait_for_event(uint16_t id, uint16_t value); 00223 00224 /** 00225 * Configures the fiber context for the current fiber to block on an event ID 00226 * and value, but does not deschedule the fiber. 00227 * 00228 * @param id The ID field of the event to listen for (e.g. MICROBIT_ID_BUTTON_A) 00229 * 00230 * @param value The value of the event to listen for (e.g. MICROBIT_BUTTON_EVT_CLICK) 00231 * 00232 * @return MICROBIT_OK, or MICROBIT_NOT_SUPPORTED if the fiber scheduler is not running, or associated with an EventModel. 00233 * 00234 * @code 00235 * fiber_wake_on_event(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK); 00236 * 00237 * //perform some time critical operation. 00238 * 00239 * //deschedule the current fiber manually, waiting for the previously configured event. 00240 * schedule(); 00241 * @endcode 00242 */ 00243 int fiber_wake_on_event(uint16_t id, uint16_t value); 00244 00245 /** 00246 * Executes the given function asynchronously if necessary. 00247 * 00248 * Fibers are often used to run event handlers, however many of these event handlers are very simple functions 00249 * that complete very quickly, bringing unecessary RAM overhead. 00250 * 00251 * This function takes a snapshot of the current processor context, then attempts to optimistically call the given function directly. 00252 * We only create an additional fiber if that function performs a block operation. 00253 * 00254 * @param entry_fn The function to execute. 00255 * 00256 * @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER. 00257 */ 00258 int invoke(void (*entry_fn)(void)); 00259 00260 /** 00261 * Executes the given function asynchronously if necessary, and offers the ability to provide a parameter. 00262 * 00263 * Fibers are often used to run event handlers, however many of these event handlers are very simple functions 00264 * that complete very quickly, bringing unecessary RAM. overhead 00265 * 00266 * This function takes a snapshot of the current fiber context, then attempt to optimistically call the given function directly. 00267 * We only create an additional fiber if that function performs a block operation. 00268 * 00269 * @param entry_fn The function to execute. 00270 * 00271 * @param param an untyped parameter passed into the entry_fn and completion_fn. 00272 * 00273 * @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER. 00274 */ 00275 int invoke(void (*entry_fn)(void *), void *param); 00276 00277 /** 00278 * Resizes the stack allocation of the current fiber if necessary to hold the system stack. 00279 * 00280 * If the stack allocation is large enough to hold the current system stack, then this function does nothing. 00281 * Otherwise, the the current allocation of the fiber is freed, and a larger block is allocated. 00282 * 00283 * @param f The fiber context to verify. 00284 * 00285 * @return The stack depth of the given fiber. 00286 */ 00287 inline void verify_stack_size(Fiber *f); 00288 00289 /** 00290 * Event callback. Called from an instance of MicroBitMessageBus whenever an event is raised. 00291 * 00292 * This function checks to determine if any fibers blocked on the wait queue need to be woken up 00293 * and made runnable due to the event. 00294 * 00295 * @param evt the event that has just been raised on an instance of MicroBitMessageBus. 00296 */ 00297 void scheduler_event(MicroBitEvent evt); 00298 00299 /** 00300 * Determines if any fibers are waiting to be scheduled. 00301 * 00302 * @return The number of fibers currently on the run queue 00303 */ 00304 int scheduler_runqueue_empty(); 00305 00306 /** 00307 * Utility function to add the currenty running fiber to the given queue. 00308 * 00309 * Perform a simple add at the head, to avoid complexity, 00310 * 00311 * Queues are normally very short, so maintaining a doubly linked, sorted list typically outweighs the cost of 00312 * brute force searching. 00313 * 00314 * @param f The fiber to add to the queue 00315 * 00316 * @param queue The run queue to add the fiber to. 00317 */ 00318 void queue_fiber(Fiber *f, Fiber **queue); 00319 00320 /** 00321 * Utility function to the given fiber from whichever queue it is currently stored on. 00322 * 00323 * @param f the fiber to remove. 00324 */ 00325 void dequeue_fiber(Fiber *f); 00326 00327 /** 00328 * Set of tasks to perform when idle. 00329 * Service any background tasks that are required, and attempt a power efficient sleep. 00330 */ 00331 void idle(); 00332 00333 /** 00334 * The idle task, which is called when the runtime has no fibers that require execution. 00335 * 00336 * This function typically calls idle(). 00337 */ 00338 void idle_task(); 00339 00340 /** 00341 * Adds a component to the array of idle thread components, which are processed 00342 * when the run queue is empty. 00343 * 00344 * @param component The component to add to the array. 00345 * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the fiber components array is full. 00346 */ 00347 int fiber_add_idle_component(MicroBitComponent *component); 00348 00349 /** 00350 * remove a component from the array of idle thread components 00351 * 00352 * @param component the component to remove from the idle component array. 00353 * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added. 00354 */ 00355 int fiber_remove_idle_component(MicroBitComponent *component); 00356 00357 /** 00358 * Determines if the processor is executing in interrupt context. 00359 * 00360 * @return true if any the processor is currently executing any interrupt service routine. False otherwise. 00361 */ 00362 inline int inInterruptContext() 00363 { 00364 return (((int)__get_IPSR()) & 0x003F) > 0; 00365 } 00366 00367 /** 00368 * Assembler Context switch routing. 00369 * Defined in CortexContextSwitch.s. 00370 */ 00371 extern "C" void swap_context(Cortex_M0_TCB *from, Cortex_M0_TCB *to, uint32_t from_stack, uint32_t to_stack); 00372 extern "C" void save_context(Cortex_M0_TCB *tcb, uint32_t stack); 00373 extern "C" void save_register_context(Cortex_M0_TCB *tcb); 00374 extern "C" void restore_register_context(Cortex_M0_TCB *tcb); 00375 00376 #endif
Generated on Wed Jul 13 2022 00:58:03 by 1.7.2