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_ */ 311
