mirror of https://github.com/ARMmbed/mbed-os.git
285 lines
11 KiB
C++
285 lines
11 KiB
C++
/* mbed Microcontroller Library
|
|
* Copyright (c) 2006-2019 ARM Limited
|
|
* SPDX-License-Identifier: MIT
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in
|
|
* all copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
* SOFTWARE.
|
|
*/
|
|
#ifndef THREAD_H
|
|
#define THREAD_H
|
|
|
|
#include <stdint.h>
|
|
#include "rtos/mbed_rtos_types.h"
|
|
#include "rtos/mbed_rtos1_types.h"
|
|
#include "rtos/mbed_rtos_storage.h"
|
|
#include "platform/Callback.h"
|
|
#include "platform/mbed_toolchain.h"
|
|
#include "platform/NonCopyable.h"
|
|
#include "rtos/Semaphore.h"
|
|
#include "rtos/Mutex.h"
|
|
|
|
#if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY) || defined(UNITTEST)
|
|
|
|
namespace rtos {
|
|
/** \addtogroup rtos-public-api */
|
|
/** @{*/
|
|
|
|
/**
|
|
* \defgroup rtos_Thread Thread class
|
|
* @{
|
|
*/
|
|
|
|
/** The Thread class allow defining, creating, and controlling thread functions in the system.
|
|
*
|
|
* Example:
|
|
* @code
|
|
* #include "mbed.h"
|
|
* #include "rtos.h"
|
|
*
|
|
* Thread thread;
|
|
* DigitalOut led1(LED1);
|
|
* volatile bool running = true;
|
|
*
|
|
* // Blink function toggles the led in a long running loop
|
|
* void blink(DigitalOut *led) {
|
|
* while (running) {
|
|
* *led = !*led;
|
|
* ThisThread::sleep_for(1000);
|
|
* }
|
|
* }
|
|
*
|
|
* // Spawns a thread to run blink for 5 seconds
|
|
* int main() {
|
|
* thread.start(callback(blink, &led1));
|
|
* ThisThread::sleep_for(5000);
|
|
* running = false;
|
|
* thread.join();
|
|
* }
|
|
* @endcode
|
|
*
|
|
* @note
|
|
* Memory considerations: The thread control structures will be created on current thread's stack, both for the mbed OS
|
|
* and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
|
|
* Additionally the stack memory for this thread will be allocated on the heap, if it wasn't supplied to the constructor.
|
|
*
|
|
* @note
|
|
* MBED_TZ_DEFAULT_ACCESS (default:0) flag can be used to change the default access of all user threads in non-secure mode.
|
|
* MBED_TZ_DEFAULT_ACCESS set to 1, means all non-secure user threads have access to call secure functions.
|
|
* MBED_TZ_DEFAULT_ACCESS set to 0, means none of the non-secure user thread have access to call secure functions,
|
|
* to give access to particular thread used overloaded constructor with `tz_module` as argument during thread creation.
|
|
*
|
|
* MBED_TZ_DEFAULT_ACCESS is target specific define, should be set in targets.json file for Cortex-M23/M33 devices.
|
|
*
|
|
* @note
|
|
* Bare metal profile: This class is not supported.
|
|
*/
|
|
|
|
class Thread : private mbed::NonCopyable<Thread> {
|
|
public:
|
|
/** Allocate a new thread without starting execution
|
|
@param priority initial priority of the thread function. (default: osPriorityNormal).
|
|
@param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
|
|
@param stack_mem pointer to the stack area to be used by this thread (default: nullptr).
|
|
@param name name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: nullptr)
|
|
|
|
@note Default value of tz_module will be MBED_TZ_DEFAULT_ACCESS
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
|
|
Thread(osPriority priority = osPriorityNormal,
|
|
uint32_t stack_size = OS_STACK_SIZE,
|
|
unsigned char *stack_mem = nullptr, const char *name = nullptr)
|
|
{
|
|
constructor(priority, stack_size, stack_mem, name);
|
|
}
|
|
|
|
/** Allocate a new thread without starting execution
|
|
@param tz_module trustzone thread identifier (osThreadAttr_t::tz_module)
|
|
Context of RTOS threads in non-secure state must be saved when calling secure functions.
|
|
tz_module ID is used to allocate context memory for threads, and it can be safely set to zero for
|
|
threads not using secure calls at all. See "TrustZone RTOS Context Management" for more details.
|
|
@param priority initial priority of the thread function. (default: osPriorityNormal).
|
|
@param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
|
|
@param stack_mem pointer to the stack area to be used by this thread (default: nullptr).
|
|
@param name name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: nullptr)
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
|
|
Thread(uint32_t tz_module, osPriority priority = osPriorityNormal,
|
|
uint32_t stack_size = OS_STACK_SIZE,
|
|
unsigned char *stack_mem = nullptr, const char *name = nullptr)
|
|
{
|
|
constructor(tz_module, priority, stack_size, stack_mem, name);
|
|
}
|
|
|
|
|
|
/** Starts a thread executing the specified function.
|
|
@param task function to be executed by this thread.
|
|
@return status code that indicates the execution status of the function.
|
|
@note a thread can only be started once
|
|
|
|
@note You cannot call this function ISR context.
|
|
*/
|
|
osStatus start(mbed::Callback<void()> task);
|
|
|
|
/** Wait for thread to terminate
|
|
@return status code that indicates the execution status of the function.
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
osStatus join();
|
|
|
|
/** Terminate execution of a thread and remove it from Active Threads
|
|
@return status code that indicates the execution status of the function.
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
osStatus terminate();
|
|
|
|
/** Set priority of an active thread
|
|
@param priority new priority value for the thread function.
|
|
@return status code that indicates the execution status of the function.
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
osStatus set_priority(osPriority priority);
|
|
|
|
/** Get priority of an active thread
|
|
@return current priority value of the thread function.
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
osPriority get_priority() const;
|
|
|
|
/** Set the specified Thread Flags for the thread.
|
|
@param flags specifies the flags of the thread that should be set.
|
|
@return thread flags after setting or osFlagsError in case of incorrect parameters.
|
|
|
|
@note You may call this function from ISR context.
|
|
*/
|
|
uint32_t flags_set(uint32_t flags);
|
|
|
|
/** State of the Thread */
|
|
enum State {
|
|
Inactive, /**< NOT USED */
|
|
Ready, /**< Ready to run */
|
|
Running, /**< Running */
|
|
WaitingDelay, /**< Waiting for a delay to occur */
|
|
WaitingJoin, /**< Waiting for thread to join. Only happens when using RTX directly. */
|
|
WaitingThreadFlag, /**< Waiting for a thread flag to be set */
|
|
WaitingEventFlag, /**< Waiting for a event flag to be set */
|
|
WaitingMutex, /**< Waiting for a mutex event to occur */
|
|
WaitingSemaphore, /**< Waiting for a semaphore event to occur */
|
|
WaitingMemoryPool, /**< Waiting for a memory pool */
|
|
WaitingMessageGet, /**< Waiting for message to arrive */
|
|
WaitingMessagePut, /**< Waiting for message to be send */
|
|
WaitingInterval, /**< NOT USED */
|
|
WaitingOr, /**< NOT USED */
|
|
WaitingAnd, /**< NOT USED */
|
|
WaitingMailbox, /**< NOT USED (Mail is implemented as MemoryPool and Queue) */
|
|
|
|
/* Not in sync with RTX below here */
|
|
Deleted, /**< The task has been deleted or not started */
|
|
};
|
|
|
|
/** State of this Thread
|
|
@return the State of this Thread
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
State get_state() const;
|
|
|
|
/** Get the total stack memory size for this Thread
|
|
@return the total stack memory size in bytes
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
uint32_t stack_size() const;
|
|
|
|
/** Get the currently unused stack memory for this Thread
|
|
@return the currently unused stack memory in bytes
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
uint32_t free_stack() const;
|
|
|
|
/** Get the currently used stack memory for this Thread
|
|
@return the currently used stack memory in bytes
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
uint32_t used_stack() const;
|
|
|
|
/** Get the maximum stack memory usage to date for this Thread
|
|
@return the maximum stack memory usage to date in bytes
|
|
|
|
@note You cannot call this function from ISR context.
|
|
*/
|
|
uint32_t max_stack() const;
|
|
|
|
/** Get thread name
|
|
@return thread name or nullptr if the name was not set.
|
|
|
|
@note You may call this function from ISR context.
|
|
*/
|
|
const char *get_name() const;
|
|
|
|
/** Get thread id
|
|
@return thread ID for reference by other functions.
|
|
|
|
@note You may call this function from ISR context.
|
|
*/
|
|
osThreadId_t get_id() const;
|
|
|
|
/** Thread destructor
|
|
*
|
|
* @note You cannot call this function from ISR context.
|
|
*/
|
|
virtual ~Thread();
|
|
|
|
private:
|
|
// Required to share definitions without
|
|
// delegated constructors
|
|
void constructor(osPriority priority = osPriorityNormal,
|
|
uint32_t stack_size = OS_STACK_SIZE,
|
|
unsigned char *stack_mem = nullptr,
|
|
const char *name = nullptr);
|
|
void constructor(uint32_t tz_module,
|
|
osPriority priority = osPriorityNormal,
|
|
uint32_t stack_size = OS_STACK_SIZE,
|
|
unsigned char *stack_mem = nullptr,
|
|
const char *name = nullptr);
|
|
static void _thunk(void *thread_ptr);
|
|
|
|
mbed::Callback<void()> _task;
|
|
osThreadId_t _tid;
|
|
osThreadAttr_t _attr;
|
|
bool _dynamic_stack;
|
|
bool _finished;
|
|
Semaphore _join_sem;
|
|
mutable Mutex _mutex;
|
|
mbed_rtos_storage_thread_t _obj_mem;
|
|
};
|
|
/** @}*/
|
|
/** @}*/
|
|
}
|
|
#endif
|
|
|
|
#endif
|