HAL ETH Use Cases ¶

ETH Initialization ¶

$@startuml hide footbox !pragma teoz true <style> box { LineColor transparent LineThickness 5 BackgroundColor #APPLICATION .system_boundary { LineColor #6b254b LineThickness 3 LineStyle 5-5 FontColor #6b254b BackgroundColor transparent BorderColor #6b254b } } </style> skinparam sequencebox<<container_boundary>> { FontColor #d7a538 BackgroundColor transparent BorderColor #d7a538 BorderStyle dashed } title ETH Peripheral Initialization !$APP_COLOR = " #fff4bf" !$GLUE_COLOR = " #ceecf9" !$POOL_COLOR = " #e9c0f5" !$HW_COLOR = " #E6007E" participant "Application" as Application $APP_COLOR box HAL System Peripheral Drivers #cfdbf3 participant "HAL Core" as STM32_HAL participant "RCC HAL" as RCC_HAL participant "GPIO HAL" as GPIO_HAL end box box Ethernet Network Interface #EEEFF1 participant "Tx Buffer Pool" as TX_POOL $POOL_COLOR participant "Rx Buffer Pool" as RX_POOL $POOL_COLOR participant "ETH Memory Pool" as ETH_MEM_POOL $POOL_COLOR participant "Applicative glue" as APP_GLUE $GLUE_COLOR control "Ethernet Process" as ETH_PROC $GLUE_COLOR participant "Messages Queue" as WT_QUEUE $POOL_COLOR end box participant "Ethernet HAL" as ETH_HAL << Peripheral driver >> control "Ethernet HW" as ETH_HW << Ethernet hardware >> participant "External PHY driver" as PHY_DRV << Part driver >> alt Main Initialization [-> Application++ $APP_COLOR: //User::AppInit()//\nMain Application Initialization. end ' =================================================================== == System Initialization == ' =================================================================== Application -> STM32_HAL++ $APP_COLOR: HAL Initialization HAL_Init() note right of STM32_HAL #Yellow Initialize System Time Base end note return success or failure Application -> RCC_HAL++ $APP_COLOR: System and Peripherals Clock Configurations note right of RCC_HAL #Yellow Configure System and Peripherals Clocks end note return success or failure Application -> PHY_DRV++ $APP_COLOR: Initialize PHY lan8742_init() return success or failure ' =================================================================== == ETH Peripheral Instance (eth_instance) Initialization == ' =================================================================== alt "Ethernet Clocks Enabling If USE_ETH_CLK_ENABLE_MODEL = HAL_CLK_ENABLE_NO" note right of Application #Yellow if USE_ETH_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO - Enable ETH Clocks - Enable ETH GPIOs Clocks end note Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1_EnableClock() return success or failure Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1TX_EnableClock() return success or failure Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1RX_EnableClock() return success or failure Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1CK_EnableClock() return success or failure end Application -> RCC_HAL++ $APP_COLOR: Enable ETH GPIO clocks: HAL_RCC_GPIO<x>_EnableClock() return success or failure Application -> GPIO_HAL++ $APP_COLOR: Initialize ETH GPIO Pins: HAL_GPIO_Init() return success or failure Application -> ETH_HAL++ $APP_COLOR: Initialize the HAL ETH: HAL_ETH_Init(eth_instance) return success or failure Application -> APP_GLUE++ $APP_COLOR: Initialize the Ethernet Network Interface : EthInit(p_eth_handler) APP_GLUE -> ETH_MEM_POOL++ $APP_COLOR: Driver Memory Pool Initialization MemPoolInit() return success or failure APP_GLUE -> TX_POOL++ $APP_COLOR: Tx Memory Pool Initialization TxPoolInit() return success or failure APP_GLUE -> RX_POOL++ $APP_COLOR: Rx Memory Pool Initialization RxPoolInit() return success or failure APP_GLUE -> ETH_HAL++ $APP_COLOR: Register Data callback : HAL_ETH_RegisterDataCallback(\n p_eth_handler, data_callback) return success or failure return success or failure @enduml$

Called functions:

HAL_ETH_Init()

ETH De-initialization ¶

$@startuml hide footbox !pragma teoz true <style> box { LineColor transparent LineThickness 5 BackgroundColor #APPLICATION .system_boundary { LineColor #6b254b LineThickness 3 LineStyle 5-5 FontColor #6b254b BackgroundColor transparent BorderColor #6b254b } } </style> skinparam sequencebox<<container_boundary>> { FontColor #d7a538 BackgroundColor transparent BorderColor #d7a538 BorderStyle dashed } title ETH Peripheral De-Initialization !$APP_COLOR = " #fff4bf" !$GLUE_COLOR = " #ceecf9" !$POOL_COLOR = " #e9c0f5" !$HW_COLOR = " #E6007E" participant "Application" as Application $APP_COLOR box HAL System Peripheral Drivers #cfdbf3 participant "HAL Core" as STM32_HAL participant "RCC HAL" as RCC_HAL participant "GPIO HAL" as GPIO_HAL end box box Ethernet Network Interface #EEEFF1 participant "Tx Buffer Pool" as TX_POOL $POOL_COLOR participant "Rx Buffer Pool" as RX_POOL $POOL_COLOR participant "ETH Memory Pool" as ETH_MEM_POOL $POOL_COLOR participant "Applicative glue" as APP_GLUE $GLUE_COLOR control "Ethernet Process" as ETH_PROC $GLUE_COLOR participant "Messages Queue" as WT_QUEUE $POOL_COLOR end box participant "Ethernet HAL" as ETH_HAL << Peripheral driver >> control "Ethernet HW" as ETH_HW << Ethernet hardware >> participant "External PHY driver" as PHY_DRV << Part driver >> alt Main De-Initialization [-> Application++ $APP_COLOR: //User::AppDeInit()//\nMain Application De-Initialization. end ' =================================================================== == ETH Network Interface De-Initialization == ' =================================================================== Application -> APP_GLUE++ $APP_COLOR: De-initialize the Ethernet Network Interface: EthDeInit(p_eth_handler) note right of APP_GLUE #Yellow All Used ETH Channels should be stopped end note APP_GLUE -> ETH_MEM_POOL++ $APP_COLOR: Driver Memory Pool De-Initialization: MemPoolDeInit() return success or failure APP_GLUE -> TX_POOL++ $APP_COLOR: Tx Memory Pool De-Initialization: TxPoolDeInit() return success or failure APP_GLUE -> RX_POOL++ $APP_COLOR: Rx Memory Pool De-Initialization: RxPoolDeInit() return success or failure return success or failure ' =================================================================== == ETH Peripheral Instance (eth_instance) De-Initialization == ' =================================================================== Application -> ETH_HAL++ $APP_COLOR: De-initialize the HAL ETH: HAL_ETH_DeInit(eth_instance) return success or failure alt "Ethernet Clocks Disabling If USE_ETH_CLK_ENABLE_MODEL = HAL_CLK_ENABLE_NO" note right of Application #Yellow if USE_ETH_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO - Disable ETH Clocks - Disable ETH GPIOs Clocks end note Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1_DisableClock() return success or failure Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1TX_DisableClock() return success or failure Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1RX_DisableClock() return success or failure Application -> RCC_HAL++ $APP_COLOR : HAL_RCC_ETH1CK_DisableClock() return success or failure end Application -> GPIO_HAL++ $APP_COLOR: De-initialize ETH GPIO Pins: HAL_GPIO_DeInit() return success or failure Application -> RCC_HAL++ $APP_COLOR: Disable ETH GPIO clocks: HAL_RCC_GPIO<x>_DisableClock() return success or failure ' =================================================================== == System De-Initialization == ' =================================================================== Application -> PHY_DRV++ $APP_COLOR: De-initialize PHY lan8742_deinit() return success or failure Application -> RCC_HAL++ $APP_COLOR: System and Peripherals Clock Reset note right of RCC_HAL #Yellow Reset System and Peripherals Clocks end note return success or failure Application -> STM32_HAL++ $APP_COLOR: HAL De-Initialization HAL_DeInit() note right of STM32_HAL #Yellow De-Initialize System Time Base end note return success or failure @enduml$

Called functions:

HAL_ETH_DeInit()

ETH Peripheral Configuration ¶

$@startuml hide footbox !pragma teoz true <style> box { LineColor transparent LineThickness 5 BackgroundColor #APPLICATION .system_boundary { LineColor #6b254b LineThickness 3 LineStyle 5-5 FontColor #6b254b BackgroundColor transparent BorderColor #6b254b } } </style> skinparam sequencebox<<container_boundary>> { FontColor #d7a538 BackgroundColor transparent BorderColor #d7a538 BorderStyle dashed } title Ethernet Peripheral Configuration !$APP_COLOR = " #fff4bf" !$GLUE_COLOR = " #ceecf9" !$POOL_COLOR = " #e9c0f5" !$HW_COLOR = " #E6007E" participant "Application" as Application $APP_COLOR box Ethernet Network Interface #EEEFF1 participant "Tx Buffer Pool" as TX_POOL $POOL_COLOR participant "Rx Buffer Pool" as RX_POOL $POOL_COLOR participant "ETH Memory Pool" as ETH_MEM_POOL $POOL_COLOR participant "Applicative glue" as APP_GLUE $GLUE_COLOR control "Ethernet Process" as ETH_PROC $GLUE_COLOR participant "Messages Queue" as WT_QUEUE $POOL_COLOR end box participant "Ethernet HAL" as ETH_HAL << Peripheral driver >> control "Ethernet HW" as ETH_HW << Ethernet hardware >> alt Request for Frame Transmission [-> Application++ $APP_COLOR: //User::SetEthConfig(mac_addr, media_interface)//\nConfigure the Ethernet peripheral. end ' =================================================================== == Basic Ethernet Peripheral Configuration == ' =================================================================== note over Application Setup ETH Peripheral Configuration - eth_config.mac_addr = mac_addr - eth_config.media_interface = media_interface end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_SetConfig(p_eth_handler, &eth_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Write Global Configuration\n to hardware return return success or failure ' =================================================================== == Advanced Ethernet Peripheral Configuration == ' =================================================================== group Advenced : ETH MAC Configuration note over Application Get current ETH MAC Configuration (Default) end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_MAC_GetConfig(p_eth_handler, &eth_mac_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Read MAC Configuration\n from hardware return return success or failure note over Application Setup ETH MAC Configuration - Update eth_mac_config fields i.e : - eth_mac_config.link_config.speed = HAL_ETH_MAC_SPEED_100M - eth_mac_config.loopback_mode = HAL_ETH_MAC_LOOPBACK_ENABLE end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_MAC_SetConfig(p_eth_handler, &eth_mac_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Write ETH MAC Configuration\n to hardware return return success or failure end group group Advenced : ETH MTL Configuration note over Application Get current ETH MTL Configuration (Default) end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_MTL_GetConfig(p_eth_handler, &eth_mtl_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Read MTL Configuration\n from hardware return return success or failure note over Application Setup ETH MTL Configuration - Update eth_mtl_config fields i.e : - eth_mtl_config.tx_fwd_status = HAL_ETH_MTL_TX_FWD_STATUS_DISABLE end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_MTL_SetConfig(p_eth_handler, &eth_mtl_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Write ETH MTL Configuration\n to hardware return return success or failure end group group Advenced : ETH DMA Configuration note over Application Get current ETH DMA Configuration (Default) end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_DMA_GetConfig(p_eth_handler, &eth_dma_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Read DMA Configuration\n from hardware return return success or failure note over Application Setup ETH DMA Configuration - Update eth_dma_config fields i.e : - eth_dma_config.burst_mode = HAL_ETH_DMA_BURST_LEN_FIXED - eth_dma_config.tr_priority = HAL_ETH_DMA_TR_PRIO_ENABLE end note Application -> ETH_HAL++ $APP_COLOR : HAL_ETH_DMA_SetConfig(p_eth_handler, &eth_mtl_config) ETH_HAL -> ETH_HW++ $APP_COLOR: Write ETH DMA Configuration\n to hardware return return success or failure end group @enduml$

Called functions:

ETH Tx Channel Configuration ¶

Called functions:

ETH Rx Channel Configuration ¶

Called functions:

ETH Start Rx/Tx Channel(s) ¶

Called functions:

ETH Stop Rx/Tx Channel(s) ¶

Called functions:

HAL_ETH_StopChannel()

ETH Rx/Tx Processing ¶

$@startuml hide footbox !pragma teoz true <style> box { LineColor transparent LineThickness 5 BackgroundColor #APPLICATION .system_boundary { LineColor #6b254b LineThickness 3 LineStyle 5-5 FontColor #6b254b BackgroundColor transparent BorderColor #6b254b } } </style> skinparam sequencebox<<container_boundary>> { FontColor #d7a538 BackgroundColor transparent BorderColor #d7a538 BorderStyle dashed } title Ethernet Rx/Tx Processing !$APP_COLOR = " #fff4bf" !$GLUE_COLOR = " #ceecf9" !$POOL_COLOR = " #e9c0f5" !$HW_COLOR = " #E6007E" participant "Application" as Application $APP_COLOR box Ethernet Network Interface #EEEFF1 participant "Tx Buffer Pool" as TX_POOL $POOL_COLOR participant "Rx Buffer Pool" as RX_POOL $POOL_COLOR participant "ETH Memory Pool" as ETH_MEM_POOL $POOL_COLOR participant "Applicative glue" as APP_GLUE $GLUE_COLOR control "Ethernet Process" as ETH_PROC $GLUE_COLOR participant "Messages Queue" as WT_QUEUE $POOL_COLOR end box participant "Ethernet HAL" as ETH_HAL << Peripheral driver >> control "Ethernet HW" as ETH_HW << Ethernet hardware >> alt Request for Frame Transmission [-> Application++ $APP_COLOR: //User::SendFrame(channel_id)//\nTransmit a frame on the specified\nchannel_id end ' =================================================================== == Frame Transmission == ' =================================================================== Application -> Application: Frame processing Application -> APP_GLUE++ $APP_COLOR: Request for Frame Transmission APP_GLUE -> TX_POOL++ $APP_COLOR: Request memory from Tx Pool (buffer) return APP_GLUE -> APP_GLUE: Transmit Request configuration APP_GLUE -> ETH_HAL++ $APP_COLOR: **HAL_ETH_RequestTx**(channel_id) ETH_HAL -> ETH_HW++ $APP_COLOR: Submit Request\n to hardware return return return deactivate Application alt [-> Application++ $APP_COLOR: //MainApp::ReceiveFrame(channel_id)//\nReceive an incoming frame on the\nspecified channel_id end ' =================================================================== == Frame Reception == ' =================================================================== Application -> APP_GLUE++ $APP_COLOR: Get a Received Frame APP_GLUE -> RX_POOL++ $APP_COLOR: Get a Frame from Rx FIFO return return Application -> Application $APP_COLOR: Frame processing Application -> APP_GLUE++ $APP_COLOR: Release to pool (buffer) APP_GLUE -> RX_POOL++ $APP_COLOR: Release Frame in Rx FIFO return return deactivate Application ' =================================================================== == Hardware Event(s) == ' =================================================================== ETH_HW ->> ETH_HAL++ $HW_COLOR: **HAL_ETH_IRQHandler**() ETH_HAL -> ETH_HAL: Clear IT ETH_HAL -> APP_GLUE++ $HW_COLOR: **p_data_cb**(set of channels with pending SW operations) APP_GLUE ->> WT_QUEUE++ $HW_COLOR: queue message (data event id + channel(s) mask) return APP_GLUE --> ETH_HAL deactivate ETH_HAL deactivate APP_GLUE alt Worker Thread [-> ETH_PROC++ $GLUE_COLOR: //OS::Scheduler()//\nWorker Thread scheduled for execution end ' =================================================================== == Rx/Tx Frame(s) Processing == ' =================================================================== ETH_PROC -> WT_QUEUE++ $GLUE_COLOR: dequeue messages (data event id + channel(s) mask) return ETH_PROC -> ETH_HAL++ $GLUE_COLOR: **HAL_ETH_ExecDataHandler**(in: set of channels selected by appli for processing,\n out: set of channels with pending SW operations) loop For each TX channel in the set (decreasing priority order) loop For each descriptor with completed transmission ETH_HAL -> APP_GLUE++ $GLUE_COLOR: **p_tx_complete_cb**(channel, buffer, <metadata>) APP_GLUE -> TX_POOL++ $GLUE_COLOR: Release to pool (buffer) return return end end loop For each RX channel in the set (decreasing priority order) loop For each descriptor with completed reception ETH_HAL -> APP_GLUE++ $GLUE_COLOR: **p_rx_complete_cb**(channel, buffer, size, <metadata>) APP_GLUE ->> RX_POOL++ $GLUE_COLOR: Put received buffer in Rx FIFO note over RX_POOL The buffer remains referenced until the payload is consumed by the user application. end note return APP_GLUE --> ETH_HAL deactivate APP_GLUE alt New Frame Received (Optional) [<- APP_GLUE++ $GLUE_COLOR: //OS::Notify()//\nNotify Application about the reception\nof a new Frame return deactivate APP_GLUE end ETH_HAL -> APP_GLUE++ $GLUE_COLOR: **p_rx_allocate_cb**(channel, buffer, size) APP_GLUE -> RX_POOL++ $GLUE_COLOR: Get new buffer from RX FIFO note over RX_POOL The memory allocation is done by the application. If no more memory the rx_allocate_cp should return error to the callee. end note return return return deactivate ETH_HAL deactivate ETH_PROC end end @enduml$

Called functions: