stm32f4xx_hal_eth.c File Reference

ETH HAL module driver. This file provides firmware functions to manage the following functionalities of the Ethernet (ETH) peripheral: More...

#include "stm32f4xx_hal.h"

Include dependency graph for stm32f4xx_hal_eth.c:

Go to the source code of this file.

Macros
#define	ETH_MACCR_MASK   0xFFFB7F7CU
#define	ETH_MACECR_MASK   0x3F077FFFU
#define	ETH_MACFFR_MASK   0x800007FFU
#define	ETH_MACWTR_MASK   0x0000010FU
#define	ETH_MACTFCR_MASK   0xFFFF00F2U
#define	ETH_MACRFCR_MASK   0x00000003U
#define	ETH_MTLTQOMR_MASK   0x00000072U
#define	ETH_MTLRQOMR_MASK   0x0000007BU
#define	ETH_DMAMR_MASK   0x00007802U
#define	ETH_DMASBMR_MASK   0x0000D001U
#define	ETH_DMACCR_MASK   0x00013FFFU
#define	ETH_DMACTCR_MASK   0x003F1010U
#define	ETH_DMACRCR_MASK   0x803F0000U
#define	ETH_MACPMTCSR_MASK
#define	ETH_SWRESET_TIMEOUT   500U
#define	ETH_MDIO_BUS_TIMEOUT   1000U
#define	ETH_DMARXDESC_ERRORS_MASK
#define	ETH_MAC_US_TICK   1000000U
#define	ETH_MACTSCR_MASK   0x0087FF2FU
#define	ETH_PTPTSHR_VALUE   0xFFFFFFFFU
#define	ETH_PTPTSLR_VALUE   0xBB9ACA00U
#define	ETH_MACMIIAR_CR_MASK   0xFFFFFFE3U
#define	ETH_REG_WRITE_DELAY   0x00000001U
#define	ETH_MACCR_CLEAR_MASK   0xFD20810FU
#define	ETH_MACFCR_CLEAR_MASK   0x0000FF41U
#define	ETH_DMAOMR_CLEAR_MASK   0xF8DE3F23U
#define	ETH_MAC_ADDR_HBASE   (uint32_t)(ETH_MAC_BASE + 0x40U) /* ETHERNET MAC address high offset */
#define	ETH_MAC_ADDR_LBASE   (uint32_t)(ETH_MAC_BASE + 0x44U) /* ETHERNET MAC address low offset */
#define	ETH_DMARXDESC_FRAMELENGTHSHIFT   16U
#define	INCR_TX_DESC_INDEX(inx, offset)
#define	INCR_RX_DESC_INDEX(inx, offset)

Functions
static void	ETH_SetMACConfig (ETH_HandleTypeDef *heth, const ETH_MACConfigTypeDef *macconf)
static void	ETH_SetDMAConfig (ETH_HandleTypeDef *heth, const ETH_DMAConfigTypeDef *dmaconf)
static void	ETH_MACDMAConfig (ETH_HandleTypeDef *heth)
	Configures Ethernet MAC and DMA with default parameters. called by HAL_ETH_Init() API.
static void	ETH_DMATxDescListInit (ETH_HandleTypeDef *heth)
	Initializes the DMA Tx descriptors. called by HAL_ETH_Init() API.
static void	ETH_DMARxDescListInit (ETH_HandleTypeDef *heth)
	Initializes the DMA Rx descriptors in chain mode. called by HAL_ETH_Init() API.
static uint32_t	ETH_Prepare_Tx_Descriptors (ETH_HandleTypeDef *heth, const ETH_TxPacketConfigTypeDef *pTxConfig, uint32_t ItMode)
	Prepare Tx DMA descriptor before transmission. called by HAL_ETH_Transmit_IT and HAL_ETH_Transmit_IT() API.
static void	ETH_UpdateDescriptor (ETH_HandleTypeDef *heth)
	This function gives back Rx Desc of the last received Packet to the DMA, so ETH DMA will be able to use these descriptors to receive next Packets.
static void	ETH_FlushTransmitFIFO (ETH_HandleTypeDef *heth)
	Clears the ETHERNET transmit FIFO.
static void	ETH_MACAddressConfig (ETH_HandleTypeDef *heth, uint32_t MacAddr, uint8_t *Addr)
	Configures the selected MAC address.
HAL_StatusTypeDef	HAL_ETH_Init (ETH_HandleTypeDef *heth)
	Initialize the Ethernet peripheral registers.
HAL_StatusTypeDef	HAL_ETH_DeInit (ETH_HandleTypeDef *heth)
	DeInitializes the ETH peripheral.
void	HAL_ETH_MspInit (ETH_HandleTypeDef *heth)
	Initializes the ETH MSP.
void	HAL_ETH_MspDeInit (ETH_HandleTypeDef *heth)
	DeInitializes ETH MSP.
HAL_StatusTypeDef	HAL_ETH_Start (ETH_HandleTypeDef *heth)
	Enables Ethernet MAC and DMA reception and transmission.
HAL_StatusTypeDef	HAL_ETH_Start_IT (ETH_HandleTypeDef *heth)
	Enables Ethernet MAC and DMA reception/transmission in Interrupt mode.
HAL_StatusTypeDef	HAL_ETH_Stop (ETH_HandleTypeDef *heth)
	Stop Ethernet MAC and DMA reception/transmission.
HAL_StatusTypeDef	HAL_ETH_Stop_IT (ETH_HandleTypeDef *heth)
	Stop Ethernet MAC and DMA reception/transmission in Interrupt mode.
HAL_StatusTypeDef	HAL_ETH_Transmit (ETH_HandleTypeDef *heth, ETH_TxPacketConfigTypeDef *pTxConfig, uint32_t Timeout)
	Sends an Ethernet Packet in polling mode.
HAL_StatusTypeDef	HAL_ETH_Transmit_IT (ETH_HandleTypeDef *heth, ETH_TxPacketConfigTypeDef *pTxConfig)
	Sends an Ethernet Packet in interrupt mode.
HAL_StatusTypeDef	HAL_ETH_ReadData (ETH_HandleTypeDef *heth, void **pAppBuff)
	Read a received packet.
HAL_StatusTypeDef	HAL_ETH_RegisterRxAllocateCallback (ETH_HandleTypeDef *heth, pETH_rxAllocateCallbackTypeDef rxAllocateCallback)
	Register the Rx alloc callback.
HAL_StatusTypeDef	HAL_ETH_UnRegisterRxAllocateCallback (ETH_HandleTypeDef *heth)
	Unregister the Rx alloc callback.
void	HAL_ETH_RxAllocateCallback (uint8_t **buff)
	Rx Allocate callback.
void	HAL_ETH_RxLinkCallback (void **pStart, void **pEnd, uint8_t *buff, uint16_t Length)
	Rx Link callback.
HAL_StatusTypeDef	HAL_ETH_RegisterRxLinkCallback (ETH_HandleTypeDef *heth, pETH_rxLinkCallbackTypeDef rxLinkCallback)
	Set the Rx link data function.
HAL_StatusTypeDef	HAL_ETH_UnRegisterRxLinkCallback (ETH_HandleTypeDef *heth)
	Unregister the Rx link callback.
HAL_StatusTypeDef	HAL_ETH_GetRxDataErrorCode (const ETH_HandleTypeDef *heth, uint32_t *pErrorCode)
	Get the error state of the last received packet.
HAL_StatusTypeDef	HAL_ETH_RegisterTxFreeCallback (ETH_HandleTypeDef *heth, pETH_txFreeCallbackTypeDef txFreeCallback)
	Set the Tx free function.
HAL_StatusTypeDef	HAL_ETH_UnRegisterTxFreeCallback (ETH_HandleTypeDef *heth)
	Unregister the Tx free callback.
void	HAL_ETH_TxFreeCallback (uint32_t *buff)
	Tx Free callback.
HAL_StatusTypeDef	HAL_ETH_ReleaseTxPacket (ETH_HandleTypeDef *heth)
	Release transmitted Tx packets.
void	HAL_ETH_IRQHandler (ETH_HandleTypeDef *heth)
	This function handles ETH interrupt request.
void	HAL_ETH_TxCpltCallback (ETH_HandleTypeDef *heth)
	Tx Transfer completed callbacks.
void	HAL_ETH_RxCpltCallback (ETH_HandleTypeDef *heth)
	Rx Transfer completed callbacks.
void	HAL_ETH_ErrorCallback (ETH_HandleTypeDef *heth)
	Ethernet transfer error callbacks.
void	HAL_ETH_PMTCallback (ETH_HandleTypeDef *heth)
	Ethernet Power Management module IT callback.
void	HAL_ETH_WakeUpCallback (ETH_HandleTypeDef *heth)
	ETH WAKEUP interrupt callback.
HAL_StatusTypeDef	HAL_ETH_ReadPHYRegister (ETH_HandleTypeDef *heth, uint32_t PHYAddr, uint32_t PHYReg, uint32_t *pRegValue)
	Read a PHY register.
HAL_StatusTypeDef	HAL_ETH_WritePHYRegister (const ETH_HandleTypeDef *heth, uint32_t PHYAddr, uint32_t PHYReg, uint32_t RegValue)
	Writes to a PHY register.
HAL_StatusTypeDef	HAL_ETH_GetMACConfig (const ETH_HandleTypeDef *heth, ETH_MACConfigTypeDef *macconf)
	Get the configuration of the MAC and MTL subsystems.
HAL_StatusTypeDef	HAL_ETH_GetDMAConfig (const ETH_HandleTypeDef *heth, ETH_DMAConfigTypeDef *dmaconf)
	Get the configuration of the DMA.
HAL_StatusTypeDef	HAL_ETH_SetMACConfig (ETH_HandleTypeDef *heth, ETH_MACConfigTypeDef *macconf)
	Set the MAC configuration.
HAL_StatusTypeDef	HAL_ETH_SetDMAConfig (ETH_HandleTypeDef *heth, ETH_DMAConfigTypeDef *dmaconf)
	Set the ETH DMA configuration.
void	HAL_ETH_SetMDIOClockRange (ETH_HandleTypeDef *heth)
	Configures the Clock range of ETH MDIO interface.
HAL_StatusTypeDef	HAL_ETH_SetMACFilterConfig (ETH_HandleTypeDef *heth, const ETH_MACFilterConfigTypeDef *pFilterConfig)
	Set the ETH MAC (L2) Filters configuration.
HAL_StatusTypeDef	HAL_ETH_GetMACFilterConfig (const ETH_HandleTypeDef *heth, ETH_MACFilterConfigTypeDef *pFilterConfig)
	Get the ETH MAC (L2) Filters configuration.
HAL_StatusTypeDef	HAL_ETH_SetSourceMACAddrMatch (const ETH_HandleTypeDef *heth, uint32_t AddrNbr, const uint8_t *pMACAddr)
	Set the source MAC Address to be matched.
HAL_StatusTypeDef	HAL_ETH_SetHashTable (ETH_HandleTypeDef *heth, uint32_t *pHashTable)
	Set the ETH Hash Table Value.
void	HAL_ETH_SetRxVLANIdentifier (ETH_HandleTypeDef *heth, uint32_t ComparisonBits, uint32_t VLANIdentifier)
	Set the VLAN Identifier for Rx packets.
void	HAL_ETH_EnterPowerDownMode (ETH_HandleTypeDef *heth, const ETH_PowerDownConfigTypeDef *pPowerDownConfig)
	Enters the Power down mode.
void	HAL_ETH_ExitPowerDownMode (ETH_HandleTypeDef *heth)
	Exits from the Power down mode.
HAL_StatusTypeDef	HAL_ETH_SetWakeUpFilter (ETH_HandleTypeDef *heth, uint32_t *pFilter, uint32_t Count)
	Set the WakeUp filter.
HAL_ETH_StateTypeDef	HAL_ETH_GetState (const ETH_HandleTypeDef *heth)
	Returns the ETH state.
uint32_t	HAL_ETH_GetError (const ETH_HandleTypeDef *heth)
	Returns the ETH error code.
uint32_t	HAL_ETH_GetDMAError (const ETH_HandleTypeDef *heth)
	Returns the ETH DMA error code.
uint32_t	HAL_ETH_GetMACError (const ETH_HandleTypeDef *heth)
	Returns the ETH MAC error code.
uint32_t	HAL_ETH_GetMACWakeUpSource (const ETH_HandleTypeDef *heth)
	Returns the ETH MAC WakeUp event source.

Detailed Description

ETH HAL module driver. This file provides firmware functions to manage the following functionalities of the Ethernet (ETH) peripheral:

Author

MCD Application Team

• Initialization and deinitialization functions
• IO operation functions
• Peripheral Control functions
• Peripheral State and Errors functions

Attention

Copyright (c) 2016 STMicroelectronics. All rights reserved.

This software is licensed under terms that can be found in the LICENSE file in the root directory of this software component. If no LICENSE file comes with this software, it is provided AS-IS.

==============================================================================
                  ##### How to use this driver #####
==============================================================================
   [..]
   The ETH HAL driver can be used as follows:

    (#)Declare a ETH_HandleTypeDef handle structure, for example:
       ETH_HandleTypeDef  heth;

    (#)Fill parameters of Init structure in heth handle

    (#)Call HAL_ETH_Init() API to initialize the Ethernet peripheral (MAC, DMA, ...)

    (#)Initialize the ETH low level resources through the HAL_ETH_MspInit() API:
        (##) Enable the Ethernet interface clock using
              (+++)  __HAL_RCC_ETH1MAC_CLK_ENABLE()
              (+++)  __HAL_RCC_ETH1TX_CLK_ENABLE()
              (+++)  __HAL_RCC_ETH1RX_CLK_ENABLE()

        (##) Initialize the related GPIO clocks
        (##) Configure Ethernet pinout
        (##) Configure Ethernet NVIC interrupt (in Interrupt mode)

    (#) Ethernet data reception is asynchronous, so call the following API
        to start the listening mode:
        (##) HAL_ETH_Start():
             This API starts the MAC and DMA transmission and reception process,
             without enabling end of transfer interrupts, in this mode user
             has to poll for data reception by calling HAL_ETH_ReadData()
        (##) HAL_ETH_Start_IT():
             This API starts the MAC and DMA transmission and reception process,
             end of transfer interrupts are enabled in this mode,
             HAL_ETH_RxCpltCallback() will be executed when an Ethernet packet is received

    (#) When data is received user can call the following API to get received data:
        (##) HAL_ETH_ReadData(): Read a received packet

    (#) For transmission path, two APIs are available:
       (##) HAL_ETH_Transmit(): Transmit an ETH frame in blocking mode
       (##) HAL_ETH_Transmit_IT(): Transmit an ETH frame in interrupt mode,
            HAL_ETH_TxCpltCallback() will be executed when end of transfer occur

    (#) Communication with an external PHY device:
       (##) HAL_ETH_ReadPHYRegister(): Read a register from an external PHY
       (##) HAL_ETH_WritePHYRegister(): Write data to an external RHY register

    (#) Configure the Ethernet MAC after ETH peripheral initialization
        (##) HAL_ETH_GetMACConfig(): Get MAC actual configuration into ETH_MACConfigTypeDef
        (##) HAL_ETH_SetMACConfig(): Set MAC configuration based on ETH_MACConfigTypeDef

    (#) Configure the Ethernet DMA after ETH peripheral initialization
        (##) HAL_ETH_GetDMAConfig(): Get DMA actual configuration into ETH_DMAConfigTypeDef
        (##) HAL_ETH_SetDMAConfig(): Set DMA configuration based on ETH_DMAConfigTypeDef

    (#) Configure the Ethernet PTP after ETH peripheral initialization
        (##) Define HAL_ETH_USE_PTP to use PTP APIs.
        (##) HAL_ETH_PTP_GetConfig(): Get PTP actual configuration into ETH_PTP_ConfigTypeDef
        (##) HAL_ETH_PTP_SetConfig(): Set PTP configuration based on ETH_PTP_ConfigTypeDef
        (##) HAL_ETH_PTP_GetTime(): Get Seconds and Nanoseconds for the Ethernet PTP registers
        (##) HAL_ETH_PTP_SetTime(): Set Seconds and Nanoseconds for the Ethernet PTP registers
        (##) HAL_ETH_PTP_AddTimeOffset(): Add Seconds and Nanoseconds offset for the Ethernet PTP registers
        (##) HAL_ETH_PTP_InsertTxTimestamp(): Insert Timestamp in transmission
        (##) HAL_ETH_PTP_GetTxTimestamp(): Get transmission timestamp
        (##) HAL_ETH_PTP_GetRxTimestamp(): Get reception timestamp

    -@- The ARP offload feature is not supported in this driver.

    -@- The PTP offload feature is not supported in this driver.

*** Callback registration ***
=============================================

The compilation define  USE_HAL_ETH_REGISTER_CALLBACKS when set to 1
allows the user to configure dynamically the driver callbacks.
Use Function HAL_ETH_RegisterCallback() to register an interrupt callback.

Function HAL_ETH_RegisterCallback() allows to register following callbacks:
  (+) TxCpltCallback   : Tx Complete Callback.
  (+) RxCpltCallback   : Rx Complete Callback.
  (+) ErrorCallback    : Error Callback.
  (+) PMTCallback      : Power Management Callback
  (+) EEECallback      : EEE Callback.
  (+) WakeUpCallback   : Wake UP Callback
  (+) MspInitCallback  : MspInit Callback.
  (+) MspDeInitCallback: MspDeInit Callback.

This function takes as parameters the HAL peripheral handle, the Callback ID
and a pointer to the user callback function.

For specific callbacks RxAllocateCallback use dedicated register callbacks:
respectively HAL_ETH_RegisterRxAllocateCallback().

For specific callbacks RxLinkCallback use dedicated register callbacks:
respectively HAL_ETH_RegisterRxLinkCallback().

For specific callbacks TxFreeCallback use dedicated register callbacks:
respectively HAL_ETH_RegisterTxFreeCallback().

For specific callbacks TxPtpCallback use dedicated register callbacks:
respectively HAL_ETH_RegisterTxPtpCallback().

Use function HAL_ETH_UnRegisterCallback() to reset a callback to the default
weak function.
HAL_ETH_UnRegisterCallback takes as parameters the HAL peripheral handle,
and the Callback ID.
This function allows to reset following callbacks:
  (+) TxCpltCallback   : Tx Complete Callback.
  (+) RxCpltCallback   : Rx Complete Callback.
  (+) ErrorCallback    : Error Callback.
  (+) PMTCallback      : Power Management Callback
  (+) EEECallback      : EEE Callback.
  (+) WakeUpCallback   : Wake UP Callback
  (+) MspInitCallback  : MspInit Callback.
  (+) MspDeInitCallback: MspDeInit Callback.

For specific callbacks RxAllocateCallback use dedicated unregister callbacks:
respectively HAL_ETH_UnRegisterRxAllocateCallback().

For specific callbacks RxLinkCallback use dedicated unregister callbacks:
respectively HAL_ETH_UnRegisterRxLinkCallback().

For specific callbacks TxFreeCallback use dedicated unregister callbacks:
respectively HAL_ETH_UnRegisterTxFreeCallback().

For specific callbacks TxPtpCallback use dedicated unregister callbacks:
respectively HAL_ETH_UnRegisterTxPtpCallback().

By default, after the HAL_ETH_Init and when the state is HAL_ETH_STATE_RESET
all callbacks are set to the corresponding weak functions:
examples HAL_ETH_TxCpltCallback(), HAL_ETH_RxCpltCallback().
Exception done for MspInit and MspDeInit functions that are
reset to the legacy weak function in the HAL_ETH_Init/ HAL_ETH_DeInit only when
these callbacks are null (not registered beforehand).
if not, MspInit or MspDeInit are not null, the HAL_ETH_Init/ HAL_ETH_DeInit
keep and use the user MspInit/MspDeInit callbacks (registered beforehand)

Callbacks can be registered/unregistered in HAL_ETH_STATE_READY state only.
Exception done MspInit/MspDeInit that can be registered/unregistered
in HAL_ETH_STATE_READY or HAL_ETH_STATE_RESET state,
thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
In that case first register the MspInit/MspDeInit user callbacks
using HAL_ETH_RegisterCallback() before calling HAL_ETH_DeInit
or HAL_ETH_Init function.

When The compilation define USE_HAL_ETH_REGISTER_CALLBACKS is set to 0 or
not defined, the callback registration feature is not available and all callbacks
are set to the corresponding weak functions.

Definition in file stm32f4xx_hal_eth.c.