add standard mutex support and add tracking capability such that a unit test can detect if a mutex remained in a lock'd state at the end of a unit test.

Author: mattheweshleman

cpputest-for-freertos-lib/CMakeLists.txt

@@ -42,6 +42,7 @@ add_library(cpputest-for-freertos-lib
         src/cpputest_for_freertos_timers.cpp
         src/cpputest_main.cpp
         src/cpputest_for_freertos_semaphore.cpp
+        src/cpputest_for_freertos_mutex.cpp
         include/cpputest_for_freertos_lib.hpp
 )
 

cpputest-for-freertos-lib/include/cpputest_for_freertos_lib.hpp

@@ -27,6 +27,7 @@
 #include "cpputest_for_freertos_assert.hpp"
 #include "cpputest_for_freertos_task.hpp"
 #include "cpputest_for_freertos_timers.hpp"
+#include "cpputest_for_freertos_mutex.hpp"
 
 namespace cms {
     namespace test {
@@ -38,13 +39,15 @@ namespace cms {
             TaskInit();
             AssertOutputEnable();
             TimersInit();
+            MutexTrackingInit();
         }
 
         /**
          * call this in your unit test teardown() method to correctly
          * destroy/teardown all available CppUTest for FreeRTOS modules.
          */
         void LibTeardownAll() {
+            MutexTrackingTeardown();
             TimersDestroy();
             TaskDestroy();
         }

cpputest-for-freertos-lib/include/cpputest_for_freertos_mutex.hpp

@@ -0,0 +1,33 @@
+
+#ifndef CPPUTEST_FOR_FREERTOS_LIB_CPPUTEST_FOR_FREERTOS_MUTEX_HPP
+#define CPPUTEST_FOR_FREERTOS_LIB_CPPUTEST_FOR_FREERTOS_MUTEX_HPP
+
+namespace cms {
+namespace test {
+
+    /**
+     * Initialize the mutex state tracking,
+     * such that this unit test, when Teardown is called,
+     * will confirm that all mutexes are unlocked.
+     */
+    void MutexTrackingInit();
+
+    /**
+     * Check the state of any active mutexes.
+     * If a mutex is found to be locked, then that is considered
+     * a test failure. i.e. confirm that all mutex usage during
+     * a unit test locks and then unlocks.
+     */
+    void MutexTrackingTeardown();
+
+    /**
+     * Check if any active mutexes are in a locked
+     * state.
+     * @return
+     */
+    bool IsAnyMutexLocked();
+
+} //namespace
+}//namespace
+
+#endif //CPPUTEST_FOR_FREERTOS_LIB_CPPUTEST_FOR_FREERTOS_MUTEX_HPP

cpputest-for-freertos-lib/src/cpputest_for_freertos_mutex.cpp

@@ -0,0 +1,110 @@
+/// @brief Provides an implementation of a fake FreeRTOS semaphore
+///        which, like FreeRTOS, is under the hood a queue.
+///        cpputest-for-freertos-lib assumes that a queue should be
+///        functional, i.e. not a mock. No blocking is implemented.
+///
+/// @ingroup
+/// @cond
+///***************************************************************************
+///
+/// Copyright (C) 2024 Matthew Eshleman. All rights reserved.
+///
+/// This program is open source software: you can redistribute it and/or
+/// modify it under the terms of the GNU General Public License as published
+/// by the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, upon written permission from Matthew Eshleman, this program
+/// may be distributed and modified under the terms of a Commercial
+/// License. For further details, see the Contact Information below.
+///
+/// Contact Information:
+///   Matthew Eshleman
+///   https://covemountainsoftware.com
+///   [email protected]
+///***************************************************************************
+/// @endcond
+
+#include <list>
+#include <algorithm>
+#include "cpputest_for_freertos_fake_queue.hpp"
+#include "cpputest_for_freertos_mutex.hpp"
+#include "queue.h"
+#include "semphr.h"
+
+//must be last
+#include "CppUTest/TestHarness.h"
+
+namespace cms {
+    namespace test {
+
+        static std::list<QueueHandle_t>* s_mutexes = nullptr;
+
+        void MutexTrackingInit()
+        {
+            configASSERT(s_mutexes == nullptr);
+            s_mutexes = new std::list<QueueHandle_t>;
+        }
+
+        void MutexTrackingTeardown()
+        {
+            if (s_mutexes == nullptr)
+                return;
+
+            bool isAnyLocked = IsAnyMutexLocked();
+
+            s_mutexes->clear();
+            delete s_mutexes;
+            s_mutexes = nullptr;
+
+            if (isAnyLocked)
+            {
+                FAIL_TEST("A mutex is still active and locked. Test expects all mutexes to be unlocked.");
+            }
+        }
+
+        bool IsAnyMutexLocked()
+        {
+            if (s_mutexes == nullptr)
+                return false;
+
+            return std::any_of(s_mutexes->begin(), s_mutexes->end(), [](QueueDefinition* mutex)
+            {
+                return uxSemaphoreGetCount(mutex) == 0;
+            });
+        }
+
+        void MutexAboutToDelete(QueueHandle_t mutex)
+        {
+            if (s_mutexes == nullptr)
+                return;
+
+            s_mutexes->remove(mutex);
+        }
+    } //namespace
+}//namespace
+
+extern "C" QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType )
+{
+    (void)ucQueueType;
+    auto mutex = xQueueGenericCreate(1, 0, ucQueueType);
+    switch (ucQueueType) {
+        case queueQUEUE_TYPE_MUTEX:
+            //wasn't documented, but in experiment, the standard mutex is created unlocked
+            //(i.e) with one token available
+            xSemaphoreGive(mutex);
+            break;
+        case queueQUEUE_TYPE_RECURSIVE_MUTEX:
+            //todo
+            break;
+        default:
+            configASSERT(true == false);
+            break;
+    }
+    configASSERT(mutex != nullptr);
+    if (cms::test::s_mutexes != nullptr)
+    {
+        cms::test::s_mutexes->push_back(mutex);
+    }
+    return mutex;
+}

cpputest-for-freertos-lib/src/cpputest_for_freertos_queue.cpp

@@ -40,9 +40,18 @@ extern "C" QueueHandle_t xQueueGenericCreate(const UBaseType_t queueLength,
     return queue;
 }
 
+namespace cms{
+    namespace test {
+        extern void MutexAboutToDelete(QueueHandle_t mutex);
+    }
+}
 extern "C" void vQueueDelete(QueueHandle_t queue)
 {
     configASSERT(queue != nullptr);
+    if (queue->queueType == queueQUEUE_TYPE_MUTEX)
+    {
+        cms::test::MutexAboutToDelete(queue);
+    }
     delete queue;
 }
 

cpputest-for-freertos-lib/src/cpputest_for_freertos_semaphore.cpp

@@ -1,3 +1,30 @@
+/// @brief Provides an implementation of a fake FreeRTOS semaphore
+///        which, like FreeRTOS, is under the hood a queue.
+///        cpputest-for-freertos-lib assumes that a queue should be
+///        functional, i.e. not a mock. No blocking is implemented.
+///
+/// @ingroup
+/// @cond
+///***************************************************************************
+///
+/// Copyright (C) 2024 Matthew Eshleman. All rights reserved.
+///
+/// This program is open source software: you can redistribute it and/or
+/// modify it under the terms of the GNU General Public License as published
+/// by the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, upon written permission from Matthew Eshleman, this program
+/// may be distributed and modified under the terms of a Commercial
+/// License. For further details, see the Contact Information below.
+///
+/// Contact Information:
+///   Matthew Eshleman
+///   https://covemountainsoftware.com
+///   [email protected]
+///***************************************************************************
+/// @endcond
+
 #include "cpputest_for_freertos_fake_queue.hpp"
 #include <cstring>
 #include "queue.h"

cpputest-for-freertos-lib/src/cpputest_for_freertos_timers.cpp

@@ -1,3 +1,28 @@
+/// @brief Provides an implementation of fake but functional
+///        FreeRTOS software timers.
+///
+/// @ingroup
+/// @cond
+///***************************************************************************
+///
+/// Copyright (C) 2024 Matthew Eshleman. All rights reserved.
+///
+/// This program is open source software: you can redistribute it and/or
+/// modify it under the terms of the GNU General Public License as published
+/// by the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, upon written permission from Matthew Eshleman, this program
+/// may be distributed and modified under the terms of a Commercial
+/// License. For further details, see the Contact Information below.
+///
+/// Contact Information:
+///   Matthew Eshleman
+///   https://covemountainsoftware.com
+///   [email protected]
+///***************************************************************************
+/// @endcond
+
 #include "FreeRTOS.h"
 #include "timers.h"
 #include "FakeTimers.hpp"

cpputest-for-freertos-lib/tests/CMakeLists.txt

@@ -6,6 +6,7 @@ set(TEST_SOURCES
         cpputest_for_freertos_queue_tests.cpp
         cpputest_for_freertos_task_tests.cpp
         cpputest_for_freertos_semaphore_tests.cpp
+        cpputest_for_freertos_mutex_tests.cpp
 )
 
 # this include expects TEST_SOURCES and TEST_APP_NAME to be

cpputest-for-freertos-lib/tests/cpputest_for_freertos_mutex_tests.cpp

@@ -0,0 +1,93 @@
+/// @brief Tests of CppUTest for FreeRTOS mutex implementation
+/// @ingroup
+/// @cond
+///***************************************************************************
+///
+/// Copyright (C) 2024 Matthew Eshleman. All rights reserved.
+///
+/// This program is open source software: you can redistribute it and/or
+/// modify it under the terms of the GNU General Public License as published
+/// by the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, upon written permission from Matthew Eshleman, this program
+/// may be distributed and modified under the terms of a Commercial
+/// License. For further details, see the Contact Information below.
+///
+/// Contact Information:
+///   Matthew Eshleman
+///   https://covemountainsoftware.com
+///   [email protected]
+///***************************************************************************
+/// @endcond
+
+#include "FreeRTOS.h"
+#include "semphr.h"
+#include "cpputest_for_freertos_mutex.hpp"
+#include "CppUTest/TestHarness.h"
+
+
+TEST_GROUP(MutexTests)
+{
+    SemaphoreHandle_t mMutexUnderTest;
+
+    void setup() final
+    {
+    }
+
+    void teardown() final
+    {
+        if (mMutexUnderTest != nullptr)
+        {
+            vSemaphoreDelete(mMutexUnderTest);
+        }
+    }
+
+    void CreateMutex()
+    {
+        mMutexUnderTest = xSemaphoreCreateMutex();
+    }
+};
+
+TEST(MutexTests, can_create_a_mutex_and_is_not_locked)
+{
+    CreateMutex();
+    CHECK_EQUAL(1, uxSemaphoreGetCount(mMutexUnderTest));
+}
+
+TEST(MutexTests, can_lock_and_unlock_a_mutex)
+{
+    CreateMutex();
+    xSemaphoreTake(mMutexUnderTest, 1000);
+    CHECK_EQUAL(0, uxSemaphoreGetCount(mMutexUnderTest));
+    xSemaphoreGive(mMutexUnderTest);
+    CHECK_EQUAL(1, uxSemaphoreGetCount(mMutexUnderTest));
+}
+
+TEST(MutexTests, library_can_detect_locked_mutexes)
+{
+    CHECK_FALSE(cms::test::IsAnyMutexLocked());
+    cms::test::MutexTrackingInit();
+    CreateMutex();
+    CHECK_FALSE(cms::test::IsAnyMutexLocked());
+
+    xSemaphoreTake(mMutexUnderTest, 1000);
+    CHECK_TRUE(cms::test::IsAnyMutexLocked());
+
+    xSemaphoreGive(mMutexUnderTest);
+    CHECK_FALSE(cms::test::IsAnyMutexLocked());
+    cms::test::MutexTrackingTeardown();
+}
+
+TEST(MutexTests, library_does_not_detect_locked_mutex_that_was_deleted)
+{
+    cms::test::MutexTrackingInit();
+    CreateMutex();
+    xSemaphoreTake(mMutexUnderTest, 1000);
+    CHECK_TRUE(cms::test::IsAnyMutexLocked());
+
+    vSemaphoreDelete(mMutexUnderTest);
+    mMutexUnderTest = nullptr;
+    CHECK_FALSE(cms::test::IsAnyMutexLocked());
+    cms::test::MutexTrackingTeardown();
+}

cpputest-for-freertos-lib/tests/cpputest_for_freertos_semaphore_tests.cpp

@@ -1,3 +1,26 @@
+/// @brief Tests of CppUTest for FreeRTOS semaphore implementation
+/// @ingroup
+/// @cond
+///***************************************************************************
+///
+/// Copyright (C) 2024 Matthew Eshleman. All rights reserved.
+///
+/// This program is open source software: you can redistribute it and/or
+/// modify it under the terms of the GNU General Public License as published
+/// by the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, upon written permission from Matthew Eshleman, this program
+/// may be distributed and modified under the terms of a Commercial
+/// License. For further details, see the Contact Information below.
+///
+/// Contact Information:
+///   Matthew Eshleman
+///   https://covemountainsoftware.com
+///   [email protected]
+///***************************************************************************
+/// @endcond
+
 #include "FreeRTOS.h"
 #include "semphr.h"
 #include "CppUTest/TestHarness.h"