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 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

  • NVIC configuration if you need to use interrupt process

4.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_SetConfig()

  • 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_SetConfigTimeoutCounter()

  • HAL_FDCAN_GetConfigTimeoutCounter()

  • HAL_FDCAN_GetTimeoutCounter()

  • HAL_FDCAN_EnableTimeoutCounter()

  • HAL_FDCAN_DisableTimeoutCounter()

  • HAL_FDCAN_ResetTimeoutCounter()

  • HAL_FDCAN_SetConfigTxDelayCompensation()

  • HAL_FDCAN_GetConfigTxDelayCompensation()

  • HAL_FDCAN_EnableTxDelayCompensation()

  • HAL_FDCAN_DisableTxDelayCompensation()

  • HAL_FDCAN_EnableISOMode()

  • HAL_FDCAN_DisableISOMode()

  • HAL_FDCAN_EnableEdgeFiltering()

  • HAL_FDCAN_DisableEdgeFiltering()

  • HAL_FDCAN_SetMode()

  • HAL_FDCAN_GetMode()

  • HAL_FDCAN_SetFrameFormat()

  • HAL_FDCAN_GetFrameFormat()

  • HAL_FDCAN_SetAutoRetransmission()

  • HAL_FDCAN_GetAutoRetransmission()

  • HAL_FDCAN_SetTransmitPause()

  • HAL_FDCAN_GetTransmitPause()

  • HAL_FDCAN_SetProtocolException()

  • HAL_FDCAN_GetProtocolException()

  • HAL_FDCAN_GetClockFreq()

  • HAL_FDCAN_SetTxMode()

  • HAL_FDCAN_GetTxMode()

5.The control functions allow the user application to initiate Rx/TX transfer 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 given states, for example HAL_FDCAN_Start() can be called in IDLE and ACTIVE but not in 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_DisableRestrictedOperationMode()

• HAL_FDCAN_EnableRestrictedOperationMode()

• HAL_FDCAN_IsEnabledRestrictedOperationMode()

To start the FDCAN module, the user application must call HAL_FDCAN_Start() function. At this level 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 having submitted a Tx request in Tx FIFO or Queue, it is possible to get Tx buffer location used to place the Tx request thanks to HAL_FDCAN_GetLatestTxFifoQRequestBuffer() function. It is then possible to abort later on the corresponding Tx Request using HAL_FDCAN_ReqAbortOfTxBuffer() function.

• When a message is received into the FDCAN message RAM, it can be retrieved using the HAL_FDCAN_GetReceivedMessage() function.

• Calling the HAL_FDCAN_Stop() function stops the FDCAN module by entering it to initialization mode and re-enabling access to configuration registers through the configuration functions listed here above.

6.Polling mode operation.

• Reception and transmission states can be monitored through the following functions:

  • HAL_FDCAN_GetTxBufferMessageStatus() : this function checks if a transmission request is pending on the selected Tx buffer.

  • HAL_FDCAN_GetRxFifoFillLevel() : this function retrieves the number of elements stored in Rx FIFO 0 or RX FIFO 1 according to the passed parameter.

  • HAL_FDCAN_GetTxFifoFreeLevel() : this function retrieves the number of consecutive free Tx FIFO elements.

7.Interrupt mode operation.

• The interrupt management process can be configured using the HAL_FDCAN_SetInterruptGroupsToLine() to associate one or several interrupt group (the interrupt groups can be OR-ed) to an interrupt line. It is also possible to know which interrupt line is connected to an interrupt group using the HAL_FDCAN_GetLineFromInterruptGroup() function. The latter function applies to only one interrupt group.

• There are two interrupt lines: line 0 and 1. By default, all interrupt groups are assigned to line 0. Interrupt lines can be enabled using HAL_FDCAN_EnableInterruptLines() function. The user can check the status of interrupt Line (Enabled or Disabled) using the HAL_FDCAN_IsEnabledInterruptLine() function, the latter applies to only one interrupt line: Interrupt Line 0 or Interrupt Line 1.

• Interrupts are enabled using HAL_FDCAN_EnableInterrupts() function, the interrupt sources can be OR-ed.Then, the process can be controlled through one of the available user callbacks: HAL_FDCAN_xxxCallback(). The user can check the status of interrupt (Enabled or Disabled) using the HAL_FDCAN_IsEnabledInterrupt() function, the latter applies to only one interrupt signal.

• For Transmission Complete Interrupt and Transmission Cancellation Finished interrupt, the buffer(s) on which the interrupt applies, has to be enabled with the respective HAL_FDCAN_EnableTxBufferCompleteInterrupts() and HAL_FDCAN_EnableTxBufferCancellationInterrupts() functions. The buffer can be a single buffer or a combination of several buffers. The same way, those buffers can be disconnected from their respective interrupts signals by using HAL_FDCAN_DisableTxBufferCompleteInterrupts() and HAL_FDCAN_DisableTxBufferCancellationInterrupts() functions. If the user wants to check the status of the buffer (enabled or disabled), the functions HAL_FDCAN_IsEnabledTxBufferCompleteInterrupt() and HAL_FDCAN_IsEnabledTxBufferCancellationInterrupt() have to be used, those functions deal with one single buffer only and cannot be OR-ed contrary to the associated previous Enable and Disable functions.

• In the same way, interrupt lines and interrupts can be disabled using the dedicated functions respectively HAL_FDCAN_DisableInterruptLines() and HAL_FDCAN_DisableInterrupts() functions.

8.Callback registration

• The compilation define USE_HAL_FDCAN_REGISTER_CALLBACKS when set to 1 allows the user to configure dynamically the driver callbacks.

• For specific callbacks TxEventFifoCallback, RxFifo0Callback, RxFifo1Callback, TxBufferCompleteCallback, TxBufferAbortCallback, HighPriorityMessageCallback, TxFifoEmptyCallback, TimeStampWrapAroundCallback, and ErrorCallback(), use dedicated register callbacks, respectively:

  • HAL_FDCAN_RegisterRxFifo0Callback() ,

  • HAL_FDCAN_RegisterRxFifo1Callback() ,

  • HAL_FDCAN_RegisterTxEventFifoCallback() ,

  • HAL_FDCAN_RegisterTxBufferCompleteCallback() ,

  • HAL_FDCAN_RegisterTxBufferAbortCallback() ,

  • HAL_FDCAN_RegisterTxFifoEmptyCallback() ,

  • HAL_FDCAN_RegisterHighPriorityMessageCallback() ,

  • HAL_FDCAN_RegisterTimestampWraparoundCallback() ,

  • HAL_FDCAN_RegisterErrorCallback() ,

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

  • examples HAL_FDCAN_ErrorCallback() .

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

• When the compilation defines USE_HAL_FDCAN_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.

9.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.