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