glue_timers.c

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2004 Ocean Blue Software Ltd
 * Copyright © 2000 Koninklijke Philips Electronics N.V
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 *
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
/*---includes for this file--------------------------------------------------*/
#include <stdlib.h>
#include "stb_os.h"
#include "glue_memory.h"
#include "glue_debug.h"
#include "glue_timers.h"

/*---constant definitions for this file--------------------------------------*/

/* Some magic numbers which are set in the timer info structure to help detect
 * for invalid handles
 */
#define MHEG_TIMER_MAGIC            0xc10c0000

/* Maximum wait of the OSAL is 0x7fffffff ms. We specify a maximum timeout of 1
 * minute to try to recover from programming errors.
 */
#define MHEG_TIMER_MAX_WAIT         60000

/* Define the accuracy with which we expect timers to fire in milliseconds. They
 * may fire up to this many milliseconds early.
 *
 * NOTE: A problem with dvp1 beta2 nt4 build was found. A timeout of 1 millisec
 * appears to wait indefinately, so this value should be 2 or greater.
 */
#define MHEG_TIMER_ACCURACY         5

#define SIZEOF_TIMER_EVENT_MSG      1
#define MAX_NUM_TIMER_EVENT_MSG     100


/*---local typedef structs for this file-------------------------------------*/

/* Fill in the structure that an H_Timer points to. This has the
 * following members:
 *      timerHdl        Handle/Identity (with magic number for validating)
 *      triggerTime     Absolute system time that the timer will trigger
 *      callback        Pointer to the callback function that will be invoked
 *                      when the timer expires or is destroyed when unexpired.
 *      callerRef       Caller reference that will be passed to the callback
 *      next            Pointer to next timer in the timer list.
 */
typedef struct s_timer_info
{
   U_PARAM timerHdl;
   U32BIT triggerTime;
   F_TimerCallback callback;
   void *callerRef;
   struct s_timer_info *next;
} S_TIMER_INFO;

/*---local (static) variable declarations for this file----------------------*/

/* The timerListHead stores a pointer to the first timer in a linked list of
 * active timers. The list is always stored such that the next timer to fire
 * is at the head of the list.
 */
static S_TIMER_INFO *timerListHead = 0;

/* Handle of a mutex used to protect against simultaneous access of the list
 * of timers. Timer data that is on the list must not be read or written without
 * holding the mutex.
 */
static void *mhegTimerListMutex = 0;
static void *mhegTimerCountMutex = 0;

/* Handle of an event that is used to signal to the timer task that the head
 * of the timer list has changed. This event causes the main task timeout to be
 * re-evaluated. It is also used to wake the main task when we want it to die.
 */
static void *mhegTimerUpdateEvent = 0;

/* Handle of the timer task */
static void *mhegTimerTaskHandle = 0;

/* Set to TRUE to indicate that we want the main timer task to exit.
 */
static BOOLEAN mhegTimerQuit = FALSE;

/* Set to TRUE to indicate that the timer task is running.
 */
static BOOLEAN mhegTimerTaskRunning = FALSE;

/* Basis of timer identity - to be combined with magic number to create handle */
static U16BIT mhegTimerIdentityCount = 0;


/*---local function definitions----------------------------------------------*/

/*---global function definitions---------------------------------------------*/


static void TimersMain(void *pArg)
{
   S32BIT eventWaitTimeout = 0;
   U32BIT sysTime;

   U8BIT timerEventMsg;

   /* Show that the timer task is running */
   mhegTimerTaskRunning = TRUE;

   while (!mhegTimerQuit)
   {
      /* Get the current system time */
      sysTime = STB_OSGetClockMilliseconds();

      /* Adjust the system time to allow for a margin in the timeout. */
      sysTime += MHEG_TIMER_ACCURACY;

      /* Enter the mutex before we read/write the timer list */
      STB_OSMutexLock(mhegTimerListMutex);

      /* Check for events that need to fire */
      while ((timerListHead != 0) && (timerListHead->triggerTime <= sysTime))
      {
         S_TIMER_INFO *pOldTimerInfo;

         /* Keep a reference to this timer */
         pOldTimerInfo = timerListHead;

         /* Remove this timer from the list (it is at the head of the
          * list)
          */

         timerListHead = timerListHead->next;

         /* Call the callback for this timer. */
         (pOldTimerInfo->callback)( TRUE, pOldTimerInfo->callerRef,
            (H_Timer)pOldTimerInfo->timerHdl.ptr);

         /* Free the memory. */
         SYS_Free( pOldTimerInfo );
      }

      /* Calculate the timeout based on the first entry in the timer list */
      if (timerListHead == 0)
      {
         /* No entries left in timer list. Set out timeout variable to a
          * large value. We expect the task to be woken by an event (when
          * a new timer is added).
          */
         eventWaitTimeout = MHEG_TIMER_MAX_WAIT;
      }
      else
      {
         /* Calculate the number of milliseconds until the next timer fires
          * and use this as the timout for the event wait.
          */
         eventWaitTimeout = timerListHead->triggerTime - sysTime;

         /* Cap the event wait timeout to the max allowed value. */
         if (eventWaitTimeout > MHEG_TIMER_MAX_WAIT)
         {
            eventWaitTimeout = MHEG_TIMER_MAX_WAIT;
         }
      }

      /* We have finished with the timer list, so release the mutex */
      STB_OSMutexUnlock(mhegTimerListMutex);

      /* Wait for either:
       *  a) an event, indicating that a new entry has been added to the head
       *     of the list of timers.
       *  b) a timeout, indicating that the first timer entry should be fired
       */
      STB_OSReadQueue(mhegTimerUpdateEvent, (void *) &timerEventMsg, SIZEOF_TIMER_EVENT_MSG, (U16BIT) eventWaitTimeout);
   }

   /* Show that timer task is exiting */
   mhegTimerTaskRunning = FALSE;
}

E_MhegErr VT_TimerCreate(U32BIT millisecs,
   F_TimerCallback callback, void *callerRef,
   H_Timer *pTimerHandle)
{
   U32BIT sysTime;
   S_TIMER_INFO *pNewTimerInfo;

   U8BIT timerEventMsg;

   /* Initialise returned handle to 0 */
   *pTimerHandle = 0;

   /* Get the current system time */
   sysTime = STB_OSGetClockMilliseconds();

   if (!mhegTimerCountMutex || !mhegTimerListMutex)
   {
      return MHERR_COMP_NOT_STARTED;
   }

   /* Allocate memory for storing the timer */
   pNewTimerInfo = SYS_Alloc(sizeof(S_TIMER_INFO));
   if (pNewTimerInfo == 0)
   {
      return MHERR_ALLOCATING_MEMORY;
   }

   /* Add the relative time to the system time, detecting a wrap of the least
    * significant bits
    */
   pNewTimerInfo->triggerTime = sysTime + millisecs;

   pNewTimerInfo->callback = callback;
   pNewTimerInfo->callerRef = callerRef;

   /* We now need to insert the newly created entry into the linked list.
    * The linked list is kept in triggering order, so we need to insert the
    * new entry in the appropriate location in the list. If we add the new
    * timer to the head of the list we send an event to the main timer task
    * so that it can adjust it's timeout value.
    */

   /* Enter the mutex before we read/write the timer list */
   STB_OSMutexLock(mhegTimerCountMutex);
   ++mhegTimerIdentityCount;
   pNewTimerInfo->timerHdl.u32 = MHEG_TIMER_MAGIC | mhegTimerIdentityCount;
   STB_OSMutexUnlock(mhegTimerCountMutex);

   /* Pass the new timer handle back to the caller */
   *pTimerHandle = (H_Timer)pNewTimerInfo->timerHdl.ptr;

   STB_OSMutexLock(mhegTimerListMutex);
   if ((timerListHead == 0) ||
       (timerListHead->triggerTime >= pNewTimerInfo->triggerTime))
   {
      /* Either there are no entries in the list, or the first entry in the
       * list triggers after the new one. Add the new timer to the head of the
       * list
       */
      pNewTimerInfo->next = timerListHead;
      timerListHead = pNewTimerInfo;

      /* Notify the timer thread that the head of the list has changed. This
       * causes the timout to be re-evaluated.
       */
      STB_OSWriteQueue(mhegTimerUpdateEvent, (void *) &timerEventMsg, SIZEOF_TIMER_EVENT_MSG, TIMEOUT_NOW);
   }
   else
   {
      S_TIMER_INFO *pTimerInfo;

      /* Search through the list while
       *   a) we are not at the end of the list
       *   b) the next timer triggers before the new one
       */
      pTimerInfo = timerListHead;
      while ((pTimerInfo->next != 0) &&
             (pTimerInfo->next->triggerTime <= pNewTimerInfo->triggerTime))
      {
         pTimerInfo = pTimerInfo->next;
      }

      /* Insert the new timer into this position in the list */
      pNewTimerInfo->next = pTimerInfo->next;
      pTimerInfo->next = pNewTimerInfo;
   }

   /* We have finished with the timer list, so release the mutex */
   STB_OSMutexUnlock(mhegTimerListMutex);

   return MHERR_OK;
}

E_MhegErr VT_TimerDestroy(H_Timer timerHandle)
{
   U_PARAM timerHdl;
   S_TIMER_INFO *pOldTimerInfo = NULL;
   E_MhegErr retVal;

   timerHdl.ptr = timerHandle;
   assert((timerHdl.u32 & 0xffff0000) == MHEG_TIMER_MAGIC);

   if (mhegTimerListMutex == 0)
   {
      retVal = MHERR_COMP_NOT_OPEN;
   }
   else
   {
      /* Enter the mutex before we read/write the timer list */
      STB_OSMutexLock(mhegTimerListMutex);

      /* Check the handle that we have been passed */
      if (timerListHead == NULL)
      {
         retVal = MHERR_BAD_PARAMETER;
      }
      else
      {
         if (timerListHead->timerHdl.ptr == timerHdl.ptr)
         {
            pOldTimerInfo = timerListHead;
            timerListHead = timerListHead->next;
         }
         else
         {
            S_TIMER_INFO *pTimerInfo;
            S_TIMER_INFO *prevTimerInfo;
            prevTimerInfo = timerListHead;
            pTimerInfo = timerListHead->next;
            while (pTimerInfo != 0)
            {
               if (pTimerInfo->timerHdl.ptr == timerHdl.ptr)
               {
                  pOldTimerInfo = pTimerInfo;
                  prevTimerInfo->next = pTimerInfo->next;
                  break;
               }
               prevTimerInfo = pTimerInfo;
               pTimerInfo = pTimerInfo->next;
            }
         }

         if (pOldTimerInfo)
         {
            /* The timer was still in the active timer list. Call the callback
             * to allow the calling application to free of any resource for this
             * timer.
             * NOTE: The triggered flag is set to FALSE.
             */
            (pOldTimerInfo->callback)( FALSE, pOldTimerInfo->callerRef, (H_Timer)timerHdl.ptr);

            /* Free the memory. */
            SYS_Free(pOldTimerInfo);
            retVal = MHERR_OK;
         }
         else
         {
            retVal = MHERR_BAD_PARAMETER;
         }
      }

      /* We have finished with the timer list, so release the mutex */
      STB_OSMutexUnlock(mhegTimerListMutex);
   }

   return retVal;
}

E_MhegErr VT_TimersInit(U32BIT task_priority)
{
   if (mhegTimerTaskHandle != 0 && mhegTimerListMutex != 0)
   {
      /* aleady initialised - just say it is OK */
      return MHERR_OK;
   }
   else
   {
      /* Create the mutex for ensuring integrity of the timer list */
      mhegTimerListMutex = STB_OSCreateMutex();
      TRACE(TKEYS, ("mhegTimerListMutex=%d", mhegTimerListMutex))
      if (mhegTimerListMutex == NULL)
      {
         return MHERR_SYSTEM_RESOURCE_MUTEX;
      }
      mhegTimerCountMutex = STB_OSCreateMutex();
      TRACE(TKEYS, ("mhegTimerCountMutex=%d", mhegTimerCountMutex))
      if (mhegTimerCountMutex == NULL)
      {
         STB_OSDeleteMutex(mhegTimerListMutex);
         mhegTimerListMutex = 0;
         return MHERR_SYSTEM_RESOURCE_MUTEX;
      }

      /* Create the event used to notify the main task of a change to the head of
       * the timer list
       */
      mhegTimerUpdateEvent = STB_OSCreateQueue(SIZEOF_TIMER_EVENT_MSG, MAX_NUM_TIMER_EVENT_MSG);
      if (mhegTimerUpdateEvent == NULL)
      {
         STB_OSDeleteMutex(mhegTimerCountMutex);
         mhegTimerCountMutex = 0;
         STB_OSDeleteMutex(mhegTimerListMutex);
         mhegTimerListMutex = 0;
         return MHERR_SYSTEM_RESOURCE_QUEUE;
      }

      /*timer priority should be higher than the mheg engine*/
      task_priority += 2;

      /* Clear the quit flag so that the task can start */
      mhegTimerQuit = FALSE;

      /* Create the main timer task */
      mhegTimerTaskHandle = STB_OSCreateTask( TimersMain, NULL, 0x1000, (U8BIT)task_priority, (U8BIT *)"MhgTimers" );
      if (mhegTimerTaskHandle == NULL)
      {
         STB_OSDestroyQueue( mhegTimerUpdateEvent );
         mhegTimerUpdateEvent = 0;
         STB_OSDeleteMutex(mhegTimerCountMutex);
         mhegTimerCountMutex = 0;
         STB_OSDeleteMutex(mhegTimerListMutex);
         mhegTimerListMutex = 0;
         return MHERR_SYSTEM_RESOURCE_TASK;
      }
   }
   return MHERR_OK;
}

E_MhegErr VT_TimersExit(void)
{
   U8BIT timerEventMsg;

   /* Check that we are initialised */
   if (!mhegTimerTaskHandle)
   {
      return MHERR_COMP_NOT_OPEN;
   }

   /* Signal to the timer task that we want it to die. */
   mhegTimerQuit = TRUE;

   /* If the task is running kill it off. */
   if (mhegTimerTaskRunning)
   {
      STB_OSWriteQueue(mhegTimerUpdateEvent, (void *) &timerEventMsg, SIZEOF_TIMER_EVENT_MSG, TIMEOUT_NOW);

      /* Wait for the timer task to die. */
      while (mhegTimerTaskRunning)
      {
         /* Sleep for 10 ms */
         STB_OSTaskDelay(10);
      }
      STB_OSDestroyTask(mhegTimerTaskHandle);
      mhegTimerTaskHandle = 0;
      STB_OSDestroyQueue(mhegTimerUpdateEvent);
      mhegTimerUpdateEvent = NULL;
   }

   /* Destroy all resources */
   if (mhegTimerListMutex != 0)
   {
      STB_OSMutexLock(mhegTimerListMutex);
      /* Free off any timers left in the timer list */
      while (timerListHead != NULL)
      {
         S_TIMER_INFO *pTimerInfo;

         pTimerInfo = timerListHead;
         timerListHead = timerListHead->next;
         (pTimerInfo->callback)(FALSE, pTimerInfo->callerRef, (H_Timer)pTimerInfo->timerHdl.ptr);
         SYS_Free(pTimerInfo);
      }

      STB_OSMutexUnlock(mhegTimerListMutex);
      STB_OSDeleteMutex(mhegTimerCountMutex);
      mhegTimerCountMutex = 0;
      STB_OSDeleteMutex(mhegTimerListMutex);
      mhegTimerListMutex = 0;
   }
   return MHERR_OK;
}