Mistake on this page?
Report an issue in GitHub or email us
ticker_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2015 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_TICKER_API_H
21 #define MBED_TICKER_API_H
22 
23 #include <stdint.h>
24 #include <stdbool.h>
25 #include "device.h"
26 
27 /**
28  * Legacy format representing a timestamp in us.
29  * Given it is modeled as a 32 bit integer, this type can represent timestamp
30  * up to 4294 seconds (71 minutes).
31  * Prefer using us_timestamp_t which store timestamp as 64 bits integer.
32  */
33 typedef uint32_t timestamp_t;
34 
35 /**
36  * A us timestamp stored in a 64 bit integer.
37  * Can store timestamp up to 584810 years.
38  */
39 typedef uint64_t us_timestamp_t;
40 
41 /** Ticker's event structure
42  */
43 typedef struct ticker_event_s {
44  us_timestamp_t timestamp; /**< Event's timestamp */
45  uint32_t id; /**< TimerEvent object */
46  struct ticker_event_s *next; /**< Next event in the queue */
48 
49 typedef void (*ticker_event_handler)(uint32_t id);
50 
51 /** Information about the ticker implementation
52  */
53 typedef struct {
54  uint32_t frequency; /**< Frequency in Hz this ticker runs at */
55  uint32_t bits; /**< Number of bits this ticker supports */
57 
58 
59 /** Ticker's interface structure - required API for a ticker
60  */
61 typedef struct {
62  void (*init)(void); /**< Init function */
63  uint32_t (*read)(void); /**< Read function */
64  void (*disable_interrupt)(void); /**< Disable interrupt function */
65  void (*clear_interrupt)(void); /**< Clear interrupt function */
66  void (*set_interrupt)(timestamp_t timestamp); /**< Set interrupt function */
67  void (*fire_interrupt)(void); /**< Fire interrupt right-away */
68  void (*free)(void); /**< Disable function */
69  const ticker_info_t *(*get_info)(void); /**< Return info about this ticker's implementation */
70  bool runs_in_deep_sleep; /**< Whether ticker operates in deep sleep */
72 
73 /** Ticker's event queue structure
74  */
75 typedef struct {
76  ticker_event_handler event_handler; /**< Event handler */
77  ticker_event_t *head; /**< A pointer to head */
78  uint32_t frequency; /**< Frequency of the timer in Hz */
79  uint32_t bitmask; /**< Mask to be applied to time values read */
80  uint32_t max_delta; /**< Largest delta in ticks that can be used when scheduling */
81  uint64_t max_delta_us; /**< Largest delta in us that can be used when scheduling */
82  uint32_t tick_last_read; /**< Last tick read */
83  uint64_t tick_remainder; /**< Ticks that have not been added to base_time */
84  us_timestamp_t present_time; /**< Store the timestamp used for present time */
85  bool initialized; /**< Indicate if the instance is initialized */
86  bool dispatching; /**< The function ticker_irq_handler is dispatching */
87  bool suspended; /**< Indicate if the instance is suspended */
88  uint8_t frequency_shifts; /**< If frequency is a value of 2^n, this is n, otherwise 0 */
90 
91 /** Ticker's data structure
92  */
93 typedef struct {
94  const ticker_interface_t *interface; /**< Ticker's interface */
95  ticker_event_queue_t *queue; /**< Ticker's event queue */
97 
98 #ifdef __cplusplus
99 extern "C" {
100 #endif
101 
102 /**
103  * \defgroup hal_ticker Ticker HAL functions
104  * @{
105  */
106 
107 /** Initialize a ticker and set the event handler
108  *
109  * @param ticker The ticker object.
110  * @param handler A handler to be set
111  */
112 void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler);
113 
114 /** IRQ handler that goes through the events to trigger overdue events.
115  *
116  * @param ticker The ticker object.
117  */
118 void ticker_irq_handler(const ticker_data_t *const ticker);
119 
120 /** Remove an event from the queue
121  *
122  * @param ticker The ticker object.
123  * @param obj The event object to be removed from the queue
124  */
125 void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj);
126 
127 /** Insert an event to the queue
128  *
129  * The event will be executed in timestamp - ticker_read().
130  *
131  * @warning This function does not consider timestamp in the past. If an event
132  * is inserted with a timestamp less than the current timestamp then the event
133  * will be executed in timestamp - ticker_read() us.
134  * The internal counter wrap very quickly it is hard to decide weither an
135  * event is in the past or in 1 hour.
136  *
137  * @note prefer the use of ticker_insert_event_us which allows registration of
138  * absolute timestamp.
139  *
140  * @param ticker The ticker object.
141  * @param obj The event object to be inserted to the queue
142  * @param timestamp The event's timestamp
143  * @param id The event object
144  */
145 void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id);
146 
147 /** Insert an event to the queue
148  *
149  * The event will be executed in timestamp - ticker_read_us() us.
150  *
151  * @note If an event is inserted with a timestamp less than the current
152  * timestamp then the event will be scheduled immediately resulting in
153  * an instant call to event handler.
154  *
155  * @param ticker The ticker object.
156  * @param obj The event object to be inserted to the queue
157  * @param timestamp The event's timestamp
158  * @param id The event object
159  */
160 void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id);
161 
162 /** Read the current (relative) ticker's timestamp
163  *
164  * @warning Return a relative timestamp because the counter wrap every 4294
165  * seconds.
166  *
167  * @param ticker The ticker object.
168  * @return The current timestamp
169  */
170 timestamp_t ticker_read(const ticker_data_t *const ticker);
171 
172 /** Read the current (absolute) ticker's timestamp
173  *
174  * @warning Return an absolute timestamp counting from the initialization of the
175  * ticker.
176  *
177  * @param ticker The ticker object.
178  * @return The current timestamp
179  */
180 us_timestamp_t ticker_read_us(const ticker_data_t *const ticker);
181 
182 /** Read the next event's timestamp
183  *
184  * @param ticker The ticker object.
185  * @param timestamp The timestamp object.
186  * @return 1 if timestamp is pending event, 0 if there's no event pending
187  */
188 int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp);
189 
190 /** Read the next event's timestamp
191  *
192  * @param ticker The ticker object.
193  * @param timestamp The timestamp object.
194  * @return 1 if timestamp is pending event, 0 if there's no event pending
195  */
196 int ticker_get_next_timestamp_us(const ticker_data_t *const ticker, us_timestamp_t *timestamp);
197 
198 /** Suspend this ticker
199  *
200  * When suspended reads will always return the same time and no
201  * events will be dispatched. When suspended the common layer
202  * will only ever call the interface function clear_interrupt()
203  * and that is only if ticker_irq_handler is called.
204  *
205  *
206  * @param ticker The ticker object.
207  */
208 void ticker_suspend(const ticker_data_t *const ticker);
209 
210 /** Resume this ticker
211  *
212  * When resumed the ticker will ignore any time that has passed
213  * and continue counting up where it left off.
214  *
215  * @param ticker The ticker object.
216  */
217 void ticker_resume(const ticker_data_t *const ticker);
218 
219 /* Private functions
220  *
221  * @cond PRIVATE
222  *
223  */
224 
225 int _ticker_match_interval_passed(timestamp_t prev_tick, timestamp_t cur_tick, timestamp_t match_tick);
226 
227 /*
228  * @endcond PRIVATE
229  *
230  */
231 
232 /**@}*/
233 
234 #ifdef __cplusplus
235 }
236 #endif
237 
238 #endif
239 
240 /** @}*/
uint64_t tick_remainder
Ticks that have not been added to base_time.
Definition: ticker_api.h:83
void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id)
Insert an event to the queue.
uint32_t tick_last_read
Last tick read.
Definition: ticker_api.h:82
void ticker_resume(const ticker_data_t *const ticker)
Resume this ticker.
Information about the ticker implementation.
Definition: ticker_api.h:53
uint32_t id
TimerEvent object.
Definition: ticker_api.h:45
Ticker&#39;s interface structure - required API for a ticker.
Definition: ticker_api.h:61
ticker_event_t * head
A pointer to head.
Definition: ticker_api.h:77
ticker_event_queue_t * queue
Ticker&#39;s event queue.
Definition: ticker_api.h:95
uint32_t max_delta
Largest delta in ticks that can be used when scheduling.
Definition: ticker_api.h:80
bool runs_in_deep_sleep
Whether ticker operates in deep sleep.
Definition: ticker_api.h:70
int ticker_get_next_timestamp_us(const ticker_data_t *const ticker, us_timestamp_t *timestamp)
Read the next event&#39;s timestamp.
uint64_t us_timestamp_t
A us timestamp stored in a 64 bit integer.
Definition: ticker_api.h:39
us_timestamp_t timestamp
Event&#39;s timestamp.
Definition: ticker_api.h:44
struct ticker_event_s ticker_event_t
Ticker&#39;s event structure.
Ticker&#39;s data structure.
Definition: ticker_api.h:93
uint32_t frequency
Frequency in Hz this ticker runs at.
Definition: ticker_api.h:54
uint32_t frequency
Frequency of the timer in Hz.
Definition: ticker_api.h:78
struct ticker_event_s * next
Next event in the queue.
Definition: ticker_api.h:46
Ticker&#39;s event queue structure.
Definition: ticker_api.h:75
us_timestamp_t present_time
Store the timestamp used for present time.
Definition: ticker_api.h:84
uint8_t frequency_shifts
If frequency is a value of 2^n, this is n, otherwise 0.
Definition: ticker_api.h:88
Ticker&#39;s event structure.
Definition: ticker_api.h:43
uint32_t bitmask
Mask to be applied to time values read.
Definition: ticker_api.h:79
uint32_t bits
Number of bits this ticker supports.
Definition: ticker_api.h:55
timestamp_t ticker_read(const ticker_data_t *const ticker)
Read the current (relative) ticker&#39;s timestamp.
const ticker_interface_t * interface
Ticker&#39;s interface.
Definition: ticker_api.h:94
void ticker_irq_handler(const ticker_data_t *const ticker)
IRQ handler that goes through the events to trigger overdue events.
bool dispatching
The function ticker_irq_handler is dispatching.
Definition: ticker_api.h:86
us_timestamp_t ticker_read_us(const ticker_data_t *const ticker)
Read the current (absolute) ticker&#39;s timestamp.
int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp)
Read the next event&#39;s timestamp.
void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id)
Insert an event to the queue.
bool initialized
Indicate if the instance is initialized.
Definition: ticker_api.h:85
uint32_t timestamp_t
Legacy format representing a timestamp in us.
Definition: ticker_api.h:33
bool suspended
Indicate if the instance is suspended.
Definition: ticker_api.h:87
void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj)
Remove an event from the queue.
ticker_event_handler event_handler
Event handler.
Definition: ticker_api.h:76
void ticker_suspend(const ticker_data_t *const ticker)
Suspend this ticker.
uint64_t max_delta_us
Largest delta in us that can be used when scheduling.
Definition: ticker_api.h:81
void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler)
Initialize a ticker and set the event handler.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.