HAL I3C Use Cases ¶

Build Controller CCC Transfer Context ¶

$@startuml note over App : Building transfer context is a 100% software process. It can be performed at any time and does not depend on any I3C instance or driver handle. participant App as "User application" participant "HAL I3C" as I3C == Build a controller CCC transfer context\n== App -> I3C : HAL_I3C_CTRL_ResetTransferCtx(ctx) App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_InitTransferCtxTc(ctx, ctrl_buf) App <-- I3C : HAL_OK alt If Tx transfer in usecase App -> I3C : HAL_I3C_CTRL_InitTransferCtxTx(ctx, tx_concatenated_buf) App <-- I3C : HAL_OK end alt If Rx transfer in usecase App -> I3C : HAL_I3C_CTRL_InitTransferCtxRx(ctx, rx_concatenated_buf) App <-- I3C : HAL_OK end App -> I3C : HAL_I3C_CTRL_BuildTransferCtxCCC(ctx) App <-- I3C : HAL_OK @enduml$

Called functions:

Build Controller Private Transfer Context ¶

$@startuml note over App : Building transfer context is a 100% software process. It can be performed at any time and does not depend on any I3C instance or driver handle. participant App as "User application" participant "HAL I3C" as I3C == Build a controller Private transfer context\n== App -> I3C : HAL_I3C_CTRL_ResetTransferCtx(ctx) App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_InitTransferCtxTc(ctx, ctrl_buf) App <-- I3C : HAL_OK alt If Tx transfer in usecase App -> I3C : HAL_I3C_CTRL_InitTransferCtxTx(ctx, tx_concatenated_buf) App <-- I3C : HAL_OK end alt If Rx transfer in usecase App -> I3C : HAL_I3C_CTRL_InitTransferCtxRx(ctx, rx_concatenated_buf) App <-- I3C : HAL_OK end App -> I3C : HAL_I3C_CTRL_BuildTransferCtxPrivate(ctx) App <-- I3C : HAL_OK @enduml$

Called functions:

Prerequisite ¶

@startuml
==Prerequisite==

participant App as "User application"
participant "HAL GENERIC" as GENERIC
participant "HAL RCC" as RCC

App -> GENERIC : HAL_Init
GENERIC --> App
App -> RCC : Configure system clock
RCC --> App
@enduml

I3C Controller Initialization ¶

$@startuml participant App as "User controller application" participant "HAL I3C" as I3C participant "HAL CORTEX\n(NVIC)" as CORTEX participant "HAL DMA" as DMA participant "HAL RCC" as RCC participant "HAL GPIO" as GPIO ==I3C HAL Initialization == App -> I3C : HAL_I3C_Init alt#grey #lightgrey If USE_HAL_I3C_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO I3C->RCC : Enable the I3C clock RCC-->I3C end note over App : Driver state = HAL_I3C_STATE_INIT\n App <-- I3C : HAL_OK ==I3C System Initialization== Note over I3C : I3C System initialization can be called before\nI3C HAL initialization alt#grey #lightgrey If USE_HAL_I3C_DMA == 1 App->DMA : Initialization of DMA DMA-->App App->I3C : HAL_I3C_SetTxDMA() / HAL_I3C_SetRxDMA() DMA-->App end alt#grey #lightgrey If Interrupt needed App->CORTEX : Enable needed Interrupt CORTEX-->App end alt#grey #lightgrey If GPIO(s) needed App->GPIO : Initialization of GPIOs GPIO-->App end alt#grey #lightgrey If USE_HAL_I3C_CLK_ENABLE_MODEL == HAL_CLK_ENABLE_NO App->RCC : Enable the I3C clock RCC --> App end ==I3C controller configuration== App -> I3C : HAL_I3C_CTRL_SetConfig() App <-- I3C :HAL_OK note over App : Driver state = HAL_I3C_STATE_IDLE\nUser can start any process or execute any configuration. ==Advanced I3C controller configuration== App -> I3C : HAL_I3C_CTRL_SetConfigXXX() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_CTRL_EnableXXX() App <-- I3C :HAL_OK ==I3C controller notifications activation== App -> I3C : HAL_I3C_CTRL_ActivateNotification() App <-- I3C :HAL_OK @enduml$

Called functions:

I3C Target Initialization ¶

$@startuml participant App as "User target application" participant "HAL I3C" as I3C participant "HAL CORTEX\n(NVIC)" as CORTEX participant "HAL DMA" as DMA participant "HAL RCC" as RCC participant "HAL GPIO" as GPIO ==I3C HAL Initialization == App -> I3C : HAL_I3C_Init alt#grey #lightgrey If USE_HAL_I3C_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO I3C->RCC : Enable the I3C clock RCC-->I3C end note over App : Driver state = HAL_I3C_STATE_INIT\n App <-- I3C : HAL_OK ==I3C system initialization== Note over I3C : I3C System initialization can be called before\nI3C HAL initialization alt#grey #lightgrey If USE_HAL_I3C_DMA == 1 App->DMA : Initialization of DMA DMA-->App App->I3C : HAL_I3C_SetTxDMA() / HAL_I3C_SetRxDMA() DMA-->App end alt#grey #lightgrey If Interrupt needed App->CORTEX : Enable needed Interrupt CORTEX-->App end alt#grey #lightgrey If GPIO(s) needed App->GPIO : Initialization of GPIOs GPIO-->App end alt#grey #lightgrey If USE_HAL_I3C_CLK_ENABLE_MODEL == HAL_CLK_ENABLE_NO App->RCC : Enable the I3C clock RCC --> App end ==I3C target configuration== App -> I3C : HAL_I3C_TGT_SetConfig() App <-- I3C :HAL_OK note over App : Driver state = HAL_I3C_STATE_IDLE\nUser can start any process or execute any configuration. ==Advanced I3C target configuration== App -> I3C : HAL_I3C_TGT_SetConfigFifo() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_EnableGroupAddrCapability() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_SetPayloadENTDAAConfig() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_SetConfigCtrlRole() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_EnableCtrlRoleRequest() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_EnableHotJoinRequest() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_SetConfigIBI() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_EnableIBI() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_SetConfigMaxDataSize() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_SetConfigGETMXDS() App <-- I3C :HAL_OK App -> I3C : HAL_I3C_TGT_SetConfigCtrlHandOffActivity() App <-- I3C :HAL_OK ==I3C target notifications activation== App -> I3C : HAL_I3C_TGT_ActivateNotification() App <-- I3C :HAL_OK @enduml$

Called functions:

I3C Deinitialization Sequence ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C participant "HAL CORTEX\n(NVIC)" as CORTEX participant "HAL DMA" as DMA participant "HAL RCC" as RCC participant "HAL GPIO" as GPIO ==I3C deInitialisation== App->I3C : HAL_I3C_DeInit App<--I3C ==I3C system deInitalization== alt#grey #lightgrey If USE_HAL_I3C_DMA == 1 App->DMA : DeInitialization of DMA DMA-->App end alt#grey #lightgrey If Interrupt needed App->CORTEX : Disable needed Interrupt CORTEX-->App end alt#grey #lightgrey If GPIO(s) needed App->GPIO : DeInitialization of GPIOs GPIO-->App end App->RCC : Disable the I3C clock RCC --> App @enduml$

Called functions:

HAL_I3C_DeInit()

Process Controller Dynamic Address Assignment ¶

$@startuml participant App as "User controller application" participant "HAL I3C" as I3C ==Process : Controller Dynamic Address Assign (IT)\n== note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_CTRL_DynAddrAssign_IT note over App : Driver state = HAL_I3C_STATE_DAA\n App <-- I3C : HAL_OK ... loop while (all devices) "I3Cx_IRQHandler" <- : I3Cx interrupt RXFNEF "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() I3C <- I3C: DAA process "I3Cx_IRQHandler" <- : I3Cx interrupt TXFNFF "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() App <- I3C : HAL_I3C_CTRL_TgtReqDynAddrCallback() App --> I3C : HAL_I3C_CTRL_SetDynAddr() App <-- I3C : HAL_OK end "I3Cx_IRQHandler" <- : I3Cx interrupt FC "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() note over App : Driver state = HAL_I3C_STATE_IDLE\n App <- I3C : HAL_I3C_CTRL_DAACpltCallback() App -> I3C : HAL_I3C_CTRL_SetConfigBusDevices() App <-- I3C : HAL_OK @enduml$

Called functions:

Process Controller CCC/Private Transfer ¶

Called functions:

HAL_I3C_CTRL_Transfer()

Process Controller CCC/Private Transfer IT ¶

$@startuml participant App as "User controller application" participant "HAL I3C" as I3C ==Process : Controller CCC or private multiple transfer IT\n== note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_CTRL_Transfer_IT(built CCC ctx or built private ctx) note over App : Driver state = HAL_I3C_STATE_TX_RX\n App <-- I3C : HAL_OK ... loop while (ctrl_count-- != 0) I3C --> "I3Cx_IRQHandler" "I3Cx_IRQHandler" --> "I3Cx_IRQHandler" <- : I3Cx interrupt CFNF, CR 1 ... CR N "I3Cx_IRQHandler" <- : I3Cx interrupt TXFNF, Byte 1 ... Byte N "I3Cx_IRQHandler" <- : I3Cx interrupt RXFNF, Byte 1 ... Byte N I3C <- "I3Cx_IRQHandler" : HAL_I3C_EV_IRQHandler() note over I3C : I3C_Ctrl_Multiple_Xfer_ISR() alt if (ctrl_count > 0) note over I3C : ctrl_func() end alt if (tx_xfer_count > 0) note over I3C : tx_func() end alt if (rx_xfer_count > 0) note over I3C : rx_func() end I3C --> "I3Cx_IRQHandler" "I3Cx_IRQHandler" --> "I3Cx_IRQHandler" <- : I3Cx interrupt FC I3C <- "I3Cx_IRQHandler" : HAL_I3C_EV_IRQHandler() note over I3C : I3C_Ctrl_Multiple_Xfer_ISR() alt if (ctrl_count == 0) note over I3C : Disable_IRQ() note over App : Driver state = HAL_I3C_STATE_IDLE App <- I3C : HAL_I3C_CTRL_TransferCpltCallback() else if (ctrl_count != 0) note over I3C : Initiate a Start condition end end I3C --> "I3Cx_IRQHandler" "I3Cx_IRQHandler" --> @enduml$

Called functions:

Process Controller CCC/Private Transfer DMA ¶

$@startuml participant App as "User controller application" participant "HAL I3C" as I3C participant App participant I3C participant "I3Cx_IRQHandler" participant "HAL DMA driver" participant "DMAx_IRQHandler" ==Process : Controller CCC or private multiple transfer DMA\n== note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_CTRL_Transfer_DMA(built CCC ctx or built private ctx) I3C-> "HAL DMA driver" : HAL_DMA_Start_IT(dma_cr) "HAL DMA driver" --> I3C : HAL_OK I3C-> "HAL DMA driver" : HAL_DMA_Start_IT(dma_tx) "HAL DMA driver" --> I3C : HAL_OK I3C-> "HAL DMA driver" : HAL_DMA_Start_IT(dma_rx) "HAL DMA driver" --> I3C : HAL_OK note over App : Driver state = HAL_I3C_STATE_TX_RX\n App <-- I3C : HAL_OK ... "DMAx_IRQHandler" <- : DMAx complete interrupt "DMAx_IRQHandler" -> "HAL DMA driver" : HAL_DMA_IRQHandler() "HAL DMA driver" -> I3C : XferCpltCallback() "HAL DMA driver" <-- I3C "DMAx_IRQHandler" <-- "HAL DMA driver" "DMAx_IRQHandler" --> "I3Cx_IRQHandler" <- : I3Cx interrupt FC "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() note over App : Driver state = HAL_I3C_STATE_INIT\n I3C-> App : HAL_I3C_CTRL_TransferCpltCallback() I3C<-- App "I3Cx_IRQHandler" <-- I3C "I3Cx_IRQHandler" --> @enduml$

Called functions:

Controller Control-Role Switch to Target ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process : Controller control-role switch to target (IT)\n== App -> I3C : HAL_I3C_Init() App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_SetConfig() App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_ActivateNotification(HAL_I3C_CTRL_NOTIFICATION_CR) App <-- I3C : HAL_OK note over App : Activate controller-role request event "I3Cx_IRQHandler" <- : I3Cx interrupt CRF "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler I3C <- I3C: Control role request process App <- I3C : HAL_I3C_NotifyCallback() App -> I3C : HAL_I3C_GetCCCInfo() App <-- I3C : HAL_OK note over App : Receive GETACCCR App -> I3C : HAL_I3C_CTRL_BuildTransferCtxCCC() App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_Transfer() App <-- I3C : HAL_OK note over App : Switch to target App -> I3C : HAL_I3C_TGT_SetConfig() note over App : Driver state = HAL_I3C_STATE_INIT\n App <-- I3C : HAL_OK @enduml$

Called functions:

Controller Hot-Join ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process : Controller hot join (IT)\n== App -> I3C : HAL_I3C_Init() App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_SetConfig() App <-- I3C : HAL_OK App -> I3C : HAL_I3C_CTRL_ActivateNotification(HAL_I3C_CTRL_NOTIFICATION_HJ) App <-- I3C : HAL_OK note over App : Activate controller-role request event ... "I3Cx_IRQHandler" <- : I3Cx interrupt HJF "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() App <- I3C : HAL_I3C_NotifyCallback() note over App : Next step, see "Process controller Dynamic Address Assignement" (HAL_I3C_CTRL_DynAddrAssign_IT)\n App <-- I3C : HAL_OK @enduml$

Called functions:

Target Process When Controller Assign Dynamic Address ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process : Target control-role switch to controller (IT)\n== note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_TGT_ActivateNotification(HAL_I3C_TGT_NOTIFICATION_DAU) App <-- I3C : HAL_OK ... "I3Cx_IRQHandler" <- : I3Cx interrupt DAUPD "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() App <- I3C : HAL_I3C_NotifyCallback(HAL_I3C_TGT_NOTIFICATION_DAU) App -> I3C : HAL_I3C_GetCCCInfo(HAL_I3C_TGT_NOTIFICATION_DAU, &dynamic_address) App <-- I3C : HAL_OK @enduml$

Called functions:

Target Control-Role Switch to Controller ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process : Target control-role switch to controller (IT)\n== note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_TGT_ControlRoleReq_IT() App <-- I3C : HAL_OK "I3Cx_IRQHandler" <- : I3Cx interrupt CRUPDF "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() I3C <- I3C: Control role request process App <- I3C : HAL_I3C_NotifyCallback() note over App : Switch to controller App -> I3C : HAL_I3C_CTRL_SetConfig() note over App : Driver state = HAL_I3C_STATE_INIT\n App <-- I3C : HAL_OK @enduml$

Called functions:

Target Hot Join ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process : Target Hot join (IT)\n== note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_TGT_HotJoinReq_IT() note over App : Driver state = HAL_I3C_STATE_TGT_REQ\n App <-- I3C : HAL_OK "I3Cx_IRQHandler" <- : I3Cx interrupt DAUPDF "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() note over App : Driver state = HAL_I3C_STATE_INIT\n App <- I3C : HAL_I3C_TGT_HotJoinCallback(dynamic_address) @enduml$

Called functions:

Process Target Tx IT ¶

$@startuml ==Process : Target transfer transmit(tx) IT== participant App as "User application" participant "HAL I3C" as I3C note over App : Driver state must be HAL_I3C_STATE_IDLE\n App -> I3C : HAL_I3C_TGT_Transmit_IT(handle, addr, &buffer,\n size_in_byte = N) App <-- I3C : HAL_OK loop while (size-- != 0) "I3Cx_IRQHandler" <- : I3Cx interrupt TXFNFF, Byte 1 ... Byte N I3C <- "I3Cx_IRQHandler" : HAL_I3C_EV_IRQHandler note over I3C : I3C_Tgt_Tx_ISR() alt if (tx_count> 0) note over I3C : p_tx_func() end I3C --> "I3Cx_IRQHandler" "I3Cx_IRQHandler" --> end ... "I3Cx_IRQHandler" <- : I3Cx interrupt FC "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() note over I3C : Clear Frame Complete note over App : Driver state = HAL_I3C_STATE_IDLE\n App <- I3C : HAL_I3C_TGT_TxCpltCallback() App --> I3C "I3Cx_IRQHandler" <-- I3C "I3Cx_IRQHandler" --> @enduml$

Called functions:

Target Transfer Receive Rx IT ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process : Target transfer Rx IT== App -> I3C : HAL_I3C_TGT_Receive_IT(handle, addr, &buffer,\n size_in_byte = N) App <-- I3C : HAL_OK ... loop while (size-- != 0) "I3Cx_IRQHandler" <- : I3Cx interrupt RXFNFF\nByte 1 ... Byte N I3C <- "I3Cx_IRQHandler" : HAL_I3C_EV_IRQHandler() note over I3C : I3C_Tgt_Rx_ISR() alt if (rx_count> 0) note over I3C : p_rx_func() end I3C --> "I3Cx_IRQHandler" "I3Cx_IRQHandler" --> end ... "I3Cx_IRQHandler" <- : I3Cx interrupt FC "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() note over I3C : Clear Frame Complete note over App : Driver state = HAL_I3C_STATE_IDLE\n App <- I3C : HAL_I3C_TGT_RxCpltCallback() App --> I3C "I3Cx_IRQHandler" <-- I3C "I3Cx_IRQHandler" --> @enduml$

Called functions:

Abort Process IT ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process abort : Controller/Target asynchrone process (IT/DMA)\n== App -> I3C : HAL_I3C_CTRL/TGT_ANY_PROCESS_IT/DMA App <-- I3C : HAL_OK ... App -> I3C : HAL_I3C_Abort_IT App <-- I3C : HAL_OK ... "I3Cx_IRQHandler" <- : I3Cx interrupt Underflow/Overflow "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() "I3Cx_IRQHandler" <-- I3C "I3Cx_IRQHandler" -> I3C : HAL_I3C_ERR_IRQHandler() note over App : Driver state = HAL_I3C_STATE_INIT\n App <- I3C : HAL_I3C_AbortCpltCallback() App --> I3C "I3Cx_IRQHandler" <-- I3C "I3Cx_IRQHandler" --> @enduml$

Called functions:

Abort Process DMA ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process abort : Controller Transmit asynchrone (DMA)\n== App -> I3C : HAL_I3C_CTRL_Transfer_DMA() App <-- I3C : HAL_OK ... App -> I3C : HAL_I3C_Abort_IT() I3C -> "HAL DMA driver" : HAL_DMA_Abort_IT() I3C <-- "HAL DMA driver" : HAL_OK App <-- I3C : HAL_OK ... "DMAx_IRQHandler" <- : DMAx interrupt I3C <- "DMAx_IRQHandler" : I3C_DMAAbort() I3C --> "DMAx_IRQHandler" "DMAx_IRQHandler" --> ... "I3Cx_IRQHandler" <- : I3Cx interrupt FC "I3Cx_IRQHandler" -> I3C : HAL_I3C_EV_IRQHandler() note over App : Driver state = HAL_I3C_STATE_INIT\n App <- I3C : HAL_I3C_AbortCpltCallback() App --> I3C "I3Cx_IRQHandler" <-- I3C "I3Cx_IRQHandler" --> @enduml$

Called functions:

Recoverable Blocking Error ¶

$@startuml participant App as "User application" participant "HAL I3C" as I3C ==Process recoverable blocking error : Controller Transmit (IT or DMA)\n == App -> I3C : HAL_I3C_CTRL_Transfer_IT/DMA App <-- I3C : HAL_OK ... I3C <- : I3Cx or DMAx recoverable error interrupt App <-[#Orange] I3C :\ <color #Orange> HAL_I3C_ErrorCallback(&hi3c) </color> alt#grey #lightgrey If USE_HAL_I3C_GET_LAST_ERRORS == 1 App->I3C : HAL_I3C_GetLastErrorCodes() App <-- I3C : \ (HAL_I3C_ERROR_XXX | HAL_I3C_ERROR_YYY) end App [#Orange]--> I3C I3C --> @enduml$

Called functions:

Acquire/Release ¶

$@startuml participant "User 1" participant "User 2" participant "HAL I3C" as I3C participant "HAL OS wrapper" "User 1"-[#green]>I3C : <color #green>HAL_I3C_AcquireBus()</color> I3C-[#green]>"HAL OS wrapper" :<color #green>HAL_OS_SemaphoreTake()</color> I3C <-[#green]- "HAL OS wrapper" "User 1" <-[#green]- I3C : <color #green>HAL_OK</color> note over I3C : Bus acquired by user 1. Any Process can be executed.\nFor instance : Controller Transmit Polling "User 2"-[#red]>I3C : <color #red>HAL_I3C_AcquireBus()</color> I3C-[#red]>"HAL OS wrapper" :<color #red>HAL_OS_SemaphoreTake()</color> "User 1"-[#green]>I3C : <color #green>HAL_I3C_ReleaseBus()</color> "User 1" <-[#green]- I3C : <color #green>HAL_OK</color> I3C <-[#red]- "HAL OS wrapper" "User 2" <-[#red]- I3C : <color #red>HAL_OK</color> note over I3C : Bus acquired by user 2. Any Process can be executed.\nFor instance : Controller Transmit Polling @enduml$

Called functions: