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

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