Watchdog.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2025, 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. For CC35XX devices, debug stalling is not supported.
 *
 *  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 */