GPTimerCC26XX.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       GPTimerCC26XX.h
 *  @brief      GPTimer driver implementation for CC26XX/CC13XX
 *
 *     # Overview #
 *  This TI RTOS driver can be used to configure GPTimer modules to the modes
 *  supported by the GPTimer. The board file or application must define the device
 *  specific configuration before using the driver.
 *     # Configuration #
 *  The GPTimer can be used in two different configurations. In 32-bit mode the
 *  timer will act as a full-width timer and is controlled using the Timer A unit.
 *  In split (16-bit) mode the timer is split into 2x 16-bit timers. In 16-bit mode
 *  a prescaler is available for each timer unit, effectively increasing the
 *  resolution in this mode to 24-bit. All supported modes by driver in split
 *  configuration uses prescaler as timer extension.
 *
 *  # Modes #
 *  The GPTimer driver supports the following timer modes:
 *    - Oneshot mode counting upwards. When timer reaches load value, the timer
 *      is stopped automatically. Supported in both 16 and 32-bit configuration.
 *    - Periodic mode counting upwards. When timer reaches load value it wraps and
 *      starts counting from 0 again. Supported in both 16 and 32-bit configuration.
 *    - Input edge-count. Timer counts the number of events on its input capture port
 *      upwards from 0. Events can be rising-edge, falling-edge, or both.
 *      Supported only in 16-bit mode.
 *    - Input edge-time. Timer counts upwards from 0 and captures the time of an
 *      event on its input capture port. This can be used to count the time
 *      between events. Events can be rising-edge, falling-edge or both.
 *      Supported only in 16-bit mode.
 *    - PWM mode. Timer counts downwards from load value. CCP is set to 1 when
 *      reaching timeout (0) and toggles when reaching match value.
 *
 * # Power Management #
 * The TI-RTOS 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 GPTimerCC26XX 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 GPTimerCC26XX_open():
 *        The device is still allowed to enter Standby. When the device is
 *        active the corresponding GPTimer peripheral will be enabled and clocked.
 *    - After GPTimerCC26XX_start():
 *        The device will only go to Idle power mode since the high-frequency
 *        clock is needed for timer operation.
 *    - After GPTimerCC26XX_stop():
 *        Conditions are equal as for after GPTimerCC26XX_open
 *    - After GPTimerCC26XX_close():
 *        The underlying GPTimer is turned off and the device is allowed to go
 *        to standby.
 *
 *  # Accuracy #
 *  The GPTimer clock is dependent on the MCU system clock.
 *  If very high-accuracy outputs are needed, the application should request
 *  using the external HF crystal:
 *  @code
 *  #include <ti/sysbios/family/arm/cc26xx/Power.h>
 *  #include <ti/sysbios/family/arm/cc26xx/PowerCC2650.h>
 *  Power_setDependency(XOSC_HF);
 *  @endcode
 *
 *  # Limitations #
 *  - DMA usage is not supported
 *  - Timer synchronization is not supported
 *  - Down counting modes (except for PWM) are not supported by driver
 *
 *  # GPTimerCC26XX usage #
 *
 *  ## Periodic timer ##
 *  The example below will generate an interrupt using the GPTimer every 1 ms.
 *
 *  @code
 *  GPTimerCC26XX_Handle hTimer;
 *  void timerCallback(GPTimerCC26XX_Handle handle, GPTimerCC26XX_IntMask interruptMask) {
 *      // interrupt callback code goes here. Minimize processing in interrupt.
 *  }
 *
 *  void taskFxn(uintptr_t a0, uintptr_t a1) {
 *    GPTimerCC26XX_Params params;
 *    GPTimerCC26XX_Params_init(&params);
 *    params.width          = GPT_CONFIG_16BIT;
 *    params.mode           = GPT_MODE_PERIODIC;
 *    params.direction      = GPTimerCC26XX_DIRECTION_UP;
 *    params.debugStallMode = GPTimerCC26XX_DEBUG_STALL_OFF;
 *    hTimer = GPTimerCC26XX_open(CC2650_GPTIMER0A, &params);
 *    if(hTimer == NULL) {
 *      Log_error0("Failed to open GPTimer");
 *      Task_exit();
 *    }
 *
 *    Types_FreqHz  freq;
 *    BIOS_getCpuFreq(&freq);
 *    GPTimerCC26XX_Value loadVal = freq.lo / 1000 - 1; //47999
 *    GPTimerCC26XX_setLoadValue(hTimer, loadVal);
 *    GPTimerCC26XX_registerInterrupt(hTimer, timerCallback, GPT_INT_TIMEOUT);
 *
 *    GPTimerCC26XX_start(hTimer);
 *
 *    while(1) {
 *      Task_sleep(BIOS_WAIT_FOREVER);
 *    }
 *  }
 *  @endcode
 *
 *
 *  ## PWM output ##
 *  See the PWM2TimerCC26XX driver
 *******************************************************************************
 */

#ifndef ti_drivers_timer_GPTIMERCC26XX__include
#define ti_drivers_timer_GPTIMERCC26XX__include

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

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

#include <ti/devices/DeviceFamily.h>
#include DeviceFamily_constructPath(inc/hw_gpt.h)
#include DeviceFamily_constructPath(driverlib/event.h)
#include DeviceFamily_constructPath(driverlib/ioc.h)
#include DeviceFamily_constructPath(driverlib/timer.h)

#ifdef __cplusplus
extern "C" {
#endif

/* Backwards compatibility - old timer modes. New behaviour is count-up by default but configurable. */
#define GPT_MODE_ONESHOT_UP    GPT_MODE_ONESHOT
#define GPT_MODE_PERIODIC_UP   GPT_MODE_PERIODIC
#define GPT_MODE_EDGE_COUNT_UP GPT_MODE_EDGE_COUNT
#define GPT_MODE_EDGE_TIME_UP  GPT_MODE_EDGE_TIME

typedef enum GPTimerCC26XX_Width
{
    GPT_CONFIG_32BIT = GPT_CFG_CFG_32BIT_TIMER,
    GPT_CONFIG_16BIT = GPT_CFG_CFG_16BIT_TIMER,
} GPTimerCC26XX_Width;

typedef enum GPTimerCC26XX_Mode
{
    /* One shot mode counting upwards */
    GPT_MODE_ONESHOT    = GPT_TAMR_TAMR_ONE_SHOT | GPT_TAMR_TAMIE,
    /* Periodic mode counting upwards */
    GPT_MODE_PERIODIC   = GPT_TAMR_TAMR_PERIODIC | GPT_TAMR_TAMIE,
    /* Edge count mode counting upwards */
    GPT_MODE_EDGE_COUNT = GPT_TAMR_TAMR_CAPTURE | GPT_TAMR_TACM_EDGCNT,
    /* Edge count mode counting upwards */
    GPT_MODE_EDGE_TIME  = GPT_TAMR_TAMR_CAPTURE | GPT_TAMR_TACM_EDGTIME,
    /* PWM mode counting downwards. This specific configuration is used by the
       PWM2TimerCC26XX driver */
    GPT_MODE_PWM        = GPT_TAMR_TAMR_PERIODIC | GPT_TAMR_TAPWMIE_EN | GPT_TAMR_TAAMS_PWM | GPT_TAMR_TACM_EDGCNT |
                   GPT_TAMR_TAPLO_CCP_ON_TO,
} GPTimerCC26XX_Mode;

typedef enum GPTimerCC26XX_Interrupt
{
    GPT_INT_TIMEOUT       = 1 << 0,
    GPT_INT_CAPTURE_MATCH = 1 << 1,
    GPT_INT_CAPTURE       = 1 << 2,
    GPT_INT_MATCH         = 1 << 3,
} GPTimerCC26XX_Interrupt;

/* Number of entries in GPTimerCC26XX_Interrupt */
#define GPT_NUM_INTS 4

typedef enum GPTimerCC26XX_Part
{
    GPT_A = 0,
    GPT_B,
} GPTimerCC26XX_Part;

#define GPT_PARTS_COUNT 2

typedef enum GPTimerCC26XX_PinMux
{
    GPT_PIN_0A = IOC_PORT_MCU_PORT_EVENT0,
    GPT_PIN_0B = IOC_PORT_MCU_PORT_EVENT1,
    GPT_PIN_1A = IOC_PORT_MCU_PORT_EVENT2,
    GPT_PIN_1B = IOC_PORT_MCU_PORT_EVENT3,
    GPT_PIN_2A = IOC_PORT_MCU_PORT_EVENT4,
    GPT_PIN_2B = IOC_PORT_MCU_PORT_EVENT5,
    GPT_PIN_3A = IOC_PORT_MCU_PORT_EVENT6,
    GPT_PIN_3B = IOC_PORT_MCU_PORT_EVENT7,
} GPTimerCC26XX_PinMux;

typedef enum GPTimerCC26XX_DebugMode
{
    GPTimerCC26XX_DEBUG_STALL_OFF = 0,
    GPTimerCC26XX_DEBUG_STALL_ON,
} GPTimerCC26XX_DebugMode;

typedef enum GPTimerCC26XX_Direction
{
    GPTimerCC26XX_DIRECTION_DOWN = 0,
    GPTimerCC26XX_DIRECTION_UP,
} GPTimerCC26XX_Direction;

typedef enum GPTimerCC26XX_SetMatchTiming
{
    GPTimerCC26XX_SET_MATCH_NEXT_CLOCK = 0,
    GPTimerCC26XX_SET_MATCH_ON_TIMEOUT,
} GPTimerCC26XX_SetMatchTiming;

typedef enum GPTimerCC26XX_Edge
{
    GPTimerCC26XX_POS_EDGE   = GPT_CTL_TAEVENT_POS,
    GPTimerCC26XX_NEG_EDGE   = GPT_CTL_TAEVENT_NEG,
    GPTimerCC26XX_BOTH_EDGES = GPT_CTL_TAEVENT_BOTH,
} GPTimerCC26XX_Edge;

/* Forward declaration of GPTimer configuration */
typedef struct GPTimerCC26XX_Config GPTimerCC26XX_Config;

/* GPTimer handle is pointer to configuration structure */
typedef GPTimerCC26XX_Config *GPTimerCC26XX_Handle;

/* Interrupt bit vector. See GPTimerCC26XX_Interrupt for available interrupts */
typedef uint16_t GPTimerCC26XX_IntMask;

/* Timer value */
typedef uint32_t GPTimerCC26XX_Value;

/* Function prototype for interrupt callbacks */
typedef void (*GPTimerCC26XX_HwiFxn)(GPTimerCC26XX_Handle handle, GPTimerCC26XX_IntMask interruptMask);

typedef struct GPTimerCC26XX_HWAttrs
{
    uint32_t baseAddr;
    uint8_t intNum;
    uint8_t intPriority;
    uint8_t powerMngrId;
    GPTimerCC26XX_Part timer;
    GPTimerCC26XX_PinMux pinMux;
} GPTimerCC26XX_HWAttrs;

typedef struct GPTimerCC26XX_Object
{
    GPTimerCC26XX_Width width;                            
    bool isOpen[GPT_PARTS_COUNT];                         
    HwiP_Struct hwi[GPT_PARTS_COUNT];                     
    GPTimerCC26XX_HwiFxn hwiCallbackFxn[GPT_PARTS_COUNT]; 
    volatile bool powerConstraint[GPT_PARTS_COUNT];       
    uint32_t arg;                                         
} GPTimerCC26XX_Object;

struct GPTimerCC26XX_Config
{
    GPTimerCC26XX_Object *object;
    const GPTimerCC26XX_HWAttrs *hwAttrs;
    GPTimerCC26XX_Part timerPart;
};

typedef struct GPTimerCC26XX_Params
{
    GPTimerCC26XX_Width width;                
    GPTimerCC26XX_Mode mode;                  
    GPTimerCC26XX_SetMatchTiming matchTiming; 
    GPTimerCC26XX_Direction direction;        
    GPTimerCC26XX_DebugMode debugStallMode;   
} GPTimerCC26XX_Params;

extern void GPTimerCC26XX_Params_init(GPTimerCC26XX_Params *params);

extern GPTimerCC26XX_Handle GPTimerCC26XX_open(unsigned int index, const GPTimerCC26XX_Params *params);

extern void GPTimerCC26XX_close(GPTimerCC26XX_Handle handle);

extern void GPTimerCC26XX_start(GPTimerCC26XX_Handle handle);

extern void GPTimerCC26XX_stop(GPTimerCC26XX_Handle handle);

extern void GPTimerCC26XX_setLoadValue(GPTimerCC26XX_Handle handle, GPTimerCC26XX_Value loadValue);

extern void GPTimerCC26XX_setMatchValue(GPTimerCC26XX_Handle handle, GPTimerCC26XX_Value matchValue);

extern void GPTimerCC26XX_setCaptureEdge(GPTimerCC26XX_Handle handle, GPTimerCC26XX_Edge edge);

extern GPTimerCC26XX_Value GPTimerCC26XX_getFreeRunValue(GPTimerCC26XX_Handle handle);

extern GPTimerCC26XX_Value GPTimerCC26XX_getValue(GPTimerCC26XX_Handle handle);

extern void GPTimerCC26XX_registerInterrupt(GPTimerCC26XX_Handle handle,
                                            GPTimerCC26XX_HwiFxn callback,
                                            GPTimerCC26XX_IntMask intMask);

extern void GPTimerCC26XX_unregisterInterrupt(GPTimerCC26XX_Handle handle);

extern void GPTimerCC26XX_enableInterrupt(GPTimerCC26XX_Handle handle, GPTimerCC26XX_IntMask interruptMask);
extern void GPTimerCC26XX_disableInterrupt(GPTimerCC26XX_Handle handle, GPTimerCC26XX_IntMask interruptMask);

extern void GPTimerCC26XX_configureDebugStall(GPTimerCC26XX_Handle handle, GPTimerCC26XX_DebugMode mode);

extern uint32_t GPTimerCC26XX_getArg(GPTimerCC26XX_Handle handle);

extern void GPTimerCC26XX_setArg(GPTimerCC26XX_Handle handle, void *arg);

static inline GPTimerCC26XX_PinMux GPTimerCC26XX_getPinMux(GPTimerCC26XX_Handle handle)
{
    return handle->hwAttrs->pinMux;
}

#ifdef __cplusplus
}
#endif
#endif /* ti_drivers_timer_GPTIMERCC26XX__include */