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