AMiRo-OS

/*

AMiRo-Apps is a collection of applications for the Autonomous Mini Robot (AMiRo) platform.

Copyright (C) 2018..2018  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_

/*============================================================================*/

/* 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 <urt_types.h>

#include <amiroos.h>

/*============================================================================*/

/* TIME                                                                       */

/*============================================================================*/

/**

 * @brief   The urt_osTime_t represents time at an arbitrary precision.

 */

typedef aos_timestamp_t urt_osTime_t;

/**

 * @brief   Convert an urt_osTime_t to microseconds.

 *

 * @param[in]   time    The urt_osTime_t object to convert.

 *

 * @return  The time at microsecond precision.

 */

static inline uint64_t urtTime2Us(urt_osTime_t* time)

{

  aosDbgCheck(time != NULL);

  return *time;

}

/**

 * @brief   Retrieve the current system time.

 *

 * @return  The current system time.

 */

static inline urt_osTime_t urtTimeNow(void)

{

  urt_osTime_t time;

  aosSysGetUptime(&time);

  return time;

}

/*============================================================================*/

/* TIMER                                                                      */

/*============================================================================*/

/**

 * @brief   A timer type.

 */

typedef aos_timer_t urt_osTimer_t;

/**

 * @brief   Initialize a timer object.

 *

 * @param[in]   timer   The timer object to initialize.

 */

static inline void urtTimerInit(urt_osTimer_t* timer)

{

  aosDbgCheck(timer != NULL);

  aosTimerInit(timer);

}

/**

 * @brief   Set a timer to fire after a specified delay and execute the callback function.

 *

 * @param[in]   timer       The timer object.

 * @param[in]   delay       A delay after which the timer shall fire.

 * @param[in]   callback    The callback to be executed by the timer.

 * @param[in]   parameter   Optional parameters to the callback function.

 *

 * @return  Satus indicating whether execution was successful.

 */

static inline urt_status_t urtTimerSet(urt_osTimer_t* timer, urt_delay_t delay, urt_osTimerCallback callback, void* parameter)

{

  aosDbgCheck(timer != NULL);

  aosDbgCheck(callback != NULL);

  if (sizeof(urt_delay_t) > sizeof(aos_interval_t)) {

    aos_longinterval_t interval = delay;

    aosTimerSetLongInterval(timer, &interval, callback, parameter);

  } else {

    aosTimerSetInterval(timer, delay, callback, parameter);

  }

  return URT_STATUS_OK;

}

/**

 * @brief   Reset a timer.

 *

 * @param[in]   timer   The timer to reset.

 *

 * @return  Status indicating whether execution was successful.

 */

static inline urt_status_t urtTimerReset(urt_osTimer_t* timer)

{

  aosDbgCheck(timer != NULL);

  aosTimerReset(timer);

  return URT_STATUS_OK;

}

/**

 * @brief   Retrieve whether a timer is currently armed.

 *

 * @param[in]   timer   The timer to check.

 *

 * @return  Indicator whether the timer is armed.

 */

static inline bool urtTimerIsArmed(urt_osTimer_t* timer)

{

  aosDbgCheck(timer != NULL);

  return aosTimerIsArmed(timer);

}

/*============================================================================*/

/* STREAMS                                                                    */

/*============================================================================*/

/**

 * @brief   Prints a formatted string to standard output.

 * @note    Behaves like standard C printf().

 *

 * @param[in] fmt   Formatted string to print.

 */

#define urtPrintf(fmt, ...)                     aosprintf(fmt, ##__VA_ARGS__)

/**

 * @brief   Prints a formatted string to error output.

 * @note    Behaves like to standard C printf().

 *

 * @param[in] fmt   Formatted string to print.

 */

#define urtErrPrintf(fmt, ...)                  aosprintf(fmt, ##__VA_ARGS__)

/*============================================================================*/

/* EVENTS                                                                     */

/*============================================================================*/

/**

 * @brief   Type representing event masks.

 * @details Event masks can be used to distinguish and filter events.

 */

typedef eventmask_t urt_osEventMask_t;

/**

 * @brief   The event mask that is served by the kernel with highest priority.

 * @details It is assumed to be one of three values:

 *          * 1   Lower bits have higher priority.

 *          * -1  Higher bits have higher priority.

 *          * 0   Thekernel does not implement any priorities.

 */

#define URT_EVENTMASK_MAXPRIO     (urt_osEventMask_t)1

/**

 * @brief   Type representing event flags.

 * @details Event flags can be used to represent rudiemntary metadata or filter events.

 */

typedef eventflags_t urt_osEventFlags_t;

/**

 * @brief   Event source type.

 */

typedef event_source_t urt_osEventSource_t;

/**

 * @brief   Initialize an event source object.

 *

 * @param[in]   source    The event source object to initialize.

 */

static inline void urtEventSourceInit(urt_osEventSource_t* source)

{

  aosDbgCheck(source != NULL);

  chEvtObjectInit(source);

}

/**

 * @brief   Broadcast an event via the source.

 *

 * @param[in]   source    The event source to use for broadcasting.

 * @param[in]   flags     Flags to be broadcasted along with the event.

 */

static inline void urtEventSourceBroadcast(urt_osEventSource_t* source, urt_osEventFlags_t flags)

{

  aosDbgCheck(source != NULL);

  chEvtBroadcastFlags(source, flags);

}

/**

 * @brief   Event listener type.

 */

typedef event_listener_t urt_osEventListener_t;

/**

 * @brief   Initialize an event listener object.

 *

 * @param[in]   listener    The vent listener object to initialize.

 */

static inline void urtEventListenerInit(urt_osEventListener_t* listener)

{

  aosDbgCheck(listener != NULL);

  (void)listener;

  return;

}

/**

 * @brief   Retrieve the flags of a listener.

 *

 * @param[in]   listener    Event listener to retrieve the flags from.

 *

 * @return  The flag mask of the event listener.

 */

static inline urt_osEventFlags_t urtEventListenerGetFlags(urt_osEventListener_t* listener)

{

  aosDbgCheck(listener != NULL);

  return listener->flags;

}

/**

 * @brief   Retrieve and clear the flags of listener.

 *

 * @param[in]   listener    Event listener to retrieve and clear the flags from.

 *

 * @return    The flag mask of the event listener before it was cleared.

 */

static inline urt_osEventFlags_t urtEventListenerGetAndClearFlags(urt_osEventListener_t* listener)

{

  aosDbgCheck(listener != NULL);

  return chEvtGetAndClearFlags(listener);

}

/**

 * @brief   Register an event source and listener with an individual event nask.

 *

 * @param[in]   source      The event source to register.

 * @param[in]   listener    The event listener to register.

 * @param[in]   mask        Individual event mask to idetify these evente.

 *

 * @return  Status indicating whether registration was successful.

 */

static inline urt_status_t urtEventRegister(urt_osEventSource_t* source, urt_osEventListener_t* listener, urt_osEventMask_t mask)

{

  aosDbgCheck(source!= NULL);

  aosDbgCheck(listener != NULL);

  chEvtRegisterMask(source, listener, mask);

  return URT_STATUS_OK;

}

/**

 * @brief   Unregister an event source and listener.

 *

 * @param[in]   source      The event source to unregister.

 * @param[in]   listener    The event listener to unregister.

 *

 * @return  Status indicating whether unregistration was successful.

 */

static inline urt_status_t urtEventUnregister(urt_osEventSource_t* source, urt_osEventListener_t* listener)

{

  aosDbgCheck(source != NULL);

  aosDbgCheck(listener != NULL);

  chEvtUnregister(source, listener);

  return URT_STATUS_OK;

}

/**

 * @brief   Wait for one, any or all specified events to occur.

 *

 * @param[in]   mask      An event mask for filtering events.

 * @param[in]   type      Specifier to define how to wait for one or multiple events.

 * @param[in]   timeout   Timeout after which the function will return.

 *

 * @return  The ORed event mask of all received events.

 *          In case of a timeout it will be zero.

 */

static inline urt_osEventMask_t urtEventWait(urt_osEventMask_t mask, urt_osEventWaitType_t type, urt_delay_t timeout)

{

  switch (type) {

    case URT_EVENT_WAIT_ONE:

      return chEvtWaitOneTimeout(mask, timeout);

    case URT_EVENT_WAIT_ANY:

      return chEvtWaitAnyTimeout(mask, timeout);

    case URT_EVENT_WAIT_ALL:

      return chEvtWaitAllTimeout(mask, timeout);

  }

}

/*============================================================================*/

/* MUTEX LOCK                                                                 */

/*============================================================================*/

/**

 * @brief   Mutex lock type.

 */

typedef mutex_t urt_osMutex_t;

/**

 * @brief   Initialization of a mutex lock object.

 *

 * @param[in]   mutex   The mutex lock object to initialize.

 */

static inline void urtMutexInit(urt_osMutex_t* mutex)

{

  aosDbgCheck(mutex != NULL);

  chMtxObjectInit(mutex);

}

/**

 * @brief   Lock a mutex lock (blocking).

 * @details If the specified mutex is curently locked, the function will block until it could be acquired.

 *

 * @param[in]   mutex   The mutex lock to lock.

 */

static inline void urtMutexLock(urt_osMutex_t* mutex)

{

  aosDbgCheck(mutex != NULL);

  chMtxLock(mutex);

}

/**

 * @brief   Try to lock a mutex lock (unblocking)

 * @details If the mutex lock is currently locked, the function will return immediately.

 *

 * @param[in]   mutex   The mutex lock to lock.

 *

 * @return  Status indicating whether the mutex lock could be acquired.

 */

static inline bool urtMutexTryLock(urt_osMutex_t* mutex)

{

  aosDbgCheck(mutex != NULL);

  return chMtxTryLock(mutex);

}

/**

 * @brief   Unlock an owned mutex lock.

 *

 * @param[in]   mutex   The mutex lock to unlock.

 */

static inline void urtMutexUnlock(urt_osMutex_t* mutex)

{

  aosDbgCheck(mutex != NULL);

  chMtxUnlock(mutex);

}

/*============================================================================*/

/* CONDITION VARIABLE                                                         */

/*============================================================================*/

/**

 * @brief   Condition variable type.

 */

typedef condition_variable_t urt_osCondvar_t;

/**

 * @brief   Initialize a condition variable object.

 *

 * @param[in]   condvar   The condition variable object to initualize.

 */

static inline void urtCondvarInit(urt_osCondvar_t* condvar)

{

  aosDbgCheck(condvar != NULL);

  chCondObjectInit(condvar);

}

/**

 * @brief   Signal a condition variable.

 *

 * @param[in]   condvar   The condition variable to be signaled.

 */

static inline void urtCondvarSignal(urt_osCondvar_t* condvar)

{

  aosDbgCheck(condvar != NULL);

  chCondSignal(condvar);

}

/**

 * @brief   Broadcast a condition variable.

 *

 * @param[in]   condvar   The condition variable to be broadcasted.

 */

static inline void urtCondvarBroadcast(urt_osCondvar_t* condvar)

{

  aosDbgCheck(condvar != NULL);

  chCondBroadcast(condvar);

}

/**

 * @brief   Wait for a condition variable.

 *

 * @param[in]   condvar   The condition variable to wait for.

 * @param[in]   mutex     A priviously acquired mutex lock.

 * @param[in]   timeout   A timeout when the function will return.

 *

 * @return  Status indicating how the condition variable was signaled or whether a timeout occurred.

 */

static inline urt_condvarStatus_t urtCondvarWait(urt_osCondvar_t* condvar, urt_osMutex_t* mutex, urt_delay_t timeout)

{

  aosDbgCheck(condvar != NULL);

  aosDbgCheck(mutex != NULL);

  (void)mutex;

  switch (chCondWaitTimeout(condvar, timeout)) {

    case MSG_OK:

      return URT_CONDVAR_STATUS_SIGNAL;

    case MSG_RESET:

      return URT_CONDVAR_STATUS_BROADCAST;

    case MSG_TIMEOUT:

      return URT_CONDVAR_STATUS_TIMEOUT;

    default:

      chSysHalt(__func__);

      return URT_CONDVAR_STATUS_TIMEOUT;

  }

}

/*============================================================================*/

/* THREAD                                                                     */

/*============================================================================*/

/**

 * @brief   Thread priority data type.

 */

typedef tprio_t urt_osThreadPrio_t;

/**

 * @brief   Minimum thread priority.

 */

#define URT_THREAD_PRIO_LOW_MIN                 AOS_THD_LOWPRIO_MIN

/**

 * @brief   Maximum thread priority for low priority class threads.

 */

#define URT_THREAD_PRIO_LOW_MAX                 AOS_THD_LOWPRIO_MAX

/**

 * @brief   Minimum thread priority for normal priority class threads.

 */

#define URT_THREAD_PRIO_NORMAL_MIN              AOS_THD_NORMALPRIO_MIN

/**

 * @brief   Maximum thread priority for normal priority class threads.

 */

#define URT_THREAD_PRIO_NORMAL_MAX              AOS_THD_NORMALPRIO_MAX

/**

 * @brief   Minimum thread priority for high priority class threads.

 */

#define URT_THREAD_PRIO_HIGH_MIN                AOS_THD_HIGHPRIO_MIN

/**

 * @brief   Maximum thread priority for high priority class threads.

 */

#define URT_THREAD_PRIO_HIGH_MAX                AOS_THD_HIGHPRIO_MAX

/**

 * @brief   Minimum thread priority for real-time class threads.

 */

#define URT_THREAD_PRIO_RT_MIN                  AOS_THD_RTPRIO_MIN

/**

 * @brief   maximum thread priority for real-time class threads.

 */

#define URT_THREAD_PRIO_RT_MAX                  AOS_THD_RTPRIO_MAX

/**

 * @brief   Thread data type.

 */

typedef thread_t urt_osThread_t;

/**

 * @brief   Maximum number of seconds a thread can sleep.

 */

#define URT_THREAD_SLEEP_MAX                    (float)AOS_THD_MAX_SLEEP_S

/**

 * @brief   Maximum number of seconds a thread can sleep.

 */

#define URT_THREAD_SSLEEP_MAX                   (unsigned int)AOS_THD_MAX_SLEEP_S

/**

 * @brief   Maximum number of milliseconds a thread can sleep.

 */

#define URT_THREAD_MSLEEP_MAX                   (unsigned int)AOS_THD_MAX_SLEEP_MS

/**

 * @brief   Maximum number of microseconds a thread can sleep.

 */

#define URT_THREAD_USLEEP_MAX                   (urt_delay_t)AOS_THD_MAX_SLEEP_US

/**

 * @brief   Macro function to layout a thread memory.

 * @details The overall memory required for a thread usually is a combination of the stack and some further data (i.e. the thread object itself).

 *          The layout in memory as well as the metadata may differ between kernels and event hardware ports.

 *

 * @param[in]   varname     The name of the resulting buffer variable.

 * @param[in]   stacksize   The size of the thread's stack.

 */

#define URT_THREAD_MEMORY(varname, stacksize)   THD_WORKING_AREA(varname, stacksize)

/**

 * @brief   Initialize a thread object.

 * @details The thread is created but not started yet.

 *

 * @param[in]   memory    The thread memory to use (see @p URT_THREAD_MEMORY)

 * @param[in]   size      Size of the thread memory in bytes.

 * @param[in]   func      The thread main function to execute.

 *

 * @return  Pointer to the created thread object.

 */

static inline urt_osThread_t* urtThreadInit(void* memory, size_t size, urt_osThreadFunction_t func)

{

  aosDbgCheck(memory != NULL);

  aosDbgCheck(size != 0);

  aosDbgCheck(func != NULL);

  const thread_descriptor_t descriptor = {

    /* name                         */ "",

    /* pointer to working area base */ (stkalign_t*)memory,

    /* end of the working area      */ &((stkalign_t*)memory)[size / sizeof(stkalign_t)],

    /* thread priority              */ URT_THREAD_PRIO_LOW_MIN,

    /* thread function pointer      */ func,

    /* thread argument              */ NULL,

    /* pointer to the parent thread */ chThdGetSelfX(),

  };

  urt_osThread_t* thread = chThdCreateSuspended(&descriptor);

  // store the function pointer in the stack (required for urtThreadStart())

  *((urt_osThreadFunction_t*)thread->wabase) = func;

  return thread;

}

/**

 * @brief   Start a previously initialized thread.

 *

 * @param[in]   thread    Pointer to the thread to start.

 * @param[in]   prio      Priority to set for the thread.

 * @param[in]   arg       Optional arguments for the thread function.

 */

static inline void urtThreadStart(urt_osThread_t* thread, urt_osThreadPrio_t prio, void* arg)

{

  aosDbgCheck(thread != NULL);

  aosDbgCheck(prio >= URT_THREAD_PRIO_LOW_MIN && prio <= URT_THREAD_PRIO_RT_MAX);

  PORT_SETUP_CONTEXT(thread, thread->wabase, thread, *(urt_osThreadFunction_t*)thread->wabase, arg);

  chThdSetPriority(prio);

  chThdStart(thread);

}

/**

 * @brief   The calling thread yields execution until it is scheduled again.

 */

static inline void urtThreadYield(void)

{

  chThdYield();

}

/**

 * @brief   Retrieve the currently set priority of the calling thread.

 * @return

 */

static inline urt_osThreadPrio_t urtThreadGetPriority(void)

{

  return chThdGetPriorityX();

}

/**

 * @brief   Set a new priority for the calling thread.

 *

 * @param[in]   prio    The new priority to set.

 */

static inline void urtThreadSetPriority(urt_osThreadPrio_t prio)

{

  aosDbgCheck(prio >= URT_THREAD_PRIO_LOW_MIN && prio <= URT_THREAD_PRIO_RT_MAX);

  chThdSetPriority(prio);

}

/**

 * @brief   suspend execution of the calling thread.

 */

static inline void urtThreadSuspend()

{

  thread_reference_t ref = chThdGetSelfX();

  chSysLock();

  chThdSuspendS(&ref);

  chSysUnlock();

}

/**

 * @brief   Resume a suspended thread.

 *

 * @param[in]   thread    The suspended thread to be resumed.

 *

 * @return  Status indicating whether resuming the thread was successful.

 */

static inline urt_status_t urtThreadResume(urt_osThread_t* thread)

{

  aosDbgCheck(thread != NULL);

  thread_reference_t ref = thread;

  chSysLock();

  chThdResumeS(&ref, thread->u.rdymsg);

  chSysUnlock();

  return URT_STATUS_OK;

}

/**

 * @brief   The calling thread sleeps for the specified amount of time (seconds).

 *

 * @param[in]   seconds   The duration to sleep in seconds.

 */

static inline void urtThreadSleep(float seconds)

{

  aosDbgCheck(seconds <= URT_THREAD_SLEEP_MAX);

  aosThdSleep(seconds);

}

/**

 * @brief   The calling thread sleeps for the specified amount of time (seconds).

 *

 * @param[in]   seconds   The duration to sleep in seconds.

 */

static inline void urtThreadSSleep(unsigned int seconds)

{

  aosDbgCheck(seconds <= URT_THREAD_SSLEEP_MAX);

  aosThdSSleep(seconds);

}

/**

 * @brief   The calling thread sleeps for the specified amount of time (milliseconds).

 *

 * @param[in]   milliseconds    The duration to sleep in milliseconds.

 */

static inline void urtThreadMSleep(unsigned int milliseconds)

{

  aosDbgCheck(milliseconds <= URT_THREAD_MSLEEP_MAX);

  aosThdMSleep(milliseconds);

}

/**

 * @brief   The calling thread sleeps for the specified amount of time (microseconds).

 *

 * @param[in]   microseconds    The duration to sleep in microseconds.

 */

static inline void urtThreadUSleep(unsigned int microseconds)

{

  aosDbgCheck(microseconds <= URT_THREAD_USLEEP_MAX);

  aosThdUSleep(microseconds);

}

/**

 * @brief   The calling thread sleeps until the specified system time.

 *

 * @param[in]   time    The system time to wake up again.

 */

static inline void urtThreadSleepUntil(urt_osTime_t time)

{

  aosThdSleepUntil(&time);

}

/**

 * @brief   The calling thread terminates and ends execution.

 */

static inline void urtThreadExit(void)

{

  chThdExit(MSG_OK);

}

/**

 * @brief   Make a thread terminate.

 *

 * @param[in]   thread    The thread to be terminated.

 * @param[in]   sig       The signal value how to terminate the thread.

 */

static inline void urtThreadTerminate(urt_osThread_t* thread, urt_osThreadTerminateSignal_t sig)

{

  aosDbgCheck(thread != NULL);

  /*

   * TODO: implement kill functionality.

   */

  (void)sig;

  chThdTerminate(thread);

}

/**

 * @brief   Wait for a thread to terminate.

 *

 * @param[in]   thread    The thread to wait for.

 *

 * @return  Status value of the terminated thread (0 = success).

 */

static inline int urtThreadJoin(urt_osThread_t* thread)

{

  aosDbgCheck(thread != NULL);

  return chThdWait(thread);

}

/**

 * @brief   Retrieve the current execution state of a thread.

 *

 * @param[in]   thread    Thread to retrieve the execution state from.

 *

 * @return  Execution state of the specified thread.

 */

static inline urt_osThreadState_t urtThreadGetState(urt_osThread_t* thread)

{

  aosDbgCheck(thread != NULL);

  switch (thread->state) {

    case CH_STATE_CURRENT:

      return URT_THREAD_STATE_RUNNING;

    case CH_STATE_READY:

      return URT_THREAD_STATE_READY;

    case CH_STATE_SLEEPING:

      return URT_THREAD_STATE_SLEEPING;

    case CH_STATE_WTSTART:

    case CH_STATE_SUSPENDED:

      return URT_THREAD_STATE_SUSPENDED;

    case CH_STATE_FINAL:

      return URT_THREAD_STATE_TERMINATED;

    case CH_STATE_QUEUED:

    case CH_STATE_WTSEM:

    case CH_STATE_WTMTX:

    case CH_STATE_WTCOND:

    case CH_STATE_WTEXIT:

    case CH_STATE_WTOREVT:

    case CH_STATE_WTANDEVT:

    case CH_STATE_SNDMSGQ:

    case CH_STATE_SNDMSG:

    case CH_STATE_WTMSG:

    default:

      return URT_THREAD_STATE_WAITING;

  }

}

/**

 * @brief   The calling thread retrieves a pointer to itself.

 *

 * @return  Pointer to the calling thread object.

 */

static inline urt_osThread_t* urtThreadGetSelf(void)

{

  return chThdGetSelfX();

}

/**

 * @brief   Retrieve the first child of a thread.

 *

 * @param[in]   thread    Thread to retrieve the children from.

 *

 * @return  Pointer to the first child or @p NULL if the thread has no children.

 */

static inline urt_osThread_t* urtThreadGetChildren(urt_osThread_t* thread)

{

  aosDbgCheck(thread != NULL);

  return thread->children;

}

/**

 * @brief   Retrieve a sibling of a thread.

 *

 * @param[in]   thread    Thread to retrieve the siblsing from.

 *

 * @return  Pointer to the sibling thread or @p NULL if there are no further siblings.

 */

static inline urt_osThread_t* urtThreadGetSibling(urt_osThread_t* thread)

{

  aosDbgCheck(thread != NULL);

  return thread->sibling;

}

/**

 * @brief   Retrieve the parent of a thread.

 *

 * @param[in]   thread    Thread to retrieve the parent from.

 *

 * @return  Pointer to the parent thread or @p NULL if there is nor parent.

 */

static inline urt_osThread_t* urtThreadGetParent(urt_osThread_t* thread)

{

  aosDbgCheck(thread != NULL);

  return thread->parent;

}

#endif /* _URT_OSAL_H_ */