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