1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_NETWORKING_INTERFACES 9 * @defgroup ETHER_API Ethernet Interface 10 * @brief Interface for Ethernet functions. 11 * 12 * @section ETHER_API_Summary Summary 13 * The Ethernet interface provides Ethernet functionality. 14 * The Ethernet interface supports the following features: 15 * - Transmit/receive processing (Blocking and Non-Blocking) 16 * - Callback function with returned event code 17 * - Magic packet detection mode support 18 * - Auto negotiation support 19 * - Flow control support 20 * - Multicast filtering support 21 * 22 * 23 * @{ 24 **********************************************************************************************************************/ 25 26 #ifndef R_ETHER_API_H 27 #define R_ETHER_API_H 28 29 /*********************************************************************************************************************** 30 * Includes 31 **********************************************************************************************************************/ 32 33 /* Register definitions, common services and error codes. */ 34 #include "bsp_api.h" 35 #include "r_ether_phy_api.h" 36 37 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 38 FSP_HEADER 39 40 /********************************************************************************************************************** 41 * Macro definitions 42 **********************************************************************************************************************/ 43 44 /********************************************************************************************************************** 45 * Typedef definitions 46 **********************************************************************************************************************/ 47 48 /** Wake on LAN */ 49 typedef enum e_ether_wake_on_lan 50 { 51 ETHER_WAKE_ON_LAN_DISABLE = 0, ///< Disable Wake on LAN 52 ETHER_WAKE_ON_LAN_ENABLE = 1, ///< Enable Wake on LAN 53 } ether_wake_on_lan_t; 54 55 /** Flow control functionality */ 56 typedef enum e_ether_flow_control 57 { 58 ETHER_FLOW_CONTROL_DISABLE = 0, ///< Disable flow control functionality 59 ETHER_FLOW_CONTROL_ENABLE = 1, ///< Enable flow control functionality with pause frames 60 } ether_flow_control_t; 61 62 /** Multicast Filter */ 63 typedef enum e_ether_multicast 64 { 65 ETHER_MULTICAST_DISABLE = 0, ///< Disable reception of multicast frames 66 ETHER_MULTICAST_ENABLE = 1, ///< Enable reception of multicast frames 67 } ether_multicast_t; 68 69 /** Promiscuous Mode */ 70 typedef enum e_ether_promiscuous 71 { 72 ETHER_PROMISCUOUS_DISABLE = 0, ///< Only receive packets with current MAC address, multicast, and broadcast 73 ETHER_PROMISCUOUS_ENABLE = 1, ///< Receive all packets 74 } ether_promiscuous_t; 75 76 /** Zero copy */ 77 typedef enum e_ether_zerocopy 78 { 79 ETHER_ZEROCOPY_DISABLE = 0, ///< Disable zero copy in Read/Write function 80 ETHER_ZEROCOPY_ENABLE = 1, ///< Enable zero copy in Read/Write function 81 } ether_zerocopy_t; 82 83 typedef enum e_ether_padding 84 { 85 ETHER_PADDING_DISABLE = 0, 86 ETHER_PADDING_1BYTE = 1, 87 ETHER_PADDING_2BYTE = 2, 88 ETHER_PADDING_3BYTE = 3, 89 } ether_padding_t; 90 91 #ifndef BSP_OVERRIDE_ETHER_EVENT_T 92 93 /** Event code of callback function */ 94 typedef enum e_ether_event 95 { 96 ETHER_EVENT_WAKEON_LAN, ///< Magic packet detection event 97 ETHER_EVENT_LINK_ON, ///< Link up detection event 98 ETHER_EVENT_LINK_OFF, ///< Link down detection event 99 ETHER_EVENT_INTERRUPT, ///< Interrupt event 100 } ether_event_t; 101 #endif 102 103 #ifndef BSP_OVERRIDE_ETHER_CALLBACK_ARGS_T 104 105 /** Callback function parameter data */ 106 typedef struct st_ether_callback_args 107 { 108 uint32_t channel; ///< Device channel number 109 ether_event_t event; ///< Event code 110 uint32_t status_ecsr; ///< ETHERC status register for interrupt handler 111 uint32_t status_eesr; ///< ETHERC/EDMAC status register for interrupt handler 112 113 void const * p_context; ///< Placeholder for user data. Set in @ref ether_api_t::open function in @ref ether_cfg_t. 114 } ether_callback_args_t; 115 #endif 116 117 /** Control block. Allocate an instance specific control block to pass into the API calls. 118 */ 119 typedef void ether_ctrl_t; 120 121 /** Configuration parameters. */ 122 typedef struct st_ether_cfg 123 { 124 uint8_t channel; ///< Channel 125 ether_zerocopy_t zerocopy; ///< Zero copy enable or disable in Read/Write function 126 ether_multicast_t multicast; ///< Multicast enable or disable 127 ether_promiscuous_t promiscuous; ///< Promiscuous mode enable or disable 128 ether_flow_control_t flow_control; ///< Flow control functionally enable or disable 129 ether_padding_t padding; ///< Padding length inserted into the received Ethernet frame. 130 uint32_t padding_offset; ///< Offset of the padding inserted into the received Ethernet frame. 131 uint32_t broadcast_filter; ///< Limit of the number of broadcast frames received continuously 132 uint8_t * p_mac_address; ///< Pointer of MAC address 133 134 uint8_t num_tx_descriptors; ///< Number of transmission descriptor 135 uint8_t num_rx_descriptors; ///< Number of receive descriptor 136 137 uint8_t ** pp_ether_buffers; ///< Transmit and receive buffer 138 139 uint32_t ether_buffer_size; ///< Size of transmit and receive buffer 140 141 IRQn_Type irq; ///< Interrupt number 142 uint32_t interrupt_priority; ///< Interrupt priority 143 144 void (* p_callback)(ether_callback_args_t * p_args); ///< Callback provided when an ISR occurs. 145 146 ether_phy_instance_t const * p_ether_phy_instance; ///< Pointer to ETHER_PHY instance 147 148 /** Placeholder for user data. Passed to the user callback in ether_callback_args_t. */ 149 void const * p_context; ///< Placeholder for user data. 150 void const * p_extend; ///< Placeholder for user extension. 151 } ether_cfg_t; 152 153 /** Functions implemented at the HAL layer will follow this API. */ 154 typedef struct st_ether_api 155 { 156 /** Open driver. 157 * 158 * @param[in] p_ctrl Pointer to control structure. 159 * @param[in] p_cfg Pointer to pin configuration structure. 160 */ 161 fsp_err_t (* open)(ether_ctrl_t * const p_ctrl, ether_cfg_t const * const p_cfg); 162 163 /** Close driver. 164 * 165 * @param[in] p_ctrl Pointer to control structure. 166 */ 167 fsp_err_t (* close)(ether_ctrl_t * const p_ctrl); 168 169 /** Read packet if data is available. 170 * 171 * @param[in] p_ctrl Pointer to control structure. 172 * @param[in] p_buffer Pointer to where to store read data. 173 * @param[in] length_bytes Number of bytes in buffer 174 */ 175 fsp_err_t (* read)(ether_ctrl_t * const p_ctrl, void * const p_buffer, uint32_t * const length_bytes); 176 177 /** Release rx buffer from buffer pool process in zero-copy read operation. 178 * 179 * @param[in] p_ctrl Pointer to control structure. 180 */ 181 fsp_err_t (* bufferRelease)(ether_ctrl_t * const p_ctrl); 182 183 /** Update the buffer pointer in the current receive descriptor. 184 * 185 * @param[in] p_ctrl Pointer to control structure. 186 * @param[in] p_buffer New address to write into the rx buffer descriptor. 187 */ 188 fsp_err_t (* rxBufferUpdate)(ether_ctrl_t * const p_ctrl, void * const p_buffer); 189 190 /** Write packet. 191 * 192 * @param[in] p_ctrl Pointer to control structure. 193 * @param[in] p_buffer Pointer to data to write. 194 * @param[in] frame_length Send ethernet frame size (without 4 bytes of CRC data size). 195 */ 196 fsp_err_t (* write)(ether_ctrl_t * const p_ctrl, void * const p_buffer, uint32_t const frame_length); 197 198 /** Process link. 199 * 200 * @param[in] p_ctrl Pointer to control structure. 201 */ 202 fsp_err_t (* linkProcess)(ether_ctrl_t * const p_ctrl); 203 204 /** Enable magic packet detection. 205 * 206 * @param[in] p_ctrl Pointer to control structure. 207 */ 208 fsp_err_t (* wakeOnLANEnable)(ether_ctrl_t * const p_ctrl); 209 210 /** Get the address of the most recently sent buffer. 211 * 212 * @param[in] p_ctrl Pointer to control structure. 213 * @param[out] p_buffer_address Pointer to the address of the most recently sent buffer. 214 */ 215 fsp_err_t (* txStatusGet)(ether_ctrl_t * const p_ctrl, void * const p_buffer_address); 216 217 /** 218 * Specify callback function and optional context pointer and working memory pointer. 219 * 220 * @param[in] p_ctrl Pointer to the ETHER control block. 221 * @param[in] p_callback Callback function 222 * @param[in] p_context Pointer to send to callback function 223 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 224 * Callback arguments allocated here are only valid during the callback. 225 */ 226 fsp_err_t (* callbackSet)(ether_ctrl_t * const p_ctrl, void (* p_callback)(ether_callback_args_t *), 227 void const * const p_context, ether_callback_args_t * const p_callback_memory); 228 } ether_api_t; 229 230 /** This structure encompasses everything that is needed to use an instance of this interface. */ 231 typedef struct st_ether_instance 232 { 233 ether_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 234 ether_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 235 ether_api_t const * p_api; ///< Pointer to the API structure for this instance 236 } ether_instance_t; 237 238 /*******************************************************************************************************************//** 239 * @} (end defgroup ETHER_API) 240 **********************************************************************************************************************/ 241 242 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 243 FSP_FOOTER 244 245 #endif /* R_ETHERNET_API_H */ 246
