RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity

Merge #17066

Browse Source 
17066: sys/irq: Add C++ wrapper using RAII r=maribu a=jenswet

### Contribution description

This adds a C++ wrapper around the `irq.h` API. The wrapper uses RAII to accomplish a convenient and bug resistent use.
 
A little background: I'm currently writing my master thesis on using C++ for embedded development, at the working group that `@maribu` is part of. For that I will try to add better C++ support to several parts of RIOT and then do some benchmarking and metrics to compare it with the C implementation. For example, I also plan to add a wrapper around i2c, a std::cout drop-in replacement and probably some more about networks or threads.

### Testing procedure

I've added a unit test to verify that the IRQ wrapper calls the original `irq` functions as expected. As C++ and wrapper testing isn't done much so far in this project, I've added two additional headers to ease testing:
1.  #17076 - fake functions framework, already merged
2. As there is no framework for C++ unit tests yet, I've added something for this too. Unfortunately the existing frameworks like GoogleTest, CppUTest or CppUnit don't easily compile for embedded or are difficult to integrate in to the RIOT build process. That's why I wrote some (simple) helper functions and macros inspired by the above frameworks. That allows to create C++ tests based on a fixture class with set up and tear down methods. It also allows some simple assertions and is easily extendable for other use cases. It wraps some of the fff functionality too.

Both of this is obviously not required for the initial reason of this PR. But I'd like to provide unit tests for the features that I suggest to introduce where possible. So I'd appreciate some feedback on that too. If you'd prefer a PR without or different tests please let me know.

You can run the test `irq_cpp` locally or on the CI to test the implementation.

Please feel free to give feedback or suggest improvements!

Co-authored-by: Jens Wetterich <jens@wetterich-net.de>
This commit is contained in:
bors[bot] 2023-01-15 18:17:00 +00:00 committed by GitHub
commit 1b352d69f7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 653 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
pkg/fff/Makefile.include
View File

@ -3,3 +3,6 @@ INCLUDES += -I$(PKGDIRBASE)/fff
# There's nothing to build in this package, it's used as a header only library.
# So it's declared as a pseudo-module
PSEUDOMODULES += fff
# Tests don't need pedantic. Pedantic throws errors in variadic macros when compiling for C++
CXXEXFLAGS += -Wno-pedantic

34
sys/include/cppunit.hpp Normal file
View File

@ -0,0 +1,34 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup sys
* @defgroup unittests_cpp C++ Unittests
* @brief RIOT unit tests for C++
* @details The C++ unit test framework syntax is loosely based on
* GoogleTest, but offers far less functionality.
* For mocking the package @ref pkg_fff can be used.
* @{
* @file
* @brief RIOT unit tests for C++
* @details The C++ unit test framework syntax is loosely based on GoogleTest,
* but offers far less functionality.
* For mocking the package @ref pkg_fff can be used.
* @author Jens Wetterich <jens@wetterich-net.de>
*
*/
#ifndef CPPUNIT_H
#define CPPUNIT_H
#if __cplusplus >= 201103L || defined(DOXYGEN)
#include "cppunit/cppunit_base.hpp"
#include "cppunit/cppunit_expect.hpp"
#include "cppunit/cppunit_fff.hpp"
#else
#error This library needs C++11 and newer
#endif
#endif
/** @} */

191
sys/include/cppunit/cppunit_base.hpp Normal file
View File

@ -0,0 +1,191 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @addtogroup unittests_cpp
* @{
* @file
* @brief RIOT unit tests for C++ base classes and macros
* @author Jens Wetterich <jens@wetterich-net.de>
*
*/
#ifndef CPPUNIT_BASE_H
#define CPPUNIT_BASE_H
#if __cplusplus >= 201103L || defined(DOXYGEN)
#include <array>
#include <cstdio>
#include <cstring>
#include <type_traits>
#ifndef CPPUNIT_SUITE_CNT
/**
* @brief Maximum amount of tests in one test suite
*/
#define CPPUNIT_SUITE_CNT (10)
#endif
/**
* @brief RIOT C++ namespace
*/
namespace riot {
/**
* @brief namespace for cpp unit tests
*/
namespace testing {
/**
* @brief Test base class
* @details Should not be instantiated directly.
* @sa #TEST(suite, name) macro
*/
class test {
private:
bool suc = true; ///< indicates success of the test after running
public:
/**
* @brief Run the test
* @details Should not be called directly, only via macros
* @sa #RUN_SUITE(name)
* @return whether the test completed without errors
*/
virtual bool run() = 0;
/**
* @brief Indicate failure during test run
* @details Should be called by assertions macros
* @sa #EXPECT_EQ(expected, actual, msg)
* @sa #EXPECT_STREQ(expected, actual, msg)
* @sa #EXPECT_FFF_CALL_COUNT(name, count)
* @sa #EXPECT_FFF_CALL_PARAMS(mock, ...)
*/
void fail() {
suc = false;
}
/**
* @brief Check whether the test completed successfully
* @return whether the test completed without errors
*/
bool success() const {
return suc;
}
};
/**
* @brief Test suite base class
* @details Should not be instantiated directly.
* To customize a test suite with custom set_up and tear down methods,
* inherit from this class and override set_up() and/or tear_down().
* They will before / after every test.
* @sa #TEST_SUITE(name) macro
* @sa #TEST_SUITE_F(suite, name) macro
* @sa test_suite::set_up()
* @sa test_suite::tear_down()
*/
class test_suite {
protected:
bool suc = true; ///< Indicates success of all tests after running the suite
std::array<test*, CPPUNIT_SUITE_CNT> tests{}; ///< array of tests to run
public:
/**
* @brief method to run before each test
*/
virtual void set_up() {
}
/**
* @brief method to run after each test
*/
virtual void tear_down() {
}
/**
* @brief get the name of the test suite
* @return name string
*/
virtual const char* get_name() const {
return "";
};
/**
* @brief Run all tests in the suite
*/
virtual void run() {
printf("----\nStarting Test suite %s\n", get_name());
for (auto test : tests) {
if (test) {
suc = test->run() && suc;
}
}
printf("Suite %s completed: %s\n----\n", get_name(), suc ? "SUCCESS" : "FAILURE");
}
/**
* @brief Run all tests in the suite
*/
void addTest(test* test) {
for (int i = 0; i < CPPUNIT_SUITE_CNT; i++) {
if (!tests[i]) {
tests[i] = test;
break;
}
}
}
};
}// namespace testing
}// namespace riot
/**
* @brief Run the test suite \a name
* @hideinitializer
* @param[in] name Name of the suite
*/
#define RUN_SUITE(name) test_suite_##name.run();
/**
* @brief Instantiate a test suite with custom test fixture
* @hideinitializer
* @param[in] suite Name of the custom test fixture class
* @param[in] name Instantiation name of the suite
*/
#define TEST_SUITE_F(suite, name) \
static_assert(sizeof(#suite) > 1, "test fixture class must not be empty"); \
static_assert(sizeof(#name) > 1, "test_suite name must not be empty"); \
class test_suite_##name : public suite { \
const char* get_name() const override { \
return #name; \
}; \
}; \
test_suite_##name test_suite_##name;
/**
* @brief Instantiate a test suite
* @hideinitializer
* @param[in] name Instantiation name of the suite
*/
#define TEST_SUITE(name) TEST_SUITE_F(::riot::testing::test_suite, name)
/**
* @brief Begin the definition of a test
* @details Insert the test body after the macro
* @hideinitializer
* @param[in] suite Name of the suite to add the test to
* @param[in] name Instantiation name of the test
*/
#define TEST(suite, name) \
class Test_##name : public ::riot::testing::test { \
private: \
void test_body(); \
\
public: \
Test_##name() { \
test_suite_##suite.addTest(this); \
} \
bool run() { \
test_suite_##suite.set_up(); \
printf("Running test " #name "...\n"); \
test_body(); \
printf("Test " #name ": %s\n", success() ? "SUCCESS" : "FAILURE"); \
test_suite_##suite.tear_down(); \
return success(); \
}; \
}; \
void Test_##name::test_body()
#else
#error This library needs C++11 and newer
#endif
#endif
/** @} */

63
sys/include/cppunit/cppunit_expect.hpp Normal file
View File

@ -0,0 +1,63 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @addtogroup unittests_cpp
* @{
* @file
* @brief RIOT unit tests for C++ assertion macros
* @author Jens Wetterich <jens@wetterich-net.de>
*
*/
#ifndef CPPUNIT_EXPECT_H
#define CPPUNIT_EXPECT_H
#if __cplusplus >= 201103L || defined(DOXYGEN)
/**
* @brief Expect equality of the \a actual and \a expected value
* @hideinitializer
* @param[in] expected Expected value
* @param[in] actual Actual value
* @param[in] msg Message to print in case of failure
*/
#define EXPECT_EQ(expected, actual, msg) \
static_assert(std::is_integral<decltype(expected)>::value, \
"EXPECT_EQ requires an integral type "); \
if ((actual) != (expected)) { \
fail(); \
if (std::is_same<decltype(expected), bool>::value) { \
printf("Expected: %s, actual: %s\n" msg "\n", (expected) ? "true" : "false", \
(actual) ? "true" : "false"); \
} \
else if (std::is_unsigned<decltype(expected)>::value) { \
printf("Expected: %u, actual: %u\n" msg "\n", static_cast<unsigned>(expected), \
static_cast<unsigned>(actual)); \
} \
else { \
printf("Expected: %d, actual: %d\n" msg "\n", static_cast<int>(expected), \
static_cast<int>(actual)); \
} \
}
/**
* @brief Expect string equality of the \a actual and \a expected value
* @details Interprets both values as const char* string
* @hideinitializer
* @param[in] expected Expected value
* @param[in] actual Actual value
* @param[in] msg Message to print in case of failure
*/
#define EXPECT_STREQ(expected, actual, msg) \
auto expected_str = static_cast<const char*>(expected); \
auto actual_str = static_cast<const char*>(actual); \
if (strcmp(expected_str, actual_str) != 0) { \
fail(); \
printf(msg " not equal! Expected: %s, actual: %s\n", expected_str, actual_str); \
}
#else
#error This library needs C++11 and newer
#endif
#endif
/** @} */

136
sys/include/cppunit/cppunit_fff.hpp Normal file
View File

@ -0,0 +1,136 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @addtogroup unittests_cpp
* @{
* @file
* @brief RIOT unit tests for C++ assertion macros for @ref pkg_fff
* @author Jens Wetterich <jens@wetterich-net.de>
*
*/
#ifndef CPPUNIT_FFF_H
#define CPPUNIT_FFF_H
#if __cplusplus >= 201103L || defined(DOXYGEN)
/**
* @brief Expect \a count calls to \a name mock
* @details Needs the @ref pkg_fff for mocks
* @hideinitializer
* @param[in] name Name of the mock
* @param[in] count Expected calls
*/
#define EXPECT_FFF_CALL_COUNT(name, count) \
if (name##_fake.call_count != (count)) { \
fail(); \
printf("Expected %d calls to " #name ", but got %d\n", count, name##_fake.call_count); \
}
/** @cond Helper macros for the EXPECT_FFF_CALL_PARAMS macro */
#define EXPECT_FFF_CALL_1(name, val1) \
if (name##_fake.arg0_val != (val1)) { \
fail(); \
puts("Argument 0 to mock " #name " doesn't match the expectation.\n"); \
}
#define EXPECT_FFF_CALL_2(name, val1, val2) \
if (name##_fake.arg0_val != (val1)) { \
fail(); \
puts("Argument 1 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg1_val != (val2)) { \
fail(); \
puts("Argument 2 to mock " #name " doesn't match the expectation.\n"); \
}
#define EXPECT_FFF_CALL_3(name, val1, val2, val3) \
if (name##_fake.arg0_val != (val1)) { \
fail(); \
puts("Argument 1 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg1_val != (val2)) { \
fail(); \
puts("Argument 2 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg2_val != (val3)) { \
fail(); \
puts("Argument 3 to mock " #name " doesn't match the expectation.\n"); \
}
#define EXPECT_FFF_CALL_4(name, val1, val2, val3, val4) \
if (name##_fake.arg0_val != (val1)) { \
fail(); \
puts("Argument 1 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg1_val != (val2)) { \
fail(); \
puts("Argument 2 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg2_val != (val3)) { \
fail(); \
puts("Argument 3 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg3_val != (val4)) { \
fail(); \
puts("Argument 4 to mock " #name " doesn't match the expectation.\n"); \
}
#define EXPECT_FFF_CALL_5(name, val1, val2, val3, val4, val5) \
if (name##_fake.arg0_val != (val1)) { \
fail(); \
puts("Argument 1 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg1_val != (val2)) { \
fail(); \
puts("Argument 2 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg2_val != (val3)) { \
fail(); \
puts("Argument 3 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg3_val != (val4)) { \
fail(); \
puts("Argument 4 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg4_val != (val5)) { \
fail(); \
puts("Argument 5 to mock " #name " doesn't match the expectation.\n"); \
}
#define EXPECT_FFF_CALL_6(name, val1, val2, val3, val4, val5, val6) \
if (name##_fake.arg0_val != (val1)) { \
fail(); \
puts("Argument 1 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg1_val != (val2)) { \
fail(); \
puts("Argument 2 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg2_val != (val3)) { \
fail(); \
puts("Argument 3 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg3_val != (val4)) { \
fail(); \
puts("Argument 4 to mock " #name " doesn't match the expectation.\n"); \
} \
if (name##_fake.arg5_val != (val6)) { \
fail(); \
puts("Argument 6 to mock " #name " doesn't match the expectation.\n"); \
}
#define GET_FFF_MACRO(_1, _2, _3, _4, _5, _6, NAME, ...) NAME
/** @endcond */
/**
* @brief Expect that the last call to \a mock was made with the given parameters
* @details Needs the @ref pkg_fff for mocks
* @hideinitializer
* @param[in] mock Name of the mock
* @param[in] ... params
*/
#define EXPECT_FFF_CALL_PARAMS(mock, ...) \
GET_FFF_MACRO(__VA_ARGS__, EXPECT_FFF_CALL_6, EXPECT_FFF_CALL_5, EXPECT_FFF_CALL_4, \
EXPECT_FFF_CALL_3, EXPECT_FFF_CALL_2, EXPECT_FFF_CALL_1) \
(mock, __VA_ARGS__)
#else
#error This library needs C++11 and newer
#endif
#endif
/** @} */

67
sys/include/irq.hpp Normal file
View File

@ -0,0 +1,67 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup core_irq
* @{
* @file
* @brief Provides a C++ RAI based API to control interrupt processing
* @author Jens Wetterich <jens@wetterich-net.de>
*
*/
#ifndef IRQ_HPP
#define IRQ_HPP
#include "irq.h"
namespace riot {
/**
* @brief RAII based IRQ lock
* @details While this object is on the stack IRQ is disabled.
* During destruction it will be restored to the previous state.
*/
class irq_lock {
public:
/**
* @brief Test whether IRQs are currently enabled.
* @return IRQ enabled
*/
static inline bool is_locked() noexcept {
return irq_is_enabled() == 0;
}
/**
* @brief Check whether called from interrupt service routine.
* @return in ISR context
*/
static inline bool is_isr() noexcept {
return irq_is_in() != 0;
}
/**
* @brief This sets the IRQ disable bit in the status register.
*/
inline irq_lock() : state(irq_disable()) {
}
/**
* @brief This restores the IRQ disable bit in the status register
* to the value saved during construction of the object
* @see irq_disable
*/
inline ~irq_lock() {
irq_restore(state);
}
irq_lock(irq_lock const& irq) = delete;
irq_lock(irq_lock const&& irq) = delete;
private:
unsigned int state;
};
}// namespace riot
#endif /* IRQ_HPP */
/** @} */

13
tests/irq_cpp/Makefile Normal file
View File

@ -0,0 +1,13 @@
include ../Makefile.tests_common
FEATURES_REQUIRED += cpp
FEATURES_REQUIRED += libstdcpp
USEPKG += fff
# Some boards don't define irq functions as static inline. Then they can't be mocked.
FEATURES_BLACKLIST += \
arch_esp32 \
arch_esp8266 \
arch_mips32r2 \
arch_native
include $(RIOTBASE)/Makefile.include

5
tests/irq_cpp/Makefile.ci Normal file
View File

@ -0,0 +1,5 @@
BOARD_INSUFFICIENT_MEMORY := \
nucleo-l011k4 \
samd10-xmini \
stm32f030f4-demo \
#

30
tests/irq_cpp/irq.h Normal file
View File

@ -0,0 +1,30 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup tests
* @brief Dummy irq header to allow mocking. Prevents inclusion of the original IRQ header
* @{
*
* @file
*
* @author Jens Wetterich <jens@wetterich-net.de>
*/
#ifndef IRQ_H
#define IRQ_H
#ifdef __cplusplus
extern "C" {
#endif
unsigned irq_disable();
unsigned irq_enable();
int irq_is_enabled();
int irq_is_in();
void irq_restore(unsigned state);
#ifdef __cplusplus
}
#endif
#endif /* IRQ_H */

92
tests/irq_cpp/main.cpp Normal file
View File

@ -0,0 +1,92 @@
/*
* Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup tests
* @{
*
* @file
* @brief Unit tests for the C++ IRQ wrapper irq.hpp
*
* @author Jens Wetterich <jens@wetterich-net.de>
*/
#define FFF_ARG_HISTORY_LEN 1u
#define FFF_CALL_HISTORY_LEN 1u
#include "cppunit.hpp"
#include "fff.h"
#include "irq.h"
#include "irq.hpp"
DEFINE_FFF_GLOBALS
FAKE_VALUE_FUNC(unsigned, irq_disable)
FAKE_VALUE_FUNC(unsigned, irq_enable)
FAKE_VALUE_FUNC(int, irq_is_enabled)
FAKE_VALUE_FUNC(int, irq_is_in)
FAKE_VOID_FUNC(irq_restore, unsigned)
class irq_suite : public riot::testing::test_suite {
public:
void set_up() override {
RESET_FAKE(irq_restore);
RESET_FAKE(irq_disable);
RESET_FAKE(irq_enable);
RESET_FAKE(irq_is_enabled);
RESET_FAKE(irq_is_in);
}
};
TEST_SUITE_F(irq_suite, irq);
TEST(irq, is_isr) {
// Setup test data
irq_is_in_fake.return_val = 0;
// Run test
auto en = riot::irq_lock::is_isr();
irq_is_in_fake.return_val = 1;
auto en2 = riot::irq_lock::is_isr();
// Assert results
EXPECT_EQ(en, false, "Return Value");
EXPECT_EQ(en2, true, "Return Value");
EXPECT_FFF_CALL_COUNT(irq_is_in, 2);
}
TEST(irq, is_enabled) {
// Setup test data
irq_is_enabled_fake.return_val = 0;
// Run test
auto en = riot::irq_lock::is_locked();
irq_is_enabled_fake.return_val = 1;
auto en2 = riot::irq_lock::is_locked();
// Assert results
EXPECT_STREQ("s", "s", "");
EXPECT_EQ(en, true, "Return Value");
EXPECT_EQ(en2, false, "Return Value");
EXPECT_FFF_CALL_COUNT(irq_is_enabled, 2);
}
TEST(irq, irq_disable_restore) {
// Setup test data
auto reg = 7u;
irq_disable_fake.return_val = reg;
// Run test
{
riot::irq_lock lock;
}
// Assert results
EXPECT_FFF_CALL_COUNT(irq_disable, 1);
EXPECT_FFF_CALL_COUNT(irq_restore, 1);
EXPECT_FFF_CALL_PARAMS(irq_restore, reg);
EXPECT_EQ(irq_restore_fake.arg0_val, reg, "Restore Value");
}
int main() {
puts("Testing irq wrapper");
RUN_SUITE(irq);
}
/** @} */

19
tests/irq_cpp/tests/01-run.py Executable file
View File

@ -0,0 +1,19 @@
#!/usr/bin/env python3
# Copyright (C) 2021 Jens Wetterich <jens@wetterich-net.de>
#
# This file is subject to the terms and conditions of the GNU Lesser
# General Public License v2.1. See the file LICENSE in the top level
# directory for more details.
import sys
from testrunner import run
def testfunc(child):
child.expect_exact("Suite irq completed: SUCCESS")
print("All tests successful")
if __name__ == "__main__":
sys.exit(run(testfunc, timeout=1, echo=True, traceback=True))