RTOS: Changes to the EvenFlags API, doxy and tests

Author: bulislaw

TESTS/mbedmicro-rtos-mbed/event_flags/main.cpp

@@ -1,3 +1,20 @@
+/*
+ * Copyright (c) 2013-2017, ARM Limited, All Rights Reserved
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 #include "mbed.h"
 #include "greentea-client/test_env.h"
 #include "rtos.h"
@@ -10,37 +27,33 @@
 
 #define   EVENT_SET_VALUE    0x01
 const int EVENT_TO_EMIT = 100;
-const int EVENT_HANDLE_DELEY = 25;
+const int EVENT_HANDLE_DELAY = 25;
 
 DigitalOut led(LED1);
-EventFlags event_flags();
+EventFlags event_flags;
 
 int events_counter = 0;
 
 void led_thread() {
     while (true) {
-        // events flags that are reported as event are automatically cleared.
-        event_flags.wait(EVENT_SET_VALUE);
+        event_flags.wait_all(EVENT_SET_VALUE);
         led = !led;
         events_counter++;
     }
 }
 
 int main (void) {
-    GREENTEA_SETUP(20, "default_auto");
+    GREENTEA_SETUP(10, "default_auto");
 
     Thread thread(osPriorityNormal, TEST_STACK_SIZE);
     thread.start(led_thread);
 
     bool result = false;
 
-    printf("Handling %d events...\r\n", EVENT_TO_EMIT);
-
     while (true) {
-        Thread::wait(2 * EVENT_HANDLE_DELEY);
+        Thread::wait(2 * EVENT_HANDLE_DELAY);
         event_flags.set(EVENT_SET_VALUE);
         if (events_counter == EVENT_TO_EMIT) {
-            printf("Handled %d events\r\n", events_counter);
             result = true;
             break;
         }

rtos/EventFlags.cpp

@@ -26,15 +26,18 @@
 
 namespace rtos {
 
-EventFlags::EventFlags() {
+EventFlags::EventFlags()
+{
     constructor();
 }
 
-EventFlags::EventFlags(const char *name) {
+EventFlags::EventFlags(const char *name)
+{
     constructor(name);
 }
 
-void EventFlags::constructor(const char *name) {
+void EventFlags::constructor(const char *name)
+{
     memset(&_obj_mem, 0, sizeof(_obj_mem));
     memset(&_attr, 0, sizeof(_attr));
     _attr.name = name ? name : "application_unnamed_event_flags";
@@ -44,27 +47,43 @@ void EventFlags::constructor(const char *name) {
     MBED_ASSERT(_id);
 }
 
-uint32_t EventFlags::set(uint32_t flags) {
+uint32_t EventFlags::set(uint32_t flags)
+{
     return osEventFlagsSet(_id, flags);
 }
 
-uint32_t EventFlags::clear(uint32_t flags) {
+uint32_t EventFlags::clear(uint32_t flags)
+{
     return osEventFlagsClear(_id, flags);
 }
 
-uint32_t EventFlags::get() {
+uint32_t EventFlags::get() const
+{
     return osEventFlagsGet(_id);
 }
 
-uint32_t EventFlags::wait(uint32_t flags, uint32_t timeout) {
-    if(flags == 0) {
-        return osEventFlagsWait(_id, 0x7fffffff, osFlagsWaitAny | osFlagsNoClear, timeout); 
-    }
-    return osEventFlagsWait(_id, flags, osFlagsWaitAll, timeout);
+uint32_t EventFlags::wait_all(uint32_t flags, uint32_t timeout, bool clear)
+{
+    return wait(flags, osFlagsWaitAll, timeout, clear);
+}
+
+uint32_t EventFlags::wait_any(uint32_t flags, uint32_t timeout, bool clear)
+{
+    return wait(flags, osFlagsWaitAny, timeout, clear);
 }
 
-EventFlags::~EventFlags() {
+EventFlags::~EventFlags()
+{
     osEventFlagsDelete(_id);
 }
 
+uint32_t EventFlags::wait(uint32_t flags, uint32_t opt, uint32_t timeout, bool clear)
+{
+    if (clear == false) {
+        opt |= osFlagsNoClear;
+    }
+
+    return osEventFlagsWait(_id, flags, opt, timeout);
+}
+
 }

rtos/EventFlags.h

@@ -33,9 +33,9 @@ namespace rtos {
 /** \addtogroup rtos */
 /** @{*/
 
-/** The EventFlags class is used to signal to whom it may concern about an event has occured.
+/** The EventFlags class is used to signal or wait for an arbitrary event or events.
  @note 
- EventFlags support 31 flags so the MSB flag is ignored, it is used to return error code (osFlagsError)
+ EventFlags support 31 flags so the MSB flag is ignored, it is used to return an error code (@a osFlagsError)
  @note
  Memory considerations: The EventFlags 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).
@@ -52,35 +52,43 @@ class EventFlags : private mbed::NonCopyable<EventFlags> {
     EventFlags(const char *name);
 
     /** Set the specified Event Flags.
-      @param   flags  specifies the flags that shall be set. (default: 0x7fffffff)
-      @return  event flags after setting or error code if highest bit set (osFlagsError).
+      @param   flags  specifies the flags that shall be set.
+      @return  event flags after setting or error code if highest bit set (@a osFlagsError).
      */
-    uint32_t set(uint32_t flags = 0x7fffffff);
+    uint32_t set(uint32_t flags);
 
     /** Clear the specified Event Flags.
-      @param   flags  specifies the flags that shall be cleared. (default: 0x7fffffff0)
-      @return  event flags before clearing or error code if highest bit set (osFlagsError).
+      @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).
      */
     uint32_t clear(uint32_t flags = 0x7fffffff);
 
-    /** Get the current Event Flags.
-      @return  current event flags.
+    /** Get the currently set Event Flags.
+      @return  set event flags.
      */
-    uint32_t get();
+    uint32_t get() const;
 
-    /** Wait for one or more Event Flags to become signaled.
+    /** Wait for all of the specified event flags to become signaled.
+      @param   flags    specifies the flags to wait for.
+      @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).
+     */
+    uint32_t wait_all(uint32_t flags = 0, uint32_t timeout = osWaitForever, bool clear = true);
+
+    /** Wait for any of the specified event flags to become signaled.
       @param   flags    specifies the flags to wait for. (default: 0)
       @param   timeout  timeout value or 0 in case of no time-out. (default: osWaitForever)
-      @return  event flags before clearing or error code if highest bit set (osFlagsError).
-      @note    incase of flags 0 the function will wait to any flag and will not clear the flags, 
-               the user must clear the flags. otherwise the function to wait all specified flags and clear them. 
+      @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).
      */
-    uint32_t wait(uint32_t flags = 0, uint32_t timeout = osWaitForever);
+    uint32_t wait_any(uint32_t flags = 0, uint32_t timeout = osWaitForever, bool clear = true);
 
     ~EventFlags();
 
 private:
     void constructor(const char *name = NULL);
+    uint32_t wait(uint32_t flags, uint32_t opt, uint32_t timeout, bool clear);
     osEventFlagsId_t                _id;
     osEventFlagsAttr_t              _attr;
     mbed_rtos_storage_event_flags_t _obj_mem;