Skip to content

Commit aeffd73

Browse files
pan-pan-
committed
ticker_api: Code clarification
* update_interrupt renamed into schedule_interrupt * update_current_timestamp renamed into update_present_time * ticker_event_queue_t::timestamp renamed into * ticker_event_queue_t::present_time * Fix doxygen comments in ticker_api.h * Update comments internal comments in mbed_ticker_api.c
1 parent c20a1cc commit aeffd73

File tree

3 files changed

+93
-86
lines changed

3 files changed

+93
-86
lines changed

‎TESTS/mbed_hal/ticker/main.cpp

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ static ticker_event_queue_t queue_stub = {
100100
static void reset_queue_stub() {
101101
queue_stub.event_handler = NULL;
102102
queue_stub.head = NULL,
103-
queue_stub.timestamp = 0;
103+
queue_stub.present_time = 0;
104104
queue_stub.initialized = false;
105105
}
106106

@@ -174,7 +174,7 @@ static void test_ticker_initialization() {
174174

175175
TEST_ASSERT_TRUE(interface_stub.initialized);
176176
TEST_ASSERT_EQUAL_PTR(dummy_handler, queue_stub.event_handler);
177-
TEST_ASSERT_EQUAL_UINT64(interface_stub.timestamp, queue_stub.timestamp);
177+
TEST_ASSERT_EQUAL_UINT64(interface_stub.timestamp, queue_stub.present_time);
178178
TEST_ASSERT_EQUAL(1, interface_stub.set_interrupt_call);
179179
TEST_ASSERT_EQUAL_UINT32(
180180
interface_stub.timestamp + TIMESTAMP_MAX_DELTA,
@@ -437,7 +437,7 @@ static void test_legacy_insert_event_overflow() {
437437
TIMESTAMP_MAX_DELTA +
438438
1;
439439
const us_timestamp_t expected_us_timestamp =
440-
(((queue_stub.timestamp >> 32) + 1) << 32) | expected_timestamp;
440+
(((queue_stub.present_time >> 32) + 1) << 32) | expected_timestamp;
441441
const uint32_t expected_id = 0xDEADDEAF;
442442

443443
ticker_insert_event(
@@ -792,12 +792,12 @@ static void test_insert_event_us_outside_overflow_range() {
792792
ticker_set_handler(&ticker_stub, NULL);
793793
interface_stub.set_interrupt_call = 0;
794794
interface_stub.timestamp = 0xAAAAAAAA;
795-
queue_stub.timestamp = 10ULL << 32 | interface_stub.timestamp;
795+
queue_stub.present_time = 10ULL << 32 | interface_stub.timestamp;
796796

797797
// test the end of the range
798798
ticker_event_t last_event = { 0 };
799799
const us_timestamp_t timestamp_last_event =
800-
queue_stub.timestamp + TIMESTAMP_MAX_DELTA;
800+
queue_stub.present_time + TIMESTAMP_MAX_DELTA;
801801
const uint32_t id_last_event = 0xDEADDEAF;
802802

803803
ticker_insert_event_us(
@@ -816,7 +816,7 @@ static void test_insert_event_us_outside_overflow_range() {
816816

817817
// test the beginning of the range
818818
ticker_event_t first_event = { 0 };
819-
const us_timestamp_t timestamp_first_event = queue_stub.timestamp + 1;
819+
const us_timestamp_t timestamp_first_event = queue_stub.present_time + 1;
820820
const uint32_t id_first_event = 0xAAAAAAAA;
821821

822822
ticker_insert_event_us(
@@ -852,7 +852,7 @@ static void test_insert_event_us_in_overflow_range() {
852852
ticker_set_handler(&ticker_stub, NULL);
853853
interface_stub.set_interrupt_call = 0;
854854
interface_stub.timestamp = 0xAAAAAAAA;
855-
queue_stub.timestamp = 10ULL << 32 | interface_stub.timestamp;
855+
queue_stub.present_time = 10ULL << 32 | interface_stub.timestamp;
856856

857857
// test the end of the range
858858
ticker_event_t last_event = { 0 };
@@ -876,11 +876,11 @@ static void test_insert_event_us_in_overflow_range() {
876876

877877
// test the beginning of the range
878878
++interface_stub.timestamp;
879-
++queue_stub.timestamp;
879+
++queue_stub.present_time;
880880

881881
ticker_event_t first_event = { 0 };
882882
const us_timestamp_t timestamp_first_event =
883-
queue_stub.timestamp + TIMESTAMP_MAX_DELTA + 1;
883+
queue_stub.present_time + TIMESTAMP_MAX_DELTA + 1;
884884
uint32_t id_first_event = 0xAAAAAAAA;
885885

886886
ticker_insert_event_us(&ticker_stub,
@@ -914,11 +914,11 @@ static void test_insert_event_us_underflow() {
914914
interface_stub.set_interrupt_call = 0;
915915

916916
interface_stub.timestamp = 0xAAAAAAAA;
917-
queue_stub.timestamp = 10ULL << 32 | interface_stub.timestamp;
917+
queue_stub.present_time = 10ULL << 32 | interface_stub.timestamp;
918918

919919
// test the end of the range
920920
ticker_event_t event = { 0 };
921-
const timestamp_t expected_timestamp = queue_stub.timestamp - 1;
921+
const timestamp_t expected_timestamp = queue_stub.present_time - 1;
922922
const uint32_t expected_id = 0xDEADDEAF;
923923

924924
ticker_insert_event_us(
@@ -951,16 +951,16 @@ static void test_insert_event_us_head() {
951951
ticker_set_handler(&ticker_stub, NULL);
952952
interface_stub.set_interrupt_call = 0;
953953
interface_stub.timestamp = 0xAAAAAAAA;
954-
queue_stub.timestamp = 10ULL << 32 | interface_stub.timestamp;
954+
queue_stub.present_time = 10ULL << 32 | interface_stub.timestamp;
955955

956956
const us_timestamp_t timestamps[] = {
957957
UINT64_MAX,
958-
queue_stub.timestamp + TIMESTAMP_MAX_DELTA + 1,
959-
queue_stub.timestamp + TIMESTAMP_MAX_DELTA,
960-
queue_stub.timestamp + (TIMESTAMP_MAX_DELTA / 2),
961-
queue_stub.timestamp + (TIMESTAMP_MAX_DELTA / 4),
962-
queue_stub.timestamp + (TIMESTAMP_MAX_DELTA / 8),
963-
queue_stub.timestamp + (TIMESTAMP_MAX_DELTA / 16),
958+
queue_stub.present_time + TIMESTAMP_MAX_DELTA + 1,
959+
queue_stub.present_time + TIMESTAMP_MAX_DELTA,
960+
queue_stub.present_time + (TIMESTAMP_MAX_DELTA / 2),
961+
queue_stub.present_time + (TIMESTAMP_MAX_DELTA / 4),
962+
queue_stub.present_time + (TIMESTAMP_MAX_DELTA / 8),
963+
queue_stub.present_time + (TIMESTAMP_MAX_DELTA / 16),
964964
};
965965
ticker_event_t events[MBED_ARRAY_SIZE(timestamps)] = { 0 };
966966

@@ -971,14 +971,14 @@ static void test_insert_event_us_head() {
971971
);
972972

973973
TEST_ASSERT_EQUAL_PTR(&events[i], queue_stub.head);
974-
if ((timestamps[i] - queue_stub.timestamp) < TIMESTAMP_MAX_DELTA) {
974+
if ((timestamps[i] - queue_stub.present_time) < TIMESTAMP_MAX_DELTA) {
975975
TEST_ASSERT_EQUAL_UINT32(
976976
timestamps[i],
977977
interface_stub.interrupt_timestamp
978978
);
979979
} else {
980980
TEST_ASSERT_EQUAL_UINT32(
981-
queue_stub.timestamp + TIMESTAMP_MAX_DELTA,
981+
queue_stub.present_time + TIMESTAMP_MAX_DELTA,
982982
interface_stub.interrupt_timestamp
983983
);
984984
}
@@ -1464,7 +1464,7 @@ static void test_overflow_event_update() {
14641464
interface_stub.set_interrupt_call = 0;
14651465

14661466
for (size_t i = 0; i < 8; ++i) {
1467-
us_timestamp_t previous_timestamp = queue_stub.timestamp;
1467+
us_timestamp_t previous_timestamp = queue_stub.present_time;
14681468
timestamp_t interface_timestamp =
14691469
previous_timestamp + (TIMESTAMP_MAX_DELTA + i * 100);
14701470
interface_stub.timestamp = interface_timestamp;
@@ -1505,7 +1505,7 @@ static void test_overflow_event_update_when_spurious_interrupt() {
15051505
interface_stub.set_interrupt_call = 0;
15061506

15071507
for (size_t i = 0; i < 8; ++i) {
1508-
us_timestamp_t previous_timestamp = queue_stub.timestamp;
1508+
us_timestamp_t previous_timestamp = queue_stub.present_time;
15091509
timestamp_t interface_timestamp =
15101510
previous_timestamp + (TIMESTAMP_MAX_DELTA / (2 + i));
15111511
interface_stub.timestamp = interface_timestamp;

‎hal/mbed_ticker_api.c

Lines changed: 62 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,8 @@
1818
#include "hal/ticker_api.h"
1919
#include "platform/mbed_critical.h"
2020

21-
#define MBED_MIN(x,y) (((x)<(y))?(x):(y))
22-
23-
static void update_interrupt(const ticker_data_t *const ticker);
24-
static void update_current_timestamp(const ticker_data_t *const ticker);
21+
static void schedule_interrupt(const ticker_data_t *const ticker);
22+
static void update_present_time(const ticker_data_t *const ticker);
2523

2624
/*
2725
* Initialize a ticker instance.
@@ -38,11 +36,11 @@ static void initialize(const ticker_data_t *ticker)
3836

3937
ticker->queue->event_handler = NULL;
4038
ticker->queue->head = NULL;
41-
ticker->queue->timestamp = 0;
39+
ticker->queue->present_time = 0;
4240
ticker->queue->initialized = true;
4341

44-
update_current_timestamp(ticker);
45-
update_interrupt(ticker);
42+
update_present_time(ticker);
43+
schedule_interrupt(ticker);
4644
}
4745

4846
/**
@@ -54,22 +52,29 @@ static void set_handler(const ticker_data_t *const ticker, ticker_event_handler
5452
}
5553

5654
/*
57-
* Convert a low res timestamp to a high res timestamp. An high resolution
58-
* timestamp is used as the reference point to convert the low res timestamp
59-
* into an high res one.
60-
*
61-
* It is important to note that the result will **never** be in the past. If the
62-
* value of the low res timetamp is less than the low res part of the reference
63-
* timestamp then an overflow is
55+
* Convert a 32 bit timestamp into a 64 bit timestamp.
56+
*
57+
* A 64 bit timestamp is used as the point of time of reference while the
58+
* timestamp to convert is relative to this point of time.
59+
*
60+
* The lower 32 bits of the timestamp returned will be equal to the timestamp to
61+
* convert.
6462
*
65-
* @param ref: The timestamp of reference.
66-
* @param relative_timestamp: The timestamp to convert.
63+
* If the timestamp to convert is less than the lower 32 bits of the time
64+
* reference then the timestamp to convert is seen as an overflowed value and
65+
* the upper 32 bit of the timestamp returned will be equal to the upper 32 bit
66+
* of the reference point + 1.
67+
* Otherwise, the upper 32 bit returned will be equal to the upper 32 bit of the
68+
* reference point.
69+
*
70+
* @param ref: The 64 bit timestamp of reference.
71+
* @param timestamp: The timestamp to convert.
6772
*/
68-
static us_timestamp_t convert_relative_timestamp(us_timestamp_t ref, timestamp_t relative_timestamp)
73+
static us_timestamp_t convert_timestamp(us_timestamp_t ref, timestamp_t timestamp)
6974
{
70-
bool overflow = relative_timestamp < ((timestamp_t) ref) ? true : false;
75+
bool overflow = timestamp < ((timestamp_t) ref) ? true : false;
7176

72-
us_timestamp_t result = (ref & ~((us_timestamp_t)UINT32_MAX)) | relative_timestamp;
77+
us_timestamp_t result = (ref & ~((us_timestamp_t)UINT32_MAX)) | timestamp;
7378
if (overflow) {
7479
result += (1ULL<<32);
7580
}
@@ -78,38 +83,42 @@ static us_timestamp_t convert_relative_timestamp(us_timestamp_t ref, timestamp_t
7883
}
7984

8085
/**
81-
* update the current timestamp value of a ticker.
86+
* Update the present timestamp value of a ticker.
8287
*/
83-
static void update_current_timestamp(const ticker_data_t *const ticker)
88+
static void update_present_time(const ticker_data_t *const ticker)
8489
{
85-
ticker->queue->timestamp = convert_relative_timestamp(
86-
ticker->queue->timestamp,
90+
ticker->queue->present_time = convert_timestamp(
91+
ticker->queue->present_time,
8792
ticker->interface->read()
8893
);
8994
}
9095

9196
/**
92-
* update the interrupt with the appropriate timestamp.
93-
* if there is no interrupt scheduled or the next event to execute is in more
94-
* than MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA us from now then the
95-
* interrupt will be set to MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA us from now.
96-
* Otherwise the interrupt will be set to head->timestamp - queue->timestamp us.
97+
* Compute the time when the interrupt has to be triggered and schedule it.
98+
*
99+
* If there is no event in the queue or the next event to execute is in more
100+
* than MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA us from now then the ticker
101+
* irq will be scheduled in MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA us.
102+
* Otherwise the irq will be scheduled to happen when the running counter reach
103+
* the timestamp of the first event in the queue.
104+
*
105+
* @note If there is no event in the queue then the interrupt is scheduled to
106+
* in MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA. This is necessary to keep track
107+
* of the timer overflow.
97108
*/
98-
static void update_interrupt(const ticker_data_t *const ticker)
109+
static void schedule_interrupt(const ticker_data_t *const ticker)
99110
{
100-
update_current_timestamp(ticker);
101-
uint32_t diff = MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA;
102-
103-
if (ticker->queue->head) {
104-
diff = MBED_MIN(
105-
(ticker->queue->head->timestamp - ticker->queue->timestamp),
106-
MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA
107-
);
111+
update_present_time(ticker);
112+
uint32_t duration = MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA;
113+
114+
if (ticker->queue->head) {
115+
us_timestamp_t event_interval = (ticker->queue->head->timestamp - ticker->queue->present_time);
116+
if (event_interval < MBED_TICKER_INTERRUPT_TIMESTAMP_MAX_DELTA) {
117+
duration = event_interval;
118+
}
108119
}
109120

110-
ticker->interface->set_interrupt(
111-
ticker->queue->timestamp + diff
112-
);
121+
ticker->interface->set_interrupt(ticker->queue->present_time + duration);
113122
}
114123

115124
void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler)
@@ -129,9 +138,9 @@ void ticker_irq_handler(const ticker_data_t *const ticker)
129138
}
130139

131140
// update the current timestamp used by the queue
132-
update_current_timestamp(ticker);
141+
update_present_time(ticker);
133142

134-
if (ticker->queue->head->timestamp <= ticker->queue->timestamp) {
143+
if (ticker->queue->head->timestamp <= ticker->queue->present_time) {
135144
// This event was in the past:
136145
// point to the following one and execute its handler
137146
ticker_event_t *p = ticker->queue->head;
@@ -146,18 +155,17 @@ void ticker_irq_handler(const ticker_data_t *const ticker)
146155
}
147156
}
148157

149-
update_interrupt(ticker);
158+
schedule_interrupt(ticker);
150159
}
151160

152161
void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id)
153162
{
154-
/* disable interrupts for the duration of the function */
155163
core_util_critical_section_enter();
156164

157165
// update the current timestamp
158-
update_current_timestamp(ticker);
159-
us_timestamp_t absolute_timestamp = convert_relative_timestamp(
160-
ticker->queue->timestamp,
166+
update_present_time(ticker);
167+
us_timestamp_t absolute_timestamp = convert_timestamp(
168+
ticker->queue->present_time,
161169
timestamp
162170
);
163171
core_util_critical_section_exit();
@@ -171,15 +179,14 @@ void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj,
171179

172180
void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id)
173181
{
174-
/* disable interrupts for the duration of the function */
175182
core_util_critical_section_enter();
176183

177184
// update the current timestamp
178-
update_current_timestamp(ticker);
185+
update_present_time(ticker);
179186

180187
// filter out timestamp in the past
181-
if (timestamp < ticker->queue->timestamp) {
182-
update_interrupt(ticker);
188+
if (timestamp < ticker->queue->present_time) {
189+
schedule_interrupt(ticker);
183190
return;
184191
}
185192

@@ -211,7 +218,7 @@ void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *o
211218
prev->next = obj;
212219
}
213220

214-
update_interrupt(ticker);
221+
schedule_interrupt(ticker);
215222

216223
core_util_critical_section_exit();
217224
}
@@ -224,7 +231,7 @@ void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj)
224231
if (ticker->queue->head == obj) {
225232
// first in the list, so just drop me
226233
ticker->queue->head = obj->next;
227-
update_interrupt(ticker);
234+
schedule_interrupt(ticker);
228235
} else {
229236
// find the object before me, then drop me
230237
ticker_event_t* p = ticker->queue->head;
@@ -247,8 +254,8 @@ timestamp_t ticker_read(const ticker_data_t *const ticker)
247254

248255
us_timestamp_t ticker_read_us(const ticker_data_t *const ticker)
249256
{
250-
update_current_timestamp(ticker);
251-
return ticker->queue->timestamp;
257+
update_present_time(ticker);
258+
return ticker->queue->present_time;
252259
}
253260

254261
int ticker_get_next_timestamp(const ticker_data_t *const data, timestamp_t *timestamp)

0 commit comments

Comments
 (0)