Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_aon_timer.h File Reference

(dcee03a)

Always-On Timer Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Go to the source code of this file.

Data Structures

struct  dif_aon_timer_params
 Hardware instantiation parameters for Always-On Timer. More...
 
struct  dif_aon_timer
 A handle to Always-On Timer. More...
 

Typedefs

typedef struct dif_aon_timer_params dif_aon_timer_params_t
 Hardware instantiation parameters for Always-On Timer. More...
 
typedef struct dif_aon_timer dif_aon_timer_t
 A handle to Always-On Timer. More...
 
typedef enum dif_aon_timer_result dif_aon_timer_result_t
 The result of a Always-On Timer operation.
 
typedef enum dif_aon_timer_watchdog_result dif_aon_timer_watchdog_result_t
 The result of a Always-On Timer (watchdog timer) operation.
 
typedef enum dif_aon_timer_irq dif_aon_timer_irq_t
 An Always-On Timer interrupt request type.
 

Enumerations

enum  dif_aon_timer_result {
  kDifAonTimerOk = 0,
  kDifAonTimerError = 1,
  kDifAonTimerBadArg = 2
}
 The result of a Always-On Timer operation. More...
 
enum  dif_aon_timer_watchdog_result {
  kDifAonTimerWatchdogOk = kDifAonTimerOk,
  kDifAonTimerWatchdogError = kDifAonTimerError,
  kDifAonTimerWatchdogBadArg = kDifAonTimerBadArg,
  kDifAonTimerWatchdogLocked = 3
}
 The result of a Always-On Timer (watchdog timer) operation. More...
 
enum  dif_aon_timer_irq {
  kDifAonTimerIrqWakeupThreshold = 0,
  kDifAonTimerIrqWatchdogBarkThreshold
}
 An Always-On Timer interrupt request type. More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_init (dif_aon_timer_params_t params, dif_aon_timer_t *aon)
 Creates a new handle for Always-On Timer. More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_start (const dif_aon_timer_t *aon, uint32_t threshold, uint32_t prescaler)
 Starts Always-On Timer (wake-up timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_stop (const dif_aon_timer_t *aon)
 Stops Always-On Timer (wake-up timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_restart (const dif_aon_timer_t *aon)
 Restarts Always-On Timer (wake-up timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_get_count (const dif_aon_timer_t *aon, uint32_t *count)
 Retrieves Always-On Timer (wake-up timer) tick count. More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_start (const dif_aon_timer_t *aon, uint32_t bark_threshold, uint32_t bite_threshold, bool pause_in_sleep, bool lock)
 Starts Always-On Timer (watchdog timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_stop (const dif_aon_timer_t *aon)
 Stops Always-On Timer (watchdog timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_restart (const dif_aon_timer_t *aon)
 Restarts Always-On Timer (watchdog timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_watchdog_get_count (const dif_aon_timer_t *aon, uint32_t *count)
 Retrieves Always-On Timer (watchdog timer) tick count. More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_watchdog_pet (const dif_aon_timer_t *aon)
 Clears Always-On Timer (watchdog timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_lock (const dif_aon_timer_t *aon)
 Locks Always-On Timer (watchdog timer). More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_watchdog_is_locked (const dif_aon_timer_t *aon, bool *is_locked)
 Checks whether this Always-On Timer (watchdog timer) is locked. More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_irq_is_pending (const dif_aon_timer_t *aon, dif_aon_timer_irq_t irq, bool *is_pending)
 Returns whether a particular interrupt is currently pending. More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_irq_acknowledge (const dif_aon_timer_t *aon, dif_aon_timer_irq_t irq)
 Acknowledges a particular interrupt. More...
 
DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_irq_force (const dif_aon_timer_t *aon, dif_aon_timer_irq_t irq)
 Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...
 

Detailed Description

Always-On Timer Device Interface Functions

Definition in file dif_aon_timer.h.


Data Structure Documentation

◆ dif_aon_timer_params

struct dif_aon_timer_params

Hardware instantiation parameters for Always-On Timer.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 31 of file dif_aon_timer.h.

Data Fields
mmio_region_t base_addr The base address for the Always-On Timer hardware registers.

◆ dif_aon_timer

struct dif_aon_timer

A handle to Always-On Timer.

This type should be treated as opaque by users.

Definition at line 43 of file dif_aon_timer.h.

Data Fields
dif_aon_timer_params_t params

Typedef Documentation

◆ dif_aon_timer_params_t

Hardware instantiation parameters for Always-On Timer.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_aon_timer_t

A handle to Always-On Timer.

This type should be treated as opaque by users.

Enumeration Type Documentation

◆ dif_aon_timer_irq

An Always-On Timer interrupt request type.

Enumerator
kDifAonTimerIrqWakeupThreshold 

Wake-up timer has expired.

kDifAonTimerIrqWatchdogBarkThreshold 

Watchdog timer "Bark" threshold has expired.

Definition at line 97 of file dif_aon_timer.h.

◆ dif_aon_timer_result

The result of a Always-On Timer operation.

Enumerator
kDifAonTimerOk 

Indicates that the operation succeeded.

kDifAonTimerError 

Indicates some unspecified failure.

kDifAonTimerBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 50 of file dif_aon_timer.h.

◆ dif_aon_timer_watchdog_result

The result of a Always-On Timer (watchdog timer) operation.

Enumerator
kDifAonTimerWatchdogOk 

Indicates that the operation succeeded.

kDifAonTimerWatchdogError 

Indicates some unspecified failure.

kDifAonTimerWatchdogBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAonTimerWatchdogLocked 

Indicates that this operation has been locked out, and can never succeed until hardware reset.

Definition at line 71 of file dif_aon_timer.h.

Function Documentation

◆ dif_aon_timer_init()

Creates a new handle for Always-On Timer.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]aonOut param for the initialised handle.
Returns
The result of the operation.

Definition at line 83 of file dif_aon_timer.c.

◆ dif_aon_timer_irq_acknowledge()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_irq_acknowledge ( const dif_aon_timer_t aon,
dif_aon_timer_irq_t  irq 
)

Acknowledges a particular interrupt.

This operation indicates to the hardware that the interrupt has been successfully serviced.

Parameters
aonAn Always-On Timer handle.
irqAn interrupt type.
Returns
The result of the operation.

Definition at line 282 of file dif_aon_timer.c.

◆ dif_aon_timer_irq_force()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_irq_force ( const dif_aon_timer_t aon,
dif_aon_timer_irq_t  irq 
)

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters
aonAn Always-On Timer handle.
irqAn interrupt type.
Returns
The result of the operation.

Definition at line 301 of file dif_aon_timer.c.

◆ dif_aon_timer_irq_is_pending()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_irq_is_pending ( const dif_aon_timer_t aon,
dif_aon_timer_irq_t  irq,
bool *  is_pending 
)

Returns whether a particular interrupt is currently pending.

Parameters
aonAn Always-On Timer handle.
irqAn interrupt type.
[out]is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 263 of file dif_aon_timer.c.

◆ dif_aon_timer_wakeup_get_count()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_get_count ( const dif_aon_timer_t aon,
uint32_t *  count 
)

Retrieves Always-On Timer (wake-up timer) tick count.

Parameters
aonAn Always-On Timer handle.
[out]countCurrent timer tick count.
Returns
The result of the operation.

Definition at line 139 of file dif_aon_timer.c.

◆ dif_aon_timer_wakeup_restart()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_restart ( const dif_aon_timer_t aon)

Restarts Always-On Timer (wake-up timer).

Clears the counter and restarts the timer using the existing configuration.

Parameters
aonAn Always-On Timer handle.
Returns
The result of the operation.

Definition at line 127 of file dif_aon_timer.c.

◆ dif_aon_timer_wakeup_start()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_start ( const dif_aon_timer_t aon,
uint32_t  threshold,
uint32_t  prescaler 
)

Starts Always-On Timer (wake-up timer).

This operation starts the wake-up timer with the provided configuration. Note that the timer is stopped and counter cleared, before the timer is started with the new configuration.

Parameters
aonAn Always-On Timer handle.
thresholdThreshold in ticks.
prescaler12 bit pre-scaler to enable very long timeouts (one tick every N + 1 clock cycles, where N is the pre-scaler value).
Returns
The result of the operation.

Definition at line 94 of file dif_aon_timer.c.

◆ dif_aon_timer_wakeup_stop()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_wakeup_stop ( const dif_aon_timer_t aon)

Stops Always-On Timer (wake-up timer).

Stops the timer. Configuration is not touched, and can be restarted via dif_aon_timer_wakeup_restart.

Parameters
aonAn Always-On Timer handle.
Returns
The result of the operation.

Definition at line 117 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_get_count()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_watchdog_get_count ( const dif_aon_timer_t aon,
uint32_t *  count 
)

Retrieves Always-On Timer (watchdog timer) tick count.

Parameters
aonAn Always-On Timer handle.
[out]countCurrent timer tick count.
Returns
The result of the operation.

Definition at line 219 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_is_locked()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_watchdog_is_locked ( const dif_aon_timer_t aon,
bool *  is_locked 
)

Checks whether this Always-On Timer (watchdog timer) is locked.

Parameters
aonAn Always-On Timer handle.
[out]is_lockedOut-param for the locked state.
Returns
The result of the operation.

Definition at line 252 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_lock()

DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_lock ( const dif_aon_timer_t aon)

Locks Always-On Timer (watchdog timer).

The watchdog configuration will be locked until the next reset. This means that this timer cannot be stopped, restarted or reconfigured, however the count can be cleared via dif_aon_timer_watchdog_pet.

Parameters
aonAn Always-On Timer handle.
Returns
The result of the operation.

Definition at line 241 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_pet()

DIF_WARN_UNUSED_RESULT dif_aon_timer_result_t dif_aon_timer_watchdog_pet ( const dif_aon_timer_t aon)

Clears Always-On Timer (watchdog timer).

This function must be called periodically to satisfy "Bite" and "Bark" thresholds. The semantics of this function are similar to dif_aon_timer_watchdog_restart, however it does not write to the control register, and is guaranteed to succeed even when the watchdog is locked.

Parameters
aonAn Always-On Timer handle.
Returns
The result of the operation.

Definition at line 231 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_restart()

DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_restart ( const dif_aon_timer_t aon)

Restarts Always-On Timer (watchdog timer).

Clears the counter and restarts the timer using the existing configuration.

Parameters
aonAn Always-On Timer handle.
Returns
The result of the operation.

Definition at line 203 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_start()

DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_start ( const dif_aon_timer_t aon,
uint32_t  bark_threshold,
uint32_t  bite_threshold,
bool  pause_in_sleep,
bool  lock 
)

Starts Always-On Timer (watchdog timer).

This operation starts the watchdog timer with the provided configuration. Note that the timer is stopped and counter cleared, before the timer is started with the new configuration.

Parameters
aonAn Always-On Timer handle.
bark_threshold"Bark" threshold in ticks.
bite_threshold"Bite" threshold in ticks.
pause_in_sleepWatchdog is paused when device is in one of the low power modes.
lockLock access to watchdog configuration registers.
Returns
The result of the operation.

Definition at line 151 of file dif_aon_timer.c.

◆ dif_aon_timer_watchdog_stop()

DIF_WARN_UNUSED_RESULT dif_aon_timer_watchdog_result_t dif_aon_timer_watchdog_stop ( const dif_aon_timer_t aon)

Stops Always-On Timer (watchdog timer).

Stops the timer. Configuration is not touched, and can be restarted via dif_aon_timer_watchdog_restart.

Parameters
aonAn Always-On Timer handle.
Returns
The result of the operation.

Definition at line 188 of file dif_aon_timer.c.