HAL FDCAN How to Use

group FDCAN_How_To_Use

How to use this driver

1. Declare a hal_fdcan_handle_t handle structure and initialize the FDCAN driver with an FDCAN instance.

2. Initialize the FDCAN peripheral using the HAL_FDCAN_Init() function. The FDCAN clock is enabled inside HAL_FDCAN_Init() if USE_HAL_FDCAN_CLK_ENABLE_MODEL > HAL_CLK_ENABLE_NO.

3. Configure the low-level hardware (GPIO, CLOCK, NVIC, etc.)

• Enable the FDCAN clock if USE_HAL_FDCAN_CLK_ENABLE_MODEL = HAL_CLK_ENABLE_NO

• FDCAN pins configuration:

  • Enable the clock for the FDCAN GPIOs

  • Configure the NVIC for interrupt processing

1. Configure the peripheral using the HAL_FDCAN_SetConfig()

• If needed, the kernel clock divider can be changed by the first instance after the global configuration using HAL_FDCAN_SetClockDivider(). Only the first instance is allowed to modify the divider.

• If needed, configure and retrieve the reception filters and optional features using the following configuration functions:

  • HAL_FDCAN_GetConfig()

  • HAL_FDCAN_SetNominalBitTiming()

  • HAL_FDCAN_GetNominalBitTiming()

  • HAL_FDCAN_SetDataBitTiming()

  • HAL_FDCAN_GetDataBitTiming()

  • HAL_FDCAN_SetClockDivider()

  • HAL_FDCAN_GetClockDivider()

  • HAL_FDCAN_SetFilter()

  • HAL_FDCAN_GetFilter()

  • HAL_FDCAN_SetGlobalFilter()

  • HAL_FDCAN_GetGlobalFilter()

  • HAL_FDCAN_SetExtendedIdMask()

  • HAL_FDCAN_GetExtendedIdMask()

  • HAL_FDCAN_SetRxFifoOverwrite()

  • HAL_FDCAN_GetRxFifoOverwrite()

  • HAL_FDCAN_SetRamWatchdog()

  • HAL_FDCAN_GetRamWatchdog()

  • HAL_FDCAN_SetConfigTimestampCounter()

  • HAL_FDCAN_GetConfigTimestampCounter()

  • HAL_FDCAN_GetTimestampCounter()

  • HAL_FDCAN_ResetTimestampCounter()

  • HAL_FDCAN_SetConfigTimeoutCounter()

  • HAL_FDCAN_GetConfigTimeoutCounter()

  • HAL_FDCAN_GetTimeoutCounter()

  • HAL_FDCAN_EnableTimeoutCounter()

  • HAL_FDCAN_DisableTimeoutCounter()

  • HAL_FDCAN_IsEnabledTimeoutCounter()

  • HAL_FDCAN_ResetTimeoutCounter()

  • HAL_FDCAN_SetConfigTxDelayCompensation()

  • HAL_FDCAN_GetConfigTxDelayCompensation()

  • HAL_FDCAN_EnableTxDelayCompensation()

  • HAL_FDCAN_DisableTxDelayCompensation()

  • HAL_FDCAN_IsEnabledTxDelayCompensation()

  • HAL_FDCAN_EnableISOMode()

  • HAL_FDCAN_DisableISOMode()

  • HAL_FDCAN_IsEnabledISOMode()

  • HAL_FDCAN_EnableEdgeFiltering()

  • HAL_FDCAN_DisableEdgeFiltering()

  • HAL_FDCAN_IsEnabledEdgeFiltering()

  • HAL_FDCAN_SetMode()

  • HAL_FDCAN_GetMode()

  • HAL_FDCAN_EnableRestrictedOperationMode()

  • HAL_FDCAN_DisableRestrictedOperationMode()

  • HAL_FDCAN_IsEnabledRestrictedOperationMode()

  • HAL_FDCAN_SetFrameFormat()

  • HAL_FDCAN_GetFrameFormat()

  • HAL_FDCAN_EnableAutoRetransmission()

  • HAL_FDCAN_DisableAutoRetransmission()

  • HAL_FDCAN_IsEnabledAutoRetransmission()

  • HAL_FDCAN_EnableTransmitPause()

  • HAL_FDCAN_DisableTransmitPause()

  • HAL_FDCAN_IsEnabledTransmitPause()

  • HAL_FDCAN_EnableProtocolException()

  • HAL_FDCAN_DisableProtocolException()

  • HAL_FDCAN_IsEnabledProtocolException()

  • HAL_FDCAN_SetTxMode()

  • HAL_FDCAN_GetTxMode()

  • HAL_FDCAN_GetClockFreq()

1. Operation Modes

• FDCAN communication is primarily handled in interrupt (IT) mode. After configuring the peripheral and enabling the necessary interrupts, the application starts the FDCAN module. Events such as transmission complete, transmission cancellation, or message reception are handled asynchronously via their respective callbacks (e.g., HAL_FDCAN_TxEventFifoCallback(), HAL_FDCAN_TxBufferCompleteCallback()). The interrupt configuration sequence is as follows:

  • Enable individual interrupt sources using HAL_FDCAN_EnableInterrupts().

  • Map interrupt groups to an interrupt line using HAL_FDCAN_SetInterruptGroupsToLine().

  • Enable the selected interrupt line(s) using HAL_FDCAN_EnableInterruptLines(). The status of individual interrupt sources can be checked with HAL_FDCAN_IsEnabledInterrupt(), and the status of interrupt lines can be checked with HAL_FDCAN_IsEnabledInterruptLine().

• For transmission complete and transmission cancellation finished interrupts, buffer-specific interrupt enables are required.

  • Enable interrupts for the relevant transmit buffers using HAL_FDCAN_EnableTxBufferCompleteInterrupts() and HAL_FDCAN_EnableTxBufferCancellationInterrupts(). These functions allow enabling one or multiple buffers simultaneously.

  • Disable interrupts for specific buffers using HAL_FDCAN_DisableTxBufferCompleteInterrupts() and HAL_FDCAN_DisableTxBufferCancellationInterrupts(). These functions allow disabling one or multiple buffers simultaneously.

  • Check the enable status of a specific buffer interrupt using HAL_FDCAN_IsEnabledTxBufferCompleteInterrupt() or HAL_FDCAN_IsEnabledTxBufferCancellationInterrupt(). These status functions operate on a single buffer at a time.

• While interrupt-driven operation is recommended for most use cases, the driver also provides blocking (polling) APIs for synchronous state monitoring.

  • Use HAL_FDCAN_GetTxBufferMessageStatus() to check if a transmission request is pending on a specific Tx buffer.

  • Use HAL_FDCAN_GetRxFifoFillLevel() to retrieve the current number of elements in an Rx FIFO.

  • Use HAL_FDCAN_GetTxFifoFreeLevel() to determine the number of free elements available in the Tx FIFO. Use these polling APIs to monitor transmission and reception states synchronously, which can be useful in scenarios where deterministic, blocking behavior is required or when interrupts are not suitable or available.

1. Use the control functions to initiate Rx/Tx transfers over the FDCAN bus, either sending frames, or receiving frames, or checking and managing the whole transfer process and resources (status, buffers, events). Most of the control functions can be called in IDLE, ACTIVE, or POWER_DOWN states; however, some control functions are restricted to specific states. For example, HAL_FDCAN_Start() can be called in IDLE but not in ACTIVE or POWER_DOWN. The control functions include the following set of functions:

   • HAL_FDCAN_Start()

   • HAL_FDCAN_Stop()

   • HAL_FDCAN_ReqTransmitMsgFromFIFOQ()

   • HAL_FDCAN_GetTxFifoStatus()

   • HAL_FDCAN_GetLatestTxFifoQRequestBuffer()

   • HAL_FDCAN_GetTxFifoFreeLevel()

   • HAL_FDCAN_ReqAbortOfTxBuffer()

   • HAL_FDCAN_GetTxEvent()

   • HAL_FDCAN_GetTxBufferMessageStatus()

   • HAL_FDCAN_GetReceivedMessage()

   • HAL_FDCAN_GetRxFifoFillLevel()

   • HAL_FDCAN_GetHighPriorityMessageStatus()

   • HAL_FDCAN_GetProtocolStatus()

   • HAL_FDCAN_GetErrorCounters()

   • HAL_FDCAN_Recover()

Call HAL_FDCAN_Start() to start the FDCAN module. At this step, the node is active on the bus:

• It can send and receive messages:

  • The following Tx control functions can be called when the FDCAN module is started or in power down mode, but it must be operating only when the FDCAN is in active mode.

    • HAL_FDCAN_ReqTransmitMsgFromFIFOQ()

    • HAL_FDCAN_ReqAbortOfTxBuffer()

• After submitting a Tx request in the Tx FIFO or queue, call HAL_FDCAN_GetLatestTxFifoQRequestBuffer() to determine which Tx buffer was used for the request. The corresponding Tx request can then be aborted later using the HAL_FDCAN_ReqAbortOfTxBuffer() function.

• Retrieve a message received into the FDCAN message RAM using the HAL_FDCAN_GetReceivedMessage() function.

• Call HAL_FDCAN_Stop() to stop the FDCAN module by switching it to initialization mode, which re-enables access to configuration registers through the configuration functions listed above.

1. Callbacks definition in interrupt mode:

   When the compilation define USE_HAL_FDCAN_REGISTER_CALLBACKS is set to 1U, configure the driver callbacks dynamically using the registration functions below:

Callback name	Default value	Callback registration function
Rx FIFO 0	HAL_FDCAN_RxFifo0Callback()	HAL_FDCAN_RegisterRxFifo0Callback()
Rx FIFO 1	HAL_FDCAN_RxFifo1Callback()	HAL_FDCAN_RegisterRxFifo1Callback()
Tx event FIFO	HAL_FDCAN_TxEventFifoCallback()	HAL_FDCAN_RegisterTxEventFifoCallback()
Tx FIFO empty	HAL_FDCAN_TxFifoEmptyCallback()	HAL_FDCAN_RegisterTxFifoEmptyCallback()
Tx buffer complete	HAL_FDCAN_TxBufferCompleteCallback()	HAL_FDCAN_RegisterTxBufferCompleteCallback()
Tx buffer abort	HAL_FDCAN_TxBufferAbortCallback()	HAL_FDCAN_RegisterTxBufferAbortCallback()
High priority MSG	HAL_FDCAN_HighPriorityMessageCallback()	HAL_FDCAN_RegisterHighPriorityMessageCallback()
TS wraparound	HAL_FDCAN_TimestampWraparoundCallback()	HAL_FDCAN_RegisterTimestampWraparoundCallback()
Error	HAL_FDCAN_ErrorCallback()	HAL_FDCAN_RegisterErrorCallback()

If one needs to unregister a callback, register the default callback via the registration function.

By default, after the HAL_FDCAN_Init() and when the state is HAL_FDCAN_STATE_INIT, all callbacks are set to the corresponding default weak functions.

• Callbacks can be registered in HAL_FDCAN_STATE_INIT or HAL_FDCAN_STATE_IDLE states only.

• When HAL_FDCAN_ErrorCallback() (or its registered callback) is called, check if the error code contains HAL_FDCAN_ERROR_BUS_FAULT_OFF. If a bus-off condition is detected, initiate recovery by calling HAL_FDCAN_Recover().

• Restricted operation mode handling:

  • The hardware in some cases automatically sets the ASM bit (restricted operation). Calling HAL_FDCAN_GetMode() can return HAL_FDCAN_MODE_INVALID because the CCCR bits combination does not match a standard user-configurable mode.

  • Scenarios forcing restricted operation (ASM bit set):

    • Message RAM access failure:

      • A RAM access fault (e.g., timing violation or HW fault) sets ASM and raises HAL_FDCAN_ERROR_RAM_ACCESS_FAILURE.

      • Required actions:

        • Diagnose and fix the RAM access issue (memory layout, timing, HW fault).

        • Reinitialize or reset the FDCAN peripheral if needed.

        • Clear ASM by calling HAL_FDCAN_DisableRestrictedOperationMode() when fixed.

  • Normal communication is suspended while ASM remains set; clear it after resolving the root cause.

• If USE_HAL_FDCAN_REGISTER_CALLBACKS is 0U (or undefined) callback registration is not available and the default weak callbacks listed above are used.

1. Acquire/Release the FDCAN bus

• When the compilation flag USE_HAL_MUTEX is set to 1, it allows the user to acquire/reserve the whole FDCAN bus for executing process. The HAL_FDCAN_Acquire and HAL_FDCAN_Release are based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

  • HAL_FDCAN_AcquireBus() for acquiring the bus or wait for it.

  • HAL_FDCAN_ReleaseBus() for releasing the bus.

• When the compilation flag USE_HAL_MUTEX is set to 0 or not defined, HAL_FDCAN_AcquireBus/HAL_FDCAN_ReleaseBus are not available.