PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Typedefs | Enumerations | Functions
Timer (Timer/Counter)
HAL API Reference » HAL Drivers

## General Description

High level interface for interacting with the Timer/Counter hardware resource.

The timer block is commonly used to measure the time of occurrence of an event, to measure the time difference between two events or perform an action after a specified period of time. The driver also allows the user to invoke a callback function when a particular event occurs.

Some use case scenarios of timer -

- Creating a periodic interrupt for executing periodic tasks
- Measuring time between two events
- Triggering other system resources after a certain number of events
- Capturing time stamps when events occur

# Features

- Runtime configurable parameters like period and compare value
- Configurable counting direction
- Interrupt on various events
- Continuous or One Shot run modes

# Quick Start

See Snippet 1: Measuring time of an operation.

# Code Snippets

## Snippet 1: Measuring time of an operation

The following snippet initializes a Timer and measures the time between two events. The clock will be defined in design.modus, and can be over-ridden with the mtb_hal_timer_setup() call.

cy_rslt_t rslt;
uint32_t read_val;
/* Use the device-configurator output for the alias "timer" */
rslt = Cy_TCPWM_Counter_Init(timer_HW, timer_NUM, &timer_config);
if (rslt == CY_RSLT_SUCCESS)
{
rslt = mtb_hal_timer_setup(&my_timer, &timer_hal_config, NULL);
if (rslt == CY_RSLT_SUCCESS)
{
rslt = mtb_hal_timer_enable(&my_timer, true);
}
}
if (rslt == CY_RSLT_SUCCESS)
{
// Start the timer with the configured settings
rslt = mtb_hal_timer_start(&my_timer);
}
// Delay Function simulates the time between two events
mtb_hal_system_delay_ms(500);
// Read the current timer value, which should be close to the amount of delay in ms * 10 (5000)
read_val = mtb_hal_timer_read(&my_timer);
mtb_hal_system_delay_ms
cy_rslt_t mtb_hal_system_delay_ms(uint32_t milliseconds)
Requests that the current operation delays for at least the specified length of time.
Definition: mtb_hal_system.c:63
mtb_hal_timer_read
uint32_t mtb_hal_timer_read(const mtb_hal_timer_t *obj)
Reads the current value from the timer/counter See Snippet 1: Measuring time of an operation.
Definition: mtb_hal_timer.c:152
mtb_hal_timer_setup
cy_rslt_t mtb_hal_timer_setup(mtb_hal_timer_t *obj, const mtb_hal_timer_configurator_t *config, mtb_hal_clock_t *clock)
Sets up a HAL instance to use the specified hardware resource.
Definition: mtb_hal_timer.c:51
mtb_hal_timer_start
cy_rslt_t mtb_hal_timer_start(mtb_hal_timer_t *obj)
Starts the timer/counter with the pre-set configuration.
Definition: mtb_hal_timer.c:89
mtb_hal_timer_enable
cy_rslt_t mtb_hal_timer_enable(mtb_hal_timer_t *obj, bool enable)
Enable/disable the Timer.
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486
Cy_TCPWM_Counter_Init
cy_en_tcpwm_status_t Cy_TCPWM_Counter_Init(TCPWM_Type *base, uint32_t cntNum, cy_stc_tcpwm_counter_config_t const *config)
Initializes the counter in the TCPWM block for the Counter operation.
Definition: cy_tcpwm_counter.c:58

## Snippet 2: Handling an event in a callback function

The following snippet initializes a Timer and triggers an event after every one second. The clock will be defined in design.modus, and can be over-ridden with the mtb_hal_timer_setup() call.

/*
* Timer event handler - called from mtb_hal_timer_process_interrupt()
*/
void my_timer_irq_handler(void* arg, mtb_hal_timer_event_t event)
{
(void)arg;
(void)event;
}
cy_rslt_t snippet_mtb_hal_timer_event_interrupt(void)
{
cy_rslt_t rslt;
/* Use the device-configurator output for the alias "timer" */
rslt = Cy_TCPWM_Counter_Init(timer_HW, timer_NUM, &timer_config);
if (rslt == CY_RSLT_SUCCESS)
{
rslt = mtb_hal_timer_setup(&my_timer, &timer_hal_config, NULL);
if (rslt == CY_RSLT_SUCCESS)
{
rslt = mtb_hal_timer_enable(&my_timer, true);
}
}
// Enable System IRQ
if (rslt == CY_RSLT_SUCCESS)
{
uint32_t savedIntrStatus = mtb_hal_system_critical_section_enter();
// Enable IRQ
cy_stc_sysint_t intr_cfg;
#if defined (CY_IP_M7CPUSS)
intr_cfg.intrSrc = _mtb_hal_get_intSrc(timer_IRQ);
#else
intr_cfg.intrSrc = (IRQn_Type)_mtb_hal_get_intSrc(timer_IRQ);
#endif
intr_cfg.intrPriority = 7u;
// Register system callback
Cy_SysInt_Init(&intr_cfg, my_test_sys_irq_handler);
NVIC_EnableIRQ((IRQn_Type)_mtb_hal_get_intVec(timer_IRQ));
mtb_hal_system_critical_section_exit(savedIntrStatus);
}
// Register the Callback and enable the events
if (CY_RSLT_SUCCESS == rslt)
{
/* set up pointer to our timer before enabling interrupts */
my_timer_ptr = &my_timer;
// Assign the ISR to execute on timer interrupt
mtb_hal_timer_register_callback(&my_timer, my_timer_irq_handler, NULL);
// Set the event on which timer interrupt occurs and enable it
mtb_hal_timer_enable_event(&my_timer, MTB_HAL_TIMER_EVENT_TERMINAL_COUNT, true);
}
// Start the timer
if (rslt == CY_RSLT_SUCCESS)
{
rslt = mtb_hal_timer_start(&my_timer);
}
// Delay to allow interrupt to happen
mtb_hal_system_delay_ms(1000);
return rslt;
}
mtb_hal_system_critical_section_exit
void mtb_hal_system_critical_section_exit(uint32_t old_state)
Exit a critical section.
mtb_hal_system_critical_section_enter
uint32_t mtb_hal_system_critical_section_enter(void)
Enter a critical section.
mtb_hal_timer_event_t
mtb_hal_timer_event_t
HAL Timer events.
Definition: mtb_hal_timer.h:113
mtb_hal_timer_enable_event
void mtb_hal_timer_enable_event(mtb_hal_timer_t *obj, mtb_hal_timer_event_t event, bool enable)
Configure timer/counter event enablement
Definition: mtb_hal_timer.c:186
mtb_hal_timer_register_callback
void mtb_hal_timer_register_callback(mtb_hal_timer_t *obj, mtb_hal_timer_event_callback_t callback, void *callback_arg)
Register a timer/counter callback handler
Definition: mtb_hal_timer.c:169
MTB_HAL_TIMER_EVENT_TERMINAL_COUNT
@ MTB_HAL_TIMER_EVENT_TERMINAL_COUNT
Timer Event Terminal Count = (timer reached max count),.
Definition: mtb_hal_timer.h:117
cy_stc_sysint_t::intrSrc
IRQn_Type intrSrc
Interrupt source.
Definition: cy_sysint.h:229
cy_stc_sysint_t::intrPriority
uint32_t intrPriority
Interrupt priority number (Refer to __NVIC_PRIO_BITS)
Definition: cy_sysint.h:231
cy_stc_sysint_t
Initialization configuration structure for a single interrupt channel.
Definition: cy_sysint.h:227
Cy_SysInt_Init
cy_en_sysint_status_t Cy_SysInt_Init(const cy_stc_sysint_t *config, cy_israddress userIsr)
Initializes the referenced interrupt by setting the priority and the interrupt vector.
Definition: cy_sysint_v2.c:80

## API Reference
| Timer HAL Results
| Timer specific return codes.

## Typedefs
typedef void(* | mtb_hal_timer_event_callback_t) (void *callback_arg, mtb_hal_timer_event_t event)
| Handler for timer events, callback_arg is a pointer to the timer obj.

## Enumerations
enum | mtb_hal_timer_event_t { MTB_HAL_TIMER_EVENT_NONE = (MTB_HAL_MAP_TIMER_EVENT_NONE) , MTB_HAL_TIMER_EVENT_TERMINAL_COUNT = (MTB_HAL_MAP_TIMER_EVENT_TERMINAL_COUNT) , MTB_HAL_TIMER_EVENT_COMPARE_CC0 = (MTB_HAL_MAP_TIMER_EVENT_COMPARE_CC0) , MTB_HAL_TIMER_EVENT_COMPARE_CC0_OR_TERMINAL_COUNT = (MTB_HAL_MAP_TIMER_EVENT_COMPARE_CC0_OR_TERMINAL_COUNT) , MTB_HAL_TIMER_EVENT_COMPARE_CC1 = (MTB_HAL_MAP_TIMER_EVENT_COMPARE_CC1) , MTB_HAL_TIMER_EVENT_ALL = (MTB_HAL_MAP_TIMER_EVENT_ALL) }
| HAL Timer events. More...

## Functions
cy_rslt_t | mtb_hal_timer_setup (mtb_hal_timer_t *obj, const mtb_hal_timer_configurator_t *config, mtb_hal_clock_t *clock)
| Sets up a HAL instance to use the specified hardware resource. More...
cy_rslt_t | mtb_hal_timer_enable (mtb_hal_timer_t *obj, bool enable)
| Enable/disable the Timer. More...
cy_rslt_t | mtb_hal_timer_start (mtb_hal_timer_t *obj)
| Starts the timer/counter with the pre-set configuration. More...
cy_rslt_t | mtb_hal_timer_stop (mtb_hal_timer_t *obj)
| Stops the timer/counter. More...
cy_rslt_t | mtb_hal_timer_reset (mtb_hal_timer_t *obj, uint32_t start_value)
| Reset the timer/counter value. More...
uint32_t | mtb_hal_timer_read (const mtb_hal_timer_t *obj)
| Reads the current value from the timer/counter See Snippet 1: Measuring time of an operation. More...
void | mtb_hal_timer_register_callback (mtb_hal_timer_t *obj, mtb_hal_timer_event_callback_t callback, void *callback_arg)
| Register a timer/counter callback handler More...
void | mtb_hal_timer_enable_event (mtb_hal_timer_t *obj, mtb_hal_timer_event_t event, bool enable)
| Configure timer/counter event enablement More...
cy_rslt_t | mtb_hal_timer_process_interrupt (mtb_hal_timer_t *obj)
| Process interrupts related related to a Timer instance. More...

## Enumeration Type Documentation

## ◆ mtb_hal_timer_event_t

enum mtb_hal_timer_event_t

HAL Timer events.

Enumerator
MTB_HAL_TIMER_EVENT_NONE | No event.
MTB_HAL_TIMER_EVENT_TERMINAL_COUNT | Timer Event Terminal Count = (timer reached max count),.
MTB_HAL_TIMER_EVENT_COMPARE_CC0 | Timer Event Compare Count 0 = (timer reached compare 0 count),.
MTB_HAL_TIMER_EVENT_COMPARE_CC0_OR_TERMINAL_COUNT | Timer Event Compare Count 0 -or- Terminal Count.
MTB_HAL_TIMER_EVENT_COMPARE_CC1 | Timer Event Compare Count 1 = (timer reached compare 1 count),.
MTB_HAL_TIMER_EVENT_ALL | All Timer Events Combined.

## Function Documentation

## ◆ mtb_hal_timer_setup()

cy_rslt_t mtb_hal_timer_setup | ( | mtb_hal_timer_t * | obj,
|  | const mtb_hal_timer_configurator_t * | config,
|  | mtb_hal_clock_t * | clock
| ) |  |

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

  [out] | obj | The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
  [in] | config | The configurator-generated HAL config structure for this peripheral instance
  [in] | clock | The HAL clock object that is connected to this peripheral instance

Returns
  the status of the HAL setup

## ◆ mtb_hal_timer_enable()

cy_rslt_t mtb_hal_timer_enable | ( | mtb_hal_timer_t * | obj,
|  | bool | enable
| ) |  |

Enable/disable the Timer.

The function returns without waiting for the enable to complete.

Parameters

  [in] | obj | The Timer object
  [in] | enable | Enable/disable

Returns
  The status of the enable request

## ◆ mtb_hal_timer_start()

cy_rslt_t mtb_hal_timer_start | ( | mtb_hal_timer_t * | obj | ) |

Starts the timer/counter with the pre-set configuration.

This does not reset the counter. The count value will start from the value that was set by the last operation to modify it. See Snippet 1: Measuring time of an operation.

Parameters

  [in] | obj | The timer/counter object

Returns
  The status of the start request

## ◆ mtb_hal_timer_stop()

cy_rslt_t mtb_hal_timer_stop | ( | mtb_hal_timer_t * | obj | ) |

Stops the timer/counter.

Does not reset counter value.

Parameters

  [in] | obj | The timer/counter object

Returns
  The status of the stop request

## ◆ mtb_hal_timer_reset()

cy_rslt_t mtb_hal_timer_reset | ( | mtb_hal_timer_t * | obj,
|  | uint32_t | start_value
| ) |  |

Reset the timer/counter value.

Parameters

  [in] | obj | The timer/counter object
  [in] | start_value | Start value for the timer.

Returns
  The status of the reset request

## ◆ mtb_hal_timer_read()

uint32_t mtb_hal_timer_read | ( | const mtb_hal_timer_t * | obj | ) |

Reads the current value from the timer/counter
See Snippet 1: Measuring time of an operation.

Parameters

  [in] | obj | The timer/counter object

Returns
  The current value of the timer/counter

## ◆ mtb_hal_timer_register_callback()

void mtb_hal_timer_register_callback | ( | mtb_hal_timer_t * | obj,
|  | mtb_hal_timer_event_callback_t | callback,
|  | void * | callback_arg
| ) |  |

Register a timer/counter callback handler

This function will be called when one of the events enabled by mtb_hal_timer_enable_event occurs.

See Snippet 2: Handling an event in a callback function.

Parameters

  [in] | obj | The timer/counter object
  [in] | callback | The callback handler which will be invoked when the event occurs
  [in] | callback_arg | Generic argument that will be provided to the callback when called

## ◆ mtb_hal_timer_enable_event()

void mtb_hal_timer_enable_event | ( | mtb_hal_timer_t * | obj,
|  | mtb_hal_timer_event_t | event,
|  | bool | enable
| ) |  |

Configure timer/counter event enablement

When an enabled event occurs, the function specified by mtb_hal_timer_register_callback will be called.

See Snippet 2: Handling an event in a callback function.

Parameters

  [in] | obj | The timer/counter object
  [in] | event | The timer/counter event mtb_hal_timer_event_t
  [in] | enable | True to turn on interrupts, False to turn off

## ◆ mtb_hal_timer_process_interrupt()

cy_rslt_t mtb_hal_timer_process_interrupt | ( | mtb_hal_timer_t * | obj | ) |

Process interrupts related related to a Timer instance.

Parameters

  obj | HAL object for which the interrupt should be processed

Returns
  CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error