Frazer Legge / mbed-rtos

Official mbed Real Time Operating System based on the RTX implementation of the CMSIS-RTOS API open standard.

Dependents:   Assignment_3__Embedded_Software

Fork of mbed-rtos by mbed official

rtos/Thread.h@118:6635230e06ba, 2016-07-25 (annotated)

Committer:
Kojto
Date:
Mon Jul 25 14:12:24 2016 +0100
Revision:
118:6635230e06ba
Parent:
107:bdd541595fc5
Child:
119:19af2d39a542
RTOS rev118



Compatible with the mbed library v122



Changes:

- warnings about duplicated CM symbols fix

- init sequence update - allows init array to be run prior kernel start

- RTOS with OS_TIMERS=0 fix for thread id

- Thread ctor is deprecated, use start() method

- main stack fix for IAR (set via linker script)

- add TCB context pointer

- provide thread safety for toolchains (std lib locks)

- add MBED_RTOS_SINGLE_THREAD macro (sets TSKCNT to 1 and TIMERS to 0)

- nrf51, nucleo l423kc, nucleo f767zi, nucleo f446ze, efm32 support addition

- add OSObserver function

Who changed what in which revision?

UserRevisionLine numberNew contents of line
emilmont 8:88a1a9c26ae3 1 /* mbed Microcontroller Library
emilmont 8:88a1a9c26ae3 2 * Copyright (c) 2006-2012 ARM Limited
emilmont 8:88a1a9c26ae3 3 *
emilmont 8:88a1a9c26ae3 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
emilmont 8:88a1a9c26ae3 5 * of this software and associated documentation files (the "Software"), to deal
emilmont 8:88a1a9c26ae3 6 * in the Software without restriction, including without limitation the rights
emilmont 8:88a1a9c26ae3 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
emilmont 8:88a1a9c26ae3 8 * copies of the Software, and to permit persons to whom the Software is
emilmont 8:88a1a9c26ae3 9 * furnished to do so, subject to the following conditions:
emilmont 8:88a1a9c26ae3 10 *
emilmont 8:88a1a9c26ae3 11 * The above copyright notice and this permission notice shall be included in
emilmont 8:88a1a9c26ae3 12 * all copies or substantial portions of the Software.
emilmont 8:88a1a9c26ae3 13 *
emilmont 8:88a1a9c26ae3 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
emilmont 8:88a1a9c26ae3 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
emilmont 8:88a1a9c26ae3 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
emilmont 8:88a1a9c26ae3 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
emilmont 8:88a1a9c26ae3 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
emilmont 8:88a1a9c26ae3 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
emilmont 8:88a1a9c26ae3 20 * SOFTWARE.
emilmont 8:88a1a9c26ae3 21 */
emilmont 6:350b53afb889 22 #ifndef THREAD_H
emilmont 8:88a1a9c26ae3 23 #define THREAD_H
emilmont 6:350b53afb889 24
emilmont 6:350b53afb889 25 #include <stdint.h>
emilmont 6:350b53afb889 26 #include "cmsis_os.h"
Kojto 118:6635230e06ba 27 #include "Callback.h"
Kojto 118:6635230e06ba 28 #include "toolchain.h"
emilmont 6:350b53afb889 29
emilmont 6:350b53afb889 30 namespace rtos {
emilmont 6:350b53afb889 31
emilmont 8:88a1a9c26ae3 32 /** The Thread class allow defining, creating, and controlling thread functions in the system. */
emilmont 6:350b53afb889 33 class Thread {
emilmont 6:350b53afb889 34 public:
Kojto 118:6635230e06ba 35 /** Allocate a new thread without starting execution
Kojto 118:6635230e06ba 36 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 37 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 38 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 39 */
Kojto 118:6635230e06ba 40 Thread(osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 41 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 42 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 43 constructor(priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 44 }
Kojto 118:6635230e06ba 45
emilmont 8:88a1a9c26ae3 46 /** Create a new thread, and start it executing the specified function.
emilmont 8:88a1a9c26ae3 47 @param task function to be executed by this thread.
emilmont 8:88a1a9c26ae3 48 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
emilmont 8:88a1a9c26ae3 49 @param priority initial priority of the thread function. (default: osPriorityNormal).
emilmont 8:88a1a9c26ae3 50 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
emilmont 8:88a1a9c26ae3 51 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 52 @deprecated
Kojto 118:6635230e06ba 53 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 54 program state when a thread is declared.
Kojto 118:6635230e06ba 55
Kojto 118:6635230e06ba 56 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 57 a thread.
emilmont 6:350b53afb889 58 */
Kojto 118:6635230e06ba 59 MBED_DEPRECATED(
Kojto 118:6635230e06ba 60 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 61 "program state when a thread is declared")
Kojto 118:6635230e06ba 62 Thread(mbed::Callback<void()> task,
Kojto 118:6635230e06ba 63 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 64 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 65 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 66 constructor(task, priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 67 }
Kojto 118:6635230e06ba 68
Kojto 118:6635230e06ba 69 /** Create a new thread, and start it executing the specified function.
Kojto 118:6635230e06ba 70 @param obj argument to task.
Kojto 118:6635230e06ba 71 @param method function to be executed by this thread.
Kojto 118:6635230e06ba 72 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
Kojto 118:6635230e06ba 73 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 74 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 75 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 76 @deprecated
Kojto 118:6635230e06ba 77 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 78 program state when a thread is declared.
Kojto 118:6635230e06ba 79
Kojto 118:6635230e06ba 80 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 81 a thread.
Kojto 118:6635230e06ba 82 */
Kojto 118:6635230e06ba 83 template <typename T>
Kojto 118:6635230e06ba 84 MBED_DEPRECATED(
Kojto 118:6635230e06ba 85 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 86 "program state when a thread is declared")
Kojto 118:6635230e06ba 87 Thread(T *obj, void (T::*method)(),
Kojto 118:6635230e06ba 88 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 89 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 90 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 91 constructor(mbed::Callback<void()>(obj, method),
Kojto 118:6635230e06ba 92 priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 93 }
Kojto 118:6635230e06ba 94
Kojto 118:6635230e06ba 95 /** Create a new thread, and start it executing the specified function.
Kojto 118:6635230e06ba 96 @param obj argument to task.
Kojto 118:6635230e06ba 97 @param method function to be executed by this thread.
Kojto 118:6635230e06ba 98 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
Kojto 118:6635230e06ba 99 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 100 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 101 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 102 @deprecated
Kojto 118:6635230e06ba 103 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 104 program state when a thread is declared.
Kojto 118:6635230e06ba 105
Kojto 118:6635230e06ba 106 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 107 a thread.
Kojto 118:6635230e06ba 108 */
Kojto 118:6635230e06ba 109 template <typename T>
Kojto 118:6635230e06ba 110 MBED_DEPRECATED(
Kojto 118:6635230e06ba 111 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 112 "program state when a thread is declared")
Kojto 118:6635230e06ba 113 Thread(T *obj, void (*method)(T *),
Kojto 118:6635230e06ba 114 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 115 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 116 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 117 constructor(mbed::Callback<void()>(obj, method),
Kojto 118:6635230e06ba 118 priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 119 }
Kojto 118:6635230e06ba 120
Kojto 118:6635230e06ba 121 /** Create a new thread, and start it executing the specified function.
Kojto 118:6635230e06ba 122 Provided for backwards compatibility
Kojto 118:6635230e06ba 123 @param task function to be executed by this thread.
Kojto 118:6635230e06ba 124 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
Kojto 118:6635230e06ba 125 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 126 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 127 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 128 @deprecated
Kojto 118:6635230e06ba 129 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 130 program state when a thread is declared.
Kojto 118:6635230e06ba 131
Kojto 118:6635230e06ba 132 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 133 a thread.
Kojto 118:6635230e06ba 134 */
Kojto 118:6635230e06ba 135 MBED_DEPRECATED(
Kojto 118:6635230e06ba 136 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 137 "program state when a thread is declared")
emilmont 6:350b53afb889 138 Thread(void (*task)(void const *argument), void *argument=NULL,
emilmont 6:350b53afb889 139 osPriority priority=osPriorityNormal,
emilmont 6:350b53afb889 140 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 141 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 142 constructor(mbed::Callback<void()>(argument, (void (*)(void *))task),
Kojto 118:6635230e06ba 143 priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 144 }
Kojto 118:6635230e06ba 145
Kojto 118:6635230e06ba 146 /** Starts a thread executing the specified function.
Kojto 118:6635230e06ba 147 @param task function to be executed by this thread.
Kojto 118:6635230e06ba 148 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 149 */
Kojto 118:6635230e06ba 150 osStatus start(mbed::Callback<void()> task);
Kojto 118:6635230e06ba 151
Kojto 118:6635230e06ba 152 /** Starts a thread executing the specified function.
Kojto 118:6635230e06ba 153 @param obj argument to task
Kojto 118:6635230e06ba 154 @param method function to be executed by this thread.
Kojto 118:6635230e06ba 155 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 156 */
Kojto 118:6635230e06ba 157 template <typename T, typename M>
Kojto 118:6635230e06ba 158 osStatus start(T *obj, M method) {
Kojto 118:6635230e06ba 159 return start(mbed::Callback<void()>(obj, method));
Kojto 118:6635230e06ba 160 }
Kojto 118:6635230e06ba 161
Kojto 118:6635230e06ba 162 /** Wait for thread to terminate
Kojto 118:6635230e06ba 163 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 164 @note not callable from interrupt
Kojto 118:6635230e06ba 165 */
Kojto 118:6635230e06ba 166 osStatus join();
mbed_official 31:015df9e602b6 167
emilmont 8:88a1a9c26ae3 168 /** Terminate execution of a thread and remove it from Active Threads
emilmont 8:88a1a9c26ae3 169 @return status code that indicates the execution status of the function.
emilmont 6:350b53afb889 170 */
emilmont 6:350b53afb889 171 osStatus terminate();
mbed_official 31:015df9e602b6 172
emilmont 8:88a1a9c26ae3 173 /** Set priority of an active thread
emilmont 8:88a1a9c26ae3 174 @param priority new priority value for the thread function.
emilmont 8:88a1a9c26ae3 175 @return status code that indicates the execution status of the function.
emilmont 6:350b53afb889 176 */
emilmont 6:350b53afb889 177 osStatus set_priority(osPriority priority);
mbed_official 31:015df9e602b6 178
emilmont 8:88a1a9c26ae3 179 /** Get priority of an active thread
emilmont 8:88a1a9c26ae3 180 @return current priority value of the thread function.
emilmont 6:350b53afb889 181 */
emilmont 6:350b53afb889 182 osPriority get_priority();
mbed_official 31:015df9e602b6 183
emilmont 8:88a1a9c26ae3 184 /** Set the specified Signal Flags of an active thread.
emilmont 8:88a1a9c26ae3 185 @param signals specifies the signal flags of the thread that should be set.
emilmont 8:88a1a9c26ae3 186 @return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
emilmont 6:350b53afb889 187 */
emilmont 6:350b53afb889 188 int32_t signal_set(int32_t signals);
mbed_official 31:015df9e602b6 189
mbed_official 76:85a52b7ef44b 190 /** Clears the specified Signal Flags of an active thread.
mbed_official 76:85a52b7ef44b 191 @param signals specifies the signal flags of the thread that should be cleared.
mbed_official 76:85a52b7ef44b 192 @return resultant signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
mbed_official 76:85a52b7ef44b 193 */
mbed_official 76:85a52b7ef44b 194 int32_t signal_clr(int32_t signals);
mbed_official 76:85a52b7ef44b 195
emilmont 8:88a1a9c26ae3 196 /** State of the Thread */
emilmont 8:88a1a9c26ae3 197 enum State {
emilmont 8:88a1a9c26ae3 198 Inactive, /**< Not created or terminated */
emilmont 8:88a1a9c26ae3 199 Ready, /**< Ready to run */
emilmont 8:88a1a9c26ae3 200 Running, /**< Running */
emilmont 8:88a1a9c26ae3 201 WaitingDelay, /**< Waiting for a delay to occur */
emilmont 8:88a1a9c26ae3 202 WaitingInterval, /**< Waiting for an interval to occur */
emilmont 8:88a1a9c26ae3 203 WaitingOr, /**< Waiting for one event in a set to occur */
emilmont 8:88a1a9c26ae3 204 WaitingAnd, /**< Waiting for multiple events in a set to occur */
emilmont 8:88a1a9c26ae3 205 WaitingSemaphore, /**< Waiting for a semaphore event to occur */
emilmont 8:88a1a9c26ae3 206 WaitingMailbox, /**< Waiting for a mailbox event to occur */
emilmont 8:88a1a9c26ae3 207 WaitingMutex, /**< Waiting for a mutex event to occur */
emilmont 8:88a1a9c26ae3 208 };
mbed_official 31:015df9e602b6 209
emilmont 8:88a1a9c26ae3 210 /** State of this Thread
emilmont 8:88a1a9c26ae3 211 @return the State of this Thread
emilmont 8:88a1a9c26ae3 212 */
emilmont 8:88a1a9c26ae3 213 State get_state();
mbed_official 84:143955ffb790 214
mbed_official 84:143955ffb790 215 /** Get the total stack memory size for this Thread
mbed_official 84:143955ffb790 216 @return the total stack memory size in bytes
mbed_official 84:143955ffb790 217 */
mbed_official 84:143955ffb790 218 uint32_t stack_size();
mbed_official 84:143955ffb790 219
mbed_official 84:143955ffb790 220 /** Get the currently unused stack memory for this Thread
mbed_official 84:143955ffb790 221 @return the currently unused stack memory in bytes
mbed_official 84:143955ffb790 222 */
mbed_official 84:143955ffb790 223 uint32_t free_stack();
mbed_official 84:143955ffb790 224
mbed_official 84:143955ffb790 225 /** Get the currently used stack memory for this Thread
mbed_official 84:143955ffb790 226 @return the currently used stack memory in bytes
mbed_official 84:143955ffb790 227 */
mbed_official 84:143955ffb790 228 uint32_t used_stack();
mbed_official 84:143955ffb790 229
mbed_official 84:143955ffb790 230 /** Get the maximum stack memory usage to date for this Thread
mbed_official 84:143955ffb790 231 @return the maximum stack memory usage to date in bytes
mbed_official 84:143955ffb790 232 */
mbed_official 84:143955ffb790 233 uint32_t max_stack();
mbed_official 31:015df9e602b6 234
mbed_official 31:015df9e602b6 235 /** Wait for one or more Signal Flags to become signaled for the current RUNNING thread.
emilmont 8:88a1a9c26ae3 236 @param signals wait until all specified signal flags set or 0 for any single signal flag.
emilmont 8:88a1a9c26ae3 237 @param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
emilmont 8:88a1a9c26ae3 238 @return event flag information or error code.
Kojto 118:6635230e06ba 239 @note not callable from interrupt
emilmont 6:350b53afb889 240 */
emilmont 6:350b53afb889 241 static osEvent signal_wait(int32_t signals, uint32_t millisec=osWaitForever);
mbed_official 31:015df9e602b6 242
emilmont 8:88a1a9c26ae3 243 /** Wait for a specified time period in millisec:
emilmont 8:88a1a9c26ae3 244 @param millisec time delay value
mbed_official 31:015df9e602b6 245 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 246 @note not callable from interrupt
emilmont 6:350b53afb889 247 */
emilmont 6:350b53afb889 248 static osStatus wait(uint32_t millisec);
mbed_official 31:015df9e602b6 249
emilmont 8:88a1a9c26ae3 250 /** Pass control to next thread that is in state READY.
emilmont 8:88a1a9c26ae3 251 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 252 @note not callable from interrupt
emilmont 6:350b53afb889 253 */
emilmont 6:350b53afb889 254 static osStatus yield();
mbed_official 31:015df9e602b6 255
emilmont 8:88a1a9c26ae3 256 /** Get the thread id of the current running thread.
emilmont 8:88a1a9c26ae3 257 @return thread ID for reference by other functions or NULL in case of error.
emilmont 6:350b53afb889 258 */
emilmont 6:350b53afb889 259 static osThreadId gettid();
mbed_official 107:bdd541595fc5 260
mbed_official 107:bdd541595fc5 261 /** Attach a function to be called by the RTOS idle task
mbed_official 107:bdd541595fc5 262 @param fptr pointer to the function to be called
mbed_official 107:bdd541595fc5 263 */
mbed_official 107:bdd541595fc5 264 static void attach_idle_hook(void (*fptr)(void));
mbed_official 31:015df9e602b6 265
emilmont 6:350b53afb889 266 virtual ~Thread();
emilmont 6:350b53afb889 267
emilmont 6:350b53afb889 268 private:
Kojto 118:6635230e06ba 269 // Required to share definitions without
Kojto 118:6635230e06ba 270 // delegated constructors
Kojto 118:6635230e06ba 271 void constructor(osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 272 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 273 unsigned char *stack_pointer=NULL);
Kojto 118:6635230e06ba 274 void constructor(mbed::Callback<void()> task,
Kojto 118:6635230e06ba 275 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 276 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 277 unsigned char *stack_pointer=NULL);
Kojto 118:6635230e06ba 278
Kojto 118:6635230e06ba 279 mbed::Callback<void()> _task;
emilmont 6:350b53afb889 280 osThreadId _tid;
emilmont 6:350b53afb889 281 osThreadDef_t _thread_def;
emilmont 6:350b53afb889 282 bool _dynamic_stack;
emilmont 6:350b53afb889 283 };
emilmont 6:350b53afb889 284
emilmont 6:350b53afb889 285 }
emilmont 6:350b53afb889 286 #endif