diff --git a/drivers/can/can_esp32_twai.c b/drivers/can/can_esp32_twai.c index 06595e57e84..cd0d6bad6ec 100644 --- a/drivers/can/can_esp32_twai.c +++ b/drivers/can/can_esp32_twai.c @@ -7,7 +7,7 @@ #define DT_DRV_COMPAT espressif_esp32_twai -#include "can_sja1000.h" +#include #include #include diff --git a/drivers/can/can_kvaser_pci.c b/drivers/can/can_kvaser_pci.c index 248f37b2a86..39ed411cc67 100644 --- a/drivers/can/can_kvaser_pci.c +++ b/drivers/can/can_kvaser_pci.c @@ -6,7 +6,7 @@ #define DT_DRV_COMPAT kvaser_pcican -#include "can_sja1000.h" +#include #include #include diff --git a/drivers/can/can_sja1000.c b/drivers/can/can_sja1000.c index 5790032206e..a83cecf4fee 100644 --- a/drivers/can/can_sja1000.c +++ b/drivers/can/can_sja1000.c @@ -4,7 +4,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -#include "can_sja1000.h" +#include #include "can_sja1000_priv.h" #include diff --git a/drivers/can/can_sja1000.h b/include/zephyr/drivers/can/can_sja1000.h similarity index 57% rename from drivers/can/can_sja1000.h rename to include/zephyr/drivers/can/can_sja1000.h index d4baa821806..a85dc2ffa53 100644 --- a/drivers/can/can_sja1000.h +++ b/include/zephyr/drivers/can/can_sja1000.h @@ -4,12 +4,21 @@ * SPDX-License-Identifier: Apache-2.0 */ -#ifndef ZEPHYR_DRIVERS_CAN_SJA1000_H_ -#define ZEPHYR_DRIVERS_CAN_SJA1000_H_ +/** + * @file + * @brief API for NXP SJA1000 (and compatible) CAN controller frontend drivers. + */ + +#ifndef ZEPHYR_INCLUDE_DRIVERS_CAN_CAN_SJA1000_H_ +#define ZEPHYR_INCLUDE_DRIVERS_CAN_CAN_SJA1000_H_ #include -/* Output Control Register (OCR) bits */ +/** + * @name SJA1000 Output Control Register (OCR) bits + * + * @{ + */ #define CAN_SJA1000_OCR_OCMODE_MASK GENMASK(1, 0) #define CAN_SJA1000_OCR_OCPOL0 BIT(2) #define CAN_SJA1000_OCR_OCTN0 BIT(3) @@ -23,7 +32,13 @@ #define CAN_SJA1000_OCR_OCMODE_NORMAL FIELD_PREP(CAN_SJA1000_OCR_OCMODE_MASK, 2U) #define CAN_SJA1000_OCR_OCMODE_CLOCK FIELD_PREP(CAN_SJA1000_OCR_OCMODE_MASK, 3U) -/* Clock Divider Register (CDR) bits */ +/** @} */ + +/** + * @name SJA1000 Clock Divider Register (CDR) bits + * + * @{ + */ #define CAN_SJA1000_CDR_CD_MASK GENMASK(2, 0) #define CAN_SJA1000_CDR_CLOCK_OFF BIT(3) #define CAN_SJA1000_CDR_RXINTEN BIT(5) @@ -39,6 +54,11 @@ #define CAN_SJA1000_CDR_CD_DIV12 FIELD_PREP(CAN_SJA1000_CDR_CD_MASK, 5U) #define CAN_SJA1000_CDR_CD_DIV14 FIELD_PREP(CAN_SJA1000_CDR_CD_MASK, 6U) +/** @} */ + +/** + * @brief SJA1000 specific static initializer for a minimum @p can_timing struct + */ #define CAN_SJA1000_TIMING_MIN_INITIALIZER \ { \ .sjw = 1, \ @@ -48,6 +68,9 @@ .prescaler = 1 \ } +/** + * @brief SJA1000 specific static initializer for a maximum @p can_timing struct + */ #define CAN_SJA1000_TIMING_MAX_INITIALIZER \ { \ .sjw = 4, \ @@ -57,10 +80,27 @@ .prescaler = 64 \ } +/** + * @brief SJA1000 driver front-end callback for writing a register value + * + * @param dev Pointer to the device structure for the driver instance. + * @param reg Register offset + * @param val Register value + */ typedef void (*can_sja1000_write_reg_t)(const struct device *dev, uint8_t reg, uint8_t val); +/** + * @brief SJA1000 driver front-end callback for reading a register value + * + * @param dev Pointer to the device structure for the driver instance. + * @param reg Register offset + * @retval Register value + */ typedef uint8_t (*can_sja1000_read_reg_t)(const struct device *dev, uint8_t reg); +/** + * @brief SJA1000 driver internal configuration structure. + */ struct can_sja1000_config { can_sja1000_read_reg_t read_reg; can_sja1000_write_reg_t write_reg; @@ -76,6 +116,16 @@ struct can_sja1000_config { const void *custom; }; +/** + * @brief Static initializer for @p can_sja1000_config struct + * + * @param node_id Devicetree node identifier + * @param _custom Pointer to custom driver frontend configuration structure + * @param _read_reg Driver frontend SJA100 register read function + * @param _write_reg Driver frontend SJA100 register write function + * @param _ocr Initial SJA1000 Output Control Register (OCR) value + * @param _cdr Initial SJA1000 Clock Divider Register (CDR) value + */ #define CAN_SJA1000_DT_CONFIG_GET(node_id, _custom, _read_reg, _write_reg, _ocr, _cdr) \ { \ .read_reg = _read_reg, .write_reg = _write_reg, \ @@ -88,15 +138,32 @@ struct can_sja1000_config { .ocr = _ocr, .cdr = _cdr, .custom = _custom, \ } +/** + * @brief Static initializer for @p can_sja1000_config struct from a DT_DRV_COMPAT instance + * + * @param inst DT_DRV_COMPAT instance number + * @param _custom Pointer to custom driver frontend configuration structure + * @param _read_reg Driver frontend SJA100 register read function + * @param _write_reg Driver frontend SJA100 register write function + * @param _ocr Initial SJA1000 Output Control Register (OCR) value + * @param _cdr Initial SJA1000 Clock Divider Register (CDR) value + * @see CAN_SJA1000_DT_CONFIG_GET() + */ #define CAN_SJA1000_DT_CONFIG_INST_GET(inst, _custom, _read_reg, _write_reg, _ocr, _cdr) \ CAN_SJA1000_DT_CONFIG_GET(DT_DRV_INST(inst), _custom, _read_reg, _write_reg, _ocr, _cdr) +/** + * @brief SJA1000 driver internal RX filter structure. + */ struct can_sja1000_rx_filter { struct can_filter filter; can_rx_callback_t callback; void *user_data; }; +/** + * @brief SJA1000 driver internal data structure. + */ struct can_sja1000_data { ATOMIC_DEFINE(rx_allocs, CONFIG_CAN_MAX_FILTER); struct can_sja1000_rx_filter filters[CONFIG_CAN_MAX_FILTER]; @@ -113,45 +180,111 @@ struct can_sja1000_data { void *custom; }; +/** + * @brief Initializer for a @a can_sja1000_data struct + * @param _custom Pointer to custom driver frontend data structure + */ #define CAN_SJA1000_DATA_INITIALIZER(_custom) \ { \ .custom = _custom, \ } +/** + * @brief SJA1000 callback API upon setting CAN bus timing + * See @a can_set_timing() for argument description + */ int can_sja1000_set_timing(const struct device *dev, const struct can_timing *timing); +/** + * @brief SJA1000 callback API upon getting CAN controller capabilities + * See @a can_get_capabilities() for argument description + */ int can_sja1000_get_capabilities(const struct device *dev, can_mode_t *cap); +/** + * @brief SJA1000 callback API upon starting CAN controller + * See @a can_start() for argument description + */ int can_sja1000_start(const struct device *dev); +/** + * @brief SJA1000 callback API upon stopping CAN controller + * See @a can_stop() for argument description + */ int can_sja1000_stop(const struct device *dev); +/** + * @brief SJA1000 callback API upon setting CAN controller mode + * See @a can_set_mode() for argument description + */ int can_sja1000_set_mode(const struct device *dev, can_mode_t mode); +/** + * @brief SJA1000 callback API upon sending a CAN frame + * See @a can_send() for argument description + */ int can_sja1000_send(const struct device *dev, const struct can_frame *frame, k_timeout_t timeout, can_tx_callback_t callback, void *user_data); +/** + * @brief SJA1000 callback API upon adding an RX filter + * See @a can_add_rx_callback() for argument description + */ int can_sja1000_add_rx_filter(const struct device *dev, can_rx_callback_t callback, void *user_data, const struct can_filter *filter); +/** + * @brief SJA1000 callback API upon removing an RX filter + * See @a can_remove_rx_filter() for argument description + */ void can_sja1000_remove_rx_filter(const struct device *dev, int filter_id); #ifndef CONFIG_CAN_AUTO_BUS_OFF_RECOVERY +/** + * @brief SJA1000 callback API upon recovering the CAN bus + * See @a can_recover() for argument description + */ int can_sja1000_recover(const struct device *dev, k_timeout_t timeout); #endif /* !CONFIG_CAN_AUTO_BUS_OFF_RECOVERY */ +/** + * @brief SJA1000 callback API upon getting the CAN controller state + * See @a can_get_state() for argument description + */ int can_sja1000_get_state(const struct device *dev, enum can_state *state, struct can_bus_err_cnt *err_cnt); +/** + * @brief SJA1000 callback API upon setting a state change callback + * See @a can_set_state_change_callback() for argument description + */ void can_sja1000_set_state_change_callback(const struct device *dev, can_state_change_callback_t callback, void *user_data); +/** + * @brief SJA1000 callback API upon getting the maximum number of concurrent CAN RX filters + * See @a can_get_max_filters() for argument description + */ int can_sja1000_get_max_filters(const struct device *dev, bool ide); +/** + * @brief SJA1000 callback API upon getting the maximum supported bitrate + * See @a can_get_max_bitrate() for argument description + */ int can_sja1000_get_max_bitrate(const struct device *dev, uint32_t *max_bitrate); +/** + * @brief SJA1000 IRQ handler callback. + * + * @param dev Pointer to the device structure for the driver instance. + */ void can_sja1000_isr(const struct device *dev); +/** + * @brief SJA1000 driver initialization callback. + * + * @param dev Pointer to the device structure for the driver instance. + */ int can_sja1000_init(const struct device *dev); -#endif /* ZEPHYR_DRIVERS_CAN_SJA1000_H_ */ +#endif /* ZEPHYR_INCLUDE_DRIVERS_CAN_CAN_SJA1000_H_ */