Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
lp_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_LPTICKER_API_H
21 #define MBED_LPTICKER_API_H
22 
23 #include "device.h"
24 
25 #if DEVICE_LPTICKER
26 
27 #include "hal/ticker_api.h"
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /**
34  * \defgroup hal_lp_ticker Low Power Ticker
35  * Low level interface to the low power ticker of a target
36  *
37  * # Defined behavior
38  * * Has a reported frequency between 4KHz and 64KHz - verified by ::lp_ticker_info_test
39  * * Has a counter that is at least 12 bits wide - verified by ::lp_ticker_info_test
40  * * Continues operating in deep sleep mode - verified by ::lp_ticker_deepsleep_test
41  * * All behavior defined by the @ref hal_ticker_shared "ticker specification"
42  *
43  * # Undefined behavior
44  * * See the @ref hal_ticker_shared "ticker specification"
45  * * Calling any function other than lp_ticker_init after calling lp_ticker_free
46  *
47  * # Potential bugs
48  * * Glitches due to ripple counter - Verified by ::lp_ticker_glitch_test
49  *
50  * @see hal_lp_ticker_tests
51  *
52  * # Compile-time optimization macros
53  *
54  * To permit compile-time optimization, the following macros can be defined by a target's device.h:
55  *
56  * LP_TICKER_PERIOD_NUM, LP_TICKER_PERIOD_DEN: These denote the ratio (numerator, denominator)
57  * of the ticker period to a microsecond. For example, a 64kHz ticker would have NUM = 125, DEN = 8;
58  * a 4kHz ticker would have NUM = 250, DEN = 1; a 32.768kHz ticker would have NUM = 15625, DEN = 512.
59  * Both numerator and denominator must be 32 bits or less. They do not need to be fully simplified,
60  * so 32.768kHz could also be NUM = 1000000, DEN = 32768, but more simplification may be a minor
61  * speed optimisation, as can matching numerator or denominator with US_TICKER.
62  *
63  * LP_TICKER_MASK: The value mask for the ticker - eg 0x07FFFFFF for a 27-bit ticker.
64  *
65  * If any are defined, all 3 must be defined, and the macros are checked for consistency with
66  * lp_ticker_get_info by test ::lp_ticker_info_test.
67 
68  * @{
69  */
70 
71 /**
72  * \defgroup hal_lp_ticker_tests Low Power Ticker tests
73  * Tests to validate the proper implementation of the low power ticker
74  *
75  * To run the low power ticker hal tests use the command:
76  *
77  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-lp_ticker*
78  *
79  */
80 
81 typedef void (*ticker_irq_handler_type)(const ticker_data_t *const);
82 
83 /** Set low power ticker IRQ handler
84  *
85  * @param ticker_irq_handler IRQ handler to be connected
86  *
87  * @return previous ticker IRQ handler
88  *
89  * @note by default IRQ handler is set to ::ticker_irq_handler
90  * @note this function is primarily for testing purposes and it's not required part of HAL implementation
91  *
92  */
93 ticker_irq_handler_type set_lp_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler);
94 
95 /** Get low power ticker's data
96  *
97  * @return The low power ticker data
98  */
99 const ticker_data_t *get_lp_ticker_data(void);
100 
101 /** The wrapper for ticker_irq_handler, to pass lp ticker's data
102  *
103  */
104 void lp_ticker_irq_handler(void);
105 
106 /* HAL lp ticker */
107 
108 /** Initialize the low power ticker
109  *
110  * Initialize or re-initialize the ticker. This resets all the
111  * clocking and prescaler registers, along with disabling
112  * the compare interrupt.
113  *
114  * Pseudo Code:
115  * @code
116  * void lp_ticker_init()
117  * {
118  * // Enable clock gate so processor can read LPTMR registers
119  * POWER_CTRL |= POWER_CTRL_LPTMR_Msk;
120  *
121  * // Disable the timer and ensure it is powered down
122  * LPTMR_CTRL &= ~(LPTMR_CTRL_ENABLE_Msk | LPTMR_CTRL_COMPARE_ENABLE_Msk);
123  *
124  * // Configure divisors - no division necessary
125  * LPTMR_PRESCALE = 0;
126  * LPTMR_CTRL |= LPTMR_CTRL_ENABLE_Msk;
127  *
128  * // Install the interrupt handler
129  * NVIC_SetVector(LPTMR_IRQn, (uint32_t)lp_ticker_irq_handler);
130  * NVIC_EnableIRQ(LPTMR_IRQn);
131  * }
132  * @endcode
133  */
134 void lp_ticker_init(void);
135 
136 /** Deinitialize the lower power ticker
137  *
138  * Powerdown the lp ticker in preparation for sleep, powerdown, or reset.
139  *
140  * After calling this function no other ticker functions should be called except
141  * lp_ticker_init(). Calling any function other than init after freeing is
142  * undefined.
143  *
144  * @note This function stops the ticker from counting.
145  */
146 void lp_ticker_free(void);
147 
148 /** Read the current tick
149  *
150  * If no rollover has occurred, the seconds passed since lp_ticker_init()
151  * was called can be found by dividing the ticks returned by this function
152  * by the frequency returned by ::lp_ticker_get_info.
153  *
154  * @return The current timer's counter value in ticks
155  *
156  * Pseudo Code:
157  * @code
158  * uint32_t lp_ticker_read()
159  * {
160  * uint16_t count;
161  * uint16_t last_count;
162  *
163  * // Loop until the same tick is read twice since this
164  * // is ripple counter on a different clock domain.
165  * count = LPTMR_COUNT;
166  * do {
167  * last_count = count;
168  * count = LPTMR_COUNT;
169  * } while (last_count != count);
170  *
171  * return count;
172  * }
173  * @endcode
174  */
175 uint32_t lp_ticker_read(void);
176 
177 /** Set interrupt for specified timestamp
178  *
179  * @param timestamp The time in ticks to be set
180  *
181  * @note no special handling needs to be done for times in the past
182  * as the common timer code will detect this and call
183  * lp_ticker_fire_interrupt() if this is the case
184  *
185  * @note calling this function with timestamp of more than the supported
186  * number of bits returned by ::lp_ticker_get_info results in undefined
187  * behavior.
188  *
189  * Pseudo Code:
190  * @code
191  * void lp_ticker_set_interrupt(timestamp_t timestamp)
192  * {
193  * LPTMR_COMPARE = timestamp;
194  * LPTMR_CTRL |= LPTMR_CTRL_COMPARE_ENABLE_Msk;
195  * }
196  * @endcode
197  */
198 void lp_ticker_set_interrupt(timestamp_t timestamp);
199 
200 /** Disable low power ticker interrupt
201  *
202  * Pseudo Code:
203  * @code
204  * void lp_ticker_disable_interrupt(void)
205  * {
206  * // Disable the compare interrupt
207  * LPTMR_CTRL &= ~LPTMR_CTRL_COMPARE_ENABLE_Msk;
208  * }
209  * @endcode
210  */
211 void lp_ticker_disable_interrupt(void);
212 
213 /** Clear the low power ticker interrupt
214  *
215  * Pseudo Code:
216  * @code
217  * void lp_ticker_clear_interrupt(void)
218  * {
219  * // Write to the ICR (interrupt clear register) of the LPTMR
220  * LPTMR_ICR = LPTMR_ICR_COMPARE_Msk;
221  * }
222  * @endcode
223  */
224 void lp_ticker_clear_interrupt(void);
225 
226 /** Set pending interrupt that should be fired right away.
227  *
228  * Pseudo Code:
229  * @code
230  * void lp_ticker_fire_interrupt(void)
231  * {
232  * NVIC_SetPendingIRQ(LPTMR_IRQn);
233  * }
234  * @endcode
235  */
236 void lp_ticker_fire_interrupt(void);
237 
238 /** Get frequency and counter bits of this ticker.
239  *
240  * Pseudo Code:
241  * @code
242  * const ticker_info_t* lp_ticker_get_info()
243  * {
244  * static const ticker_info_t info = {
245  * 32768, // 32KHz
246  * 16 // 16 bit counter
247  * };
248  * return &info;
249  * }
250  * @endcode
251  */
252 const ticker_info_t *lp_ticker_get_info(void);
253 
254 /**@}*/
255 
256 #ifdef __cplusplus
257 }
258 #endif
259 
260 #endif
261 
262 #endif
263 
264 /** @}*/
ticker_info_t
Information about the ticker implementation.
Definition: ticker_api.h:53
lp_ticker_read
uint32_t lp_ticker_read(void)
Read the current tick.
get_lp_ticker_data
const ticker_data_t * get_lp_ticker_data(void)
Get low power ticker&#39;s data.
lp_ticker_irq_handler
void lp_ticker_irq_handler(void)
The wrapper for ticker_irq_handler, to pass lp ticker&#39;s data.
ticker_data_t
Ticker&#39;s data structure.
Definition: ticker_api.h:144
set_lp_ticker_irq_handler
ticker_irq_handler_type set_lp_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler)
Set low power ticker IRQ handler.
lp_ticker_disable_interrupt
void lp_ticker_disable_interrupt(void)
Disable low power ticker interrupt.
lp_ticker_fire_interrupt
void lp_ticker_fire_interrupt(void)
Set pending interrupt that should be fired right away.
ticker_irq_handler
void ticker_irq_handler(const ticker_data_t *const ticker)
IRQ handler that goes through the events to trigger overdue events.
lp_ticker_set_interrupt
void lp_ticker_set_interrupt(timestamp_t timestamp)
Set interrupt for specified timestamp.
lp_ticker_init
void lp_ticker_init(void)
Initialize the low power ticker.
lp_ticker_free
void lp_ticker_free(void)
Deinitialize the lower power ticker.
timestamp_t
uint32_t timestamp_t
Legacy format representing a timestamp in us.
Definition: ticker_api.h:33
lp_ticker_clear_interrupt
void lp_ticker_clear_interrupt(void)
Clear the low power ticker interrupt.
lp_ticker_get_info
const ticker_info_t * lp_ticker_get_info(void)
Get frequency and counter bits of this ticker.
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.