2 * Copyright (C) 2016 CSI Project. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
26 typedef void *eth_mac_handle_t;
28 #define MAX_FRAMELEN 1518 /* (note: maximum ethernet frame length would be 1518) */
30 #define CSI_ETH_MAC_API_VERSION CSI_DRIVER_VERSION_MAJOR_MINOR(2,1) /* API version */
32 #define _CSI_Driver_ETH_MAC_(n) Driver_ETH_MAC##n
33 #define CSI_Driver_ETH_MAC_(n) _CSI_Driver_ETH_MAC_(n)
35 /****** Ethernet MAC Control Codes *****/
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)
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)
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
65 /*----- Ethernet MAC VLAN Filter Flag -----*/
66 #define CSI_ETH_MAC_VLAN_FILTER_ID_ONLY (1UL << 16) ///< Compare only the VLAN Identifier (12-bit)
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
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
85 \brief Ethernet MAC Time
87 typedef struct eth_mac_time {
88 uint32_t ns; ///< Nano seconds
89 uint32_t sec; ///< Seconds
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
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.
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;
109 \brief Ethernet MAC Capabilities
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;
133 \brief Ethernet Frame filter
135 typedef struct eth_frame_filter {
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
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;
152 * Structure describing a frame filter list item
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;
165 struct eth_frame_filter_list
167 struct eth_frame_filter_list* next;
169 typedef struct eth_frame_filter_list eth_frame_filter_list_t;
173 eth_event_cb_t cb_event;
174 eth_capabilities_t capabilities;
178 \brief Get driver version.
179 \param[in] handle ethernet handle
180 \return ethernet version including chip version and driver version
182 csi_drv_version_t csi_eth_mac_get_version(eth_mac_handle_t handle);
185 \brief Get driver capabilities.
186 \param[in] handle ethernet handle
187 \return ethernet capabilities
189 eth_capabilities_t csi_eth_mac_get_capabilities(eth_mac_handle_t handle);
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
196 eth_mac_handle_t csi_eth_mac_initialize(eth_event_cb_t cb);
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
203 int32_t csi_eth_mac_uninitialize(eth_mac_handle_t handle);
206 \brief Control Ethernet MAC Device Power.
207 \param[in] handle ethernet handle
208 \param[in] state Power state
211 int32_t csi_eth_mac_power_control(eth_mac_handle_t handle, eth_power_state_t state);
214 \brief Get Ethernet MAC Address.
215 \param[in] handle ethernet handle
216 \param[in] mac Pointer to address
219 int32_t csi_eth_mac_get_macaddr(eth_mac_handle_t handle, eth_mac_addr_t *mac);
222 \brief Set Ethernet MAC Address.
223 \param[in] handle ethernet handle
224 \param[in] mac Pointer to address
227 int32_t csi_eth_mac_set_macaddr(eth_mac_handle_t handle, const eth_mac_addr_t *mac);
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
236 int32_t csi_eth_mac_set_addrfilter(eth_mac_handle_t handle, const eth_mac_addr_t *addr, uint32_t num_addr);
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_...)
246 int32_t csi_eth_mac_send_frame(eth_mac_handle_t handle, const uint8_t *frame, uint32_t len, uint32_t flags);
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
257 int32_t csi_eth_mac_read_frame(eth_mac_handle_t handle, uint8_t *frame, uint32_t len);
260 \brief Get size of received Ethernet frame.
261 \param[in] handle ethernet handle
262 \return number of bytes in received frame
264 int32_t csi_eth_mac_get_rx_framesize(eth_mac_handle_t handle);
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
272 int32_t csi_eth_mac_get_rx_frametime(eth_mac_handle_t handle, eth_mac_time_t *time);
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
280 int32_t csi_eth_mac_get_tx_frametime(eth_mac_handle_t handle, eth_mac_time_t *time);
283 \brief Control Ethernet Interface.
284 \param[in] handle ethernet handle
285 \param[in] control Operation
286 \param[in] arg Argument of operation (optional)
289 int32_t csi_eth_mac_control(eth_mac_handle_t handle, uint32_t control, uint32_t arg);
292 \brief Control Precision Timer.
293 \param[in] handle ethernet handle
294 \param[in] control Operation
295 \param[in] time Pointer to time structure
298 int32_t csi_eth_mac_control_time(eth_mac_handle_t handle, uint32_t control, eth_mac_time_t *time);
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
308 int32_t csi_eth_mac_phy_read(eth_mac_handle_t handle, uint8_t phy_addr, uint8_t reg_addr, uint16_t *data);
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
318 int32_t csi_eth_mac_phy_write(eth_mac_handle_t handle, uint8_t phy_addr, uint8_t reg_addr, uint16_t data);
321 \brief Callback function that signals a Ethernet Event.
322 \param[in] handle ethernet handle
323 \param[in] event event notification mask
326 void csi_eth_mac_signal_event(eth_mac_handle_t handle, uint32_t event);
329 \brief Add Frame Filter Setting with Filter ID.
330 \param[in] handle ethernet handle
331 \param[in] filter Pointer to filter setting
334 int32_t csi_eth_mac_add_framefilter(eth_mac_handle_t handle, const eth_frame_filter_t *filter);
337 \brief Remove Frame Filter Setting.
338 \param[in] handle ethernet handle
339 \param[in] filter_id Frame Filter ID
342 int32_t csi_eth_mac_remove_framefilter(eth_mac_handle_t handle, uint32_t filter_id);
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
351 int32_t csi_eth_mac_en_framefilter(eth_mac_handle_t handle, uint32_t filter_id, bool en);
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
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);
364 #ifdef CONFIG_ETH_ENC28J60_USE_PBUF
366 \brief Begin to Send Ethernet frame.
367 \param[in] handle ethernet handle
368 \param[in] len Frame buffer length in bytes
371 int32_t csi_eth_mac_ex_send_frame_begin(eth_mac_handle_t handle, uint32_t len);
375 * @param address the packet data length
380 int32_t csi_eth_mac_ex_send_frame(eth_mac_handle_t handle, const uint8_t *frame, uint32_t len, uint32_t flags);
383 \brief End Send Ethernet frame.
384 \param[in] handle ethernet handle
387 int32_t csi_eth_mac_ex_send_frame_end(eth_mac_handle_t handle);
390 \brief Read data of received Ethernet frame.
391 \param[in] handle ethernet handle
392 \param[in] frame Pointer to frame buffer for data to read into
393 \param[in] len Frame buffer length in bytes
394 \return number of data bytes read or execution status
395 - value >= 0: number of data bytes read
396 - value < 0: error occurred, value is execution status as defined with execution_status
398 int32_t csi_eth_mac_ex_read_frame(eth_mac_handle_t handle, uint8_t *frame, uint32_t len);
401 \brief Begin to Read data of received Ethernet frame.
402 \param[in] handle ethernet handle
403 \param[in] len Frame buffer length in bytes
404 \return >0 data byte in hardware buffer
408 int32_t csi_eth_mac_ex_read_frame_begin(eth_mac_handle_t handle);
411 \brief Begin to Read data of received Ethernet frame.
412 \param[in] handle ethernet handle
415 int32_t csi_eth_mac_ex_read_frame_end(eth_mac_handle_t handle);