cdx_time.h Source

  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//=============================================================================