cdx_app_functions.h Source

 1//=============================================================================
 2//! @file
 3//! @author GEMS
 4//! @date   7 October 2026
 5//! @brief Statically linked callbacks required from the client model.
 6//=============================================================================
 7
 8#ifndef CDX_APP_FUNCTIONS_H_INCLUDED
 9#define CDX_APP_FUNCTIONS_H_INCLUDED
10//=============================================================================
11
12//=============================================================================
13// Includes
14//=============================================================================
15
16#if defined(CDX_USER_HEADER) && !defined(CDX_USER_H_INCLUDED)
17#include CDX_USER_HEADER
18#endif
19
20#include "cdx_can.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26//! @defgroup CDX_APP_FUNCTIONS Application Callbacks
27//! @brief Functions that the client model must implement with C linkage.
28//! @details Called serially in foreground, never from an interrupt. Simulation
29//! implementations may forward these entry points to dynamically bound models.
30//! @{
31
32//=============================================================================
33// Prototypes
34//=============================================================================
35
36//-----------------------------------------------------------------------------
37//! @brief Initialize application resources once during CM4 startup.
38//! @retval CDX_STATUS_OK Application setup succeeded.
39//! @return Any other status faults the runtime before period/model initialization
40//! and prevents READY. A model without system setup must return CDX_STATUS_OK.
41//! @note Called after platform setup, runtime binding and IPC validation, before
42//! CDX_app_model_period_us_get and CDX_app_model_init. Time and memory APIs are
43//! available; TX enqueue remains offline. Do not initialize runtime-owned MU,
44//! PIT, cache or shared IPC resources here. A CM4 reset/reload calls it again.
45CDX_STATUS CDX_app_system_init(void);
46
47//-----------------------------------------------------------------------------
48//! @brief Return the fixed execution period after application system setup.
49//! @return Period in microseconds, in the range 1..INT32_MAX.
50//! @note Called after CDX_app_system_init and before CDX_app_model_init. The
51//! runtime is bound; configuration loaded by system initialization may be used.
52uint32_t CDX_app_model_period_us_get(void);
53
54//-----------------------------------------------------------------------------
55//! @brief Initialize the model before the runtime publishes READY.
56//! @retval CDX_STATUS_OK Initialization succeeded.
57//! @return Any other status faults the model and prevents RUNNING.
58//! @note System initialization and period validation have succeeded before this
59//! call. The runtime is bound; TX enqueue remains offline.
60CDX_STATUS CDX_app_model_init(void);
61
62//-----------------------------------------------------------------------------
63//! @brief Execute one due model step after queued RX callbacks.
64//! @retval CDX_STATUS_OK Step completed successfully.
65//! @return Any other status faults the model and discards queued TX frames.
66//! @note Called only while RUNNING; missed periods are counted, not replayed.
67CDX_STATUS CDX_app_model_step(void);
68
69//-----------------------------------------------------------------------------
70//! @brief Process one received CAN/FD frame before the next model step.
71//! @param frame Nonnull borrowed frame; its payload is valid only in this call.
72//! @retval CDX_STATUS_OK Frame handled.
73//! @retval CDX_STATUS_MESSAGE_IGNORED Frame intentionally ignored.
74//! @retval CDX_STATUS_MULTIPLEX_IGNORED Multiplexed frame not selected.
75//! @retval CDX_STATUS_NO_DATA No applicable data.
76//! @return Any other status faults the model; implement an ignored result if
77//! the application does not handle received frames. Copy data to retain it.
78CDX_STATUS CDX_app_can_rx_handle(CDX_CAN_FRAME const* frame);
79
80//! @}
81#ifdef __cplusplus
82} // extern "C"
83#endif
84
85//=============================================================================
86#endif // CDX_APP_FUNCTIONS_H_INCLUDED
87//=============================================================================
88// End of File
89//=============================================================================