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