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

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