Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
clock_alignment.c
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#include <stddef.h>
19#include "clock_alignment.h"
20
21/**
22 * @file clock_alignment.c
23 * @brief Implementation of USHER's token-bound, interval-based clock alignment.
24 * @details This intentionally avoids synchronizing clocks globally. It validates a
25 * small request/reply exchange, then maps only poses that carry the matching token.
26 * Integer interval arithmetic makes the drift assumptions explicit and handles normal
27 * uint32_t flight-controller timer wrap by subtraction.
28 */
29
30_Static_assert(sizeof(union usher_clock_reply_union) == USHER_CLOCK_REPLY_MSG_SIZE, "Clock reply wire size");
31_Static_assert(sizeof(union usher_pose_clocked_union) == USHER_POSE_CLOCKED_MSG_SIZE, "Clocked pose wire size");
32
33/** @brief Compare opaque wire tokens without depending on host structure padding. */
35{
36 return first.data.token_low == second.data.token_low && first.data.token_high == second.data.token_high;
37}
38
39bool clock_alignment_request(struct clock_alignment *clock, union usher_clock_request_union token, uint64_t sent_us)
40{
41 if (clock == NULL || sent_us == 0 || sent_us > UINT64_MAX - CLOCK_ALIGNMENT_MAX_RTT_US
42 || (token.data.token_low == 0 && token.data.token_high == 0)
43 || same_token(token, clock->pending_token) || same_token(token, clock->mapped_token)) return false;
44 clock->pending_token = token;
45 clock->sent_us = sent_us;
46 clock->pending = true;
47 return true;
48}
49
50bool clock_alignment_reply(struct clock_alignment *clock, const uint8_t *payload, size_t length, uint64_t received_us)
51{
52 if (clock == NULL || !clock->pending || payload == NULL || length != USHER_CLOCK_REPLY_MSG_SIZE) return false;
53 union usher_clock_reply_union reply = {0};
54 for (size_t index = 0; index < sizeof(reply.bin); ++index) reply.bin[index] = payload[index];
55 if (!same_token(reply.data.request, clock->pending_token)) return false;
56 clock->pending = false;
57 clock->valid = false;
58 if (received_us < clock->sent_us || received_us > UINT64_MAX - CLOCK_ALIGNMENT_MAX_AGE_US - 10000
59 || received_us - clock->sent_us > CLOCK_ALIGNMENT_MAX_RTT_US) return false;
60 const uint32_t service_us = reply.data.transmit_us - reply.data.receive_us;
61 if (service_us > CLOCK_ALIGNMENT_MAX_RTT_US) return false;
62 const uint64_t service_min_us = (uint64_t)service_us * 1000000 / (1000000 + CLOCK_ALIGNMENT_DRIFT_PPM);
63 const uint64_t lower = clock->sent_us + (service_min_us > 2 ? service_min_us - 2 : 0);
64 if (lower > received_us + 2) return false;
65 clock->anchor = (struct clock_interval) {lower, received_us + 2};
66 clock->anchor_fc_us = reply.data.transmit_us;
67 clock->receive_fc_us = reply.data.receive_us;
68 clock->mapped_sent_us = clock->sent_us;
69 clock->received_us = received_us;
70 clock->mapped_token = reply.data.request;
71 clock->valid = true;
72 return true;
73}
74
76 uint32_t fc_us, uint64_t now_us, struct clock_interval *interval)
77{
78 if (clock == NULL || interval == NULL || !clock->valid || !same_token(token, clock->mapped_token)
79 || now_us < clock->received_us || now_us - clock->received_us > CLOCK_ALIGNMENT_MAX_AGE_US) return false;
80 const uint32_t elapsed = fc_us - clock->anchor_fc_us;
81 if (elapsed > CLOCK_ALIGNMENT_MAX_AGE_US) return false;
82 const uint64_t minimum = (uint64_t)elapsed * 1000000 / (1000000 + CLOCK_ALIGNMENT_DRIFT_PPM);
83 const uint64_t maximum = ((uint64_t)elapsed * 1000000 + 999999 - CLOCK_ALIGNMENT_DRIFT_PPM)
84 / (1000000 - CLOCK_ALIGNMENT_DRIFT_PPM);
85 const uint64_t earliest = clock->anchor.earliest_us + (minimum > 2 ? minimum - 2 : 0);
86 uint64_t latest = clock->anchor.latest_us + maximum + 2;
87 if (earliest > now_us) return false;
88 if (latest > now_us) latest = now_us;
89 *interval = (struct clock_interval) {earliest, latest};
90 return true;
91}
static uint64_t service_us[COVERAGE_CAMERAS]
bool clock_alignment_reply(struct clock_alignment *clock, const uint8_t *payload, size_t length, uint64_t received_us)
Validate a flight-controller clock reply and establish a mapping anchor.
bool clock_alignment_request(struct clock_alignment *clock, union usher_clock_request_union token, uint64_t sent_us)
Register a newly transmitted clock probe.
static bool same_token(union usher_clock_request_union first, union usher_clock_request_union second)
Compare opaque wire tokens without depending on host structure padding.
bool clock_alignment_map(const struct clock_alignment *clock, union usher_clock_request_union token, uint32_t fc_us, uint64_t now_us, struct clock_interval *interval)
Project a controller timestamp into a conservative USHER time interval.
Bounded mapping between flight-controller microseconds and USHER monotonic time.
#define CLOCK_ALIGNMENT_DRIFT_PPM
#define CLOCK_ALIGNMENT_MAX_AGE_US
#define CLOCK_ALIGNMENT_MAX_RTT_US
static struct latest_measurement latest
Stateful evidence for at most one pending and one accepted clock probe.
uint64_t mapped_sent_us
union usher_clock_request_union pending_token
struct clock_interval anchor
union usher_clock_request_union mapped_token
Inclusive USHER monotonic-time bounds for a mapped controller timestamp.
struct usher_clock_reply_union::@260221177250276350221210364003171064301345176114 data
union usher_clock_request_union request
uint8_t bin[USHER_CLOCK_REPLY_MSG_SIZE]
struct usher_clock_request_union::@124322121054031044024143305010352315355331137256 data
uint64_t received_us
Definition usher.c:536
#define USHER_CLOCK_REPLY_MSG_SIZE
#define USHER_POSE_CLOCKED_MSG_SIZE