This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Counter

Overview

API Reference

group counter_interface

Counter Interface.

Typedefs

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

Alarm callback.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • chan_id – Channel ID.

  • ticks – Counter value that triggered the alarm.

  • user_data – User data.

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

Callback called when counter turns around.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • user_data – User data provided in counter_set_top_value.

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_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)

Functions

bool counter_is_counting_up(const struct device *dev)

Function to check if counter is counting up.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

Returns

  • true – if counter is counting up.

  • false – if counter is counting down.

uint8_t counter_get_num_of_channels(const struct device *dev)

Function to get number of alarm channels.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

Returns

Number of alarm channels.

uint32_t counter_get_frequency(const struct device *dev)

Function to get counter frequency.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

Returns

Frequency of the counter in Hz, or zero if the counter does not have a fixed frequency.

uint32_t counter_us_to_ticks(const struct device *dev, uint64_t us)

Function to convert microseconds to ticks.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

  • us – [in] Microseconds.

Returns

Converted ticks. Ticks will be saturated if exceed 32 bits.

uint64_t counter_ticks_to_us(const struct device *dev, uint32_t ticks)

Function to convert ticks to microseconds.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

  • ticks – [in] Ticks.

Returns

Converted microseconds.

uint32_t counter_get_max_top_value(const struct device *dev)

Function to retrieve maximum top value that can be set.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

Returns

Max top value.

int counter_start(const struct device *dev)

Start counter device in free running mode.

Parameters

  • dev – Pointer to the device structure for the driver instance.

Returns

  • 0 – If successful.

  • Negative – errno code if failure.

int counter_stop(const struct device *dev)

Stop counter device.

Parameters

  • dev – Pointer to the device structure for the driver instance.

Returns

  • 0 – If successful.

  • -ENOTSUP – if the device doesn’t support stopping the counter.

int counter_get_value(const struct device *dev, uint32_t *ticks)

Get current counter value.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • ticks – Pointer to where to store the current counter value

Returns

  • 0 – If successful.

  • Negative – error code on failure getting the counter value

int counter_set_channel_alarm(const struct device *dev, uint8_t chan_id, const struct counter_alarm_cfg *alarm_cfg)

Set a single shot alarm on a channel.

After expiration alarm can be set again, disabling is not needed. When alarm expiration handler is called, channel is considered available and can be set again in that context.

Note

API is not thread safe.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • chan_id – Channel ID.

  • alarm_cfg – Alarm configuration.

Returns

  • 0 – If successful.

  • -ENOTSUP – if request is not supported (device does not support interrupts or requested channel).

  • -EINVAL – if alarm settings are invalid.

  • -ETIME – if absolute alarm was set too late.

int counter_cancel_channel_alarm(const struct device *dev, uint8_t chan_id)

Cancel an alarm on a channel.

Note

API is not thread safe.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • chan_id – Channel ID.

Returns

  • 0 – If successful.

  • -ENOTSUP – if request is not supported or the counter was not started yet.

int counter_set_top_value(const struct device *dev, const struct counter_top_cfg *cfg)

Set counter top value.

Function sets top value and optionally resets the counter to 0 or top value depending on counter direction. On turnaround, counter can be reset and optional callback is periodically called. Top value can only be changed when there is no active channel alarm.

COUNTER_TOP_CFG_DONT_RESET prevents counter reset. When counter is running while top value is updated, it is possible that counter progresses outside the new top value. In that case, error is returned and optionally driver can reset the counter (see COUNTER_TOP_CFG_RESET_WHEN_LATE).

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • cfg – Configuration. Cannot be NULL.

Returns

  • 0 – If successful.

  • -ENOTSUP – if request is not supported (e.g. top value cannot be changed or counter cannot/must be reset during top value update).

  • -EBUSY – if any alarm is active.

  • -ETIME – if COUNTER_TOP_CFG_DONT_RESET was set and new top value is smaller than current counter value (counter counting up).

int counter_get_pending_int(const struct device *dev)

Function to get pending interrupts.

The purpose of this function is to return the interrupt status register for the device. This is especially useful when waking up from low power states to check the wake up source.

Parameters

  • dev – Pointer to the device structure for the driver instance.

Returns

  • 1 – if any counter interrupt is pending.

  • 0 – if no counter interrupt is pending.

uint32_t counter_get_top_value(const struct device *dev)

Function to retrieve current top value.

Parameters

  • dev – [in] Pointer to the device structure for the driver instance.

Returns

Top value.

int counter_set_guard_period(const struct device *dev, uint32_t ticks, uint32_t flags)

Set guard period in counter ticks.

Setting non-zero guard period enables detection of setting absolute alarm too late. It limits how far in the future absolute alarm can be set.

Detection of too late setting is vital since if it is not detected alarm is delayed by full period of the counter (up to 32 bits). Because of the wrapping, it is impossible to distinguish alarm which is short in the past from alarm which is targeted to expire after full counter period. In order to detect too late setting, longest possible alarm is limited. Absolute value cannot exceed: (now + top_value - guard_period) % top_value.

Guard period depends on application and counter frequency. If it is expected that absolute alarms setting might be delayed then guard period should exceed maximal potential delay. If use case allows, guard period can be set very high (e.g. half of the counter top value).

After initialization guard period is set to 0 and late detection is disabled.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • ticks – Guard period in counter ticks.

  • flags – See Counter guard period flags.

Returns

  • 0 – if successful.

  • -ENOTSUP – if function or flags are not supported.

  • -EINVAL – if ticks value is invalid.

uint32_t counter_get_guard_period(const struct device *dev, uint32_t flags)

Return guard period.

See counter_set_guard_period.

Parameters

  • dev – Pointer to the device structure for the driver instance.

  • flags – See Counter guard period flags.

Returns

Guard period given in counter ticks or 0 if function or flags are not supported.

struct counter_alarm_cfg
#include <counter.h>

Alarm callback structure.

Parameters

  • callback – Callback called on alarm (cannot be NULL).

  • ticks – Number of ticks that triggers the alarm. It can be relative (to now) or absolute value (see COUNTER_ALARM_CFG_ABSOLUTE). Absolute alarm cannot be set further in future than top_value decremented by the guard period. Relative alarm ticks cannot exceed current top value (see counter_get_top_value). If counter is clock driven then ticks can be converted to microseconds (see counter_ticks_to_us). Alternatively, counter implementation may count asynchronous events.

  • user_data – User data returned in callback.

  • flags – Alarm flags. See Alarm configuration flags.

struct counter_top_cfg
#include <counter.h>

Top value configuration structure.

Parameters

  • ticks – Top value.

  • callback – Callback function. Can be NULL.

  • user_data – User data passed to callback function. Not valid if callback is NULL.

  • flags – Flags. See Flags used by .

struct counter_config_info
#include <counter.h>

Structure with generic counter features.

Parameters

  • max_top_value – Maximal (default) top value on which counter is reset (cleared or reloaded).

  • freq – Frequency of the source clock if synchronous events are counted.

  • flags – Flags. See Counter device capabilities.

  • channels – Number of channels that can be used for setting alarm, see counter_set_channel_alarm.

struct counter_driver_api
#include <counter.h>