1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef R_CAN_API_H 8 #define R_CAN_API_H 9 10 /*******************************************************************************************************************//** 11 * @ingroup RENESAS_CONNECTIVITY_INTERFACES 12 * @defgroup CAN_API CAN Interface 13 * @brief Interface for CAN peripheral 14 * 15 * @section CAN_INTERFACE_SUMMARY Summary 16 * The CAN interface provides common APIs for CAN HAL drivers. CAN interface supports following features. 17 * - Full-duplex CAN communication 18 * - Generic CAN parameter setting 19 * - Interrupt driven transmit/receive processing 20 * - Callback function support with returning event code 21 * - Hardware resource locking during a transaction 22 * 23 * @{ 24 **********************************************************************************************************************/ 25 26 /*********************************************************************************************************************** 27 * Includes 28 **********************************************************************************************************************/ 29 30 /* Includes board and MCU related header files. */ 31 #include "bsp_api.h" 32 33 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 34 FSP_HEADER 35 36 /********************************************************************************************************************** 37 * Macro definitions 38 **********************************************************************************************************************/ 39 40 #if BSP_FEATURE_CANFD_NUM_CHANNELS 41 #define CAN_DATA_BUFFER_LENGTH (64) 42 #else 43 #define CAN_DATA_BUFFER_LENGTH (8) 44 #endif 45 46 /********************************************************************************************************************** 47 * Typedef definitions 48 **********************************************************************************************************************/ 49 50 /** CAN event codes */ 51 typedef enum e_can_event 52 { 53 CAN_EVENT_ERR_WARNING = 0x0002, ///< Error Warning event. 54 CAN_EVENT_ERR_PASSIVE = 0x0004, ///< Error Passive event. 55 CAN_EVENT_ERR_BUS_OFF = 0x0008, ///< Bus Off event. 56 CAN_EVENT_BUS_RECOVERY = 0x0010, ///< Bus Off Recovery event. 57 CAN_EVENT_MAILBOX_MESSAGE_LOST = 0x0020, ///< Mailbox has been overrun. 58 CAN_EVENT_ERR_BUS_LOCK = 0x0080, ///< Bus lock detected (32 consecutive dominant bits). 59 CAN_EVENT_ERR_CHANNEL = 0x0100, ///< Channel error has occurred. 60 CAN_EVENT_TX_ABORTED = 0x0200, ///< Transmit abort event. 61 CAN_EVENT_RX_COMPLETE = 0x0400, ///< Receive complete event. 62 CAN_EVENT_TX_COMPLETE = 0x0800, ///< Transmit complete event. 63 CAN_EVENT_ERR_GLOBAL = 0x1000, ///< Global error has occurred. 64 CAN_EVENT_TX_FIFO_EMPTY = 0x2000, ///< Transmit FIFO is empty. 65 CAN_EVENT_FIFO_MESSAGE_LOST = 0x4000, ///< Receive FIFO overrun. 66 } can_event_t; 67 68 /** CAN Operation modes */ 69 typedef enum e_can_operation_mode 70 { 71 CAN_OPERATION_MODE_NORMAL = 0, ///< CAN Normal Operation Mode 72 CAN_OPERATION_MODE_RESET, ///< CAN Reset Operation Mode 73 CAN_OPERATION_MODE_HALT, ///< CAN Halt Operation Mode 74 CAN_OPERATION_MODE_SLEEP = 5, ///< CAN Sleep Operation Mode 75 CAN_OPERATION_MODE_GLOBAL_OPERATION = 0x80, // CANFD Global Operation Mode 76 CAN_OPERATION_MODE_GLOBAL_RESET, // CANFD Global Reset Mode 77 CAN_OPERATION_MODE_GLOBAL_HALT, // CANFD Global Halt Mode 78 CAN_OPERATION_MODE_GLOBAL_SLEEP = 0x85 // CANFD Global Sleep Mode 79 } can_operation_mode_t; 80 81 /** CAN Test modes */ 82 typedef enum e_can_test_mode 83 { 84 CAN_TEST_MODE_DISABLED = 0, ///< CAN Test Mode Disabled. 85 CAN_TEST_MODE_LISTEN = 3, ///< CAN Test Listen Mode. 86 CAN_TEST_MODE_LOOPBACK_EXTERNAL = 5, ///< CAN Test External Loopback Mode. 87 CAN_TEST_MODE_LOOPBACK_INTERNAL = 7, ///< CAN Test Internal Loopback Mode. 88 CAN_TEST_MODE_INTERNAL_BUS = 0x80 ///< CANFD Internal CAN Bus Communication Test Mode. 89 } can_test_mode_t; 90 91 /** CAN status info */ 92 typedef struct st_can_info 93 { 94 uint32_t status; ///< Useful information from the CAN status register. 95 uint32_t rx_mb_status; ///< RX Message Buffer New Data flags. 96 uint32_t rx_fifo_status; ///< RX FIFO Empty flags. 97 uint8_t error_count_transmit; ///< Transmit error count. 98 uint8_t error_count_receive; ///< Receive error count. 99 uint32_t error_code; ///< Error code, cleared after reading. 100 } can_info_t; 101 102 /** CAN ID modes */ 103 typedef enum e_can_id_mode 104 { 105 CAN_ID_MODE_STANDARD, ///< Standard IDs of 11 bits used. 106 CAN_ID_MODE_EXTENDED, ///< Extended IDs of 29 bits used. 107 } can_id_mode_t; 108 109 /** CAN frame types */ 110 typedef enum e_can_frame_type 111 { 112 CAN_FRAME_TYPE_DATA, ///< Data frame. 113 CAN_FRAME_TYPE_REMOTE, ///< Remote frame. 114 } can_frame_type_t; 115 116 /** CAN bit rate configuration. */ 117 typedef struct st_can_bit_timing_cfg 118 { 119 uint32_t baud_rate_prescaler; ///< Baud rate prescaler. Valid values: 1 - 1024. 120 uint32_t time_segment_1; ///< Time segment 1 control. 121 uint32_t time_segment_2; ///< Time segment 2 control. 122 uint32_t synchronization_jump_width; ///< Synchronization jump width. 123 } can_bit_timing_cfg_t; 124 125 /** CAN data Frame */ 126 typedef struct st_can_frame 127 { 128 uint32_t id; ///< CAN ID. 129 can_id_mode_t id_mode; ///< Standard or Extended ID (IDE). 130 can_frame_type_t type; ///< Frame type (RTR). 131 uint8_t data_length_code; ///< CAN Data Length Code (DLC). 132 uint32_t options; ///< Implementation-specific options. 133 uint8_t data[CAN_DATA_BUFFER_LENGTH]; ///< CAN data. 134 } can_frame_t; 135 136 /** CAN callback parameter definition */ 137 typedef struct st_can_callback_args 138 { 139 uint32_t channel; ///< Device channel number. 140 can_event_t event; ///< Event code. 141 uint32_t error; ///< Error code. 142 union 143 { 144 uint32_t mailbox; ///< Mailbox number of interrupt source. 145 uint32_t buffer; ///< Buffer number of interrupt source. 146 }; 147 void const * p_context; ///< Context provided to user during callback. 148 can_frame_t frame; ///< Received frame data. 149 } can_callback_args_t; 150 151 /** CAN Configuration */ 152 typedef struct st_can_cfg 153 { 154 /* CAN generic configuration */ 155 uint32_t channel; ///< CAN channel. 156 can_bit_timing_cfg_t * p_bit_timing; ///< CAN bit timing. 157 158 /* Configuration for CAN Event processing */ 159 void (* p_callback)(can_callback_args_t * p_args); ///< Pointer to callback function 160 void const * p_context; ///< User defined callback context. 161 162 /* Pointer to CAN peripheral specific configuration */ 163 void const * p_extend; ///< CAN hardware dependent configuration 164 uint8_t ipl; ///< Error/Transmit/Receive interrupt priority 165 IRQn_Type error_irq; ///< Error IRQ number 166 IRQn_Type rx_irq; ///< Receive IRQ number 167 IRQn_Type tx_irq; ///< Transmit IRQ number 168 } can_cfg_t; 169 170 /** CAN control block. Allocate an instance specific control block to pass into the CAN API calls. 171 */ 172 typedef void can_ctrl_t; 173 174 /** Shared Interface definition for CAN */ 175 typedef struct st_can_api 176 { 177 /** Open function for CAN device 178 * 179 * @param[in,out] p_ctrl Pointer to the CAN control block. Must be declared by user. Value set here. 180 * @param[in] p_cfg Pointer to CAN configuration structure. All elements of this structure must be set by 181 * user. 182 */ 183 fsp_err_t (* open)(can_ctrl_t * const p_ctrl, can_cfg_t const * const p_cfg); 184 185 /** Write function for CAN device 186 * @param[in] p_ctrl Pointer to the CAN control block. 187 * @param[in] buffer Buffer number (mailbox or message buffer) to write to. 188 * @param[in] p_frame Pointer for frame of CAN ID, DLC, data and frame type to write. 189 */ 190 fsp_err_t (* write)(can_ctrl_t * const p_ctrl, uint32_t buffer_number, can_frame_t * const p_frame); 191 192 /** Read function for CAN device 193 * @param[in] p_ctrl Pointer to the CAN control block. 194 * @param[in] buffer Message buffer (number) to read from. 195 * @param[in] p_frame Pointer to store the CAN ID, DLC, data and frame type. 196 */ 197 fsp_err_t (* read)(can_ctrl_t * const p_ctrl, uint32_t buffer_number, can_frame_t * const p_frame); 198 199 /** Close function for CAN device 200 * @param[in] p_ctrl Pointer to the CAN control block. 201 */ 202 fsp_err_t (* close)(can_ctrl_t * const p_ctrl); 203 204 /** Mode Transition function for CAN device 205 * @param[in] p_ctrl Pointer to the CAN control block. 206 * @param[in] operation_mode Destination CAN operation state. 207 * @param[in] test_mode Destination CAN test state. 208 */ 209 fsp_err_t (* modeTransition)(can_ctrl_t * const p_ctrl, can_operation_mode_t operation_mode, 210 can_test_mode_t test_mode); 211 212 /** Get CAN channel info. 213 * 214 * @param[in] p_ctrl Handle for channel (pointer to channel control block) 215 * @param[out] p_info Memory address to return channel specific data to. 216 */ 217 fsp_err_t (* infoGet)(can_ctrl_t * const p_ctrl, can_info_t * const p_info); 218 219 /** Specify callback function and optional context pointer and working memory pointer. 220 * 221 * @param[in] p_ctrl Control block set in @ref can_api_t::open call. 222 * @param[in] p_callback Callback function to register 223 * @param[in] p_context Pointer to send to callback function 224 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 225 * Callback arguments allocated here are only valid during the callback. 226 */ 227 fsp_err_t (* callbackSet)(can_ctrl_t * const p_ctrl, void (* p_callback)(can_callback_args_t *), 228 void const * const p_context, can_callback_args_t * const p_callback_memory); 229 } can_api_t; 230 231 /** This structure encompasses everything that is needed to use an instance of this interface. */ 232 typedef struct st_can_instance 233 { 234 can_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 235 can_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 236 can_api_t const * p_api; ///< Pointer to the API structure for this instance 237 } can_instance_t; 238 239 /*******************************************************************************************************************//** 240 * @} (end defgroup CAN_API) 241 **********************************************************************************************************************/ 242 243 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 244 FSP_FOOTER 245 246 #endif 247
