m2mb_wDog.h

Go to the documentation of this file.

/* $version: 372317T2_R1  */ 
/*===============================================================================================*/
/*         >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<<          */
#ifndef M2MB_WDOG_H
#define M2MB_WDOG_H
 
/* Include ======================================================================================*/
 
 
/* Global declarations ==========================================================================*/
#define M2MB_WDOG_INVALID    0
 
#define M2MB_WDOG_ENABLED            TRUE
#define M2MB_WDOG_DISABLED           FALSE
#define M2MB_WDOG_GPIO_ISR_ENABLE    TRUE
#define M2MB_WDOG_GPIO_ISR_DISABLE   FALSE
 
/* Global typedefs ==============================================================================*/
/* define the handle for watchdog management */
typedef struct M2MB_WDOG_HANDLE_TAG *M2MB_WDOG_HANDLE;
 
/* possible events on watchdog indication callback */
typedef enum
{
  M2MB_WDOG_TIMEOUT_IND,
  ENUM_TO_INT( M2MB_WDOG_IND_E )
} M2MB_WDOG_IND_E;
 
/* command selection to be used in m2mb_wdog_getItem: parameters are set instead using proper APIs.
   Please note that here below sometimes the commands
   are used in the description as they were the associated parameters values
   that can be retrieved using the same commands:
   e.g
   "after M2MB_WDOG_SELECT_CMD_MAX_TICKS_TO_REBOOT" is intended after the value you can get calling
   m2mb_wdog_getItem with M2MB_WDOG_SELECT_CMD_MAX_TICKS_TO_REBOOT command
*/
typedef enum
{
  /* general instance control activity counter in ticks, both for task control and ISR
     depending on handle type
*/
  M2MB_WDOG_SELECT_CMD_TICKS,
  /* reboots the system in case no action is taken after watchdog timeout reached for at least a task.
     In case instance is managed by ISR, please reboots after M2MB_WDOG_SELECT_CMD_MAX_TICKS_TO_REBOOT.
     For example, if system is in busy loop, since in this scenario callback could not be invoked,
     the system is rebooted after M2MB_WDOG_SELECT_CMD_MAX_TICKS_TO_REBOOT if callback is not called
  */
  M2MB_WDOG_SELECT_CMD_MAX_TICKS_TO_REBOOT,
  /* instance counter value: from M2MB_WDOG_SELECT_CMD_TICKS_WAKEUP to 0 */
  M2MB_WDOG_SELECT_CMD_CNT,
  /* wake_up means how many control events before actual control, both ISR or task.
     On ISR, to optimize the performances, it is better to set correctly the HW signal on gpio instead
     of SW use; basically, it is better to set M2MB_WDOG_SELECT_CMD_TICKS_WAKEUP to 1 for ISR, when possible.
     On task control, value from M2MB_WDOG_SELECT_CMD_TICK_DURATION_MS can be used to properly adjust
     M2MB_WDOG_SELECT_CMD_TICKS_WAKEUP
  */
  M2MB_WDOG_SELECT_CMD_TICKS_WAKEUP,
  /* provide status on ISR set: if M2MB_WDOG_GPIO_ISR_ENABLE instance is set as ISR */
  M2MB_WDOG_SELECT_CMD_ISR,
  /* M2MB_WDOG_DISABLED if disable or M2MB_WDOG_ENABLED if instance control is enabled */
  M2MB_WDOG_SELECT_CMD_STATUS,
  /* meaningful only for wDog in task control type, not in ISR */
  M2MB_WDOG_SELECT_CMD_TICK_DURATION_MS,
  /* task counter from M2MB_WDOG_SELECT_CMD_TASK_TIMEOUT to 0 for task in selected instance */
  M2MB_WDOG_SELECT_CMD_TASK_CNT,
  M2MB_WDOG_SELECT_CMD_TASK_TIMEOUT,
  /* M2MB_WDOG_SELECT_CMD_TASK_TIMED_OUT and M2MB_WDOG_SELECT_CMD_NEXT_EXPIRING_TASK,
    belong to instance, task handle is ignored for these commands selections
    task handle is the returned value
  */
  /* timed out task in the instance, if any; it reports only the first task timed out occurred,
     while any counter of every other task in the instance, is kept frozen.
     M2MB_OS_TASK_INVALID in case no timed out task */
  M2MB_WDOG_SELECT_CMD_TASK_TIMED_OUT,
  /* next expiring task in the instance */
  M2MB_WDOG_SELECT_CMD_NEXT_EXPIRING_TASK,
  ENUM_TO_INT( M2MB_WDOG_SELECT_CMD_E )
} M2MB_WDOG_SELECT_CMD_E;
 
/* callback invoked during watchdog event like M2MB_WDOG_TIMEOUT_IND
   resp_struct is generally a pointer to the response related to each M2MB_WDOG_IND_E event
   and should be casted to it. resp_size is related to specific undefined field in structure
   where present or it is the size of structure itself(e.g. data)
   For M2MB_WDOG_TIMEOUT_IND, event resp_size and resp_struct has not to be used for
   m2mb_wDog module. Info can be collected like below example
   void watchdog_callback( M2MB_WDOG_HANDLE hDog, M2MB_WDOG_IND_E wDog_event,
                                 UINT16 resp_size, void *resp_struct, void *userdata )
   {
     M2MB_OS_TASK_HANDLE hTask;
     M2MB_RESULT_E m2mbRes;
     UNUSED_3( resp_size, resp_struct, userdata ); //depending on which input parameters are not used
 
     switch( wDog_event )
     {
       case M2MB_WDOG_TIMEOUT_IND:
         m2mbRes = m2mb_wDog_disable( hDog ); //disable if it is desired
         //get info on which task timed out
         m2mbRes = m2mb_wDog_getItem( hDog, M2MB_WDOG_SELECT_CMD_TASK_TIMED_OUT, 0, ( MEM_W *)&hTask );
         //performs some log if needed
         //performs in case action like restarting the involved application, having previously get the
         //application handle appMngH
         m2mb_appMng_restart( appMngH );
       break;
 
       default:
       break;
     }
   }
*/
typedef void ( *M2MB_WDOG_IND_CALLBACK )( M2MB_WDOG_HANDLE h, M2MB_WDOG_IND_E wDog_event,
                                          UINT16 resp_size, void *resp_struct, void *userdata );
 
/* Global functions =============================================================================*/
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_init( M2MB_WDOG_HANDLE *h, M2MB_WDOG_IND_CALLBACK wDogCallback, void *userdata );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_deinit( M2MB_WDOG_HANDLE h );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_enable( M2MB_WDOG_HANDLE h, MEM_W wDogWakeUpTicks, MEM_W ticksToReboot );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_disable( M2MB_WDOG_HANDLE h );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_reset( M2MB_WDOG_HANDLE h );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_isr( M2MB_WDOG_HANDLE h, const CHAR *gpioPath, M2MB_GPIO_TRIGGER_E edgeTrigger );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_addTask( M2MB_WDOG_HANDLE h, M2MB_OS_TASK_HANDLE hTask, UINT32 wdTimeout );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_removeTask( M2MB_WDOG_HANDLE h, M2MB_OS_TASK_HANDLE hTask );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_kick( M2MB_WDOG_HANDLE h, M2MB_OS_TASK_HANDLE hTask );
 
/*------------------------------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------------------------*/
M2MB_RESULT_E m2mb_wDog_getItem( M2MB_WDOG_HANDLE h, M2MB_WDOG_SELECT_CMD_E wDogCmd,
                                 M2MB_OS_TASK_HANDLE hTask, MEM_W *pOut );
 
 
/* Global define ================================================================================*/
 
#endif /* M2MB_WDOG_H */