counter.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016 Intel Corporation
 * Copyright (c) 2018 Nordic Semiconductor ASA
 * Copyright (c) 2026 Meta Platforms
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_COUNTER_H_
#define ZEPHYR_INCLUDE_DRIVERS_COUNTER_H_

 
#include <errno.h>
 
#include <zephyr/types.h>
#include <stddef.h>
#include <zephyr/device.h>
#include <zephyr/sys_clock.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif


#define COUNTER_CONFIG_INFO_COUNT_UP BIT(0)



#define COUNTER_TOP_CFG_DONT_RESET BIT(0)

#define COUNTER_TOP_CFG_RESET_WHEN_LATE BIT(1)



#define COUNTER_ALARM_CFG_ABSOLUTE BIT(0)

#define COUNTER_ALARM_CFG_EXPIRE_WHEN_LATE BIT(1)



#define COUNTER_GUARD_PERIOD_LATE_TO_SET BIT(0)



#define COUNTER_CAPTURE_RISING_EDGE BIT(0)

#define COUNTER_CAPTURE_FALLING_EDGE BIT(1)

#define COUNTER_CAPTURE_BOTH_EDGES (COUNTER_CAPTURE_FALLING_EDGE | COUNTER_CAPTURE_RISING_EDGE)

#define COUNTER_CAPTURE_CONTINUOUS 0

#define COUNTER_CAPTURE_SINGLE_SHOT BIT(2)

 
typedef uint32_t counter_capture_flags_t;


typedef void (*counter_capture_cb_t)(const struct device *dev, uint8_t chan_id,
                                     counter_capture_flags_t flags, uint32_t ticks,
                                     void *user_data);

typedef void (*counter_alarm_callback_t)(const struct device *dev, uint8_t chan_id, uint32_t ticks,
                                         void *user_data);

struct counter_alarm_cfg {
        counter_alarm_callback_t callback;
        uint32_t ticks;
        void *user_data;
        uint32_t flags;
};

typedef void (*counter_top_callback_t)(const struct device *dev, void *user_data);

struct counter_top_cfg {
        uint32_t ticks;
        counter_top_callback_t callback;
        void *user_data;
        uint32_t flags;
};

struct counter_config_info {
#ifdef CONFIG_COUNTER_64BITS_FREQ
        uint64_t freq;
#else
        uint32_t freq;
#endif
#ifdef CONFIG_COUNTER_64BITS_TICKS
        union {
                uint64_t max_top_value_64;
                struct {
#ifdef CONFIG_BIG_ENDIAN
                        uint32_t reserved;
                        uint32_t max_top_value;
#else
                        uint32_t max_top_value;
                        uint32_t reserved;
#endif /* CONFIG_BIG_ENDIAN */
                };
        };
#else
        uint32_t max_top_value;
#endif /* CONFIG_COUNTER_64BITS_TICKS */
        uint8_t flags;
        uint8_t channels;
};

typedef void (*counter_alarm_callback_64_t)(const struct device *dev, uint8_t chan_id,
                                            uint64_t ticks, void *user_data);

struct counter_alarm_cfg_64 {
        uint64_t ticks;
        counter_alarm_callback_64_t callback;
        void *user_data;
        uint32_t flags;
};

struct counter_top_cfg_64 {
        uint64_t ticks;
        counter_top_callback_t callback;
        void *user_data;
        uint32_t flags;
};

typedef void (*counter_capture_cb_64_t)(const struct device *dev, uint8_t chan_id,
                                        counter_capture_flags_t flags, uint64_t ticks,
                                        void *user_data);


typedef int (*counter_api_start)(const struct device *dev);
typedef int (*counter_api_stop)(const struct device *dev);
typedef int (*counter_api_get_value)(const struct device *dev, uint32_t *ticks);
typedef int (*counter_api_reset)(const struct device *dev);
typedef int (*counter_api_set_value)(const struct device *dev, uint32_t ticks);
typedef int (*counter_api_set_alarm)(const struct device *dev, uint8_t chan_id,
                                     const struct counter_alarm_cfg *alarm_cfg);
typedef int (*counter_api_cancel_alarm)(const struct device *dev, uint8_t chan_id);
typedef int (*counter_api_set_top_value)(const struct device *dev,
                                         const struct counter_top_cfg *cfg);
typedef uint32_t (*counter_api_get_pending_int)(const struct device *dev);
typedef uint32_t (*counter_api_get_top_value)(const struct device *dev);
typedef uint32_t (*counter_api_get_guard_period)(const struct device *dev, uint32_t flags);
typedef int (*counter_api_set_guard_period)(const struct device *dev, uint32_t ticks,
                                            uint32_t flags);
typedef uint32_t (*counter_api_get_freq)(const struct device *dev);
typedef uint64_t (*counter_api_get_freq_64)(const struct device *dev);

typedef int (*counter_api_get_value_64)(const struct device *dev, uint64_t *ticks);
typedef int (*counter_api_set_value_64)(const struct device *dev, uint64_t ticks);
typedef int (*counter_api_set_alarm_64)(const struct device *dev, uint8_t chan_id,
                                        const struct counter_alarm_cfg_64 *alarm_cfg);
typedef uint64_t (*counter_api_get_guard_period_64)(const struct device *dev, uint32_t flags);
typedef int (*counter_api_set_guard_period_64)(const struct device *dev, uint64_t ticks,
                                               uint32_t flags);
typedef uint64_t (*counter_api_get_top_value_64)(const struct device *dev);
typedef int (*counter_api_set_top_value_64)(const struct device *dev,
                                            const struct counter_top_cfg_64 *cfg);
typedef int (*counter_api_capture_configure)(const struct device *dev, uint8_t chan_id,
                                             counter_capture_flags_t flags,
                                             counter_capture_cb_t cb, void *user_data);
typedef int (*counter_api_capture_configure_64)(const struct device *dev, uint8_t chan_id,
                                                counter_capture_flags_t flags,
                                                counter_capture_cb_64_t cb, void *user_data);
typedef int (*counter_api_enable_capture)(const struct device *dev, uint8_t chan_id);
typedef int (*counter_api_disable_capture)(const struct device *dev, uint8_t chan_id);

__subsystem struct counter_driver_api {
        counter_api_start start;
        counter_api_stop stop;
        counter_api_get_value get_value;
        counter_api_reset reset;
        counter_api_set_value set_value;
        counter_api_set_alarm set_alarm;
        counter_api_cancel_alarm cancel_alarm;
        counter_api_set_top_value set_top_value;
        counter_api_get_pending_int get_pending_int;
        counter_api_get_top_value get_top_value;
        counter_api_get_guard_period get_guard_period;
        counter_api_set_guard_period set_guard_period;
        counter_api_get_freq get_freq;
#ifdef CONFIG_COUNTER_64BITS_FREQ
        counter_api_get_freq_64 get_freq_64;
#endif /* CONFIG_COUNTER_64BITS_FREQ */
#ifdef CONFIG_COUNTER_64BITS_TICKS
        counter_api_get_value_64 get_value_64;
        counter_api_set_value_64 set_value_64;
        counter_api_set_alarm_64 set_alarm_64;
        counter_api_get_guard_period_64 get_guard_period_64;
        counter_api_set_guard_period_64 set_guard_period_64;
        counter_api_get_top_value_64 get_top_value_64;
        counter_api_set_top_value_64 set_top_value_64;
#endif /* CONFIG_COUNTER_64BITS_TICKS */
#ifdef CONFIG_COUNTER_CAPTURE
        counter_api_capture_configure capture_configure;
#ifdef CONFIG_COUNTER_64BITS_TICKS
        counter_api_capture_configure_64 capture_configure_64;
#endif /* CONFIG_COUNTER_64BITS_TICKS */
        counter_api_enable_capture enable_capture;
        counter_api_disable_capture disable_capture;
#endif /* CONFIG_COUNTER_CAPTURE */
};


__syscall bool counter_is_counting_up(const struct device *dev);
 
static inline bool z_impl_counter_is_counting_up(const struct device *dev)
{
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
 
        return config->flags & COUNTER_CONFIG_INFO_COUNT_UP;
}

__syscall uint8_t counter_get_num_of_channels(const struct device *dev);
 
static inline uint8_t z_impl_counter_get_num_of_channels(const struct device *dev)
{
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
 
        return config->channels;
}
 
__syscall uint32_t counter_get_frequency(const struct device *dev);
 
#ifdef CONFIG_COUNTER_64BITS_FREQ
static inline uint32_t z_impl_counter_get_frequency(const struct device *dev)
{
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (api->get_freq) {
                return api->get_freq(dev);
        } else {
                return config->freq > UINT32_MAX ? UINT32_MAX : (uint32_t)config->freq;
        }
}
 
#else

static inline uint32_t z_impl_counter_get_frequency(const struct device *dev)
{
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        return api->get_freq ? api->get_freq(dev) : config->freq;
}
#endif

__syscall uint64_t counter_get_frequency_64(const struct device *dev);
 
static inline uint64_t z_impl_counter_get_frequency_64(const struct device *dev)
{
#ifdef CONFIG_COUNTER_64BITS_FREQ
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (api->get_freq_64) {
                return api->get_freq_64(dev);
        } else if (api->get_freq) {
                return (uint64_t)api->get_freq(dev);
        } else {
                return config->freq;
        }
#else
        ARG_UNUSED(dev);
        return -ENOTSUP;
#endif
}
 
#ifdef CONFIG_COUNTER_64BITS_FREQ
#define z_counter_get_frequency z_impl_counter_get_frequency_64
#else
#define z_counter_get_frequency z_impl_counter_get_frequency
#endif

__syscall uint32_t counter_us_to_ticks(const struct device *dev, uint64_t us);
 
static inline uint32_t z_impl_counter_us_to_ticks(const struct device *dev, uint64_t us)
{
        uint64_t ticks = (us * z_counter_get_frequency(dev)) / USEC_PER_SEC;
 
        return (ticks > (uint64_t)UINT32_MAX) ? UINT32_MAX : ticks;
}

__syscall uint64_t counter_us_to_ticks_64(const struct device *dev, uint64_t us);
 
static inline uint64_t z_impl_counter_us_to_ticks_64(const struct device *dev, uint64_t us)
{
        return (us * z_counter_get_frequency(dev)) / USEC_PER_SEC;
}

__syscall uint64_t counter_ticks_to_us(const struct device *dev, uint32_t ticks);
 
static inline uint64_t z_impl_counter_ticks_to_us(const struct device *dev, uint32_t ticks)
{
        return ((uint64_t)ticks * USEC_PER_SEC) / z_counter_get_frequency(dev);
}

__syscall uint64_t counter_ticks_to_us_64(const struct device *dev, uint64_t ticks);
 
static inline uint64_t z_impl_counter_ticks_to_us_64(const struct device *dev, uint64_t ticks)
{
        return (ticks * USEC_PER_SEC) / z_counter_get_frequency(dev);
}

__syscall uint32_t counter_ns_to_ticks(const struct device *dev, uint64_t ns);
 
static inline uint32_t z_impl_counter_ns_to_ticks(const struct device *dev, uint64_t ns)
{
        uint64_t ticks = (ns * z_counter_get_frequency(dev)) / NSEC_PER_SEC;
 
        return (ticks > (uint64_t)UINT32_MAX) ? UINT32_MAX : ticks;
}

__syscall uint64_t counter_ns_to_ticks_64(const struct device *dev, uint64_t ns);
 
static inline uint64_t z_impl_counter_ns_to_ticks_64(const struct device *dev, uint64_t ns)
{
        return (ns * z_counter_get_frequency(dev)) / NSEC_PER_SEC;
}

__syscall uint64_t counter_ticks_to_ns(const struct device *dev, uint32_t ticks);
 
static inline uint64_t z_impl_counter_ticks_to_ns(const struct device *dev, uint32_t ticks)
{
        return ((uint64_t)ticks * NSEC_PER_SEC) / z_counter_get_frequency(dev);
}

__syscall uint64_t counter_ticks_to_ns_64(const struct device *dev, uint64_t ticks);
 
static inline uint64_t z_impl_counter_ticks_to_ns_64(const struct device *dev, uint64_t ticks)
{
        return (ticks * NSEC_PER_SEC) / z_counter_get_frequency(dev);
}

__syscall uint32_t counter_get_max_top_value(const struct device *dev);
 
static inline uint32_t z_impl_counter_get_max_top_value(const struct device *dev)
{
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
 
        return config->max_top_value;
}

__syscall int counter_start(const struct device *dev);
 
static inline int z_impl_counter_start(const struct device *dev)
{
        return DEVICE_API_GET(counter, dev)->start(dev);
}

__syscall int counter_stop(const struct device *dev);
 
static inline int z_impl_counter_stop(const struct device *dev)
{
        return DEVICE_API_GET(counter, dev)->stop(dev);
}

__syscall int counter_get_value(const struct device *dev, uint32_t *ticks);
 
static inline int z_impl_counter_get_value(const struct device *dev, uint32_t *ticks)
{
        return DEVICE_API_GET(counter, dev)->get_value(dev, ticks);
}

__syscall int counter_reset(const struct device *dev);
 
static inline int z_impl_counter_reset(const struct device *dev)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (!api->reset) {
                return -ENOSYS;
        }
 
        return api->reset(dev);
}

__syscall int counter_set_value(const struct device *dev, uint32_t ticks);
 
static inline int z_impl_counter_set_value(const struct device *dev, uint32_t ticks)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (!api->set_value) {
                return -ENOSYS;
        }
 
        return api->set_value(dev, ticks);
}

__syscall int counter_set_channel_alarm(const struct device *dev, uint8_t chan_id,
                                        const struct counter_alarm_cfg *alarm_cfg);
 
static inline int z_impl_counter_set_channel_alarm(const struct device *dev, uint8_t chan_id,
                                                   const struct counter_alarm_cfg *alarm_cfg)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->set_alarm(dev, chan_id, alarm_cfg);
}

__syscall int counter_cancel_channel_alarm(const struct device *dev, uint8_t chan_id);
 
static inline int z_impl_counter_cancel_channel_alarm(const struct device *dev, uint8_t chan_id)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->cancel_alarm(dev, chan_id);
}

__syscall int counter_set_top_value(const struct device *dev, const struct counter_top_cfg *cfg);
 
static inline int z_impl_counter_set_top_value(const struct device *dev,
                                               const struct counter_top_cfg *cfg)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (cfg->ticks > counter_get_max_top_value(dev)) {
                return -EINVAL;
        }
 
        return api->set_top_value(dev, cfg);
}

__syscall uint32_t counter_get_pending_int(const struct device *dev);
 
static inline uint32_t z_impl_counter_get_pending_int(const struct device *dev)
{
        return DEVICE_API_GET(counter, dev)->get_pending_int(dev);
}

__syscall uint32_t counter_get_top_value(const struct device *dev);
 
static inline uint32_t z_impl_counter_get_top_value(const struct device *dev)
{
        return DEVICE_API_GET(counter, dev)->get_top_value(dev);
}

__syscall int counter_set_guard_period(const struct device *dev, uint32_t ticks, uint32_t flags);
 
static inline int z_impl_counter_set_guard_period(const struct device *dev, uint32_t ticks,
                                                  uint32_t flags)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (!api->set_guard_period) {
                return -ENOSYS;
        }
 
        return api->set_guard_period(dev, ticks, flags);
}

__syscall uint32_t counter_get_guard_period(const struct device *dev, uint32_t flags);
 
static inline uint32_t z_impl_counter_get_guard_period(const struct device *dev, uint32_t flags)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        return (api->get_guard_period) ? api->get_guard_period(dev, flags) : 0;
}

__syscall uint64_t counter_get_max_top_value_64(const struct device *dev);
 
static inline uint64_t z_impl_counter_get_max_top_value_64(const struct device *dev)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_config_info *config = (const struct counter_config_info *)dev->config;
 
        return config->max_top_value_64;
#else
        ARG_UNUSED(dev);
        return -ENOTSUP;
#endif
}

__syscall int counter_set_top_value_64(const struct device *dev,
                                       const struct counter_top_cfg_64 *cfg);
 
static inline int z_impl_counter_set_top_value_64(const struct device *dev,
                                                  const struct counter_top_cfg_64 *cfg)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (cfg->ticks > counter_get_max_top_value_64(dev)) {
                return -EINVAL;
        }
 
        return api->set_top_value_64(dev, cfg);
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(cfg);
        return -ENOTSUP;
#endif
}

__syscall int counter_set_channel_alarm_64(const struct device *dev, uint8_t chan_id,
                                           const struct counter_alarm_cfg_64 *alarm_cfg);
 
static inline int z_impl_counter_set_channel_alarm_64(const struct device *dev, uint8_t chan_id,
                                                      const struct counter_alarm_cfg_64 *alarm_cfg)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->set_alarm_64(dev, chan_id, alarm_cfg);
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(chan_id);
        ARG_UNUSED(alarm_cfg);
        return -ENOTSUP;
#endif
}

__syscall uint64_t counter_get_top_value_64(const struct device *dev);
 
static inline uint64_t z_impl_counter_get_top_value_64(const struct device *dev)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        return DEVICE_API_GET(counter, dev)->get_top_value_64(dev);
#else
        ARG_UNUSED(dev);
        return 0;
#endif
}

__syscall int counter_set_guard_period_64(const struct device *dev, uint64_t ticks, uint32_t flags);
 
static inline int z_impl_counter_set_guard_period_64(const struct device *dev, uint64_t ticks,
                                                     uint32_t flags)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (!api->set_guard_period_64) {
                return -ENOSYS;
        }
 
        return api->set_guard_period_64(dev, ticks, flags);
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(ticks);
        ARG_UNUSED(flags);
        return -ENOTSUP;
#endif
}

__syscall uint64_t counter_get_guard_period_64(const struct device *dev, uint32_t flags);
 
static inline uint64_t z_impl_counter_get_guard_period_64(const struct device *dev, uint32_t flags)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        return (api->get_guard_period_64) ? api->get_guard_period_64(dev, flags) : 0;
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(flags);
        return -ENOTSUP;
#endif
}

__syscall int counter_get_value_64(const struct device *dev, uint64_t *ticks);
 
static inline int z_impl_counter_get_value_64(const struct device *dev, uint64_t *ticks)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (!api->get_value_64) {
                return -ENOSYS;
        }
 
        return api->get_value_64(dev, ticks);
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(ticks);
        return -ENOTSUP;
#endif
}

__syscall int counter_set_value_64(const struct device *dev, uint64_t ticks);
 
static inline int z_impl_counter_set_value_64(const struct device *dev, uint64_t ticks)
{
#ifdef CONFIG_COUNTER_64BITS_TICKS
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (!api->set_value_64) {
                return -ENOSYS;
        }
 
        return api->set_value_64(dev, ticks);
#else
        ARG_UNUSED(dev);
        ARG_UNUSED(ticks);
        return -ENOTSUP;
#endif
}
 
#if defined(CONFIG_COUNTER_CAPTURE) || defined(__DOXYGEN__)

static inline int counter_capture_configure(const struct device *dev, uint8_t chan_id,
                                            counter_capture_flags_t flags,
                                            counter_capture_cb_t cb, void *user_data)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (api->capture_configure == NULL) {
                return -ENOTSUP;
        }
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->capture_configure(dev, chan_id, flags, cb, user_data);
}
 
#if defined(CONFIG_COUNTER_64BITS_TICKS) || defined(__DOXYGEN__)
static inline int counter_capture_configure_64(const struct device *dev, uint8_t chan_id,
                                               counter_capture_flags_t flags,
                                               counter_capture_cb_64_t cb, void *user_data)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (api->capture_configure_64 == NULL) {
                return -ENOTSUP;
        }
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->capture_configure_64(dev, chan_id, flags, cb, user_data);
}
#endif /* CONFIG_COUNTER_64BITS_TICKS */

__syscall int counter_enable_capture(const struct device *dev, uint8_t chan_id);
 
static inline int z_impl_counter_enable_capture(const struct device *dev, uint8_t chan_id)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (api->enable_capture == NULL) {
                return -ENOTSUP;
        }
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->enable_capture(dev, chan_id);
}

__syscall int counter_disable_capture(const struct device *dev, uint8_t chan_id);
 
static inline int z_impl_counter_disable_capture(const struct device *dev, uint8_t chan_id)
{
        const struct counter_driver_api *api = DEVICE_API_GET(counter, dev);
 
        if (api->disable_capture == NULL) {
                return -ENOTSUP;
        }
 
        if (chan_id >= counter_get_num_of_channels(dev)) {
                return -ENOTSUP;
        }
 
        return api->disable_capture(dev, chan_id);
}

#endif /* CONFIG_COUNTER_CAPTURE */
 
#ifdef __cplusplus
}
#endif

 
#include <zephyr/syscalls/counter.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_COUNTER_H_ */