0ef1717155
Some checks failed
Basic Checks / license-check (push) Has been cancelled
Basic Checks / include-check (push) Has been cancelled
Basic Checks / style-check (push) Has been cancelled
Basic Checks / docs-check (push) Has been cancelled
Basic Checks / python-tests (push) Has been cancelled
Basic Checks / pin-validation (push) Has been cancelled
Basic Checks / cmake-checks (push) Has been cancelled
Basic Checks / frozen-tools-check (push) Has been cancelled
Publish or Update docker image for head of branch / prepare-tags (push) Has been cancelled
Release or update docker image for a released mbed-os version / prepare-tags (push) Has been cancelled
Publish or Update docker image for head of branch / build-container (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/amd64) (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/arm64) (push) Has been cancelled
Publish or Update docker image for head of branch / deploy-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / build-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/amd64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/arm64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / deploy-container (push) Has been cancelled
Prune temporary docker images / prune-images (push) Has been cancelled
342 lines
14 KiB
C
342 lines
14 KiB
C
/***************************************************************************//**
|
|
* \file cyhal_timer.h
|
|
*
|
|
* \brief
|
|
* Provides a high level interface for interacting with the Cypress Timer/Counter.
|
|
* This interface abstracts out the chip specific details. If any chip specific
|
|
* functionality is necessary, or performance is critical the low level functions
|
|
* can be used directly.
|
|
*
|
|
********************************************************************************
|
|
* \copyright
|
|
* Copyright 2018-2021 Cypress Semiconductor Corporation
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*******************************************************************************/
|
|
|
|
/**
|
|
* \addtogroup group_hal_timer Timer (Timer/Counter)
|
|
* \ingroup group_hal
|
|
* \{
|
|
* 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
|
|
*
|
|
* \section subsection_timer_features Features
|
|
* * Runtime configurable parameters like period and compare value - \ref cyhal_timer_cfg_t
|
|
* * Configurable counting direction - \ref cyhal_timer_direction_t
|
|
* * Interrupt on various events - \ref cyhal_timer_event_t
|
|
* * Continuous or One Shot run modes
|
|
*
|
|
* \section subsection_timer_quickstart Quick Start
|
|
*
|
|
* \ref cyhal_timer_init can be used for timer initialization by providing the timer object - \ref cyhal_timer_t,
|
|
* and shared clock source - <b> clk </b> (optional). The timer parameters needs to be populated in \ref cyhal_timer_cfg_t structure.
|
|
* The timer then needs to be configured by using the \ref cyhal_timer_configure function.
|
|
*
|
|
* \note A default frequency is set when an existing clock divider - <b> clk </b> is not provided to \ref cyhal_timer_init which is
|
|
* defined by the macro - \ref CYHAL_TIMER_DEFAULT_FREQ.
|
|
*
|
|
* \warning Currently there is no support for pin connections to Timer using this driver. So, the <b> pin </b> should be
|
|
* assigned as \ref NC while using the \ref cyhal_timer_init to initialize the timer.
|
|
*
|
|
*
|
|
* See \ref subsection_timer_snippet_1.
|
|
*
|
|
* \section subsection_timer_sample_snippets Code Snippets
|
|
*
|
|
* \subsection subsection_timer_snippet_1 Snippet 1: Measuring time of an operation
|
|
* The following snippet initializes a Timer and measures the time between two events.
|
|
* The <b>clk</b> need not be provided, in which case a clock resource is assigned.
|
|
* \snippet hal_timer.c snippet_cyhal_timer_event_measure
|
|
*
|
|
* \subsection subsection_timer_snippet_2 Snippet 2: Handling an event in a callback function
|
|
* The following snippet initializes a Timer and triggers an event after every one second.
|
|
* The <b>clk</b> need not be provided (NULL), in which case a clock resource is assigned.
|
|
* \snippet hal_timer.c snippet_cyhal_timer_event_interrupt
|
|
*
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include "cy_result.h"
|
|
#include "cyhal_hw_types.h"
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \addtogroup group_hal_results_timer Timer HAL Results
|
|
* Timer specific return codes
|
|
* \ingroup group_hal_results
|
|
* \{ *//**
|
|
*/
|
|
|
|
/** Bad argument. eg: null pointer */
|
|
#define CYHAL_TIMER_RSLT_ERR_BAD_ARGUMENT \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_TIMER, 0))
|
|
/** Failed to initialize Timer clock */
|
|
#define CYHAL_TIMER_RSLT_ERR_CLOCK_INIT \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_TIMER, 1))
|
|
/** Failed to initialize Timer */
|
|
#define CYHAL_TIMER_RSLT_ERR_INIT \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_TIMER, 2))
|
|
/** Cannot change the timer frequency when a shared clock divider is in use */
|
|
#define CYHAL_TIMER_RSLT_ERR_SHARED_CLOCK \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_TIMER, 3))
|
|
|
|
/**
|
|
* \}
|
|
*/
|
|
|
|
/*******************************************************************************
|
|
* Enumerations
|
|
*******************************************************************************/
|
|
|
|
/** Timer directions */
|
|
typedef enum
|
|
{
|
|
CYHAL_TIMER_DIR_UP, //!< Counts up
|
|
CYHAL_TIMER_DIR_DOWN, //!< Counts down
|
|
CYHAL_TIMER_DIR_UP_DOWN, //!< Counts up and down, terminal count occurs on both overflow and underflow.
|
|
} cyhal_timer_direction_t;
|
|
|
|
/** Timer/counter interrupt triggers */
|
|
typedef enum {
|
|
CYHAL_TIMER_IRQ_NONE = 0, /**< No interrupt handled **/
|
|
CYHAL_TIMER_IRQ_TERMINAL_COUNT = 1 << 0, /**< Interrupt when terminal count is reached **/
|
|
CYHAL_TIMER_IRQ_CAPTURE_COMPARE = 1 << 1, /**< Interrupt when Compare/Capture value is reached **/
|
|
CYHAL_TIMER_IRQ_ALL = (1 << 2) - 1, /**< Interrupt on terminal count and Compare/Capture values **/
|
|
} cyhal_timer_event_t;
|
|
|
|
/** Timer/counter input signal */
|
|
typedef enum
|
|
{
|
|
CYHAL_TIMER_INPUT_START, //!< Start signal
|
|
CYHAL_TIMER_INPUT_STOP, //!< Stop signal
|
|
CYHAL_TIMER_INPUT_RELOAD, //!< Reload signal
|
|
CYHAL_TIMER_INPUT_COUNT, //!< Count signal
|
|
CYHAL_TIMER_INPUT_CAPTURE, //!< Capture signal
|
|
} cyhal_timer_input_t;
|
|
|
|
/** Timer/counter output signal */
|
|
typedef enum
|
|
{
|
|
CYHAL_TIMER_OUTPUT_OVERFLOW, //!< Overflow signal
|
|
CYHAL_TIMER_OUTPUT_UNDERFLOW, //!< Underflow signal
|
|
CYHAL_TIMER_OUTPUT_COMPARE_MATCH, //!< Compare Match signal
|
|
CYHAL_TIMER_OUTPUT_TERMINAL_COUNT, //!< Terminal count signal (logical OR of overflow and underflow signal)
|
|
} cyhal_timer_output_t;
|
|
|
|
/*******************************************************************************
|
|
* Data Structures
|
|
*******************************************************************************/
|
|
|
|
/** @brief Describes the current configuration of a timer/counter */
|
|
typedef struct
|
|
{
|
|
/**
|
|
* Whether the timer is set to continuously run.
|
|
* If true, the timer will run forever.
|
|
* Otherwise, the timer will run once and stop (one shot).
|
|
*/
|
|
bool is_continuous; //!< Whether the timer/counter operates continuous (true) or one shot (false)
|
|
cyhal_timer_direction_t direction; //!< Direction the timer/counter is running
|
|
bool is_compare; //!< Is it in compare (true) or capture (false) mode
|
|
uint32_t period; //!< Timer/counter period
|
|
uint32_t compare_value; //!< Timer/counter comparison value
|
|
uint32_t value; //!< Default value of the timer/counter. \ref cyhal_timer_reset() will also change counter to this value when called.
|
|
} cyhal_timer_cfg_t;
|
|
|
|
/*******************************************************************************
|
|
* Typedefs
|
|
*******************************************************************************/
|
|
|
|
/** Handler for timer events */
|
|
typedef void(*cyhal_timer_event_callback_t)(void *callback_arg, cyhal_timer_event_t event);
|
|
|
|
/*******************************************************************************
|
|
* Defines
|
|
*******************************************************************************/
|
|
|
|
/** Default timer frequency, used when an existing clock divider is not provided to \ref cyhal_timer_init() */
|
|
#define CYHAL_TIMER_DEFAULT_FREQ (1000000u)
|
|
|
|
/*******************************************************************************
|
|
* Functions
|
|
*******************************************************************************/
|
|
|
|
/** Initialize the timer/counter peripheral and configure the pin. <br>
|
|
* See \ref subsection_timer_snippet_1.
|
|
*
|
|
* @param[out] obj Pointer to a timer/counter object. The caller must allocate the memory
|
|
* for this object but the init function will initialize its contents.
|
|
* @param[in] pin optional - The timer/counter compare/capture pin to initialize
|
|
* @param[in] clk optional - The shared clock to use, if not provided a new clock will be allocated
|
|
* and the timer frequency will be set to \ref CYHAL_TIMER_DEFAULT_FREQ
|
|
* @return The status of the init request
|
|
*/
|
|
cy_rslt_t cyhal_timer_init(cyhal_timer_t *obj, cyhal_gpio_t pin, const cyhal_clock_t *clk);
|
|
|
|
/** Deinitialize the timer/counter object
|
|
*
|
|
* @param[in,out] obj The timer/counter object
|
|
*/
|
|
void cyhal_timer_free(cyhal_timer_t *obj);
|
|
|
|
/** Updates the configuration and counter value of the timer/counter object. <br>
|
|
* This function may temporary stop the timer if it is currently running.
|
|
* See \ref subsection_timer_snippet_1.
|
|
* @param[in] obj The timer/counter object
|
|
* @param[in] cfg The configuration of the timer/counter
|
|
* @return The status of the configure request
|
|
*/
|
|
cy_rslt_t cyhal_timer_configure(cyhal_timer_t *obj, const cyhal_timer_cfg_t *cfg);
|
|
|
|
/** Configures the timer frequency.
|
|
* \note This is only valid to call if a null clock divider was provided to \ref cyhal_timer_init.
|
|
* If a custom clock was provided its frequency should be adjusted directly.
|
|
*
|
|
* See \ref subsection_timer_snippet_1.
|
|
* @param[in] obj The timer/counter object
|
|
* @param[in] hz The frequency rate in Hz
|
|
* @return The status of the set_frequency request
|
|
*/
|
|
cy_rslt_t cyhal_timer_set_frequency(cyhal_timer_t *obj, uint32_t hz);
|
|
|
|
/** Starts the timer/counter with the pre-set configuration from \ref cyhal_timer_configure.
|
|
* 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 \ref cyhal_timer_configure, and \ref
|
|
* cyhal_timer_reset for how the value can be changed. If none of these functions have
|
|
* been called, it will start from 0.<br>
|
|
* See \ref subsection_timer_snippet_1.
|
|
*
|
|
* @param[in] obj The timer/counter object
|
|
* @return The status of the start request
|
|
*/
|
|
cy_rslt_t cyhal_timer_start(cyhal_timer_t *obj);
|
|
|
|
/** Stops the timer/counter. Does not reset counter value. <br>
|
|
*
|
|
* @param[in] obj The timer/counter object
|
|
* @return The status of the stop request
|
|
*/
|
|
cy_rslt_t cyhal_timer_stop(cyhal_timer_t *obj);
|
|
|
|
/** Reset the timer/counter value to the default value set from \ref cyhal_timer_configure.
|
|
* If \ref cyhal_timer_configure was never called, this will reset timer/counter value to 0.
|
|
* This function may temporary stop the timer. <br>
|
|
*
|
|
* @param[in] obj The timer/counter object
|
|
* @return The status of the reset request
|
|
*/
|
|
cy_rslt_t cyhal_timer_reset(cyhal_timer_t *obj);
|
|
|
|
/** Reads the current value from the timer/counter <br>
|
|
* See \ref subsection_timer_snippet_1.
|
|
*
|
|
* @param[in] obj The timer/counter object
|
|
* @return The current value of the timer/counter
|
|
*/
|
|
uint32_t cyhal_timer_read(const cyhal_timer_t *obj);
|
|
|
|
/** Register a timer/counter callback handler<br>
|
|
*
|
|
* This function will be called when one of the events enabled by \ref cyhal_timer_enable_event occurs.
|
|
*
|
|
* See \ref subsection_timer_snippet_2.
|
|
*
|
|
* @param[in] obj The timer/counter object
|
|
* @param[in] callback The callback handler which will be invoked when the event occurs
|
|
* @param[in] callback_arg Generic argument that will be provided to the callback when called
|
|
*/
|
|
void cyhal_timer_register_callback(cyhal_timer_t *obj, cyhal_timer_event_callback_t callback, void *callback_arg);
|
|
|
|
/** Configure timer/counter event enablement <br>
|
|
*
|
|
* When an enabled event occurs, the function specified by \ref cyhal_timer_register_callback will be called.
|
|
*
|
|
* See \ref subsection_timer_snippet_2.
|
|
*
|
|
* @param[in] obj The timer/counter object
|
|
* @param[in] event The timer/counter event type
|
|
* @param[in] intr_priority The priority for NVIC interrupt events
|
|
* @param[in] enable True to turn on interrupts, False to turn off
|
|
*/
|
|
void cyhal_timer_enable_event(cyhal_timer_t *obj, cyhal_timer_event_t event, uint8_t intr_priority, bool enable);
|
|
|
|
/** Connects a source signal and configures and enables a timer event to be
|
|
* triggered from that signal. These timer events can be configured
|
|
* independently and connect to the same or different source signals.
|
|
*
|
|
* @param[in] obj Timer obj
|
|
* @param[in] source Source signal obtained from another driver's cyhal_<PERIPH>_enable_output
|
|
* @param[in] signal The timer input signal
|
|
* @param[in] type The timer input signal edge type
|
|
* @return The current status of the connection
|
|
* */
|
|
cy_rslt_t cyhal_timer_connect_digital(cyhal_timer_t *obj, cyhal_source_t source, cyhal_timer_input_t signal, cyhal_edge_type_t type);
|
|
|
|
/** Enables the specified output signal from a tcpwm that will be triggered
|
|
* when the corresponding event occurs. Multiple output signals can be
|
|
* configured simultaneously.
|
|
*
|
|
* @param[in] obj Timer obj
|
|
* @param[in] signal The timer output signal
|
|
* @param[out] source Pointer to user-allocated source signal object which
|
|
* will be initialized by enable_output. \p source should be passed to
|
|
* (dis)connect_digital functions to (dis)connect the associated endpoints.
|
|
* @return The current status of the output enable
|
|
* */
|
|
cy_rslt_t cyhal_timer_enable_output(cyhal_timer_t *obj, cyhal_timer_output_t signal, cyhal_source_t *source);
|
|
|
|
/** Disconnects a source signal and disables the timer event.
|
|
*
|
|
* @param[in] obj Timer obj
|
|
* @param[in] source Source signal from cyhal_<PERIPH>_enable_output to disable
|
|
* @param[in] signal The timer input signal
|
|
* @return The status of the disconnection
|
|
* */
|
|
cy_rslt_t cyhal_timer_disconnect_digital(cyhal_timer_t *obj, cyhal_source_t source, cyhal_timer_input_t signal);
|
|
|
|
/** Disables the specified output signal from a timer.
|
|
*
|
|
* @param[in] obj Timer obj
|
|
* @param[in] signal The timer output signal
|
|
* @return The status of the output disable
|
|
* */
|
|
cy_rslt_t cyhal_timer_disable_output(cyhal_timer_t *obj, cyhal_timer_output_t signal);
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#ifdef CYHAL_TIMER_IMPL_HEADER
|
|
#include CYHAL_TIMER_IMPL_HEADER
|
|
#endif /* CYHAL_TIMER_IMPL_HEADER */
|
|
|
|
/** \} group_hal_timer */
|