|
STM32F479xx HAL User Manual
|
FMPI2C HAL module driver. This file provides firmware functions to manage the following functionalities of the Inter Integrated Circuit (FMPI2C) peripheral: + Initialization and de-initialization functions + IO operation functions + Peripheral State and Errors functions. More...
#include "stm32f4xx_hal.h"Go to the source code of this file.
FMPI2C HAL module driver. This file provides firmware functions to manage the following functionalities of the Inter Integrated Circuit (FMPI2C) peripheral: + Initialization and de-initialization functions + IO operation functions + Peripheral State and Errors functions.
==============================================================================
##### How to use this driver #####
==============================================================================
[..]
The FMPI2C HAL driver can be used as follows:
(#) Declare a FMPI2C_HandleTypeDef handle structure, for example:
FMPI2C_HandleTypeDef hfmpi2c;
(#)Initialize the FMPI2C low level resources by implementing the HAL_FMPI2C_MspInit() API:
(##) Enable the FMPI2Cx interface clock
(##) FMPI2C pins configuration
(+++) Enable the clock for the FMPI2C GPIOs
(+++) Configure FMPI2C pins as alternate function open-drain
(##) NVIC configuration if you need to use interrupt process
(+++) Configure the FMPI2Cx interrupt priority
(+++) Enable the NVIC FMPI2C IRQ Channel
(##) DMA Configuration if you need to use DMA process
(+++) Declare a DMA_HandleTypeDef handle structure for
the transmit or receive stream
(+++) Enable the DMAx interface clock using
(+++) Configure the DMA handle parameters
(+++) Configure the DMA Tx or Rx stream
(+++) Associate the initialized DMA handle to the hfmpi2c DMA Tx or Rx handle
(+++) Configure the priority and enable the NVIC for the transfer complete interrupt on
the DMA Tx or Rx stream
(#) Configure the Communication Clock Timing, Own Address1, Master Addressing mode, Dual Addressing mode,
Own Address2, Own Address2 Mask, General call and Nostretch mode in the hfmpi2c Init structure.
(#) Initialize the FMPI2C registers by calling the HAL_FMPI2C_Init(), configures also the low level Hardware
(GPIO, CLOCK, NVIC...etc) by calling the customized HAL_FMPI2C_MspInit(&hfmpi2c) API.
(#) To check if target device is ready for communication, use the function HAL_FMPI2C_IsDeviceReady()
(#) For FMPI2C IO and IO MEM operations, three operation modes are available within this driver :
*** Polling mode IO operation ***
=================================
[..]
(+) Transmit in master mode an amount of data in blocking mode using HAL_FMPI2C_Master_Transmit()
(+) Receive in master mode an amount of data in blocking mode using HAL_FMPI2C_Master_Receive()
(+) Transmit in slave mode an amount of data in blocking mode using HAL_FMPI2C_Slave_Transmit()
(+) Receive in slave mode an amount of data in blocking mode using HAL_FMPI2C_Slave_Receive()
*** Polling mode IO MEM operation ***
=====================================
[..]
(+) Write an amount of data in blocking mode to a specific memory address using HAL_FMPI2C_Mem_Write()
(+) Read an amount of data in blocking mode from a specific memory address using HAL_FMPI2C_Mem_Read()
*** Interrupt mode IO operation ***
===================================
[..]
(+) Transmit in master mode an amount of data in non-blocking mode using HAL_FMPI2C_Master_Transmit_IT()
(+) At transmission end of transfer, HAL_FMPI2C_MasterTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MasterTxCpltCallback()
(+) Receive in master mode an amount of data in non-blocking mode using HAL_FMPI2C_Master_Receive_IT()
(+) At reception end of transfer, HAL_FMPI2C_MasterRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MasterRxCpltCallback()
(+) Transmit in slave mode an amount of data in non-blocking mode using HAL_FMPI2C_Slave_Transmit_IT()
(+) At transmission end of transfer, HAL_FMPI2C_SlaveTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_SlaveTxCpltCallback()
(+) Receive in slave mode an amount of data in non-blocking mode using HAL_FMPI2C_Slave_Receive_IT()
(+) At reception end of transfer, HAL_FMPI2C_SlaveRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_SlaveRxCpltCallback()
(+) In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_ErrorCallback()
(+) Abort a master FMPI2C process communication with Interrupt using HAL_FMPI2C_Master_Abort_IT()
(+) End of abort process, HAL_FMPI2C_AbortCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_AbortCpltCallback()
(+) Discard a slave FMPI2C process communication using __HAL_FMPI2C_GENERATE_NACK() macro.
This action will inform Master to generate a Stop condition to discard the communication.
*** Interrupt mode or DMA mode IO sequential operation ***
==========================================================
[..]
(@) These interfaces allow to manage a sequential transfer with a repeated start condition
when a direction change during transfer
[..]
(+) A specific option field manage the different steps of a sequential transfer
(+) Option field values are defined through FMPI2C_XFEROPTIONS and are listed below:
(++) FMPI2C_FIRST_AND_LAST_FRAME: No sequential usage, functional is same as associated interfaces in no sequential mode
(++) FMPI2C_FIRST_FRAME: Sequential usage, this option allow to manage a sequence with start condition, address
and data to transfer without a final stop condition
(++) FMPI2C_FIRST_AND_NEXT_FRAME: Sequential usage (Master only), this option allow to manage a sequence with start condition, address
and data to transfer without a final stop condition, an then permit a call the same master sequential interface
several times (like HAL_FMPI2C_Master_Seq_Transmit_IT() then HAL_FMPI2C_Master_Seq_Transmit_IT()
or HAL_FMPI2C_Master_Seq_Transmit_DMA() then HAL_FMPI2C_Master_Seq_Transmit_DMA())
(++) FMPI2C_NEXT_FRAME: Sequential usage, this option allow to manage a sequence with a restart condition, address
and with new data to transfer if the direction change or manage only the new data to
transfer
if no direction change and without a final stop condition in both cases
(++) FMPI2C_LAST_FRAME: Sequential usage, this option allow to manage a sequance with a restart condition, address
and with new data to transfer if the direction change or manage only the new data to
transfer
if no direction change and with a final stop condition in both cases
(++) FMPI2C_LAST_FRAME_NO_STOP: Sequential usage (Master only), this option allow to manage a restart condition
after several call of the same master sequential interface several times
(link with option FMPI2C_FIRST_AND_NEXT_FRAME).
Usage can, transfer several bytes one by one using
HAL_FMPI2C_Master_Seq_Transmit_IT
or HAL_FMPI2C_Master_Seq_Receive_IT
or HAL_FMPI2C_Master_Seq_Transmit_DMA
or HAL_FMPI2C_Master_Seq_Receive_DMA
with option FMPI2C_FIRST_AND_NEXT_FRAME then FMPI2C_NEXT_FRAME.
Then usage of this option FMPI2C_LAST_FRAME_NO_STOP at the last Transmit or
Receive sequence permit to call the opposite interface Receive or Transmit
without stopping the communication and so generate a restart condition.
(++) FMPI2C_OTHER_FRAME: Sequential usage (Master only), this option allow to manage a restart condition after
each call of the same master sequential
interface.
Usage can, transfer several bytes one by one with a restart with slave address between
each bytes using
HAL_FMPI2C_Master_Seq_Transmit_IT
or HAL_FMPI2C_Master_Seq_Receive_IT
or HAL_FMPI2C_Master_Seq_Transmit_DMA
or HAL_FMPI2C_Master_Seq_Receive_DMA
with option FMPI2C_FIRST_FRAME then FMPI2C_OTHER_FRAME.
Then usage of this option FMPI2C_OTHER_AND_LAST_FRAME at the last frame to help automatic
generation of STOP condition.
(+) Different sequential FMPI2C interfaces are listed below:
(++) Sequential transmit in master FMPI2C mode an amount of data in non-blocking mode using HAL_FMPI2C_Master_Seq_Transmit_IT()
or using HAL_FMPI2C_Master_Seq_Transmit_DMA()
(+++) At transmission end of current frame transfer, HAL_FMPI2C_MasterTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MasterTxCpltCallback()
(++) Sequential receive in master FMPI2C mode an amount of data in non-blocking mode using HAL_FMPI2C_Master_Seq_Receive_IT()
or using HAL_FMPI2C_Master_Seq_Receive_DMA()
(+++) At reception end of current frame transfer, HAL_FMPI2C_MasterRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MasterRxCpltCallback()
(++) Abort a master IT or DMA FMPI2C process communication with Interrupt using HAL_FMPI2C_Master_Abort_IT()
(+++) End of abort process, HAL_FMPI2C_AbortCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_AbortCpltCallback()
(++) Enable/disable the Address listen mode in slave FMPI2C mode using HAL_FMPI2C_EnableListen_IT() HAL_FMPI2C_DisableListen_IT()
(+++) When address slave FMPI2C match, HAL_FMPI2C_AddrCallback() is executed and user can
add his own code to check the Address Match Code and the transmission direction request by master (Write/Read).
(+++) At Listen mode end HAL_FMPI2C_ListenCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_ListenCpltCallback()
(++) Sequential transmit in slave FMPI2C mode an amount of data in non-blocking mode using HAL_FMPI2C_Slave_Seq_Transmit_IT()
or using HAL_FMPI2C_Slave_Seq_Transmit_DMA()
(+++) At transmission end of current frame transfer, HAL_FMPI2C_SlaveTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_SlaveTxCpltCallback()
(++) Sequential receive in slave FMPI2C mode an amount of data in non-blocking mode using HAL_FMPI2C_Slave_Seq_Receive_IT()
or using HAL_FMPI2C_Slave_Seq_Receive_DMA()
(+++) At reception end of current frame transfer, HAL_FMPI2C_SlaveRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_SlaveRxCpltCallback()
(++) In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_ErrorCallback()
(++) Discard a slave FMPI2C process communication using __HAL_FMPI2C_GENERATE_NACK() macro.
This action will inform Master to generate a Stop condition to discard the communication.
*** Interrupt mode IO MEM operation ***
=======================================
[..]
(+) Write an amount of data in non-blocking mode with Interrupt to a specific memory address using
HAL_FMPI2C_Mem_Write_IT()
(+) At Memory end of write transfer, HAL_FMPI2C_MemTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MemTxCpltCallback()
(+) Read an amount of data in non-blocking mode with Interrupt from a specific memory address using
HAL_FMPI2C_Mem_Read_IT()
(+) At Memory end of read transfer, HAL_FMPI2C_MemRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MemRxCpltCallback()
(+) In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_ErrorCallback()
*** DMA mode IO operation ***
==============================
[..]
(+) Transmit in master mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Master_Transmit_DMA()
(+) At transmission end of transfer, HAL_FMPI2C_MasterTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MasterTxCpltCallback()
(+) Receive in master mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Master_Receive_DMA()
(+) At reception end of transfer, HAL_FMPI2C_MasterRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MasterRxCpltCallback()
(+) Transmit in slave mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Slave_Transmit_DMA()
(+) At transmission end of transfer, HAL_FMPI2C_SlaveTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_SlaveTxCpltCallback()
(+) Receive in slave mode an amount of data in non-blocking mode (DMA) using
HAL_FMPI2C_Slave_Receive_DMA()
(+) At reception end of transfer, HAL_FMPI2C_SlaveRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_SlaveRxCpltCallback()
(+) In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_ErrorCallback()
(+) Abort a master FMPI2C process communication with Interrupt using HAL_FMPI2C_Master_Abort_IT()
(+) End of abort process, HAL_FMPI2C_AbortCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_AbortCpltCallback()
(+) Discard a slave FMPI2C process communication using __HAL_FMPI2C_GENERATE_NACK() macro.
This action will inform Master to generate a Stop condition to discard the communication.
*** DMA mode IO MEM operation ***
=================================
[..]
(+) Write an amount of data in non-blocking mode with DMA to a specific memory address using
HAL_FMPI2C_Mem_Write_DMA()
(+) At Memory end of write transfer, HAL_FMPI2C_MemTxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MemTxCpltCallback()
(+) Read an amount of data in non-blocking mode with DMA from a specific memory address using
HAL_FMPI2C_Mem_Read_DMA()
(+) At Memory end of read transfer, HAL_FMPI2C_MemRxCpltCallback() is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_MemRxCpltCallback()
(+) In case of transfer Error, HAL_FMPI2C_ErrorCallback() function is executed and user can
add his own code by customization of function pointer HAL_FMPI2C_ErrorCallback()
*** FMPI2C HAL driver macros list ***
==================================
[..]
Below the list of most used macros in FMPI2C HAL driver.
(+) __HAL_FMPI2C_ENABLE: Enable the FMPI2C peripheral
(+) __HAL_FMPI2C_DISABLE: Disable the FMPI2C peripheral
(+) __HAL_FMPI2C_GENERATE_NACK: Generate a Non-Acknowledge FMPI2C peripheral in Slave mode
(+) __HAL_FMPI2C_GET_FLAG: Check whether the specified FMPI2C flag is set or not
(+) __HAL_FMPI2C_CLEAR_FLAG: Clear the specified FMPI2C pending flag
(+) __HAL_FMPI2C_ENABLE_IT: Enable the specified FMPI2C interrupt
(+) __HAL_FMPI2C_DISABLE_IT: Disable the specified FMPI2C interrupt
*** Callback registration ***
=============================================
[..]
The compilation flag USE_HAL_FMPI2C_REGISTER_CALLBACKS when set to 1
allows the user to configure dynamically the driver callbacks.
Use Functions HAL_FMPI2C_RegisterCallback() or HAL_FMPI2C_RegisterAddrCallback()
to register an interrupt callback.
[..]
Function HAL_FMPI2C_RegisterCallback() allows to register following callbacks:
(+) MasterTxCpltCallback : callback for Master transmission end of transfer.
(+) MasterRxCpltCallback : callback for Master reception end of transfer.
(+) SlaveTxCpltCallback : callback for Slave transmission end of transfer.
(+) SlaveRxCpltCallback : callback for Slave reception end of transfer.
(+) ListenCpltCallback : callback for end of listen mode.
(+) MemTxCpltCallback : callback for Memory transmission end of transfer.
(+) MemRxCpltCallback : callback for Memory reception end of transfer.
(+) ErrorCallback : callback for error detection.
(+) AbortCpltCallback : callback for abort completion process.
(+) MspInitCallback : callback for Msp Init.
(+) MspDeInitCallback : callback for Msp DeInit.
This function takes as parameters the HAL peripheral handle, the Callback ID
and a pointer to the user callback function.
[..]
For specific callback AddrCallback use dedicated register callbacks : HAL_FMPI2C_RegisterAddrCallback().
[..]
Use function HAL_FMPI2C_UnRegisterCallback to reset a callback to the default
weak function.
HAL_FMPI2C_UnRegisterCallback takes as parameters the HAL peripheral handle,
and the Callback ID.
This function allows to reset following callbacks:
(+) MasterTxCpltCallback : callback for Master transmission end of transfer.
(+) MasterRxCpltCallback : callback for Master reception end of transfer.
(+) SlaveTxCpltCallback : callback for Slave transmission end of transfer.
(+) SlaveRxCpltCallback : callback for Slave reception end of transfer.
(+) ListenCpltCallback : callback for end of listen mode.
(+) MemTxCpltCallback : callback for Memory transmission end of transfer.
(+) MemRxCpltCallback : callback for Memory reception end of transfer.
(+) ErrorCallback : callback for error detection.
(+) AbortCpltCallback : callback for abort completion process.
(+) MspInitCallback : callback for Msp Init.
(+) MspDeInitCallback : callback for Msp DeInit.
[..]
For callback AddrCallback use dedicated register callbacks : HAL_FMPI2C_UnRegisterAddrCallback().
[..]
By default, after the HAL_FMPI2C_Init() and when the state is HAL_FMPI2C_STATE_RESET
all callbacks are set to the corresponding weak functions:
examples HAL_FMPI2C_MasterTxCpltCallback(), HAL_FMPI2C_MasterRxCpltCallback().
Exception done for MspInit and MspDeInit functions that are
reset to the legacy weak functions in the HAL_FMPI2C_Init()/ HAL_FMPI2C_DeInit() only when
these callbacks are null (not registered beforehand).
If MspInit or MspDeInit are not null, the HAL_FMPI2C_Init()/ HAL_FMPI2C_DeInit()
keep and use the user MspInit/MspDeInit callbacks (registered beforehand) whatever the state.
[..]
Callbacks can be registered/unregistered in HAL_FMPI2C_STATE_READY state only.
Exception done MspInit/MspDeInit functions that can be registered/unregistered
in HAL_FMPI2C_STATE_READY or HAL_FMPI2C_STATE_RESET state,
thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
Then, the user first registers the MspInit/MspDeInit user callbacks
using HAL_FMPI2C_RegisterCallback() before calling HAL_FMPI2C_DeInit()
or HAL_FMPI2C_Init() function.
[..]
When the compilation flag USE_HAL_FMPI2C_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.
[..]
(@) You can refer to the FMPI2C HAL driver header file for more useful macros
This software component is licensed by ST under BSD 3-Clause license, the "License"; You may not use this file except in compliance with the License. You may obtain a copy of the License at: opensource.org/licenses/BSD-3-Clause
Definition in file stm32f4xx_hal_fmpi2c.c.
1.7.6.1