LGPTimerLPF3.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023, 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       LGPTimerLPF3.h
 *  @brief      LGPTimer driver implementation for Low Power F3 devices
 *
 *  @anchor ti_drivers_LGPTimer_Overview
 *  # Overview #
 *  The LGPTimer driver allows you to measure elapsed time with simple and
 *  portable APIs. It also allows for asynchronous callbacks after a
 *  certain amount of time has elapsed.
 *
 *  The LGPTimer driver also handles the general purpose timer resource allocation.
 *  For each driver that requires use of a general purpose timer, it calls
 *  LGPTimerLPF3_open() to occupy the specified timer, and calls
 *  LGPTimerLPF3_close() to release the occupied timer resource.
 *
 *  @anchor ti_drivers_LGPTimer_PeripheralProperties
 *  # LGPT peripheral properties #
 *  The LGPT peripherals support different timer counter widths depending
 *  on the peripheral instance number (LGPT0, LGPT1, ..). The table below
 *  lists supported counter widths for each peripheral instance number on
 *  available device types.
 *  The timer counter clock is sourced from the internal prescaler stage which
 *  has the high frequency clock (CLKSVT) as input.
 *  The prescaler can be configured to divide the input system clock, effectively
 *  extending the maximal time interval for the timer counter while reducing the
 *  timer resolution.
 *
 * | Device type   | LGPT0   | LGPT1   | LGPT2   | LGPT3   |
 * |---------------|---------|---------|---------|---------|
 * | CC2340R2      | 16 bits | 16 bits |   N.A   |   N.A   |
 * | CC2340R5      | 16 bits | 16 bits | 16 bits | 24 bits |
 * | CC27X5        | 16 bits | 16 bits | 16 bits | 24 bits |
 *
 *  @anchor ti_drivers_LGPTimer_CounterModes
 *  # Counter Modes #
 *  The LGPTimer driver supports the following timer counter modes:
 *    - Oneshot mode counting upwards. When the counter reaches the target value, the
 *      timer is stopped automatically and the TGT interrupt status flag
 *      (@ref LGPTimerLPF3_INT_TGT) is set.
 *    - Periodic mode counting upwards. When the counter reaches target value it wraps
 *      and restarts counting from 0 again. The TGT interrupt status flag is set each
 *      time the target value is reached. The ZERO interrupt status flag
 *      (@ref LGPTimerLPF3_INT_ZERO) is set each time the counter restarts from 0.
 *    - Periodic mode counting upwards/downwads. When the counter reaches target value
 *      while counting upwards the TGT interrupt flag is set and it starts counting
 *      downwards to 0. When 0 is reached the ZERO insterrupt status flag is set
 *      and the sequence is repeated.
 *
 *  @anchor ti_drivers_LGPTimer_UnsupportedFeatures
 *  # Unsupported Features #
 *  - Use of the three configurable capture/compare channels is not supported
 *  - PWM signal generation is not supported
 *  - DMA usage is not supported
 *  - ADC trigger is not supported
 *  - QDEC mode where the timer functions as a quadrature decoder is not supported
 *  - Timer synchronization is not supported
 *  - Prescaler counter clock sourced from events is not supported
 *
 *  @anchor ti_drivers_LGPTimer_PowerManagement
 *  # Power Management #
 *  The power management framework will try to put the device into the most
 *  power efficient mode whenever possible. Please see the technical reference
 *  manual for further details on each power mode.
 *
 *  The LGPTimer driver will set constraints on disallowed power modes when
 *  needed, removing the need for the application to handle this.
 *  The following statements are valid:
 *    - After LGPTimerLPF3_open():
 *        The device is still allowed to enter Standby. When the device is
 *        active, the corresponding LGPT peripheral will be enabled and clocked.
 *        Note that a configured counter target will not be retained when going
 *        in and out of Standby. The counter target is set by the functions
 *        LGPTimerLPF3_setInitialCounterTarget() and LGPTimerLPF3_setNextCounterTarget().
 *    - After LGPTimerLPF3_start():
 *        The device will only go to Idle power mode since the high frequency
 *        clock (CLKSVT) is needed for timer operation.
 *    - After LGPTimerLPF3_stop():
 *        The device is still allowed to enter Standby. When the device is
 *        active, the corresponding LGPT peripheral will be enabled and clocked.
 *    - After LGPTimerLPF3_close():
 *        The underlying LGPT peripheral is turned off. The device is allowed to
 *        enter Standby.
 *
 *  @anchor ti_drivers_LGPTimer_Accuracy
 *  # Accuracy #
 *  The timer clock of the LGPT peripheral is dependent on the high frequency clock (CLKSVT).
 *
 *  @anchor ti_drivers_LGPTimer_Usage
 *  # Usage #
 *
 *  This documentation provides a basic @ref ti_drivers_LGPTimer_Example "example"
 *  in the form of a commented code fragment.
 *
 *  @anchor ti_drivers_LGPTimer_Example
 *  ## Periodic timer example##
 *  The code example below will generate an interrupt using the LGPTimer every 1 ms.
 *
 *  @anchor ti_drivers_LGPTimer_Code
 *  @code
 *  LGPTimerLPF3_Handle hTimer;
 *  void timerCallback(LGPTimerLPF3_Handle lgptHandle, LGPTimerLPF3_IntMask interruptMask) {
 *      // interrupt callback code goes here. Minimize processing in interrupt.
 *  }
 *
 *  void taskFxn(uintptr_t a0, uintptr_t a1) {
 *    uint32_t counterTarget;
 *
 *    lgptHandle = NULL;
 *    LGPTimerLPF3_Params params;
 *    LGPTimerLPF3_Params_init(&params);
 *    params.hwiCallbackFxn = timerCallback;
 *    lgptHandle = LGPTimerLPF3_open(0, &params);
 *    if(lgptHandle == NULL) {
 *      Log_error0("Failed to open LGPTimer");
 *      Task_exit();
 *    }
 *
 *    counterTarget = 48000;  // 1 ms with a system clock of 48 MHz
 *    LGPTimerLPF3_setInitialCounterTarget(lgptHandle, counterTarget, true);
 *    LGPTimerLPF3_enableInterrupt(lgptHandle, LGPTimerLPF3_INT_TGT);
 *
 *    LGPTimerLPF3_start(lgptHandle, LGPTimerLPF3_CTL_MODE_UP_PER);
 *
 *    while(1) {
 *        vTaskSuspend(lgptHandle);
 *    }
 *  }
 *  @endcode
 *
 *
 *  <hr>
 *  @anchor ti_drivers_LGPT_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 *
 *  ============================================================================
 */

#ifndef ti_drivers_timer_LGPTimerLPF3__include
#define ti_drivers_timer_LGPTimerLPF3__include

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/Power.h>

#include <ti/devices/DeviceFamily.h>
#include DeviceFamily_constructPath(inc/hw_lgpt.h)

#ifdef __cplusplus
extern "C" {
#endif

typedef enum
{
    LGPTimerLPF3_CTL_MODE_DIS       = LGPT_CTL_MODE_DIS,
    LGPTimerLPF3_CTL_MODE_UP_ONCE   = LGPT_CTL_MODE_UP_ONCE,
    LGPTimerLPF3_CTL_MODE_UP_PER    = LGPT_CTL_MODE_UP_PER,
    LGPTimerLPF3_CTL_MODE_UPDWN_PER = LGPT_CTL_MODE_UPDWN_PER,
} LGPTimerLPF3_Mode;

typedef enum
{
    LGPTimerLPF3_INT_TGT  = 1 << LGPT_RIS_TGT_S,
    LGPTimerLPF3_INT_ZERO = 1 << LGPT_RIS_ZERO_S,
} LGPTimerLPF3_Interrupt;

typedef enum
{
    LGPTimerLPF3_DEBUG_STALL_OFF       = LGPT_EMU_HALT_DIS,
    LGPTimerLPF3_DEBUG_STALL_IMMEDIATE = (LGPT_EMU_HALT_EN | LGPT_EMU_CTL_IMMEDIATE),
    LGPTimerLPF3_DEBUG_STALL_ON_ZERO   = (LGPT_EMU_HALT_EN | LGPT_EMU_CTL_ZERCOND),
} LGPTimerLPF3_DebugMode;

/* Forward declaration of LGPTimer configuration */
typedef struct LGPTimerLPF3_Config LGPTimerLPF3_Config;

/* LGPTimer handle is pointer to configuration structure */
typedef LGPTimerLPF3_Config *LGPTimerLPF3_Handle;

/* Interrupt bit vector. See LGPTimerLPF3_Interrupt for available interrupts */
typedef uint16_t LGPTimerLPF3_IntMask;

typedef void (*LGPTimerLPF3_HwiFxn)(LGPTimerLPF3_Handle handle, LGPTimerLPF3_IntMask interruptMask);

typedef struct LGPTimerLPF3_Params
{
    LGPTimerLPF3_HwiFxn hwiCallbackFxn;
    bool intPhaseLate;
    uint8_t prescalerDiv;
    LGPTimerLPF3_DebugMode debugStallMode;
} LGPTimerLPF3_Params;

typedef struct LGPTimerLPF3_HWAttrs
{
    uint32_t baseAddr;
    uint8_t intNum;
    uint8_t intPriority;
    uint8_t powerID;
} LGPTimerLPF3_HWAttrs;

typedef struct LGPTimerLPF3_Object
{
    HwiP_Struct hwi;                       
    LGPTimerLPF3_HwiFxn hwiCallbackFxn;    
    Power_NotifyObj postNotify;            
    uint32_t arg;                          
    bool isOpen;                           
    bool intPhaseLate;                     
    uint8_t prescalerDiv;                  
    LGPTimerLPF3_DebugMode debugStallMode; 
} LGPTimerLPF3_Object;

struct LGPTimerLPF3_Config
{
    LGPTimerLPF3_Object *object;
    const LGPTimerLPF3_HWAttrs *hwAttrs;
};

extern void LGPTimerLPF3_Params_init(LGPTimerLPF3_Params *params);

extern LGPTimerLPF3_Handle LGPTimerLPF3_open(uint_least8_t index, const LGPTimerLPF3_Params *params);

extern void LGPTimerLPF3_close(LGPTimerLPF3_Handle handle);

extern void LGPTimerLPF3_start(LGPTimerLPF3_Handle handle, LGPTimerLPF3_Mode mode);

extern void LGPTimerLPF3_stop(LGPTimerLPF3_Handle handle);

extern void LGPTimerLPF3_setInitialCounterTarget(LGPTimerLPF3_Handle handle, uint32_t value, bool intFlagClr);

extern void LGPTimerLPF3_setNextCounterTarget(LGPTimerLPF3_Handle handle, uint32_t value, bool intFlagClr);

extern uint32_t LGPTimerLPF3_getCounter(LGPTimerLPF3_Handle handle);

extern uint32_t LGPTimerLPF3_getArg(LGPTimerLPF3_Handle handle);

extern void LGPTimerLPF3_setArg(LGPTimerLPF3_Handle handle, void *arg);

void LGPTimerLPF3_enableInterrupt(LGPTimerLPF3_Handle handle, LGPTimerLPF3_IntMask intMask);

void LGPTimerLPF3_disableInterrupt(LGPTimerLPF3_Handle handle, LGPTimerLPF3_IntMask intMask);

#ifdef __cplusplus
}
#endif
#endif /* ti_drivers_timer_LGPTimerLPF3__include */