/* * Copyright (c) 2024 Nordic Semiconductor ASA * * SPDX-License-Identifier: Apache-2.0 */ #ifndef ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_GRTC_TIMER_H #define ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_GRTC_TIMER_H #ifdef __cplusplus extern "C" { #endif #include /** @brief GRTC timer compare event handler. * * Called from GRTC ISR context when processing a compare event. * * @param id Compare channel ID. * * @param expire_time An actual absolute expiration time set for a compare * channel. It can differ from the requested target time * and the difference can be used to determine whether the * time set was delayed. * * @param user_data Pointer to a user context data. */ typedef void (*z_nrf_grtc_timer_compare_handler_t)(int32_t id, uint64_t expire_time, void *user_data); /** @brief Allocate GRTC capture/compare channel. * * @retval >=0 Non-negative indicates allocated channel ID. * @retval -ENOMEM if channel cannot be allocated. */ int32_t z_nrf_grtc_timer_chan_alloc(void); /** @brief Free GRTC capture/compare channel. * * @param chan Previously allocated channel ID. */ void z_nrf_grtc_timer_chan_free(int32_t chan); /** @brief Read current absolute time. * * @return Current absolute time. */ uint64_t z_nrf_grtc_timer_read(void); /** @brief Check COMPARE event state. * * @param chan Channel ID. * * @retval true The event has been generated. * @retval false The event has not been generated. */ bool z_nrf_grtc_timer_compare_evt_check(int32_t chan); /** @brief Get COMPARE event register address. * * Address can be used for DPPIC. * * @param chan Channel ID. * * @return Register address. */ uint32_t z_nrf_grtc_timer_compare_evt_address_get(int32_t chan); /** @brief Get CAPTURE task register address. * * Address can be used for DPPIC. * * @param chan Channel ID. * * @return Register address. */ uint32_t z_nrf_grtc_timer_capture_task_address_get(int32_t chan); /** @brief Safely disable compare event interrupt. * * Function returns key indicating whether interrupt was already disabled. * * @param chan Channel ID. * * @return key passed to z_nrf_grtc_timer_compare_int_unlock(). */ bool z_nrf_grtc_timer_compare_int_lock(int32_t chan); /** @brief Safely enable compare event interrupt. * * Event interrupt is conditionally enabled based on @p key. * * @param chan Channel ID. * * @param key Key returned by z_nrf_grtc_timer_compare_int_lock(). */ void z_nrf_grtc_timer_compare_int_unlock(int32_t chan, bool key); /** @brief Read compare register value. * * @param chan Channel ID. * * @param val Pointer to store the value. * * @retval 0 if the compare register was read successfully. * @retval -EAGAIN if compare for given channel is not set. * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running. */ int z_nrf_grtc_timer_compare_read(int32_t chan, uint64_t *val); /** @brief Set compare channel to given value. * * @param chan Channel ID. * * @param target_time Absolute target time in GRTC ticks. * * @param handler User function called in the context of the GRTC interrupt. * * @param user_data Data passed to the handler. * * @retval 0 if the compare channel was set successfully. * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running. */ int z_nrf_grtc_timer_set(int32_t chan, uint64_t target_time, z_nrf_grtc_timer_compare_handler_t handler, void *user_data); /** @brief Abort a timer requested with z_nrf_grtc_timer_set(). * * If an abort operation is performed too late it is still possible for an event * to fire. The user can detect a spurious event by comparing absolute time * provided in callback and a result of z_nrf_grtc_timer_read(). During this * operation interrupt from that compare channel is disabled. Other interrupts * are not locked during this operation. * * @param chan Channel ID between 1 and CONFIG_NRF_RTC_TIMER_USER_CHAN_COUNT. */ void z_nrf_grtc_timer_abort(int32_t chan); /** @brief Convert system clock time to GRTC ticks. * * @p t can be absolute or relative. * * @retval >=0 Positive value represents @p t in GRTC tick value. * @retval -EINVAL if @p t is out of range. */ uint64_t z_nrf_grtc_timer_get_ticks(k_timeout_t t); /** @brief Prepare channel for timestamp capture. * * Use z_nrf_grtc_timer_capture_task_address_get() to determine the register * address that is used to trigger capture. * * @note Capture and compare are mutually exclusive features - they cannot be * used simultaneously on the same GRTC channel. * * @param chan Channel ID. * * @retval 0 if the channel was successfully prepared. * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running. */ int z_nrf_grtc_timer_capture_prepare(int32_t chan); /** @brief Read timestamp value captured on the channel. * * The @p chan must be prepared using z_nrf_grtc_timer_capture_prepare(). * * @param chan Channel ID. * * @param captured_time Pointer to store the value. * * @retval 0 if the timestamp was successfully caught and read. * @retval -EBUSY if capturing has not been triggered. * @retval -EPERM if either channel is unavailable or SYSCOUNTER is not running. */ int z_nrf_grtc_timer_capture_read(int32_t chan, uint64_t *captured_time); /** @brief Prepare GRTC as a source of wake up event and set the wake up time. * * @note Calling this function should be immediately followed by low-power mode enter * (if it executed successfully). * * @param wake_time_us Relative wake up time in microseconds. * * @retval 0 if wake up time was successfully set. * @retval -EPERM if the SYSCOUNTER is not running. * @retval -ENOMEM if no available GRTC channels were found. * @retval -EINVAL if @p wake_time_us is too low. */ int z_nrf_grtc_wakeup_prepare(uint64_t wake_time_us); /** * @brief Initialize the GRTC clock timer driver from an application- * defined function. * * @retval 0 on success. * @retval -errno Negative error code on failure. */ int nrf_grtc_timer_clock_driver_init(void); #ifdef __cplusplus } #endif #endif /* ZEPHYR_INCLUDE_DRIVERS_TIMER_NRF_GRTC_TIMER_H */