1 /** 2 * Copyright (c) 2025 STMicroelectronics 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_DRIVERS_TIMER_CORTEX_M_SYSTICK_H_ 8 #define ZEPHYR_INCLUDE_DRIVERS_TIMER_CORTEX_M_SYSTICK_H_ 9 10 #include <zephyr/types.h> 11 12 /** 13 * Hooks/callbacks definitions for interaction between the Cortex-M 14 * SysTick driver and a platform-specific low-power timer driver. 15 * 16 * These functions are invoked by the Cortex-M SysTick driver to 17 * configure a platform-specific timer that remains active when 18 * the system enters a low-power mode. 19 * 20 * In the rest of this file, the "platform-specific low-power mode timer" 21 * is named "LPTIM", and the platform-specific driver that configures the 22 * LPTIM (and implements these hooks/callbacks) is named "LPTIM driver". 23 * 24 * The following behavior is observed when this option is enabled: 25 * 26 * |------(1)---(2)--------------------(3)-------(4)--------------> Time 27 * 28 * (1) cmsd_hook_on_lpm_entry() is invoked 29 * (2) The system enters in low-power mode 30 * (3) The system exits low-power mode (due to timeout or HW event) 31 * (4) cmsd_hook_lpm_time_elapsed() is called 32 * 33 * The return value of cmsd_hook_lpm_time_elapsed() should be as close 34 * as possible to the real time interval between events (1) and (4). 35 * 36 * These hooks should be implemented by the application if and only if 37 * CONFIG_CORTEX_M_SYSTICK_LPM_TIMER_HOOKS is enabled. 38 * 39 * NOTE: the hooks are not invoked when the system enters in low-power 40 * mode for an indefinite amount of time (requires CONFIG_TICKLESS_KERNEL 41 * and no thread PENDING with timeout). 42 */ 43 44 /** 45 * @brief Hook invoked when the system is about to enter low-power mode 46 * 47 * @param max_lpm_time_us Maximal time allowed in low-power mode (µs) 48 * 49 * The LPTIM driver should configure the LPTIM to wake up the system 50 * after at most @a{max_lpm_time_us} elapses; depending on hardware 51 * capabilities, the LPTIM may have to be configured to wake up the 52 * system earlier than requested (but no later!). 53 * 54 * Note that this hook is not called if the system enters low-power 55 * mode for an indefinite amount of time (i.e., when no threads are 56 * runnable or waiting with timeout). 57 */ 58 void z_cms_lptim_hook_on_lpm_entry(uint64_t max_lpm_time_us); 59 60 /** 61 * @brief Callback invoked after system exits low-power mode 62 * 63 * This function should return the time elapsed, in microseconds, 64 * since entry in low-power mode occurred (i.e., since the call 65 * to @ref{cmsd_hook_on_lpm_entry}). 66 */ 67 uint64_t z_cms_lptim_hook_on_lpm_exit(void); 68 #endif /* ZEPHYR_INCLUDE_DRIVERS_TIMER_CORTEX_M_SYSTICK_H_ */ 69
