1 /** 2 * Copyright (C) 2016 CSI Project. All rights reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef _CSI_ETH_H_ 18 #define _CSI_ETH_H_ 19 20 #include <stdbool.h> 21 #include "drv/eth.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 typedef void *eth_mac_handle_t; 28 29 #define MAX_FRAMELEN 1518 /* (note: maximum ethernet frame length would be 1518) */ 30 31 #define CSI_ETH_MAC_API_VERSION CSI_DRIVER_VERSION_MAJOR_MINOR(2,1) /* API version */ 32 33 #define _CSI_Driver_ETH_MAC_(n) Driver_ETH_MAC##n 34 #define CSI_Driver_ETH_MAC_(n) _CSI_Driver_ETH_MAC_(n) 35 36 /****** Ethernet MAC Control Codes *****/ 37 38 #define CSI_ETH_MAC_CONFIGURE (0x01) ///< Configure MAC; arg = configuration 39 #define CSI_ETH_MAC_CONTROL_TX (0x02) ///< Transmitter; arg: 0=disabled (default), 1=enabled 40 #define CSI_ETH_MAC_CONTROL_RX (0x03) ///< Receiver; arg: 0=disabled (default), 1=enabled 41 #define CSI_ETH_MAC_FLUSH (0x04) ///< Flush buffer; arg = CSI_ETH_MAC_FLUSH_... 42 #define CSI_ETH_MAC_SLEEP (0x05) ///< Sleep mode; arg: 1=enter and wait for Magic packet, 0=exit 43 #define CSI_ETH_MAC_VLAN_FILTER (0x06) ///< VLAN Filter for received frames; arg15..0: VLAN Tag; arg16: optional CSI_ETH_MAC_VLAN_FILTER_ID_ONLY; 0=disabled (default) 44 #define DRV_ETH_MAC_ADJUST_LINK (0x07) ///< Adjust MAC link state according to phy state; arg: phy handle 45 #define DRV_ETH_MAC_CONTROL_IRQ (0x08) ///< Interrupt request; arg: 0=disable, 1=enable 46 47 /*----- Ethernet MAC Configuration -----*/ 48 #define CSI_ETH_MAC_SPEED_Pos 0 49 #define CSI_ETH_MAC_SPEED_Msk (3UL << CSI_ETH_MAC_SPEED_Pos) 50 #define CSI_ETH_MAC_SPEED_10M (CSI_ETH_SPEED_10M << CSI_ETH_MAC_SPEED_Pos) ///< 10 Mbps link speed 51 #define CSI_ETH_MAC_SPEED_100M (CSI_ETH_SPEED_100M << CSI_ETH_MAC_SPEED_Pos) ///< 100 Mbps link speed 52 #define CSI_ETH_MAC_SPEED_1G (CSI_ETH_SPEED_1G << CSI_ETH_MAC_SPEED_Pos) ///< 1 Gpbs link speed 53 #define CSI_ETH_MAC_DUPLEX_Pos 2 54 #define CSI_ETH_MAC_DUPLEX_Msk (1UL << CSI_ETH_MAC_DUPLEX_Pos) 55 #define CSI_ETH_MAC_DUPLEX_HALF (CSI_ETH_DUPLEX_HALF << CSI_ETH_MAC_DUPLEX_Pos) ///< Half duplex link 56 #define CSI_ETH_MAC_DUPLEX_FULL (CSI_ETH_DUPLEX_FULL << CSI_ETH_MAC_DUPLEX_Pos) ///< Full duplex link 57 #define CSI_ETH_MAC_LOOPBACK (1UL << 4) ///< Loop-back test mode 58 #define CSI_ETH_MAC_CHECKSUM_OFFLOAD_RX (1UL << 5) ///< Receiver Checksum offload 59 #define CSI_ETH_MAC_CHECKSUM_OFFLOAD_TX (1UL << 6) ///< Transmitter Checksum offload 60 #define CSI_ETH_MAC_ADDRESS_BROADCAST (1UL << 7) ///< Accept frames with Broadcast address 61 #define CSI_ETH_MAC_ADDRESS_MULTICAST (1UL << 8) ///< Accept frames with any Multicast address 62 #define CSI_ETH_MAC_ADDRESS_ALL (1UL << 9) ///< Accept frames with any address (Promiscuous Mode) 63 64 /*----- Ethernet MAC Flush Flags -----*/ 65 #define CSI_ETH_MAC_FLUSH_RX (1UL << 0) ///< Flush Receive buffer 66 #define CSI_ETH_MAC_FLUSH_TX (1UL << 1) ///< Flush Transmit buffer 67 68 /*----- Ethernet MAC VLAN Filter Flag -----*/ 69 #define CSI_ETH_MAC_VLAN_FILTER_ID_ONLY (1UL << 16) ///< Compare only the VLAN Identifier (12-bit) 70 71 72 /****** Ethernet MAC Frame Transmit Flags *****/ 73 #define CSI_ETH_MAC_TX_FRAME_FRAGMENT (1UL << 0) ///< Indicate frame fragment 74 #define CSI_ETH_MAC_TX_FRAME_EVENT (1UL << 1) ///< Generate event when frame is transmitted 75 #define CSI_ETH_MAC_TX_FRAME_TIMESTAMP (1UL << 2) ///< Capture frame time stamp 76 77 78 /****** Ethernet MAC Timer Control Codes *****/ 79 #define CSI_ETH_MAC_TIMER_GET_TIME (0x01) ///< Get current time 80 #define CSI_ETH_MAC_TIMER_SET_TIME (0x02) ///< Set new time 81 #define CSI_ETH_MAC_TIMER_INC_TIME (0x03) ///< Increment current time 82 #define CSI_ETH_MAC_TIMER_DEC_TIME (0x04) ///< Decrement current time 83 #define CSI_ETH_MAC_TIMER_SET_ALCSI (0x05) ///< Set alarm time 84 #define CSI_ETH_MAC_TIMER_ADJUST_CLOCK (0x06) ///< Adjust clock frequency; time->ns: correction factor * 2^31 85 86 87 /** 88 \brief Ethernet MAC Time 89 */ 90 typedef struct eth_mac_time { 91 uint32_t ns; ///< Nano seconds 92 uint32_t sec; ///< Seconds 93 } eth_mac_time_t; 94 95 96 /****** Ethernet MAC Event *****/ 97 #define CSI_ETH_MAC_EVENT_RX_FRAME (1UL << 0) ///< Frame Received 98 #define CSI_ETH_MAC_EVENT_TX_FRAME (1UL << 1) ///< Frame Transmitted 99 #define CSI_ETH_MAC_EVENT_WAKEUP (1UL << 2) ///< Wake-up (on Magic Packet) 100 #define CSI_ETH_MAC_EVENT_TIMER_ALCSI (1UL << 3) ///< Timer Alarm 101 #define CSI_ETH_MAC_EVENT_LINK_CHANGE (1UL << 4) ///< Link state 102 103 typedef void (*eth_event_cb_t)(int32_t idx, uint32_t event); ///< Pointer to \ref eth_event_cb_t : Signal Ethernet Event. 104 105 typedef enum { 106 FRAME_FILTER_RULE_POSITIVE_MATCHING = 0, /*!< Specifies that a filter should match a given pattern */ 107 FRAME_FILTER_RULE_NEGATIVE_MATCHING = 1, /*!< Specifies that a filter should NOT match a given pattern */ 108 } frame_filter_rule_t; 109 110 /** 111 \brief Ethernet MAC Capabilities 112 */ 113 typedef struct eth_capabilities { 114 uint32_t checksum_offload_rx_ip4 : 1; ///< 1 = IPv4 header checksum verified on receive 115 uint32_t checksum_offload_rx_ip6 : 1; ///< 1 = IPv6 checksum verification supported on receive 116 uint32_t checksum_offload_rx_udp : 1; ///< 1 = UDP payload checksum verified on receive 117 uint32_t checksum_offload_rx_tcp : 1; ///< 1 = TCP payload checksum verified on receive 118 uint32_t checksum_offload_rx_icmp : 1; ///< 1 = ICMP payload checksum verified on receive 119 uint32_t checksum_offload_tx_ip4 : 1; ///< 1 = IPv4 header checksum generated on transmit 120 uint32_t checksum_offload_tx_ip6 : 1; ///< 1 = IPv6 checksum generation supported on transmit 121 uint32_t checksum_offload_tx_udp : 1; ///< 1 = UDP payload checksum generated on transmit 122 uint32_t checksum_offload_tx_tcp : 1; ///< 1 = TCP payload checksum generated on transmit 123 uint32_t checksum_offload_tx_icmp : 1; ///< 1 = ICMP payload checksum generated on transmit 124 uint32_t media_interface : 2; ///< Ethernet Media Interface type 125 uint32_t mac_address : 1; ///< 1 = driver provides initial valid MAC address 126 uint32_t event_rx_frame : 1; ///< 1 = callback event generated 127 uint32_t event_tx_frame : 1; ///< 1 = callback event generated 128 uint32_t event_wakeup : 1; ///< 1 = wakeup event generated 129 uint32_t precision_timer : 1; ///< 1 = Precision Timer supported 130 uint32_t reserved : 15; ///< Reserved (must be zero) 131 } eth_capabilities_t; 132 133 /** 134 * Structure describing a frame filter list item 135 */ 136 typedef struct { 137 uint32_t id; /*!< Unique identifier for a packet filter item */ 138 frame_filter_rule_t rule; /*!< Filter matches are either POSITIVE or NEGATIVE matching */ 139 uint16_t offset; /*!< Offset in bytes to start filtering (referenced to the start of the ethernet packet) */ 140 uint16_t mask_size; /*!< Size of the mask in bytes */ 141 uint8_t *mask; /*!< Pattern mask bytes to be ANDed with the pattern eg. "\xff00" (must be in network byte order) */ 142 uint8_t *pattern; /*!< Pattern bytes used to filter eg. "\x0800" (must be in network byte order) */ 143 bool enabled_status; /*!< When returned from mhd_get_packet_filters, indicates if the filter is enabled */ 144 } eth_frame_filter_t; 145 146 struct eth_frame_filter_list { 147 struct eth_frame_filter_list *next; 148 }; 149 150 typedef struct eth_frame_filter_list eth_frame_filter_list_t; 151 152 typedef struct { 153 eth_event_cb_t cb_event; 154 eth_capabilities_t capabilities; 155 } eth_mac_priv_t; 156 157 /** 158 \brief Get driver version. 159 \param[in] handle ethernet handle 160 \return ethernet version including chip version and driver version 161 */ 162 csi_drv_version_t csi_eth_mac_get_version(eth_mac_handle_t handle); 163 164 /** 165 \brief Get driver capabilities. 166 \param[in] idx device id 167 \return ethernet capabilities 168 */ 169 eth_capabilities_t csi_eth_mac_get_capabilities(int32_t idx); 170 171 /** 172 \brief This function is used to initialize Ethernet device and related resource, an event callback is registered. It is called when the middleware component like TCPIP starts operation. 173 \param[in] idx device id 174 \param[in] cb callback to handle ethernet event 175 \return return ethernet handle if success 176 */ 177 eth_mac_handle_t csi_eth_mac_initialize(int32_t idx, eth_event_cb_t cb_event); 178 179 /** 180 \brief This function is used to de-initialize Ethernet device. It is called when the middleware component stops operation and releases the software resources used by the interface. 181 \param[in] handle ethernet handle 182 \return error code 183 */ 184 int32_t csi_eth_mac_uninitialize(eth_mac_handle_t handle); 185 186 /** 187 \brief Control Ethernet MAC Device Power. 188 \param[in] handle ethernet handle 189 \param[in] state Power state 190 \return error code 191 */ 192 int32_t csi_eth_mac_power_control(eth_mac_handle_t handle, eth_power_state_t state); 193 194 /** 195 \brief Get Ethernet MAC Address. 196 \param[in] handle ethernet handle 197 \param[in] mac Pointer to address 198 \return error code 199 */ 200 int32_t csi_eth_mac_get_macaddr(eth_mac_handle_t handle, eth_mac_addr_t *mac); 201 202 /** 203 \brief Set Ethernet MAC Address. 204 \param[in] handle ethernet handle 205 \param[in] mac Pointer to address 206 \return error code 207 */ 208 int32_t csi_eth_mac_set_macaddr(eth_mac_handle_t handle, const eth_mac_addr_t *mac); 209 210 /** 211 \brief Configure Address Filter. 212 \param[in] handle ethernet handle 213 \param[in] addr Pointer to addresses 214 \param[in] num_addr Number of addresses to configure 215 \return error code 216 */ 217 int32_t csi_eth_mac_set_addrfilter(eth_mac_handle_t handle, const eth_mac_addr_t *addr, uint32_t num_addr); 218 219 /** 220 \brief Send Ethernet frame. 221 \param[in] handle ethernet handle 222 \param[in] frame Pointer to frame buffer with data to send 223 \param[in] len Frame buffer length in bytes 224 \param[in] flags Frame transmit flags (see CSI_ETH_MAC_TX_FRAME_...) 225 \return error code 226 */ 227 int32_t csi_eth_mac_send_frame(eth_mac_handle_t handle, const uint8_t *frame, uint32_t len, uint32_t flags); 228 229 /** 230 \brief Read data of received Ethernet frame. 231 \param[in] handle ethernet handle 232 \param[in] frame Pointer to frame buffer for data to read into 233 \param[in] len Frame buffer length in bytes 234 \return number of data bytes read or execution status 235 - value >= 0: number of data bytes read 236 - value < 0: error occurred, value is execution status as defined with execution_status 237 */ 238 int32_t csi_eth_mac_read_frame(eth_mac_handle_t handle, uint8_t *frame, uint32_t len); 239 240 /** 241 \brief Request data of received Ethernet frame. 242 drv_eth_mac_request_frame() and drv_eth_mac_release_frame() 243 must be called in pairs. 244 \param[in] handle ethernet handle 245 \param[in] frame Pointer to frame buffer pointer 246 \return number of data bytes read or execution status 247 - value >= 0: number of data bytes read 248 - value < 0: error occurred 249 */ 250 int32_t drv_eth_mac_request_frame(eth_mac_handle_t handle, uint8_t **frame); 251 252 /** 253 \brief Release current Ethernet frame. 254 drv_eth_mac_request_frame() and drv_eth_mac_release_frame() 255 must be called in pairs. 256 \param[in] handle ethernet handle 257 \return error code 258 */ 259 int32_t drv_eth_mac_release_frame(eth_mac_handle_t handle); 260 261 /** 262 \brief Get size of received Ethernet frame. 263 \param[in] handle ethernet handle 264 \return number of bytes in received frame 265 */ 266 int32_t csi_eth_mac_get_rx_framesize(eth_mac_handle_t handle); 267 268 /** 269 \brief Get time of received Ethernet frame. 270 \param[in] handle ethernet handle 271 \param[in] time Pointer to time structure for data to read into 272 \return error code 273 */ 274 int32_t csi_eth_mac_get_rx_frametime(eth_mac_handle_t handle, eth_mac_time_t *time); 275 276 /** 277 \brief Get time of transmitted Ethernet frame. 278 \param[in] handle ethernet handle 279 \param[in] time Pointer to time structure for data to read into 280 \return error code 281 */ 282 int32_t csi_eth_mac_get_tx_frametime(eth_mac_handle_t handle, eth_mac_time_t *time); 283 284 /** 285 \brief Control Ethernet Interface. 286 \param[in] handle ethernet handle 287 \param[in] control Operation 288 \param[in] arg Argument of operation (optional) 289 \return error code 290 */ 291 int32_t csi_eth_mac_control(eth_mac_handle_t handle, uint32_t control, uint32_t arg); 292 293 /** 294 \brief Control Precision Timer. 295 \param[in] handle ethernet handle 296 \param[in] control Operation 297 \param[in] time Pointer to time structure 298 \return error code 299 */ 300 int32_t csi_eth_mac_control_time(eth_mac_handle_t handle, uint32_t control, eth_mac_time_t *time); 301 302 /** 303 \brief Read Ethernet PHY Register through Management Interface. 304 \param[in] handle ethernet handle 305 \param[in] phy_addr 5-bit device address 306 \param[in] reg_addr 5-bit register address 307 \param[out] data Pointer where the result is written to 308 \return error code 309 */ 310 int32_t csi_eth_mac_phy_read(eth_mac_handle_t handle, uint8_t phy_addr, uint8_t reg_addr, uint16_t *data); 311 312 /** 313 \brief Write Ethernet PHY Register through Management Interface. 314 \param[in] handle ethernet handle 315 \param[in] phy_addr 5-bit device address 316 \param[in] reg_addr 5-bit register address 317 \param[in] data 16-bit data to write 318 \return error code 319 */ 320 int32_t csi_eth_mac_phy_write(eth_mac_handle_t handle, uint8_t phy_addr, uint8_t reg_addr, uint16_t data); 321 322 /** 323 \brief Callback function that signals a Ethernet Event. 324 \param[in] handle ethernet handle 325 \param[in] event event notification mask 326 \return none 327 */ 328 void csi_eth_mac_signal_event(eth_mac_handle_t handle, uint32_t event); 329 330 /** 331 \brief Add Frame Filter Setting with Filter ID. 332 \param[in] handle ethernet handle 333 \param[in] filter Pointer to filter setting 334 \return error code 335 */ 336 int32_t csi_eth_mac_add_framefilter(eth_mac_handle_t handle, const eth_frame_filter_t *filter); 337 338 /** 339 \brief Remove Frame Filter Setting. 340 \param[in] handle ethernet handle 341 \param[in] filter_id Frame Filter ID 342 \return error code 343 */ 344 int32_t csi_eth_mac_remove_framefilter(eth_mac_handle_t handle, uint32_t filter_id); 345 346 /** 347 \brief Enable/Disable Specified Frame Filter ID. 348 \param[in] handle ethernet handle 349 \param[in] filter_id Frame Filter ID 350 \param[in] en Enable or disable 351 \return error code 352 */ 353 int32_t csi_eth_mac_en_framefilter(eth_mac_handle_t handle, uint32_t filter_id, bool en); 354 355 /** 356 \brief Get frame filter table list. 357 \param[in] handle ethernet handle 358 \param[in] list frame filter table list 359 \param[in] count_out the count of filter setting added 360 \param[in] max_count max filter setting can be supported 361 \return error code 362 */ 363 int32_t csi_eth_mac_get_framefilter(eth_mac_handle_t handle, eth_frame_filter_list_t *list, uint32_t *count_out, uint32_t max_count); 364 365 #ifdef __cplusplus 366 } 367 #endif 368 369 #endif 370