006d6e5cb7
Add support for a hook-based low-power mode timer to the Cortex-M SysTick driver, in addition to the existing Counter API-based timer. This is useful on platforms such as the STM32WB0 where the wake-up timer is too limited for a Counter API driver to be implemented on top of it. Signed-off-by: Mathieu Choplain <mathieu.choplain@st.com>
69 lines
2.5 KiB
C
69 lines
2.5 KiB
C
/**
|
|
* Copyright (c) 2025 STMicroelectronics
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_INCLUDE_DRIVERS_TIMER_CORTEX_M_SYSTICK_H_
|
|
#define ZEPHYR_INCLUDE_DRIVERS_TIMER_CORTEX_M_SYSTICK_H_
|
|
|
|
#include <zephyr/types.h>
|
|
|
|
/**
|
|
* Hooks/callbacks definitions for interaction between the Cortex-M
|
|
* SysTick driver and a platform-specific low-power timer driver.
|
|
*
|
|
* These functions are invoked by the Cortex-M SysTick driver to
|
|
* configure a platform-specific timer that remains active when
|
|
* the system enters a low-power mode.
|
|
*
|
|
* In the rest of this file, the "platform-specific low-power mode timer"
|
|
* is named "LPTIM", and the platform-specific driver that configures the
|
|
* LPTIM (and implements these hooks/callbacks) is named "LPTIM driver".
|
|
*
|
|
* The following behavior is observed when this option is enabled:
|
|
*
|
|
* |------(1)---(2)--------------------(3)-------(4)--------------> Time
|
|
*
|
|
* (1) cmsd_hook_on_lpm_entry() is invoked
|
|
* (2) The system enters in low-power mode
|
|
* (3) The system exits low-power mode (due to timeout or HW event)
|
|
* (4) cmsd_hook_lpm_time_elapsed() is called
|
|
*
|
|
* The return value of cmsd_hook_lpm_time_elapsed() should be as close
|
|
* as possible to the real time interval between events (1) and (4).
|
|
*
|
|
* These hooks should be implemented by the application if and only if
|
|
* CONFIG_CORTEX_M_SYSTICK_LPM_TIMER_HOOKS is enabled.
|
|
*
|
|
* NOTE: the hooks are not invoked when the system enters in low-power
|
|
* mode for an indefinite amount of time (requires CONFIG_TICKLESS_KERNEL
|
|
* and no thread PENDING with timeout).
|
|
*/
|
|
|
|
/**
|
|
* @brief Hook invoked when the system is about to enter low-power mode
|
|
*
|
|
* @param max_lpm_time_us Maximal time allowed in low-power mode (µs)
|
|
*
|
|
* The LPTIM driver should configure the LPTIM to wake up the system
|
|
* after at most @a{max_lpm_time_us} elapses; depending on hardware
|
|
* capabilities, the LPTIM may have to be configured to wake up the
|
|
* system earlier than requested (but no later!).
|
|
*
|
|
* Note that this hook is not called if the system enters low-power
|
|
* mode for an indefinite amount of time (i.e., when no threads are
|
|
* runnable or waiting with timeout).
|
|
*/
|
|
void z_cms_lptim_hook_on_lpm_entry(uint64_t max_lpm_time_us);
|
|
|
|
/**
|
|
* @brief Callback invoked after system exits low-power mode
|
|
*
|
|
* This function should return the time elapsed, in microseconds,
|
|
* since entry in low-power mode occurred (i.e., since the call
|
|
* to @ref{cmsd_hook_on_lpm_entry}).
|
|
*/
|
|
uint64_t z_cms_lptim_hook_on_lpm_exit(void);
|
|
#endif /* ZEPHYR_INCLUDE_DRIVERS_TIMER_CORTEX_M_SYSTICK_H_ */
|