ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add notes about ISR safety to RTOS doxygen

pull/5760/head
Bartek Szatkowski 2017-12-27 14:46:00 +00:00
parent 9cce4d2b06
commit 71555a984d
9 changed files with 184 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
rtos/ConditionVariable.h
View File

@ -118,7 +118,10 @@ struct Waiter;
*/
class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {
public:
/** Create and Initialize a ConditionVariable object */
/** Create and Initialize a ConditionVariable object
*
* @note This function may be called from ISR context.
*/
ConditionVariable(Mutex &mutex);
/** Wait for a notification
@ -142,6 +145,8 @@ public:
*
* mutex.unlock();
* @endcode
*
* @note This function cannot be called from ISR context.
*/
void wait();
@ -176,21 +181,31 @@ public:
*
* mutex.unlock();
* @endcode
*
* @note This function cannot be called from ISR context.
*/
bool wait_for(uint32_t millisec);
/** Notify one waiter on this condition variable that a condition changed.
*
* @note - The thread calling this function must be the owner of the ConditionVariable's mutex
*
* @note This function may be called from ISR context.
*/
void notify_one();
/** Notify all waiters on this condition variable that a condition changed.
*
* @note - The thread calling this function must be the owner of the ConditionVariable's mutex
*
* @note This function may be called from ISR context.
*/
void notify_all();
/** ConditionVariable destructor
*
* @note This function may be called from ISR context.
*/
~ConditionVariable();
protected:

21
rtos/EventFlags.h
View File

@ -46,29 +46,40 @@ namespace rtos {
*/
class EventFlags : private mbed::NonCopyable<EventFlags> {
public:
/** Create and Initialize a EventFlags object */
/** Create and Initialize a EventFlags object
*
* @note This function cannot be called from ISR context.
*/
EventFlags();
/** Create and Initialize a EventFlags object
@param name name to be used for this EventFlags. It has to stay allocated for the lifetime of the thread.
@note This function cannot be called from ISR context.
*/
EventFlags(const char *name);
/** Set the specified Event Flags.
@param flags specifies the flags that shall be set.
@return event flags after setting or error code if highest bit set (@a osFlagsError).
@note This function may be called from ISR context.
*/
uint32_t set(uint32_t flags);
/** Clear the specified Event Flags.
@param flags specifies the flags that shall be cleared. (default: 0x7fffffff - all flags)
@return event flags before clearing or error code if highest bit set (@a osFlagsError).
@note This function may be called from ISR context.
*/
uint32_t clear(uint32_t flags = 0x7fffffff);
/** Get the currently set Event Flags.
@return set event flags.
@note This function may be called from ISR context.
*/
uint32_t get() const;
@ -77,6 +88,8 @@ public:
@param timeout timeout value or 0 in case of no time-out. (default: osWaitForever)
@param clear specifies wether to clear the flags after waiting for them. (default: true)
@return event flags before clearing or error code if highest bit set (@a osFlagsError).
@note This function may be called from ISR context if the timeout parameter is set to 0.
*/
uint32_t wait_all(uint32_t flags = 0, uint32_t timeout = osWaitForever, bool clear = true);
@ -85,9 +98,15 @@ public:
@param timeout timeout value or 0 in case of no time-out. (default: osWaitForever)
@param clear specifies wether to clear the flags after waiting for them. (default: true)
@return event flags before clearing or error code if highest bit set (@a osFlagsError).
@note This function may be called from ISR context if the timeout parameter is set to 0.
*/
uint32_t wait_any(uint32_t flags = 0, uint32_t timeout = osWaitForever, bool clear = true);
/** Event flags destructor
@note This function cannot be called from ISR context.
*/
~EventFlags();
private:

19
rtos/Mail.h
View File

@ -55,12 +55,17 @@ namespace rtos {
template<typename T, uint32_t queue_sz>
class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
public:
/** Create and Initialise Mail queue. */
/** Create and Initialise Mail queue.
*
* @note This function cannot be called from ISR context.
*/
Mail() { };
/** Check if the mail queue is empty
*
* @return True if the mail queue is empty, false if not
*
* @note This function may be called from ISR context.
*/
bool empty() const {
return _queue.empty();
@ -69,6 +74,8 @@ public:
/** Check if the mail queue is full
*
* @return True if the mail queue is full, false if not
*
* @note This function may be called from ISR context.
*/
bool full() const {
return _queue.full();
@ -77,6 +84,8 @@ public:
/** Allocate a memory block of type T
@param millisec timeout value or 0 in case of no time-out. (default: 0).
@return pointer to memory block that can be filled with mail or NULL in case error.
@note This function may be called from ISR context if the millisec parameter is set to 0.
*/
T* alloc(uint32_t millisec=0) {
return _pool.alloc();
@ -85,6 +94,8 @@ public:
/** Allocate a memory block of type T and set memory block to zero.
@param millisec timeout value or 0 in case of no time-out. (default: 0).
@return pointer to memory block that can be filled with mail or NULL in case error.
@note This function may be called from ISR context if the millisec parameter is set to 0.
*/
T* calloc(uint32_t millisec=0) {
return _pool.calloc();
@ -93,6 +104,8 @@ public:
/** Put a mail in the queue.
@param mptr memory block previously allocated with Mail::alloc or Mail::calloc.
@return status code that indicates the execution status of the function.
@note This function may be called from ISR context.
*/
osStatus put(T *mptr) {
return _queue.put(mptr);
@ -101,6 +114,8 @@ public:
/** Get a mail from a queue.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return event that contains mail information or error code.
@note This function may be called from ISR context if the millisec parameter is set to 0.
*/
osEvent get(uint32_t millisec=osWaitForever) {
osEvent evt = _queue.get(millisec);
@ -113,6 +128,8 @@ public:
/** Free a memory block from a mail.
@param mptr pointer to the memory block that was obtained with Mail::get.
@return status code that indicates the execution status of the function.
@note This function may be called from ISR context.
*/
osStatus free(T *mptr) {
return _pool.free(mptr);

15
rtos/MemoryPool.h
View File

@ -50,7 +50,10 @@ template<typename T, uint32_t pool_sz>
class MemoryPool : private mbed::NonCopyable<MemoryPool<T, pool_sz> > {
MBED_STATIC_ASSERT(pool_sz > 0, "Invalid memory pool size. Must be greater than 0.");
public:
/** Create and Initialize a memory pool. */
/** Create and Initialize a memory pool.
*
* @note This function cannot be called from ISR context.
*/
MemoryPool() {
memset(_pool_mem, 0, sizeof(_pool_mem));
memset(&_obj_mem, 0, sizeof(_obj_mem));
@ -63,13 +66,18 @@ public:
MBED_ASSERT(_id);
}
/** Destroy a memory pool */
/** Destroy a memory pool
*
* @note This function cannot be called from ISR context.
*/
~MemoryPool() {
osMemoryPoolDelete(_id);
}
/** Allocate a memory block of type T from a memory pool.
@return address of the allocated memory block or NULL in case of no memory available.
@note This function may be called from ISR context.
*/
T* alloc(void) {
return (T*)osMemoryPoolAlloc(_id, 0);
@ -77,6 +85,8 @@ public:
/** Allocate a memory block of type T from a memory pool and set memory block to zero.
@return address of the allocated memory block or NULL in case of no memory available.
@note This function may be called from ISR context.
*/
T* calloc(void) {
T *item = (T*)osMemoryPoolAlloc(_id, 0);
@ -92,6 +102,7 @@ public:
is NULL or invalid, or osErrorResource if given memory block is in an
invalid memory pool state.
@note This function may be called from ISR context.
*/
osStatus free(T *block) {
return osMemoryPoolFree(_id, (void*)block);

22
rtos/Mutex.h
View File

@ -40,18 +40,26 @@ namespace rtos {
/** The Mutex class is used to synchronize the execution of threads.
This is for example used to protect access to a shared resource.
@note Member functions of this class cannot be used in ISR context. If you require Mutex functionality within
ISR handler consider using @a Semaphore.
@note
Memory considerations: The mutex 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).
*/
class Mutex : private mbed::NonCopyable<Mutex> {
public:
/** Create and Initialize a Mutex object */
/** Create and Initialize a Mutex object
*
* @note This function cannot be called from ISR context.
*/
Mutex();
/** Create and Initialize a Mutex object
@param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
@note This function cannot be called from ISR context.
*/
Mutex(const char *name);
@ -63,11 +71,15 @@ public:
@a osErrorParameter internal error.
@a osErrorResource the mutex could not be obtained when no timeout was specified.
@a osErrorISR this function cannot be called from the interrupt service routine.
@note This function cannot be called from ISR context.
*/
osStatus lock(uint32_t millisec=osWaitForever);
/** Try to lock the mutex, and return immediately
@return true if the mutex was acquired, false otherwise.
@note This function cannot be called from ISR context.
*/
bool trylock();
@ -77,14 +89,22 @@ public:
@a osErrorParameter internal error.
@a osErrorResource the mutex was not locked or the current thread wasn't the owner.
@a osErrorISR this function cannot be called from the interrupt service routine.
@note This function cannot be called from ISR context.
*/
osStatus unlock();
/** Get the owner the this mutex
@return the current owner of this mutex.
@note This function cannot be called from ISR context.
*/
osThreadId get_owner();
/** Mutex destructor
*
* @note This function cannot be called from ISR context.
*/
~Mutex();
private:

18
rtos/Queue.h
View File

@ -52,7 +52,10 @@ namespace rtos {
template<typename T, uint32_t queue_sz>
class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
public:
/** Create and initialize a message Queue. */
/** Create and initialize a message Queue.
*
* @note This function cannot be called from ISR context.
*/
Queue() {
memset(&_obj_mem, 0, sizeof(_obj_mem));
osMessageQueueAttr_t attr = { 0 };
@ -63,7 +66,10 @@ public:
_id = osMessageQueueNew(queue_sz, sizeof(T*), &attr);
MBED_ASSERT(_id);
}
/** Queue destructor
*
* @note This function cannot be called from ISR context.
*/
~Queue() {
osMessageQueueDelete(_id);
}
@ -71,6 +77,8 @@ public:
/** Check if the queue is empty
*
* @return True if the queue is empty, false if not
*
* @note This function may be called from ISR context.
*/
bool empty() const {
return osMessageQueueGetCount(_id) == 0;
@ -79,6 +87,8 @@ public:
/** Check if the queue is full
*
* @return True if the queue is full, false if not
*
* @note This function may be called from ISR context.
*/
bool full() const {
return osMessageQueueGetSpace(_id) == 0;
@ -93,6 +103,8 @@ public:
@a osErrorTimeout the message could not be put into the queue in the given time.
@a osErrorResource not enough space in the queue.
@a osErrorParameter internal error or non-zero timeout specified in an ISR.
@note This function may be called from ISR context if the millisec parameter is set to 0.
*/
osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
return osMessageQueuePut(_id, &data, prio, millisec);
@ -106,6 +118,8 @@ public:
@a osOK no message is available in the queue and no timeout was specified.
@a osEventTimeout no message has arrived during the given timeout period.
@a osErrorParameter a parameter is invalid or outside of a permitted range.
@note This function may be called from ISR context if the millisec parameter is set to 0.
*/
osEvent get(uint32_t millisec=osWaitForever) {
osEvent event;

14
rtos/RtosTimer.h
View File

@ -93,6 +93,8 @@ public:
@deprecated Replaced with RtosTimer(Callback<void()>, os_timer_type)
@deprecated
The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
@note This function cannot be called from ISR context.
*/
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Replaced with RtosTimer(Callback<void()>, os_timer_type)")
@ -107,6 +109,8 @@ public:
@param type osTimerOnce for one-shot or osTimerPeriodic for periodic behaviour. (default: osTimerPeriodic)
@deprecated
The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
@note This function cannot be called from ISR context.
*/
MBED_DEPRECATED_SINCE("mbed-os-5.2",
"The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
@ -123,6 +127,8 @@ public:
RtosTimer(callback(obj, method), os_timer_type).
@deprecated
The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
@note This function cannot be called from ISR context.
*/
template <typename T, typename M>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
@ -140,6 +146,8 @@ public:
@a osErrorISR @a stop cannot be called from interrupt service routines.
@a osErrorParameter internal error.
@a osErrorResource the timer is not running.
@note This function cannot be called from ISR context.
*/
osStatus stop(void);
@ -150,9 +158,15 @@ public:
@a osErrorISR @a start cannot be called from interrupt service routines.
@a osErrorParameter internal error or incorrect parameter value.
@a osErrorResource internal error (the timer is in an invalid timer state).
@note This function cannot be called from ISR context.
*/
osStatus start(uint32_t millisec);
/** RtosTimer destructor
*
* @note This function cannot be called from ISR context.
*/
~RtosTimer();
private:

12
rtos/Semaphore.h
View File

@ -46,18 +46,24 @@ class Semaphore : private mbed::NonCopyable<Semaphore> {
public:
/** Create and Initialize a Semaphore object used for managing resources.
@param count number of available resources; maximum index value is (count-1). (default: 0).
@note This function cannot be called from ISR context.
*/
Semaphore(int32_t count=0);
/** Create and Initialize a Semaphore object used for managing resources.
@param count number of available resources
@param max_count maximum number of available resources
@note This function cannot be called from ISR context.
*/
Semaphore(int32_t count, uint16_t max_count);
/** Wait until a Semaphore resource becomes available.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return number of available tokens, before taking one; or -1 in case of incorrect parameters
@note This function may be called from ISR context if the millisec parameter is set to 0.
*/
int32_t wait(uint32_t millisec=osWaitForever);
@ -66,9 +72,15 @@ public:
@a osOK the token has been correctly released.
@a osErrorResource the maximum token count has been reached.
@a osErrorParameter internal error.
@note This function may be called from ISR context.
*/
osStatus release(void);
/** Semaphore destructor
*
* @note This function cannot be called from ISR context.
*/
~Semaphore();
private:

57
rtos/Thread.h
View File

@ -80,6 +80,8 @@ public:
@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: NULL).
@param name name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: NULL)
@note This function cannot be called from ISR context.
*/
Thread(osPriority priority=osPriorityNormal,
uint32_t stack_size=OS_STACK_SIZE,
@ -103,6 +105,8 @@ public:
error("oh no!");
}
@endcode
@note This function cannot be called from ISR context.
*/
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Thread-spawning constructors hide errors. "
@ -131,6 +135,8 @@ public:
error("oh no!");
}
@endcode
@note This function cannot be called from ISR context.
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
@ -161,6 +167,8 @@ public:
error("oh no!");
}
@endcode
@note This function cannot be called from ISR context.
*/
template <typename T>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
@ -192,6 +200,8 @@ public:
error("oh no!");
}
@endcode
@note This function cannot be called from ISR context.
*/
MBED_DEPRECATED_SINCE("mbed-os-5.1",
"Thread-spawning constructors hide errors. "
@ -208,6 +218,8 @@ public:
@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 This function cannot be called from ISR context.
*/
osStatus start(mbed::Callback<void()> task);
@ -217,6 +229,8 @@ public:
@return status code that indicates the execution status of the function.
@deprecated
The start function does not support cv-qualifiers. Replaced by start(callback(obj, method)).
@note This function cannot be called from ISR context.
*/
template <typename T, typename M>
MBED_DEPRECATED_SINCE("mbed-os-5.1",
@ -229,28 +243,38 @@ public:
/** Wait for thread to terminate
@return status code that indicates the execution status of the function.
@note not callable from interrupt
@note This function cannot be called 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 This function cannot be called 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 This function cannot be called from ISR context.
*/
osStatus set_priority(osPriority priority);
/** Get priority of an active thread
@return current priority value of the thread function.
@note This function cannot be called from ISR context.
*/
osPriority get_priority();
/** Set the specified Thread Flags for the thread.
@param signals specifies the signal flags of the thread that should be set.
@return signal flags after setting or osFlagsError in case of incorrect parameters.
@note This function may be called from ISR context.
*/
int32_t signal_set(int32_t signals);
@ -279,37 +303,51 @@ public:
/** State of this Thread
@return the State of this Thread
@note This function cannot be called from ISR context.
*/
State get_state();
/** Get the total stack memory size for this Thread
@return the total stack memory size in bytes
@note This function cannot be called from ISR context.
*/
uint32_t stack_size();
/** Get the currently unused stack memory for this Thread
@return the currently unused stack memory in bytes
@note This function cannot be called from ISR context.
*/
uint32_t free_stack();
/** Get the currently used stack memory for this Thread
@return the currently used stack memory in bytes
@note This function cannot be called from ISR context.
*/
uint32_t used_stack();
/** Get the maximum stack memory usage to date for this Thread
@return the maximum stack memory usage to date in bytes
@note This function cannot be called from ISR context.
*/
uint32_t max_stack();
/** Get thread name
@return thread name or NULL if the name was not set.
@note This function may be called from ISR context.
*/
const char *get_name();
/** Clears the specified Thread Flags of the currently running thread.
@param signals specifies the signal flags of the thread that should be cleared.
@return signal flags before clearing or osFlagsError in case of incorrect parameters.
@note This function cannot be called from ISR context.
*/
static int32_t signal_clr(int32_t signals);
@ -317,38 +355,51 @@ public:
@param signals wait until all specified signal flags are set or 0 for any single signal flag.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return event flag information or error code. @note if @a millisec is set to 0 and flag is no set the event carries osOK value.
@note not callable from interrupt
@note This function cannot be called from ISR context.
*/
static osEvent signal_wait(int32_t signals, uint32_t millisec=osWaitForever);
/** Wait for a specified time period in millisec:
@param millisec time delay value
@return status code that indicates the execution status of the function.
@note not callable from interrupt
@note This function cannot be called from ISR context.
*/
static osStatus wait(uint32_t millisec);
/** Pass control to next thread that is in state READY.
@return status code that indicates the execution status of the function.
@note not callable from interrupt
@note This function cannot be called from ISR context.
*/
static osStatus yield();
/** Get the thread id of the current running thread.
@return thread ID for reference by other functions or NULL in case of error.
@note This function may be called from ISR context.
*/
static osThreadId gettid();
/** Attach a function to be called by the RTOS idle task
@param fptr pointer to the function to be called
@note This function may be called from ISR context.
*/
static void attach_idle_hook(void (*fptr)(void));
/** Attach a function to be called when a task is killed
@param fptr pointer to the function to be called
@note This function may be called from ISR context.
*/
static void attach_terminate_hook(void (*fptr)(osThreadId id));
/** Thread destructor
*
* @note This function cannot be called from ISR context.
*/
virtual ~Thread();
private: