cdx_can.h Source

  1//=============================================================================
  2//! @file
  3//! @author GEMS
  4//! @date   7 October 2026
  5//! @brief Foreground model CAN/FD frame and Model IPC transmission API.
  6//=============================================================================
  7// (c) Copyright 2026 General Engine Management Systems (GEMS) Ltd
  8//=============================================================================
  9
 10#ifndef CDX_CAN_H_INCLUDED
 11#define CDX_CAN_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 "cdx_status.h"
 23#include "cdx_can_bus_id.h"
 24#include "cdx_time.h"
 25#include "cdx_utils.h"
 26#include "cdx_dbc_unpack.h"
 27#include "cdx_dbc_pack.h"
 28#include "cdx_dbc_copy.h"
 29
 30#ifdef __cplusplus
 31extern "C" {
 32#endif
 33
 34//! @defgroup CDX_CAN CDX Model CAN API
 35//! @brief Foreground-only access to the model's sole logical IPC bus.
 36//! @details IPC maps to CM7's Model IPC/CAN3 port, not a physical CM4 CAN
 37//! controller. Call from model callbacks, not interrupts or concurrent threads.
 38//! @{
 39//=============================================================================
 40// Definitions
 41//=============================================================================
 42
 43//! @brief Aligned eight-byte payload chunk with unsigned access views.
 44typedef union CDX_DATA_64_UNION
 45{
 46    uint64_t u64;       //!< Native-endian 64-bit view of the chunk.
 47    uint32_t u32[2];    //!< Two native-endian 32-bit words in storage order.
 48    uint16_t u16[4];    //!< Four native-endian 16-bit words in storage order.
 49    uint8_t u8[8];      //!< Eight bytes in payload order; u8[0] is first.
 50} CDX_DATA_64;
 51
 52//! @brief CDX flags; these values are not the Model IPC wire flag encoding.
 53typedef uint16_t CDX_CAN_FRAME_FLAGS;
 54//! @brief Classic frame with a standard 11-bit identifier.
 55#define CDX_CAN_FRAME_FLAG_NONE 0u
 56//! @brief Extended 29-bit identifier.
 57#define CDX_CAN_FRAME_FLAG_IDE 0x0001u
 58//! @brief CAN-FD payload, up to 64 bytes instead of the classic 8-byte limit.
 59#define CDX_CAN_FRAME_FLAG_EDL 0x0008u
 60//! @brief CAN-FD bit-rate switch; valid only with EDL.
 61#define CDX_CAN_FRAME_FLAG_BRS 0x0010u
 62//! @brief Ignore deadline_ticks when enqueueing and publishing this TX frame.
 63#define CDX_CAN_FRAME_FLAG_DISABLE_DEADLINE 0x0100u
 64
 65//=============================================================================
 66// Types
 67//=============================================================================
 68
 69//! @brief Received frame; the frame and data are valid only during RX callback.
 70typedef struct CDX_CAN_FRAME_STRUCT
 71{
 72    uint32_t id;                         //!< Raw 11-bit or 29-bit CAN identifier.
 73    CDX_CAN_BUS_ID bus;                   //!< CDX_CAN_BUS_ID_IPC for Model IPC.
 74    uint8_t error_type;                   //!< Zero; error frames are not supported.
 75    CDX_CAN_FRAME_FLAGS flags;            //!< IDE, EDL and BRS frame attributes.
 76    CDX_TICKS_32 timestamp_ticks;         //!< Receiver-local arrival microseconds.
 77    uint32_t hw_timestamp;               //!< Zero; no physical CAN timestamp.
 78    uint16_t length_bytes;               //!< Payload bytes: classic 0..8, FD 0..64.
 79    uint8_t data_chunks;                 //!< Number of chunks, ceil(length_bytes/8).
 80    uint8_t reserved;                    //!< Zero; reserved for future API use.
 81    CDX_DATA_64 const* data;              //!< Borrowed aligned chunks; copy to retain.
 82} CDX_CAN_FRAME;
 83
 84//! @brief TX request copied during enqueue; zero-initialize before filling it.
 85typedef struct CDX_CAN_TX_PARAMS_STRUCT
 86{
 87    uint32_t id;                         //!< Raw 11-bit or 29-bit CAN identifier.
 88    CDX_CAN_FRAME_FLAGS flags;            //!< Frame attributes and TX policy flags.
 89    uint16_t length_bytes;               //!< Payload bytes: classic 0..8, FD 0..64.
 90    CDX_TICKS_32 deadline_ticks;          //!< Absolute local ticks; zero disables expiry.
 91} CDX_CAN_TX_PARAMS;
 92
 93//=============================================================================
 94// Inline Functions
 95//=============================================================================
 96
 97//-----------------------------------------------------------------------------
 98//! @brief Test for a classic standard-ID frame.
 99//! @param flags Frame flags; policy and other attribute bits are ignored.
100//! @return Nonzero if both IDE and EDL are clear.
101static inline int CDX_can_frame_flags_is_std(CDX_CAN_FRAME_FLAGS flags)
102{
103    return (flags & (CDX_CAN_FRAME_FLAG_IDE | CDX_CAN_FRAME_FLAG_EDL)) == 0u;
104}
105//-----------------------------------------------------------------------------
106//! @brief Test for a classic extended-ID frame.
107//! @param flags Frame flags; policy and other attribute bits are ignored.
108//! @return Nonzero if IDE is set and EDL is clear.
109static inline int CDX_can_frame_flags_is_ext(CDX_CAN_FRAME_FLAGS flags)
110{
111    return (flags & (CDX_CAN_FRAME_FLAG_IDE | CDX_CAN_FRAME_FLAG_EDL)) == CDX_CAN_FRAME_FLAG_IDE;
112}
113//-----------------------------------------------------------------------------
114//! @brief Test for a CAN-FD standard-ID frame.
115//! @param flags Frame flags; policy and other attribute bits are ignored.
116//! @return Nonzero if EDL is set and IDE is clear.
117static inline int CDX_can_frame_flags_is_fd_std(CDX_CAN_FRAME_FLAGS flags)
118{
119    return (flags & (CDX_CAN_FRAME_FLAG_IDE | CDX_CAN_FRAME_FLAG_EDL)) == CDX_CAN_FRAME_FLAG_EDL;
120}
121//-----------------------------------------------------------------------------
122//! @brief Test for a CAN-FD extended-ID frame.
123//! @param flags Frame flags; policy and other attribute bits are ignored.
124//! @return Nonzero if both IDE and EDL are set.
125static inline int CDX_can_frame_flags_is_fd_ext(CDX_CAN_FRAME_FLAGS flags)
126{
127    return (flags & (CDX_CAN_FRAME_FLAG_IDE | CDX_CAN_FRAME_FLAG_EDL)) ==
128        (CDX_CAN_FRAME_FLAG_IDE | CDX_CAN_FRAME_FLAG_EDL);
129}
130
131//=============================================================================
132// Prototypes
133//=============================================================================
134
135//-----------------------------------------------------------------------------
136//! @brief Copy a TX request and payload into the nonblocking Model IPC queue.
137//! @param bus Sole logical bus: CDX_CAN_BUS_ID_IPC (legacy CAN1 is an alias).
138//! @param params Nonnull request, with supported flags, ID and byte length.
139//! @param data Aligned payload chunks containing length_bytes bytes; may be
140//! NULL only for an empty payload. Storage may be reused after this call.
141//! @retval CDX_STATUS_OK Copied and accepted; not yet delivered to the peer.
142//! @retval CDX_STATUS_BAD_PARAM Invalid bus, pointer, flags, ID or length.
143//! @retval CDX_STATUS_IPC_OFFLINE No bound RUNNING runtime or IPC session lost.
144//! @retval CDX_STATUS_TIMEOUT Nonzero, enabled deadline has already expired.
145//! @retval CDX_STATUS_QUEUE_FULL Newest frame rejected; runtime drop count rises.
146//! @note There are no TX completion callbacks. Acceptance does not guarantee
147//! publication, physical CAN delivery or model execution. Queued frames may
148//! expire or be discarded on IPC fault. Published batches remain owned by the
149//! peer until acknowledgement; they cannot be cancelled by expiry.
150CDX_STATUS CDX_can_tx_enqueue_copy(CDX_CAN_BUS_ID bus,
151    CDX_CAN_TX_PARAMS const* params, CDX_DATA_64 const* data);
152
153//-----------------------------------------------------------------------------
154//! @brief Test elapsed local milliseconds using unsigned wrap-safe subtraction.
155//! @param received_ms Recent past timestamp from the local millisecond clock.
156//! @param timeout_ms Timeout interval; zero always times out.
157//! @return Nonzero if elapsed milliseconds are at least timeout_ms.
158//! @note The timestamp must be less than one millisecond-counter wrap old.
159int CDX_can_is_timed_out_ms(CDX_MILLISEC_32 received_ms, CDX_MILLISEC_32 timeout_ms);
160
161//-----------------------------------------------------------------------------
162//! @copydoc CDX_dbc_unpack_u32_le
163uint32_t CDX_can_read_signal_u32_le(void const* buffer, uint32_t size, uint16_t offset, uint8_t bits);
164
165//-----------------------------------------------------------------------------
166//! @copydoc CDX_dbc_unpack_u64_le
167uint64_t CDX_can_read_signal_u64_le(void const* buffer, uint32_t size, uint16_t offset, uint8_t bits);
168
169//-----------------------------------------------------------------------------
170//! @copydoc CDX_dbc_unpack_u32_be
171uint32_t CDX_can_read_signal_u32_be(void const* buffer, uint32_t size, uint16_t offset, uint8_t bits);
172
173//-----------------------------------------------------------------------------
174//! @copydoc CDX_dbc_unpack_u64_be
175uint64_t CDX_can_read_signal_u64_be(void const* buffer, uint32_t size, uint16_t offset, uint8_t bits);
176
177//! @}
178#ifdef __cplusplus
179} // extern "C"
180#endif
181
182//=============================================================================
183#endif // CDX_CAN_H_INCLUDED
184//=============================================================================
185// End of File
186//=============================================================================