/urt_osal.h - Annotate - AMiRo-OS - Research for Cognitive Interaction

urtware / urt_osal.h @ 6882b76c

History | View | Annotate | Download (29.595 KB)

-            46471486
+/*
 µRtWare is a lightweight publish/subscribe middleware for real-time
 applications. It was developed as part of the software habitat for the
 Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well.
 Copyright (C) 2018..2020  Thomas Schöpping et al.
 This program is free 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.
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 #ifndef URT_OSAL_H
 #define URT_OSAL_H
 #include <urtware.h>
 /*============================================================================*/
 /* VERSION                                                                    */
 /*============================================================================*/
 /**
  * @brief   The µRtWare operating system abstraction layer interface major version.
  * @note    Changes of the major version imply incompatibilities.
  */
 #define URT_OSAL_VERSION_MAJOR                  0
 /**
  * @brief   The µRtWare operating system abstraction layer interface minor version.
  * @note    A higher minor version implies new functionalty, but all old interfaces are still available.
  */
 #define URT_OSAL_VERSION_MINOR                  1
 /*============================================================================*/
 /* DEPENDENCIES                                                               */
 /*============================================================================*/
 #include <stdint.h>
 /*============================================================================*/
 /* DEBUG                                                                      */
 /*============================================================================*/
 #if defined(__cplusplus)
 extern "C" {
 #endif /* defined(__cplusplus) */
 #if !defined(urtDebugAssert) || defined(__DOXYGEN__)
   /**
    * @brief Assert function to check a given condition.
+   *
    * @param[in] condition   The condition to check.
    */
   void urtDebugAssert(const bool condition);
 #endif /* !defined(urtDebugAssert) */
 #if defined(__cplusplus)
+}
 #endif /* defined(__cplusplus) */
 /*============================================================================*/
 /* MUTEX                                                                      */
 /*============================================================================*/
 /*
  * The following type must be defined by the implementation:
+ *
  * urt_osMutex_t
  *    Type to represent a mutex lock object.
  *    Is only used via pointers by the API.
  */
 #if defined(__cplusplus)
 extern "C" {
 #endif /* defined(__cplusplus) */
 #if !defined(urtMutexInit) || defined(__DOXYGEN__)
   /**
    * @brief   Initialize a mutex lock object.
+   *
    * @param[in] mutex   Pointer to the mutex lock object to initialize.
    *                    Must not be NULL.
    */
   void urtMutexInit(urt_osMutex_t* mutex);
 #endif /* !defined(urtMutexInit) */
 #if !defined(urtMutexLock) || defined(__DOXYGEN__)
   /**
    * @brief   Lock a mutex lock.
    * @details The calling thread is blocked until the mutex lock could be acquired.
+   *
    * @param[in] mutex   Pointer to the mutex lock to acquire.
    *                    Must not be NULL.
    */
   void urtMutexLock(urt_osMutex_t* mutex);
 #endif /* !defined(urtMutexLock) */
 #if !defined(urtMutexTryLock) || defined(__DOXYGEN__)
   /**
    * @brief   Try to lock a mutex lock.
    * @details This function does not block but returns immediately.
+   *
    * @param[in] mutex   Pointer to the mutex lock to acquire.
+   *
    * @return  Indicator whether the lock was acquired.
    * @retval true   The lock was acquired successfully.
    * @retval false  The lock could not be acquired.
    */
   bool urtMutexTryLock(urt_osMutex_t* mutex);
 #endif /* !defined(urtMutexTryLock) */
 #if !defined(urtMutexUnlock) || defined(__DOXYGEN__)
   /**
    * @brief   Unlock an owned mutex lock.
+   *
    * @param[in] mutex   Pointer to the mutex lock to unlock.
    *                    Must not be NULL.
    */
   void urtMutexUnlock(urt_osMutex_t* mutex);
 #endif /* !defined(urtMutexUnlock) */
 #if defined(__cplusplus)
+}
 #endif /* defined(__cplusplus) */
 /*============================================================================*/
 /* CONDITION VARIABLE                                                         */
 /*============================================================================*/
 /*
  * The following type must be defined by the implementation:
+ *
  * urt_osCondvar_t
  *    Type to represent a condition variable object.
  *    Is only used via pointers by the API.
  */
 /**
  * @brief   Status type of condition variables.
  */
 typedef enum {
   URT_CONDVAR_WAITSTATUS_SIGNAL = 1,    /**< The condition variable has been signaled individually. */
   URT_CONDVAR_WAITSTATUS_BROADCAST = 2, /**< The condition variable has been signal via broadcast. */
   URT_CONDVAR_WAITSTATUS_TIMEOUT = 0,   /**< Waiting for the condition variable timed out. */
 } urt_osCondvarWaitStatus_t;
 #if defined(__cplusplus)
 extern "C" {
 #endif /* defined(__cplusplus) */
 #if !defined(urtCondvarInit) || defined(__DOXYGEN__)
   /**
    * @brief   Initialize a condition variable object.
+   *
    * @param[in] condvar   Pointer to the object to initialize.
    *                      Must not be NULL.
    */
   void urtCondvarInit(urt_osCondvar_t* condvar);
 #endif /* !defined(urtCondvarInit) */
 #if !defined(urtCondvarSignal) || defined(__DOXYGEN__)
   /**
    * @brief   Signal a condition variable (wake one waiting thread).
+   *
    * @param[in] condvar   Pointer to the condition variable to signal.
    *                      Must not be NULL.
    */
   void urtCondvarSignal(urt_osCondvar_t* condvar);
 #endif /* !defined(urtCondvarSignal) */
 #if !defined(urtCondvarBroadcast) || defined(__DOXYGEN__)
   /**
    * @brief   Signal a condition variable via broadcast (wake all waiting threads).
+   *
    * @param[in] condvar   Pointer to the condition variable to signal via broadcast.
    *                      Must not be NULL.
    */
   void urtCondvarBroadcast(urt_osCondvar_t* condvar);
 #endif /* !defined(urtCondvarBroadcast) */
-de5bed8
+#if (!defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true)) || defined(__DOXYGEN__)
-            46471486
+  /**
    * @brief   Wait for a condition variable to be signaled or timeout.
+   *
    * @param[in] condvar   Pointer to the condition variabel to wait for.
    *                      Must not be NULL.
    * @param[in] mutex     Pointer to the associated mutex lock.
    *                      Must not be NULL.
    *                      Mutex must be acquired when this function is called.
    * @param[in] timeout   Timeout (in microseconds) when the function will return even without the condition variable being signaled.
    *                      Use URT_DELAY_INFINITE to deactivate timeout.
    * @return
    */
   urt_osCondvarWaitStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex, urt_delay_t timeout);
-de5bed8
+#else /* !defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true) */
   urt_osCondvarWaitStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex);
 #endif /* !defined(urtCondvarWait) && (URT_CFG_OSAL_CONDVAR_TIMEOUT == true) */
-            46471486
+            Thomas Schöpping
 #if defined(__cplusplus)
+}
 #endif /* defined(__cplusplus) */
 /*============================================================================*/
 /* EVENTS                                                                     */
 /*============================================================================*/
 /*
  * The following types and constants must be defined by the implementation:
+ *
  * urt_osEventSource_t
  *    Type to represent an event source object.
  *    Is only used via pointers by the API.
+ *
  * urt_osEventListener_t
  *    Type to represent an event listener object.
  *    Is only used via pointers by the API.
+ *
  * urt_osEventMask_t
  *    Integer type to represent event masks.
+ *
  * urt_osEventFlags_t
  *    Integer type to represent event flags.
+ *
  * URT_EVENTMASK_MAXPRIO
  *    Constant of type urt_osEventMask_t to specify the event mask that is
  *    handled with maximum priority.
  *    This constant is typically either 0x0..1 (low values have high priority)
  *    or 0x8..0 (high values have high priority).
  *    A value of 0 indicates that priorities are not supported.
-ea18a07
+            Svenja
  * URT_EVENTMASK_ALL
  *    Constant of type urt_osEventMask_t to filter no events at all.
  *    Typically is 0xF..F.
-            46471486
+ */
 /**