Thomas Lyp / DevLibMemoryController

Initial commit

Dependencies:   FastPWM

mbed-dev-master/hal/ticker_api.h@0:bb348c97df44, 2020-09-16 (annotated)

Committer:
lypinator
Date:
Wed Sep 16 01:11:49 2020 +0000
Revision:
0:bb348c97df44
Added PWM

Who changed what in which revision?

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