1//=============================================================================
2//! @file
3//! @author GEMS
4//! @date 7 October 2026
5//! @brief Receiver-local runtime timestamps and wrap-safe deadline helpers.
6//=============================================================================
7// (c) Copyright 2026 General Engine Management Systems (GEMS) Ltd
8//=============================================================================
9
10#ifndef CDX_TIME_H_INCLUDED
11#define CDX_TIME_H_INCLUDED
12//=============================================================================
13
14//=============================================================================
15// Includes
16//=============================================================================
17
18#if defined(CDX_USER_HEADER) && !defined(CDX_USER_H_INCLUDED)
19#include CDX_USER_HEADER
20#endif
21
22#include <stdint.h>
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28//=============================================================================
29// Definitions
30//=============================================================================
31
32//! @brief Wrapping microsecond ticks; one tick is one microsecond, not one ms.
33typedef uint32_t CDX_TICKS_32;
34//! @brief Wrapping 32-bit milliseconds.
35typedef uint32_t CDX_MILLISEC_32;
36//! @brief Wrapping 32-bit microseconds.
37typedef uint32_t CDX_MICROSEC_32;
38//! @brief Extended 64-bit microseconds, maintained by foreground polling.
39typedef uint64_t CDX_MICROSEC_64;
40//! @brief Largest unambiguous future deadline interval in microseconds.
41#define CDX_MICROSEC_32_DEADLINE_MAX 0x7fffffffu
42
43//! @defgroup CDX_TIME CDX Runtime Time
44//! @brief Foreground time helpers; CM4 and CM7 clocks are not synchronized.
45//! @details The runtime must poll at least once per 32-bit microsecond wrap
46//! (about 71 minutes) to extend time correctly. Deadline comparisons require
47//! intervals within the half-range limit. These APIs are not ISR-safe.
48//! @{
49//=============================================================================
50// Prototypes
51//=============================================================================
52
53//-----------------------------------------------------------------------------
54//! @brief Read the current wrapping microsecond tick counter.
55//! @return Local ticks, or zero when no runtime clock is bound.
56CDX_TICKS_32 CDX_ticks_now(void);
57
58//-----------------------------------------------------------------------------
59//! @brief Read the local microsecond counter modulo 2^32.
60//! @return Local microseconds, or zero when no runtime clock is bound.
61CDX_MICROSEC_32 CDX_microsec_32_now(void);
62
63//-----------------------------------------------------------------------------
64//! @brief Read local microseconds with foreground-maintained wrap extension.
65//! @return Extended microsecond count, or zero when no runtime is bound.
66CDX_MICROSEC_64 CDX_microsec_64_now(void);
67
68//-----------------------------------------------------------------------------
69//! @brief Read local milliseconds modulo 2^32.
70//! @return Extended microseconds divided by 1000, truncated to 32 bits.
71CDX_MILLISEC_32 CDX_millisec_32_now(void);
72
73//-----------------------------------------------------------------------------
74//! @brief Convert a recent past microsecond timestamp to local milliseconds.
75//! @param ticks Past local timestamp less than one microsecond-counter wrap old.
76//! @return Timestamp in wrapping milliseconds, accounting for a recent tick wrap.
77CDX_MILLISEC_32 CDX_millisec_32_from_ticks(CDX_TICKS_32 ticks);
78
79//-----------------------------------------------------------------------------
80//! @brief Calculate microseconds remaining to a local absolute deadline.
81//! @param deadline Wrapping microsecond deadline within the half-range limit.
82//! @return Remaining microseconds, or zero if due, expired or beyond half-range.
83//! @note This helper does not interpret zero as a disabled CAN deadline.
84CDX_MICROSEC_32 CDX_microsec_deadline_remain(CDX_MICROSEC_32 deadline);
85
86//-----------------------------------------------------------------------------
87//! @brief Form a nonzero CAN deadline relative to the current local ticks.
88//! @param interval_ms Milliseconds ahead; clamped to the half-range limit / 1000.
89//! @return Absolute wrapping deadline; a computed zero is changed to one tick.
90//! @note Zero in CDX_CAN_TX_PARAMS means no deadline, so this result avoids zero.
91CDX_TICKS_32 CDX_ticks_deadline_from_millisec(CDX_MILLISEC_32 interval_ms);
92
93//! @}
94#ifdef __cplusplus
95} // extern "C"
96#endif
97
98//=============================================================================
99#endif // CDX_TIME_H_INCLUDED
100//=============================================================================
101// End of File
102//=============================================================================