Detailed Description

LGPTimer driver implementation for Low Power F3 devices.

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.

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

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 (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 (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.

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

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.

Accuracy

The timer clock of the LGPT peripheral is dependent on the high frequency clock (CLKSVT).

Usage

This documentation provides a basic example in the form of a commented code fragment.

Periodic timer example

The code example below will generate an interrupt using the LGPTimer every 1 ms.

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);
  }
}

Configuration

Refer to the Driver's Configuration section for driver configuration information.

#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)>

Include dependency graph for LGPTimerLPF3.h:

Go to the source code of this file.

Data Structures
struct	LGPTimerLPF3_Params
	LGPTimerLPF3 Parameters. More...

struct	LGPTimerLPF3_HWAttrs
	LGPTimerLPF3 Hardware attributes. More...

struct	LGPTimerLPF3_Object
	LGPTimerLPF3 Object. More...

struct	LGPTimerLPF3_Config
	LGPTimer Global configuration. More...

Typedefs
typedef struct LGPTimerLPF3_Config	LGPTimerLPF3_Config

typedef LGPTimerLPF3_Config *	LGPTimerLPF3_Handle

typedef uint16_t	LGPTimerLPF3_IntMask

typedef void(*	LGPTimerLPF3_HwiFxn) (LGPTimerLPF3_Handle handle, LGPTimerLPF3_IntMask interruptMask)
	The definition of a callback function used by the LGPTimer driver. More...

typedef struct LGPTimerLPF3_Params	LGPTimerLPF3_Params
	LGPTimerLPF3 Parameters. More...

typedef struct LGPTimerLPF3_HWAttrs	LGPTimerLPF3_HWAttrs
	LGPTimerLPF3 Hardware attributes. More...

typedef struct LGPTimerLPF3_Object	LGPTimerLPF3_Object
	LGPTimerLPF3 Object. More...

Enumerations
enum	LGPTimerLPF3_Mode { 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 }
	Definitions for supported LGPTimer counting modes. More...

enum	LGPTimerLPF3_Interrupt { LGPTimerLPF3_INT_TGT = 1 << LGPT_RIS_TGT_S, LGPTimerLPF3_INT_ZERO = 1 << LGPT_RIS_ZERO_S }
	Definitions for supported LGPTimer interrupts. LGPTimerLPF3_IntMask arguments should be a bit vector containing these definitions. More...

enum	LGPTimerLPF3_DebugMode { 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) }
	Definitions for controlling timer debug stall mode. More...

Functions
void	LGPTimerLPF3_Params_init (LGPTimerLPF3_Params *params)
	Function that initializes the LGPTimerLPF3_Params struct to its default values. More...

LGPTimerLPF3_Handle	LGPTimerLPF3_open (uint_least8_t index, const LGPTimerLPF3_Params *params)
	Function that opens a driver for the given LGPT peripheral. Will set power dependency on timer and configure it into specified configuration. More...

void	LGPTimerLPF3_close (LGPTimerLPF3_Handle handle)
	Function that closes a LGPTimer driver specified by the LGPTimer handle. Closing LGPTimer driver will release power dependency on timer and clear configuration. More...

void	LGPTimerLPF3_start (LGPTimerLPF3_Handle handle, LGPTimerLPF3_Mode mode)
	Function that starts the timer counter of the specified LGPTimer handle with current settings and specified timer counter mode. More...

void	LGPTimerLPF3_stop (LGPTimerLPF3_Handle handle)
	Function that stops the timer counter of the specified LGPTimer driver. More...

void	LGPTimerLPF3_setInitialCounterTarget (LGPTimerLPF3_Handle handle, uint32_t value, bool intFlagClr)
	Function that sets the initial timer counter target on the specified LGPTimer. This function must be called before the timer is started. The LGPTimerLPF3_INT_TGT and LGPTimerLPF3_INT_ZERO interrupt status flags are cleared. Timer counter width (16 or 24 bits) depends on selected peripheral instance. More...

void	LGPTimerLPF3_setNextCounterTarget (LGPTimerLPF3_Handle handle, uint32_t value, bool intFlagClr)
	Function that sets the next timer counter target on the specified LGPTimer. The specified target value will be valid as timer counter target on the upcoming zero crossing. When counting repeatedly upwards a zero crossing is regarded as when the timer counter restarts counting from 0. The LGPTimerLPF3_INT_TGT and LGPTimerLPF3_INT_ZERO interrupt status flags are cleared at the counter zero crossing. This function can be called after the timer has started. Timer counter width (16 or 24 bits) depends on selected peripheral instance. More...

uint32_t	LGPTimerLPF3_getCounter (LGPTimerLPF3_Handle handle)
	Function that returns the current timer counter value. More...

uint32_t	LGPTimerLPF3_getArg (LGPTimerLPF3_Handle handle)
	Function to get a custom argument. More...

void	LGPTimerLPF3_setArg (LGPTimerLPF3_Handle handle, void *arg)
	Function to set a custom argument. More...

void	LGPTimerLPF3_enableInterrupt (LGPTimerLPF3_Handle handle, LGPTimerLPF3_IntMask intMask)
	Enable interrupt source for the LGPTimer handle. More...

void	LGPTimerLPF3_disableInterrupt (LGPTimerLPF3_Handle handle, LGPTimerLPF3_IntMask intMask)
	Disable interrupt source for the LGPTimer handle. More...

Typedef Documentation

§ LGPTimerLPF3_Config

typedef struct LGPTimerLPF3_Config LGPTimerLPF3_Config

§ LGPTimerLPF3_Handle

typedef LGPTimerLPF3_Config* LGPTimerLPF3_Handle

§ LGPTimerLPF3_IntMask

typedef uint16_t LGPTimerLPF3_IntMask

§ LGPTimerLPF3_HwiFxn

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

The definition of a callback function used by the LGPTimer driver.

Parameters

[in]	handle	A LGPTimer handle
[in]	interruptMask	LGPTimer interrupt mask

§ LGPTimerLPF3_Params

typedef struct LGPTimerLPF3_Params LGPTimerLPF3_Params

LGPTimerLPF3 Parameters.

LGPTimer parameters are used by the LGPTimerLPF3_open() call. Default values for these parameters are set using LGPTimerLPF3_Params_init().

See also: LGPTimerLPF3_Params_init()

§ LGPTimerLPF3_HWAttrs

typedef struct LGPTimerLPF3_HWAttrs LGPTimerLPF3_HWAttrs

LGPTimerLPF3 Hardware attributes.

These fields are used by the driver to set up underlying LGPTimer driver statically. A sample structure is shown below:

// LGPTimer hardware attributes, one per supported LGPT peripheral
const LGPTimerLPF3_HWAttrs LGPTimerLPF3HWAttrs[] = {
    {
         .baseAddr     = LGPT0_BASE,
         .intNum       = INT_LGPT0_COMB,
         .intPriority  = INT_PRI_LEVEL1,
         .powerMngrId  = PowerLPF3_PERIPH_LGPT0,
    },
};

§ LGPTimerLPF3_Object

typedef struct LGPTimerLPF3_Object LGPTimerLPF3_Object

LGPTimerLPF3 Object.

These fields are used by the driver to store and modify LGPTimer configuration during run-time. The application must not edit any member variables of this structure. Appplications should also not access member variables of this structure as backwards compatibility is not guaranteed. An example structure is shown below:

// LGPTimer objects, one per LGPT peripheral (LGPT0, LGPT1..)

LGPTimerLPF3_Object LGPTimerLPF3Objects[];

Enumeration Type Documentation

§ LGPTimerLPF3_Mode

enum LGPTimerLPF3_Mode

Definitions for supported LGPTimer counting modes.

Enumerator
LGPTimerLPF3_CTL_MODE_DIS	Disable timer. Updates to counter and events are stopped.
LGPTimerLPF3_CTL_MODE_UP_ONCE	Count up one-shot. The timer increments from 0 to target value, then stops and sets MODE to LGPTimerLPF3_CTL_MODE_DIS.
LGPTimerLPF3_CTL_MODE_UP_PER	Count up periodically. The timer increments from 0 to target value, repeatedly.
LGPTimerLPF3_CTL_MODE_UPDWN_PER	Count up and down periodically. The timer counts from 0 to target value and back to 0, repeatedly.

§ LGPTimerLPF3_Interrupt

enum LGPTimerLPF3_Interrupt

Definitions for supported LGPTimer interrupts. LGPTimerLPF3_IntMask arguments should be a bit vector containing these definitions.

Enumerator
LGPTimerLPF3_INT_TGT	Timer counter target interrupt
LGPTimerLPF3_INT_ZERO	Timer counter zero interrupt

§ LGPTimerLPF3_DebugMode

enum LGPTimerLPF3_DebugMode

Definitions for controlling timer debug stall mode.

Enumerator
LGPTimerLPF3_DEBUG_STALL_OFF	The LGPT is not halted when CPU is halted in debug
LGPTimerLPF3_DEBUG_STALL_IMMEDIATE	Halt LGPT immediatly when CPU is halted in debug
LGPTimerLPF3_DEBUG_STALL_ON_ZERO	Halt LGPT when counter equals 0 while CPU is halted in debug

Function Documentation

§ LGPTimerLPF3_Params_init()

void LGPTimerLPF3_Params_init ( LGPTimerLPF3_Params * params )

Function that initializes the LGPTimerLPF3_Params struct to its default values.

Parameters

[in] params An pointer to LGPTimerLPF3_Params structure for initialization

Default values are: Interrupt callback fxn: NULL, Interrupt phase late : false, Prescaler division : 0, Timer debug stall mode: LGPTimerLPF3_DEBUG_STALL_OFF

§ LGPTimerLPF3_open()

LGPTimerLPF3_Handle LGPTimerLPF3_open	(	uint_least8_t	index,
		const LGPTimerLPF3_Params *	params
	)

Function that opens a driver for the given LGPT peripheral. Will set power dependency on timer and configure it into specified configuration.

Parameters

[in]	index	Index in the LGPTimerLPF3_config table.
[in]	params	Pointer to a parameter block. If NULL, it will use default values.

Returns: A LGPTimerLPF3_Handle on success or NULL on an error or if it has been opened already. If NULL is returned, further LGPTimerLPF3 API calls will result in undefined behaviour.

See also: LGPTimerLPF3_close()

§ LGPTimerLPF3_close()

void LGPTimerLPF3_close ( LGPTimerLPF3_Handle handle )

Function that closes a LGPTimer driver specified by the LGPTimer handle. Closing LGPTimer driver will release power dependency on timer and clear configuration.

Precondition: LGPTimerLPF3_open() has to be called first.; LGPTimerLPF3_stop() should to be called first if LGPTimer is started.

Parameters

[in] handle A LGPTimerLPF3 handle returned from LGPTimerLPF3_open()

See also: LGPTimerLPF3_open(); LGPTimerLPF3_start(); LGPTimerLPF3_stop()

§ LGPTimerLPF3_start()

void LGPTimerLPF3_start	(	LGPTimerLPF3_Handle	handle,
		LGPTimerLPF3_Mode	mode
	)

Function that starts the timer counter of the specified LGPTimer handle with current settings and specified timer counter mode.

Note: The LGPT3 timer has timer counter width of 24-bits. The others have 16-bits.

Precondition: LGPTimerLPF3_open() has to be called first successfully.

Parameters

[in]	handle	A LGPTimerLPF3 handle returned from LGPTimerLPF3_open().
[in]	mode	The timer counter mode.

See also: LGPTimerLPF3_setPrescaler()

Postcondition: LGPTimerLPF3_stop()

§ LGPTimerLPF3_stop()

void LGPTimerLPF3_stop ( LGPTimerLPF3_Handle handle )

Function that stops the timer counter of the specified LGPTimer driver.

Precondition: LGPTimerLPF3_open() has to be called first successfully.

Parameters

[in] handle A LGPTimerLPF3 handle returned from LGPTimerLPF3_open()

See also: LGPTimerLPF3_open(); LGPTimerLPF3_start()

§ LGPTimerLPF3_setInitialCounterTarget()

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

Function that sets the initial timer counter target on the specified LGPTimer. This function must be called before the timer is started. The LGPTimerLPF3_INT_TGT and LGPTimerLPF3_INT_ZERO interrupt status flags are cleared. Timer counter width (16 or 24 bits) depends on selected peripheral instance.

Precondition: LGPTimerLPF3_open() has to be called first successfully

Parameters

[in]	handle	A LGPTimerLPF3 handle returned from LGPTimerLPF3_open
[in]	value	Initial target value of the timer counter. Max value: LGPT peripheral properties
[in]	intFlagClr	Controls if the LGPTimerLPF3_INT_TGT and LGPTimerLPF3_INT_ZERO interrupt status flags are cleared or not when this function is executed.

See also: LGPTimerLPF3_open(); LGPTimerLPF3_start()

§ LGPTimerLPF3_setNextCounterTarget()

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

Function that sets the next timer counter target on the specified LGPTimer. The specified target value will be valid as timer counter target on the upcoming zero crossing. When counting repeatedly upwards a zero crossing is regarded as when the timer counter restarts counting from 0. The LGPTimerLPF3_INT_TGT and LGPTimerLPF3_INT_ZERO interrupt status flags are cleared at the counter zero crossing. This function can be called after the timer has started. Timer counter width (16 or 24 bits) depends on selected peripheral instance.

Precondition: LGPTimerLPF3_open() has to be called first successfully

Parameters

[in]	handle	A LGPTimerLPF3 handle returned from LGPTimerLPF3_open
[in]	value	Next target value of the timer counter. Max value Max value: LGPT peripheral properties"
[in]	intFlagClr	Controls if the LGPTimerLPF3_INT_TGT and LGPTimerLPF3_INT_ZERO interrupt status flags are cleared or not when this function is executed.

See also: LGPTimerLPF3_open(); LGPTimerLPF3_start()

§ LGPTimerLPF3_getCounter()

uint32_t LGPTimerLPF3_getCounter ( LGPTimerLPF3_Handle handle )

Function that returns the current timer counter value.

Precondition: LGPTimerLPF3_open() has to be called first successfully

Parameters

[in] handle A LGPTimerLPF3 handle returned from LGPTimerLPF3_open

Returns: The current timer counter value

See also: LGPTimerLPF3_open

§ LGPTimerLPF3_getArg()

uint32_t LGPTimerLPF3_getArg ( LGPTimerLPF3_Handle handle )

Function to get a custom argument.

Precondition: LGPTimerLPF3_open() has to be called first successfully; LGPTimerLPF3_setArg() has to be called first

Parameters

[in] handle A LGPTimerLPF3 handle returned from LGPTimerLPF3_open

Returns: The custom argument

See also: LGPTimerLPF3_setArg; LGPTimerLPF3_open

§ LGPTimerLPF3_setArg()

void LGPTimerLPF3_setArg	(	LGPTimerLPF3_Handle	handle,
		void *	arg
	)

Function to set a custom argument.

Precondition: LGPTimerLPF3_open() has to be called first successfully

Parameters

[in]	handle	A LGPTimerLPF3 handle returned from LGPTimerLPF3_open
[in]	arg	Pointer to a custom argument

See also: LGPTimerLPF3_getArg; LGPTimerLPF3_open

§ LGPTimerLPF3_enableInterrupt()

void LGPTimerLPF3_enableInterrupt	(	LGPTimerLPF3_Handle	handle,
		LGPTimerLPF3_IntMask	intMask
	)

Enable interrupt source for the LGPTimer handle.

Precondition: LGPTimerLPF3_open() has to be called first successfully

Parameters

[in]	handle	A LGPTimerLPF3 handle returned from LGPTimerLPF3_open
[in]	intMask	A bit mask of interrupt flags to enable

§ LGPTimerLPF3_disableInterrupt()

void LGPTimerLPF3_disableInterrupt	(	LGPTimerLPF3_Handle	handle,
		LGPTimerLPF3_IntMask	intMask
	)

Disable interrupt source for the LGPTimer handle.

Precondition: LGPTimerLPF3_open() has to be called first successfully; LGPTimerLPF3_enableInterrupt() has to be called first

Parameters

[in]	handle	A LGPTimerLPF3 handle returned from LGPTimerLPF3_open
[in]	intMask	A bit mask of interrupt flags to disable

Detailed Description

Overview

LGPT peripheral properties

Counter Modes

Unsupported Features

Power Management

Accuracy

Usage

Periodic timer example

Configuration

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

§ LGPTimerLPF3_Config

§ LGPTimerLPF3_Handle

§ LGPTimerLPF3_IntMask

§ LGPTimerLPF3_HwiFxn

§ LGPTimerLPF3_Params

§ LGPTimerLPF3_HWAttrs

§ LGPTimerLPF3_Object

Enumeration Type Documentation

§ LGPTimerLPF3_Mode

§ LGPTimerLPF3_Interrupt

§ LGPTimerLPF3_DebugMode

Function Documentation

§ LGPTimerLPF3_Params_init()

§ LGPTimerLPF3_open()

§ LGPTimerLPF3_close()

§ LGPTimerLPF3_start()

§ LGPTimerLPF3_stop()

§ LGPTimerLPF3_setInitialCounterTarget()

§ LGPTimerLPF3_setNextCounterTarget()

§ LGPTimerLPF3_getCounter()

§ LGPTimerLPF3_getArg()

§ LGPTimerLPF3_setArg()

§ LGPTimerLPF3_enableInterrupt()

§ LGPTimerLPF3_disableInterrupt()