HAL SMARTCARD Functions

IRQHandler and Default Callbacks

group SMARTCARD_Exported_Functions_Group8

This subsection provides the function handling the interruption of the SMARTCARDx in asynchronous mode.

HAL_SMARTCARD_IRQHandler() is designed to process the different interruptions in the following order:

  • Error on Rx side (PE, FE, NE, ORE, RTOF)

  • Error on DMA side

  • Data on Rx side

  • Data on Tx side

  • FIFO Empty (Tx)

  • FIFO Full (Rx)

Depending on the process function one’s use, different callback might be triggered:

Process API

\

Callbacks

HAL_SMARTCARD_Transmit_IT

HAL_SMARTCARD_Receive_IT

HAL_SMARTCARD_TxCpltCallback

x

HAL_SMARTCARD_RxCpltCallback

x

HAL_SMARTCARD_ErrorCallback

x

x

Process API

\

Callbacks

HAL_SMARTCARD_Transmit_IT_Opt

HAL_SMARTCARD_Receive_IT_Opt

HAL_SMARTCARD_TxCpltCallback

x

HAL_SMARTCARD_RxCpltCallback

x

HAL_SMARTCARD_ErrorCallback

x

x

HAL_SMARTCARD_TxFifoEmptyCallback*

x

HAL_SMARTCARD_RxFifoFullCallback**

x

Process API

\

Callbacks

HAL_SMARTCARD_Transmit_DMA

HAL_SMARTCARD_Receive_DMA

HAL_SMARTCARD_TxHalfCpltCallback*

x

HAL_SMARTCARD_TxCpltCallback

x

HAL_SMARTCARD_RxHalfCpltCallback*

x

HAL_SMARTCARD_RxCpltCallback

x

HAL_SMARTCARD_ErrorCallback**

x

x

Process API

\

Callbacks

HAL_SMARTCARD_Transmit_DMA_Opt

HAL_SMARTCARD_Receive_DMA_Opt

HAL_SMARTCARD_TxHalfCpltCallback

x

HAL_SMARTCARD_TxCpltCallback

x

HAL_SMARTCARD_RxHalfCpltCallback

x

HAL_SMARTCARD_RxCpltCallback

x

HAL_SMARTCARD_TxFifoEmptyCallback*

x

HAL_SMARTCARD_RxFifoFullCallback**

x

HAL_SMARTCARD_ErrorCallback

x

x

Process API

\

Callbacks

HAL_SMARTCARD_Abort_IT

HAL_SMARTCARD_AbortCpltCallback

x

HAL_SMARTCARD_ErrorCallback

x

Note

* with HAL_SMARTCARD_OPT_TX_IT_FIFO_EMPTY arguments value for interrupts parameter

Note

** with HAL_SMARTCARD_OPT_RX_IT_FIFO_FULL arguments value for interrupts parameter

Note

* these callbacks might be called following DMA IRQ management, not SMARTCARDx IRQ management.

Note

** these callbacks might be called following DMA IRQ management, or SMARTCARDx IRQ management.

Note

* with HAL_SMARTCARD_OPT_TX_IT_FIFO_EMPTY arguments value for interrupts parameter

Note

** with HAL_SMARTCARD_OPT_RX_IT_FIFO_FULL arguments value for interrupts parameter

Functions

void HAL_SMARTCARD_IRQHandler ( hal_smartcard_handle_t * hsmartcard )

Handle SMARTCARD interrupt request.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for SMARTCARD module.

void HAL_SMARTCARD_TxCpltCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Tx completed callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_TxCpltCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_TxHalfCpltCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Tx Half completed callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_TxHalfCpltCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_RxCpltCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Rx completed callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_RxCpltCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_RxHalfCpltCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Rx Half completed callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_RxHalfCpltCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_ErrorCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Error callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_ErrorCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_AbortCpltCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Abort completed callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_AbortCpltCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_RxFifoFullCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Rx FIFO full callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_RxFifoFullCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

void HAL_SMARTCARD_TxFifoEmptyCallback ( hal_smartcard_handle_t * hsmartcard )

SMARTCARD Tx FIFO empty callback.

Warning

This function must not be modified, when the callback is needed, the HAL_SMARTCARD_TxFifoEmptyCallback() can be implemented in the user file.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Initialization and de-initialization functions

group SMARTCARD_Exported_Functions_Group1

This subsection provides a set of functions allowing to initialize and de-initialize the USARTx peripheral:

Functions

hal_status_t HAL_SMARTCARD_Init ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_t instance )

Initialize the SMARTCARD according to the associated handle.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for SMARTCARD module.

  • instance – SMARTCARD instance.

Return values :

  • HAL_INVALID_PARAM – When the handle is NULL.

  • HAL_ERROR – When the MUTEX cannot be created.

  • HAL_OK – HAL SMARTCARD driver correctly Initialized for the given SMARTCARD instance.

hal_status_t HAL_SMARTCARD_DeInit ( hal_smartcard_handle_t * hsmartcard )

De-Initialize the HAL SMARTCARD driver for the given handle.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for SMARTCARD module.

Return values :

HAL_OK – HAL SMARTCARD driver correctly deinitialized for the given SMARTCARD handle.

General Config functions

group SMARTCARD_Exported_Functions_Group2

This subsection provides a set of functions allowing to configure the USARTx peripheral in SMARTCARD mode:

Functions

hal_status_t HAL_SMARTCARD_SetConfig ( hal_smartcard_handle_t * hsmartcard , const hal_smartcard_config_t * p_config )

Configure the SMARTCARD according to the user parameters into the handler instance registers.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_GetConfig ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_config_t * p_config )

Retrieve the SMARTCARD configuration from the handler instance registers.

Parameters :
Return values :

HAL_OK – Operation completed successfully

Unitary basic config functions

group SMARTCARD_Exported_Functions_Group3

This subsection provides a set of unitary functions allowing to configure the USARTx peripheral in SMARTCARD mode:

Functions

hal_status_t HAL_SMARTCARD_SetBaudRate ( const hal_smartcard_handle_t * hsmartcard , uint32_t baud_rate )

Set the SMARTCARD baud rate configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

  • HAL_OK – SMARTCARD baud rate set successfully

  • HAL_INVALID_PARAM – Invalid baud rate parameter

uint32_t HAL_SMARTCARD_GetBaudRate ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD baud rate configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

uint32_t – SMARTCARD baud rate value

hal_status_t HAL_SMARTCARD_SetStopBits ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_stop_bits_t stop_bits )

Set the Stop Bits configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD stop bit value set successfully

hal_smartcard_stop_bits_t HAL_SMARTCARD_GetStopBits ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD Stop Bits configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_stop_bits_t – SMARTCARD stop bit value

hal_status_t HAL_SMARTCARD_SetFirstBit ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_bit_order_t first_bit )

Set the SMARTCARD first bit sent (MSB or LSB) configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD first bit set successfully

hal_smartcard_bit_order_t HAL_SMARTCARD_GetFirstBit ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD first bit sent (MSB or LSB) configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_bit_order_t – SMARTCARD first bit sent (MSB or LSB)

hal_status_t HAL_SMARTCARD_SetParity ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_parity_t parity )

Set the SMARTCARD parity configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD parity mode set successfully

hal_smartcard_parity_t HAL_SMARTCARD_GetParity ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD parity configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_parity_t – SMARTCARD parity mode

hal_status_t HAL_SMARTCARD_SetNack ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_nack_state_t nack )

Set SMARTCARD nack management setting configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – nack management set successfully

hal_smartcard_nack_state_t HAL_SMARTCARD_GetNack ( const hal_smartcard_handle_t * hsmartcard )

Get SMARTCARD nack management setting configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_nack_state_t – nack status

hal_status_t HAL_SMARTCARD_SetClockOutput ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_clock_output_t clock_output )

Enable the SMARTCARD clock output.

Parameters :
Return values :

HAL_OK – SMARTCARD clock output enabled successfully

hal_smartcard_clock_output_t HAL_SMARTCARD_GetClockOutput ( const hal_smartcard_handle_t * hsmartcard )

Get SMARTCARD clock output configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_clock_output_t – clock output status

hal_status_t HAL_SMARTCARD_SetClockPolarity ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_clock_polarity_t clock_polarity )

Set the SMARTCARD clock polarity configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD clock polarity set successfully

hal_smartcard_clock_polarity_t HAL_SMARTCARD_GetClockPolarity ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD clock polarity configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_clock_polarity_t – SMARTCARD clock polarity

hal_status_t HAL_SMARTCARD_SetClockPhase ( const hal_smartcard_handle_t * hsmartcard , hal_smartcard_clock_phase_t clock_phase )

Set the SMARTCARD clock phase configuration passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD clock phase set successfully

hal_smartcard_clock_phase_t HAL_SMARTCARD_GetClockPhase ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD clock phase configuration from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_clock_phase_t – SMARTCARD clock phase

hal_status_t HAL_SMARTCARD_SetGuardTime ( const hal_smartcard_handle_t * hsmartcard , uint32_t guard_time_etu )

Set the SMARTCARD guard time configuration passed in parameters into the handler instance registers.

Note

guard time is expressed in etu (Elementary Time Unit), in SMARTCARD case etu is the baud period duration.

Parameters :
Return values :

HAL_OK – SMARTCARD guard time set successfully

uint32_t HAL_SMARTCARD_GetGuardTime ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD guard time configuration from the handler instance registers.

Note

guard time is expressed in etu (Elementary Time Unit), in SMARTCARD case etu is the baud period duration.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

uint32_t – SMARTCARD guard time

hal_status_t HAL_SMARTCARD_SetAutoRetryCount ( const hal_smartcard_handle_t * hsmartcard , uint32_t retry_count )

Set the SMARTCARD auto retry count feature into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD retry count set successfully

uint32_t HAL_SMARTCARD_GetAutoRetryCount ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD auto retry count feature from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

uint32_t – SMARTCARD retry count

Advanced config functions

group SMARTCARD_Exported_Functions_Group4

This subsection provides a set of functions allowing to configure optional USARTx parameters for SMARTCARD mode:

Those optional parameters have the following default state :

Parameter

Default register state

IOInversion

HAL_SMARTCARD_IO_INVERT_DISABLED

DataInvert

HAL_SMARTCARD_DATA_INVERT_DISABLED

TxRxSwap

HAL_SMARTCARD_TX_RX_SWAP_DISABLED

RxOverRunDetection

HAL_SMARTCARD_OVERRUN_DETECT_ENABLED

DMAStopOnRxError

HAL_SMARTCARD_DMA_STOP_NONE

ReceiverTimeout

HAL_SMARTCARD_TIMEOUT_DISABLED

TxCpltIndication

HAL_SMARTCARD_TX_CPLT_AFTER_GUARD_TIME

BlockLength

0U

Functions

hal_status_t HAL_SMARTCARD_EnableIOInvert ( const hal_smartcard_handle_t * hsmartcard )

Enable SMARTCARD pin active level logic inversion into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – Tx inversion feature enabled successfully

hal_status_t HAL_SMARTCARD_DisableIOInvert ( const hal_smartcard_handle_t * hsmartcard )

Disable SMARTCARD pin active level logic inversion into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – Tx inversion feature disabled successfully

hal_smartcard_io_invert_status_t HAL_SMARTCARD_IsEnabledIOInvert ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD pin active level logic inversion status from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_inversion_status_t – SMARTCARD Tx inversion feature status

hal_status_t HAL_SMARTCARD_EnableDataInvert ( const hal_smartcard_handle_t * hsmartcard )

Enable the binary Data Inversion into the handler instance registers, (1=L, 0=H).

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

HAL_OK – SMARTCARD instance has been correctly configured.

hal_status_t HAL_SMARTCARD_DisableDataInvert ( const hal_smartcard_handle_t * hsmartcard )

Disable the binary Data Inversion into the handler instance registers (1=H, 0=L).

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

HAL_OK – SMARTCARD instance has been correctly configured.

hal_smartcard_data_invert_status_t HAL_SMARTCARD_IsEnabledDataInvert ( const hal_smartcard_handle_t * hsmartcard )

Return the binary Data Inversion status according to the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

hal_smartcard_data_invert_status_t – Current Data Inversion status.

hal_status_t HAL_SMARTCARD_EnableTxRxSwap ( const hal_smartcard_handle_t * hsmartcard )

Enable the Swap between Tx and Rx Pin into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

HAL_OK – SMARTCARD instance has been correctly configured.

hal_status_t HAL_SMARTCARD_DisableTxRxSwap ( const hal_smartcard_handle_t * hsmartcard )

Disable the Swap between Tx and Rx Pin into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

HAL_OK – SMARTCARD instance has been correctly configured.

hal_smartcard_tx_rx_swap_status_t HAL_SMARTCARD_IsEnabledTxRxSwap ( const hal_smartcard_handle_t * hsmartcard )

Return the Swap between Tx and Rx Pin status according to the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

hal_smartcard_tx_rx_swap_status_t – Current Tx Rx Swap status.

hal_status_t HAL_SMARTCARD_EnableRxOverRunDetection ( const hal_smartcard_handle_t * hsmartcard )

Enable SMARTCARD RxOverrun detection into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – Rx overrun feature enabled successfully

hal_status_t HAL_SMARTCARD_DisableRxOverRunDetection ( const hal_smartcard_handle_t * hsmartcard )

Disable SMARTCARD RxOverrun detection into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – Rx overrun feature disabled successfully

hal_smartcard_rx_overrun_detection_status_t HAL_SMARTCARD_IsEnabledRxOverRunDetection ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD RxOverrun detection status from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_rx_overrun_detection_status_t – SMARTCARD Rx overrun feature status

hal_status_t HAL_SMARTCARD_EnableDMAStopOnRxError ( const hal_smartcard_handle_t * hsmartcard )

Enable SMARTCARD DMA stop on Rx error into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – DMA stop on Rx error feature enabled successfully

hal_status_t HAL_SMARTCARD_DisableDMAStopOnRxError ( const hal_smartcard_handle_t * hsmartcard )

Disable SMARTCARD DMA stop on Rx error into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – DMA stop on Rx error feature disabled successfully

hal_smartcard_dma_stop_status_t HAL_SMARTCARD_IsEnabledDMAStopOnRxError ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD DMA stop on Rx error status from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_dma_stop_status_t – SMARTCARD DMA stop on Rx error feature status

hal_status_t HAL_SMARTCARD_SetReceiverTimeout ( const hal_smartcard_handle_t * hsmartcard , uint32_t timeout_etu )

Set the SMARTCARD receiver timeout value passed in parameters into the handler instance registers.

Note

timeout is expressed in etu (Elementary Time Unit), in SMARTCARD case etu is the baud period duration.

Parameters :
Return values :

HAL_OK – SMARTCARD receiver timeout value set successfully

uint32_t HAL_SMARTCARD_GetReceiverTimeout ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD receiver timeout value from the handler instance registers.

Note

timeout is expressed in etu (Elementary Time Unit), in SMARTCARD case etu is the baud period duration.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

uint32_t – SMARTCARD receiver timeout value

hal_status_t HAL_SMARTCARD_EnableReceiverTimeout ( const hal_smartcard_handle_t * hsmartcard )

Enable SMARTCARD Receiver Timeout feature into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – Receiver Timeout feature enabled successfully

hal_status_t HAL_SMARTCARD_DisableReceiverTimeout ( const hal_smartcard_handle_t * hsmartcard )

Disable SMARTCARD Receiver Timeout feature into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – Receiver Timeout feature disabled successfully

hal_smartcard_timeout_status_t HAL_SMARTCARD_IsEnabledReceiverTimeout ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD Receiver Timeout feature status from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_timeout_status_t – SMARTCARD Receiver Timeout feature status

hal_status_t HAL_SMARTCARD_SetTxCpltIndication ( hal_smartcard_handle_t * hsmartcard , const hal_smarcard_tx_cplt_guard_time_indication_t tx_cplt_indication )

Set the SMARTCARD Pre guard time Tx complete indication passed in parameters into the handler instance registers.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t

  • tx_cplt_indication – SMARTCARD Pre guard time Tx complete indication

Return values :

HAL_OK – SMARTCARD Tx completion indication set successfully

hal_smarcard_tx_cplt_guard_time_indication_t HAL_SMARTCARD_GetTxCpltIndication ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD Pre guard time Tx complete indication feature from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smarcard_tx_cplt_guard_time_indication_t – SMARTCARD Pre guard time Tx complete indication

hal_status_t HAL_SMARTCARD_SetBlockLength ( const hal_smartcard_handle_t * hsmartcard , uint32_t block_length_byte )

Set the SMARTCARD block length for T=1 smartcard protocol passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD block length set successfully

uint32_t HAL_SMARTCARD_GetBlockLength ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD block length for T=1 smartcard protocol from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

uint32_t – SMARTCARD block length

hal_status_t HAL_SMARTCARD_EnableEndOfBlockIT ( const hal_smartcard_handle_t * hsmartcard )

Enable SMARTCARD End of block interrupt into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – End of block interrupt enabled successfully

hal_status_t HAL_SMARTCARD_DisableEndOfBlockIT ( const hal_smartcard_handle_t * hsmartcard )

Disable SMARTCARD End of block interrupt into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – End of block interrupt disabled successfully

hal_smartcard_end_of_block_interrupt_status_t HAL_SMARTCARD_IsEnabledEndOfBlockIT ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD End of block interrupt status from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_end_of_block_interrupt_status_t – SMARTCARD End of block interrupt status

FIFO config functions

group SMARTCARD_Exported_Functions_Group5

This subsection provides a set of functions allowing to use the fifo mode feature for the USARTx instance. Prior to use the fifo mode feature, one has to configure one’s instance with HAL_SMARTCARD_SetConfig() . A set of functions is provided to use the fifo mode feature:

The feature has been designed to be used following the procedure:

Functions

hal_status_t HAL_SMARTCARD_EnableFifoMode ( hal_smartcard_handle_t * hsmartcard )

Enable SMARTCARD FIFO mode into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – FIFO feature enabled successfully

hal_status_t HAL_SMARTCARD_DisableFifoMode ( hal_smartcard_handle_t * hsmartcard )

Disable SMARTCARD FIFO mode into the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

HAL_OK – FIFO feature disabled successfully

hal_smartcard_fifo_mode_status_t HAL_SMARTCARD_IsEnabledFifoMode ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD FIFO status from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_fifo_mode_status_t – SMARTCARD FIFO feature status

hal_status_t HAL_SMARTCARD_SetTxFifoThreshold ( hal_smartcard_handle_t * hsmartcard , const hal_smartcard_fifo_threshold_t tx_fifo_threshold )

Set the SMARTCARD Tx FIFO threshold value passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD Tx FIFO threshold value set successfully

hal_smartcard_fifo_threshold_t HAL_SMARTCARD_GetTxFifoThreshold ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD Tx FIFO threshold value from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_fifo_threshold_t – SMARTCARD Tx FIFO threshold value

hal_status_t HAL_SMARTCARD_SetRxFifoThreshold ( hal_smartcard_handle_t * hsmartcard , const hal_smartcard_fifo_threshold_t rx_fifo_threshold )

Set the SMARTCARD Rx FIFO threshold value passed in parameters into the handler instance registers.

Parameters :
Return values :

HAL_OK – SMARTCARD Rx FIFO threshold value set successfully

hal_smartcard_fifo_threshold_t HAL_SMARTCARD_GetRxFifoThreshold ( const hal_smartcard_handle_t * hsmartcard )

Get the SMARTCARD Rx FIFO threshold value from the handler instance registers.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t

Return values :

hal_smartcard_fifo_threshold_t – SMARTCARD Rx FIFO threshold

IO operation functions

group SMARTCARD_Exported_Functions_Group6

This subsection provides a set of functions allowing to manage the SMARTCARD data transfers.

There are two modes of transfer:

  • Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer.

  • Non-Blocking mode: The communication is performed using Interrupts or DMA, These API’s return the HAL status. The end of the data processing will be indicated through the dedicated SMARTCARD IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_SMARTCARD_TxCpltCallback() , HAL_SMARTCARD_RxCpltCallback() user callbacks will be executed respectively at the end of the Transmit or Receive process The HAL_SMARTCARD_ErrorCallback() user callback will be executed when a communication error is detected.

Polling APIs:

IT APIs:

DMA APIs:

Functions

hal_status_t HAL_SMARTCARD_Transmit ( hal_smartcard_handle_t * hsmartcard , const uint8_t * p_data , uint16_t size_byte , uint32_t timeout_ms )

Send an amount of data in blocking mode.

Note

When FIFO mode is enabled, writing a data in the TDR register adds one data to the TXFIFO. Write operations to the TDR register are performed when TXFNF flag is set. From hardware perspective, TXFNF flag and TXE are mapped on the same bit-field.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be sent.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_TIMEOUT – Transfer timeout

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Receive ( hal_smartcard_handle_t * hsmartcard , uint8_t * p_data , uint16_t size_byte , uint32_t timeout_ms )

Receive an amount of data in blocking mode.

Note

When FIFO mode is enabled, the RXFNE flag is set as long as the RXFIFO is not empty. Read operations from the RDR register are performed when RXFNE flag is set. From hardware perspective, RXFNE flag and RXNE are mapped on the same bit-field.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be received.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_TIMEOUT – Transfer timeout

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Transmit_IT ( hal_smartcard_handle_t * hsmartcard , const uint8_t * p_data , uint16_t size_byte )

Send an amount of data in interrupt mode.

Note

When FIFO mode is disabled, USART interrupt is generated whenever USART_TDR register is empty, i.e one interrupt per data to transmit.

Note

When FIFO mode is enabled, USART interrupt is generated whenever TXFIFO threshold reached. In that case the interrupt rate depends on TXFIFO threshold configuration.

Note

This function sets the hsmartcard->TxIsr function pointer according to the FIFO mode (data transmission processing depends on FIFO mode).

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be sent.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Transmit_IT_Opt ( hal_smartcard_handle_t * hsmartcard , const uint8_t * p_data , uint16_t size_byte , uint32_t interrupts )

Send an amount of data in interrupt mode, allow user to enable Optional Interrupts part of SMARTCARD optional TX IT interrupts.

Note

When FIFO mode is disabled, USART interrupt is generated whenever USART_TDR register is empty, i.e one interrupt per data to transmit.

Note

When FIFO mode is enabled, USART interrupt is generated whenever TXFIFO threshold reached. In that case the interrupt rate depends on TXFIFO threshold configuration.

Note

This function sets the hsmartcard->TxIsr function pointer according to the FIFO mode (data transmission processing depends on FIFO mode).

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data to be sent.

  • interrupts – Optional interrupts part of SMARTCARD optional TX IT interrupts.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Receive_IT ( hal_smartcard_handle_t * hsmartcard , uint8_t * p_data , uint16_t size_byte )

Receive an amount of data in interrupt mode.

Note

When FIFO mode is disabled, USART interrupt is generated whenever USART_RDR register can be read, i.e one interrupt per data to receive.

Note

When FIFO mode is enabled, USART interrupt is generated whenever RXFIFO threshold reached. In that case the interrupt rate depends on RXFIFO threshold configuration.

Note

This function sets the hsmartcard->RxIsr function pointer according to the FIFO mode (data reception processing depends on FIFO mode).

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be received.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Receive_IT_Opt ( hal_smartcard_handle_t * hsmartcard , uint8_t * p_data , uint16_t size_byte , uint32_t interrupts )

Receive an amount of data in interrupt mode, allow user to enable Optional Interrupts part of SMARTCARD Optional RX IT interrupts.

Note

When FIFO mode is disabled, USART interrupt is generated whenever USART_RDR register can be read, i.e one interrupt per data to receive.

Note

When FIFO mode is enabled, USART interrupt is generated whenever RXFIFO threshold reached. In that case the interrupt rate depends on RXFIFO threshold configuration.

Note

This function sets the hsmartcard->RxIsr function pointer according to the FIFO mode (data reception processing depends on FIFO mode).

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be received.

  • interrupts – Optional interrupts part of SMARTCARD Optional RX IT interrupts.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_BUSY – Concurrent process ongoing

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Transmit_DMA ( hal_smartcard_handle_t * hsmartcard , const uint8_t * p_data , uint16_t size_byte )

Send an amount of data in DMA mode.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be sent.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – DMA did not start successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Transmit_DMA_Opt ( hal_smartcard_handle_t * hsmartcard , const uint8_t * p_data , uint16_t size_byte , uint32_t interrupts )

Send an amount of data in DMA mode, allow user to enable Optional Interrupts part of SMARTCARD Optional TX DMA interrupts.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data to be sent.

  • interrupts – Optional interrupts part of SMARTCARD Optional TX DMA interrupts.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – DMA did not start successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Receive_DMA ( hal_smartcard_handle_t * hsmartcard , uint8_t * p_data , uint16_t size_byte )

Receive an amount of data in DMA mode.

Note

The SMARTCARD-associated USART parity is enabled (PCE = 1), the received data contain the parity bit (MSB position).

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – pointer to data buffer.

  • size_byte – amount of data to be received.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – DMA did not start successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Receive_DMA_Opt ( hal_smartcard_handle_t * hsmartcard , uint8_t * p_data , uint16_t size_byte , uint32_t interrupts )

Receive an amount of data in DMA mode, allow user to enable Optional Interrupts part of SMARTCARD Optional RX DMA interrupts.

Note

The SMARTCARD-associated USART parity is enabled (PCE = 1), the received data contain the parity bit (MSB position).

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

  • p_data – Pointer to data buffer.

  • size_byte – Amount of data to be received.

  • interrupts – Optional interrupts part of SMARTCARD Optional RX DMA interrupts.

Return values :

  • HAL_OK – Operation started successfully

  • HAL_ERROR – DMA did not start successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_Abort ( hal_smartcard_handle_t * hsmartcard )

Abort ongoing transfers either Tx or Rx (blocking mode).

Note

This procedure could be used for aborting any ongoing transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable SMARTCARD Interrupts (Tx and Rx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort (in case of transfer in DMA mode)

  • Set handle State to HAL_SMARTCARD_STATE_IDLE

Note

This procedure is executed in blocking mode : when exiting function, Abort is considered as completed.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

Return values :

  • HAL_OK – Operation successfully aborted

  • HAL_TIMEOUT – Abort timeout

hal_status_t HAL_SMARTCARD_Abort_IT ( hal_smartcard_handle_t * hsmartcard )

Abort ongoing transfers either Tx or Rx (Interrupt mode).

Note

This procedure could be used for aborting any ongoing transfer started in Interrupt or DMA mode. This procedure performs following operations :

  • Disable SMARTCARD Interrupts (Tx and Rx)

  • Disable the DMA transfer in the peripheral register (if enabled)

  • Abort DMA transfer by calling HAL_DMA_Abort_IT (in case of transfer in DMA mode)

  • Set handle State to HAL_SMARTCARD_STATE_IDLE

  • At abort completion, call user abort complete callback

Note

This procedure is executed in Interrupt mode, meaning that abort procedure could be considered as completed only when user abort complete callback is executed (not when exiting function).

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for the specified SMARTCARD module.

Return values :

HAL_OK – Operation successfully aborted

DMA Configuration functions

group SMARTCARD_Exported_Functions_Group7

This subsection provides a set of functions allowing to link the HAL SMARTCARD handle to a Tx and Rx DMA handler for the USARTx instance. A set of functions is provided to use the DMA feature:

Functions

hal_status_t HAL_SMARTCARD_SetTxDMA ( hal_smartcard_handle_t * hsmartcard , hal_dma_handle_t * hdma_tx )

Set DMA channel for Transmission.

Parameters :
Return values :

  • HAL_OK – The channel has been correctly set.

  • HAL_INVALID_PARAM – hdma_tx is NULL.

hal_status_t HAL_SMARTCARD_SetRxDMA ( hal_smartcard_handle_t * hsmartcard , hal_dma_handle_t * hdma_rx )

Set DMA channel for Reception.

Parameters :
Return values :

  • HAL_OK – The channel has been correctly set.

  • HAL_INVALID_PARAM – hdma_rx is NULL.

Callbacks Register functions

group SMARTCARD_Exported_Functions_Group9

This subsection provides a set of functions allowing to configure the Callbacks for the USARTx instance. Prior to configure the Callbacks, one has to configure one’s with HAL_SMARTCARD_SetConfig() . A set of functions is provided to configure the callbacks:

Functions

hal_status_t HAL_SMARTCARD_RegisterTxCpltCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD Tx Transfer completed callback.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t

  • p_callback – Pointer to the Tx Transfer completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterTxHalfCpltCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD Tx Transfer Half completed callback.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t

  • p_callback – Pointer to the Tx Transfer Half completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterRxCpltCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD Rx Transfer completed callback.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t

  • p_callback – Pointer to the Rx Transfer completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterRxHalfCpltCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD Rx Transfer Half completed callback.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t

  • p_callback – Pointer to the Rx Transfer Half completed callback function

Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterErrorCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD error callback.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterAbortCpltCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD abort complete callback.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterRxFifoFullCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD Rx FIFO empty callback.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_SMARTCARD_RegisterTxFifoEmptyCallback ( hal_smartcard_handle_t * hsmartcard , hal_smartcard_cb_t p_callback )

Register the SMARTCARD Tx FIFO empty callback.

Parameters :
Return values :

  • HAL_OK – Operation completed successfully

  • HAL_INVALID_PARAM – Invalid parameter

State, Error and Clock Frequency functions

group SMARTCARD_Exported_Functions_Group10

This subsection provides 2 functions allowing to read peripheral state and last occurred errors.

Functions

hal_smartcard_state_t HAL_SMARTCARD_GetState ( const hal_smartcard_handle_t * hsmartcard )

Retrieve the SMARTCARD handle state.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for SMARTCARD module.

Return values :

hal_smartcard_state_t – SMARTCARD state

uint32_t HAL_SMARTCARD_GetLastErrorCodes ( const hal_smartcard_handle_t * hsmartcard )

Retrieve the SMARTCARD errors codes.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure that contains the configuration information for SMARTCARD module.

Return values :

uint32_t – Returned value can be a combination of the following values:

uint32_t HAL_SMARTCARD_GetClockFreq ( const hal_smartcard_handle_t * hsmartcard )

Report the SMARTCARD clock frequency from the RCC configuration.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the USART instance.

Return values :

uint32_t – clock frequency

Acquire/Release Bus functions

group SMARTCARD_Exported_Functions_Group11

This subsection provides functions allowing to control the bus of the USARTx instance:

For multi task application, it is strongly recommended to use the bus operation functions to avoid race concurrency.

Functions

hal_status_t HAL_SMARTCARD_AcquireBus ( hal_smartcard_handle_t * hsmartcard , uint32_t timeout_ms )

Acquire the current instance bus.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

  • timeout_ms – Timeout in milliseconds for the Acquire to expire.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SMARTCARD_ReleaseBus ( hal_smartcard_handle_t * hsmartcard )

Release the current instance bus.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

UserData functions

group SMARTCARD_Exported_Functions_Group12

This subsection provides functions allowing to set user specific data to a SMARTCARDx instance:

Functions

void HAL_SMARTCARD_SetUserData ( hal_smartcard_handle_t * hsmartcard , const void * p_user_data )

Store User Data pointer into the handle.

Parameters :

  • hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

  • p_user_data – Pointer to the user data.

const void * HAL_SMARTCARD_GetUserData ( const hal_smartcard_handle_t * hsmartcard )

Retrieve User Data pointer from the handle.

Parameters :

hsmartcard – Pointer to a hal_smartcard_handle_t structure which contains the SMARTCARD instance.

Return values :

Pointer – to the user data.