git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/T-HEAD_CB2201_CDK/csi/csi_driver/include/drv_eth_mac.h

   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
 364 #ifdef CONFIG_ETH_ENC28J60_USE_PBUF
 365 /**
 366   \brief       Begin to Send Ethernet frame.
 367   \param[in]   handle  ethernet handle
 368   \param[in]   len    Frame buffer length in bytes
 369   \return      error code
 370 */
 371 int32_t csi_eth_mac_ex_send_frame_begin(eth_mac_handle_t handle, uint32_t len);
 372
 373 /**
 374  *   send a packet data
 375  * @param address the packet data length
 376  *
 377  * @return
 378  *        - sent data length
 379  */
 380 int32_t csi_eth_mac_ex_send_frame(eth_mac_handle_t handle, const uint8_t *frame, uint32_t len, uint32_t flags);
 381
 382 /**
 383   \brief       End Send Ethernet frame.
 384   \param[in]   handle  ethernet handle
 385   \return      error code
 386 */
 387 int32_t csi_eth_mac_ex_send_frame_end(eth_mac_handle_t handle);
 388
 389 /**
 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
 397 */
 398 int32_t csi_eth_mac_ex_read_frame(eth_mac_handle_t handle, uint8_t *frame, uint32_t len);
 399
 400 /**
 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
 405                ==0 no data
 406                < 0 error
 407 */
 408 int32_t csi_eth_mac_ex_read_frame_begin(eth_mac_handle_t handle);
 409
 410 /**
 411   \brief       Begin to Read data of received Ethernet frame.
 412   \param[in]   handle  ethernet handle
 413   \return      error code
 414 */
 415 int32_t csi_eth_mac_ex_read_frame_end(eth_mac_handle_t handle);
 416 #endif
 417
 418 #ifdef __cplusplus
 419 }
 420 #endif
 421
 422 #endif