cdx_fast_io.h Source

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