Amit Gandhi / mbed-dev_2

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.

Fork of mbed-dev by mbed official

hal/ticker_api.h@175:b96e65c34a4d, 2017-10-02 (annotated)

Committer:
AnnaBridge
Date:
Mon Oct 02 15:33:19 2017 +0100
Revision:
175:b96e65c34a4d
Parent:
168:e84263d55307
Child:
177:447f873cad2f
This updates the lib to the mbed lib v 152

Who changed what in which revision?

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