ALPAKA/rtos2-utils
1
0
Fork 0
mirror of https://git.intern.spaceteamaachen.de/ALPAKA/rtos2-utils.git synced 2025-08-06 11:07:34 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Rework. Improve doxygen documentation

Browse Source
This commit is contained in:
Henrik Stickann
2022-05-08 03:15:08 +02:00
parent 0fe1be1863
commit b09de25c62
14 changed files with 340 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
include/sta/rtos2/defs.hpp
View File

@@ -1,9 +1,32 @@
/**
* @file
* @brief Constants and macros for use with CMSIS RTOS2.
*/
#ifndef STA_RTOS2_DEFS_HPP
#define STA_RTOS2_DEFS_HPP
/**
* @defgroup rtos2 RTOS2
* @brief CMSIS RTOS2 library.
*/
/**
* @defgroup rtos2API API
* @ingroup rtos2
* @brief Public library interface.
*/
/**
* @defgroup rtos2BuildConfig Build config
* @ingroup rtos2
* @brief Build configuration options.
*/
/**
* @ingroup rtos2API
* @{
*/
// See limits defined in cmsis_os2.c
#define STA_RTOS2_MAX_BITS_TASK_NOTIFY 31U
@@ -13,4 +36,6 @@
#define STA_RTOS2_EVENT_FLAGS_VALID_BITS ((1UL << STA_RTOS2_MAX_BITS_EVENT_GROUPS) - 1U)
/** @} */
#endif // STA_RTOS2_DEFS_HPP

74
include/sta/rtos2/easy_config.hpp
View File

@@ -1,26 +1,49 @@
/**
* @file
* @brief Helper for easy system task setup in `<sta/config.hpp>`.
*
* Configuration:
* STA_OS2_SYSTEM_TASKS_ENABLE: Enable all system tasks and required features
* STA_OS2_WATCHDOG_TIMER_NAME: Set watchdog timer handle and callback names based on this
* STA_OS2_WATCHDOG_NAME: Set watchdog task handle and entry function names based on this
*/
#ifndef STA_RTOS2_EASY_CONFIG_HPP
#define STA_RTOS2_EASY_CONFIG_HPP
/**
* @defgroup rtos2EasyConfig Easy Config
* @ingroup rtos2BuildConfig
* @brief Helpers for easy RTOS2 module setup.
*
* Use this header only inside the <sta/config.hpp> header of your application.
*/
#ifdef DOXYGEN
/**
* @brief Don't warn about use of <rtos2/easy_config.hpp> outside of <sta/config.hpp>.
*
* @ingroup rtos2EasyConfig
*/
# define STA_RTOS2_EASY_CONFIG_NO_WARNING
#endif // DOXYGEN
#if !defined(STA_CONFIG_HPP) && !defined(STA_RTOS2_EASY_CONFIG_NO_WARNING)
#warning "Intended for use in <sta/config.hpp>"
#endif // !STA_CONFIG_HPP && !STA_RTOS2_EASY_CONFIG_NO_WARNING
#ifdef STA_RTOS2_SYSTEM_TASKS_ENABLE
#ifdef DOXYGEN
/**
* @brief Enable all system tasks and required features.
*
* @ingroup rtos2EasyConfig
*/
# define STA_RTOS2_EASY_CONFIG_SYSTEM_TASKS_ENABLE
#endif // DOXYGEN
#ifdef STA_RTOS2_EASY_CONFIG_SYSTEM_TASKS_ENABLE
// Enable system events used by system tasks
# define STA_RTOS2_SYSTEM_EVENT_ENABLE
// Enable system tasks
# define STA_RTOS2_WATCHDOG_ENABLE
# define STA_RTOS2_STARTUP_ENABLE
#endif // STA_RTOS2_SYSTEM_TASKS_ENABLE
#endif // STA_RTOS2_EASY_CONFIG_SYSTEM_TASKS_ENABLE
#define _STA_RTOS2_CONCAT(a, b) a ## b
@@ -29,17 +52,34 @@
#define STA_RTOS2_MAKE_CALLBACK_NAME(name) _STA_RTOS2_CONCAT(name, Callback)
#define STA_RTOS2_MAKE_TASK_NAME(name) _STA_RTOS2_CONCAT(name, Task)
// Use common base name for watchdog timer handle and callback
#ifdef STA_RTOS2_WATCHDOG_TIMER_NAME
# define STA_RTOS2_WATCHDOG_TIMER_HANDLE STA_RTOS2_MAKE_HANDLE_NAME(STA_RTOS2_WATCHDOG_TIMER_NAME)
# define STA_RTOS2_WATCHDOG_TIMER_CALLBACK STA_RTOS2_MAKE_CALLBACK_NAME(STA_RTOS2_WATCHDOG_TIMER_NAME)
#endif // STA_RTOS2_WATCHDOG_TIMER_NAME
// Use common base name for watchdog task handle and entry function
#ifdef STA_RTOS2_WATCHDOG_NAME
# define STA_RTOS2_WATCHDOG_HANDLE STA_RTOS2_MAKE_HANDLE_NAME(STA_RTOS2_WATCHDOG_NAME)
# define STA_RTOS2_WATCHDOG_ENTRY_FUNCTION STA_RTOS2_MAKE_TASK_NAME(STA_RTOS2_WATCHDOG_NAME)
#endif // STA_RTOS2_WATCHDOG_NAME
#ifdef DOXYGEN
/**
* @brief Common base name used for watchdog timer handle and callback names.
*
* @ingroup rtos2EasyConfig
*/
# define STA_RTOS2_EASY_CONFIG_WATCHDOG_TIMER_NAME
#endif // DOXYGEN
#ifdef STA_RTOS2_EASY_CONFIG_WATCHDOG_TIMER_NAME
# define STA_RTOS2_WATCHDOG_TIMER_HANDLE STA_RTOS2_MAKE_HANDLE_NAME(STA_RTOS2_EASY_CONFIG_WATCHDOG_TIMER_NAME)
# define STA_RTOS2_WATCHDOG_TIMER_CALLBACK STA_RTOS2_MAKE_CALLBACK_NAME(STA_RTOS2_EASY_CONFIG_WATCHDOG_TIMER_NAME)
#endif // STA_RTOS2_EASY_CONFIG_WATCHDOG_TIMER_NAME
#ifdef DOXYGEN
/**
* @brief Common base name used for watchdog task handle and entry function names.
*
* @ingroup rtos2EasyConfig
*/
# define STA_RTOS2_EASY_CONFIG_WATCHDOG_NAME
#endif // DOXYGEN
#ifdef STA_RTOS2_EASY_CONFIG_WATCHDOG_NAME
# define STA_RTOS2_WATCHDOG_HANDLE STA_RTOS2_MAKE_HANDLE_NAME(STA_RTOS2_EASY_CONFIG_WATCHDOG_NAME)
# define STA_RTOS2_WATCHDOG_ENTRY_FUNCTION STA_RTOS2_MAKE_TASK_NAME(STA_RTOS2_EASY_CONFIG_WATCHDOG_NAME)
#endif // STA_RTOS2_EASY_CONFIG_WATCHDOG_NAME
#endif // STA_RTOS2_EASY_CONFIG_HPP

5
include/sta/rtos2/mutex.hpp
View File

@@ -1,4 +1,5 @@
/**
* @file
* @brief CMSIS RTOS2 mutex implementation.
*/
#ifndef STA_RTOS2_MUTEX_HPP
@@ -12,7 +13,9 @@
namespace sta
{
/**
* @brief Implementation of `Mutex` interface using CMSIS RTOS2.
* @brief Implementation of Mutex interface using CMSIS RTOS2.
*
* @ingroup rtos2API
*/
class Rtos2Mutex : public Mutex
{

70
include/sta/rtos2/queue.hpp
View File

@@ -1,63 +1,67 @@
/**
* @file
* @brief CMSIS RTOS2 queue implementation.
*/
#ifndef STA_RTOS2_QUEUE_HPP
#define STA_RTOS2_QUEUE_HPP
#include <sta/assert.hpp>
#include <cmsis_os2.h>
#include <cstdint>
namespace sta
{
/**
* @brief Interface object for using CMSIS RTOS2 queues.
*
* @tparam Message type
*
* @ingroup rtos2API
*/
template <typename T>
class Rtos2Queue
{
public:
using Message = T;
using Message = T; /**< Queue message type */
public:
/**
* @param handle CMSIS RTOS2 queue handle
*/
Rtos2Queue(osMessageQueueId_t * handle);
/**
* @brief Place message in queue.
*
* @param msg Message object
* @param timeout Timeout
* @return True on success
*/
bool put(const Message & msg, uint32_t timeout = osWaitForever);
/**
* @brief Take message from queue.
*
* @param[out] outMsg Message object destination
* @param timeout Timeout
* @return True on success
*/
bool get(Message * outMsg, uint32_t timeout = osWaitForever);
uint32 available() const;
/**
* @brief Get number of messages in queue.
*
* @return Number of messages in queue
*/
uint32_t available() const;
private:
osMessageQueueId_t * handle_;
osMessageQueueId_t * handle_; /**< CMSIS RTOS2 queue handle */
};
} // namespace sta
namespace sta
{
template <typename T>
Rtos2Queue<T>::Rtos2Queue(osMessageQueueId_t * handle)
: handle_{handle}
{
STA_ASSERT(handle != nullptr);
}
template <typename T>
bool Rtos2Queue<T>::put(const Message & msg, uint32_t timeout /* = osWaitForever */)
{
return (osOK == osMessageQueuePut(*handle_, &msg, 0, timeout));
}
template <typename T>
bool Rtos2Queue<T>::get(Message * outMsg, uint32_t timeout /* = osWaitForever */)
{
uint8_t prio;
return (osOK == osMessageQueueGet(*handle_, outMsg, &prio, timeout));
}
template <typename T>
uint32 Rtos2Queue<T>::available() const
{
return osMessageQueueGetCount(*handle_);
}
} // namespace sta
#include <sta/rtos2/queue.tpp>
#endif // STA_RTOS2_QUEUE_HPP

41
include/sta/rtos2/queue.tpp Normal file
View File

@@ -0,0 +1,41 @@
#ifndef STA_RTOS2_QUEUE_TPP
#define STA_RTOS2_QUEUE_TPP
#ifndef STA_RTOS2_QUEUE_HPP
# error "Internal header. Use <sta/rtos2/queue.hpp> instead."
#endif // !STA_RTOS2_QUEUE_HPP
#include <sta/assert.hpp>
namespace sta
{
template <typename T>
Rtos2Queue<T>::Rtos2Queue(osMessageQueueId_t * handle)
: handle_{handle}
{
STA_ASSERT(handle != nullptr);
}
template <typename T>
bool Rtos2Queue<T>::put(const Message & msg, uint32_t timeout /* = osWaitForever */)
{
return (osOK == osMessageQueuePut(*handle_, &msg, 0, timeout));
}
template <typename T>
bool Rtos2Queue<T>::get(Message * outMsg, uint32_t timeout /* = osWaitForever */)
{
uint8_t prio;
return (osOK == osMessageQueueGet(*handle_, outMsg, &prio, timeout));
}
template <typename T>
uint32 Rtos2Queue<T>::available() const
{
return osMessageQueueGetCount(*handle_);
}
} // namespace sta
#endif // STA_RTOS2_QUEUE_TPP

5
include/sta/rtos2/signal.hpp
View File

@@ -1,4 +1,5 @@
/**
* @file
* @brief CMSIS RTOS2 signal implementation.
*/
#ifndef STA_RTOS2_SIGNAL_HPP
@@ -12,7 +13,9 @@
namespace sta
{
/**
* @brief Implementation of `Signal` interface using CMSIS RTOS2.
* @brief Implementation of Signal interface using CMSIS RTOS2.
*
* @ingroup rtos2API
*/
class Rtos2Signal : public Signal
{

37
include/sta/rtos2/startup.hpp
View File

@@ -1,13 +1,40 @@
/**
* @file
* @brief Implementation of startup system task.
*
* Configuration:
* STA_RTOS2_STARTUP_ENABLE: Enable module
* STA_RTOS2_STARTUP_ENTRY_FUNCTION: Override name of startup task entry function (default: startupTask)
*/
#ifndef STA_RTOS2_STARTUP_HPP
#define STA_RTOS2_STARTUP_HPP
/**
* @defgroup rtos2Startup Startup task
* @ingroup rtos2API
* @brief Startup system task.
*
* Check @ref rtos2BuildConfig for configuration options.
*/
#ifdef DOXYGEN
/**
* @brief Enable module.
*
* @ingroup rtos2BuildConfig
*/
# define STA_RTOS2_STARTUP_ENABLE
#endif // DOXYGEN
/**
* @def STA_RTOS2_STARTUP_ENTRY_FUNCTION
* @brief Set name of startup task entry function.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_STARTUP_ENTRY_FUNCTION
# define STA_RTOS2_STARTUP_ENTRY_FUNCTION startupTask
#endif // !STA_RTOS2_STARTUP_ENTRY_FUNCTION
#include <sta/config.hpp>
#ifdef STA_RTOS2_STARTUP_ENABLE
@@ -18,6 +45,8 @@ namespace sta
* @brief Extra initialization run at start of startup task.
*
* May be overridden by application if required.
*
* @ingroup rtos2Startup
*/
void startupExtras(void * argument);
} // namespace sta

46
include/sta/rtos2/system_event.hpp
View File

@@ -1,13 +1,38 @@
/**
* @file
* @brief Implementation of system events.
*
* Configuration:
* STA_RTOS2_SYSTEM_EVENT_ENABLE: Enable module
* STA_RTOS2_SYSTEM_EVENT_HANDLE: Override variable name of flag handle (default: systemEventHandle)
*/
#ifndef STA_OS2_SYSTEM_EVENT_HPP
#define STA_OS2_SYSTEM_EVENT_HPP
/**
* @defgroup rtos2SysEvent System Events
* @ingroup rtos2API
* @brief System events.
*
* Check @ref rtos2BuildConfig for configuration options.
*/
#ifdef DOXYGEN
/**
* @brief Enable module.
*
* @ingroup rtos2BuildConfig
*/
# define STA_RTOS2_SYSTEM_EVENT_ENABLE
#endif // DOXYGEN
/**
* @def STA_RTOS2_SYSTEM_EVENT_HANDLE
* @brief Set variable name of event flags handle.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_SYSTEM_EVENT_HANDLE
# define STA_RTOS2_SYSTEM_EVENT_HANDLE systemEventHandle
#endif // !STA_RTOS2_SYSTEM_EVENT_HANDLE
#include <sta/config.hpp>
#ifdef STA_RTOS2_SYSTEM_EVENT_ENABLE
@@ -17,6 +42,11 @@
// System event flags
//
/**
* @brief Startup system event flag.
*
* @ingroup rtos2SysEvent
*/
#define STA_SYSTEM_EVENT_STARTUP 0x100000U
@@ -26,6 +56,8 @@ namespace sta
* @brief Signal system events.
*
* @param flags System event flags
*
* @ingroup rtos2SysEvent
*/
void signalSystemEvents(uint32_t flags);
@@ -35,12 +67,16 @@ namespace sta
* @param flags System event flags
* @param options osFlagsWaitAll or osFlagsWaitAny (osFlagsNoClear always set)
* @param timeout Wait timeout (0 = instant, osWaitForever = infinite)
*
* @ingroup rtos2SysEvent
*/
void waitForSystemEvents(uint32_t flags, uint32_t options, uint32_t timeout);
/**
* @brief Signal startup system event.
*
* @ingroup rtos2SysEvent
*/
void signalStartupEvent();
@@ -48,6 +84,8 @@ namespace sta
* @brief Wait for startup system event.
*
* Blocking while waiting
*
* @ingroup rtos2SysEvent
*/
void waitForStartupEvent();
} // namespace sta

87
include/sta/rtos2/watchdog.hpp
View File

@@ -1,17 +1,79 @@
/**
* @file
* @brief Implementation of watchdog system task.
*
* Configuration:
* STA_RTOS2_WATCHDOG_ENABLE: Enable module
* STA_RTOS2_WATCHDOG_TIMER_PERIOD: Set period in ticks of heartbeat timer (default: 1000)
* STA_RTOS2_WATCHDOG_TIMER_HANDLE: Override variable name of heartbeat timer handle (default: heartbeatHandle)
* STA_RTOS2_WATCHDOG_TIMER_CALLBACK: Override name of heartbeat timer callback function (default: heartbeatCallback)
* STA_RTOS2_WATCHDOG_HANDLE: Override variable name of watchdog task handle (default: watchdogHandle)
* STA_RTOS2_WATCHDOG_ENTRY_FUNCTION: Override name of watchdog task entry function (default: watchdogTask)
*/
#ifndef STA_RTOS2_WATCHDOG_HPP
#define STA_RTOS2_WATCHDOG_HPP
/**
* @defgroup rtos2Watchdog Watchdog task
* @ingroup rtos2API
* @brief Watchdog system task.
*
* Check @ref rtos2BuildConfig for configuration options.
*/
#ifdef DOXYGEN
/**
* @brief Enable module.
*
* @ingroup rtos2BuildConfig
*/
# define STA_RTOS2_WATCHDOG_ENABLE
#endif // DOXYGEN
/**
* @def STA_RTOS2_WATCHDOG_TIMER_PERIOD
* @brief Set period in ticks of heartbeat timer.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_WATCHDOG_TIMER_PERIOD
# define STA_RTOS2_WATCHDOG_TIMER_PERIOD 1000
#endif // !STA_RTOS2_WATCHDOG_TIMER_PERIOD
/**
* @def STA_RTOS2_WATCHDOG_TIMER_HANDLE
* @brief Set variable name of heartbeat timer handle.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_WATCHDOG_TIMER_HANDLE
# define STA_RTOS2_WATCHDOG_TIMER_HANDLE heartbeatHandle
#endif // !STA_RTOS2_WATCHDOG_TIMER_HANDLE
/**
* @def STA_RTOS2_WATCHDOG_TIMER_CALLBACK
* @brief Set name of heartbeat timer callback function.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_WATCHDOG_TIMER_CALLBACK
# define STA_RTOS2_WATCHDOG_TIMER_CALLBACK heartbeatCallback
#endif // !STA_RTOS2_WATCHDOG_TIMER_CALLBACK
/**
* @def STA_RTOS2_WATCHDOG_HANDLE
* @brief Set variable name of watchdog task handle.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_WATCHDOG_HANDLE
# define STA_RTOS2_WATCHDOG_HANDLE watchdogHandle
#endif // !STA_RTOS2_WATCHDOG_HANDLE
/**
* @def STA_RTOS2_WATCHDOG_ENTRY_FUNCTION
* @brief Set name of watchdog task entry function.
*
* @ingroup rtos2BuildConfig
*/
#ifndef STA_RTOS2_WATCHDOG_ENTRY_FUNCTION
# define STA_RTOS2_WATCHDOG_ENTRY_FUNCTION watchdogTask
#endif // !STA_RTOS2_WATCHDOG_ENTRY_FUNCTION
#include <sta/config.hpp>
#ifdef STA_RTOS2_WATCHDOG_ENABLE
@@ -21,6 +83,11 @@
// Watchdog task flags
//
/**
* @brief Watchdog heartbeat flag.
*
* @ingroup rtos2Watchdog
*/
#define STA_WATCHDOG_FLAG_HEARTBEAT 0x00001000U
@@ -28,10 +95,14 @@ namespace sta
{
/**
* @brief Start heartbeat timer for watchdog.
*
* @ingroup rtos2Watchdog
*/
void startWatchdogTimer();
/**
* @brief Send notification to watchdog task.
*
* @ingroup rtos2Watchdog
*/
void notifyWatchdog(uint32_t flags);
} // namespace sta