Zephyr API Documentation 4.0.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Counter Interface

Counter Interface . More...

Data Structures

struct  counter_alarm_cfg
 Alarm callback structure. More...
 
struct  counter_top_cfg
 Top value configuration structure. More...
 
struct  counter_config_info
 Structure with generic counter features. More...
 
struct  counter_driver_api
 

Typedefs

typedef void(* counter_alarm_callback_t) (const struct device *dev, uint8_t chan_id, uint32_t ticks, void *user_data)
 Alarm callback.
 
typedef void(* counter_top_callback_t) (const struct device *dev, void *user_data)
 Callback called when counter turns around.
 
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_get_value_64) (const struct device *dev, uint64_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)
 

Functions

bool counter_is_counting_up (const struct device *dev)
 Function to check if counter is counting up.
 
uint8_t counter_get_num_of_channels (const struct device *dev)
 Function to get number of alarm channels.
 
uint32_t counter_get_frequency (const struct device *dev)
 Function to get counter frequency.
 
uint32_t counter_us_to_ticks (const struct device *dev, uint64_t us)
 Function to convert microseconds to ticks.
 
uint64_t counter_ticks_to_us (const struct device *dev, uint32_t ticks)
 Function to convert ticks to microseconds.
 
uint32_t counter_get_max_top_value (const struct device *dev)
 Function to retrieve maximum top value that can be set.
 
int counter_start (const struct device *dev)
 Start counter device in free running mode.
 
int counter_stop (const struct device *dev)
 Stop counter device.
 
int counter_get_value (const struct device *dev, uint32_t *ticks)
 Get current counter value.
 
int counter_get_value_64 (const struct device *dev, uint64_t *ticks)
 Get current counter 64-bit 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.
 
int counter_cancel_channel_alarm (const struct device *dev, uint8_t chan_id)
 Cancel an alarm on a channel.
 
int counter_set_top_value (const struct device *dev, const struct counter_top_cfg *cfg)
 Set counter top value.
 
int counter_get_pending_int (const struct device *dev)
 Function to get pending interrupts.
 
uint32_t counter_get_top_value (const struct device *dev)
 Function to retrieve current top value.
 
int counter_set_guard_period (const struct device *dev, uint32_t ticks, uint32_t flags)
 Set guard period in counter ticks.
 
uint32_t counter_get_guard_period (const struct device *dev, uint32_t flags)
 Return guard period.
 

Counter device capabilities

#define COUNTER_CONFIG_INFO_COUNT_UP   BIT(0)
 Counter count up flag.
 

Flags used by counter_top_cfg.

#define COUNTER_TOP_CFG_DONT_RESET   BIT(0)
 Flag preventing counter reset when top value is changed.
 
#define COUNTER_TOP_CFG_RESET_WHEN_LATE   BIT(1)
 Flag instructing counter to reset itself if changing top value results in counter going out of new top value bound.
 

Alarm configuration flags

Used in alarm configuration structure (counter_alarm_cfg).

#define COUNTER_ALARM_CFG_ABSOLUTE   BIT(0)
 Counter alarm absolute value flag.
 
#define COUNTER_ALARM_CFG_EXPIRE_WHEN_LATE   BIT(1)
 Alarm flag enabling immediate expiration when driver detects that absolute alarm was set too late.
 

Counter guard period flags

Used by counter_set_guard_period and counter_get_guard_period.

#define COUNTER_GUARD_PERIOD_LATE_TO_SET   BIT(0)
 Identifies guard period needed for detection of late setting of absolute alarm (see counter_set_channel_alarm).
 

Detailed Description

Counter Interface .

Since
1.14
Version
0.8.0

Macro Definition Documentation

◆ COUNTER_ALARM_CFG_ABSOLUTE

#define COUNTER_ALARM_CFG_ABSOLUTE   BIT(0)

#include <zephyr/drivers/counter.h>

Counter alarm absolute value flag.

Ticks relation to counter value. If set ticks are treated as absolute value, else it is relative to the counter reading performed during the call.

◆ COUNTER_ALARM_CFG_EXPIRE_WHEN_LATE

#define COUNTER_ALARM_CFG_EXPIRE_WHEN_LATE   BIT(1)

#include <zephyr/drivers/counter.h>

Alarm flag enabling immediate expiration when driver detects that absolute alarm was set too late.

Alarm callback must be called from the same context as if it was set on time.

◆ COUNTER_CONFIG_INFO_COUNT_UP

#define COUNTER_CONFIG_INFO_COUNT_UP   BIT(0)

#include <zephyr/drivers/counter.h>

Counter count up flag.

◆ COUNTER_GUARD_PERIOD_LATE_TO_SET

#define COUNTER_GUARD_PERIOD_LATE_TO_SET   BIT(0)

#include <zephyr/drivers/counter.h>

Identifies guard period needed for detection of late setting of absolute alarm (see counter_set_channel_alarm).

◆ COUNTER_TOP_CFG_DONT_RESET

#define COUNTER_TOP_CFG_DONT_RESET   BIT(0)

#include <zephyr/drivers/counter.h>

Flag preventing counter reset when top value is changed.

If flags is set then counter is free running while top value is updated, otherwise counter is reset (see counter_set_top_value()).

◆ COUNTER_TOP_CFG_RESET_WHEN_LATE

#define COUNTER_TOP_CFG_RESET_WHEN_LATE   BIT(1)

#include <zephyr/drivers/counter.h>

Flag instructing counter to reset itself if changing top value results in counter going out of new top value bound.

See COUNTER_TOP_CFG_DONT_RESET.

Typedef Documentation

◆ counter_alarm_callback_t

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

#include <zephyr/drivers/counter.h>

Alarm callback.

Parameters
devPointer to the device structure for the driver instance.
chan_idChannel ID.
ticksCounter value that triggered the alarm.
user_dataUser data.

◆ counter_api_cancel_alarm

typedef int(* counter_api_cancel_alarm) (const struct device *dev, uint8_t chan_id)

◆ counter_api_get_freq

typedef uint32_t(* counter_api_get_freq) (const struct device *dev)

◆ counter_api_get_guard_period

typedef uint32_t(* counter_api_get_guard_period) (const struct device *dev, uint32_t flags)

◆ counter_api_get_pending_int

typedef uint32_t(* counter_api_get_pending_int) (const struct device *dev)

◆ counter_api_get_top_value

typedef uint32_t(* counter_api_get_top_value) (const struct device *dev)

◆ counter_api_get_value

typedef int(* counter_api_get_value) (const struct device *dev, uint32_t *ticks)

◆ counter_api_get_value_64

typedef int(* counter_api_get_value_64) (const struct device *dev, uint64_t *ticks)

◆ counter_api_set_alarm

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

◆ counter_api_set_guard_period

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

◆ counter_api_set_top_value

typedef int(* counter_api_set_top_value) (const struct device *dev, const struct counter_top_cfg *cfg)

◆ counter_api_start

typedef int(* counter_api_start) (const struct device *dev)

◆ counter_api_stop

typedef int(* counter_api_stop) (const struct device *dev)

◆ counter_top_callback_t

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

#include <zephyr/drivers/counter.h>

Callback called when counter turns around.

Parameters
devPointer to the device structure for the driver instance.
user_dataUser data provided in counter_set_top_value.

Function Documentation

◆ counter_cancel_channel_alarm()

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

#include <zephyr/drivers/counter.h>

Cancel an alarm on a channel.

Note
API is not thread safe.
Parameters
devPointer to the device structure for the driver instance.
chan_idChannel ID.
Return values
0If successful.
-ENOTSUPif request is not supported or the counter was not started yet.

◆ counter_get_frequency()

uint32_t counter_get_frequency ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Function to get counter frequency.

Parameters
[in]devPointer 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.

◆ counter_get_guard_period()

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

#include <zephyr/drivers/counter.h>

Return guard period.

See also
counter_set_guard_period.
Parameters
devPointer to the device structure for the driver instance.
flagsSee COUNTER_GUARD_PERIOD_FLAGS.
Returns
Guard period given in counter ticks or 0 if function or flags are not supported.

◆ counter_get_max_top_value()

uint32_t counter_get_max_top_value ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Function to retrieve maximum top value that can be set.

Parameters
[in]devPointer to the device structure for the driver instance.
Returns
Max top value.

◆ counter_get_num_of_channels()

uint8_t counter_get_num_of_channels ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Function to get number of alarm channels.

Parameters
[in]devPointer to the device structure for the driver instance.
Returns
Number of alarm channels.

◆ counter_get_pending_int()

int counter_get_pending_int ( const struct device * dev)

#include <zephyr/drivers/counter.h>

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
devPointer to the device structure for the driver instance.
Return values
1if any counter interrupt is pending.
0if no counter interrupt is pending.

◆ counter_get_top_value()

uint32_t counter_get_top_value ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Function to retrieve current top value.

Parameters
[in]devPointer to the device structure for the driver instance.
Returns
Top value.

◆ counter_get_value()

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

#include <zephyr/drivers/counter.h>

Get current counter value.

Parameters
devPointer to the device structure for the driver instance.
ticksPointer to where to store the current counter value
Return values
0If successful.
Negativeerror code on failure getting the counter value

◆ counter_get_value_64()

int counter_get_value_64 ( const struct device * dev,
uint64_t * ticks )

#include <zephyr/drivers/counter.h>

Get current counter 64-bit value.

Parameters
devPointer to the device structure for the driver instance.
ticksPointer to where to store the current counter value
Return values
0If successful.
Negativeerror code on failure getting the counter value

◆ counter_is_counting_up()

bool counter_is_counting_up ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Function to check if counter is counting up.

Parameters
[in]devPointer to the device structure for the driver instance.
Return values
trueif counter is counting up.
falseif counter is counting down.

◆ counter_set_channel_alarm()

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

#include <zephyr/drivers/counter.h>

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
devPointer to the device structure for the driver instance.
chan_idChannel ID.
alarm_cfgAlarm configuration.
Return values
0If successful.
-ENOTSUPif request is not supported (device does not support interrupts or requested channel).
-EINVALif alarm settings are invalid.
-ETIMEif absolute alarm was set too late.
-EBUSYif alarm is already active.

◆ counter_set_guard_period()

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

#include <zephyr/drivers/counter.h>

Set guard period in counter ticks.

When setting an absolute alarm value close to the current counter value there is a risk that the counter will have counted past the given absolute value before the driver manages to activate the alarm. If this would go unnoticed then the alarm would only expire after the timer has wrapped and reached the given absolute value again after a full timer period. This could take a long time in case of a 32 bit timer. Setting a sufficiently large guard period will help the driver detect unambiguously whether it is late or not.

The guard period should be as many counter ticks as the driver will need at most to actually activate the alarm after the driver API has been called. If the driver finds that the counter has just passed beyond the given absolute tick value but is still close enough to fall within the guard period, it will assume that it is "late", i.e. that the intended expiry time has already passed. Depending on the COUNTER_ALARM_CFG_EXPIRE_WHEN_LATE flag the driver will either ignore the alarm or expire it immediately in such a case.

If, however, the counter is past the given absolute tick value but outside the guard period, then the driver will assume that this is intentional and let the counter wrap around to/from zero before it expires.

More precisely:

  • When counting upwards (see COUNTER_CONFIG_INFO_COUNT_UP) the given absolute tick value must be above (now + guard_period) % top_value to be accepted by the driver.
  • When counting downwards, the given absolute tick value must be less than (now + top_value - guard_period) % top_value to be accepted.

Examples:

  • counting upwards, now = 4950, top value = 5000, guard period = 100: absolute tick value >= (4950 + 100) % 5000 = 50
  • counting downwards, now = 50, top value = 5000, guard period = 100: absolute tick value <= (50 + 5000 - * 100) % 5000 = 4950

If you need only short alarm periods, you can set the guard period very high (e.g. half of the counter top value) which will make it highly unlikely that the counter will ever unintentionally wrap.

The guard period is set to 0 on initialization (no protection).

Parameters
devPointer to the device structure for the driver instance.
ticksGuard period in counter ticks.
flagsSee COUNTER_GUARD_PERIOD_FLAGS.
Return values
0if successful.
-ENOTSUPif function or flags are not supported.
-EINVALif ticks value is invalid.

◆ counter_set_top_value()

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

#include <zephyr/drivers/counter.h>

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
devPointer to the device structure for the driver instance.
cfgConfiguration. Cannot be NULL.
Return values
0If successful.
-ENOTSUPif request is not supported (e.g. top value cannot be changed or counter cannot/must be reset during top value update).
-EBUSYif any alarm is active.
-ETIMEif COUNTER_TOP_CFG_DONT_RESET was set and new top value is smaller than current counter value (counter counting up).

◆ counter_start()

int counter_start ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Start counter device in free running mode.

Parameters
devPointer to the device structure for the driver instance.
Return values
0If successful.
Negativeerrno code if failure.

◆ counter_stop()

int counter_stop ( const struct device * dev)

#include <zephyr/drivers/counter.h>

Stop counter device.

Parameters
devPointer to the device structure for the driver instance.
Return values
0If successful.
-ENOTSUPif the device doesn't support stopping the counter.

◆ counter_ticks_to_us()

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

#include <zephyr/drivers/counter.h>

Function to convert ticks to microseconds.

Parameters
[in]devPointer to the device structure for the driver instance.
[in]ticksTicks.
Returns
Converted microseconds.

◆ counter_us_to_ticks()

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

#include <zephyr/drivers/counter.h>

Function to convert microseconds to ticks.

Parameters
[in]devPointer to the device structure for the driver instance.
[in]usMicroseconds.
Returns
Converted ticks. Ticks will be saturated if exceed 32 bits.