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 26 /** 27 * Legacy format representing a timestamp in us. 28 * Given it is modeled as a 32 bit integer, this type can represent timestamp 29 * up to 4294 seconds (71 minutes). 30 * Prefer using us_timestamp_t which store timestamp as 64 bits integer. 31 */ 32 typedef uint32_t timestamp_t; 33 34 /** 35 * A us timestamp stored in a 64 bit integer. 36 * Can store timestamp up to 584810 years. 37 */ 38 typedef uint64_t us_timestamp_t; 39 40 /** Ticker's event structure 41 */ 42 typedef struct ticker_event_s { 43 us_timestamp_t timestamp; /**< Event's timestamp */ 44 uint32_t id; /**< TimerEvent object */ 45 struct ticker_event_s *next; /**< Next event in the queue */ 46 } ticker_event_t; 47 48 typedef void (*ticker_event_handler)(uint32_t id); 49 50 /** Information about the ticker implementation 51 */ 52 typedef struct { 53 uint32_t frequency; /**< Frequency in Hz this ticker runs at */ 54 uint32_t bits; /**< Number of bits this ticker supports */ 55 } ticker_info_t; 56 57 58 /** Ticker's interface structure - required API for a ticker 59 */ 60 typedef struct { 61 void (*init)(void); /**< Init function */ 62 uint32_t (*read)(void); /**< Read function */ 63 void (*disable_interrupt)(void); /**< Disable interrupt function */ 64 void (*clear_interrupt)(void); /**< Clear interrupt function */ 65 void (*set_interrupt)(timestamp_t timestamp); /**< Set interrupt function */ 66 void (*fire_interrupt)(void); /**< Fire interrupt right-away */ 67 void (*free)(void); /**< Disable function */ 68 const ticker_info_t *(*get_info)(void); /**< Return info about this ticker's implementation */ 69 bool runs_in_deep_sleep; /**< Whether ticker operates in deep sleep */ 70 } ticker_interface_t; 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 */ 88 } ticker_event_queue_t; 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 */ 95 } ticker_data_t; 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 /** @}*/ 232