Watchdog.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!*****************************************************************************
 *  @file       Watchdog.h
 *
 *  @brief      Watchdog driver interface
 *
 *  @anchor ti_drivers_Watchdog_Overview
 *  # Overview #
 *
 *  A watchdog timer can be used to generate a reset signal if a system has
 *  become unresponsive. The Watchdog driver simplifies configuring and
 *  starting the watchdog peripherals. The watchdog peripheral can be
 *  configured with resets either on or off and a user-specified timeout
 *  period.
 *
 *  When the watchdog peripheral is configured not to generate a reset, it
 *  can be used to cause a hardware interrupt at a programmable interval.
 *  The driver provides the ability to specify a user-provided callback
 *  function that is called when the watchdog causes an interrupt.
 *
 *  The Watchdog driver simplifies configuring and starting the Watchdog
 *  peripherals. The Watchdog can be set up to produce a reset signal after a
 *  timeout, or simply cause a hardware interrupt at a programmable interval.
 *  The driver provides the ability to specify a callback function that is
 *  called when the Watchdog causes an interrupt.
 *
 *  When resets are turned on, it is the user application's responsibility to
 *  call Watchdog_clear() in order to clear the Watchdog and prevent a reset.
 *  Watchdog_clear() can be called at any time.
 *
 *  @anchor ti_drivers_Watchdog_Usage
 *  # Usage #
 *
 *  This section will cover driver usage.
 *  @anchor ti_drivers_Watchdog_Synopsis
 *  ## Synopsis #
 *
 *  Open the driver with default settings:
 *  @code
 *  Watchdog_Handle watchdogHandle;
 *
 *  Watchdog_init();
 *  watchdogHandle = Watchdog_open(WATCHDOG_INDEX, NULL);
 *  if (watchdogHandle == NULL) {
 *      // Spin forever
 *      while(1);
 *  }
 *  @endcode
 *
 *  The Watchdog driver must be initialized by calling Watchdog_init(),
 *  before any other Watchdog APIs can be called.
 *  Once the watchdog is initialized, a Watchdog object can be created
 *  through the following steps:
 *  -   Create and initialize the #Watchdog_Params structure.
 *  -   Assign desired values to parameters.
 *  -   Call Watchdog_open().
 *  -   Save the Watchdog_Handle returned by Watchdog_open(). This will be
 *  used to interact with the Watchdog object just created.
 *
 *  To have a user-defined function run at the hardware interrupt caused by
 *  a watchdog timer timeout, define a function of the following type:
 *  @code
 *    typedef void (*Watchdog_Callback)(uintptr_t);
 *  @endcode
 *  Then pass the function to Watchdog_open() through the #Watchdog_Params
 *  structure.
 *
 *  An example of the Watchdog creation process that uses a callback
 *  function:
 *  @anchor ti_drivers_Watchdog_example_callback
 *  @code
 *  void UserCallbackFxn(Watchdog_Handle handle)
 *  {
 *      printf("Watchdog timer triggered!\n");
 *      releaseResources();
 *  }
 *
 *  ...
 *
 *  Watchdog_Params params;
 *  Watchdog_Handle watchdogHandle;
 *
 *  Watchdog_init();
 *
 *  Watchdog_Params_init(&params);
 *  params.resetMode = Watchdog_RESET_ON;
 *  params.callbackFxn = (Watchdog_Callback) UserCallbackFxn;
 *
 *  watchdogHandle = Watchdog_open(CONFIG_WATCHDOG0, &params);
 *  if (watchdogHandle == NULL) {
 *     // Error opening Watchdog
 *     while (1);
 *  }
 *
 *  @endcode
 *
 *  If no #Watchdog_Params structure is passed to Watchdog_open(), the
 *  default values are used. By default, the Watchdog driver has resets
 *  turned on, no callback function specified, and stalls the timer at
 *  breakpoints during debugging.
 *
 *  Options for the resetMode parameter are #Watchdog_RESET_ON and
 *  #Watchdog_RESET_OFF. The latter allows the watchdog to be used like
 *  another timer interrupt. When resetMode is #Watchdog_RESET_ON, it is up
 *  to the application to call Watchdog_clear() to clear the Watchdog
 *  interrupt flag to prevent a reset. Watchdog_clear() can be called at
 *  any time.
 *
 *  @anchor ti_drivers_Watchdog_Examples
 *  # Examples
 *  - @ref ti_drivers_Watchdog_Synopsis "Default Example"
 *  - @ref ti_drivers_Watchdog_example_callback "Callback Function before watchdog reset"
 *
 *  @anchor ti_drivers_Watchdog_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for more information.
 *
 *******************************************************************************
 */

#ifndef ti_drivers_Watchdog__include
#define ti_drivers_Watchdog__include

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define Watchdog_CMD_RESERVED            (32)

#define Watchdog_STATUS_RESERVED        (-32)

#define Watchdog_STATUS_SUCCESS        (0)

#define Watchdog_STATUS_ERROR          (-1)

#define Watchdog_STATUS_UNDEFINEDCMD   (-2)

#define Watchdog_STATUS_UNSUPPORTED   (-3)

/* Add Watchdog_CMD_<commands> here */

typedef struct Watchdog_Config_ *Watchdog_Handle;

typedef enum {
    Watchdog_DEBUG_STALL_ON, 
    Watchdog_DEBUG_STALL_OFF 
} Watchdog_DebugMode;

typedef enum {
    Watchdog_RESET_OFF, 
    Watchdog_RESET_ON   
} Watchdog_ResetMode;

typedef void (*Watchdog_Callback)(uintptr_t handle);

typedef struct {
    Watchdog_Callback   callbackFxn;    
    Watchdog_ResetMode  resetMode;      
    Watchdog_DebugMode  debugStallMode; 
    void               *custom;         
} Watchdog_Params;

typedef void (*Watchdog_ClearFxn)       (Watchdog_Handle handle);

typedef void (*Watchdog_CloseFxn)       (Watchdog_Handle handle);

typedef int_fast16_t (*Watchdog_ControlFxn) (Watchdog_Handle handle,
                                             uint_fast16_t cmd,
                                             void *arg);

typedef void (*Watchdog_InitFxn)        (Watchdog_Handle handle);

typedef Watchdog_Handle (*Watchdog_OpenFxn)  (Watchdog_Handle handle,
                                              Watchdog_Params *params);

typedef int_fast16_t (*Watchdog_SetReloadFxn)(Watchdog_Handle handle,
    uint32_t ticks);

typedef uint32_t (*Watchdog_ConvertMsToTicksFxn)   (Watchdog_Handle handle,
                                                    uint32_t milliseconds);

typedef struct {
    Watchdog_ClearFxn             watchdogClear;
    Watchdog_CloseFxn             watchdogClose;
    Watchdog_ControlFxn           watchdogControl;
    Watchdog_InitFxn              watchdogInit;
    Watchdog_OpenFxn              watchdogOpen;
    Watchdog_SetReloadFxn         watchdogSetReload;
    Watchdog_ConvertMsToTicksFxn  watchdogConvertMsToTicks;
} Watchdog_FxnTable;

typedef struct Watchdog_Config_ {
    Watchdog_FxnTable const *fxnTablePtr;

    void                    *object;

    void              const *hwAttrs;
} Watchdog_Config;

extern void Watchdog_clear(Watchdog_Handle handle);

extern void Watchdog_close(Watchdog_Handle handle);

extern int_fast16_t Watchdog_control(Watchdog_Handle handle,
                                     uint_fast16_t cmd,
                                     void *arg);

extern void Watchdog_init(void);

extern Watchdog_Handle Watchdog_open(uint_least8_t index, Watchdog_Params *params);

extern void Watchdog_Params_init(Watchdog_Params *params);

extern int_fast16_t Watchdog_setReload(Watchdog_Handle handle, uint32_t ticks);

extern uint32_t Watchdog_convertMsToTicks(Watchdog_Handle handle,
    uint32_t milliseconds);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_Watchdog__include */