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  * @{
53  */
54 
55 /**
56  * \defgroup hal_lp_ticker_tests Low Power Ticker tests
57  * Tests to validate the proper implementation of the low power ticker
58  *
59  * To run the low power ticker hal tests use the command:
60  *
61  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-lp_ticker*
62  *
63  */
64 
65 typedef void (*ticker_irq_handler_type)(const ticker_data_t *const);
66 
67 /** Set low power ticker IRQ handler
68  *
69  * @param ticker_irq_handler IRQ handler to be connected
70  *
71  * @return previous ticker IRQ handler
72  *
73  * @note by default IRQ handler is set to ::ticker_irq_handler
74  * @note this function is primarily for testing purposes and it's not required part of HAL implementation
75  *
76  */
77 ticker_irq_handler_type set_lp_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler);
78 
79 /** Get low power ticker's data
80  *
81  * @return The low power ticker data
82  */
83 const ticker_data_t *get_lp_ticker_data(void);
84 
85 /** The wrapper for ticker_irq_handler, to pass lp ticker's data
86  *
87  */
88 void lp_ticker_irq_handler(void);
89 
90 /* HAL lp ticker */
91 
92 /** Initialize the low power ticker
93  *
94  * Initialize or re-initialize the ticker. This resets all the
95  * clocking and prescaler registers, along with disabling
96  * the compare interrupt.
97  *
98  * Pseudo Code:
99  * @code
100  * void lp_ticker_init()
101  * {
102  * // Enable clock gate so processor can read LPTMR registers
103  * POWER_CTRL |= POWER_CTRL_LPTMR_Msk;
104  *
105  * // Disable the timer and ensure it is powered down
106  * LPTMR_CTRL &= ~(LPTMR_CTRL_ENABLE_Msk | LPTMR_CTRL_COMPARE_ENABLE_Msk);
107  *
108  * // Configure divisors - no division necessary
109  * LPTMR_PRESCALE = 0;
110  * LPTMR_CTRL |= LPTMR_CTRL_ENABLE_Msk;
111  *
112  * // Install the interrupt handler
113  * NVIC_SetVector(LPTMR_IRQn, (uint32_t)lp_ticker_irq_handler);
114  * NVIC_EnableIRQ(LPTMR_IRQn);
115  * }
116  * @endcode
117  */
118 void lp_ticker_init(void);
119 
120 /** Deinitialize the lower power ticker
121  *
122  * Powerdown the lp ticker in preparation for sleep, powerdown, or reset.
123  *
124  * After calling this function no other ticker functions should be called except
125  * lp_ticker_init(). Calling any function other than init after freeing is
126  * undefined.
127  *
128  * @note This function stops the ticker from counting.
129  */
130 void lp_ticker_free(void);
131 
132 /** Read the current tick
133  *
134  * If no rollover has occurred, the seconds passed since lp_ticker_init()
135  * was called can be found by dividing the ticks returned by this function
136  * by the frequency returned by ::lp_ticker_get_info.
137  *
138  * @return The current timer's counter value in ticks
139  *
140  * Pseudo Code:
141  * @code
142  * uint32_t lp_ticker_read()
143  * {
144  * uint16_t count;
145  * uint16_t last_count;
146  *
147  * // Loop until the same tick is read twice since this
148  * // is ripple counter on a different clock domain.
149  * count = LPTMR_COUNT;
150  * do {
151  * last_count = count;
152  * count = LPTMR_COUNT;
153  * } while (last_count != count);
154  *
155  * return count;
156  * }
157  * @endcode
158  */
159 uint32_t lp_ticker_read(void);
160 
161 /** Set interrupt for specified timestamp
162  *
163  * @param timestamp The time in ticks to be set
164  *
165  * @note no special handling needs to be done for times in the past
166  * as the common timer code will detect this and call
167  * lp_ticker_fire_interrupt() if this is the case
168  *
169  * @note calling this function with timestamp of more than the supported
170  * number of bits returned by ::lp_ticker_get_info results in undefined
171  * behavior.
172  *
173  * Pseudo Code:
174  * @code
175  * void lp_ticker_set_interrupt(timestamp_t timestamp)
176  * {
177  * LPTMR_COMPARE = timestamp;
178  * LPTMR_CTRL |= LPTMR_CTRL_COMPARE_ENABLE_Msk;
179  * }
180  * @endcode
181  */
182 void lp_ticker_set_interrupt(timestamp_t timestamp);
183 
184 /** Disable low power ticker interrupt
185  *
186  * Pseudo Code:
187  * @code
188  * void lp_ticker_disable_interrupt(void)
189  * {
190  * // Disable the compare interrupt
191  * LPTMR_CTRL &= ~LPTMR_CTRL_COMPARE_ENABLE_Msk;
192  * }
193  * @endcode
194  */
195 void lp_ticker_disable_interrupt(void);
196 
197 /** Clear the low power ticker interrupt
198  *
199  * Pseudo Code:
200  * @code
201  * void lp_ticker_clear_interrupt(void)
202  * {
203  * // Write to the ICR (interrupt clear register) of the LPTMR
204  * LPTMR_ICR = LPTMR_ICR_COMPARE_Msk;
205  * }
206  * @endcode
207  */
208 void lp_ticker_clear_interrupt(void);
209 
210 /** Set pending interrupt that should be fired right away.
211  *
212  * Pseudo Code:
213  * @code
214  * void lp_ticker_fire_interrupt(void)
215  * {
216  * NVIC_SetPendingIRQ(LPTMR_IRQn);
217  * }
218  * @endcode
219  */
220 void lp_ticker_fire_interrupt(void);
221 
222 /** Get frequency and counter bits of this ticker.
223  *
224  * Pseudo Code:
225  * @code
226  * const ticker_info_t* lp_ticker_get_info()
227  * {
228  * static const ticker_info_t info = {
229  * 32768, // 32KHz
230  * 16 // 16 bit counter
231  * };
232  * return &info;
233  * }
234  * @endcode
235  */
236 const ticker_info_t *lp_ticker_get_info(void);
237 
238 /**@}*/
239 
240 #ifdef __cplusplus
241 }
242 #endif
243 
244 #endif
245 
246 #endif
247 
248 /** @}*/
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:93
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.