Line data Source code
1 1 : /*
2 : * Copyright (c) 2021 Vestas Wind Systems A/S
3 : * Copyright (c) 2018 Karsten Koenig
4 : * Copyright (c) 2018 Alexander Wachter
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : /**
10 : * @file
11 : * @brief Main header file for Controller Area Network (CAN) driver API.
12 : * @ingroup can_controller
13 : */
14 :
15 : #ifndef ZEPHYR_INCLUDE_DRIVERS_CAN_H_
16 : #define ZEPHYR_INCLUDE_DRIVERS_CAN_H_
17 :
18 : #include <errno.h>
19 :
20 : #include <zephyr/types.h>
21 : #include <zephyr/device.h>
22 : #include <zephyr/kernel.h>
23 : #include <string.h>
24 : #include <zephyr/sys_clock.h>
25 : #include <zephyr/sys/util.h>
26 :
27 : #ifdef __cplusplus
28 : extern "C" {
29 : #endif
30 :
31 : /**
32 : * @brief Interfaces for Controller Area Network (CAN) controllers and transceivers
33 : * @defgroup can_interface CAN
34 : * @ingroup io_interfaces
35 : *
36 : * @defgroup can_controller CAN Controller
37 : * @brief Interfaces for CAN controllers
38 : * @ingroup can_interface
39 : * @since 1.12
40 : * @version 1.1.0
41 : *
42 : * @{
43 : */
44 :
45 : /**
46 : * @name CAN frame definitions
47 : * @{
48 : */
49 :
50 : /**
51 : * @brief Bit mask for a standard (11-bit) CAN identifier.
52 : */
53 1 : #define CAN_STD_ID_MASK 0x7FFU
54 :
55 : /**
56 : * @brief Bit mask for an extended (29-bit) CAN identifier.
57 : */
58 1 : #define CAN_EXT_ID_MASK 0x1FFFFFFFU
59 :
60 : /**
61 : * @brief Maximum data length code for CAN 2.0A/2.0B.
62 : */
63 1 : #define CAN_MAX_DLC 8U
64 :
65 : /**
66 : * @brief Maximum data length code for CAN FD.
67 : */
68 1 : #define CANFD_MAX_DLC 15U
69 :
70 : /**
71 : * @cond INTERNAL_HIDDEN
72 : * Internally calculated maximum data length
73 : */
74 : #ifndef CONFIG_CAN_FD_MODE
75 : #define CAN_MAX_DLEN 8U
76 : #else
77 : #define CAN_MAX_DLEN 64U
78 : #endif /* CONFIG_CAN_FD_MODE */
79 :
80 : /** @endcond */
81 :
82 : /** @} */
83 :
84 : /**
85 : * @name CAN controller mode flags
86 : * @anchor CAN_MODE_FLAGS
87 : *
88 : * @{
89 : */
90 :
91 : /** Normal mode. */
92 1 : #define CAN_MODE_NORMAL 0
93 :
94 : /** Controller is in loopback mode (receives own frames). */
95 1 : #define CAN_MODE_LOOPBACK BIT(0)
96 :
97 : /** Controller is not allowed to send dominant bits. */
98 1 : #define CAN_MODE_LISTENONLY BIT(1)
99 :
100 : /** Controller allows transmitting/receiving CAN FD frames. */
101 1 : #define CAN_MODE_FD BIT(2)
102 :
103 : /** Controller does not retransmit in case of lost arbitration or missing ACK */
104 1 : #define CAN_MODE_ONE_SHOT BIT(3)
105 :
106 : /** Controller uses triple sampling mode */
107 1 : #define CAN_MODE_3_SAMPLES BIT(4)
108 :
109 : /** Controller requires manual recovery after entering bus-off state */
110 1 : #define CAN_MODE_MANUAL_RECOVERY BIT(5)
111 :
112 : /** @} */
113 :
114 : /**
115 : * @brief Provides a type to hold CAN controller configuration flags.
116 : *
117 : * The lower 24 bits are reserved for common CAN controller mode flags. The upper 8 bits are
118 : * reserved for CAN controller/driver specific flags.
119 : *
120 : * @see @ref CAN_MODE_FLAGS.
121 : */
122 1 : typedef uint32_t can_mode_t;
123 :
124 : /**
125 : * @brief Defines the state of the CAN controller
126 : */
127 1 : enum can_state {
128 : /** Error-active state (RX/TX error count < 96). */
129 : CAN_STATE_ERROR_ACTIVE,
130 : /** Error-warning state (RX/TX error count < 128). */
131 : CAN_STATE_ERROR_WARNING,
132 : /** Error-passive state (RX/TX error count < 256). */
133 : CAN_STATE_ERROR_PASSIVE,
134 : /** Bus-off state (RX/TX error count >= 256). */
135 : CAN_STATE_BUS_OFF,
136 : /** CAN controller is stopped and does not participate in CAN communication. */
137 : CAN_STATE_STOPPED,
138 : };
139 :
140 : /**
141 : * @name CAN frame flags
142 : * @anchor CAN_FRAME_FLAGS
143 : *
144 : * @{
145 : */
146 :
147 : /** Frame uses extended (29-bit) CAN ID */
148 1 : #define CAN_FRAME_IDE BIT(0)
149 :
150 : /** Frame is a Remote Transmission Request (RTR) */
151 1 : #define CAN_FRAME_RTR BIT(1)
152 :
153 : /** Frame uses CAN FD format (FDF) */
154 1 : #define CAN_FRAME_FDF BIT(2)
155 :
156 : /** Frame uses CAN FD Baud Rate Switch (BRS). Only valid in combination with ``CAN_FRAME_FDF``. */
157 1 : #define CAN_FRAME_BRS BIT(3)
158 :
159 : /** CAN FD Error State Indicator (ESI). Indicates that the transmitting node is in error-passive
160 : * state. Only valid in combination with ``CAN_FRAME_FDF``.
161 : */
162 1 : #define CAN_FRAME_ESI BIT(4)
163 :
164 : /** @} */
165 :
166 : /**
167 : * @brief CAN frame structure
168 : */
169 1 : struct can_frame {
170 : /** Standard (11-bit) or extended (29-bit) CAN identifier. */
171 1 : uint32_t id;
172 : /** Data Length Code (DLC) indicating data length in bytes. */
173 1 : uint8_t dlc;
174 : /** Flags. @see @ref CAN_FRAME_FLAGS. */
175 1 : uint8_t flags;
176 : #if defined(CONFIG_CAN_RX_TIMESTAMP) || defined(__DOXYGEN__)
177 : /** Captured value of the free-running timer in the CAN controller when
178 : * this frame was received. The timer is incremented every bit time and
179 : * captured at the start of frame bit (SOF).
180 : *
181 : * @note @kconfig{CONFIG_CAN_RX_TIMESTAMP} must be selected for this
182 : * field to be available.
183 : */
184 1 : uint16_t timestamp;
185 : #else
186 : /** @cond INTERNAL_HIDDEN */
187 : /** Padding. */
188 : uint16_t reserved;
189 : /** @endcond */
190 : #endif
191 : /** The frame payload data. */
192 : union {
193 : /** Payload data accessed as unsigned 8 bit values. */
194 1 : uint8_t data[CAN_MAX_DLEN];
195 : /** Payload data accessed as unsigned 32 bit values. */
196 1 : uint32_t data_32[DIV_ROUND_UP(CAN_MAX_DLEN, sizeof(uint32_t))];
197 1 : };
198 : };
199 :
200 : /**
201 : * @name CAN filter flags
202 : * @anchor CAN_FILTER_FLAGS
203 : *
204 : * @{
205 : */
206 :
207 : /** Filter matches frames with extended (29-bit) CAN IDs */
208 1 : #define CAN_FILTER_IDE BIT(0)
209 :
210 : /** @} */
211 :
212 : /**
213 : * @brief CAN filter structure
214 : */
215 1 : struct can_filter {
216 : /** CAN identifier to match. */
217 1 : uint32_t id;
218 : /** CAN identifier matching mask. If a bit in this mask is 0, the value
219 : * of the corresponding bit in the ``id`` field is ignored by the filter.
220 : */
221 1 : uint32_t mask;
222 : /** Flags. @see @ref CAN_FILTER_FLAGS. */
223 1 : uint8_t flags;
224 : };
225 :
226 : /**
227 : * @brief CAN controller error counters
228 : */
229 1 : struct can_bus_err_cnt {
230 : /** Value of the CAN controller transmit error counter. */
231 1 : uint8_t tx_err_cnt;
232 : /** Value of the CAN controller receive error counter. */
233 1 : uint8_t rx_err_cnt;
234 : };
235 :
236 : /**
237 : * @brief CAN bus timing structure
238 : *
239 : * This struct is used to pass bus timing values to the configuration and
240 : * bitrate calculation functions.
241 : *
242 : * The propagation segment represents the time of the signal propagation. Phase
243 : * segment 1 and phase segment 2 define the sampling point. The ``prop_seg`` and
244 : * ``phase_seg1`` values affect the sampling point in the same way and some
245 : * controllers only have a register for the sum of those two. The sync segment
246 : * always has a length of 1 time quantum (see below).
247 : *
248 : * @code{.text}
249 : *
250 : * +---------+----------+------------+------------+
251 : * |sync_seg | prop_seg | phase_seg1 | phase_seg2 |
252 : * +---------+----------+------------+------------+
253 : * ^
254 : * Sampling-Point
255 : *
256 : * @endcode
257 : *
258 : * 1 time quantum (tq) has the length of 1/(core_clock / prescaler). The bitrate
259 : * is defined by the core clock divided by the prescaler and the sum of the
260 : * segments:
261 : *
262 : * br = (core_clock / prescaler) / (1 + prop_seg + phase_seg1 + phase_seg2)
263 : *
264 : * The Synchronization Jump Width (SJW) defines the amount of time quanta the
265 : * sample point can be moved. The sample point is moved when resynchronization
266 : * is needed.
267 : */
268 1 : struct can_timing {
269 : /** Synchronisation jump width. */
270 1 : uint16_t sjw;
271 : /** Propagation segment. */
272 1 : uint16_t prop_seg;
273 : /** Phase segment 1. */
274 1 : uint16_t phase_seg1;
275 : /** Phase segment 2. */
276 1 : uint16_t phase_seg2;
277 : /** Prescaler value. */
278 1 : uint16_t prescaler;
279 : };
280 :
281 : /**
282 : * @brief Defines the application callback handler function signature
283 : *
284 : * @param dev Pointer to the device structure for the driver instance.
285 : * @param error Status of the performed send operation. See the list of
286 : * return values for @a can_send() for value descriptions.
287 : * @param user_data User data provided when the frame was sent.
288 : */
289 1 : typedef void (*can_tx_callback_t)(const struct device *dev, int error, void *user_data);
290 :
291 : /**
292 : * @brief Defines the application callback handler function signature for receiving.
293 : *
294 : * @param dev Pointer to the device structure for the driver instance.
295 : * @param frame Received frame.
296 : * @param user_data User data provided when the filter was added.
297 : */
298 1 : typedef void (*can_rx_callback_t)(const struct device *dev, struct can_frame *frame,
299 : void *user_data);
300 :
301 : /**
302 : * @brief Defines the state change callback handler function signature
303 : *
304 : * @param dev Pointer to the device structure for the driver instance.
305 : * @param state State of the CAN controller.
306 : * @param err_cnt CAN controller error counter values.
307 : * @param user_data User data provided the callback was set.
308 : */
309 1 : typedef void (*can_state_change_callback_t)(const struct device *dev,
310 : enum can_state state,
311 : struct can_bus_err_cnt err_cnt,
312 : void *user_data);
313 :
314 : /**
315 : * @cond INTERNAL_HIDDEN
316 : *
317 : * For internal driver use only, skip these in public documentation.
318 : */
319 :
320 : /**
321 : * @brief Calculate Transmitter Delay Compensation Offset from data phase timing parameters.
322 : *
323 : * Calculates the TDC Offset in minimum time quanta (mtq) using the sample point and CAN core clock
324 : * prescaler specified by a set of data phase timing parameters.
325 : *
326 : * The result is clamped to the minimum/maximum supported TDC Offset values provided.
327 : *
328 : * @param _timing_data Pointer to data phase timing parameters.
329 : * @param _tdco_min Minimum supported TDC Offset value in mtq.
330 : * @param _tdco_max Maximum supported TDC Offset value in mtq.
331 : * @return Calculated TDC Offset value in mtq.
332 : */
333 : #define CAN_CALC_TDCO(_timing_data, _tdco_min, _tdco_max) \
334 : CLAMP((1U + _timing_data->prop_seg + _timing_data->phase_seg1) * _timing_data->prescaler, \
335 : _tdco_min, _tdco_max)
336 :
337 : /**
338 : * @brief Common CAN controller driver configuration.
339 : *
340 : * This structure is common to all CAN controller drivers and is expected to be the first element in
341 : * the object pointed to by the config field in the device structure.
342 : */
343 : struct can_driver_config {
344 : /** Pointer to the device structure for the associated CAN transceiver device or NULL. */
345 : const struct device *phy;
346 : /** The minimum bitrate supported by the CAN controller/transceiver combination. */
347 : uint32_t min_bitrate;
348 : /** The maximum bitrate supported by the CAN controller/transceiver combination. */
349 : uint32_t max_bitrate;
350 : /** Initial CAN classic/CAN FD arbitration phase bitrate. */
351 : uint32_t bitrate;
352 : /** Initial CAN classic/CAN FD arbitration phase sample point in permille. */
353 : uint16_t sample_point;
354 : #ifdef CONFIG_CAN_FD_MODE
355 : /** Initial CAN FD data phase sample point in permille. */
356 : uint16_t sample_point_data;
357 : /** Initial CAN FD data phase bitrate. */
358 : uint32_t bitrate_data;
359 : #endif /* CONFIG_CAN_FD_MODE */
360 : };
361 :
362 : /**
363 : * @brief Static initializer for @p can_driver_config struct
364 : *
365 : * @param node_id Devicetree node identifier
366 : * @param _min_bitrate minimum bitrate supported by the CAN controller
367 : * @param _max_bitrate maximum bitrate supported by the CAN controller
368 : */
369 : #define CAN_DT_DRIVER_CONFIG_GET(node_id, _min_bitrate, _max_bitrate) \
370 : { \
371 : .phy = DEVICE_DT_GET_OR_NULL(DT_PHANDLE(node_id, phys)), \
372 : .min_bitrate = DT_CAN_TRANSCEIVER_MIN_BITRATE(node_id, _min_bitrate), \
373 : .max_bitrate = DT_CAN_TRANSCEIVER_MAX_BITRATE(node_id, _max_bitrate), \
374 : .bitrate = DT_PROP_OR(node_id, bitrate, \
375 : DT_PROP_OR(node_id, bus_speed, CONFIG_CAN_DEFAULT_BITRATE)), \
376 : .sample_point = DT_PROP_OR(node_id, sample_point, 0), \
377 : IF_ENABLED(CONFIG_CAN_FD_MODE, \
378 : (.bitrate_data = DT_PROP_OR(node_id, bitrate_data, \
379 : DT_PROP_OR(node_id, bus_speed_data, CONFIG_CAN_DEFAULT_BITRATE_DATA)), \
380 : .sample_point_data = DT_PROP_OR(node_id, sample_point_data, 0),)) \
381 : }
382 :
383 : /**
384 : * @brief Static initializer for @p can_driver_config struct from DT_DRV_COMPAT instance
385 : *
386 : * @param inst DT_DRV_COMPAT instance number
387 : * @param _min_bitrate minimum bitrate supported by the CAN controller
388 : * @param _max_bitrate maximum bitrate supported by the CAN controller
389 : * @see CAN_DT_DRIVER_CONFIG_GET()
390 : */
391 : #define CAN_DT_DRIVER_CONFIG_INST_GET(inst, _min_bitrate, _max_bitrate) \
392 : CAN_DT_DRIVER_CONFIG_GET(DT_DRV_INST(inst), _min_bitrate, _max_bitrate)
393 :
394 : /**
395 : * @brief Common CAN controller driver data.
396 : *
397 : * This structure is common to all CAN controller drivers and is expected to be the first element in
398 : * the driver's struct driver_data declaration.
399 : */
400 : struct can_driver_data {
401 : /** Current CAN controller mode. */
402 : can_mode_t mode;
403 : /** True if the CAN controller is started, false otherwise. */
404 : bool started;
405 : /** State change callback function pointer or NULL. */
406 : can_state_change_callback_t state_change_cb;
407 : /** State change callback user data pointer or NULL. */
408 : void *state_change_cb_user_data;
409 : };
410 :
411 : /**
412 : * @brief Callback API upon setting CAN bus timing
413 : * See @a can_set_timing() for argument description
414 : */
415 : typedef int (*can_set_timing_t)(const struct device *dev,
416 : const struct can_timing *timing);
417 :
418 : /**
419 : * @brief Optional callback API upon setting CAN FD bus timing for the data phase.
420 : * See @a can_set_timing_data() for argument description
421 : */
422 : typedef int (*can_set_timing_data_t)(const struct device *dev,
423 : const struct can_timing *timing_data);
424 :
425 : /**
426 : * @brief Callback API upon getting CAN controller capabilities
427 : * See @a can_get_capabilities() for argument description
428 : */
429 : typedef int (*can_get_capabilities_t)(const struct device *dev, can_mode_t *cap);
430 :
431 : /**
432 : * @brief Callback API upon starting CAN controller
433 : * See @a can_start() for argument description
434 : */
435 : typedef int (*can_start_t)(const struct device *dev);
436 :
437 : /**
438 : * @brief Callback API upon stopping CAN controller
439 : * See @a can_stop() for argument description
440 : */
441 : typedef int (*can_stop_t)(const struct device *dev);
442 :
443 : /**
444 : * @brief Callback API upon setting CAN controller mode
445 : * See @a can_set_mode() for argument description
446 : */
447 : typedef int (*can_set_mode_t)(const struct device *dev, can_mode_t mode);
448 :
449 : /**
450 : * @brief Callback API upon sending a CAN frame
451 : * See @a can_send() for argument description
452 : *
453 : * @note From a driver perspective `callback` will never be `NULL` as a default callback will be
454 : * provided if none is provided by the caller. This allows for simplifying the driver handling.
455 : */
456 : typedef int (*can_send_t)(const struct device *dev,
457 : const struct can_frame *frame,
458 : k_timeout_t timeout, can_tx_callback_t callback,
459 : void *user_data);
460 :
461 : /**
462 : * @brief Callback API upon adding an RX filter
463 : * See @a can_add_rx_callback() for argument description
464 : */
465 : typedef int (*can_add_rx_filter_t)(const struct device *dev,
466 : can_rx_callback_t callback,
467 : void *user_data,
468 : const struct can_filter *filter);
469 :
470 : /**
471 : * @brief Callback API upon removing an RX filter
472 : * See @a can_remove_rx_filter() for argument description
473 : */
474 : typedef void (*can_remove_rx_filter_t)(const struct device *dev, int filter_id);
475 :
476 : /**
477 : * @brief Optional callback API upon manually recovering the CAN controller from bus-off state
478 : * See @a can_recover() for argument description
479 : */
480 : typedef int (*can_recover_t)(const struct device *dev, k_timeout_t timeout);
481 :
482 : /**
483 : * @brief Callback API upon getting the CAN controller state
484 : * See @a can_get_state() for argument description
485 : */
486 : typedef int (*can_get_state_t)(const struct device *dev, enum can_state *state,
487 : struct can_bus_err_cnt *err_cnt);
488 :
489 : /**
490 : * @brief Callback API upon setting a state change callback
491 : * See @a can_set_state_change_callback() for argument description
492 : */
493 : typedef void(*can_set_state_change_callback_t)(const struct device *dev,
494 : can_state_change_callback_t callback,
495 : void *user_data);
496 :
497 : /**
498 : * @brief Callback API upon getting the CAN core clock rate
499 : * See @a can_get_core_clock() for argument description
500 : */
501 : typedef int (*can_get_core_clock_t)(const struct device *dev, uint32_t *rate);
502 :
503 : /**
504 : * @brief Optional callback API upon getting the maximum number of concurrent CAN RX filters
505 : * See @a can_get_max_filters() for argument description
506 : */
507 : typedef int (*can_get_max_filters_t)(const struct device *dev, bool ide);
508 :
509 : __subsystem struct can_driver_api {
510 : can_get_capabilities_t get_capabilities;
511 : can_start_t start;
512 : can_stop_t stop;
513 : can_set_mode_t set_mode;
514 : can_set_timing_t set_timing;
515 : can_send_t send;
516 : can_add_rx_filter_t add_rx_filter;
517 : can_remove_rx_filter_t remove_rx_filter;
518 : #if defined(CONFIG_CAN_MANUAL_RECOVERY_MODE) || defined(__DOXYGEN__)
519 : can_recover_t recover;
520 : #endif /* CONFIG_CAN_MANUAL_RECOVERY_MODE */
521 : can_get_state_t get_state;
522 : can_set_state_change_callback_t set_state_change_callback;
523 : can_get_core_clock_t get_core_clock;
524 : can_get_max_filters_t get_max_filters;
525 : /* Min values for the timing registers */
526 : struct can_timing timing_min;
527 : /* Max values for the timing registers */
528 : struct can_timing timing_max;
529 : #if defined(CONFIG_CAN_FD_MODE) || defined(__DOXYGEN__)
530 : can_set_timing_data_t set_timing_data;
531 : /* Min values for the timing registers during the data phase */
532 : struct can_timing timing_data_min;
533 : /* Max values for the timing registers during the data phase */
534 : struct can_timing timing_data_max;
535 : #endif /* CONFIG_CAN_FD_MODE */
536 : };
537 :
538 : /** @endcond */
539 :
540 : #if defined(CONFIG_CAN_STATS) || defined(__DOXYGEN__)
541 :
542 : #include <zephyr/stats/stats.h>
543 :
544 : /** @cond INTERNAL_HIDDEN */
545 :
546 : STATS_SECT_START(can)
547 : STATS_SECT_ENTRY32(bit_error)
548 : STATS_SECT_ENTRY32(bit0_error)
549 : STATS_SECT_ENTRY32(bit1_error)
550 : STATS_SECT_ENTRY32(stuff_error)
551 : STATS_SECT_ENTRY32(crc_error)
552 : STATS_SECT_ENTRY32(form_error)
553 : STATS_SECT_ENTRY32(ack_error)
554 : STATS_SECT_ENTRY32(rx_overrun)
555 : STATS_SECT_END;
556 :
557 : STATS_NAME_START(can)
558 : STATS_NAME(can, bit_error)
559 : STATS_NAME(can, bit0_error)
560 : STATS_NAME(can, bit1_error)
561 : STATS_NAME(can, stuff_error)
562 : STATS_NAME(can, crc_error)
563 : STATS_NAME(can, form_error)
564 : STATS_NAME(can, ack_error)
565 : STATS_NAME(can, rx_overrun)
566 : STATS_NAME_END(can);
567 :
568 : /** @endcond */
569 :
570 : /**
571 : * @brief CAN specific device state which allows for CAN device class specific
572 : * additions
573 : */
574 1 : struct can_device_state {
575 : /** Common device state. */
576 1 : struct device_state devstate;
577 : /** CAN device statistics */
578 1 : struct stats_can stats;
579 : };
580 :
581 : /** @cond INTERNAL_HIDDEN */
582 :
583 : /**
584 : * @brief Get pointer to CAN statistics structure
585 : */
586 : #define Z_CAN_GET_STATS(dev_) \
587 : CONTAINER_OF(dev_->state, struct can_device_state, devstate)->stats
588 :
589 : /** @endcond */
590 :
591 : /**
592 : * @brief Increment the bit error counter for a CAN device
593 : *
594 : * The bit error counter is incremented when the CAN controller is unable to
595 : * transmit either a dominant or a recessive bit.
596 : *
597 : * @note This error counter should only be incremented if the CAN controller is unable to
598 : * distinguish between failure to transmit a dominant versus failure to transmit a recessive bit. If
599 : * the CAN controller supports distinguishing between the two, the `bit0` or `bit1` error counter
600 : * shall be incremented instead.
601 : *
602 : * @see CAN_STATS_BIT0_ERROR_INC()
603 : * @see CAN_STATS_BIT1_ERROR_INC()
604 : *
605 : * @param dev_ Pointer to the device structure for the driver instance.
606 : */
607 1 : #define CAN_STATS_BIT_ERROR_INC(dev_) \
608 : STATS_INC(Z_CAN_GET_STATS(dev_), bit_error)
609 :
610 : /**
611 : * @brief Increment the bit0 error counter for a CAN device
612 : *
613 : * The bit0 error counter is incremented when the CAN controller is unable to
614 : * transmit a dominant bit.
615 : *
616 : * Incrementing this counter will automatically increment the bit error counter.
617 : * @see CAN_STATS_BIT_ERROR_INC()
618 : *
619 : * @param dev_ Pointer to the device structure for the driver instance.
620 : */
621 1 : #define CAN_STATS_BIT0_ERROR_INC(dev_) \
622 : do { \
623 : STATS_INC(Z_CAN_GET_STATS(dev_), bit0_error); \
624 : CAN_STATS_BIT_ERROR_INC(dev_); \
625 : } while (0)
626 :
627 : /**
628 : * @brief Increment the bit1 (recessive) error counter for a CAN device
629 : *
630 : * The bit1 error counter is incremented when the CAN controller is unable to
631 : * transmit a recessive bit.
632 : *
633 : * Incrementing this counter will automatically increment the bit error counter.
634 : * @see CAN_STATS_BIT_ERROR_INC()
635 : *
636 : * @param dev_ Pointer to the device structure for the driver instance.
637 : */
638 1 : #define CAN_STATS_BIT1_ERROR_INC(dev_) \
639 : do { \
640 : STATS_INC(Z_CAN_GET_STATS(dev_), bit1_error); \
641 : CAN_STATS_BIT_ERROR_INC(dev_); \
642 : } while (0)
643 :
644 : /**
645 : * @brief Increment the stuffing error counter for a CAN device
646 : *
647 : * The stuffing error counter is incremented when the CAN controller detects a
648 : * bit stuffing error.
649 : *
650 : * @param dev_ Pointer to the device structure for the driver instance.
651 : */
652 1 : #define CAN_STATS_STUFF_ERROR_INC(dev_) \
653 : STATS_INC(Z_CAN_GET_STATS(dev_), stuff_error)
654 :
655 : /**
656 : * @brief Increment the CRC error counter for a CAN device
657 : *
658 : * The CRC error counter is incremented when the CAN controller detects a frame
659 : * with an invalid CRC.
660 : *
661 : * @param dev_ Pointer to the device structure for the driver instance.
662 : */
663 1 : #define CAN_STATS_CRC_ERROR_INC(dev_) \
664 : STATS_INC(Z_CAN_GET_STATS(dev_), crc_error)
665 :
666 : /**
667 : * @brief Increment the form error counter for a CAN device
668 : *
669 : * The form error counter is incremented when the CAN controller detects a
670 : * fixed-form bit field containing illegal bits.
671 : *
672 : * @param dev_ Pointer to the device structure for the driver instance.
673 : */
674 1 : #define CAN_STATS_FORM_ERROR_INC(dev_) \
675 : STATS_INC(Z_CAN_GET_STATS(dev_), form_error)
676 :
677 : /**
678 : * @brief Increment the acknowledge error counter for a CAN device
679 : *
680 : * The acknowledge error counter is incremented when the CAN controller does not
681 : * monitor a dominant bit in the ACK slot.
682 : *
683 : * @param dev_ Pointer to the device structure for the driver instance.
684 : */
685 1 : #define CAN_STATS_ACK_ERROR_INC(dev_) \
686 : STATS_INC(Z_CAN_GET_STATS(dev_), ack_error)
687 :
688 : /**
689 : * @brief Increment the RX overrun counter for a CAN device
690 : *
691 : * The RX overrun counter is incremented when the CAN controller receives a CAN
692 : * frame matching an installed filter but lacks the capacity to store it (either
693 : * due to an already full RX mailbox or a full RX FIFO).
694 : *
695 : * @param dev_ Pointer to the device structure for the driver instance.
696 : */
697 1 : #define CAN_STATS_RX_OVERRUN_INC(dev_) \
698 : STATS_INC(Z_CAN_GET_STATS(dev_), rx_overrun)
699 :
700 : /**
701 : * @brief Zero all statistics for a CAN device
702 : *
703 : * The driver is responsible for resetting the statistics before starting the CAN
704 : * controller.
705 : *
706 : * @param dev_ Pointer to the device structure for the driver instance.
707 : */
708 1 : #define CAN_STATS_RESET(dev_) \
709 : stats_reset(&(Z_CAN_GET_STATS(dev_).s_hdr))
710 :
711 : /** @cond INTERNAL_HIDDEN */
712 :
713 : /**
714 : * @brief Define a statically allocated and section assigned CAN device state
715 : */
716 : #define Z_CAN_DEVICE_STATE_DEFINE(dev_id) \
717 : static struct can_device_state Z_DEVICE_STATE_NAME(dev_id) \
718 : __attribute__((__section__(".z_devstate")))
719 :
720 : /**
721 : * @brief Define a CAN device init wrapper function
722 : *
723 : * This does device instance specific initialization of common data (such as stats)
724 : * and calls the given init_fn
725 : */
726 : #define Z_CAN_INIT_FN(dev_id, init_fn) \
727 : static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
728 : { \
729 : struct can_device_state *state = \
730 : CONTAINER_OF(dev->state, struct can_device_state, devstate); \
731 : stats_init(&state->stats.s_hdr, STATS_SIZE_32, 8, \
732 : STATS_NAME_INIT_PARMS(can)); \
733 : stats_register(dev->name, &(state->stats.s_hdr)); \
734 : if (!is_null_no_warn(init_fn)) { \
735 : return init_fn(dev); \
736 : } \
737 : \
738 : return 0; \
739 : }
740 :
741 : /** @endcond */
742 :
743 : /**
744 : * @brief Like DEVICE_DT_DEFINE() with CAN device specifics.
745 : *
746 : * @details Defines a device which implements the CAN API. May generate a custom
747 : * device_state container struct and init_fn wrapper when needed depending on
748 : * @kconfig{CONFIG_CAN_STATS}.
749 : *
750 : * @param node_id The devicetree node identifier.
751 : * @param init_fn Name of the init function of the driver.
752 : * @param pm PM device resources reference (NULL if device does not use PM).
753 : * @param data Pointer to the device's private data.
754 : * @param config The address to the structure containing the configuration
755 : * information for this instance of the driver.
756 : * @param level The initialization level. See SYS_INIT() for
757 : * details.
758 : * @param prio Priority within the selected initialization level. See
759 : * SYS_INIT() for details.
760 : * @param api Provides an initial pointer to the API function struct
761 : * used by the driver. Can be NULL.
762 : */
763 : #define CAN_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
764 1 : prio, api, ...) \
765 : Z_CAN_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
766 : Z_CAN_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn) \
767 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
768 : DEVICE_DT_NAME(node_id), \
769 : &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init), \
770 : NULL, Z_DEVICE_DT_FLAGS(node_id), pm, data, \
771 : config, level, prio, api, \
772 : &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
773 : __VA_ARGS__)
774 :
775 : #else /* CONFIG_CAN_STATS */
776 :
777 : #define CAN_STATS_BIT_ERROR_INC(dev_)
778 : #define CAN_STATS_BIT0_ERROR_INC(dev_)
779 : #define CAN_STATS_BIT1_ERROR_INC(dev_)
780 : #define CAN_STATS_STUFF_ERROR_INC(dev_)
781 : #define CAN_STATS_CRC_ERROR_INC(dev_)
782 : #define CAN_STATS_FORM_ERROR_INC(dev_)
783 : #define CAN_STATS_ACK_ERROR_INC(dev_)
784 : #define CAN_STATS_RX_OVERRUN_INC(dev_)
785 : #define CAN_STATS_RESET(dev_)
786 :
787 : #define CAN_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
788 : prio, api, ...) \
789 : DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
790 : prio, api, __VA_ARGS__)
791 :
792 : #endif /* CONFIG_CAN_STATS */
793 :
794 : /**
795 : * @brief Like CAN_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible
796 : *
797 : * @param inst Instance number. This is replaced by <tt>DT_DRV_COMPAT(inst)</tt>
798 : * in the call to CAN_DEVICE_DT_DEFINE().
799 : * @param ... Other parameters as expected by CAN_DEVICE_DT_DEFINE().
800 : */
801 1 : #define CAN_DEVICE_DT_INST_DEFINE(inst, ...) \
802 : CAN_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
803 :
804 : /**
805 : * @name CAN controller configuration
806 : *
807 : * @{
808 : */
809 :
810 : /**
811 : * @brief Get the CAN core clock rate
812 : *
813 : * Returns the CAN core clock rate. One minimum time quantum (mtq) is 1/(core clock rate). The CAN
814 : * core clock can be further divided by the CAN clock prescaler (see the @a can_timing struct),
815 : * providing the time quantum (tq).
816 : *
817 : * @param dev Pointer to the device structure for the driver instance.
818 : * @param[out] rate CAN core clock rate in Hz.
819 : *
820 : * @return 0 on success, or a negative error code on error
821 : */
822 1 : __syscall int can_get_core_clock(const struct device *dev, uint32_t *rate);
823 :
824 : static inline int z_impl_can_get_core_clock(const struct device *dev, uint32_t *rate)
825 : {
826 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
827 :
828 : return api->get_core_clock(dev, rate);
829 : }
830 :
831 : /**
832 : * @brief Get minimum supported bitrate
833 : *
834 : * Get the minimum supported bitrate for the CAN controller/transceiver combination.
835 : *
836 : * @note The minimum bitrate represents limitations of the CAN controller/transceiver
837 : * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
838 : * rate and the minimum CAN timing limits.
839 : *
840 : * @see can_get_core_clock()
841 : * @see can_get_timing_min()
842 : * @see can_get_timing_data_min()
843 : *
844 : * @param dev Pointer to the device structure for the driver instance.
845 : * @return Minimum supported bitrate in bits/s. A value of 0 means the lower limit is unspecified.
846 : */
847 1 : __syscall uint32_t can_get_bitrate_min(const struct device *dev);
848 :
849 : static inline uint32_t z_impl_can_get_bitrate_min(const struct device *dev)
850 : {
851 : const struct can_driver_config *common = (const struct can_driver_config *)dev->config;
852 :
853 : return common->min_bitrate;
854 : }
855 :
856 : /**
857 : * @brief Get maximum supported bitrate
858 : *
859 : * Get the maximum supported bitrate for the CAN controller/transceiver combination.
860 : *
861 : * @note The maximum bitrate represents limitations of the CAN controller/transceiver
862 : * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
863 : * rate and the maximum CAN timing limits.
864 : *
865 : * @see can_get_core_clock()
866 : * @see can_get_timing_max()
867 : * @see can_get_timing_data_max()
868 : *
869 : * @param dev Pointer to the device structure for the driver instance.
870 : * @return Maximum supported bitrate in bits/s
871 : */
872 1 : __syscall uint32_t can_get_bitrate_max(const struct device *dev);
873 :
874 : static inline uint32_t z_impl_can_get_bitrate_max(const struct device *dev)
875 : {
876 : const struct can_driver_config *common = (const struct can_driver_config *)dev->config;
877 :
878 : return common->max_bitrate;
879 : }
880 :
881 : /**
882 : * @brief Get the minimum supported timing parameter values.
883 : *
884 : * @param dev Pointer to the device structure for the driver instance.
885 : *
886 : * @return Pointer to the minimum supported timing parameter values.
887 : */
888 1 : __syscall const struct can_timing *can_get_timing_min(const struct device *dev);
889 :
890 : static inline const struct can_timing *z_impl_can_get_timing_min(const struct device *dev)
891 : {
892 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
893 :
894 : return &api->timing_min;
895 : }
896 :
897 : /**
898 : * @brief Get the maximum supported timing parameter values.
899 : *
900 : * @param dev Pointer to the device structure for the driver instance.
901 : *
902 : * @return Pointer to the maximum supported timing parameter values.
903 : */
904 1 : __syscall const struct can_timing *can_get_timing_max(const struct device *dev);
905 :
906 : static inline const struct can_timing *z_impl_can_get_timing_max(const struct device *dev)
907 : {
908 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
909 :
910 : return &api->timing_max;
911 : }
912 :
913 : /**
914 : * @brief Calculate timing parameters from bitrate and sample point
915 : *
916 : * Calculate the timing parameters from a given bitrate in bits/s and the
917 : * sampling point in permill (1/1000) of the entire bit time. The bitrate must
918 : * always match perfectly. If no result can be reached for the given parameters,
919 : * -EINVAL is returned.
920 : *
921 : * If the sample point is set to 0, this function defaults to a sample point of 75.0%
922 : * for bitrates over 800 kbit/s, 80.0% for bitrates over 500 kbit/s, and 87.5% for
923 : * all other bitrates.
924 : *
925 : * @note The requested ``sample_pnt`` will not always be matched perfectly. The
926 : * algorithm calculates the best possible match.
927 : *
928 : * @param dev Pointer to the device structure for the driver instance.
929 : * @param[out] res Result is written into the @a can_timing struct provided.
930 : * @param bitrate Target bitrate in bits/s.
931 : * @param sample_pnt Sample point in permille of the entire bit time or 0 for
932 : * automatic sample point location.
933 : *
934 : * @retval 0 or positive sample point error on success.
935 : * @retval -EINVAL if the requested bitrate or sample point is out of range.
936 : * @retval -ENOTSUP if the requested bitrate is not supported.
937 : * @retval -EIO if @a can_get_core_clock() is not available.
938 : */
939 1 : __syscall int can_calc_timing(const struct device *dev, struct can_timing *res,
940 : uint32_t bitrate, uint16_t sample_pnt);
941 :
942 : /**
943 : * @brief Get the minimum supported timing parameter values for the data phase.
944 : *
945 : * Same as @a can_get_timing_min() but for the minimum values for the data phase.
946 : *
947 : * @note @kconfig{CONFIG_CAN_FD_MODE} must be selected for this function to be
948 : * available.
949 : *
950 : * @param dev Pointer to the device structure for the driver instance.
951 : *
952 : * @return Pointer to the minimum supported timing parameter values, or NULL if
953 : * CAN FD support is not implemented by the driver.
954 : */
955 1 : __syscall const struct can_timing *can_get_timing_data_min(const struct device *dev);
956 :
957 : #ifdef CONFIG_CAN_FD_MODE
958 : static inline const struct can_timing *z_impl_can_get_timing_data_min(const struct device *dev)
959 : {
960 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
961 :
962 : return &api->timing_data_min;
963 : }
964 : #endif /* CONFIG_CAN_FD_MODE */
965 :
966 : /**
967 : * @brief Get the maximum supported timing parameter values for the data phase.
968 : *
969 : * Same as @a can_get_timing_max() but for the maximum values for the data phase.
970 : *
971 : * @note @kconfig{CONFIG_CAN_FD_MODE} must be selected for this function to be
972 : * available.
973 : *
974 : * @param dev Pointer to the device structure for the driver instance.
975 : *
976 : * @return Pointer to the maximum supported timing parameter values, or NULL if
977 : * CAN FD support is not implemented by the driver.
978 : */
979 1 : __syscall const struct can_timing *can_get_timing_data_max(const struct device *dev);
980 :
981 : #ifdef CONFIG_CAN_FD_MODE
982 : static inline const struct can_timing *z_impl_can_get_timing_data_max(const struct device *dev)
983 : {
984 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
985 :
986 : return &api->timing_data_max;
987 : }
988 : #endif /* CONFIG_CAN_FD_MODE */
989 :
990 : /**
991 : * @brief Calculate timing parameters for the data phase
992 : *
993 : * Same as @a can_calc_timing() but with the maximum and minimum values from the
994 : * data phase.
995 : *
996 : * @note @kconfig{CONFIG_CAN_FD_MODE} must be selected for this function to be
997 : * available.
998 : *
999 : * @param dev Pointer to the device structure for the driver instance.
1000 : * @param[out] res Result is written into the @a can_timing struct provided.
1001 : * @param bitrate Target bitrate for the data phase in bits/s
1002 : * @param sample_pnt Sample point for the data phase in permille of the entire bit
1003 : * time or 0 for automatic sample point location.
1004 : *
1005 : * @retval 0 or positive sample point error on success.
1006 : * @retval -EINVAL if the requested bitrate or sample point is out of range.
1007 : * @retval -ENOTSUP if the requested bitrate is not supported.
1008 : * @retval -EIO if @a can_get_core_clock() is not available.
1009 : */
1010 1 : __syscall int can_calc_timing_data(const struct device *dev, struct can_timing *res,
1011 : uint32_t bitrate, uint16_t sample_pnt);
1012 :
1013 : /**
1014 : * @brief Configure the bus timing for the data phase of a CAN FD controller.
1015 : *
1016 : * @note @kconfig{CONFIG_CAN_FD_MODE} must be selected for this function to be
1017 : * available.
1018 : *
1019 : * @see can_set_timing()
1020 : *
1021 : * @param dev Pointer to the device structure for the driver instance.
1022 : * @param timing_data Bus timings for data phase
1023 : *
1024 : * @retval 0 If successful.
1025 : * @retval -EBUSY if the CAN controller is not in stopped state.
1026 : * @retval -EIO General input/output error, failed to configure device.
1027 : * @retval -ENOTSUP if the timing parameters are not supported by the driver.
1028 : * @retval -ENOSYS if CAN FD support is not implemented by the driver.
1029 : */
1030 1 : __syscall int can_set_timing_data(const struct device *dev,
1031 : const struct can_timing *timing_data);
1032 :
1033 : /**
1034 : * @brief Set the bitrate for the data phase of the CAN FD controller
1035 : *
1036 : * CAN in Automation (CiA) 301 v4.2.0 recommends a sample point location of
1037 : * 87.5% percent for all bitrates. However, some CAN controllers have
1038 : * difficulties meeting this for higher bitrates.
1039 : *
1040 : * This function defaults to using a sample point of 75.0% for bitrates over 800
1041 : * kbit/s, 80.0% for bitrates over 500 kbit/s, and 87.5% for all other
1042 : * bitrates. This is in line with the sample point locations used by the Linux
1043 : * kernel.
1044 : *
1045 : * @note @kconfig{CONFIG_CAN_FD_MODE} must be selected for this function to be
1046 : * available.
1047 : *
1048 : * @see can_set_bitrate()
1049 :
1050 : * @param dev Pointer to the device structure for the driver instance.
1051 : * @param bitrate_data Desired data phase bitrate.
1052 : *
1053 : * @retval 0 If successful.
1054 : * @retval -EBUSY if the CAN controller is not in stopped state.
1055 : * @retval -EINVAL if the requested bitrate is out of range.
1056 : * @retval -ENOTSUP if the requested bitrate not supported by the CAN controller/transceiver
1057 : * combination.
1058 : * @retval -ERANGE if the resulting sample point is off by more than +/- 5%.
1059 : * @retval -EIO General input/output error, failed to set bitrate.
1060 : */
1061 1 : __syscall int can_set_bitrate_data(const struct device *dev, uint32_t bitrate_data);
1062 :
1063 : /**
1064 : * @brief Configure the bus timing of a CAN controller.
1065 : *
1066 : * @see can_set_timing_data()
1067 : *
1068 : * @param dev Pointer to the device structure for the driver instance.
1069 : * @param timing Bus timings.
1070 : *
1071 : * @retval 0 If successful.
1072 : * @retval -EBUSY if the CAN controller is not in stopped state.
1073 : * @retval -ENOTSUP if the timing parameters are not supported by the driver.
1074 : * @retval -EIO General input/output error, failed to configure device.
1075 : */
1076 1 : __syscall int can_set_timing(const struct device *dev,
1077 : const struct can_timing *timing);
1078 :
1079 : /**
1080 : * @brief Get the supported modes of the CAN controller
1081 : *
1082 : * The returned capabilities may not necessarily be supported at the same time (e.g. some CAN
1083 : * controllers support both ``CAN_MODE_LOOPBACK`` and ``CAN_MODE_LISTENONLY``, but not at the same
1084 : * time).
1085 : *
1086 : * @param dev Pointer to the device structure for the driver instance.
1087 : * @param[out] cap Supported capabilities.
1088 : *
1089 : * @retval 0 If successful.
1090 : * @retval -EIO General input/output error, failed to get capabilities.
1091 : */
1092 1 : __syscall int can_get_capabilities(const struct device *dev, can_mode_t *cap);
1093 :
1094 : static inline int z_impl_can_get_capabilities(const struct device *dev, can_mode_t *cap)
1095 : {
1096 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1097 :
1098 : return api->get_capabilities(dev, cap);
1099 : }
1100 :
1101 : /**
1102 : * @brief Get the CAN transceiver associated with the CAN controller
1103 : *
1104 : * Get a pointer to the device structure for the CAN transceiver associated with the CAN controller.
1105 : *
1106 : * @param dev Pointer to the device structure for the driver instance.
1107 : * @return Pointer to the device structure for the associated CAN transceiver driver instance, or
1108 : * NULL if no transceiver is associated.
1109 : */
1110 1 : __syscall const struct device *can_get_transceiver(const struct device *dev);
1111 :
1112 : static const struct device *z_impl_can_get_transceiver(const struct device *dev)
1113 : {
1114 : const struct can_driver_config *common = (const struct can_driver_config *)dev->config;
1115 :
1116 : return common->phy;
1117 : }
1118 :
1119 : /**
1120 : * @brief Start the CAN controller
1121 : *
1122 : * Bring the CAN controller out of `CAN_STATE_STOPPED`. This will reset the RX/TX error counters,
1123 : * enable the CAN controller to participate in CAN communication, and enable the CAN transceiver, if
1124 : * supported.
1125 : *
1126 : * Starting the CAN controller resets all the CAN controller statistics.
1127 : *
1128 : * @see can_stop()
1129 : * @see can_transceiver_enable()
1130 : *
1131 : * @param dev Pointer to the device structure for the driver instance.
1132 : * @retval 0 if successful.
1133 : * @retval -EALREADY if the device is already started.
1134 : * @retval -EIO General input/output error, failed to start device.
1135 : */
1136 1 : __syscall int can_start(const struct device *dev);
1137 :
1138 : static inline int z_impl_can_start(const struct device *dev)
1139 : {
1140 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1141 :
1142 : return api->start(dev);
1143 : }
1144 :
1145 : /**
1146 : * @brief Stop the CAN controller
1147 : *
1148 : * Bring the CAN controller into `CAN_STATE_STOPPED`. This will disallow the CAN controller from
1149 : * participating in CAN communication, abort any pending CAN frame transmissions, and disable the
1150 : * CAN transceiver, if supported.
1151 : *
1152 : * @see can_start()
1153 : * @see can_transceiver_disable()
1154 : *
1155 : * @param dev Pointer to the device structure for the driver instance.
1156 : * @retval 0 if successful.
1157 : * @retval -EALREADY if the device is already stopped.
1158 : * @retval -EIO General input/output error, failed to stop device.
1159 : */
1160 1 : __syscall int can_stop(const struct device *dev);
1161 :
1162 : static inline int z_impl_can_stop(const struct device *dev)
1163 : {
1164 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1165 :
1166 : return api->stop(dev);
1167 : }
1168 :
1169 : /**
1170 : * @brief Set the CAN controller to the given operation mode
1171 : *
1172 : * @param dev Pointer to the device structure for the driver instance.
1173 : * @param mode Operation mode.
1174 : *
1175 : * @retval 0 If successful.
1176 : * @retval -EBUSY if the CAN controller is not in stopped state.
1177 : * @retval -EIO General input/output error, failed to configure device.
1178 : */
1179 1 : __syscall int can_set_mode(const struct device *dev, can_mode_t mode);
1180 :
1181 : static inline int z_impl_can_set_mode(const struct device *dev, can_mode_t mode)
1182 : {
1183 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1184 :
1185 : return api->set_mode(dev, mode);
1186 : }
1187 :
1188 : /**
1189 : * @brief Get the operation mode of the CAN controller
1190 : *
1191 : * @param dev Pointer to the device structure for the driver instance.
1192 : *
1193 : * @return Current operation mode.
1194 : */
1195 1 : __syscall can_mode_t can_get_mode(const struct device *dev);
1196 :
1197 : static inline can_mode_t z_impl_can_get_mode(const struct device *dev)
1198 : {
1199 : const struct can_driver_data *common = (const struct can_driver_data *)dev->data;
1200 :
1201 : return common->mode;
1202 : }
1203 :
1204 : /**
1205 : * @brief Set the bitrate of the CAN controller
1206 : *
1207 : * CAN in Automation (CiA) 301 v4.2.0 recommends a sample point location of
1208 : * 87.5% percent for all bitrates. However, some CAN controllers have
1209 : * difficulties meeting this for higher bitrates.
1210 : *
1211 : * This function defaults to using a sample point of 75.0% for bitrates over 800
1212 : * kbit/s, 80.0% for bitrates over 500 kbit/s, and 87.5% for all other
1213 : * bitrates. This is in line with the sample point locations used by the Linux
1214 : * kernel.
1215 : *
1216 : * @see can_set_bitrate_data()
1217 : *
1218 : * @param dev Pointer to the device structure for the driver instance.
1219 : * @param bitrate Desired arbitration phase bitrate.
1220 : *
1221 : * @retval 0 If successful.
1222 : * @retval -EBUSY if the CAN controller is not in stopped state.
1223 : * @retval -EINVAL if the requested bitrate is out of range.
1224 : * @retval -ENOTSUP if the requested bitrate not supported by the CAN controller/transceiver
1225 : * combination.
1226 : * @retval -ERANGE if the resulting sample point is off by more than +/- 5%.
1227 : * @retval -EIO General input/output error, failed to set bitrate.
1228 : */
1229 1 : __syscall int can_set_bitrate(const struct device *dev, uint32_t bitrate);
1230 :
1231 : /** @} */
1232 :
1233 : /**
1234 : * @name Transmitting CAN frames
1235 : *
1236 : * @{
1237 : */
1238 :
1239 : /**
1240 : * @brief Queue a CAN frame for transmission on the CAN bus
1241 : *
1242 : * Queue a CAN frame for transmission on the CAN bus with optional timeout and
1243 : * completion callback function.
1244 : *
1245 : * Queued CAN frames are transmitted in order according to the their priority:
1246 : * - The lower the CAN-ID, the higher the priority.
1247 : * - Data frames have higher priority than Remote Transmission Request (RTR)
1248 : * frames with identical CAN-IDs.
1249 : * - Frames with standard (11-bit) identifiers have higher priority than frames
1250 : * with extended (29-bit) identifiers with identical base IDs (the higher 11
1251 : * bits of the extended identifier).
1252 : * - Transmission order for queued frames with the same priority is hardware
1253 : * dependent.
1254 : *
1255 : * @note If transmitting segmented messages spanning multiple CAN frames with
1256 : * identical CAN-IDs, the sender must ensure to only queue one frame at a time
1257 : * if FIFO order is required.
1258 : *
1259 : * By default, the CAN controller will automatically retry transmission in case
1260 : * of lost bus arbitration or missing acknowledge. Some CAN controllers support
1261 : * disabling automatic retransmissions via ``CAN_MODE_ONE_SHOT``.
1262 : *
1263 : * @param dev Pointer to the device structure for the driver instance.
1264 : * @param frame CAN frame to transmit.
1265 : * @param timeout Timeout waiting for a empty TX mailbox or ``K_FOREVER``.
1266 : * @param callback Optional callback for when the frame was sent or a
1267 : * transmission error occurred. If ``NULL``, this function is
1268 : * blocking until frame is sent. The callback must be ``NULL``
1269 : * if called from user mode.
1270 : * @param user_data User data to pass to callback function.
1271 : *
1272 : * @retval 0 if successful.
1273 : * @retval -EINVAL if an invalid parameter was passed to the function.
1274 : * @retval -ENOTSUP if an unsupported parameter was passed to the function.
1275 : * @retval -ENETDOWN if the CAN controller is in stopped state.
1276 : * @retval -ENETUNREACH if the CAN controller is in bus-off state.
1277 : * @retval -EBUSY if CAN bus arbitration was lost (only applicable if automatic
1278 : * retransmissions are disabled).
1279 : * @retval -EIO if a general transmit error occurred (e.g. missing ACK if
1280 : * automatic retransmissions are disabled).
1281 : * @retval -EAGAIN on timeout.
1282 : */
1283 1 : __syscall int can_send(const struct device *dev, const struct can_frame *frame,
1284 : k_timeout_t timeout, can_tx_callback_t callback,
1285 : void *user_data);
1286 :
1287 : /** @} */
1288 :
1289 : /**
1290 : * @name Receiving CAN frames
1291 : *
1292 : * @{
1293 : */
1294 :
1295 : /**
1296 : * @brief Add a callback function for a given CAN filter
1297 : *
1298 : * Add a callback to CAN identifiers specified by a filter. When a received CAN
1299 : * frame matching the filter is received by the CAN controller, the callback
1300 : * function is called in interrupt context.
1301 : *
1302 : * If a received frame matches more than one filter (i.e., the filter IDs/masks or
1303 : * flags overlap), the priority of the match is hardware dependent.
1304 : *
1305 : * The same callback function can be used for multiple filters.
1306 : *
1307 : * @param dev Pointer to the device structure for the driver instance.
1308 : * @param callback This function is called by the CAN controller driver whenever
1309 : * a frame matching the filter is received.
1310 : * @param user_data User data to pass to callback function.
1311 : * @param filter Pointer to a @a can_filter structure defining the filter.
1312 : *
1313 : * @retval filter_id on success.
1314 : * @retval -ENOSPC if there are no free filters.
1315 : * @retval -EINVAL if the requested filter type is invalid.
1316 : * @retval -ENOTSUP if the requested filter type is not supported.
1317 : */
1318 1 : int can_add_rx_filter(const struct device *dev, can_rx_callback_t callback,
1319 : void *user_data, const struct can_filter *filter);
1320 :
1321 : /**
1322 : * @brief Statically define and initialize a CAN RX message queue.
1323 : *
1324 : * The message queue's ring buffer contains space for @a max_frames CAN frames.
1325 : *
1326 : * @see can_add_rx_filter_msgq()
1327 : *
1328 : * @param name Name of the message queue.
1329 : * @param max_frames Maximum number of CAN frames that can be queued.
1330 : */
1331 1 : #define CAN_MSGQ_DEFINE(name, max_frames) \
1332 : K_MSGQ_DEFINE(name, sizeof(struct can_frame), max_frames, 4)
1333 :
1334 : /**
1335 : * @brief Simple wrapper function for adding a message queue for a given filter
1336 : *
1337 : * Wrapper function for @a can_add_rx_filter() which puts received CAN frames
1338 : * matching the filter in a message queue instead of calling a callback.
1339 : *
1340 : * If a received frame matches more than one filter (i.e., the filter IDs/masks or
1341 : * flags overlap), the priority of the match is hardware dependent.
1342 : *
1343 : * The same message queue can be used for multiple filters.
1344 : *
1345 : * @note The message queue must be initialized before calling this function and
1346 : * the caller must have appropriate permissions on it.
1347 : *
1348 : * @warning Message queue overruns are silently ignored and overrun frames
1349 : * discarded. Custom error handling can be implemented by using
1350 : * @a can_add_rx_filter() and @a k_msgq_put() directly.
1351 : *
1352 : * @param dev Pointer to the device structure for the driver instance.
1353 : * @param msgq Pointer to the already initialized @a k_msgq struct.
1354 : * @param filter Pointer to a @a can_filter structure defining the filter.
1355 : *
1356 : * @retval filter_id on success.
1357 : * @retval -ENOSPC if there are no free filters.
1358 : * @retval -ENOTSUP if the requested filter type is not supported.
1359 : */
1360 1 : __syscall int can_add_rx_filter_msgq(const struct device *dev, struct k_msgq *msgq,
1361 : const struct can_filter *filter);
1362 :
1363 : /**
1364 : * @brief Remove a CAN RX filter
1365 : *
1366 : * This routine removes a CAN RX filter based on the filter ID returned by @a
1367 : * can_add_rx_filter() or @a can_add_rx_filter_msgq().
1368 : *
1369 : * @param dev Pointer to the device structure for the driver instance.
1370 : * @param filter_id Filter ID
1371 : */
1372 1 : __syscall void can_remove_rx_filter(const struct device *dev, int filter_id);
1373 :
1374 : static inline void z_impl_can_remove_rx_filter(const struct device *dev, int filter_id)
1375 : {
1376 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1377 :
1378 : api->remove_rx_filter(dev, filter_id);
1379 : }
1380 :
1381 : /**
1382 : * @brief Get maximum number of RX filters
1383 : *
1384 : * Get the maximum number of concurrent RX filters for the CAN controller.
1385 : *
1386 : * @param dev Pointer to the device structure for the driver instance.
1387 : * @param ide Get the maximum standard (11-bit) CAN ID filters if false, or extended (29-bit) CAN ID
1388 : * filters if true.
1389 : *
1390 : * @retval Positive number of maximum concurrent filters.
1391 : * @retval -EIO General input/output error.
1392 : * @retval -ENOSYS If this function is not implemented by the driver.
1393 : */
1394 1 : __syscall int can_get_max_filters(const struct device *dev, bool ide);
1395 :
1396 : static inline int z_impl_can_get_max_filters(const struct device *dev, bool ide)
1397 : {
1398 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1399 :
1400 : if (api->get_max_filters == NULL) {
1401 : return -ENOSYS;
1402 : }
1403 :
1404 : return api->get_max_filters(dev, ide);
1405 : }
1406 :
1407 : /** @} */
1408 :
1409 : /**
1410 : * @name CAN bus error reporting and handling
1411 : *
1412 : * @{
1413 : */
1414 :
1415 : /**
1416 : * @brief Get current CAN controller state
1417 : *
1418 : * Returns the current state and optionally the error counter values of the CAN
1419 : * controller.
1420 : *
1421 : * @param dev Pointer to the device structure for the driver instance.
1422 : * @param[out] state Pointer to the state destination enum or NULL.
1423 : * @param[out] err_cnt Pointer to the err_cnt destination structure or NULL.
1424 : *
1425 : * @retval 0 If successful.
1426 : * @retval -EIO General input/output error, failed to get state.
1427 : */
1428 1 : __syscall int can_get_state(const struct device *dev, enum can_state *state,
1429 : struct can_bus_err_cnt *err_cnt);
1430 :
1431 : static inline int z_impl_can_get_state(const struct device *dev, enum can_state *state,
1432 : struct can_bus_err_cnt *err_cnt)
1433 : {
1434 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1435 :
1436 : return api->get_state(dev, state, err_cnt);
1437 : }
1438 :
1439 : /**
1440 : * @brief Recover from bus-off state
1441 : *
1442 : * Recover the CAN controller from bus-off state to error-active state.
1443 : *
1444 : * @note @kconfig{CONFIG_CAN_MANUAL_RECOVERY_MODE} must be enabled for this
1445 : * function to be available.
1446 : *
1447 : * @param dev Pointer to the device structure for the driver instance.
1448 : * @param timeout Timeout for waiting for the recovery or ``K_FOREVER``.
1449 : *
1450 : * @retval 0 on success.
1451 : * @retval -ENOTSUP if the CAN controller is not in manual recovery mode.
1452 : * @retval -ENETDOWN if the CAN controller is in stopped state.
1453 : * @retval -EAGAIN on timeout.
1454 : * @retval -ENOSYS If this function is not implemented by the driver.
1455 : */
1456 1 : __syscall int can_recover(const struct device *dev, k_timeout_t timeout);
1457 :
1458 : #ifdef CONFIG_CAN_MANUAL_RECOVERY_MODE
1459 : static inline int z_impl_can_recover(const struct device *dev, k_timeout_t timeout)
1460 : {
1461 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1462 :
1463 : if (api->recover == NULL) {
1464 : return -ENOSYS;
1465 : }
1466 :
1467 : return api->recover(dev, timeout);
1468 : }
1469 : #endif /* CONFIG_CAN_MANUAL_RECOVERY_MODE */
1470 :
1471 : /**
1472 : * @brief Set a callback for CAN controller state change events
1473 : *
1474 : * Set the callback for CAN controller state change events. The callback
1475 : * function will be called in interrupt context.
1476 : *
1477 : * Only one callback can be registered per controller. Calling this function
1478 : * again overrides any previously registered callback.
1479 : *
1480 : * @param dev Pointer to the device structure for the driver instance.
1481 : * @param callback Callback function.
1482 : * @param user_data User data to pass to callback function.
1483 : */
1484 1 : static inline void can_set_state_change_callback(const struct device *dev,
1485 : can_state_change_callback_t callback,
1486 : void *user_data)
1487 : {
1488 : const struct can_driver_api *api = (const struct can_driver_api *)dev->api;
1489 :
1490 : api->set_state_change_callback(dev, callback, user_data);
1491 : }
1492 :
1493 : /** @} */
1494 :
1495 : /**
1496 : * @name CAN statistics
1497 : *
1498 : * @{
1499 : */
1500 :
1501 : /**
1502 : * @brief Get the bit error counter for a CAN device
1503 : *
1504 : * The bit error counter is incremented when the CAN controller is unable to
1505 : * transmit either a dominant or a recessive bit.
1506 : *
1507 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1508 : * available.
1509 : *
1510 : * @param dev Pointer to the device structure for the driver instance.
1511 : * @return bit error counter
1512 : */
1513 1 : __syscall uint32_t can_stats_get_bit_errors(const struct device *dev);
1514 :
1515 : #ifdef CONFIG_CAN_STATS
1516 : static inline uint32_t z_impl_can_stats_get_bit_errors(const struct device *dev)
1517 : {
1518 : return Z_CAN_GET_STATS(dev).bit_error;
1519 : }
1520 : #endif /* CONFIG_CAN_STATS */
1521 :
1522 : /**
1523 : * @brief Get the bit0 error counter for a CAN device
1524 : *
1525 : * The bit0 error counter is incremented when the CAN controller is unable to
1526 : * transmit a dominant bit.
1527 : *
1528 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1529 : * available.
1530 : *
1531 : * @see can_stats_get_bit_errors()
1532 : *
1533 : * @param dev Pointer to the device structure for the driver instance.
1534 : * @return bit0 error counter
1535 : */
1536 1 : __syscall uint32_t can_stats_get_bit0_errors(const struct device *dev);
1537 :
1538 : #ifdef CONFIG_CAN_STATS
1539 : static inline uint32_t z_impl_can_stats_get_bit0_errors(const struct device *dev)
1540 : {
1541 : return Z_CAN_GET_STATS(dev).bit0_error;
1542 : }
1543 : #endif /* CONFIG_CAN_STATS */
1544 :
1545 : /**
1546 : * @brief Get the bit1 error counter for a CAN device
1547 : *
1548 : * The bit1 error counter is incremented when the CAN controller is unable to
1549 : * transmit a recessive bit.
1550 : *
1551 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1552 : * available.
1553 : *
1554 : * @see can_stats_get_bit_errors()
1555 : *
1556 : * @param dev Pointer to the device structure for the driver instance.
1557 : * @return bit1 error counter
1558 : */
1559 1 : __syscall uint32_t can_stats_get_bit1_errors(const struct device *dev);
1560 :
1561 : #ifdef CONFIG_CAN_STATS
1562 : static inline uint32_t z_impl_can_stats_get_bit1_errors(const struct device *dev)
1563 : {
1564 : return Z_CAN_GET_STATS(dev).bit1_error;
1565 : }
1566 : #endif /* CONFIG_CAN_STATS */
1567 :
1568 : /**
1569 : * @brief Get the stuffing error counter for a CAN device
1570 : *
1571 : * The stuffing error counter is incremented when the CAN controller detects a
1572 : * bit stuffing error.
1573 : *
1574 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1575 : * available.
1576 : *
1577 : * @param dev Pointer to the device structure for the driver instance.
1578 : * @return stuffing error counter
1579 : */
1580 1 : __syscall uint32_t can_stats_get_stuff_errors(const struct device *dev);
1581 :
1582 : #ifdef CONFIG_CAN_STATS
1583 : static inline uint32_t z_impl_can_stats_get_stuff_errors(const struct device *dev)
1584 : {
1585 : return Z_CAN_GET_STATS(dev).stuff_error;
1586 : }
1587 : #endif /* CONFIG_CAN_STATS */
1588 :
1589 : /**
1590 : * @brief Get the CRC error counter for a CAN device
1591 : *
1592 : * The CRC error counter is incremented when the CAN controller detects a frame
1593 : * with an invalid CRC.
1594 : *
1595 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1596 : * available.
1597 : *
1598 : * @param dev Pointer to the device structure for the driver instance.
1599 : * @return CRC error counter
1600 : */
1601 1 : __syscall uint32_t can_stats_get_crc_errors(const struct device *dev);
1602 :
1603 : #ifdef CONFIG_CAN_STATS
1604 : static inline uint32_t z_impl_can_stats_get_crc_errors(const struct device *dev)
1605 : {
1606 : return Z_CAN_GET_STATS(dev).crc_error;
1607 : }
1608 : #endif /* CONFIG_CAN_STATS */
1609 :
1610 : /**
1611 : * @brief Get the form error counter for a CAN device
1612 : *
1613 : * The form error counter is incremented when the CAN controller detects a
1614 : * fixed-form bit field containing illegal bits.
1615 : *
1616 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1617 : * available.
1618 : *
1619 : * @param dev Pointer to the device structure for the driver instance.
1620 : * @return form error counter
1621 : */
1622 1 : __syscall uint32_t can_stats_get_form_errors(const struct device *dev);
1623 :
1624 : #ifdef CONFIG_CAN_STATS
1625 : static inline uint32_t z_impl_can_stats_get_form_errors(const struct device *dev)
1626 : {
1627 : return Z_CAN_GET_STATS(dev).form_error;
1628 : }
1629 : #endif /* CONFIG_CAN_STATS */
1630 :
1631 : /**
1632 : * @brief Get the acknowledge error counter for a CAN device
1633 : *
1634 : * The acknowledge error counter is incremented when the CAN controller does not
1635 : * monitor a dominant bit in the ACK slot.
1636 : *
1637 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1638 : * available.
1639 : *
1640 : * @param dev Pointer to the device structure for the driver instance.
1641 : * @return acknowledge error counter
1642 : */
1643 1 : __syscall uint32_t can_stats_get_ack_errors(const struct device *dev);
1644 :
1645 : #ifdef CONFIG_CAN_STATS
1646 : static inline uint32_t z_impl_can_stats_get_ack_errors(const struct device *dev)
1647 : {
1648 : return Z_CAN_GET_STATS(dev).ack_error;
1649 : }
1650 : #endif /* CONFIG_CAN_STATS */
1651 :
1652 : /**
1653 : * @brief Get the RX overrun counter for a CAN device
1654 : *
1655 : * The RX overrun counter is incremented when the CAN controller receives a CAN
1656 : * frame matching an installed filter but lacks the capacity to store it (either
1657 : * due to an already full RX mailbox or a full RX FIFO).
1658 : *
1659 : * @note @kconfig{CONFIG_CAN_STATS} must be selected for this function to be
1660 : * available.
1661 : *
1662 : * @param dev Pointer to the device structure for the driver instance.
1663 : * @return RX overrun counter
1664 : */
1665 1 : __syscall uint32_t can_stats_get_rx_overruns(const struct device *dev);
1666 :
1667 : #ifdef CONFIG_CAN_STATS
1668 : static inline uint32_t z_impl_can_stats_get_rx_overruns(const struct device *dev)
1669 : {
1670 : return Z_CAN_GET_STATS(dev).rx_overrun;
1671 : }
1672 : #endif /* CONFIG_CAN_STATS */
1673 :
1674 : /** @} */
1675 :
1676 : /**
1677 : * @name CAN utility functions
1678 : *
1679 : * @{
1680 : */
1681 :
1682 : /**
1683 : * @brief Convert from Data Length Code (DLC) to the number of data bytes
1684 : *
1685 : * @param dlc Data Length Code (DLC).
1686 : *
1687 : * @retval Number of bytes.
1688 : */
1689 1 : static inline uint8_t can_dlc_to_bytes(uint8_t dlc)
1690 : {
1691 : static const uint8_t dlc_table[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 12,
1692 : 16, 20, 24, 32, 48, 64};
1693 :
1694 : return dlc_table[MIN(dlc, ARRAY_SIZE(dlc_table) - 1)];
1695 : }
1696 :
1697 : /**
1698 : * @brief Convert from number of bytes to Data Length Code (DLC)
1699 : *
1700 : * @param num_bytes Number of bytes.
1701 : *
1702 : * @retval Data Length Code (DLC).
1703 : */
1704 1 : static inline uint8_t can_bytes_to_dlc(uint8_t num_bytes)
1705 : {
1706 : return num_bytes <= 8 ? num_bytes :
1707 : num_bytes <= 12 ? 9 :
1708 : num_bytes <= 16 ? 10 :
1709 : num_bytes <= 20 ? 11 :
1710 : num_bytes <= 24 ? 12 :
1711 : num_bytes <= 32 ? 13 :
1712 : num_bytes <= 48 ? 14 :
1713 : 15;
1714 : }
1715 :
1716 : /**
1717 : * @brief Check if a CAN frame matches a CAN filter
1718 : *
1719 : * @param frame CAN frame.
1720 : * @param filter CAN filter.
1721 : * @return true if the CAN frame matches the CAN filter, false otherwise
1722 : */
1723 1 : static inline bool can_frame_matches_filter(const struct can_frame *frame,
1724 : const struct can_filter *filter)
1725 : {
1726 : if ((frame->flags & CAN_FRAME_IDE) != 0 && (filter->flags & CAN_FILTER_IDE) == 0) {
1727 : /* Extended (29-bit) ID frame, standard (11-bit) filter */
1728 : return false;
1729 : }
1730 :
1731 : if ((frame->flags & CAN_FRAME_IDE) == 0 && (filter->flags & CAN_FILTER_IDE) != 0) {
1732 : /* Standard (11-bit) ID frame, extended (29-bit) filter */
1733 : return false;
1734 : }
1735 :
1736 : if ((frame->id ^ filter->id) & filter->mask) {
1737 : /* Masked ID mismatch */
1738 : return false;
1739 : }
1740 :
1741 : return true;
1742 : }
1743 :
1744 : /** @} */
1745 :
1746 : /**
1747 : * @}
1748 : */
1749 :
1750 : #ifdef __cplusplus
1751 : }
1752 : #endif
1753 :
1754 : #include <zephyr/syscalls/can.h>
1755 :
1756 : #endif /* ZEPHYR_INCLUDE_DRIVERS_CAN_H_ */
|
