1//=============================================================================
2//! @file
3//! @author GEMS
4//! @brief Foreground model access to low-latency ADC snapshots and physical CAN.
5//=============================================================================
6#ifndef CDX_FAST_IO_H_INCLUDED
7#define CDX_FAST_IO_H_INCLUDED
8
9#include "cdx_can.h"
10
11//-----------------------------------------------------------------------------
12#ifdef __cplusplus
13extern "C" {
14#endif
15
16//=============================================================================
17// Types
18//=============================================================================
19
20//! @brief Completed external ADC scan; channels are sequentially sampled.
21typedef struct CDX_ADC_SNAPSHOT_STRUCT
22{
23 uint32_t sequence; //!< Publication counter; wraps modulo 2^32.
24 uint32_t timestamp_us; //!< CM7-local (dash) scan-completion time, not CM4 (model) ticks.
25 uint32_t valid_mask; //!< Bit per available external input, zero on fault.
26 uint16_t raw[8]; //!< External inputs 1..8, unsigned 12-bit averaged ADC.
27} CDX_ADC_SNAPSHOT;
28
29//=============================================================================
30// Data
31//=============================================================================
32
33//-----------------------------------------------------------------------------
34//! @brief Model-owned ADC raw input cache, refreshed once before each model step.
35//! @note Bind read-only Simulink ImportedExtern data stores to these symbols.
36//! These values should not be modified by the model.
37extern uint16_t CDX_model_adc_raw[8];
38//-----------------------------------------------------------------------------
39//! @brief Validity mask for the ADC raw input cache. Each bit corresponds to one channel.
40//! @details Each bit in CDX_model_adc_valid_mask corresponds to one channel in
41//! CDX_model_adc_raw.
42//! A set bit indicates that the corresponding ADC value is valid.
43//! @note Values are held on failure but the valid_mask is cleared.
44extern uint32_t CDX_model_adc_valid_mask;
45//-----------------------------------------------------------------------------
46//! @brief Sequence number for the ADC snapshot.
47//! @note Incremented on each new snapshot.
48extern uint32_t CDX_model_adc_sequence;
49//-----------------------------------------------------------------------------
50//! @brief Timestamp of the ADC snapshot in microseconds.
51//! @note Wraps at 2^32 microseconds.
52extern uint32_t CDX_model_adc_timestamp_us;
53//-----------------------------------------------------------------------------
54//! @brief Indicates whether the ADC snapshot is fresh for this session.
55//! @details CDX_model_adc_fresh is true if the ADC snapshot was updated by the
56//! Dash processor.
57extern uint8_t CDX_model_adc_fresh;
58
59//=============================================================================
60// Prototypes
61//=============================================================================
62//-----------------------------------------------------------------------------
63//! @brief Copy a consistent external ADC scan without waiting for the Dash loop.
64//! @param snapshot Nonnull output; unchanged on failure. Copy once at step entry.
65//! @return OK, BAD_PARAM, IPC_OFFLINE for absent/stale fast extension, or NO_DATA
66//! for an invalid scan or concurrent publication after two bounded attempts.
67//! @note Model callbacks only; no concurrent callers. Repeated reads can return
68//! the same sequence. No engineering scaling is applied. Timestamp wraps at
69//! 2^32 microseconds and is not directly comparable with CDX_ticks_now().
70CDX_STATUS CDX_adc_snapshot_read(CDX_ADC_SNAPSHOT* snapshot);
71
72//-----------------------------------------------------------------------------
73//! @brief Refresh the input cache with one bounded snapshot read.
74//! @param now_us Current CM4-local microseconds, sampled once at step entry.
75//! @param max_stale_us Maximum time without a new scan, 1..1000000 us.
76//! @return OK for usable cached data, TIMEOUT for stale data, or snapshot error.
77//! @note Foreground only. Timestamp remains CM7-local; staleness is measured
78//! independently using now_us. Rebinding the runtime resets this cache.
79CDX_STATUS CDX_model_inputs_refresh(uint32_t now_us, uint32_t max_stale_us);
80
81//-----------------------------------------------------------------------------
82//! @name Cached external ADC channel getters
83//! @brief Read external inputs 1..8 from the last model input refresh.
84//! @return Raw getters return ADC counts; voltage getters return nominal volts
85//! using 0.001421 V/count, matching CD6-Main-IPC-sample.dbc (no calibration).
86//! @note Foreground only. No acquisition occurs. Values remain held on failure;
87//! check the corresponding CDX_model_adc_valid_mask bit before using either form.
88//! @{
89
90//! @brief Read cached external input 1 in raw ADC counts.
91//! @return Held 12-bit ADC counts; check CDX_get_adc_1_valid() before use.
92//! @note Foreground only; refresh the input cache once before the model step.
93uint16_t CDX_get_adc_1_raw(void);
94//! @brief Read cached external input 2 in raw ADC counts.
95//! @return Held 12-bit ADC counts; check CDX_get_adc_2_valid() before use.
96//! @note Foreground only; refresh the input cache once before the model step.
97uint16_t CDX_get_adc_2_raw(void);
98//! @brief Read cached external input 3 in raw ADC counts.
99//! @return Held 12-bit ADC counts; check CDX_get_adc_3_valid() before use.
100//! @note Foreground only; refresh the input cache once before the model step.
101uint16_t CDX_get_adc_3_raw(void);
102//! @brief Read cached external input 4 in raw ADC counts.
103//! @return Held 12-bit ADC counts; check CDX_get_adc_4_valid() before use.
104//! @note Foreground only; refresh the input cache once before the model step.
105uint16_t CDX_get_adc_4_raw(void);
106//! @brief Read cached external input 5 in raw ADC counts.
107//! @return Held 12-bit ADC counts; check CDX_get_adc_5_valid() before use.
108//! @note Foreground only; refresh the input cache once before the model step.
109uint16_t CDX_get_adc_5_raw(void);
110//! @brief Read cached external input 6 in raw ADC counts.
111//! @return Held 12-bit ADC counts; check CDX_get_adc_6_valid() before use.
112//! @note Foreground only; refresh the input cache once before the model step.
113uint16_t CDX_get_adc_6_raw(void);
114//! @brief Read cached external input 7 in raw ADC counts.
115//! @return Held 12-bit ADC counts; check CDX_get_adc_7_valid() before use.
116//! @note Foreground only; refresh the input cache once before the model step.
117uint16_t CDX_get_adc_7_raw(void);
118//! @brief Read cached external input 8 in raw ADC counts.
119//! @return Held 12-bit ADC counts; check CDX_get_adc_8_valid() before use.
120//! @note Foreground only; refresh the input cache once before the model step.
121uint16_t CDX_get_adc_8_raw(void);
122//! @brief Read cached external input 1 in nominal volts without calibration.
123//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_1_valid().
124//! @note Foreground only; refresh the input cache once before the model step.
125float CDX_get_adc_1_voltage(void);
126//! @brief Read cached external input 2 in nominal volts without calibration.
127//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_2_valid().
128//! @note Foreground only; refresh the input cache once before the model step.
129float CDX_get_adc_2_voltage(void);
130//! @brief Read cached external input 3 in nominal volts without calibration.
131//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_3_valid().
132//! @note Foreground only; refresh the input cache once before the model step.
133float CDX_get_adc_3_voltage(void);
134//! @brief Read cached external input 4 in nominal volts without calibration.
135//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_4_valid().
136//! @note Foreground only; refresh the input cache once before the model step.
137float CDX_get_adc_4_voltage(void);
138//! @brief Read cached external input 5 in nominal volts without calibration.
139//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_5_valid().
140//! @note Foreground only; refresh the input cache once before the model step.
141float CDX_get_adc_5_voltage(void);
142//! @brief Read cached external input 6 in nominal volts without calibration.
143//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_6_valid().
144//! @note Foreground only; refresh the input cache once before the model step.
145float CDX_get_adc_6_voltage(void);
146//! @brief Read cached external input 7 in nominal volts without calibration.
147//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_7_valid().
148//! @note Foreground only; refresh the input cache once before the model step.
149float CDX_get_adc_7_voltage(void);
150//! @brief Read cached external input 8 in nominal volts without calibration.
151//! @return Held ADC counts times 0.001421 V/count; check CDX_get_adc_8_valid().
152//! @note Foreground only; refresh the input cache once before the model step.
153float CDX_get_adc_8_voltage(void);
154//! @}
155
156//-----------------------------------------------------------------------------
157//! @name Cached external ADC validity getters
158//! @brief Test the corresponding input 1..8 bit in CDX_model_adc_valid_mask.
159//! @return 1 for valid cached data, otherwise 0 (including stale/offline scans).
160//! @note Foreground only; no acquisition. Refresh the cache once before step.
161//! @{
162
163//! @brief Test whether cached external input 1 is valid.
164//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
165//! @note Foreground only; no acquisition. Refresh the cache once before step.
166uint8_t CDX_get_adc_1_valid(void);
167//! @brief Test whether cached external input 2 is valid.
168//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
169//! @note Foreground only; no acquisition. Refresh the cache once before step.
170uint8_t CDX_get_adc_2_valid(void);
171//! @brief Test whether cached external input 3 is valid.
172//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
173//! @note Foreground only; no acquisition. Refresh the cache once before step.
174uint8_t CDX_get_adc_3_valid(void);
175//! @brief Test whether cached external input 4 is valid.
176//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
177//! @note Foreground only; no acquisition. Refresh the cache once before step.
178uint8_t CDX_get_adc_4_valid(void);
179//! @brief Test whether cached external input 5 is valid.
180//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
181//! @note Foreground only; no acquisition. Refresh the cache once before step.
182uint8_t CDX_get_adc_5_valid(void);
183//! @brief Test whether cached external input 6 is valid.
184//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
185//! @note Foreground only; no acquisition. Refresh the cache once before step.
186uint8_t CDX_get_adc_6_valid(void);
187//! @brief Test whether cached external input 7 is valid.
188//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
189//! @note Foreground only; no acquisition. Refresh the cache once before step.
190uint8_t CDX_get_adc_7_valid(void);
191//! @brief Test whether cached external input 8 is valid.
192//! @return 1 for valid cached data, otherwise 0, including stale/offline scans.
193//! @note Foreground only; no acquisition. Refresh the cache once before step.
194uint8_t CDX_get_adc_8_valid(void);
195//! @}
196
197//-----------------------------------------------------------------------------
198//! @brief Copy an urgent physical CAN frame, bypassing Dash Output processing.
199//! @param port Physical CAN port: 0 for CAN1, 1 for CAN2 (not logical IPC).
200//! @param params Nonnull frame description; deadline_ticks must be zero and only
201//! IDE, EDL and BRS flags are supported. FD lengths must match a CAN-FD DLC.
202//! Use lifetime_us for expiry instead.
203//! @param data Copied aligned payload; NULL only when length_bytes is zero.
204//! @param lifetime_us Maximum age, 1..1000000 us, from the latest CM7 fast clock
205//! publication. Expiry is conservative by clock-publication age, not extended.
206//! @return OK, BAD_PARAM, IPC_OFFLINE or QUEUE_FULL (newest request rejected).
207//! @note Model callbacks only, never interrupts or concurrent threads. Four
208//! frames per physical port. Acceptance is not delivery; unavailable ports,
209//! expiry, bus errors, stop/reset and session changes can discard requests.
210//! No completion callback or cancellation; an in-progress CAN frame cannot be
211//! preempted. Configured bus mode and CAN arbitration still apply.
212CDX_STATUS CDX_can_tx_urgent_enqueue(uint32_t port, CDX_CAN_TX_PARAMS const* params,
213 CDX_DATA_64 const* data, uint32_t lifetime_us);
214
215//-----------------------------------------------------------------------------
216#ifdef __cplusplus
217}
218#endif
219
220#endif // CDX_FAST_IO_H_INCLUDED
221//=============================================================================
222// End of File
223//=============================================================================