1 /* 2 * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 #include <stdint.h> 14 #include <stdbool.h> 15 #include "esp_assert.h" 16 #include "esp_err.h" 17 #include "hal/eth_types.h" 18 #include "soc/emac_dma_struct.h" 19 #include "soc/emac_mac_struct.h" 20 #include "soc/emac_ext_struct.h" 21 22 /** 23 * @brief Indicate to ::emac_hal_receive_frame that receive frame buffer was allocated by ::emac_hal_alloc_recv_buf 24 * 25 */ 26 #define EMAC_HAL_BUF_SIZE_AUTO 0 27 28 /** 29 * @brief Ethernet DMA TX Descriptor 30 * 31 */ 32 typedef struct { 33 volatile union { 34 struct { 35 uint32_t Deferred : 1; /*!< MAC defers before transmission */ 36 uint32_t UnderflowErr : 1; /*!< DMA encountered an empty transmit buffer */ 37 uint32_t ExcessiveDeferral : 1; /*!< Excessive deferral of over 24,288 bit times */ 38 uint32_t CollisionCount : 4; /*!< Number of collisions occurred before transmitted */ 39 uint32_t VLanFrame : 1; /*!< Transmitted frame is a VLAN-type frame */ 40 uint32_t ExcessiveCollision : 1; /*!< Transmission aborted after 16 successive collisions */ 41 uint32_t LateCollision : 1; /*!< Collision occurred after the collision window */ 42 uint32_t NoCarrier : 1; /*!< Carrier Sense signal from the PHY was not asserted */ 43 uint32_t LossCarrier : 1; /*!< Loss of carrier occurred during transmission */ 44 uint32_t PayloadChecksumErr : 1; /*!< Checksum error in TCP/UDP/ICMP datagram payload */ 45 uint32_t FrameFlushed : 1; /*!< DMA or MTL flushed the frame */ 46 uint32_t JabberTimeout : 1; /*!< MAC transmitter has experienced a jabber timeout */ 47 uint32_t ErrSummary : 1; /*!< Error Summary */ 48 uint32_t IPHeadErr : 1; /*!< IP Header Error */ 49 uint32_t TxTimestampStatus : 1; /*!< Timestamp captured for the transmit frame */ 50 uint32_t VLANInsertControl : 2; /*!< VLAN tagging or untagging before transmitting */ 51 uint32_t SecondAddressChained : 1; /*!< Second address in the descriptor is Next Descriptor address */ 52 uint32_t TransmitEndRing : 1; /*!< Descriptor list reached its final descriptor */ 53 uint32_t ChecksumInsertControl : 2; /*!< Control checksum calculation and insertion */ 54 uint32_t CRCReplacementControl : 1; /*!< Control CRC replace */ 55 uint32_t TransmitTimestampEnable : 1; /*!< Enable IEEE1588 harware timestamping */ 56 uint32_t DisablePad : 1; /*!< Control add padding when frame short than 64 bytes */ 57 uint32_t DisableCRC : 1; /*!< Control append CRC to the end of frame */ 58 uint32_t FirstSegment : 1; /*!< Buffer contains the first segment of a frame */ 59 uint32_t LastSegment : 1; /*!< Buffer contains the last segment of a frame */ 60 uint32_t InterruptOnComplete : 1; /*!< Interrupt after frame transmitted */ 61 uint32_t Own : 1; /*!< Owner of this descriptor: DMA controller or host */ 62 }; 63 uint32_t Value; 64 } TDES0; 65 union { 66 struct { 67 uint32_t TransmitBuffer1Size : 13; /*!< First data buffer byte size */ 68 uint32_t Reserved : 3; /*!< Reserved */ 69 uint32_t TransmitBuffer2Size : 13; /*!< Second data buffer byte size */ 70 uint32_t SAInsertControl : 3; /*!< Control MAC add or replace Source Address field */ 71 }; 72 uint32_t Value; 73 } TDES1; 74 uint32_t Buffer1Addr; /*!< Buffer1 address pointer */ 75 uint32_t Buffer2NextDescAddr; /*!< Buffer2 or next descriptor address pointer */ 76 uint32_t Reserved1; /*!< Reserved */ 77 uint32_t Reserved2; /*!< Reserved */ 78 uint32_t TimeStampLow; /*!< Transmit Frame Timestamp Low */ 79 uint32_t TimeStampHigh; /*!< Transmit Frame Timestamp High */ 80 } eth_dma_tx_descriptor_t; 81 #define EMAC_DMATXDESC_CHECKSUM_BYPASS 0 /*!< Checksum engine bypass */ 82 #define EMAC_DMATXDESC_CHECKSUM_IPV4HEADER 1 /*!< IPv4 header checksum insertion */ 83 #define EMAC_DMATXDESC_CHECKSUM_TCPUDPICMPSEGMENT 2 /*!< TCP/UDP/ICMP Checksum Insertion calculated over segment only */ 84 #define EMAC_DMATXDESC_CHECKSUM_TCPUDPICMPFULL 3 /*!< TCP/UDP/ICMP Checksum Insertion fully calculated */ 85 86 ESP_STATIC_ASSERT(sizeof(eth_dma_tx_descriptor_t) == 32, "eth_dma_tx_descriptor_t should occupy 32 bytes in memory"); 87 88 /** 89 * @brief Ethernet DMA RX Descriptor 90 * 91 */ 92 typedef struct { 93 volatile union { 94 struct { 95 uint32_t ExtendStatusAvailable : 1; /*!< Extended statsu is available in RDES4 */ 96 uint32_t CRCErr : 1; /*!< CRC error occurred on frame */ 97 uint32_t DribbleBitErr : 1; /*!< frame contains non int multiple of 8 bits */ 98 uint32_t ReceiveErr : 1; /*!< Receive error */ 99 uint32_t ReceiveWatchdogTimeout : 1; /*!< Receive Watchdog timeout */ 100 uint32_t FrameType : 1; /*!< Ethernet type or IEEE802.3 */ 101 uint32_t LateCollision : 1; /*!< Late collision occurred during reception */ 102 uint32_t TSAvailIPChecksumErrGiantFrame : 1; /*!< Timestamp available or IP Checksum error or Giant frame */ 103 uint32_t LastDescriptor : 1; /*!< Last buffer of the frame */ 104 uint32_t FirstDescriptor : 1; /*!< First buffer of the frame */ 105 uint32_t VLANTag : 1; /*!< VLAN Tag: received frame is a VLAN frame */ 106 uint32_t OverflowErr : 1; /*!< Frame was damaged due to buffer overflow */ 107 uint32_t LengthErr : 1; /*!< Frame size not matching with length field */ 108 uint32_t SourceAddrFilterFail : 1; /*!< SA field of frame failed the SA filter */ 109 uint32_t DescriptorErr : 1; /*!< Frame truncated and DMA doesn't own next descriptor */ 110 uint32_t ErrSummary : 1; /*!< Error Summary, OR of all errors in RDES */ 111 uint32_t FrameLength : 14; /*!< Byte length of received frame */ 112 uint32_t DestinationAddrFilterFail : 1; /*!< Frame failed in the DA Filter in the MAC */ 113 uint32_t Own : 1; /*!< Owner of this descriptor: DMA controller or host */ 114 }; 115 uint32_t Value; 116 } RDES0; 117 union { 118 struct { 119 uint32_t ReceiveBuffer1Size : 13; /*!< First data buffer size in bytes */ 120 uint32_t Reserved1 : 1; /*!< Reserved */ 121 uint32_t SecondAddressChained : 1; /*!< Seconde address is the Next Descriptor address */ 122 uint32_t ReceiveEndOfRing : 1; /*!< Descriptor reached its final descriptor */ 123 uint32_t ReceiveBuffer2Size : 13; /*!< Second data buffer size in bytes */ 124 uint32_t Reserved : 2; /*!< Reserved */ 125 uint32_t DisableInterruptOnComplete : 1; /*!< Disable the assertion of interrupt to host */ 126 }; 127 uint32_t Value; 128 } RDES1; 129 uint32_t Buffer1Addr; /*!< Buffer1 address pointer */ 130 uint32_t Buffer2NextDescAddr; /*!< Buffer2 or next descriptor address pointer */ 131 volatile union { 132 struct { 133 uint32_t IPPayloadType : 3; /*!< Type of payload in the IP datagram */ 134 uint32_t IPHeadErr : 1; /*!< IP header error */ 135 uint32_t IPPayloadErr : 1; /*!< IP payload error */ 136 uint32_t IPChecksumBypass : 1; /*!< Checksum offload engine is bypassed */ 137 uint32_t IPv4PacketReceived : 1; /*!< Received packet is an IPv4 packet */ 138 uint32_t IPv6PacketReceived : 1; /*!< Received packet is an IPv6 packet */ 139 uint32_t MessageType : 4; /*!< PTP Message Type */ 140 uint32_t PTPFrameType : 1; /*!< PTP message is over Ethernet or IPv4/IPv6 */ 141 uint32_t PTPVersion : 1; /*!< Version of PTP protocol */ 142 uint32_t TimestampDropped : 1; /*!< Timestamp dropped because of overflow */ 143 uint32_t Reserved1 : 1; /*!< Reserved */ 144 uint32_t AVPacketReceived : 1; /*!< AV packet is received */ 145 uint32_t AVTaggedPacketReceived : 1; /*!< AV tagged packet is received */ 146 uint32_t VLANTagPrioVal : 3; /*!< VLAN tag's user value in the received packekt */ 147 uint32_t Reserved2 : 3; /*!< Reserved */ 148 uint32_t Layer3FilterMatch : 1; /*!< Received frame matches one of the enabled Layer3 IP */ 149 uint32_t Layer4FilterMatch : 1; /*!< Received frame matches one of the enabled Layer4 IP */ 150 uint32_t Layer3Layer4FilterNumberMatch : 2; /*!< Number of Layer3 and Layer4 Filter that matches the received frame */ 151 uint32_t Reserved3 : 4; /*!< Reserved */ 152 }; 153 uint32_t Value; 154 } ExtendedStatus; 155 uint32_t Reserved; /*!< Reserved */ 156 uint32_t TimeStampLow; /*!< Receive frame timestamp low */ 157 uint32_t TimeStampHigh; /*!< Receive frame timestamp high */ 158 } eth_dma_rx_descriptor_t; 159 160 ESP_STATIC_ASSERT(sizeof(eth_dma_rx_descriptor_t) == 32, "eth_dma_rx_descriptor_t should occupy 32 bytes in memory"); 161 162 typedef struct { 163 emac_mac_dev_t *mac_regs; 164 emac_dma_dev_t *dma_regs; 165 emac_ext_dev_t *ext_regs; 166 uint8_t **rx_buf; 167 uint8_t **tx_buf; 168 void *descriptors; 169 eth_dma_rx_descriptor_t *rx_desc; 170 eth_dma_tx_descriptor_t *tx_desc; 171 172 } emac_hal_context_t; 173 174 /** 175 * @brief EMAC related configuration 176 */ 177 typedef struct { 178 eth_mac_dma_burst_len_t dma_burst_len; /*!< eth-type enum of chosen dma burst-len */ 179 } emac_hal_dma_config_t; 180 181 void emac_hal_init(emac_hal_context_t *hal, void *descriptors, 182 uint8_t **rx_buf, uint8_t **tx_buf); 183 184 void emac_hal_iomux_init_mii(void); 185 186 void emac_hal_iomux_init_rmii(void); 187 188 void emac_hal_iomux_rmii_clk_input(void); 189 190 void emac_hal_iomux_rmii_clk_output(int num); 191 192 void emac_hal_iomux_init_tx_er(void); 193 194 void emac_hal_iomux_init_rx_er(void); 195 196 void emac_hal_reset_desc_chain(emac_hal_context_t *hal); 197 198 void emac_hal_reset(emac_hal_context_t *hal); 199 200 bool emac_hal_is_reset_done(emac_hal_context_t *hal); 201 202 void emac_hal_set_csr_clock_range(emac_hal_context_t *hal, int freq); 203 204 void emac_hal_init_mac_default(emac_hal_context_t *hal); 205 206 void emac_hal_init_dma_default(emac_hal_context_t *hal, emac_hal_dma_config_t *hal_config); 207 208 void emac_hal_set_speed(emac_hal_context_t *hal, uint32_t speed); 209 210 void emac_hal_set_duplex(emac_hal_context_t *hal, eth_duplex_t duplex); 211 212 void emac_hal_set_promiscuous(emac_hal_context_t *hal, bool enable); 213 214 /** 215 * @brief Send MAC-CTRL frames to peer (EtherType=0x8808, opcode=0x0001, dest_addr=MAC-specific-ctrl-proto-01 (01:80:c2:00:00:01)) 216 */ 217 void emac_hal_send_pause_frame(emac_hal_context_t *hal, bool enable); 218 219 bool emac_hal_is_mii_busy(emac_hal_context_t *hal); 220 221 void emac_hal_set_phy_cmd(emac_hal_context_t *hal, uint32_t phy_addr, uint32_t phy_reg, bool write); 222 223 void emac_hal_set_phy_data(emac_hal_context_t *hal, uint32_t reg_value); 224 225 uint32_t emac_hal_get_phy_data(emac_hal_context_t *hal); 226 227 void emac_hal_set_address(emac_hal_context_t *hal, uint8_t *mac_addr); 228 229 /** 230 * @brief Starts EMAC Transmission & Reception 231 * 232 * @param hal EMAC HAL context infostructure 233 */ 234 void emac_hal_start(emac_hal_context_t *hal); 235 236 /** 237 * @brief Stops EMAC Transmission & Reception 238 * 239 * @param hal EMAC HAL context infostructure 240 * @return 241 * - ESP_OK: succeed 242 * - ESP_ERR_INVALID_STATE: previous frame transmission/reception is not completed. When this error occurs, 243 * wait and reapeat the EMAC stop again. 244 */ 245 esp_err_t emac_hal_stop(emac_hal_context_t *hal); 246 247 /** 248 * @brief Transmit data from buffer over EMAC 249 * 250 * @param[in] hal EMAC HAL context infostructure 251 * @param[in] buf buffer to be transmitted 252 * @param[in] length length of the buffer 253 * @return number of transmitted bytes when success 254 */ 255 uint32_t emac_hal_transmit_frame(emac_hal_context_t *hal, uint8_t *buf, uint32_t length); 256 257 /** 258 * @brief Transmit data from multiple buffers over EMAC in single Ethernet frame. Data will be joint into 259 * single frame in order in which the buffers are stored in input array. 260 * 261 * @param[in] hal EMAC HAL context infostructure 262 * @param[in] buffs array of pointers to buffers to be transmitted 263 * @param[in] lengths array of lengths of the buffers 264 * @param[in] inbuffs_cnt number of buffers (i.e. input arrays size) 265 * @return number of transmitted bytes when success 266 * 267 * @pre @p lengths array must have the same size as @p buffs array and their elements need to be stored in the same 268 * order, i.e. lengths[1] is a length assocaited with data buffer referenced at buffs[1] position. 269 */ 270 uint32_t emac_hal_transmit_multiple_buf_frame(emac_hal_context_t *hal, uint8_t **buffs, uint32_t *lengths, uint32_t inbuffs_cnt); 271 272 /** 273 * @brief Allocate buffer with size equal to actually received Ethernet frame size. 274 * 275 * @param[in] hal EMAC HAL context infostructure 276 * @param[in, out] size as an input defines maximum size of buffer to be allocated. As an output, indicates actual size of received 277 * Ethernet frame which is waiting to be processed. Returned size may be 0 when there is no waiting frame. 278 * 279 * @note If maximum allowed size of buffer to be allocated is less than actual size of received Ethernet frame, the buffer 280 * is allocated with that limit and the frame will be truncated by emac_hal_receive_frame. 281 * 282 * @return Pointer to allocated buffer 283 * NULL when allocation fails or when there is no waiting Ethernet frame 284 */ 285 uint8_t *emac_hal_alloc_recv_buf(emac_hal_context_t *hal, uint32_t *size); 286 287 /** 288 * @brief Copy received Ethernet frame from EMAC DMA memory space to application. 289 * 290 * @param[in] hal EMAC HAL context infostructure 291 * @param[in] buf buffer into which the Ethernet frame is to be copied 292 * @param[in] size buffer size. When buffer was allocated by ::emac_hal_alloc_recv_buf, this parameter needs to be set 293 * to EMAC_HAL_BUF_SIZE_AUTO 294 * @param[out] frames_remain number of frames remaining to be processed 295 * @param[out] free_desc muber of free DMA Rx descriptors 296 * 297 * @return number of copied bytes when success 298 * 0 when there is no waiting Ethernet frame or on error 299 * 300 * @note FCS field is never copied 301 * @note If buffer size is less than actual size of received Ethernet frame, the frame will be truncated. 302 * @note When this function is called with EMAC_HAL_BUF_SIZE_AUTO size parameter, buffer needs to be allocated by 303 * ::emac_hal_alloc_recv_buf function at first. 304 */ 305 uint32_t emac_hal_receive_frame(emac_hal_context_t *hal, uint8_t *buf, uint32_t size, uint32_t *frames_remain, uint32_t *free_desc); 306 307 uint32_t emac_hal_flush_recv_frame(emac_hal_context_t *hal, uint32_t *frames_remain, uint32_t *free_desc); 308 309 void emac_hal_enable_flow_ctrl(emac_hal_context_t *hal, bool enable); 310 311 uint32_t emac_hal_get_intr_enable_status(emac_hal_context_t *hal); 312 313 uint32_t emac_hal_get_intr_status(emac_hal_context_t *hal); 314 315 void emac_hal_clear_corresponding_intr(emac_hal_context_t *hal, uint32_t bits); 316 317 void emac_hal_clear_all_intr(emac_hal_context_t *hal); 318 319 #ifdef __cplusplus 320 } 321 #endif 322
