6  * SPDX-License-Identifier: Apache-2.0
11  * @brief Controller Area Network (CAN) driver API.
31  * @brief CAN Interface
32  * @defgroup can_interface CAN Interface
40  * @name CAN frame definitions
45  * @brief Bit mask for a standard (11-bit) CAN identifier.
50  * @brief Bit mask for an extended (29-bit) CAN identifier.
55  * @brief Maximum data length code for CAN 2.0A/2.0B.
60  * @brief Maximum data length code for CAN FD.
79  * @name CAN controller mode flags
94 /** Controller allows transmitting/receiving CAN FD frames. */
103 /** Controller requires manual recovery after entering bus-off state */
109  * @brief Provides a type to hold CAN controller configuration flags.
111  * The lower 24 bits are reserved for common CAN controller mode flags. The upper 8 bits are
112  * reserved for CAN controller/driver specific flags.
119  * @brief Defines the state of the CAN controller
122 	/** Error-active state (RX/TX error count < 96). */
124 	/** Error-warning state (RX/TX error count < 128). */
126 	/** Error-passive state (RX/TX error count < 256). */
128 	/** Bus-off state (RX/TX error count >= 256). */
130 	/** CAN controller is stopped and does not participate in CAN communication. */
135  * @name CAN frame flags
141 /** Frame uses extended (29-bit) CAN ID */
147 /** Frame uses CAN FD format (FDF) */
150 /** Frame uses CAN FD Baud Rate Switch (BRS). Only valid in combination with ``CAN_FRAME_FDF``. */
153 /** CAN FD Error State Indicator (ESI). Indicates that the transmitting node is in error-passive
161  * @brief CAN frame structure
164 	/** Standard (11-bit) or extended (29-bit) CAN identifier. */
170 #if defined(CONFIG_CAN_RX_TIMESTAMP) || defined(__DOXYGEN__)
171 	/** Captured value of the free-running timer in the CAN controller when
195  * @name CAN filter flags
201 /** Filter matches frames with extended (29-bit) CAN IDs */
207  * @brief CAN filter structure
210 	/** CAN identifier to match. */
212 	/** CAN identifier matching mask. If a bit in this mask is 0, the value
221  * @brief CAN controller error counters
224 	/** Value of the CAN controller transmit error counter. */
226 	/** Value of the CAN controller receive error counter. */
231  * @brief CAN bus timing structure
244  * +---------+----------+------------+------------+
246  * +---------+----------+------------+------------+
248  *                             Sampling-Point
259  * sample point can be moved. The sample point is moved when resynchronization
299  * @param state     State of the CAN controller.
300  * @param err_cnt   CAN controller error counter values.
317  * Calculates the TDC Offset in minimum time quanta (mtq) using the sample point and CAN core clock
328 	CLAMP((1U + _timing_data->prop_seg + _timing_data->phase_seg1) * _timing_data->prescaler,  \
332  * @brief Common CAN controller driver configuration.
334  * This structure is common to all CAN controller drivers and is expected to be the first element in
338 	/** Pointer to the device structure for the associated CAN transceiver device or NULL. */
340 	/** The minimum bitrate supported by the CAN controller/transceiver combination. */
342 	/** The maximum bitrate supported by the CAN controller/transceiver combination. */
344 	/** Initial CAN classic/CAN FD arbitration phase bitrate. */
346 	/** Initial CAN classic/CAN FD arbitration phase sample point in permille. */
349 	/** Initial CAN FD data phase sample point in permille. */
351 	/** Initial CAN FD data phase bitrate. */
360  * @param _min_bitrate minimum bitrate supported by the CAN controller
361  * @param _max_bitrate maximum bitrate supported by the CAN controller
381  * @param _min_bitrate minimum bitrate supported by the CAN controller
382  * @param _max_bitrate maximum bitrate supported by the CAN controller
389  * @brief Common CAN controller driver data.
391  * This structure is common to all CAN controller drivers and is expected to be the first element in
395 	/** Current CAN controller mode. */
397 	/** True if the CAN controller is started, false otherwise. */
406  * @brief Callback API upon setting CAN bus timing
413  * @brief Optional callback API upon setting CAN FD bus timing for the data phase.
420  * @brief Callback API upon getting CAN controller capabilities
426  * @brief Callback API upon starting CAN controller
432  * @brief Callback API upon stopping CAN controller
438  * @brief Callback API upon setting CAN controller mode
444  * @brief Callback API upon sending a CAN frame
448  * provided if none is provided by the caller. This allows for simplifying the driver handling.
471  * @brief Optional callback API upon manually recovering the CAN controller from bus-off state
477  * @brief Callback API upon getting the CAN controller state
492  * @brief Callback API upon getting the CAN core clock rate
498  * @brief Optional callback API upon getting the maximum number of concurrent CAN RX filters
512 #if defined(CONFIG_CAN_MANUAL_RECOVERY_MODE) || defined(__DOXYGEN__)
523 #if defined(CONFIG_CAN_FD_MODE) || defined(__DOXYGEN__)
534 #if defined(CONFIG_CAN_STATS) || defined(__DOXYGEN__)
540 STATS_SECT_START(can)
551 STATS_NAME_START(can)
552 STATS_NAME(can, bit_error)
553 STATS_NAME(can, bit0_error)
554 STATS_NAME(can, bit1_error)
555 STATS_NAME(can, stuff_error)
556 STATS_NAME(can, crc_error)
557 STATS_NAME(can, form_error)
558 STATS_NAME(can, ack_error)
559 STATS_NAME(can, rx_overrun)
560 STATS_NAME_END(can);
565  * @brief CAN specific device state which allows for CAN device class specific
571 	/** CAN device statistics */
578  * @brief Get pointer to CAN statistics structure
581 	CONTAINER_OF(dev_->state, struct can_device_state, devstate)->stats
586  * @brief Increment the bit error counter for a CAN device
588  * The bit error counter is incremented when the CAN controller is unable to
591  * @note This error counter should only be incremented if the CAN controller is unable to
592  * distinguish between failure to transmit a dominant versus failure to transmit a recessive bit. If
593  * the CAN controller supports distinguishing between the two, the `bit0` or `bit1` error counter
605  * @brief Increment the bit0 error counter for a CAN device
607  * The bit0 error counter is incremented when the CAN controller is unable to
622  * @brief Increment the bit1 (recessive) error counter for a CAN device
624  * The bit1 error counter is incremented when the CAN controller is unable to
639  * @brief Increment the stuffing error counter for a CAN device
641  * The stuffing error counter is incremented when the CAN controller detects a
650  * @brief Increment the CRC error counter for a CAN device
652  * The CRC error counter is incremented when the CAN controller detects a frame
661  * @brief Increment the form error counter for a CAN device
663  * The form error counter is incremented when the CAN controller detects a
664  * fixed-form bit field containing illegal bits.
672  * @brief Increment the acknowledge error counter for a CAN device
674  * The acknowledge error counter is incremented when the CAN controller does not
683  * @brief Increment the RX overrun counter for a CAN device
685  * The RX overrun counter is incremented when the CAN controller receives a CAN
695  * @brief Zero all statistics for a CAN device
697  * The driver is responsible for resetting the statistics before starting the CAN
708  * @brief Define a statically allocated and section assigned CAN device state
715  * @brief Define a CAN device init wrapper function
724 			CONTAINER_OF(dev->state, struct can_device_state, devstate); \
725 		stats_init(&state->stats.s_hdr, STATS_SIZE_32, 8,	\
726 			   STATS_NAME_INIT_PARMS(can));			\
727 		stats_register(dev->name, &(state->stats.s_hdr));	\
728 		if (!is_null_no_warn(init_fn)) {			\
738  * @brief Like DEVICE_DT_DEFINE() with CAN device specifics.
740  * @details Defines a device which implements the CAN API. May generate a custom
746  * @param pm        PM device resources reference (NULL if device does not use PM).
755  *                  used by the driver. Can be NULL.
799  * @name CAN controller configuration
805  * @brief Get the CAN core clock rate
807  * Returns the CAN core clock rate. One minimum time quantum (mtq) is 1/(core clock rate). The CAN
808  * core clock can be further divided by the CAN clock prescaler (see the @a can_timing struct),
812  * @param[out] rate CAN core clock rate in Hz.
820 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_core_clock()
822 	return api->get_core_clock(dev, rate);  in z_impl_can_get_core_clock()
828  * Get the minimum supported bitrate for the CAN controller/transceiver combination.
830  * @note The minimum bitrate represents limitations of the CAN controller/transceiver
831  * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
832  * rate and the minimum CAN timing limits.
845 	const struct can_driver_config *common = (const struct can_driver_config *)dev->config;  in z_impl_can_get_bitrate_min()
847 	return common->min_bitrate;  in z_impl_can_get_bitrate_min()
853  * Get the maximum supported bitrate for the CAN controller/transceiver combination.
855  * @note The maximum bitrate represents limitations of the CAN controller/transceiver
856  * combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock
857  * rate and the maximum CAN timing limits.
870 	const struct can_driver_config *common = (const struct can_driver_config *)dev->config;  in z_impl_can_get_bitrate_max()
872 	return common->max_bitrate;  in z_impl_can_get_bitrate_max()
886 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_timing_min()
888 	return &api->timing_min;  in z_impl_can_get_timing_min()
902 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_timing_max()
904 	return &api->timing_max;  in z_impl_can_get_timing_max()
912  * always match perfectly. If no result can be reached for the given parameters,
913  * -EINVAL is returned.
915  * If the sample point is set to 0, this function defaults to a sample point of 75.0%
929  * @retval -EINVAL if the requested bitrate or sample point is out of range.
930  * @retval -ENOTSUP if the requested bitrate is not supported.
931  * @retval -EIO if @a can_get_core_clock() is not available.
946  * @return Pointer to the minimum supported timing parameter values, or NULL if
947  *         CAN FD support is not implemented by the driver.
954 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_timing_data_min()
956 	return &api->timing_data_min;  in z_impl_can_get_timing_data_min()
970  * @return Pointer to the maximum supported timing parameter values, or NULL if
971  *         CAN FD support is not implemented by the driver.
978 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_timing_data_max()
980 	return &api->timing_data_max;  in z_impl_can_get_timing_data_max()
1000  * @retval -EINVAL if the requested bitrate or sample point is out of range.
1001  * @retval -ENOTSUP if the requested bitrate is not supported.
1002  * @retval -EIO if @a can_get_core_clock() is not available.
1008  * @brief Configure the bus timing for the data phase of a CAN FD controller.
1018  * @retval 0 If successful.
1019  * @retval -EBUSY if the CAN controller is not in stopped state.
1020  * @retval -EIO General input/output error, failed to configure device.
1021  * @retval -ENOTSUP if the timing parameters are not supported by the driver.
1022  * @retval -ENOSYS if CAN FD support is not implemented by the driver.
1028  * @brief Set the bitrate for the data phase of the CAN FD controller
1030  * CAN in Automation (CiA) 301 v4.2.0 recommends a sample point location of
1031  * 87.5% percent for all bitrates. However, some CAN controllers have
1047  * @retval 0 If successful.
1048  * @retval -EBUSY if the CAN controller is not in stopped state.
1049  * @retval -EINVAL if the requested bitrate is out of range.
1050  * @retval -ENOTSUP if the requested bitrate not supported by the CAN controller/transceiver
1052  * @retval -ERANGE if the resulting sample point is off by more than +/- 5%.
1053  * @retval -EIO General input/output error, failed to set bitrate.
1058  * @brief Configure the bus timing of a CAN controller.
1065  * @retval 0 If successful.
1066  * @retval -EBUSY if the CAN controller is not in stopped state.
1067  * @retval -ENOTSUP if the timing parameters are not supported by the driver.
1068  * @retval -EIO General input/output error, failed to configure device.
1074  * @brief Get the supported modes of the CAN controller
1076  * The returned capabilities may not necessarily be supported at the same time (e.g. some CAN
1083  * @retval 0 If successful.
1084  * @retval -EIO General input/output error, failed to get capabilities.
1090 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_capabilities()
1092 	return api->get_capabilities(dev, cap);  in z_impl_can_get_capabilities()
1096  * @brief Get the CAN transceiver associated with the CAN controller
1098  * Get a pointer to the device structure for the CAN transceiver associated with the CAN controller.
1101  * @return Pointer to the device structure for the associated CAN transceiver driver instance, or
1102  *         NULL if no transceiver is associated.
1108 	const struct can_driver_config *common = (const struct can_driver_config *)dev->config;  in z_impl_can_get_transceiver()
1110 	return common->phy;  in z_impl_can_get_transceiver()
1114  * @brief Start the CAN controller
1116  * Bring the CAN controller out of `CAN_STATE_STOPPED`. This will reset the RX/TX error counters,
1117  * enable the CAN controller to participate in CAN communication, and enable the CAN transceiver, if
1120  * Starting the CAN controller resets all the CAN controller statistics.
1126  * @retval 0 if successful.
1127  * @retval -EALREADY if the device is already started.
1128  * @retval -EIO General input/output error, failed to start device.
1134 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_start()
1136 	return api->start(dev);  in z_impl_can_start()
1140  * @brief Stop the CAN controller
1142  * Bring the CAN controller into `CAN_STATE_STOPPED`. This will disallow the CAN controller from
1143  * participating in CAN communication, abort any pending CAN frame transmissions, and disable the
1144  * CAN transceiver, if supported.
1150  * @retval 0 if successful.
1151  * @retval -EALREADY if the device is already stopped.
1152  * @retval -EIO General input/output error, failed to stop device.
1158 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_stop()
1160 	return api->stop(dev);  in z_impl_can_stop()
1164  * @brief Set the CAN controller to the given operation mode
1169  * @retval 0 If successful.
1170  * @retval -EBUSY if the CAN controller is not in stopped state.
1171  * @retval -EIO General input/output error, failed to configure device.
1177 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_set_mode()
1179 	return api->set_mode(dev, mode);  in z_impl_can_set_mode()
1183  * @brief Get the operation mode of the CAN controller
1193 	const struct can_driver_data *common = (const struct can_driver_data *)dev->data;  in z_impl_can_get_mode()
1195 	return common->mode;  in z_impl_can_get_mode()
1199  * @brief Set the bitrate of the CAN controller
1201  * CAN in Automation (CiA) 301 v4.2.0 recommends a sample point location of
1202  * 87.5% percent for all bitrates. However, some CAN controllers have
1215  * @retval 0 If successful.
1216  * @retval -EBUSY if the CAN controller is not in stopped state.
1217  * @retval -EINVAL if the requested bitrate is out of range.
1218  * @retval -ENOTSUP if the requested bitrate not supported by the CAN controller/transceiver
1220  * @retval -ERANGE if the resulting sample point is off by more than +/- 5%.
1221  * @retval -EIO General input/output error, failed to set bitrate.
1228  * @name Transmitting CAN frames
1234  * @brief Queue a CAN frame for transmission on the CAN bus
1236  * Queue a CAN frame for transmission on the CAN bus with optional timeout and
1239  * Queued CAN frames are transmitted in order according to the their priority:
1240  * - The lower the CAN-ID, the higher the priority.
1241  * - Data frames have higher priority than Remote Transmission Request (RTR)
1242  *   frames with identical CAN-IDs.
1243  * - Frames with standard (11-bit) identifiers have higher priority than frames
1244  *   with extended (29-bit) identifiers with identical base IDs (the higher 11
1246  * - Transmission order for queued frames with the same priority is hardware
1249  * @note If transmitting segmented messages spanning multiple CAN frames with
1250  * identical CAN-IDs, the sender must ensure to only queue one frame at a time
1251  * if FIFO order is required.
1253  * By default, the CAN controller will automatically retry transmission in case
1254  * of lost bus arbitration or missing acknowledge. Some CAN controllers support
1258  * @param frame     CAN frame to transmit.
1261  *                  transmission error occurred. If ``NULL``, this function is
1263  *                  if called from user mode.
1266  * @retval 0 if successful.
1267  * @retval -EINVAL if an invalid parameter was passed to the function.
1268  * @retval -ENOTSUP if an unsupported parameter was passed to the function.
1269  * @retval -ENETDOWN if the CAN controller is in stopped state.
1270  * @retval -ENETUNREACH if the CAN controller is in bus-off state.
1271  * @retval -EBUSY if CAN bus arbitration was lost (only applicable if automatic
1273  * @retval -EIO if a general transmit error occurred (e.g. missing ACK if
1275  * @retval -EAGAIN on timeout.
1284  * @name Receiving CAN frames
1290  * @brief Add a callback function for a given CAN filter
1292  * Add a callback to CAN identifiers specified by a filter. When a received CAN
1293  * frame matching the filter is received by the CAN controller, the callback
1296  * If a received frame matches more than one filter (i.e., the filter IDs/masks or
1299  * The same callback function can be used for multiple filters.
1302  * @param callback  This function is called by the CAN controller driver whenever
1308  * @retval -ENOSPC if there are no free filters.
1309  * @retval -EINVAL if the requested filter type is invalid.
1310  * @retval -ENOTSUP if the requested filter type is not supported.
1316  * @brief Statically define and initialize a CAN RX message queue.
1318  * The message queue's ring buffer contains space for @a max_frames CAN frames.
1323  * @param max_frames Maximum number of CAN frames that can be queued.
1331  * Wrapper function for @a can_add_rx_filter() which puts received CAN frames
1334  * If a received frame matches more than one filter (i.e., the filter IDs/masks or
1337  * The same message queue can be used for multiple filters.
1343  * discarded. Custom error handling can be implemented by using
1351  * @retval -ENOSPC if there are no free filters.
1352  * @retval -ENOTSUP if the requested filter type is not supported.
1358  * @brief Remove a CAN RX filter
1360  * This routine removes a CAN RX filter based on the filter ID returned by @a
1370 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_remove_rx_filter()
1372 	api->remove_rx_filter(dev, filter_id);  in z_impl_can_remove_rx_filter()
1378  * Get the maximum number of concurrent RX filters for the CAN controller.
1381  * @param ide Get the maximum standard (11-bit) CAN ID filters if false, or extended (29-bit) CAN ID
1382  *            filters if true.
1385  * @retval -EIO General input/output error.
1386  * @retval -ENOSYS If this function is not implemented by the driver.
1392 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_max_filters()
1394 	if (api->get_max_filters == NULL) {  in z_impl_can_get_max_filters()
1395 		return -ENOSYS;  in z_impl_can_get_max_filters()
1398 	return api->get_max_filters(dev, ide);  in z_impl_can_get_max_filters()
1404  * @name CAN bus error reporting and handling
1410  * @brief Get current CAN controller state
1412  * Returns the current state and optionally the error counter values of the CAN
1419  * @retval 0 If successful.
1420  * @retval -EIO General input/output error, failed to get state.
1428 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_get_state()
1430 	return api->get_state(dev, state, err_cnt);  in z_impl_can_get_state()
1434  * @brief Recover from bus-off state
1436  * Recover the CAN controller from bus-off state to error-active state.
1445  * @retval -ENOTSUP if the CAN controller is not in manual recovery mode.
1446  * @retval -ENETDOWN if the CAN controller is in stopped state.
1447  * @retval -EAGAIN on timeout.
1448  * @retval -ENOSYS If this function is not implemented by the driver.
1455 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in z_impl_can_recover()
1457 	if (api->recover == NULL) {  in z_impl_can_recover()
1458 		return -ENOSYS;  in z_impl_can_recover()
1461 	return api->recover(dev, timeout);  in z_impl_can_recover()
1466  * @brief Set a callback for CAN controller state change events
1468  * Set the callback for CAN controller state change events. The callback
1471  * Only one callback can be registered per controller. Calling this function
1482 	const struct can_driver_api *api = (const struct can_driver_api *)dev->api;  in can_set_state_change_callback()
1484 	api->set_state_change_callback(dev, callback, user_data);  in can_set_state_change_callback()
1490  * @name CAN statistics
1496  * @brief Get the bit error counter for a CAN device
1498  * The bit error counter is incremented when the CAN controller is unable to
1517  * @brief Get the bit0 error counter for a CAN device
1519  * The bit0 error counter is incremented when the CAN controller is unable to
1540  * @brief Get the bit1 error counter for a CAN device
1542  * The bit1 error counter is incremented when the CAN controller is unable to
1563  * @brief Get the stuffing error counter for a CAN device
1565  * The stuffing error counter is incremented when the CAN controller detects a
1584  * @brief Get the CRC error counter for a CAN device
1586  * The CRC error counter is incremented when the CAN controller detects a frame
1605  * @brief Get the form error counter for a CAN device
1607  * The form error counter is incremented when the CAN controller detects a
1608  * fixed-form bit field containing illegal bits.
1626  * @brief Get the acknowledge error counter for a CAN device
1628  * The acknowledge error counter is incremented when the CAN controller does not
1647  * @brief Get the RX overrun counter for a CAN device
1649  * The RX overrun counter is incremented when the CAN controller receives a CAN
1671  * @name CAN utility functions
1688 	return dlc_table[MIN(dlc, ARRAY_SIZE(dlc_table) - 1)];  in can_dlc_to_bytes()
1711  * @brief Check if a CAN frame matches a CAN filter
1713  * @param frame CAN frame.
1714  * @param filter CAN filter.
1715  * @return true if the CAN frame matches the CAN filter, false otherwise
1720 	if ((frame->flags & CAN_FRAME_IDE) != 0 && (filter->flags & CAN_FILTER_IDE) == 0) {  in can_frame_matches_filter()
1721 		/* Extended (29-bit) ID frame, standard (11-bit) filter */  in can_frame_matches_filter()
1725 	if ((frame->flags & CAN_FRAME_IDE) == 0 && (filter->flags & CAN_FILTER_IDE) != 0) {  in can_frame_matches_filter()
1726 		/* Standard (11-bit) ID frame, extended (29-bit) filter */  in can_frame_matches_filter()
1730 	if ((frame->id ^ filter->id) & filter->mask) {  in can_frame_matches_filter()
1748 #include <zephyr/syscalls/can.h>