Daniel Vizcaya / Mbed OS 04_RTOS_Embebidos

Entrega 3er corte - sistemas embebidos

mbed-os/hal/ticker_api.h@1:fcdb45ee95b9, 2018-05-30 (annotated)

Committer:
Bethory
Date:
Wed May 30 04:46:28 2018 +0000
Revision:
1:fcdb45ee95b9
Parent:
0:6ad07c9019fd 
Entrega Final

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Bethory 0:6ad07c9019fd 1
Bethory 0:6ad07c9019fd 2 /** \addtogroup hal */
Bethory 0:6ad07c9019fd 3 /** @{*/
Bethory 0:6ad07c9019fd 4 /* mbed Microcontroller Library
Bethory 0:6ad07c9019fd 5 * Copyright (c) 2015 ARM Limited
Bethory 0:6ad07c9019fd 6 *
Bethory 0:6ad07c9019fd 7 * Licensed under the Apache License, Version 2.0 (the "License");
Bethory 0:6ad07c9019fd 8 * you may not use this file except in compliance with the License.
Bethory 0:6ad07c9019fd 9 * You may obtain a copy of the License at
Bethory 0:6ad07c9019fd 10 *
Bethory 0:6ad07c9019fd 11 * http://www.apache.org/licenses/LICENSE-2.0
Bethory 0:6ad07c9019fd 12 *
Bethory 0:6ad07c9019fd 13 * Unless required by applicable law or agreed to in writing, software
Bethory 0:6ad07c9019fd 14 * distributed under the License is distributed on an "AS IS" BASIS,
Bethory 0:6ad07c9019fd 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Bethory 0:6ad07c9019fd 16 * See the License for the specific language governing permissions and
Bethory 0:6ad07c9019fd 17 * limitations under the License.
Bethory 0:6ad07c9019fd 18 */
Bethory 0:6ad07c9019fd 19 #ifndef MBED_TICKER_API_H
Bethory 0:6ad07c9019fd 20 #define MBED_TICKER_API_H
Bethory 0:6ad07c9019fd 21
Bethory 0:6ad07c9019fd 22 #include <stdint.h>
Bethory 0:6ad07c9019fd 23 #include <stdbool.h>
Bethory 0:6ad07c9019fd 24 #include "device.h"
Bethory 0:6ad07c9019fd 25
Bethory 0:6ad07c9019fd 26 /**
Bethory 0:6ad07c9019fd 27 * Legacy format representing a timestamp in us.
Bethory 0:6ad07c9019fd 28 * Given it is modeled as a 32 bit integer, this type can represent timestamp
Bethory 0:6ad07c9019fd 29 * up to 4294 seconds (71 minutes).
Bethory 0:6ad07c9019fd 30 * Prefer using us_timestamp_t which store timestamp as 64 bits integer.
Bethory 0:6ad07c9019fd 31 */
Bethory 0:6ad07c9019fd 32 typedef uint32_t timestamp_t;
Bethory 0:6ad07c9019fd 33
Bethory 0:6ad07c9019fd 34 /**
Bethory 0:6ad07c9019fd 35 * A us timestamp stored in a 64 bit integer.
Bethory 0:6ad07c9019fd 36 * Can store timestamp up to 584810 years.
Bethory 0:6ad07c9019fd 37 */
Bethory 0:6ad07c9019fd 38 typedef uint64_t us_timestamp_t;
Bethory 0:6ad07c9019fd 39
Bethory 0:6ad07c9019fd 40 /** Ticker's event structure
Bethory 0:6ad07c9019fd 41 */
Bethory 0:6ad07c9019fd 42 typedef struct ticker_event_s {
Bethory 0:6ad07c9019fd 43 us_timestamp_t timestamp; /**< Event's timestamp */
Bethory 0:6ad07c9019fd 44 uint32_t id; /**< TimerEvent object */
Bethory 0:6ad07c9019fd 45 struct ticker_event_s *next; /**< Next event in the queue */
Bethory 0:6ad07c9019fd 46 } ticker_event_t;
Bethory 0:6ad07c9019fd 47
Bethory 0:6ad07c9019fd 48 typedef void (*ticker_event_handler)(uint32_t id);
Bethory 0:6ad07c9019fd 49
Bethory 0:6ad07c9019fd 50 /** Information about the ticker implementation
Bethory 0:6ad07c9019fd 51 */
Bethory 0:6ad07c9019fd 52 typedef struct {
Bethory 0:6ad07c9019fd 53 uint32_t frequency; /**< Frequency in Hz this ticker runs at */
Bethory 0:6ad07c9019fd 54 uint32_t bits; /**< Number of bits this ticker supports */
Bethory 0:6ad07c9019fd 55 } ticker_info_t;
Bethory 0:6ad07c9019fd 56
Bethory 0:6ad07c9019fd 57
Bethory 0:6ad07c9019fd 58 /** Ticker's interface structure - required API for a ticker
Bethory 0:6ad07c9019fd 59 */
Bethory 0:6ad07c9019fd 60 typedef struct {
Bethory 0:6ad07c9019fd 61 void (*init)(void); /**< Init function */
Bethory 0:6ad07c9019fd 62 uint32_t (*read)(void); /**< Read function */
Bethory 0:6ad07c9019fd 63 void (*disable_interrupt)(void); /**< Disable interrupt function */
Bethory 0:6ad07c9019fd 64 void (*clear_interrupt)(void); /**< Clear interrupt function */
Bethory 0:6ad07c9019fd 65 void (*set_interrupt)(timestamp_t timestamp); /**< Set interrupt function */
Bethory 0:6ad07c9019fd 66 void (*fire_interrupt)(void); /**< Fire interrupt right-away */
Bethory 0:6ad07c9019fd 67 const ticker_info_t *(*get_info)(void); /**< Return info about this ticker's implementation */
Bethory 0:6ad07c9019fd 68 } ticker_interface_t;
Bethory 0:6ad07c9019fd 69
Bethory 0:6ad07c9019fd 70 /** Ticker's event queue structure
Bethory 0:6ad07c9019fd 71 */
Bethory 0:6ad07c9019fd 72 typedef struct {
Bethory 0:6ad07c9019fd 73 ticker_event_handler event_handler; /**< Event handler */
Bethory 0:6ad07c9019fd 74 ticker_event_t *head; /**< A pointer to head */
Bethory 0:6ad07c9019fd 75 uint32_t frequency; /**< Frequency of the timer in Hz */
Bethory 0:6ad07c9019fd 76 uint32_t bitmask; /**< Mask to be applied to time values read */
Bethory 0:6ad07c9019fd 77 uint32_t max_delta; /**< Largest delta in ticks that can be used when scheduling */
Bethory 0:6ad07c9019fd 78 uint64_t max_delta_us; /**< Largest delta in us that can be used when scheduling */
Bethory 0:6ad07c9019fd 79 uint32_t tick_last_read; /**< Last tick read */
Bethory 0:6ad07c9019fd 80 uint64_t tick_remainder; /**< Ticks that have not been added to base_time */
Bethory 0:6ad07c9019fd 81 us_timestamp_t present_time; /**< Store the timestamp used for present time */
Bethory 0:6ad07c9019fd 82 bool initialized; /**< Indicate if the instance is initialized */
Bethory 0:6ad07c9019fd 83 } ticker_event_queue_t;
Bethory 0:6ad07c9019fd 84
Bethory 0:6ad07c9019fd 85 /** Ticker's data structure
Bethory 0:6ad07c9019fd 86 */
Bethory 0:6ad07c9019fd 87 typedef struct {
Bethory 0:6ad07c9019fd 88 const ticker_interface_t *interface; /**< Ticker's interface */
Bethory 0:6ad07c9019fd 89 ticker_event_queue_t *queue; /**< Ticker's event queue */
Bethory 0:6ad07c9019fd 90 } ticker_data_t;
Bethory 0:6ad07c9019fd 91
Bethory 0:6ad07c9019fd 92 #ifdef __cplusplus
Bethory 0:6ad07c9019fd 93 extern "C" {
Bethory 0:6ad07c9019fd 94 #endif
Bethory 0:6ad07c9019fd 95
Bethory 0:6ad07c9019fd 96 /**
Bethory 0:6ad07c9019fd 97 * \defgroup hal_ticker Ticker HAL functions
Bethory 0:6ad07c9019fd 98 * @{
Bethory 0:6ad07c9019fd 99 */
Bethory 0:6ad07c9019fd 100
Bethory 0:6ad07c9019fd 101 /** Initialize a ticker and set the event handler
Bethory 0:6ad07c9019fd 102 *
Bethory 0:6ad07c9019fd 103 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 104 * @param handler A handler to be set
Bethory 0:6ad07c9019fd 105 */
Bethory 0:6ad07c9019fd 106 void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler);
Bethory 0:6ad07c9019fd 107
Bethory 0:6ad07c9019fd 108 /** IRQ handler that goes through the events to trigger overdue events.
Bethory 0:6ad07c9019fd 109 *
Bethory 0:6ad07c9019fd 110 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 111 */
Bethory 0:6ad07c9019fd 112 void ticker_irq_handler(const ticker_data_t *const ticker);
Bethory 0:6ad07c9019fd 113
Bethory 0:6ad07c9019fd 114 /** Remove an event from the queue
Bethory 0:6ad07c9019fd 115 *
Bethory 0:6ad07c9019fd 116 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 117 * @param obj The event object to be removed from the queue
Bethory 0:6ad07c9019fd 118 */
Bethory 0:6ad07c9019fd 119 void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj);
Bethory 0:6ad07c9019fd 120
Bethory 0:6ad07c9019fd 121 /** Insert an event to the queue
Bethory 0:6ad07c9019fd 122 *
Bethory 0:6ad07c9019fd 123 * The event will be executed in timestamp - ticker_read().
Bethory 0:6ad07c9019fd 124 *
Bethory 0:6ad07c9019fd 125 * @warning This function does not consider timestamp in the past. If an event
Bethory 0:6ad07c9019fd 126 * is inserted with a timestamp less than the current timestamp then the event
Bethory 0:6ad07c9019fd 127 * will be executed in timestamp - ticker_read() us.
Bethory 0:6ad07c9019fd 128 * The internal counter wrap very quickly it is hard to decide weither an
Bethory 0:6ad07c9019fd 129 * event is in the past or in 1 hour.
Bethory 0:6ad07c9019fd 130 *
Bethory 0:6ad07c9019fd 131 * @note prefer the use of ticker_insert_event_us which allows registration of
Bethory 0:6ad07c9019fd 132 * absolute timestamp.
Bethory 0:6ad07c9019fd 133 *
Bethory 0:6ad07c9019fd 134 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 135 * @param obj The event object to be inserted to the queue
Bethory 0:6ad07c9019fd 136 * @param timestamp The event's timestamp
Bethory 0:6ad07c9019fd 137 * @param id The event object
Bethory 0:6ad07c9019fd 138 */
Bethory 0:6ad07c9019fd 139 void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id);
Bethory 0:6ad07c9019fd 140
Bethory 0:6ad07c9019fd 141 /** Insert an event to the queue
Bethory 0:6ad07c9019fd 142 *
Bethory 0:6ad07c9019fd 143 * The event will be executed in timestamp - ticker_read_us() us.
Bethory 0:6ad07c9019fd 144 *
Bethory 0:6ad07c9019fd 145 * @note If an event is inserted with a timestamp less than the current
Bethory 0:6ad07c9019fd 146 * timestamp then the event will be scheduled immediately resulting in
Bethory 0:6ad07c9019fd 147 * an instant call to event handler.
Bethory 0:6ad07c9019fd 148 *
Bethory 0:6ad07c9019fd 149 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 150 * @param obj The event object to be inserted to the queue
Bethory 0:6ad07c9019fd 151 * @param timestamp The event's timestamp
Bethory 0:6ad07c9019fd 152 * @param id The event object
Bethory 0:6ad07c9019fd 153 */
Bethory 0:6ad07c9019fd 154 void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id);
Bethory 0:6ad07c9019fd 155
Bethory 0:6ad07c9019fd 156 /** Read the current (relative) ticker's timestamp
Bethory 0:6ad07c9019fd 157 *
Bethory 0:6ad07c9019fd 158 * @warning Return a relative timestamp because the counter wrap every 4294
Bethory 0:6ad07c9019fd 159 * seconds.
Bethory 0:6ad07c9019fd 160 *
Bethory 0:6ad07c9019fd 161 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 162 * @return The current timestamp
Bethory 0:6ad07c9019fd 163 */
Bethory 0:6ad07c9019fd 164 timestamp_t ticker_read(const ticker_data_t *const ticker);
Bethory 0:6ad07c9019fd 165
Bethory 0:6ad07c9019fd 166 /** Read the current (absolute) ticker's timestamp
Bethory 0:6ad07c9019fd 167 *
Bethory 0:6ad07c9019fd 168 * @warning Return an absolute timestamp counting from the initialization of the
Bethory 0:6ad07c9019fd 169 * ticker.
Bethory 0:6ad07c9019fd 170 *
Bethory 0:6ad07c9019fd 171 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 172 * @return The current timestamp
Bethory 0:6ad07c9019fd 173 */
Bethory 0:6ad07c9019fd 174 us_timestamp_t ticker_read_us(const ticker_data_t *const ticker);
Bethory 0:6ad07c9019fd 175
Bethory 0:6ad07c9019fd 176 /** Read the next event's timestamp
Bethory 0:6ad07c9019fd 177 *
Bethory 0:6ad07c9019fd 178 * @param ticker The ticker object.
Bethory 0:6ad07c9019fd 179 * @param timestamp The timestamp object.
Bethory 0:6ad07c9019fd 180 * @return 1 if timestamp is pending event, 0 if there's no event pending
Bethory 0:6ad07c9019fd 181 */
Bethory 0:6ad07c9019fd 182 int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp);
Bethory 0:6ad07c9019fd 183
Bethory 0:6ad07c9019fd 184 /* Private functions
Bethory 0:6ad07c9019fd 185 *
Bethory 0:6ad07c9019fd 186 * @cond PRIVATE
Bethory 0:6ad07c9019fd 187 *
Bethory 0:6ad07c9019fd 188 */
Bethory 0:6ad07c9019fd 189
Bethory 0:6ad07c9019fd 190 int _ticker_match_interval_passed(timestamp_t prev_tick, timestamp_t cur_tick, timestamp_t match_tick);
Bethory 0:6ad07c9019fd 191
Bethory 0:6ad07c9019fd 192 /*
Bethory 0:6ad07c9019fd 193 * @endcond PRIVATE
Bethory 0:6ad07c9019fd 194 *
Bethory 0:6ad07c9019fd 195 */
Bethory 0:6ad07c9019fd 196
Bethory 0:6ad07c9019fd 197 /**@}*/
Bethory 0:6ad07c9019fd 198
Bethory 0:6ad07c9019fd 199 #ifdef __cplusplus
Bethory 0:6ad07c9019fd 200 }
Bethory 0:6ad07c9019fd 201 #endif
Bethory 0:6ad07c9019fd 202
Bethory 0:6ad07c9019fd 203 #endif
Bethory 0:6ad07c9019fd 204
Bethory 0:6ad07c9019fd 205 /** @}*/