Counter

Overview

API Reference

group counter_interface

Counter Interface.

Typedefs

typedef void (*counter_alarm_callback_t)(struct device *dev, u8_t chan_id, u32_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)(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)(struct device *dev)
typedef int (*counter_api_stop)(struct device *dev)
typedef u32_t (*counter_api_read)(struct device *dev)
typedef int (*counter_api_set_alarm)(struct device *dev, u8_t chan_id, const struct counter_alarm_cfg *alarm_cfg)
typedef int (*counter_api_cancel_alarm)(struct device *dev, u8_t chan_id)
typedef int (*counter_api_set_top_value)(struct device *dev, const struct counter_top_cfg *cfg)
typedef u32_t (*counter_api_get_pending_int)(struct device *dev)
typedef u32_t (*counter_api_get_top_value)(struct device *dev)
typedef u32_t (*counter_api_get_max_relative_alarm)(struct device *dev)
typedef u32_t (*counter_api_get_guard_period)(struct device *dev, u32_t flags)
typedef int (*counter_api_set_guard_period)(struct device *dev, u32_t ticks, u32_t flags)
typedef void *(*counter_api_get_user_data)(struct device *dev)
typedef void (*counter_callback_t)(struct device *dev, void *user_data)

Functions

static bool counter_is_counting_up(const struct device *dev)

Function to check if counter is counting up.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • true: if counter is counting up.
  • false: if counter is counting down.

static u8_t counter_get_num_of_channels(const struct device *dev)

Function to get number of alarm channels.

Return
Number of alarm channels.
Parameters
  • dev: Pointer to the device structure for the driver instance.

static u32_t counter_get_frequency(const struct device *dev)

Function to get counter frequency.

Return
Frequency of the counter in Hz, or zero if the counter does not have a fixed frequency.
Parameters
  • dev: Pointer to the device structure for the driver instance.

static u32_t counter_us_to_ticks(const struct device *dev, u64_t us)

Function to convert microseconds to ticks.

Return
Converted ticks. Ticks will be saturated if exceed 32 bits.
Parameters
  • dev: Pointer to the device structure for the driver instance.
  • us: Microseconds.

static u64_t counter_ticks_to_us(const struct device *dev, u32_t ticks)

Function to convert ticks to microseconds.

Return
Converted microseconds.
Parameters
  • dev: Pointer to the device structure for the driver instance.
  • ticks: Ticks.

static u32_t counter_get_max_top_value(const struct device *dev)

Function to retrieve maximum top value that can be set.

Return
Max top value.
Parameters
  • dev: Pointer to the device structure for the driver instance.

int counter_start(struct device *dev)

Start counter device in free running mode.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 0: If successful.
  • Negative: errno code if failure.

int counter_stop(struct device *dev)

Stop counter device.

Parameters
  • dev: Pointer to the device structure for the driver instance.
Return Value
  • 0: If successful.
  • -ENOTSUP: if the device doesn’t support stopping the counter.

u32_t counter_read(struct device *dev)

Read current counter value.

Return
32-bit value
Parameters
  • dev: Pointer to the device structure for the driver instance.

static int counter_set_channel_alarm(struct device *dev, u8_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.
Return Value
  • 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.

static int counter_cancel_channel_alarm(struct device *dev, u8_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.
Return Value
  • 0: If successful.
  • -ENOTSUP: if request is not supported or the counter was not started yet.

static int counter_set_top_value(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.
Return Value
  • 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(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.
Return Value
  • 1: if any counter interrupt is pending.
  • 0: if no counter interrupt is pending.

u32_t counter_get_top_value(struct device *dev)

Function to retrieve current top value.

Return
Top value.
Parameters
  • dev: Pointer to the device structure for the driver instance.

u32_t counter_get_max_relative_alarm(struct device *dev)

Function to retrieve maximum relative value that can be set by counter_set_channel_alarm.

Return
Max alarm value.
Parameters
  • dev: Pointer to the device structure for the driver instance.

int counter_set_guard_period(struct device *dev, u32_t ticks, u32_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.
Return Value
  • 0: if successful.
  • -ENOTSUP: if function or flags are not supported.
  • -EINVAL: if ticks value is invalid.

u32_t counter_get_guard_period(struct device *dev, u32_t flags)

Return guard period.

See counter_set_guard_period.

Return
Guard period given in counter ticks or 0 if function or flags are not supported.
Parameters
  • dev: Pointer to the device structure for the driver instance.
  • flags: See Counter guard period flags.

static int counter_set_alarm(struct device *dev, counter_callback_t callback, u32_t count, void *user_data)

Deprecated function.

static void *counter_get_user_data(struct device *dev)

Get user data set for top alarm.

Note
Function intended to be used only by deprecated RTC driver API to provide backward compatibility.
Return
User data.
Parameters
  • dev: Pointer to the device structure for the driver instance.

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.