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

   1 /*
   2  * Copyright (c) 2013-2017 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  * 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:        2. Feb 2017
  19  * $Revision:    V2.1
  20  *
  21  * Project:      Ethernet MAC (Media Access Control) Driver definitions
  22  */
  23
  24 /* History:
  25  *  Version 2.1
  26  *    Added ARM_ETH_MAC_SLEEP Control
  27  *  Version 2.0
  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 #ifdef  __cplusplus
  56 extern "C"
  57 {
  58 #endif
  59
  60 #include "Driver_ETH.h"
  61
  62 #define ARM_ETH_MAC_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,1)  /* API version */
  63
  64
  65 #define _ARM_Driver_ETH_MAC_(n)      Driver_ETH_MAC##n
  66 #define  ARM_Driver_ETH_MAC_(n) _ARM_Driver_ETH_MAC_(n)
  67
  68
  69 /****** Ethernet MAC Control Codes *****/
  70
  71 #define ARM_ETH_MAC_CONFIGURE           (0x01)      ///< Configure MAC; arg = configuration
  72 #define ARM_ETH_MAC_CONTROL_TX          (0x02)      ///< Transmitter; arg: 0=disabled (default), 1=enabled
  73 #define ARM_ETH_MAC_CONTROL_RX          (0x03)      ///< Receiver; arg: 0=disabled (default), 1=enabled
  74 #define ARM_ETH_MAC_FLUSH               (0x04)      ///< Flush buffer; arg = ARM_ETH_MAC_FLUSH_...
  75 #define ARM_ETH_MAC_SLEEP               (0x05)      ///< Sleep mode; arg: 1=enter and wait for Magic packet, 0=exit
  76 #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)
  77
  78 /*----- Ethernet MAC Configuration -----*/
  79 #define ARM_ETH_MAC_SPEED_Pos            0
  80 #define ARM_ETH_MAC_SPEED_Msk           (3UL                 << ARM_ETH_MAC_SPEED_Pos)
  81 #define ARM_ETH_MAC_SPEED_10M           (ARM_ETH_SPEED_10M   << ARM_ETH_MAC_SPEED_Pos)  ///< 10 Mbps link speed
  82 #define ARM_ETH_MAC_SPEED_100M          (ARM_ETH_SPEED_100M  << ARM_ETH_MAC_SPEED_Pos)  ///< 100 Mbps link speed
  83 #define ARM_ETH_MAC_SPEED_1G            (ARM_ETH_SPEED_1G    << ARM_ETH_MAC_SPEED_Pos)  ///< 1 Gpbs link speed
  84 #define ARM_ETH_MAC_DUPLEX_Pos           2
  85 #define ARM_ETH_MAC_DUPLEX_Msk          (1UL                 << ARM_ETH_MAC_DUPLEX_Pos)
  86 #define ARM_ETH_MAC_DUPLEX_HALF         (ARM_ETH_DUPLEX_HALF << ARM_ETH_MAC_DUPLEX_Pos) ///< Half duplex link
  87 #define ARM_ETH_MAC_DUPLEX_FULL         (ARM_ETH_DUPLEX_FULL << ARM_ETH_MAC_DUPLEX_Pos) ///< Full duplex link
  88 #define ARM_ETH_MAC_LOOPBACK            (1UL << 4)  ///< Loop-back test mode
  89 #define ARM_ETH_MAC_CHECKSUM_OFFLOAD_RX (1UL << 5)  ///< Receiver Checksum offload
  90 #define ARM_ETH_MAC_CHECKSUM_OFFLOAD_TX (1UL << 6)  ///< Transmitter Checksum offload
  91 #define ARM_ETH_MAC_ADDRESS_BROADCAST   (1UL << 7)  ///< Accept frames with Broadcast address
  92 #define ARM_ETH_MAC_ADDRESS_MULTICAST   (1UL << 8)  ///< Accept frames with any Multicast address
  93 #define ARM_ETH_MAC_ADDRESS_ALL         (1UL << 9)  ///< Accept frames with any address (Promiscuous Mode)
  94
  95 /*----- Ethernet MAC Flush Flags -----*/
  96 #define ARM_ETH_MAC_FLUSH_RX            (1UL << 0)  ///< Flush Receive buffer
  97 #define ARM_ETH_MAC_FLUSH_TX            (1UL << 1)  ///< Flush Transmit buffer
  98
  99 /*----- Ethernet MAC VLAN Filter Flag -----*/
 100 #define ARM_ETH_MAC_VLAN_FILTER_ID_ONLY (1UL << 16) ///< Compare only the VLAN Identifier (12-bit)
 101
 102
 103 /****** Ethernet MAC Frame Transmit Flags *****/
 104 #define ARM_ETH_MAC_TX_FRAME_FRAGMENT   (1UL << 0)  ///< Indicate frame fragment
 105 #define ARM_ETH_MAC_TX_FRAME_EVENT      (1UL << 1)  ///< Generate event when frame is transmitted
 106 #define ARM_ETH_MAC_TX_FRAME_TIMESTAMP  (1UL << 2)  ///< Capture frame time stamp
 107
 108
 109 /****** Ethernet MAC Timer Control Codes *****/
 110 #define ARM_ETH_MAC_TIMER_GET_TIME      (0x01)      ///< Get current time
 111 #define ARM_ETH_MAC_TIMER_SET_TIME      (0x02)      ///< Set new time
 112 #define ARM_ETH_MAC_TIMER_INC_TIME      (0x03)      ///< Increment current time
 113 #define ARM_ETH_MAC_TIMER_DEC_TIME      (0x04)      ///< Decrement current time
 114 #define ARM_ETH_MAC_TIMER_SET_ALARM     (0x05)      ///< Set alarm time
 115 #define ARM_ETH_MAC_TIMER_ADJUST_CLOCK  (0x06)      ///< Adjust clock frequency; time->ns: correction factor * 2^31
 116
 117
 118 /**
 119 \brief Ethernet MAC Time
 120 */
 121 typedef struct _ARM_ETH_MAC_TIME {
 122   uint32_t ns;                          ///< Nano seconds
 123   uint32_t sec;                         ///< Seconds
 124 } ARM_ETH_MAC_TIME;
 125
 126
 127 /****** Ethernet MAC Event *****/
 128 #define ARM_ETH_MAC_EVENT_RX_FRAME      (1UL << 0)  ///< Frame Received
 129 #define ARM_ETH_MAC_EVENT_TX_FRAME      (1UL << 1)  ///< Frame Transmitted
 130 #define ARM_ETH_MAC_EVENT_WAKEUP        (1UL << 2)  ///< Wake-up (on Magic Packet)
 131 #define ARM_ETH_MAC_EVENT_TIMER_ALARM   (1UL << 3)  ///< Timer Alarm
 132
 133
 134 // Function documentation
 135 /**
 136   \fn          ARM_DRIVER_VERSION ARM_ETH_MAC_GetVersion (void)
 137   \brief       Get driver version.
 138   \return      \ref ARM_DRIVER_VERSION
 139 */
 140 /**
 141   \fn          ARM_ETH_MAC_CAPABILITIES ARM_ETH_MAC_GetCapabilities (void)
 142   \brief       Get driver capabilities.
 143   \return      \ref ARM_ETH_MAC_CAPABILITIES
 144 */
 145 /**
 146   \fn          int32_t ARM_ETH_MAC_Initialize (ARM_ETH_MAC_SignalEvent_t cb_event)
 147   \brief       Initialize Ethernet MAC Device.
 148   \param[in]   cb_event  Pointer to \ref ARM_ETH_MAC_SignalEvent
 149   \return      \ref execution_status
 150 */
 151 /**
 152   \fn          int32_t ARM_ETH_MAC_Uninitialize (void)
 153   \brief       De-initialize Ethernet MAC Device.
 154   \return      \ref execution_status
 155 */
 156 /**
 157   \fn          int32_t ARM_ETH_MAC_PowerControl (ARM_POWER_STATE state)
 158   \brief       Control Ethernet MAC Device Power.
 159   \param[in]   state  Power state
 160   \return      \ref execution_status
 161 */
 162 /**
 163   \fn          int32_t ARM_ETH_MAC_GetMacAddress (ARM_ETH_MAC_ADDR *ptr_addr)
 164   \brief       Get Ethernet MAC Address.
 165   \param[in]   ptr_addr  Pointer to address
 166   \return      \ref execution_status
 167 */
 168 /**
 169   \fn          int32_t ARM_ETH_MAC_SetMacAddress (const ARM_ETH_MAC_ADDR *ptr_addr)
 170   \brief       Set Ethernet MAC Address.
 171   \param[in]   ptr_addr  Pointer to address
 172   \return      \ref execution_status
 173 */
 174 /**
 175   \fn          int32_t ARM_ETH_MAC_SetAddressFilter (const ARM_ETH_MAC_ADDR *ptr_addr,
 176                                                            uint32_t          num_addr)
 177   \brief       Configure Address Filter.
 178   \param[in]   ptr_addr  Pointer to addresses
 179   \param[in]   num_addr  Number of addresses to configure
 180   \return      \ref execution_status
 181 */
 182 /**
 183   \fn          int32_t ARM_ETH_MAC_SendFrame (const uint8_t *frame, uint32_t len, uint32_t flags)
 184   \brief       Send Ethernet frame.
 185   \param[in]   frame  Pointer to frame buffer with data to send
 186   \param[in]   len    Frame buffer length in bytes
 187   \param[in]   flags  Frame transmit flags (see ARM_ETH_MAC_TX_FRAME_...)
 188   \return      \ref execution_status
 189 */
 190 /**
 191   \fn          int32_t ARM_ETH_MAC_ReadFrame (uint8_t *frame, uint32_t len)
 192   \brief       Read data of received Ethernet frame.
 193   \param[in]   frame  Pointer to frame buffer for data to read into
 194   \param[in]   len    Frame buffer length in bytes
 195   \return      number of data bytes read or execution status
 196                  - value >= 0: number of data bytes read
 197                  - value < 0: error occurred, value is execution status as defined with \ref execution_status
 198 */
 199 /**
 200   \fn          uint32_t ARM_ETH_MAC_GetRxFrameSize (void)
 201   \brief       Get size of received Ethernet frame.
 202   \return      number of bytes in received frame
 203 */
 204 /**
 205   \fn          int32_t ARM_ETH_MAC_GetRxFrameTime (ARM_ETH_MAC_TIME *time)
 206   \brief       Get time of received Ethernet frame.
 207   \param[in]   time  Pointer to time structure for data to read into
 208   \return      \ref execution_status
 209 */
 210 /**
 211   \fn          int32_t ARM_ETH_MAC_GetTxFrameTime (ARM_ETH_MAC_TIME *time)
 212   \brief       Get time of transmitted Ethernet frame.
 213   \param[in]   time  Pointer to time structure for data to read into
 214   \return      \ref execution_status
 215 */
 216 /**
 217   \fn          int32_t ARM_ETH_MAC_Control (uint32_t control, uint32_t arg)
 218   \brief       Control Ethernet Interface.
 219   \param[in]   control  Operation
 220   \param[in]   arg      Argument of operation (optional)
 221   \return      \ref execution_status
 222 */
 223 /**
 224   \fn          int32_t ARM_ETH_MAC_ControlTimer (uint32_t control, ARM_ETH_MAC_TIME *time)
 225   \brief       Control Precision Timer.
 226   \param[in]   control  Operation
 227   \param[in]   time     Pointer to time structure
 228   \return      \ref execution_status
 229 */
 230 /**
 231   \fn          int32_t ARM_ETH_MAC_PHY_Read (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)
 232   \brief       Read Ethernet PHY Register through Management Interface.
 233   \param[in]   phy_addr  5-bit device address
 234   \param[in]   reg_addr  5-bit register address
 235   \param[out]  data      Pointer where the result is written to
 236   \return      \ref execution_status
 237 */
 238 /**
 239   \fn          int32_t ARM_ETH_MAC_PHY_Write (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)
 240   \brief       Write Ethernet PHY Register through Management Interface.
 241   \param[in]   phy_addr  5-bit device address
 242   \param[in]   reg_addr  5-bit register address
 243   \param[in]   data      16-bit data to write
 244   \return      \ref execution_status
 245 */
 246
 247 /**
 248   \fn          void ARM_ETH_MAC_SignalEvent (uint32_t event)
 249   \brief       Callback function that signals a Ethernet Event.
 250   \param[in]   event  event notification mask
 251   \return      none
 252 */
 253
 254 typedef void (*ARM_ETH_MAC_SignalEvent_t) (uint32_t event);  ///< Pointer to \ref ARM_ETH_MAC_SignalEvent : Signal Ethernet Event.
 255
 256
 257 /**
 258 \brief Ethernet MAC Capabilities
 259 */
 260 typedef struct _ARM_ETH_MAC_CAPABILITIES {
 261   uint32_t checksum_offload_rx_ip4  : 1;        ///< 1 = IPv4 header checksum verified on receive
 262   uint32_t checksum_offload_rx_ip6  : 1;        ///< 1 = IPv6 checksum verification supported on receive
 263   uint32_t checksum_offload_rx_udp  : 1;        ///< 1 = UDP payload checksum verified on receive
 264   uint32_t checksum_offload_rx_tcp  : 1;        ///< 1 = TCP payload checksum verified on receive
 265   uint32_t checksum_offload_rx_icmp : 1;        ///< 1 = ICMP payload checksum verified on receive
 266   uint32_t checksum_offload_tx_ip4  : 1;        ///< 1 = IPv4 header checksum generated on transmit
 267   uint32_t checksum_offload_tx_ip6  : 1;        ///< 1 = IPv6 checksum generation supported on transmit
 268   uint32_t checksum_offload_tx_udp  : 1;        ///< 1 = UDP payload checksum generated on transmit
 269   uint32_t checksum_offload_tx_tcp  : 1;        ///< 1 = TCP payload checksum generated on transmit
 270   uint32_t checksum_offload_tx_icmp : 1;        ///< 1 = ICMP payload checksum generated on transmit
 271   uint32_t media_interface          : 2;        ///< Ethernet Media Interface type
 272   uint32_t mac_address              : 1;        ///< 1 = driver provides initial valid MAC address
 273   uint32_t event_rx_frame           : 1;        ///< 1 = callback event \ref ARM_ETH_MAC_EVENT_RX_FRAME generated
 274   uint32_t event_tx_frame           : 1;        ///< 1 = callback event \ref ARM_ETH_MAC_EVENT_TX_FRAME generated
 275   uint32_t event_wakeup             : 1;        ///< 1 = wakeup event \ref ARM_ETH_MAC_EVENT_WAKEUP generated
 276   uint32_t precision_timer          : 1;        ///< 1 = Precision Timer supported
 277   uint32_t reserved                 : 15;       ///< Reserved (must be zero)
 278 } ARM_ETH_MAC_CAPABILITIES;
 279
 280
 281 /**
 282 \brief Access structure of the Ethernet MAC Driver
 283 */
 284 typedef struct _ARM_DRIVER_ETH_MAC {
 285   ARM_DRIVER_VERSION       (*GetVersion)      (void);                                                ///< Pointer to \ref ARM_ETH_MAC_GetVersion : Get driver version.
 286   ARM_ETH_MAC_CAPABILITIES (*GetCapabilities) (void);                                                ///< Pointer to \ref ARM_ETH_MAC_GetCapabilities : Get driver capabilities.
 287   int32_t                  (*Initialize)      (ARM_ETH_MAC_SignalEvent_t cb_event);                  ///< Pointer to \ref ARM_ETH_MAC_Initialize : Initialize Ethernet MAC Device.
 288   int32_t                  (*Uninitialize)    (void);                                                ///< Pointer to \ref ARM_ETH_MAC_Uninitialize : De-initialize Ethernet MAC Device.
 289   int32_t                  (*PowerControl)    (ARM_POWER_STATE state);                               ///< Pointer to \ref ARM_ETH_MAC_PowerControl : Control Ethernet MAC Device Power.
 290   int32_t                  (*GetMacAddress)   (      ARM_ETH_MAC_ADDR *ptr_addr);                    ///< Pointer to \ref ARM_ETH_MAC_GetMacAddress : Get Ethernet MAC Address.
 291   int32_t                  (*SetMacAddress)   (const ARM_ETH_MAC_ADDR *ptr_addr);                    ///< Pointer to \ref ARM_ETH_MAC_SetMacAddress : Set Ethernet MAC Address.
 292   int32_t                  (*SetAddressFilter)(const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr); ///< Pointer to \ref ARM_ETH_MAC_SetAddressFilter : Configure Address Filter.
 293   int32_t                  (*SendFrame)       (const uint8_t *frame, uint32_t len, uint32_t flags);  ///< Pointer to \ref ARM_ETH_MAC_SendFrame : Send Ethernet frame.
 294   int32_t                  (*ReadFrame)       (      uint8_t *frame, uint32_t len);                  ///< Pointer to \ref ARM_ETH_MAC_ReadFrame : Read data of received Ethernet frame.
 295   uint32_t                 (*GetRxFrameSize)  (void);                                                ///< Pointer to \ref ARM_ETH_MAC_GetRxFrameSize : Get size of received Ethernet frame.
 296   int32_t                  (*GetRxFrameTime)  (ARM_ETH_MAC_TIME *time);                              ///< Pointer to \ref ARM_ETH_MAC_GetRxFrameTime : Get time of received Ethernet frame.
 297   int32_t                  (*GetTxFrameTime)  (ARM_ETH_MAC_TIME *time);                              ///< Pointer to \ref ARM_ETH_MAC_GetTxFrameTime : Get time of transmitted Ethernet frame.
 298   int32_t                  (*ControlTimer)    (uint32_t control, ARM_ETH_MAC_TIME *time);            ///< Pointer to \ref ARM_ETH_MAC_ControlTimer : Control Precision Timer.
 299   int32_t                  (*Control)         (uint32_t control, uint32_t arg);                      ///< Pointer to \ref ARM_ETH_MAC_Control : Control Ethernet Interface.
 300   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.
 301   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.
 302 } const ARM_DRIVER_ETH_MAC;
 303
 304 #ifdef  __cplusplus
 305 }
 306 #endif
 307
 308 #endif /* DRIVER_ETH_MAC_H_ */