Line data Source code
1 1 : /*
2 : * Copyright 2025 NXP
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Single Edge Nibble Transmission (SENT) driver API.
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_SENT_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_SENT_H_
14 :
15 : #include <zephyr/kernel.h>
16 : #include <zephyr/device.h>
17 :
18 : #ifdef __cplusplus
19 : extern "C" {
20 : #endif
21 :
22 : /**
23 : * @brief SENT Interface
24 : * @defgroup sent_interface SENT Interface
25 : * @since 4.2
26 : * @version 0.1.0
27 : * @ingroup io_interfaces
28 : * @{
29 : */
30 :
31 : /**
32 : * @brief SENT frame type
33 : */
34 1 : enum sent_frame_type {
35 : /** Short serial message frame */
36 : SENT_SHORT_SERIAL_FRAME,
37 : /** Enhanced serial message frame with 4-bit message ID */
38 : SENT_ENHANCED_SERIAL_FRAME_4_BIT_ID,
39 : /** Enhanced serial message frame with 8-bit message ID */
40 : SENT_ENHANCED_SERIAL_FRAME_8_BIT_ID,
41 : /** Fast message frame */
42 : SENT_FAST_FRAME
43 : };
44 :
45 : /**
46 : * @brief Maximum number of data nibbles
47 : */
48 1 : #define SENT_MAX_DATA_NIBBLES 8
49 :
50 : /**
51 : * @brief SENT frame structure
52 : */
53 1 : struct sent_frame {
54 : /** Type of SENT frame */
55 1 : enum sent_frame_type type;
56 :
57 : union {
58 : /**
59 : * @brief Serial message
60 : */
61 : struct {
62 : /** Serial message ID */
63 1 : uint8_t id;
64 :
65 : /** Serial message data */
66 1 : uint16_t data;
67 1 : } serial;
68 :
69 : /**
70 : * @brief Fast message
71 : */
72 : struct {
73 : /** Array of fast message data nibbles */
74 1 : uint8_t data_nibbles[SENT_MAX_DATA_NIBBLES];
75 1 : } fast;
76 0 : };
77 :
78 : /** Timestamp of when the frame was captured */
79 1 : uint32_t timestamp;
80 :
81 : /** CRC checksum for message integrity validation */
82 1 : uint8_t crc;
83 : };
84 :
85 : /**
86 : * @brief Defines the application callback handler function signature for receiving frame.
87 : *
88 : * @param dev Pointer to the device structure for the driver instance.
89 : * @param channel The hardware channel of the driver instance.
90 : * @param num_frame Number of received frame.
91 : * @param user_data User data provided when receiving frame.
92 : */
93 1 : typedef void (*sent_rx_frame_callback_t)(const struct device *dev, uint8_t channel,
94 : uint32_t num_frame, void *user_data);
95 :
96 : /** @cond INTERNAL_HIDDEN */
97 :
98 : /**
99 : * @brief Callback API upon starting receive frame
100 : * See @a sent_start_listening() for argument description
101 : */
102 : typedef int (*sent_start_listening_t)(const struct device *dev, uint8_t channel);
103 :
104 : /**
105 : * @brief Callback API upon stopping receive frame
106 : * See @a sent_stop_listening() for argument description
107 : */
108 : typedef int (*sent_stop_listening_t)(const struct device *dev, uint8_t channel);
109 :
110 : /**
111 : * @brief Configuration structure for RX callback
112 : */
113 : struct sent_rx_callback_config {
114 : /** Callback function invoked on frame reception */
115 : sent_rx_frame_callback_t callback;
116 : /** Pointer to the buffer for storing received frames */
117 : struct sent_frame *frame;
118 : /** Maximum number of frames to store */
119 : uint32_t max_num_frame;
120 : /** Pointer to user data passed to the callback */
121 : void *user_data;
122 : };
123 :
124 : /**
125 : * @brief Composite configuration structure for RX callback registration
126 : */
127 : struct sent_rx_callback_configs {
128 : /** Configuration for the serial message callback */
129 : struct sent_rx_callback_config *serial;
130 : /** Configuration for the fast message callback */
131 : struct sent_rx_callback_config *fast;
132 : };
133 :
134 : /**
135 : * @brief Callback API upon adding RX callback
136 : * See @a sent_register_callback() for argument description
137 : */
138 : typedef int (*sent_register_callback_t)(const struct device *dev, uint8_t channel,
139 : struct sent_rx_callback_configs callback_configs);
140 :
141 : __subsystem struct sent_driver_api {
142 : sent_start_listening_t start_listening;
143 : sent_stop_listening_t stop_listening;
144 : sent_register_callback_t register_callback;
145 : };
146 :
147 : /** @endcond */
148 :
149 : /**
150 : * @brief Enable a specific channel to start receiving from the bus
151 : *
152 : * @param dev Pointer to the device structure for the driver instance.
153 : * @param channel The hardware channel of the driver instance.
154 : * @retval 0 successful.
155 : * @retval -EINVAL invalid channel is given.
156 : * @retval -EALREADY device is already started.
157 : * @retval -EIO general input/output error, failed to start device.
158 : */
159 1 : __syscall int sent_start_listening(const struct device *dev, uint8_t channel);
160 :
161 : static inline int z_impl_sent_start_listening(const struct device *dev, uint8_t channel)
162 : {
163 : const struct sent_driver_api *api = (const struct sent_driver_api *)dev->api;
164 :
165 : if (api->start_listening) {
166 : return api->start_listening(dev, channel);
167 : }
168 :
169 : return -ENOSYS;
170 : }
171 :
172 : /**
173 : * @brief Disable a specific channel to stop receiving from the bus
174 : *
175 : * @param dev Pointer to the device structure for the driver instance.
176 : * @param channel The hardware channel of the driver instance.
177 : * @retval 0 successful.
178 : * @retval -EINVAL invalid channel.
179 : * @retval -EALREADY device is already stopped.
180 : * @retval -EIO general input/output error, failed to stop device.
181 : */
182 1 : __syscall int sent_stop_listening(const struct device *dev, uint8_t channel);
183 :
184 : static inline int z_impl_sent_stop_listening(const struct device *dev, uint8_t channel)
185 : {
186 : const struct sent_driver_api *api = (const struct sent_driver_api *)dev->api;
187 :
188 : if (api->stop_listening) {
189 : return api->stop_listening(dev, channel);
190 : }
191 :
192 : return -ENOSYS;
193 : }
194 :
195 : /**
196 : * @brief Add a callback function to handle messages received for a specific channel
197 : *
198 : * @param dev Pointer to the device structure for the driver instance.
199 : * @param channel The hardware channel of the driver instance.
200 : * @param callback_configs The callback configurations.
201 : * @retval 0 successful.
202 : * @retval -EINVAL invalid channel.
203 : */
204 1 : __syscall int sent_register_callback(const struct device *dev, uint8_t channel,
205 : struct sent_rx_callback_configs callback_configs);
206 :
207 : static inline int z_impl_sent_register_callback(const struct device *dev, uint8_t channel,
208 : struct sent_rx_callback_configs callback_configs)
209 : {
210 : const struct sent_driver_api *api = (const struct sent_driver_api *)dev->api;
211 :
212 : if (api->register_callback) {
213 : return api->register_callback(dev, channel, callback_configs);
214 : }
215 :
216 : return -ENOSYS;
217 : }
218 :
219 : #ifdef __cplusplus
220 : }
221 : #endif
222 :
223 : /**
224 : * @}
225 : */
226 :
227 : #include <zephyr/syscalls/sent.h>
228 :
229 : #endif /* ZEPHYR_INCLUDE_DRIVERS_SENT_H_ */
|
