Mistake on this page?
Report an issue in GitHub or email us
LowPowerTickerWrapper.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2018-2019 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_LOW_POWER_TICKER_WRAPPER_H
21 #define MBED_LOW_POWER_TICKER_WRAPPER_H
22 
23 #include "device.h"
24 
25 #include "hal/ticker_api.h"
26 #include "hal/us_ticker_api.h"
27 #include "drivers/Timeout.h"
28 
29 #include "platform/mbed_chrono.h"
30 #include "platform/mbed_critical.h"
31 
32 
34 public:
35 
36 
37  /**
38  * Create a new wrapped low power ticker object
39  *
40  * @param data Low power ticker data to wrap
41  * @param interface new ticker interface functions
42  * @param min_cycles_between_writes The number of whole low power clock periods
43  * which must complete before subsequent calls to set_interrupt
44  * @param min_cycles_until_match The minimum number of whole low power clock periods
45  * from the current time for which the match timestamp passed to set_interrupt is
46  * guaranteed to fire.
47  *
48  * N = min_cycles_between_writes
49  *
50  * 0 1 N - 1 N N + 1 N + 2 N + 3
51  * |-------|------...------|-------|-------|-------|-------|
52  * ^ ^
53  * | |
54  * set_interrupt Next set_interrupt allowed
55  *
56  * N = min_cycles_until_match
57  *
58  * 0 1 N - 1 N N + 1 N + 2 N + 3
59  * |-------|------...------|-------|-------|-------|-------|
60  * ^ ^
61  * | |
62  * set_interrupt Earliest match timestamp allowed
63  *
64  *
65  */
66 
67  LowPowerTickerWrapper(const ticker_data_t *data, const ticker_interface_t *interface, uint32_t min_cycles_between_writes, uint32_t min_cycles_until_match);
68 
69  /**
70  * Interrupt handler called by the underlying driver/hardware
71  *
72  * @param handler The callback which would normally be called by the underlying driver/hardware
73  */
74  void irq_handler(ticker_irq_handler_type handler);
75 
76  /**
77  * Suspend wrapper operation and pass through interrupts.
78  *
79  * This stops to wrapper layer from using the microsecond ticker.
80  * This should be called before using the low power ticker APIs directly.
81  *
82  * @warning: Make sure to suspend the LP ticker first (call ticker_suspend()),
83  * otherwise the behavior is undefined.
84  */
85  void suspend();
86 
87  /**
88  * Resume wrapper operation and filter interrupts normally
89  */
90  void resume();
91 
92  /**
93  * Check if a Timeout object is being used
94  *
95  * @return true if Timeout is used for scheduling false otherwise
96  */
97  bool timeout_pending();
98 
99  /*
100  * Implementation of ticker_init
101  */
102  void init();
103 
104  /*
105  * Implementation of free
106  */
107  void free();
108 
109  /*
110  * Implementation of read
111  */
112  uint32_t read();
113 
114  /*
115  * Implementation of set_interrupt
116  */
117  void set_interrupt(timestamp_t timestamp);
118 
119  /*
120  * Implementation of disable_interrupt
121  */
122  void disable_interrupt();
123 
124  /*
125  * Implementation of clear_interrupt
126  */
127  void clear_interrupt();
128 
129  /*
130  * Implementation of fire_interrupt
131  */
132  void fire_interrupt();
133 
134  /*
135  * Implementation of get_info
136  */
137  const ticker_info_t *get_info();
138 
139  ticker_data_t data;
140 
141 private:
142  mbed::Timeout _timeout;
143  const ticker_interface_t *const _intf;
144 
145  /*
146  * The number of low power clock cycles which must pass between subsequent
147  * calls to intf->set_interrupt
148  */
149  const uint32_t _min_count_between_writes;
150 
151  /*
152  * The minimum number of low power clock cycles in the future that
153  * a match value can be set to and still fire
154  */
155  const uint32_t _min_count_until_match;
156 
157  /*
158  * Flag to indicate if the timer is suspended
159  */
160  bool _suspended;
161 
162  /*
163  * _cur_match_time is valid and Timeout is scheduled to fire
164  */
165  bool _pending_timeout;
166 
167  /*
168  * set_interrupt has been called and _cur_match_time is valid
169  */
170  bool _pending_match;
171 
172  /*
173  * The function LowPowerTickerWrapper::fire_interrupt has been called
174  * and an interrupt is expected.
175  */
176  bool _pending_fire_now;
177 
178  /*
179  * It is safe to call intf->set_interrupt
180  */
181  bool _set_interrupt_allowed;
182 
183  /*
184  * Last value written by LowPowerTickerWrapper::set_interrupt
185  */
186  timestamp_t _cur_match_time;
187 
188  /*
189  * Time of last call to LowPowerTickerWrapper::set_interrupt
190  */
191  uint32_t _last_set_interrupt;
192 
193  /*
194  * Time of last call to intf->set_interrupt
195  */
196  uint32_t _last_actual_set_interrupt;
197 
198  /*
199  * Mask of valid bits from intf->read()
200  */
201  uint32_t _mask;
202 
203  /*
204  * Microsecond per low power tick (rounded up)
205  */
206  uint32_t _us_per_tick;
207 
208 
209  void _reset();
210 
211  /**
212  * Set the low power ticker match time when hardware is ready
213  *
214  * This event is scheduled to set the lp timer after the previous write
215  * has taken effect and it is safe to write a new value without blocking.
216  * If the time has already passed then this function fires and interrupt
217  * immediately.
218  */
219  void _timeout_handler();
220 
221  /*
222  * Check match time has passed
223  */
224  bool _match_check(timestamp_t current);
225 
226  /*
227  * Convert low power ticks to approximate microseconds
228  *
229  * This value is always larger or equal to exact value.
230  */
231  mbed::chrono::microseconds_u32 _lp_ticks_to_us(uint32_t);
232 
233  /*
234  * Schedule a match interrupt to fire at the correct time
235  *
236  * @param current The current low power ticker time
237  */
238  void _schedule_match(timestamp_t current);
239 
240 };
241 
242 #endif
243 
244 /** @}*/
245 
246 
void irq_handler(ticker_irq_handler_type handler)
Interrupt handler called by the underlying driver/hardware.
Information about the ticker implementation.
Definition: ticker_api.h:53
Ticker's interface structure - required API for a ticker.
Definition: ticker_api.h:61
Ticker's data structure.
Definition: ticker_api.h:93
LowPowerTickerWrapper(const ticker_data_t *data, const ticker_interface_t *interface, uint32_t min_cycles_between_writes, uint32_t min_cycles_until_match)
Create a new wrapped low power ticker object.
void suspend()
Suspend wrapper operation and pass through interrupts.
uint32_t timestamp_t
Legacy format representing a timestamp in us.
Definition: ticker_api.h:33
void resume()
Resume wrapper operation and filter interrupts normally.
bool timeout_pending()
Check if a Timeout object is being used.
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.