Add notes about ISR safety to RTOS doxygen

rtos/ConditionVariable.h

@@ -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:

rtos/EventFlags.h

@@ -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:

rtos/Mail.h

@@ -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);

rtos/MemoryPool.h

@@ -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);

rtos/Mutex.h

@@ -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:

rtos/Queue.h

@@ -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;

rtos/RtosTimer.h

@@ -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:

rtos/Semaphore.h

@@ -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:

rtos/Thread.h

@@ -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: