HAL ETH How to Use

group ETH_How_To_Use

The HAL ETH driver can be used as follows:

Initialization and Configuration:

• Declare a hal_eth_handle_t handle structure, for example:

    hal_eth_handle_t  heth;
  

• Set the ETH instance number to initialize in the heth handle.

• Initialize the ETH low level resources:

  • Enable the Ethernet interface clock using

    • HAL_RCC_ETH1_EnableClock()

    • HAL_RCC_ETH1TX_EnableClock()

    • HAL_RCC_ETH1RX_EnableClock()

    • HAL_RCC_ETH1CK_EnableClock()

  • Initialize the related GPIO clocks.

  • Configure Ethernet pinout.

  • Configure Ethernet NVIC interrupt (in Interrupt mode).

• Call HAL_ETH_Init() API to initialize the Ethernet peripheral (MAC, DMA, MTL and MDIO).

• Declare a hal_eth_config_t configuration structure, for example:

    hal_eth_config_t  eth_config;
  

• Set the ETH global configuration parameters in the eth_config structure. Set the MAC Address. Select the MII/RMII/RGMII interface to use.

• Call HAL_ETH_SetConfig() API to configure the Ethernet peripheral (MAC, MTL and DMA). Default MAC, MTL and DMA configurations are applied.

Channel Configuration:

• Configure and start each Rx and Tx Channel separately. The steps below apply to any Ethernet channel type (Rx or Tx).

• All HAL ETH Channel APIs take the channel identifier argument ETH Tx and Rx Channel Identifiers

• Configure and start the HAL ETH Tx/Rx Channel as follows:

  • Declare a hal_eth_tx_channel_config_t / hal_eth_rx_channel_config_t channel configuration structure, for example:

        hal_eth_tx_channel_config_t / hal_eth_rx_channel_config_t ch_config;
    

  • Call HAL_ETH_GetConfigTxChannel()/HAL_ETH_GetConfigRxChannel() API to retrieve selected Tx/Rx Channel parameters.

  • Update the ETH Tx/Rx Channel configuration parameters in the ch_config structure.

    • Set the maximum number of application buffers to be held in the DMA FIFO.

    • Update the Tx/Rx DMA Channel Configuration.

    • Update the Tx/Rx MTL Queue Configuration.

    • Update the Tx/Rx FIFO Event Configuration.

  • Call HAL_ETH_SetConfigTxChannel()/HAL_ETH_SetConfigRxChannel() API to configure the selected Tx/Rx Channel.

  • Retrieve memory allocation requirements to allocate memory for descriptors and application buffers to be used for reception and/or transmission.

    • Declare a hal_eth_channel_alloc_needs_t channel allocation info structure, for example:

            hal_eth_channel_alloc_needs_t  alloc_needs;
      

    • Call HAL_ETH_GetChannelAllocNeeds() API to retrieve selected channel allocation information.

    • Use the allocation information to start the selected channel. The information includes:

      • The minimum memory size in bytes required by the driver for the selected channel.

      • The minimum address alignment for memory to be used by the driver.

Frame Reception:

Ethernet data reception is asynchronous, so call the following API to start the listening mode for each initialized Rx Channel(s):

• HAL_ETH_StartChannel():

  • This API starts the MAC and DMA reception process. Configure the interrupt management mode and arguments.

  • Provide memory buffers to transfer the received frame data.

  • The ETH Rx Allocate Callback p_rx_allocate_cb is called to allocate buffers for reception.

• When data is received, the ETH Data Callback p_data_cb (or HAL_ETH_DataCallback) is invoked if the channel is configured in interrupt mode.

• Call the HAL_ETH_ExecDataHandler() API to get the received data (in Thread execution mode).

• The p_rx_complete_cb and p_rx_allocate_cb callbacks are called during HAL_ETH_ExecDataHandler execution to notify about a received frame and request memory for the next frame reception.

• Call HAL_ETH_ExecDataHandler() API to retrieve received data at any time in the context of the application thread.

Communication with an external PHY device:

• HAL_ETH_MDIO_UpdateClockRange(): Update the MDIO clock range.

• HAL_ETH_MDIO_SetOpAttributes(): Configure Ethernet MDIO command attributes.

• HAL_ETH_MDIO_C22ReadData(): Read a register from an external PHY using Clause 22 method.

• HAL_ETH_MDIO_C22WriteData(): Write data to an external PHY register using Clause 22 method.

• HAL_ETH_MDIO_C45ReadData(): Read a register from an external PHY using Clause 45 method.

• HAL_ETH_MDIO_C45WriteData(): Write data to an external PHY register using Clause 45 method.

• HAL_ETH_MDIO_C45ReadDataRange(): Read a range of registers from an external PHY using Clause 45 method.

• HAL_ETH_UpdateConfigLink(): Apply MAC link speed/duplex using hal_eth_link_config_t after link configuration change. It can result from auto-negotiation between PHYs, or from a manual or managed change of settings.

Advanced Ethernet Configurations:

Configure the Ethernet MAC after ETH peripheral configuration is done:

• HAL_ETH_MAC_GetConfig(): Get MAC current configuration into hal_eth_mac_config_t.

• HAL_ETH_MAC_SetConfig(): Set MAC configuration based on hal_eth_mac_config_t.

Configure the Ethernet DMA after ETH peripheral configuration is done:

• HAL_ETH_DMA_GetConfig(): Get DMA current configuration into hal_eth_dma_config_t.

• HAL_ETH_DMA_SetConfig(): Set DMA configuration based on hal_eth_dma_config_t.

Configure the Ethernet MTL after ETH peripheral configuration is done:

• HAL_ETH_MTL_GetConfig(): Get MTL current configuration into hal_eth_mtl_config_t.

• HAL_ETH_MTL_SetConfig(): Set MTL configuration based on hal_eth_mtl_config_t.

Configure ARP offload module after ETH peripheral configuration is done:

• HAL_ETH_EnableARPOffload(): Enable ARP offload.

• HAL_ETH_DisableARPOffload(): Disable ARP offload.

• HAL_ETH_IsEnabledARPOffload(): Check whether ARP offloading is enabled.

• HAL_ETH_SetARPTargetIP(): Set the ARP Target IP address.

Configure MAC power down module:

• HAL_ETH_EnterPowerDownMode(): Enter the Power down mode.

• HAL_ETH_ExitPowerDownMode(): Exit from the Power down mode.

• HAL_ETH_SetRemoteWakeUpPcktFilter(): Set the Remote WakeUp filter.

Configure Energy Efficient Ethernet module:

• HAL_ETH_EnterLPIMode(): Enter the Low Power Idle (LPI) mode.

• HAL_ETH_ExitLPIMode(): Exit the Low Power Idle (LPI) mode.

Callback registration:

The ETH HAL driver supports two distinct sets of callbacks:

1. Mandatory callbacks Register these callbacks in the application. These callbacks are not delimited by the USE_HAL_ETH_REGISTER_CALLBACKS compilation flag and have no weak default implementations.

2. Optional callbacks These callbacks are delimited by the USE_HAL_ETH_REGISTER_CALLBACKS compilation flag and are optional. When this flag is enabled, the integration can override the default weak implementations by registering its own callbacks.

By default, after a call to HAL_ETH_Init() and while the state is HAL_ETH_STATE_INIT, all callbacks that provide weak default implementations are mapped to their corresponding weak functions (for example HAL_ETH_ErrorCallback() , HAL_ETH_WakeUpCallback() ).

Register or unregister callbacks only when the driver is in HAL_ETH_STATE_CONFIGURED state.

If USE_HAL_ETH_REGISTER_CALLBACKS is set to 0 or not defined, the callback registration mechanism (for the callbacks guarded by this compile switch) is disabled and these callbacks remain bound to their weak implementations.

Note: The following channel-related callbacks do not have weak default implementations and their registration is therefore mandatory:

• HAL_ETH_RegisterChannelRxAllocateCallback()

• HAL_ETH_RegisterChannelRxCptCallback()

• HAL_ETH_RegisterChannelTxCptCallback()

Their implementation is not delimited by the USE_HAL_ETH_REGISTER_CALLBACKS compilation flag. Register appropriate callbacks for each used channel.

The HAL ETH driver provides the following callback registration functions:

• HAL_ETH_RegisterChannelRxAllocateCallback(): Register RX buffer allocation callback for a specific channel (mandatory, no weak default).

• HAL_ETH_RegisterChannelRxCptCallback(): Register RX complete callback for a specific channel (mandatory, no weak default).

• HAL_ETH_RegisterChannelTxCptCallback(): Register TX complete callback for a specific channel (mandatory, no weak default).

• HAL_ETH_RegisterDataCallback(): Register data transfer/processing callback.

• HAL_ETH_RegisterWKUPCallback(): Register Ethernet wake-up (power management) callback.

• HAL_ETH_RegisterPMTCallback(): Register Power Management Trigger (PMT) callback.

• HAL_ETH_RegisterEEECallback(): Register Energy Efficient Ethernet (EEE) callback.

• HAL_ETH_RegisterErrorCallback(): Register error notification callback.

• HAL_ETH_RegisterEventCallback(): Register generic Ethernet event callback.

• HAL_ETH_RegisterCacheInvalidateCallback(): Register cache invalidate operation callback.

• HAL_ETH_RegisterCacheFlushCallback(): Register cache flush operation callback.

• HAL_ETH_RegisterChannelRxEventCallback(): Register generic RX event callback for a specific channel.

• HAL_ETH_RegisterChannelTxEventCallback(): Register generic TX event callback for a specific channel.

HAL ETH Driver State and Errors:

• Use HAL_ETH_GetState() function to return the global HAL ETH driver state.

• Use HAL_ETH_GetChannelState() function to return the state of a specific ETH channel.

• When enabled, use HAL_ETH_GetLastErrorCodes() to retrieve the last recorded ETH error codes.

If the compilation flag USE_HAL_ETH_GET_LAST_ERRORS is set to 1, the function HAL_ETH_GetLastErrorCodes() is available and allows the application to read back the last error codes recorded internally by the ETH driver.

If USE_HAL_ETH_GET_LAST_ERRORS is set to 0 or not defined, this function is not compiled and the last error history feature is not available.

Note

Ensure buffer(s) respect memory allocation requirements (alignment) provided by HAL_ETH_GetChannelAllocNeeds() API call.

Note

Do not call any blocking service(s) while running in handler execution mode.

Note

Do not call HAL_ETH_ExecDataHandler() API in the Handler execution mode. This breaks driver behaviour. Implement a dedicated worker thread and trigger it to retrieve the received data (in Thread execution mode).