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 */
71 
72 /** Ticker's event queue structure
73  */
74 typedef struct {
75  ticker_event_handler event_handler; /**< Event handler */
76  ticker_event_t *head; /**< A pointer to head */
77  uint32_t frequency; /**< Frequency of the timer in Hz */
78  uint32_t bitmask; /**< Mask to be applied to time values read */
79  uint32_t max_delta; /**< Largest delta in ticks that can be used when scheduling */
80  uint64_t max_delta_us; /**< Largest delta in us that can be used when scheduling */
81  uint32_t tick_last_read; /**< Last tick read */
82  uint64_t tick_remainder; /**< Ticks that have not been added to base_time */
83  us_timestamp_t present_time; /**< Store the timestamp used for present time */
84  bool initialized; /**< Indicate if the instance is initialized */
85  bool dispatching; /**< The function ticker_irq_handler is dispatching */
86  bool suspended; /**< Indicate if the instance is suspended */
87  uint8_t frequency_shifts; /**< If frequency is a value of 2^n, this is n, otherwise 0 */
89 
90 /** Ticker's data structure
91  */
92 typedef struct {
93  const ticker_interface_t *interface; /**< Ticker's interface */
94  ticker_event_queue_t *queue; /**< Ticker's event queue */
96 
97 #ifdef __cplusplus
98 extern "C" {
99 #endif
100 
101 /**
102  * \defgroup hal_ticker Ticker HAL functions
103  * @{
104  */
105 
106 /** Initialize a ticker and set the event handler
107  *
108  * @param ticker The ticker object.
109  * @param handler A handler to be set
110  */
111 void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler);
112 
113 /** IRQ handler that goes through the events to trigger overdue events.
114  *
115  * @param ticker The ticker object.
116  */
117 void ticker_irq_handler(const ticker_data_t *const ticker);
118 
119 /** Remove an event from the queue
120  *
121  * @param ticker The ticker object.
122  * @param obj The event object to be removed from the queue
123  */
124 void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj);
125 
126 /** Insert an event to the queue
127  *
128  * The event will be executed in timestamp - ticker_read().
129  *
130  * @warning This function does not consider timestamp in the past. If an event
131  * is inserted with a timestamp less than the current timestamp then the event
132  * will be executed in timestamp - ticker_read() us.
133  * The internal counter wrap very quickly it is hard to decide weither an
134  * event is in the past or in 1 hour.
135  *
136  * @note prefer the use of ticker_insert_event_us which allows registration of
137  * absolute timestamp.
138  *
139  * @param ticker The ticker object.
140  * @param obj The event object to be inserted to the queue
141  * @param timestamp The event's timestamp
142  * @param id The event object
143  */
144 void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id);
145 
146 /** Insert an event to the queue
147  *
148  * The event will be executed in timestamp - ticker_read_us() us.
149  *
150  * @note If an event is inserted with a timestamp less than the current
151  * timestamp then the event will be scheduled immediately resulting in
152  * an instant call to event handler.
153  *
154  * @param ticker The ticker object.
155  * @param obj The event object to be inserted to the queue
156  * @param timestamp The event's timestamp
157  * @param id The event object
158  */
159 void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id);
160 
161 /** Read the current (relative) ticker's timestamp
162  *
163  * @warning Return a relative timestamp because the counter wrap every 4294
164  * seconds.
165  *
166  * @param ticker The ticker object.
167  * @return The current timestamp
168  */
169 timestamp_t ticker_read(const ticker_data_t *const ticker);
170 
171 /** Read the current (absolute) ticker's timestamp
172  *
173  * @warning Return an absolute timestamp counting from the initialization of the
174  * ticker.
175  *
176  * @param ticker The ticker object.
177  * @return The current timestamp
178  */
179 us_timestamp_t ticker_read_us(const ticker_data_t *const ticker);
180 
181 /** Read the next event's timestamp
182  *
183  * @param ticker The ticker object.
184  * @param timestamp The timestamp object.
185  * @return 1 if timestamp is pending event, 0 if there's no event pending
186  */
187 int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp);
188 
189 /** Suspend this ticker
190  *
191  * When suspended reads will always return the same time and no
192  * events will be dispatched. When suspended the common layer
193  * will only ever call the interface function clear_interrupt()
194  * and that is only if ticker_irq_handler is called.
195  *
196  *
197  * @param ticker The ticker object.
198  */
199 void ticker_suspend(const ticker_data_t *const ticker);
200 
201 /** Resume this ticker
202  *
203  * When resumed the ticker will ignore any time that has passed
204  * and continue counting up where it left off.
205  *
206  * @param ticker The ticker object.
207  */
208 void ticker_resume(const ticker_data_t *const ticker);
209 
210 /* Private functions
211  *
212  * @cond PRIVATE
213  *
214  */
215 
216 int _ticker_match_interval_passed(timestamp_t prev_tick, timestamp_t cur_tick, timestamp_t match_tick);
217 
218 /*
219  * @endcond PRIVATE
220  *
221  */
222 
223 /**@}*/
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 
229 #endif
230 
231 /** @}*/
uint64_t tick_remainder
Ticks that have not been added to base_time.
Definition: ticker_api.h:82
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:81
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:76
ticker_event_queue_t * queue
Ticker&#39;s event queue.
Definition: ticker_api.h:94
uint32_t max_delta
Largest delta in ticks that can be used when scheduling.
Definition: ticker_api.h:79
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:92
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:77
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:74
us_timestamp_t present_time
Store the timestamp used for present time.
Definition: ticker_api.h:83
uint8_t frequency_shifts
If frequency is a value of 2^n, this is n, otherwise 0.
Definition: ticker_api.h:87
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:78
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:93
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:85
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:84
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:86
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:75
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:80
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.