mbed official / mbed-rtos

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

Dependents:   denki-yohou_b TestY201 Network-RTOS NTPClient_HelloWorld ... more

Deprecated

This is the mbed 2 rtos library. mbed OS 5 integrates the mbed library with mbed-rtos. With this, we have provided thread safety for all mbed APIs. If you'd like to learn about using mbed OS 5, please see the docs.

rtos/Thread.h@121:3da5f554d8bf, 2016-09-01 (annotated)

Committer:
<>
Date:
Thu Sep 01 15:13:42 2016 +0100
Revision:
121:3da5f554d8bf
Parent:
120:4dc938e301cc
Child:
123:58563e6cba1e
RTOS rev121



Compatible with the mbed library v125



Changes:

- K64F: Revert to hardcoded stack pointer in RTX.

- Adding NCS36510 support.

- Add MAX32620 target support.

- Fix implicit declaration of function 'atexit'.

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"
Kojto 119:19af2d39a542 29 #include "Semaphore.h"
Kojto 119:19af2d39a542 30 #include "Mutex.h"
emilmont 6:350b53afb889 31
emilmont 6:350b53afb889 32 namespace rtos {
emilmont 6:350b53afb889 33
emilmont 8:88a1a9c26ae3 34 /** The Thread class allow defining, creating, and controlling thread functions in the system. */
emilmont 6:350b53afb889 35 class Thread {
emilmont 6:350b53afb889 36 public:
Kojto 118:6635230e06ba 37 /** Allocate a new thread without starting execution
Kojto 118:6635230e06ba 38 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 39 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 40 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 41 */
Kojto 118:6635230e06ba 42 Thread(osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 43 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 44 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 45 constructor(priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 46 }
Kojto 118:6635230e06ba 47
emilmont 8:88a1a9c26ae3 48 /** Create a new thread, and start it executing the specified function.
emilmont 8:88a1a9c26ae3 49 @param task function to be executed by this thread.
emilmont 8:88a1a9c26ae3 50 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
emilmont 8:88a1a9c26ae3 51 @param priority initial priority of the thread function. (default: osPriorityNormal).
emilmont 8:88a1a9c26ae3 52 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
emilmont 8:88a1a9c26ae3 53 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 54 @deprecated
Kojto 118:6635230e06ba 55 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 56 program state when a thread is declared.
Kojto 118:6635230e06ba 57
Kojto 118:6635230e06ba 58 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 59 a thread.
emilmont 6:350b53afb889 60 */
Kojto 120:4dc938e301cc 61 MBED_DEPRECATED_SINCE("mbed-os-5.1",
Kojto 118:6635230e06ba 62 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 63 "program state when a thread is declared")
Kojto 118:6635230e06ba 64 Thread(mbed::Callback<void()> task,
Kojto 118:6635230e06ba 65 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 66 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 67 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 68 constructor(task, priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 69 }
Kojto 118:6635230e06ba 70
Kojto 118:6635230e06ba 71 /** Create a new thread, and start it executing the specified function.
Kojto 118:6635230e06ba 72 @param obj argument to task.
Kojto 118:6635230e06ba 73 @param method function to be executed by this thread.
Kojto 118:6635230e06ba 74 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
Kojto 118:6635230e06ba 75 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 76 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 77 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 78 @deprecated
Kojto 118:6635230e06ba 79 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 80 program state when a thread is declared.
Kojto 118:6635230e06ba 81
Kojto 118:6635230e06ba 82 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 83 a thread.
Kojto 118:6635230e06ba 84 */
Kojto 118:6635230e06ba 85 template <typename T>
Kojto 120:4dc938e301cc 86 MBED_DEPRECATED_SINCE("mbed-os-5.1",
Kojto 118:6635230e06ba 87 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 88 "program state when a thread is declared")
Kojto 118:6635230e06ba 89 Thread(T *obj, void (T::*method)(),
Kojto 118:6635230e06ba 90 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 91 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 92 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 93 constructor(mbed::Callback<void()>(obj, method),
Kojto 118:6635230e06ba 94 priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 95 }
Kojto 118:6635230e06ba 96
Kojto 118:6635230e06ba 97 /** Create a new thread, and start it executing the specified function.
Kojto 118:6635230e06ba 98 @param obj argument to task.
Kojto 118:6635230e06ba 99 @param method function to be executed by this thread.
Kojto 118:6635230e06ba 100 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
Kojto 118:6635230e06ba 101 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 102 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 103 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 104 @deprecated
Kojto 118:6635230e06ba 105 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 106 program state when a thread is declared.
Kojto 118:6635230e06ba 107
Kojto 118:6635230e06ba 108 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 109 a thread.
Kojto 118:6635230e06ba 110 */
Kojto 118:6635230e06ba 111 template <typename T>
Kojto 120:4dc938e301cc 112 MBED_DEPRECATED_SINCE("mbed-os-5.1",
Kojto 118:6635230e06ba 113 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 114 "program state when a thread is declared")
Kojto 118:6635230e06ba 115 Thread(T *obj, void (*method)(T *),
Kojto 118:6635230e06ba 116 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 117 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 118 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 119 constructor(mbed::Callback<void()>(obj, method),
Kojto 118:6635230e06ba 120 priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 121 }
Kojto 118:6635230e06ba 122
Kojto 118:6635230e06ba 123 /** Create a new thread, and start it executing the specified function.
Kojto 118:6635230e06ba 124 Provided for backwards compatibility
Kojto 118:6635230e06ba 125 @param task function to be executed by this thread.
Kojto 118:6635230e06ba 126 @param argument pointer that is passed to the thread function as start argument. (default: NULL).
Kojto 118:6635230e06ba 127 @param priority initial priority of the thread function. (default: osPriorityNormal).
Kojto 118:6635230e06ba 128 @param stack_size stack size (in bytes) requirements for the thread function. (default: DEFAULT_STACK_SIZE).
Kojto 118:6635230e06ba 129 @param stack_pointer pointer to the stack area to be used by this thread (default: NULL).
Kojto 118:6635230e06ba 130 @deprecated
Kojto 118:6635230e06ba 131 Thread-spawning constructors hide errors and may lead to complex
Kojto 118:6635230e06ba 132 program state when a thread is declared.
Kojto 118:6635230e06ba 133
Kojto 118:6635230e06ba 134 The explicit Thread::start member function should be used to spawn
Kojto 118:6635230e06ba 135 a thread.
Kojto 118:6635230e06ba 136 */
Kojto 120:4dc938e301cc 137 MBED_DEPRECATED_SINCE("mbed-os-5.1",
Kojto 118:6635230e06ba 138 "Thread-spawning constructors hide errors and may lead to complex "
Kojto 118:6635230e06ba 139 "program state when a thread is declared")
emilmont 6:350b53afb889 140 Thread(void (*task)(void const *argument), void *argument=NULL,
emilmont 6:350b53afb889 141 osPriority priority=osPriorityNormal,
emilmont 6:350b53afb889 142 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 143 unsigned char *stack_pointer=NULL) {
Kojto 118:6635230e06ba 144 constructor(mbed::Callback<void()>(argument, (void (*)(void *))task),
Kojto 118:6635230e06ba 145 priority, stack_size, stack_pointer);
Kojto 118:6635230e06ba 146 }
Kojto 118:6635230e06ba 147
Kojto 118:6635230e06ba 148 /** Starts a thread executing the specified function.
Kojto 118:6635230e06ba 149 @param task function to be executed by this thread.
Kojto 118:6635230e06ba 150 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 151 */
Kojto 118:6635230e06ba 152 osStatus start(mbed::Callback<void()> task);
Kojto 118:6635230e06ba 153
Kojto 118:6635230e06ba 154 /** Starts a thread executing the specified function.
Kojto 118:6635230e06ba 155 @param obj argument to task
Kojto 118:6635230e06ba 156 @param method function to be executed by this thread.
Kojto 118:6635230e06ba 157 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 158 */
Kojto 118:6635230e06ba 159 template <typename T, typename M>
Kojto 118:6635230e06ba 160 osStatus start(T *obj, M method) {
Kojto 118:6635230e06ba 161 return start(mbed::Callback<void()>(obj, method));
Kojto 118:6635230e06ba 162 }
Kojto 118:6635230e06ba 163
Kojto 118:6635230e06ba 164 /** Wait for thread to terminate
Kojto 118:6635230e06ba 165 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 166 @note not callable from interrupt
Kojto 118:6635230e06ba 167 */
Kojto 118:6635230e06ba 168 osStatus join();
mbed_official 31:015df9e602b6 169
emilmont 8:88a1a9c26ae3 170 /** Terminate execution of a thread and remove it from Active Threads
emilmont 8:88a1a9c26ae3 171 @return status code that indicates the execution status of the function.
emilmont 6:350b53afb889 172 */
emilmont 6:350b53afb889 173 osStatus terminate();
mbed_official 31:015df9e602b6 174
emilmont 8:88a1a9c26ae3 175 /** Set priority of an active thread
emilmont 8:88a1a9c26ae3 176 @param priority new priority value for the thread function.
emilmont 8:88a1a9c26ae3 177 @return status code that indicates the execution status of the function.
emilmont 6:350b53afb889 178 */
emilmont 6:350b53afb889 179 osStatus set_priority(osPriority priority);
mbed_official 31:015df9e602b6 180
emilmont 8:88a1a9c26ae3 181 /** Get priority of an active thread
emilmont 8:88a1a9c26ae3 182 @return current priority value of the thread function.
emilmont 6:350b53afb889 183 */
emilmont 6:350b53afb889 184 osPriority get_priority();
mbed_official 31:015df9e602b6 185
emilmont 8:88a1a9c26ae3 186 /** Set the specified Signal Flags of an active thread.
emilmont 8:88a1a9c26ae3 187 @param signals specifies the signal flags of the thread that should be set.
emilmont 8:88a1a9c26ae3 188 @return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
emilmont 6:350b53afb889 189 */
emilmont 6:350b53afb889 190 int32_t signal_set(int32_t signals);
mbed_official 31:015df9e602b6 191
mbed_official 76:85a52b7ef44b 192 /** Clears the specified Signal Flags of an active thread.
mbed_official 76:85a52b7ef44b 193 @param signals specifies the signal flags of the thread that should be cleared.
mbed_official 76:85a52b7ef44b 194 @return resultant signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
mbed_official 76:85a52b7ef44b 195 */
mbed_official 76:85a52b7ef44b 196 int32_t signal_clr(int32_t signals);
mbed_official 76:85a52b7ef44b 197
emilmont 8:88a1a9c26ae3 198 /** State of the Thread */
emilmont 8:88a1a9c26ae3 199 enum State {
emilmont 8:88a1a9c26ae3 200 Inactive, /**< Not created or terminated */
emilmont 8:88a1a9c26ae3 201 Ready, /**< Ready to run */
emilmont 8:88a1a9c26ae3 202 Running, /**< Running */
emilmont 8:88a1a9c26ae3 203 WaitingDelay, /**< Waiting for a delay to occur */
emilmont 8:88a1a9c26ae3 204 WaitingInterval, /**< Waiting for an interval to occur */
emilmont 8:88a1a9c26ae3 205 WaitingOr, /**< Waiting for one event in a set to occur */
emilmont 8:88a1a9c26ae3 206 WaitingAnd, /**< Waiting for multiple events in a set to occur */
emilmont 8:88a1a9c26ae3 207 WaitingSemaphore, /**< Waiting for a semaphore event to occur */
emilmont 8:88a1a9c26ae3 208 WaitingMailbox, /**< Waiting for a mailbox event to occur */
emilmont 8:88a1a9c26ae3 209 WaitingMutex, /**< Waiting for a mutex event to occur */
Kojto 119:19af2d39a542 210
Kojto 119:19af2d39a542 211 /* Not in sync with RTX below here */
Kojto 119:19af2d39a542 212 Deleted, /**< The task has been deleted */
emilmont 8:88a1a9c26ae3 213 };
mbed_official 31:015df9e602b6 214
emilmont 8:88a1a9c26ae3 215 /** State of this Thread
emilmont 8:88a1a9c26ae3 216 @return the State of this Thread
emilmont 8:88a1a9c26ae3 217 */
emilmont 8:88a1a9c26ae3 218 State get_state();
mbed_official 84:143955ffb790 219
mbed_official 84:143955ffb790 220 /** Get the total stack memory size for this Thread
mbed_official 84:143955ffb790 221 @return the total stack memory size in bytes
mbed_official 84:143955ffb790 222 */
mbed_official 84:143955ffb790 223 uint32_t stack_size();
mbed_official 84:143955ffb790 224
mbed_official 84:143955ffb790 225 /** Get the currently unused stack memory for this Thread
mbed_official 84:143955ffb790 226 @return the currently unused stack memory in bytes
mbed_official 84:143955ffb790 227 */
mbed_official 84:143955ffb790 228 uint32_t free_stack();
mbed_official 84:143955ffb790 229
mbed_official 84:143955ffb790 230 /** Get the currently used stack memory for this Thread
mbed_official 84:143955ffb790 231 @return the currently used stack memory in bytes
mbed_official 84:143955ffb790 232 */
mbed_official 84:143955ffb790 233 uint32_t used_stack();
mbed_official 84:143955ffb790 234
mbed_official 84:143955ffb790 235 /** Get the maximum stack memory usage to date for this Thread
mbed_official 84:143955ffb790 236 @return the maximum stack memory usage to date in bytes
mbed_official 84:143955ffb790 237 */
mbed_official 84:143955ffb790 238 uint32_t max_stack();
mbed_official 31:015df9e602b6 239
mbed_official 31:015df9e602b6 240 /** Wait for one or more Signal Flags to become signaled for the current RUNNING thread.
emilmont 8:88a1a9c26ae3 241 @param signals wait until all specified signal flags set or 0 for any single signal flag.
emilmont 8:88a1a9c26ae3 242 @param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
emilmont 8:88a1a9c26ae3 243 @return event flag information or error code.
Kojto 118:6635230e06ba 244 @note not callable from interrupt
emilmont 6:350b53afb889 245 */
emilmont 6:350b53afb889 246 static osEvent signal_wait(int32_t signals, uint32_t millisec=osWaitForever);
mbed_official 31:015df9e602b6 247
emilmont 8:88a1a9c26ae3 248 /** Wait for a specified time period in millisec:
emilmont 8:88a1a9c26ae3 249 @param millisec time delay value
mbed_official 31:015df9e602b6 250 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 251 @note not callable from interrupt
emilmont 6:350b53afb889 252 */
emilmont 6:350b53afb889 253 static osStatus wait(uint32_t millisec);
mbed_official 31:015df9e602b6 254
emilmont 8:88a1a9c26ae3 255 /** Pass control to next thread that is in state READY.
emilmont 8:88a1a9c26ae3 256 @return status code that indicates the execution status of the function.
Kojto 118:6635230e06ba 257 @note not callable from interrupt
emilmont 6:350b53afb889 258 */
emilmont 6:350b53afb889 259 static osStatus yield();
mbed_official 31:015df9e602b6 260
emilmont 8:88a1a9c26ae3 261 /** Get the thread id of the current running thread.
emilmont 8:88a1a9c26ae3 262 @return thread ID for reference by other functions or NULL in case of error.
emilmont 6:350b53afb889 263 */
emilmont 6:350b53afb889 264 static osThreadId gettid();
mbed_official 107:bdd541595fc5 265
mbed_official 107:bdd541595fc5 266 /** Attach a function to be called by the RTOS idle task
mbed_official 107:bdd541595fc5 267 @param fptr pointer to the function to be called
mbed_official 107:bdd541595fc5 268 */
mbed_official 107:bdd541595fc5 269 static void attach_idle_hook(void (*fptr)(void));
mbed_official 31:015df9e602b6 270
emilmont 6:350b53afb889 271 virtual ~Thread();
emilmont 6:350b53afb889 272
emilmont 6:350b53afb889 273 private:
Kojto 118:6635230e06ba 274 // Required to share definitions without
Kojto 118:6635230e06ba 275 // delegated constructors
Kojto 118:6635230e06ba 276 void constructor(osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 277 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 278 unsigned char *stack_pointer=NULL);
Kojto 118:6635230e06ba 279 void constructor(mbed::Callback<void()> task,
Kojto 118:6635230e06ba 280 osPriority priority=osPriorityNormal,
Kojto 118:6635230e06ba 281 uint32_t stack_size=DEFAULT_STACK_SIZE,
Kojto 118:6635230e06ba 282 unsigned char *stack_pointer=NULL);
Kojto 119:19af2d39a542 283 static void _thunk(const void * thread_ptr);
Kojto 118:6635230e06ba 284
Kojto 118:6635230e06ba 285 mbed::Callback<void()> _task;
emilmont 6:350b53afb889 286 osThreadId _tid;
emilmont 6:350b53afb889 287 osThreadDef_t _thread_def;
emilmont 6:350b53afb889 288 bool _dynamic_stack;
Kojto 119:19af2d39a542 289 Semaphore _join_sem;
Kojto 119:19af2d39a542 290 Mutex _mutex;
emilmont 6:350b53afb889 291 };
emilmont 6:350b53afb889 292
emilmont 6:350b53afb889 293 }
emilmont 6:350b53afb889 294 #endif