begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_ETH_MAC.h

   1 /*\r
   2  * Copyright (c) 2013-2016 ARM Limited. All rights reserved.\r
   3  *\r
   4  * SPDX-License-Identifier: Apache-2.0\r
   5  *\r
   6  * Licensed under the Apache License, Version 2.0 (the License); you may\r
   7  * not use this file except in compliance with the License.\r
   8  * You may obtain a copy of the License at\r
   9  *\r
  10  * http://www.apache.org/licenses/LICENSE-2.0\r
  11  *\r
  12  * Unless required by applicable law or agreed to in writing, software\r
  13  * distributed under the License is distributed on an AS IS BASIS, WITHOUT\r
  14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  15  * See the License for the specific language governing permissions and\r
  16  * limitations under the License.\r
  17  *\r
  18  * $Date:        30. May 2014\r
  19  * $Revision:    V2.01\r
  20  *\r
  21  * Project:      Ethernet MAC (Media Access Control) Driver definitions\r
  22  */\r
  23 \r
  24 /* History:\r
  25  *  Version 2.01\r
  26  *    Added ARM_ETH_MAC_SLEEP Control\r
  27  *  Version 2.00\r
  28  *    Changed MAC Address handling:\r
  29  *      moved from ARM_ETH_MAC_Initialize\r
  30  *      to new functions ARM_ETH_MAC_GetMacAddress and ARM_ETH_MAC_SetMacAddress\r
  31  *    Replaced ARM_ETH_MAC_SetMulticastAddr function with ARM_ETH_MAC_SetAddressFilter\r
  32  *    Extended ARM_ETH_MAC_SendFrame function with flags\r
  33  *    Added ARM_ETH_MAC_Control function:\r
  34  *      more control options (Broadcast, Multicast, Checksum offload, VLAN, ...)\r
  35  *      replaces ARM_ETH_MAC_SetMode\r
  36  *      replaces ARM_ETH_MAC_EnableTx, ARM_ETH_MAC_EnableRx\r
  37  *    Added optional event on transmitted frame\r
  38  *    Added support for PTP (Precision Time Protocol) through new functions:\r
  39  *       ARM_ETH_MAC_ControlTimer\r
  40  *       ARM_ETH_MAC_GetRxFrameTime\r
  41  *       ARM_ETH_MAC_GetTxFrameTime\r
  42  *    Changed prefix ARM_DRV -> ARM_DRIVER\r
  43  *    Changed return values of some functions to int32_t\r
  44  *  Version 1.10\r
  45  *    Name space prefix ARM_ added\r
  46  *  Version 1.01\r
  47  *    Renamed capabilities items for checksum offload\r
  48  *  Version 1.00\r
  49  *    Initial release\r
  50  */\r
  51 \r
  52 #ifndef __DRIVER_ETH_MAC_H\r
  53 #define __DRIVER_ETH_MAC_H\r
  54 \r
  55 #include "Driver_ETH.h"\r
  56 \r
  57 #define ARM_ETH_MAC_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,01)  /* API version */\r
  58 \r
  59 \r
  60 #define _ARM_Driver_ETH_MAC_(n)      Driver_ETH_MAC##n\r
  61 #define  ARM_Driver_ETH_MAC_(n) _ARM_Driver_ETH_MAC_(n)\r
  62 \r
  63 \r
  64 /****** Ethernet MAC Control Codes *****/\r
  65 \r
  66 #define ARM_ETH_MAC_CONFIGURE           (0x01)      ///< Configure MAC; arg = configuration\r
  67 #define ARM_ETH_MAC_CONTROL_TX          (0x02)      ///< Transmitter; arg: 0=disabled (default), 1=enabled\r
  68 #define ARM_ETH_MAC_CONTROL_RX          (0x03)      ///< Receiver; arg: 0=disabled (default), 1=enabled\r
  69 #define ARM_ETH_MAC_FLUSH               (0x04)      ///< Flush buffer; arg = ARM_ETH_MAC_FLUSH_...\r
  70 #define ARM_ETH_MAC_SLEEP               (0x05)      ///< Sleep mode; arg: 1=enter and wait for Magic packet, 0=exit\r
  71 #define ARM_ETH_MAC_VLAN_FILTER         (0x06)      ///< VLAN Filter for received frames; arg15..0: VLAN Tag; arg16: optional ARM_ETH_MAC_VLAN_FILTER_ID_ONLY; 0=disabled (default)\r
  72 \r
  73 /*----- Ethernet MAC Configuration -----*/\r
  74 #define ARM_ETH_MAC_SPEED_Pos            0\r
  75 #define ARM_ETH_MAC_SPEED_Msk           (3UL                 << ARM_ETH_MAC_SPEED_Pos)\r
  76 #define ARM_ETH_MAC_SPEED_10M           (ARM_ETH_SPEED_10M   << ARM_ETH_MAC_SPEED_Pos)  ///< 10 Mbps link speed\r
  77 #define ARM_ETH_MAC_SPEED_100M          (ARM_ETH_SPEED_100M  << ARM_ETH_MAC_SPEED_Pos)  ///< 100 Mbps link speed\r
  78 #define ARM_ETH_MAC_SPEED_1G            (ARM_ETH_SPEED_1G    << ARM_ETH_MAC_SPEED_Pos)  ///< 1 Gpbs link speed\r
  79 #define ARM_ETH_MAC_DUPLEX_Pos           2\r
  80 #define ARM_ETH_MAC_DUPLEX_Msk          (1UL                 << ARM_ETH_MAC_DUPLEX_Pos)\r
  81 #define ARM_ETH_MAC_DUPLEX_HALF         (ARM_ETH_DUPLEX_HALF << ARM_ETH_MAC_DUPLEX_Pos) ///< Half duplex link\r
  82 #define ARM_ETH_MAC_DUPLEX_FULL         (ARM_ETH_DUPLEX_FULL << ARM_ETH_MAC_DUPLEX_Pos) ///< Full duplex link\r
  83 #define ARM_ETH_MAC_LOOPBACK            (1UL << 4)  ///< Loop-back test mode\r
  84 #define ARM_ETH_MAC_CHECKSUM_OFFLOAD_RX (1UL << 5)  ///< Receiver Checksum offload\r
  85 #define ARM_ETH_MAC_CHECKSUM_OFFLOAD_TX (1UL << 6)  ///< Transmitter Checksum offload\r
  86 #define ARM_ETH_MAC_ADDRESS_BROADCAST   (1UL << 7)  ///< Accept frames with Broadcast address\r
  87 #define ARM_ETH_MAC_ADDRESS_MULTICAST   (1UL << 8)  ///< Accept frames with any Multicast address\r
  88 #define ARM_ETH_MAC_ADDRESS_ALL         (1UL << 9)  ///< Accept frames with any address (Promiscuous Mode)\r
  89 \r
  90 /*----- Ethernet MAC Flush Flags -----*/\r
  91 #define ARM_ETH_MAC_FLUSH_RX            (1UL << 0)  ///< Flush Receive buffer\r
  92 #define ARM_ETH_MAC_FLUSH_TX            (1UL << 1)  ///< Flush Transmit buffer\r
  93 \r
  94 /*----- Ethernet MAC VLAN Filter Flag -----*/\r
  95 #define ARM_ETH_MAC_VLAN_FILTER_ID_ONLY (1UL << 16) ///< Compare only the VLAN Identifier (12-bit)\r
  96 \r
  97 \r
  98 /****** Ethernet MAC Frame Transmit Flags *****/\r
  99 #define ARM_ETH_MAC_TX_FRAME_FRAGMENT   (1UL << 0)  ///< Indicate frame fragment\r
 100 #define ARM_ETH_MAC_TX_FRAME_EVENT      (1UL << 1)  ///< Generate event when frame is transmitted\r
 101 #define ARM_ETH_MAC_TX_FRAME_TIMESTAMP  (1UL << 2)  ///< Capture frame time stamp\r
 102 \r
 103 \r
 104 /****** Ethernet MAC Timer Control Codes *****/\r
 105 #define ARM_ETH_MAC_TIMER_GET_TIME      (0x01)      ///< Get current time\r
 106 #define ARM_ETH_MAC_TIMER_SET_TIME      (0x02)      ///< Set new time\r
 107 #define ARM_ETH_MAC_TIMER_INC_TIME      (0x03)      ///< Increment current time\r
 108 #define ARM_ETH_MAC_TIMER_DEC_TIME      (0x04)      ///< Decrement current time\r
 109 #define ARM_ETH_MAC_TIMER_SET_ALARM     (0x05)      ///< Set alarm time\r
 110 #define ARM_ETH_MAC_TIMER_ADJUST_CLOCK  (0x06)      ///< Adjust clock frequency; time->ns: correction factor * 2^31\r
 111 \r
 112 \r
 113 /**\r
 114 \brief Ethernet MAC Time\r
 115 */\r
 116 typedef struct _ARM_ETH_MAC_TIME {\r
 117   uint32_t ns;                          ///< Nano seconds\r
 118   uint32_t sec;                         ///< Seconds\r
 119 } ARM_ETH_MAC_TIME;\r
 120 \r
 121 \r
 122 /****** Ethernet MAC Event *****/\r
 123 #define ARM_ETH_MAC_EVENT_RX_FRAME      (1UL << 0)  ///< Frame Received\r
 124 #define ARM_ETH_MAC_EVENT_TX_FRAME      (1UL << 1)  ///< Frame Transmitted\r
 125 #define ARM_ETH_MAC_EVENT_WAKEUP        (1UL << 2)  ///< Wake-up (on Magic Packet)\r
 126 #define ARM_ETH_MAC_EVENT_TIMER_ALARM   (1UL << 3)  ///< Timer Alarm\r
 127 \r
 128 \r
 129 // Function documentation\r
 130 /**\r
 131   \fn          ARM_DRIVER_VERSION ARM_ETH_MAC_GetVersion (void)\r
 132   \brief       Get driver version.\r
 133   \return      \ref ARM_DRIVER_VERSION\r
 134 */\r
 135 /**\r
 136   \fn          ARM_ETH_MAC_CAPABILITIES ARM_ETH_MAC_GetCapabilities (void)\r
 137   \brief       Get driver capabilities.\r
 138   \return      \ref ARM_ETH_MAC_CAPABILITIES\r
 139 */\r
 140 /**\r
 141   \fn          int32_t ARM_ETH_MAC_Initialize (ARM_ETH_MAC_SignalEvent_t cb_event)\r
 142   \brief       Initialize Ethernet MAC Device.\r
 143   \param[in]   cb_event  Pointer to \ref ARM_ETH_MAC_SignalEvent\r
 144   \return      \ref execution_status\r
 145 */\r
 146 /**\r
 147   \fn          int32_t ARM_ETH_MAC_Uninitialize (void)\r
 148   \brief       De-initialize Ethernet MAC Device.\r
 149   \return      \ref execution_status\r
 150 */\r
 151 /**\r
 152   \fn          int32_t ARM_ETH_MAC_PowerControl (ARM_POWER_STATE state)\r
 153   \brief       Control Ethernet MAC Device Power.\r
 154   \param[in]   state  Power state\r
 155   \return      \ref execution_status\r
 156 */\r
 157 /**\r
 158   \fn          int32_t ARM_ETH_MAC_GetMacAddress (ARM_ETH_MAC_ADDR *ptr_addr)\r
 159   \brief       Get Ethernet MAC Address.\r
 160   \param[in]   ptr_addr  Pointer to address\r
 161   \return      \ref execution_status\r
 162 */\r
 163 /**\r
 164   \fn          int32_t ARM_ETH_MAC_SetMacAddress (const ARM_ETH_MAC_ADDR *ptr_addr)\r
 165   \brief       Set Ethernet MAC Address.\r
 166   \param[in]   ptr_addr  Pointer to address\r
 167   \return      \ref execution_status\r
 168 */\r
 169 /**\r
 170   \fn          int32_t ARM_ETH_MAC_SetAddressFilter (const ARM_ETH_MAC_ADDR *ptr_addr,\r
 171                                                            uint32_t          num_addr)\r
 172   \brief       Configure Address Filter.\r
 173   \param[in]   ptr_addr  Pointer to addresses\r
 174   \param[in]   num_addr  Number of addresses to configure\r
 175   \return      \ref execution_status\r
 176 */\r
 177 /**\r
 178   \fn          int32_t ARM_ETH_MAC_SendFrame (const uint8_t *frame, uint32_t len, uint32_t flags)\r
 179   \brief       Send Ethernet frame.\r
 180   \param[in]   frame  Pointer to frame buffer with data to send\r
 181   \param[in]   len    Frame buffer length in bytes\r
 182   \param[in]   flags  Frame transmit flags (see ARM_ETH_MAC_TX_FRAME_...)\r
 183   \return      \ref execution_status\r
 184 */\r
 185 /**\r
 186   \fn          int32_t ARM_ETH_MAC_ReadFrame (uint8_t *frame, uint32_t len)\r
 187   \brief       Read data of received Ethernet frame.\r
 188   \param[in]   frame  Pointer to frame buffer for data to read into\r
 189   \param[in]   len    Frame buffer length in bytes\r
 190   \return      number of data bytes read or execution status\r
 191                  - value >= 0: number of data bytes read\r
 192                  - value < 0: error occurred, value is execution status as defined with \ref execution_status \r
 193 */\r
 194 /**\r
 195   \fn          uint32_t ARM_ETH_MAC_GetRxFrameSize (void)\r
 196   \brief       Get size of received Ethernet frame.\r
 197   \return      number of bytes in received frame\r
 198 */\r
 199 /**\r
 200   \fn          int32_t ARM_ETH_MAC_GetRxFrameTime (ARM_ETH_MAC_TIME *time)\r
 201   \brief       Get time of received Ethernet frame.\r
 202   \param[in]   time  Pointer to time structure for data to read into\r
 203   \return      \ref execution_status\r
 204 */\r
 205 /**\r
 206   \fn          int32_t ARM_ETH_MAC_GetTxFrameTime (ARM_ETH_MAC_TIME *time)\r
 207   \brief       Get time of transmitted Ethernet frame.\r
 208   \param[in]   time  Pointer to time structure for data to read into\r
 209   \return      \ref execution_status\r
 210 */\r
 211 /**\r
 212   \fn          int32_t ARM_ETH_MAC_Control (uint32_t control, uint32_t arg)\r
 213   \brief       Control Ethernet Interface.\r
 214   \param[in]   control  Operation\r
 215   \param[in]   arg      Argument of operation (optional)\r
 216   \return      \ref execution_status\r
 217 */\r
 218 /**\r
 219   \fn          int32_t ARM_ETH_MAC_ControlTimer (uint32_t control, ARM_ETH_MAC_TIME *time)\r
 220   \brief       Control Precision Timer.\r
 221   \param[in]   control  Operation\r
 222   \param[in]   time     Pointer to time structure\r
 223   \return      \ref execution_status\r
 224 */\r
 225 /**\r
 226   \fn          int32_t ARM_ETH_MAC_PHY_Read (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)\r
 227   \brief       Read Ethernet PHY Register through Management Interface.\r
 228   \param[in]   phy_addr  5-bit device address\r
 229   \param[in]   reg_addr  5-bit register address\r
 230   \param[out]  data      Pointer where the result is written to\r
 231   \return      \ref execution_status\r
 232 */\r
 233 /**\r
 234   \fn          int32_t ARM_ETH_MAC_PHY_Write (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)\r
 235   \brief       Write Ethernet PHY Register through Management Interface.\r
 236   \param[in]   phy_addr  5-bit device address\r
 237   \param[in]   reg_addr  5-bit register address\r
 238   \param[in]   data      16-bit data to write\r
 239   \return      \ref execution_status\r
 240 */\r
 241 \r
 242 /**\r
 243   \fn          void ARM_ETH_MAC_SignalEvent (uint32_t event)\r
 244   \brief       Callback function that signals a Ethernet Event.\r
 245   \param[in]   event  event notification mask\r
 246   \return      none\r
 247 */\r
 248 \r
 249 typedef void (*ARM_ETH_MAC_SignalEvent_t) (uint32_t event);  ///< Pointer to \ref ARM_ETH_MAC_SignalEvent : Signal Ethernet Event.\r
 250 \r
 251 \r
 252 /**\r
 253 \brief Ethernet MAC Capabilities\r
 254 */\r
 255 typedef struct _ARM_ETH_MAC_CAPABILITIES {\r
 256   uint32_t checksum_offload_rx_ip4  : 1;        ///< 1 = IPv4 header checksum verified on receive\r
 257   uint32_t checksum_offload_rx_ip6  : 1;        ///< 1 = IPv6 checksum verification supported on receive\r
 258   uint32_t checksum_offload_rx_udp  : 1;        ///< 1 = UDP payload checksum verified on receive\r
 259   uint32_t checksum_offload_rx_tcp  : 1;        ///< 1 = TCP payload checksum verified on receive\r
 260   uint32_t checksum_offload_rx_icmp : 1;        ///< 1 = ICMP payload checksum verified on receive\r
 261   uint32_t checksum_offload_tx_ip4  : 1;        ///< 1 = IPv4 header checksum generated on transmit\r
 262   uint32_t checksum_offload_tx_ip6  : 1;        ///< 1 = IPv6 checksum generation supported on transmit\r
 263   uint32_t checksum_offload_tx_udp  : 1;        ///< 1 = UDP payload checksum generated on transmit\r
 264   uint32_t checksum_offload_tx_tcp  : 1;        ///< 1 = TCP payload checksum generated on transmit\r
 265   uint32_t checksum_offload_tx_icmp : 1;        ///< 1 = ICMP payload checksum generated on transmit\r
 266   uint32_t media_interface          : 2;        ///< Ethernet Media Interface type\r
 267   uint32_t mac_address              : 1;        ///< 1 = driver provides initial valid MAC address\r
 268   uint32_t event_rx_frame           : 1;        ///< 1 = callback event \ref ARM_ETH_MAC_EVENT_RX_FRAME generated\r
 269   uint32_t event_tx_frame           : 1;        ///< 1 = callback event \ref ARM_ETH_MAC_EVENT_TX_FRAME generated\r
 270   uint32_t event_wakeup             : 1;        ///< 1 = wakeup event \ref ARM_ETH_MAC_EVENT_WAKEUP generated\r
 271   uint32_t precision_timer          : 1;        ///< 1 = Precision Timer supported\r
 272 } ARM_ETH_MAC_CAPABILITIES;\r
 273 \r
 274 \r
 275 /**\r
 276 \brief Access structure of the Ethernet MAC Driver\r
 277 */\r
 278 typedef struct _ARM_DRIVER_ETH_MAC {\r
 279   ARM_DRIVER_VERSION       (*GetVersion)      (void);                                                ///< Pointer to \ref ARM_ETH_MAC_GetVersion : Get driver version.\r
 280   ARM_ETH_MAC_CAPABILITIES (*GetCapabilities) (void);                                                ///< Pointer to \ref ARM_ETH_MAC_GetCapabilities : Get driver capabilities.\r
 281   int32_t                  (*Initialize)      (ARM_ETH_MAC_SignalEvent_t cb_event);                  ///< Pointer to \ref ARM_ETH_MAC_Initialize : Initialize Ethernet MAC Device.\r
 282   int32_t                  (*Uninitialize)    (void);                                                ///< Pointer to \ref ARM_ETH_MAC_Uninitialize : De-initialize Ethernet MAC Device.\r
 283   int32_t                  (*PowerControl)    (ARM_POWER_STATE state);                               ///< Pointer to \ref ARM_ETH_MAC_PowerControl : Control Ethernet MAC Device Power.\r
 284   int32_t                  (*GetMacAddress)   (      ARM_ETH_MAC_ADDR *ptr_addr);                    ///< Pointer to \ref ARM_ETH_MAC_GetMacAddress : Get Ethernet MAC Address.\r
 285   int32_t                  (*SetMacAddress)   (const ARM_ETH_MAC_ADDR *ptr_addr);                    ///< Pointer to \ref ARM_ETH_MAC_SetMacAddress : Set Ethernet MAC Address.\r
 286   int32_t                  (*SetAddressFilter)(const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr); ///< Pointer to \ref ARM_ETH_MAC_SetAddressFilter : Configure Address Filter.\r
 287   int32_t                  (*SendFrame)       (const uint8_t *frame, uint32_t len, uint32_t flags);  ///< Pointer to \ref ARM_ETH_MAC_SendFrame : Send Ethernet frame.\r
 288   int32_t                  (*ReadFrame)       (      uint8_t *frame, uint32_t len);                  ///< Pointer to \ref ARM_ETH_MAC_ReadFrame : Read data of received Ethernet frame.\r
 289   uint32_t                 (*GetRxFrameSize)  (void);                                                ///< Pointer to \ref ARM_ETH_MAC_GetRxFrameSize : Get size of received Ethernet frame.\r
 290   int32_t                  (*GetRxFrameTime)  (ARM_ETH_MAC_TIME *time);                              ///< Pointer to \ref ARM_ETH_MAC_GetRxFrameTime : Get time of received Ethernet frame.\r
 291   int32_t                  (*GetTxFrameTime)  (ARM_ETH_MAC_TIME *time);                              ///< Pointer to \ref ARM_ETH_MAC_GetTxFrameTime : Get time of transmitted Ethernet frame.\r
 292   int32_t                  (*ControlTimer)    (uint32_t control, ARM_ETH_MAC_TIME *time);            ///< Pointer to \ref ARM_ETH_MAC_ControlTimer : Control Precision Timer.\r
 293   int32_t                  (*Control)         (uint32_t control, uint32_t arg);                      ///< Pointer to \ref ARM_ETH_MAC_Control : Control Ethernet Interface.\r
 294   int32_t                  (*PHY_Read)        (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data);  ///< Pointer to \ref ARM_ETH_MAC_PHY_Read : Read Ethernet PHY Register through Management Interface.\r
 295   int32_t                  (*PHY_Write)       (uint8_t phy_addr, uint8_t reg_addr, uint16_t  data);  ///< Pointer to \ref ARM_ETH_MAC_PHY_Write : Write Ethernet PHY Register through Management Interface.\r
 296 } const ARM_DRIVER_ETH_MAC;\r
 297 \r
 298 #endif /* __DRIVER_ETH_MAC_H */\r