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