mbed library sources. Supersedes mbed-src.
Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more
ticker_api.h
00001 00002 /** \addtogroup hal */ 00003 /** @{*/ 00004 /* mbed Microcontroller Library 00005 * Copyright (c) 2015 ARM Limited 00006 * SPDX-License-Identifier: Apache-2.0 00007 * 00008 * Licensed under the Apache License, Version 2.0 (the "License"); 00009 * you may not use this file except in compliance with the License. 00010 * You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, software 00015 * distributed under the License is distributed on an "AS IS" BASIS, 00016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00017 * See the License for the specific language governing permissions and 00018 * limitations under the License. 00019 */ 00020 #ifndef MBED_TICKER_API_H 00021 #define MBED_TICKER_API_H 00022 00023 #include <stdint.h> 00024 #include <stdbool.h> 00025 #include "device.h" 00026 00027 /** 00028 * Legacy format representing a timestamp in us. 00029 * Given it is modeled as a 32 bit integer, this type can represent timestamp 00030 * up to 4294 seconds (71 minutes). 00031 * Prefer using us_timestamp_t which store timestamp as 64 bits integer. 00032 */ 00033 typedef uint32_t timestamp_t; 00034 00035 /** 00036 * A us timestamp stored in a 64 bit integer. 00037 * Can store timestamp up to 584810 years. 00038 */ 00039 typedef uint64_t us_timestamp_t; 00040 00041 /** Ticker's event structure 00042 */ 00043 typedef struct ticker_event_s { 00044 us_timestamp_t timestamp; /**< Event's timestamp */ 00045 uint32_t id; /**< TimerEvent object */ 00046 struct ticker_event_s *next; /**< Next event in the queue */ 00047 } ticker_event_t; 00048 00049 typedef void (*ticker_event_handler)(uint32_t id); 00050 00051 /** Information about the ticker implementation 00052 */ 00053 typedef struct { 00054 uint32_t frequency; /**< Frequency in Hz this ticker runs at */ 00055 uint32_t bits; /**< Number of bits this ticker supports */ 00056 } ticker_info_t; 00057 00058 00059 /** Ticker's interface structure - required API for a ticker 00060 */ 00061 typedef struct { 00062 void (*init)(void); /**< Init function */ 00063 uint32_t (*read)(void); /**< Read function */ 00064 void (*disable_interrupt)(void); /**< Disable interrupt function */ 00065 void (*clear_interrupt)(void); /**< Clear interrupt function */ 00066 void (*set_interrupt)(timestamp_t timestamp); /**< Set interrupt function */ 00067 void (*fire_interrupt)(void); /**< Fire interrupt right-away */ 00068 void (*free)(void); /**< Disable function */ 00069 const ticker_info_t *(*get_info)(void); /**< Return info about this ticker's implementation */ 00070 } ticker_interface_t; 00071 00072 /** Ticker's event queue structure 00073 */ 00074 typedef struct { 00075 ticker_event_handler event_handler; /**< Event handler */ 00076 ticker_event_t *head; /**< A pointer to head */ 00077 uint32_t frequency; /**< Frequency of the timer in Hz */ 00078 uint32_t bitmask; /**< Mask to be applied to time values read */ 00079 uint32_t max_delta; /**< Largest delta in ticks that can be used when scheduling */ 00080 uint64_t max_delta_us; /**< Largest delta in us that can be used when scheduling */ 00081 uint32_t tick_last_read; /**< Last tick read */ 00082 uint64_t tick_remainder; /**< Ticks that have not been added to base_time */ 00083 us_timestamp_t present_time; /**< Store the timestamp used for present time */ 00084 bool initialized; /**< Indicate if the instance is initialized */ 00085 bool dispatching; /**< The function ticker_irq_handler is dispatching */ 00086 bool suspended; /**< Indicate if the instance is suspended */ 00087 uint8_t frequency_shifts; /**< If frequency is a value of 2^n, this is n, otherwise 0 */ 00088 } ticker_event_queue_t; 00089 00090 /** Ticker's data structure 00091 */ 00092 typedef struct { 00093 const ticker_interface_t *interface; /**< Ticker's interface */ 00094 ticker_event_queue_t *queue; /**< Ticker's event queue */ 00095 } ticker_data_t; 00096 00097 #ifdef __cplusplus 00098 extern "C" { 00099 #endif 00100 00101 /** 00102 * \defgroup hal_ticker Ticker HAL functions 00103 * @{ 00104 */ 00105 00106 /** Initialize a ticker and set the event handler 00107 * 00108 * @param ticker The ticker object. 00109 * @param handler A handler to be set 00110 */ 00111 void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler); 00112 00113 /** IRQ handler that goes through the events to trigger overdue events. 00114 * 00115 * @param ticker The ticker object. 00116 */ 00117 void ticker_irq_handler(const ticker_data_t *const ticker); 00118 00119 /** Remove an event from the queue 00120 * 00121 * @param ticker The ticker object. 00122 * @param obj The event object to be removed from the queue 00123 */ 00124 void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj); 00125 00126 /** Insert an event to the queue 00127 * 00128 * The event will be executed in timestamp - ticker_read(). 00129 * 00130 * @warning This function does not consider timestamp in the past. If an event 00131 * is inserted with a timestamp less than the current timestamp then the event 00132 * will be executed in timestamp - ticker_read() us. 00133 * The internal counter wrap very quickly it is hard to decide weither an 00134 * event is in the past or in 1 hour. 00135 * 00136 * @note prefer the use of ticker_insert_event_us which allows registration of 00137 * absolute timestamp. 00138 * 00139 * @param ticker The ticker object. 00140 * @param obj The event object to be inserted to the queue 00141 * @param timestamp The event's timestamp 00142 * @param id The event object 00143 */ 00144 void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id); 00145 00146 /** Insert an event to the queue 00147 * 00148 * The event will be executed in timestamp - ticker_read_us() us. 00149 * 00150 * @note If an event is inserted with a timestamp less than the current 00151 * timestamp then the event will be scheduled immediately resulting in 00152 * an instant call to event handler. 00153 * 00154 * @param ticker The ticker object. 00155 * @param obj The event object to be inserted to the queue 00156 * @param timestamp The event's timestamp 00157 * @param id The event object 00158 */ 00159 void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id); 00160 00161 /** Read the current (relative) ticker's timestamp 00162 * 00163 * @warning Return a relative timestamp because the counter wrap every 4294 00164 * seconds. 00165 * 00166 * @param ticker The ticker object. 00167 * @return The current timestamp 00168 */ 00169 timestamp_t ticker_read(const ticker_data_t *const ticker); 00170 00171 /** Read the current (absolute) ticker's timestamp 00172 * 00173 * @warning Return an absolute timestamp counting from the initialization of the 00174 * ticker. 00175 * 00176 * @param ticker The ticker object. 00177 * @return The current timestamp 00178 */ 00179 us_timestamp_t ticker_read_us(const ticker_data_t *const ticker); 00180 00181 /** Read the next event's timestamp 00182 * 00183 * @param ticker The ticker object. 00184 * @param timestamp The timestamp object. 00185 * @return 1 if timestamp is pending event, 0 if there's no event pending 00186 */ 00187 int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp); 00188 00189 /** Suspend this ticker 00190 * 00191 * When suspended reads will always return the same time and no 00192 * events will be dispatched. When suspended the common layer 00193 * will only ever call the interface function clear_interrupt() 00194 * and that is only if ticker_irq_handler is called. 00195 * 00196 * 00197 * @param ticker The ticker object. 00198 */ 00199 void ticker_suspend(const ticker_data_t *const ticker); 00200 00201 /** Resume this ticker 00202 * 00203 * When resumed the ticker will ignore any time that has passed 00204 * and continue counting up where it left off. 00205 * 00206 * @param ticker The ticker object. 00207 */ 00208 void ticker_resume(const ticker_data_t *const ticker); 00209 00210 /* Private functions 00211 * 00212 * @cond PRIVATE 00213 * 00214 */ 00215 00216 int _ticker_match_interval_passed(timestamp_t prev_tick, timestamp_t cur_tick, timestamp_t match_tick); 00217 00218 /* 00219 * @endcond PRIVATE 00220 * 00221 */ 00222 00223 /**@}*/ 00224 00225 #ifdef __cplusplus 00226 } 00227 #endif 00228 00229 #endif 00230 00231 /** @}*/
Generated on Tue Jul 12 2022 20:41:16 by 1.7.2