Home

CPAL v2 - STMicroelectronics

1. Error management CPAL drivers aim at managing all possible types of errors in order to offer the possibility for the application to handle them and for communication recovery when possible There are three types of error management Peripheral errors errors managed by the peripheral an interrupt is generated when the error occurs These errors are monitored by the CPAL driver and the application may use Error callbacks in order to perform specific actions for each error refer to Section 3 3 for more details about the error callbacks Communication errors they cannot be detected by the peripheral no interrupt flag generated when the error occurs Example external device disconnected in the middle of a communication session external device blocked by the last operation These errors are detected by the CPAL driver through the timeout mechanism refer to Section 3 3 1 for more details When a timeout is detected the Doc ID 023577 Rev 1 ky UM1566 How to use and customize the CPAL library step by step 4 5 4 5 1 4 5 2 4 5 3 CPAL_TIMEOUT_UserCallback function is called and then application may perform through this function the necessary operations used to recover from an error and restart communication correctly Advanced configuration In addition to the basic configuration some other parameters may be modified to customize the CPAL library These parame
2. 42 4 1 1 Select peripherals to be used 42 4 1 2 Configure transfer options 43 4 1 3 Select and configure user and error callbacks 43 4 1 4 Configure timeout management 43 4 1 5 Set Events Errors and DMA interrupt priorities 44 4 1 6 Configure the Log Macro 44 2 66 Doc ID 023577 Rev 1 ky UM1566 Contents 4 2 Structure initialization 45 4 3 C MMUNICAHOM wA NG eared Owe Ae AA 45 4 4 Error management 46 4 5 Advanced configuration 47 4 5 1 Select peripheral I O pins 47 4 5 2 Select TX and RX DMA channels 47 4 5 3 Set event error and DMA interrupt priorities 47 5 CPAL implementation example step by step 49 5 1 Starting point 49 5 2 stm32xxxx i2c cpal conf h 49 5 3 stm32xxxx i2c cpal usercallback c 51 5 4 MAIN ower BNG NAGA NA NGA NG eae bale Tae Ti NG 52 5 4 1 Variables and structures 52 5 4 2 Configuration
3. Doc ID 023577 Rev 1 ky UM1566 CPAL functional description sa delay has been elapsed and the CPAL TIMEOUT UserCallback function is called This function is already implemented in the CPAL library and could be called directly by the user application or mapped to an interrupt or a user function through the define in the stm32xxxx i2c cpal conf h file i e define CPAL 12C TIMEOUT Manager SysTick Handler The timeout user callback CPAL T3 MEOUT_UserCallback this function is called when the timeout condition occurs for any peripheral The user application may clear reset communication or peripheral or microcontroller depending on the situation Figure 9 CPAL 12C timeout manager flowchart CPA izo TEO Manager Na All devices checked no no wCPAL_Timeout 0 Xo Set wCPAL_Timeout to CPAL_I2C_TIMEOUT_DEFAULT v WCPAL Timeout CPAL 2C TIMEOUT DE Set CPAL State to CPAL STATE ERROR WCPAL DeveError CPAL 12C ERR NONE yes v Set wCPAL DeveError to CPAL 12C ERR TIMEOUT v FAULT v Decrement WCPAL Timeout Call CPAL_TIMEOUT_UserCallback End Doc ID 023577 Rev 1 41 66 How to use and customize the CPAL library step by step UM1566 4 4 1 42 66 How to use and customize
4. 8 2 2 1 CPAL main structures stm32xxxx_i2c_cpal h 9 2 2 2 CPAL communication functions stm32xxxx_i2c_cpal c 16 2 3 User applicationinterface 18 2 3 1 Configuration interface 18 2 3 2 User callback interface 22 2 4 Low layer interface hardware abstraction layer HAL 24 3 CPAL functional description 28 3 1 COMNGUISIION lt s oeiras ars Pace Reheat Aen ade DRA GG BAK KAANAK 28 3 1 1 CPAL_I2C_Init functional description 28 3 1 2 CPAL_I2C_Delnit functional description 29 3 1 3 CPAL 12C Structlnit functional description 31 3 2 COMMUNGCON aan TAS estes PAREN PA Rese LUNA oe Rhee ee 31 3 2 1 CPAL 12C Read functional description 32 3 2 2 CPAL 12C Write functional description 34 3 2 3 CPAL 12C Listen functional description 35 3 2 4 CPAL 12C IsDeviceReady functional description 35 3 2 5 CPAL interrupts and DMA management 36 3 3 Event and error management user callbacks 38 3 3 1 Timeout management 40 4 How to use and customize the CPAL library step by step 42 4 1 Basic configuration
5. 53 5 4 3 Communication 0 0 Wa 54 6 CPAL EXamples IIIA 55 6 1 Wakeup from Stop mode example 56 6 2 Two board example 56 6 3 Two board Listen mode example 57 7 Memory footprint of CPAL components 59 8 Frequently asked questions FAQ 61 9 Naming conventions 64 10 REVISION history IA ee BAWANG KG ed CORRE aaa 65 KYI Doc ID 023577 Rev 1 3 66 List of tables UM1566 List of tables Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 22 Table 23 Table 24 Table 25 4 66 Applicable products III IAA AAA 1 CPAL file descriptions 8 CPAL_InitTypeDef structure 10 CPAL Devfieldvalues 11 CPAL Direction field values 11 CPAL Mode field values 12 CPAL ProgModel field values 12 CPAL TransferTypeDef structure fields 12 CPAL State
6. CPAL_DirectionTypeDef Direction uint32 t Options This function initializes the DMA channels required for the buffer Tx Rx transfers related to the 1 C peripheral and specified by Direction and Option fields This function also configures and enables the required DMA clocks CPAL_I2C_HAL_DMADeInit CPAL_I2C_HAL_DMATXConfig CPAL_I2C_HAL_DMARXConfig CPAL_DevTypeDef Device CPAL_DirectionTypeDef CPAL_DevTypeDef Direction Device CPAL_TransferTypeDef TransParam eter uint32 t Options This function de initializes the DMA channels used by the 1 C peripheral and configures them to their default values The DMA clocks are not disabled by this function This function configures the DMA channels specific for Tx Rx transfer by setting the buffer address and the number of data to be transferred through the 1 C peripheral This function checks the following options CPAL_OPT_DMATX_CIRCULAR CPAL 12C HAL ITInit CPAL DevTypeDef Device uint32 t Options CPAL Direction TypeDef Direction CPAL ProgModelTypeDef ProgModel This function configures and enables the NVIC interrupt channels used by the IC peripheral according to the enabled options Interrupt DMA mode This function checks the following options CPAL OPT 12C ERRIT DISABLE CPAL OPT DMATX HTIT CPAL OPT DMARX HTIT 26 66 Doc ID 023577 Rev 1 ky UM1566
7. YYY is the pin function i e SCL SDA for 12C peripheral For each parameter set the define value to use the related configuration i e define CPAL_I2C1_SCL_GPIO_PORT GPIOB define CPAL_I2C1_SCL_GPIO_CLK RCC_APB2Periph_GPIOB define CPAI I2C1 SCI GPIO PIN GPIO Pin 6 define CPAL_I2C1_SCL_GPIO_PINSOURCE GPIO_PinSource6 For each I O one single configuration is allowed A table in the stm32xxxx_i2c_cpal h file shows the possible configurations for each I O and each peripheral Section 2 DMA Channels selection CPAL_I2CX_DMA_ZZ_Channel Where X is the peripheral instance 1 2 or 3 and ZZ is the transfer direction TX or RX Set the define values to configure the DMA channels for each peripheral and direction Only one define should be used for each peripheral channel direction A table in the stmM32xxxx_i2c_cpal h file shows the possible configurations for each DMA channel finally the 12C Event interrupts Preemption and Sub priorities are set depending on priority offsets I2CX_IT_OFFSET_PREPRIO and I2CX_IT_OFFSET_SUBPRIO defined in the stm32xxxx_i2c_cpal_contf h file Generally 12C Error interrupts should have the highest priority level then the DMA Transfer complete interrupts and Section 3 Peripheral and DMA interrupts priority selection I2CK IT WWW SUBPRIO Where X is the peripheral instance 1 2 or 3 and WWW is the peripheral interrupt or DMA
8. CPAL STATE READY TX This state is set when the related peripheral has triggered the communication procedure for transmission CPAL_STATE_READY_RX This state is set when the related peripheral has triggered the communication procedure for reception CPAL_STATE_BUSY This state is set when a write or read operation has been started but effective transfer on the peripheral has not started yet CPAL_STATE_BUSY_TX This state is set when a transmission transfer is ongoing for the related peripheral CPAL_STATE_BUSY_RX This state is set when a reception transfer is ongoing for the related peripheral CPAL_STATE_ERROR Table 10 field to determine which error occurred wCPAL DevError field values for I2C peripherals This state is set when an error occurs on the related peripheral or at CPAL driver level When this state is set the user application can check the wCPAL_DevError Field value CPAL 12C ERR NONE CPAL 12C ERR TIMEOU T This state indicates that a timeout occurred during the communication or configuration Description This is the default state of the error field It indicates that no peripheral error occurred phase Thus a specific time has elapsed without correct response event from the peripheral or the slave in Master mode CPAL 12C ERR BERR vi Itis cleared by software by setting BERRCF bit A bus error is detected when a START or a STOP co
9. CPAL architecture description Table 17 CPAL low layer interface function description continued Function name CPAL_ I2C_HAL_ITDeInit Argument type CPAL_DevTypeDef Argument name Device uint32_t Options CPAL_DirectionTypeDef Direction CPAL_ProgModelTypeDef ProgModel Description This function disables the NVIC interrupt channels used by the 1 C peripheral in the current configuration and according to the enabled options interrupt DMA mode This function checks the following options CPAL OPT I12C ERRIT DISABLE CPAL OPT DMATX HTIT CPAL OPT DMARX HTIT 4 Doc ID 023577 Rev 1 27 66 CPAL functional description UM1566 3 3 1 Note 3 1 1 28 66 CPAL functional description Configuration The whole CPAL configuration mechanism is based on a single structure CPAL_InitTypeDef holding all needed configuration information for each peripheral one structure for each peripheral as well as the current state of the communication and of the peripheral A default structure is declared by the CPAL for each peripheral And these default structures should be used by the customer application to configure and to monitor the peripheral Example the following structures are declared in stm32xxxx 12c cpal h file for the 12C peripherals extern CPAL InitTypeDef I2C1 DevStructure extern CPAL InitTypeDef I2C2_DevStructure The functions relate
10. C initialization structure pointer CPAL_I2C_StructInit pCPAL_I2C_Struct is set to a local structure CPAL 12C Init functions containing default values for the I C So this structure will be used by all C peripherals at the same time Any modification on it will affect all C peripherals To make sure that each peripheral is correctly configured declare a local structure for each one and assign it to the field pCPAL_I2C_Struct after calling CPAL_I2C_StructInit function Topic 3 Interrupts Priority group configuration may be modified by the CPAL driver To make sure that the priority group configuration corresponds to what you expect set its value in stm32xxxx i2c cpal conf h Section 5 Interrupt priority selection CPAL_NVIC_PRIOGROUP and remove any other settings of this parameter in your application CPAL Priority level is too high compared to other application interrupts that need to be processed faster In this case modify the offset value of the CPAL interrupt in stm32xxxx i2c cpal conf h file Section 5 Interrupt priority selection i e I2CX IT OFFSET SUBPRIO My program uses multiple interrupts When adding CPAL drivers to the application some all interrupts do not work correctly or do not work at all a 62 66 Doc ID 023577 Rev 1 UM1566 Frequently asked questions FAQ Table 24 Frequently asked questions continued No Question Possible answers solutions cannot
11. Ti UM1566 YA User manual STM32F0xx and STM32F3xx I2C communication peripheral application library CPAL v2 October 2012 Introduction The purpose of this document is to explain the architecture and the implementation of the PC CPAL v2 Communication Peripheral Application Library The CPAL v2 provides the same high layer API implemented in CPAL v1 thus you can migrate between these two libraries easily The CPAL v1 is a library which provides API for 2C peripherals of STM32F1 STM32F2 STM32F4 and STM32L 1 devices While CPAL v2 provides API for I C peripherals of STM32F0 and STM32F3 devices It provides CPAL drivers for communication peripherals and some examples showing how to use and customize the CPAL drivers The CPAL v2 drivers and examples are supplied within STM32FOxx STM32F37x and STM32F30x Standard Peripherals library the drivers are under LibrariesISTM32xxxx CPAL Driver and the examples under Project STM32xxxx_StdPeriph_Examples l2C Table 1 lists applicable products concerned by this user manual Table 1 Applicable products Type Part numbers Microcontrollers STM32F0xxxx and STM32F3xxxx Doc ID 023577 Rev 1 1 66 www st com Contents UM1566 Contents 1 CPAL overview ne si i i Ow 6 2 CPAL architecture description 7 2 1 CPAL application hierarchy 7 2 2 Communication layer
12. 36 66 a Doc ID 023577 Rev 1 UM1566 CPAL functional description Table 19 12C interrupt management order Interrupt Details Callback CPAL_I2C_GENCALL_UserCallback Manages the event Address phase done which means CPAL_I2C_DUALF_UserCallback ADDR that the device in mode slave received start bit followed by cpat 12C SLAVE READ UserCallback its own address and acknowledged it CPAL I2C SLAVE WRITE UserCallbac k Manages the event Not Acknowledge received flag which means the device received a NACK In master h a CPAL_I2C_AF_UserCallback mode this flag indicates an error slave don t respond to NACK 3 CPAL_I2C_ERR_UserCallback sent address In slave mode when master received all paaa data it send NACK to indicate to slave that all data are HG ma a received STOP Manages the event Stop bit received which means that cPAL 12c TXTc UserCallback the master has closed the communication CPAL I2C RXTC UserCallback For IC peripherals the Error interrupt has a dedicated IRQ channel different from the Event interrupt This means that errors can be managed asynchronously and independently of the communication events When DMA mode is selected with DMA interrupt options the following DMA interrupts are handled Transfer Complete interrupt Half Transfer Complete interrupt and Transfer Error interrupt Table 20
13. CPAL architecture description All Callbacks except when otherwise mentioned accept a single argument the pointer to the CPAL peripheral structure CPAL_InitTypeDef Thus it is possible to identify which peripheral called the function using field CPAL_Dev and to determine the current state and error using fields CPAL State and wCPAL_DevError All Callbacks return a void value void CPAL _I2C_XXXX_UserCallabck CPAL_InitTypeDef pDevInitStruct Caution Most of these functions except error callbacks are intended to perform rapid actions Implementing functions with a too long execution time may cause communication errors Table 15 CPAL configuration sections Callback Description Transfer callbacks CPAL_I2C_ZZ_UserCal Iback Where ZZ is the transfer direction TX or RX These functions are called before transmitting data TX and after receiving data RX on C peripheral CPAL 12C ZZTC User Callback Where ZZ is the transfer direction TX or RX These functions are called when the Transfer is completed in DMA or Interrupt programming model CPAL_I2C_DMAZZTC_ UserCallback Where ZZ is the transfer direction TX or RX These functions are called when the Transfer Complete interrupt occurs for the related transfer direction DMA channel CPAL_I2C_DMAZZHT_ UserCallback Where ZZ is the transfer direction TX or RX These functions are called when a Half Transfer interrupt occurs f
14. CPAL architecture description UM1566 2 When CPAL_I2C_Write function is called the user application may perform other tasks while the transfer is ongoing and the CPAL_State field can be used to monitor transfer Note 2 3 2 3 1 18 66 It is possible to configure and use more than one peripheral simultaneously since each peripheral has its own state control User application interface The user application interface consists of two files stm32xxxx_i2c_cpal_conf h and stm32xxxx_i2c_cpal_usercallback c which are described in the following sections These files may be modified by the user for each application need The CPAL library only provides templates for these files then the user should copy these templates into his project and optionally modify them according to the application needs Important notes AIC interrupt Handlers and all the DMA related interrupt Handlers are exclusively declared and managed by the CPAL library The user application does not need and should not declare these interrupt handlers If these handlers are needed for other purposes i e DMA interrupt shared between several peripherals the user application may use the related callbacks e Interrupt priority groups and preemption orders are also managed by the CPAL driver To configure these parameters modify the stm32xxxx_i2c_cpal_conf h file Configuration interface The configuration interface allows you to customize the library fo
15. DMA interrupt management order Order Interrupt Details Callback Manages the DMA event Transfer Complete which CPAL I2C DMATXTC UserCallback 1 TC means that all data programmed in DMA controller ji have been transferred transmitted received CRAL TAC DMARATO Userca back Manages the DMA event Half Transfer Complete which means that half of the data programmed in CPAL_I2C_DMATXHT_UserCallback 2 HT 1 DMA controller has been transferred CPAL 1I2C DMARXHT UserCallback transmitted received Manages the event DMA Transfer Error which l CPAL_I2C_DMATXTE_UserCallback 3 TE means that an error occurred during the DMA Ta ee J w CPAL_I2C_DMARXTE_UserCallback transfer All errors lead to a single operation call CPAL_I2C_ErrorHandler 4 The CPAL_I2C_ErrorHandler function handles all peripheral errors and timeout errors DMA errors are managed by CPAL_I2C_DMATXTE_UserCallback and CPAL_I2C_DMARXTE_UserCallback functions This function performs the basic error recovery operations clears the error flag and source if possible resets the CPAL peripheral state and then calls the user error callback Doc ID 023577 Rev 1 37 66 CPAL functional description UM1566 3 3 Event and error management user callbacks As mentioned in previous sections the CPAL allows the user application to control the communication and to perform specific actions triggered by specific communication errors
16. peripheral Error detection and recovery when possible through peripheral error detection and timeout mechanism Bug fixes and workaround selection Different device families What is the cost of using CPAL drivers in term of code size and performance As a generic driver CPAL may involve a significant firmware overhead But different customization levels allow you to reduce code size by removing any unused feature CPAL drivers use the standard peripheral drivers only for initialization phase For the communication phase only direct register access using macros is used which improves significantly the driver performance How many files should modify to configure the CPAL drivers CPAL library offers multiple levels of customization 0 file No file needs to be modified you can use the one of the provided examples without any modification in configuration files In this case the code size of the application may be too large To reduce CPAL code size you may check the next case 1 file In most cases only one file needs to be modified stm32xxxx i2c cpal conf h You can modify this file by disabling unused features or adjusting some parameters i e interrupt priority groups timeout mechanism 2 files In addition to the stm32xxxx i2c cpal conf h file you can customize the CPAL library hardware layer by modifying the file stm32f30x i2c cpal hal h Through this file you can modi
17. returns the CPAL_PASS value then the external device is ready to communicate Otherwise the external device is not ready or the bus is not free device error may be set in this case and the related callback may be used to manage the error Then to send or receive data follow the steps below e Re configure the structures pointed by pCPAL_TransferTx pCPAL TransferRx with the valid values of buffer pointer number of data and optional addresses refer to Doc ID 023577 Rev 1 45 66 How to use and customize the CPAL library step by step UM1566 4 4 46 66 Table 8 CPAL_TransferTypeDef structure fields for more details If the structure is already prepared or when DMA circular mode option is enabled there is no need to perform this operation Check the state of the peripheral wCPAL State field of the 12cx DevStructure If this state is different from CPAL STATE READY then either the peripheral is communicating or an error occurred In both cases it is not possible to use the peripheral in the current state The application may call CPAI 12C Delnit in this case to return to its default state and restart communication It is also possible to check the state by directly calling CPAL 12C Read CPAL 12C Write function if this function returns a value different from CPAL PASS then the current state does not allow communication or an error occurred as explained above Call CPAL 12C Read CPAL 12C Write functio
18. DMA Request Return N um N BRAL PAOS Y Ne CPAL_FAIL AA 34 66 Doc ID 023577 Rev 1 kr UM1566 CPAL functional description 3 2 3 3 2 4 CPAL 12C Listen functional description The CPAL_I2C_Listen function is only used with slave device when Listen mode is activated If this function is called in master mode the device is forced to slave mode CPAL_I2C_Listen function replace CPAL_I2C_Read and CPAL I2C Write functions for Slave mode Code source overload of CPAL Library is reduced when Listen mode is used when Master mode is disabled code source will decrease significantly When CPAL 12C Listen function is called slave enters in idle state and waits until it receive its own address In ADDR routine of the slave mode CPAL 12C SLAVE READ UserCallback or CPAL 12C SLAVE WRITE UserCallback is called depending on type of received request In these Callbacks user must configure transfer parameters and DMA or Interrupts in accordance with selected programming model Figure 8 CPAL 12C Listen function flowchart a CPAL I2C Listen k J Master Mode yes y Switch to Slave mode no v Set State to Busy Vv Enable Transfer Interrupt fea Return N Return CPAL_PASS J a FAIL CPAL_I2C_IsDeviceReady functional description The CPAL_I2C_IsDeviceRead
19. Disable the GPIO ports and pins used for the I2Cx peripheral reset to default state Disable the I2Cx peripheral and its APB clock Disable the DMA and or the interrupts and their related clocks and channels depending on the current values of fields CPAL_ Direction CPAL ProgModel and o CPAL_STATE_D CPAL_FAIL value o e wCPAL_Options Figure 5 CPAL 12C Delnit function flowchart CPAL 12C Delnit State is Disabled Ready Error Disable the I2Cx device and all ressources clocks y Configure all IO pins used by I2Cx device to their default state DMA Programming Model yes v Deinitialize DMA channels used by I2Cx device no v Deinitialize Interrupt channels used by I2Cx device Delnitialize Timeout mechanism Return U CPAL FAIL e a Doc ID 023577 Rev 1 UM1566 CPAL functional description 3 1 3 CPAL_I2C_Structlnit functional description The default values could be used for the peripheral configuration by setting the l2Cx DevStructure structure fields to their default values using the function CPAL 12C StructiInit This function sets the default values as detailed in the following table Table 18 CPAL 12C Struct Init default values Field Default value CPAL Dev CPAL_I2C1 CPAL Direction CPAL_DIRECTION_TXRX CPAL Mode CPAL MODE MASTER CPAL P
20. These functions allow user application to perform specific actions relative to specific communication events errors e Provide device abstraction layer CPAL library supports all STM32 device families e Provide efficient and simple debug feature through CPAL_DEBUG option debug messages are sent through customizable macro Log messages are sent at each step of the CPAL driver this macro can be customized to send messages through serial interface debug IDE interface LCD screen e In order to optimize CPAL driver performances all operations except device initialization are preformed through direct register access Doc ID 023577 Rev 1 ky UM1566 CPAL architecture description 2 CPAL architecture description 2 1 CPAL application hierarchy The CPAL library consists of three layers User Application interface allows the customization of CPAL library besides of user callbacks implementation This layer consists of files which user may modify according to application requirements Communication Layer contains the communication API for each device I2C HAL Layer is a Hardware Abstraction Layer HAL that allows controlling the different devices registers independently of the device family Each layer is described in more details in the following sections Figure 1 CPAL library architecture Communication layer s2 355 239 HAL layer Ba STM32 microcontroller MS19802V1 Note The CPAL libr
21. can be called CPAL I2C MAST ER MODE Uncomment this define to enable Slave mode use for IZC peripherals When this define is commented none of slave mode features and operations can be called CPAL I2C SLAV E MODE Uncomment this define to enable Listen mode for use by IC slave peripherals by calling the CPAL 12C Listen function When this define is uncommented CPAL_I2C_Read and CPAL_I2C_Write functions can be used only with master mode CPAL I2C LIST EN MODF Uncomment this define to enable the use of DMA for data transfers When this define is commented DMA programming model cannot be used CPAL 1I2C DMA PROGMODEL Uncomment this define to enable the use of Interrupt mode for data turnovers When this define is commented all interrupt management code is disabled except for events and error management CPAL_I2C_IT_PROGMODEL This option is used to allow the code to handle10 bit addressing mode When this option is enabled it does not mean that all C peripherals communicate in 10 bit addressing mode to select this mode for an IC peripheral the user has to enable the related option in the CPAL structure field CPAL 1I2C 10BIT ADDR MOD EH This option is valid only when CPAL OPT NO MEM ADDR option is disabled It enables the code managing the 16 bit addressing mode for the register physical address into slave memory When this option is
22. define CPAL_DEBUG ifdef CPAL_DEBUG define CPAL LOG Str printf Str else define CPAI LOG Str void 0 endif CPAL DEBUG And in the user application define the printf function ifdef __GNUC__ With GCC RAISONANCE small printf option LD Linker gt Libraries gt Small printf set to Yes calls __io_putchar define PUTCHAR_PROTOTYPE int _ io_putchar int ch else define PUTCHAR_PROTOTYPE int fputc int ch FILE f endif __GNUC__ Doc ID 023577 Rev 1 ky UM1566 How to use and customize the CPAL library step by step 4 2 Caution 4 3 Structure initialization All CPAL functions use peripheral configuration structures 12Cx DevStructure to control and monitor all communication and configuration operations Consequently before using any function of the CPAL the related peripheral structure has to be set For each peripheral a predefined structure is declared into the CPAL driver This structure has to be used into the application for any configuration or monitoring purposes no declaration is needed for these structures as they are already exported by CPAL drivers Example CPAL_InitTypeDef I2C1_DevStructure CPAL_InitTypeDef I2C2_DevStructure There are three ways to set configuration structures e Use default configuration to use the predefined default configuration call the function CPAL_I2C_StructInit which will set the default values detailed in Tab
23. disabled related define is commented in stm32xxxx 12c cpal conf h file define CPAL 16BIT REG OPTION Then setting the option CPAL OPT 16BIT REG to the wePAL Options has no effect Select and configure user and error callbacks This section allows a selection of the callbacks which will be implemented by the user application To implement a callback in your application comment the related callback define in this section and then implement the body of the callback in your application the prototype is already declared in the CPAL driver For more details about user callbacks refer to Section 3 3 Configure timeout management This section is used to configure the timeout mechanism Timeout mechanism may be not used in this case CPAL will not handle communication errors and will handle only peripheral errors which generate error interrupts In this case you have to define the timeout callbacks as void functions i e define CPAL TIMEOUT UserCal1back void To use the Timeout mechanism which offers a higher level of communication security a counter peripheral function should be used in order to call the CPAL 12C TIMEOUT Manager function at each tick preferably each 1 ms and through a high priority interrupt If the counter is implemented using an interrupt then the associated interrupt channel must be set to a priority level strictly higher than all the CPAL interrupt
24. enabled it does not mean that all devices will communicate in 16 bit register physical addressing mode to select this mode for a peripheral the user has to enable the related option in the CPAL structure field CPAL 16BIT REG OPTION Section 3 User callback configuration Generic description this section contains all User Callbacks defined in the CPAL library User Callbacks are functions that are called from CPAL library internal layers and may be implemented by the user in order to perform specific actions after specific events Only their prototypes are declared in the CPAL library To enable and use a callback comment the related define in stm32xxxx i2c cpal conf h file then implement the callback body into stm32xxxx i2c cpal usercallback c file callback prototype is already declared in CPAL library For more details about callbacks refer to Section 2 3 2 Caution Most of these functions except error callbacks are intended to perform short actions Implementing functions with a too long execution time may cause communication errors vi Doc ID 023577 Rev 1 19 66 CPAL architecture description UM1566 Table 14 CPAL configuration sections continued Section Section 4 Timeout configuration 20 66 CPAL_TIMI Options CPAL_TIMI EOUT_INIT FOUT DEINIT Doc ID 023577 Rev 1 Description This macro is used by the CPAL drivers to configure and en
25. events through the callback functions Into all CPAL communication layer drivers in strategic places some functions are called The prototypes of these functions are declared into the CPAL drivers but they are not implemented The user application may implement and use them when needed refer to Section 3 User callback configuration for more details about callback configurations To know at which level a callback function is called refer to Section 3 2 5 All User Callbacks are optional if a callback is not implemented its define should be uncommented in the stm32xxxx 12c cpal conf h file then it will be defined as a void function and will not impact the code or the functionality of the driver All Callbacks accept a single argument the pointer to the CPAL Peripheral structure CPAL_InitTypeDef Thus it is possible to identify which peripheral called the function using field CPAL Dev and to determine the current state and error using fields CPAL State and wCPAL_DevError All Callbacks return a void value void CPAL_I2C_XXXX_UserCallback CPAL_InitTypeDef pDevInitStruct Caution Callbacks except error callbacks are used to perform short operations If a callback function takes a too long execution time it may lead to communication errors due to the inserted delay This is not applicable for Error callbacks since in this case communication is already stopped The list of all available callbacks and the
26. for the communication peripheral I O pins Clocks Interrupt vectors DMA channels are internally managed by the CPAL low layer drivers The communication operations are also managed internally by the CPAL drivers communication headers address sending Interrupt and DMA control error management All operations are controlled and monitored through a single configuration structure one structure instance for each device holding all necessary configuration parameters device configuration buffers addresses and sizes as well as the current communication status and error codes e Provide efficient and complete management of device and communication errors Device events and errors are managed by the CPAL low layer drivers and allow user to integrate easily a specific code for each event and error Communication errors are also managed by a timeout mechanism that can be customized by user application e Provide high customization and integration level Several static configurations allow reducing code size when some options are not used i e Reduce the number of used devices disable management of some modes 10 bit addressing General call Dynamic and easy configuration through a unique control structure allowing dynamically enabling disabling device and communication options Several user callbacks functions declared and called by the CPAL drivers and implemented by user application when needed
27. not available the CPAL debug feature may be enabled using the USART or LCD interface For the USART and LCD you need to enable the define CPAL_DEBUG and then in the user application the printf function must be retargeted to the USART or LCD Doc ID 023577 Rev 1 ky UM1566 CPAL implementation example step by step Example for USART interface ifdef __GNUC__ With GCC RAISONANCE small printf option LD Linker gt Libraries gt Small printf set to Yes calls __io_putchar define PUTCHAR PROTOTYPE int _ io_putchar int ch else define PUTCHAR_PROTOTYPE int fputc int ch FILE f endif GNUC brief Retargets the C library printf function to the USART param None retval None PUTCHAR_PROTOTYPE Place your implementation of fputc here e g write a character to the USART USART SendData EVAL COM1 uint8_t ch Loop until the end of transmission while USART GetFlagStatus EVAL COM1 USART FLAG TC RESET O return ch Note The debug feature uses a large amount of Flash memory space due to the debug message definitions Also if the USART LCD interface is too slow it may significantly impact the behavior of the CPAL driver in some cases communication may be corrupted So make sure that the debug interface USART LCD is fast enough to avoid impacting the behavior of the CPAL driver 5 3 stm32xxxx_i2c_cpal_usercallback c 4 In this file all us
28. that contains the User Callback implementations when sercallback template needed If no callback implementation is needed this file may be c not used comment out the unused functions Communication Contains the main structure definitions and the global CPAL stm32xxxx_i2c_cpal h structure declaration as extern It also contains all option definitions and the peripheral specific error definitions This file contains the main operation functions for the peripheral layer eae 5 1 Init Delnit Read Write It also contains all the peripheral RAMA 14C_CPa C related interrupt handlers peripheral and DMA interrupts as well as the error management functions stm32xxxx_i2c_cpal_h This file provides low layer functions specific to the device family al c for controlling the IC peripheral Hardware This file provides low layer configuration options I O selection Abstraction Layer 2 2 8 66 DMA channel selection Interrupt configuration as well as low layer macros used for peripheral control This file may be modified by the user when needed to use different I Os DMA channels stm32xxxx_i2c_cpal_h al h Communication layer The CPAL communication layer interface contains all the needed functions APIs that can be called by the user application It consists of the following files stm32xxxx_i2c_cpal h e stm32xxxx_i2c_cpal c Important notes All IZC interrupt handl
29. the CPAL library step by step The CPAL library offers several configuration and customization levels Some configurations are static defines in stm32xxxx i2c cpal conf h file and others are dynamic peripheral configuration structure field assignment Most configuration and customization steps are optional default configuration or a subset of default configuration may be used instead of setting all parameter values The following sections explain all the steps needed to configure customize and implement the CPAL library into a user application Basic configuration The first step optional is to set the configuration of the peripheral and the CPAL driver This step can be done through the modification of the stm32xxxx 12c cpal conf h refer to Section 2 2 1 for detailed description file which contains all the configurable parameters of the peripheral and CPAL library Important notes AIC interrupt Handlers and all the related DMA interrupt Handlers are exclusively declared and managed by the CPAL library The user application does not need and should not declare these interrupt handlers If these handlers are needed for other purposes i e DMA interrupt shared between several peripheral etc the user application may use the related callbacks e Interrupt priority groups and preemption orders are also managed by the CPAL driver To configure these parameters modify the stm32xxxx_i2c_cpal_conf h file The stm32xxxx 12c cp
30. the IC peripheral All peripherals of the same type i e all IC peripherals share the same error callback The user has to check which peripheral caused the entering in this callback ERROR CALLBACK option is enabled 4 Doc ID 023577 Rev 1 23 66 CPAL architecture description UM1566 Table 15 CPAL configuration sections continued Callback CPAL I2C WWW Use rCallback Description Where WWW is the peripheral error i e BERR ARLO OVR These callbacks are valid only when USE_MULTIPLE_ERROR_CALLBACK option is enabled These functions are called when the related error occurs on the 1 C peripheral All peripherals of the same type i e all IC peripherals share the same error callback The user has to check which peripheral caused the entry into this callback Address mode callbacks CPAL_I2C_GENCALL_ UserCallback This callback is valid only when CPAL_OPT_I2C_GENCALL is enabled see Section 3 CPAL functional description and when BC is configured in Slave mode This function is called when a General call event occurs on an 1 C peripheral CPAL_I2C_DUALF_Us erCallback This callback is valid only when CPAL_OPT_I2C_DUALADDR is enabled see Section 3 CPAL functional description This function is called when a slave 1 C peripheral is configured to support dual addressing mode and receives correctly its second address from the master Listen Mode callbacks CPAL 1
31. 132 disabled CPAL 12C IT PROGMODEL Interrupt Mode disabled All other options enabled 4359 200 disabled ere mode disabled All other options CPAL I2C MEM ADDR disabled 4083 200 enabled 16 Bit Addressing mode disabled All other options CPAL 16BIT REG OPTION 2 4347 200 enabled disabled 10 Bit Addressing mode disabled All other options CPAL_I2C_10BIT_ADDR_MODE 4615 200 2 enabled disabled 1 Only option code size is taken into consideration considering configuration for 2 devices 2 All options enabled for 2 devices 60 66 Doc ID 023577 Rev 1 a UM1566 Frequently asked questions FAQ 8 Frequently asked questions FAQ This section gathers some of the most frequent questions CPAL users may ask It gives some solutions and tips Table 24 Frequently asked questions No Topic Question 1 General Possible answers solutions Why would use the CPAL driver rather than a standard peripheral library The main advantage of using the CPAL library is the ease of use you can use CPAL driver to control the IC interface without any knowledge about IC protocol CPAL library also offers a higher level of abstraction allowing the transparent management of Hardware components used by communication peripherals I Os DMA interrupts Transfer buffers and status managed through independent structures Peripheral states i e event management for IC
32. 2C SLAVE XX XX UserCallback Where XXXX is the requested operation Read or Write These functions are called when Slave is in Listen mode and receives its own address 2 4 Low layer interface hardware abstraction layer HAL The low layer interface is a hardware abstraction layer allowing the CPAL library to be hardware independent and allowing the user to modify update or configure hardware sections easily and efficiently It consists of the following files where xxxx the family identifier for example stm32f0xx e stm32xxxx_i2c_cpal_hal c e stm32xxxx_i2c_cpal_hal h All hardware components i e I O pin names clock enable defines DMA channels are stored in different tables one table for each parameter and one cell for each device This allows hardware configuration to be easily updated regardless of hardware modifications and supported device numbers Some hardware configurations may be modified using the stm32xxxx_i2c_cpal_hal h configuration sections 24 66 a Doc ID 023577 Rev 1 UM1566 CPAL architecture description The supported configurations are listed in the following table Table 16 HAL configuration sections Section Section 1 Peripheral pin selection Options CPAL_I2CX_YYY_GPIO_PORT CPAL_I2CX_YYY_GPIO_CLK CPAL_I2CX_YYY_GPIO_PIN CPAL_I2CX_YYY_GPIO_PINS OURCE Description Where X is the peripheral instance 1 2 or 3
33. 7 Rev 1 ky UM1566 CPAL functional description 3 1 2 4 Figure 4 CPAL_I2C_Init function flowchart C CPAL 12C Init gt State is Disabled Ready Error Disable the 12C device and all ressources clocks Y Configure and enable all IO Ports and pins used by 12Cx device y Configure I2Cx device DMA Programming Model yes y Configure and Enable DMA channels used by 1204 device AA Configure and Enable Interrupt channels used by I2Cx device v Initialize Timeout mechanism Return CPAL PASS CPAL 12C Delnit functional description Return CPAL FAIL When the communication transfer is over or when the application has to abort the peripheral operations the CPAL_I2C_DeInit function can be called to free all the resources used by the peripheral in the current configuration and return to default values Doc ID 023577 Rev 1 29 66 CPAL functional description UM1566 30 66 The CPAL_I2C_DeInit function performs the following actions Check the state of the CPAL peripheral Ifthe state is CPAL STATE READY or CPAL STATE ERROR or SABLED the operation is performed and then the function exits and returns CPAL_PASS value Ifthe state is different from the states above then the function exits and returns
34. AL USE I2C2 The CPAL configuration structure is defined as follows typedef struct f CPAL DevTypeDef CPAI Dev CPAL DirectionTypeDef CPAL Direction CPAL ModeTypeDef CPAL Mode CPAL ProgModelTypeDef CPAL_ProgModel CPAL_TransferTypeDef pCPAL_TransferTx CPAL_TransferTypeDef pCPAL_TransferRx IO CPAL_StateTypeDef CPAL State IO uint32 t WCPAL DevError uint32_t wCPAL_Options IO uint32 t WCPAL Timeout I2C_InitTypeDef pCPAL I2C Struct CPAL InitTypeDef Doc ID 023577 Rev 1 9 66 CPAL architecture description UM1566 The structure fields are detailed in Table 3 Table 3 CPAL_InitTypeDef structure Field type CPAL_DevTypeDef Field name CPAL_Dev Description This field specifies the peripheral to be configured and controlled by this structure CPAL_DirectionTypeDef CPAL Direction This field specifies the transfer directions that are to be supported for the related peripheral transmission only reception only or both directions This parameter does not indicate the direction of the current transfer but only the directions supported by the peripheral Any value listed in Table 5 can be assigned to this field CPAL_ModeTypeDef CPAL Mode Select the operating mode for the peripheral Master mode or Slave mode This mode determines if the peripheral initiates the transfer or waits till it receives transfer data from another master Any value
35. Channel DMA1 Channe16 define CPAL I2C1 DMA RX Channel DMA1 Channe17 Set event error and DMA interrupt priorities This section is used to set individual interrupt channel priorities for all used interrupts Interrupt priorities are configured relatively to an offset defined in stm32xxxx i2c cpal conf h file 12cx IT OFFSET SUBPRIO and 2CX IT OFFSET PREPRIO Doc ID 023577 Rev 1 47 66 How to use and customize the CPAL library step by step UM1566 48 66 Generally the following interrupt priority order should be applied For I2C peripherals error interrupts should have the highest priority level then DMA interrupts allowing the application to close communication and finally the IC event interrupts If the Timeout mechanism is implemented with an interrupt channel then make sure that its interrupt priority is higher than any other CPAL interrupt priority Doc ID 023577 Rev 1 ky UM1566 CPAL implementation example step by step 5 CPAL implementation example step by step This section describes all steps for using and customizing CPAL library to build a project from scratch It uses a real example an application with the requirements described below e Use two I Cs I2C1 and 12C2 to control an EEPROM memory and a temperature sensor each on separate I C bus e EEPROM memory is used for read write at fixed addresses Temperature sensor has a unique register
36. Cx The possible values for this field depend on the peripherals available in the microcontroller and the enabled defines CPAL_USE_I2Cx in the stm32xxxx i2c cpal conf h file Table 5 CPAL_Direction field values Field value Description CPAL_DIRECTION_TX This value allows only transmission transfers for the selected peripheral CPAL_DIRECTION_RX This value allows only reception transfers for the selected peripheral CPAL DIRECTION TXRX This value allows both transmission and reception transfers for the selected peripheral 4 Doc ID 023577 Rev 1 11 66 CPAL architecture description UM1566 Table 6 CPAL_Mode field values Field value CPAL_MODE_MASTER Description When this value is selected for the peripheral then it is configured in Master mode and it initiates the transfers for example generate the communication clock the slave address CPAL_MODE_SLAVE When this value is selected for the peripheral then it is configured in Slave mode and it waits till a master initiates the transfer Table 7 CPAL_ProgModel field values Field value CPAL_PROGMODEL_ INTERRUPT Description When this value is selected for the peripheral then all data transfer is managed by the peripheral interrupt IRQ handlers implemented in the CPAL library The user application then only has to monitor the status of the transfer through the status fields CPAL_PROGMODEL_ D
37. EINIT SysTick gt CTRL 0 define CPAL_I2C_TIMEOUT_Manager SysTick_Handler define CPAL I2C TIMEOUT TC 5 define CPAL I2C TIMEOUT TCR 5 define CPAL I2C TIMEOUT TXIS 5 define CPAL I2C TIMEOUT BUSY 5 Set Events Errors and DMA interrupt priorities This section can be used to configure the global priority level offset for each 12Cx peripheral This offset sets the peripheral interrupt priority levels in the file stm32xxxx_i2c_cpal h file If the Timeout mechanism is implemented with an interrupt channel then make sure that its interrupt priority is higher than any other CPAL interrupt priority Configure the Log Macro The CPAL library offers an internal debugging mechanism based on messages printed for most operations performed by CPAL driver The printed messages may be mapped to an IDE log window to an LCD screen to a USART interface RS232 To enable this feature the define CPAL_DEBUG should be enabled and the log macros CPAL_LOG should be mapped to a user printing function Be aware that using this feature may slow down the execution of the CPAL operations and may even affect in some cases the communication The CPAI LOG function should be optimized to perform fast print operation in order to minimize the impact of this feature on the communication Example Implementation of CPAL_LOG with print function modified to send data through a USART interface to a Hyperterminal application
38. MA When this value is selected for the peripheral then all data transfer is managed by the peripheral related DMA channel This is the most optimized transfer mode which allows high transfer rates and frees the CPU for other user application tasks In this case the user application has to monitor DMA channel flags or interrupts CPAL provides appropriate callbacks for managing DMA events Note For PC peripherals DMA cannot hanale 1 byte buffer transfers So when DMA mode is configured and the buffer size is equal to 1 then DMA mode is disabled and interrupt mode is enabled for this transfer At the end of the 1 byte transfer DMA mode is re enabled and interrupt mode is disabled Table 8 CPAL_TransferTypeDef structure fields Field type uint8_t Field name Description This field should contain the pointer to the buffer to be written to or read from Even when the transfer buffer format is not Byte format this pointer should be casted to Byte format The user has to set the value of this field at the start of each transfer Then the CPAL drivers update it according to the current transfer status In Interrupt mode this field is updated incremented at each data transmission or reception In DMA mode this field is updated only at the end of the current transfer pbBuffer uint32 t 12 66 This field should contain the number of data to be transferred regardless of their format Byte or Half
39. TM32xxxx is used to refer to STM32FOxx STM32F37x and STM32F30x devices Doc ID 023577 Rev 1 ky UM1566 Revision history 10 Revision history Table 25 Document revision history Date 25 Oct 2012 Revision 1 Initial release Changes Doc ID 023577 Rev 1 65 66 UM1566 Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or implied by estoppel or otherwise to any intellectual property rights is granted under this document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property co
40. Word or Word The number of data to be transferred is related only to the peripheral format configuration 8 bit or 16 bit or 32 bit The user has to set the value of this field at the start of each new transfer Then the CPAL drivers update it according to the current operations You can check this field to know how many data have been transferred In Interrupt mode this field is updated decremented by the CPAL drivers at each data transmission or reception In DMA mode this field is updated by the CPAL drivers only at the end of the transfer wNumData ky Doc ID 023577 Rev 1 UM1566 CPAL architecture description Table 8 CPAL_TransferTypeDef structure fields Field type Field name Description In Master mode this field specifies the address of the slave to uint32_t wAddr1 communicate with In Slave mode This field is not used In Master mode this field specifies the physical register address ji ji to be written to or read from into the slave for ekample for uint32_t wages memory devices In Slave mode this field is not used Table 9 CPAL State field values Field value Description CPAL STATE DISABLED This state is the default state of the CPAL driver It is set when the related peripheral is disabled not initialized and all related resources are free CPAL STATE READY This state is set when the related peripheral is initialized and all its resources are assigned
41. XTC_UserCallback CPAL_InitTypeDef pDevInitStruct APPTransferComplete 1 assuming that APPTransferComplete is global variable used by the application APP ToggleLED User application function that informs user of the end of an operation by toggling LEDs return x4 brief Manages the End of Tx transfer event param pDevinitStruct retval None y void CPAL_I2C_TXTC_UserCallback CPAL_InitTypeDef pDevInitStruct APPTransferComplete 1 assuming that APPTransferComplete is global variable used by application APP_ToggleLED User application function that informs user of the end of an operation by toggling LEDs return All other non used callbacks should be kept commented main c In this file the application uses the CPAL driver functions to configure the I C interface and then control it to communicate with the EEPROM and Temperature Sensor Variables and structures In order to send and receive data the application needs local transfer structures CPAL local transfer structures 2 structures for EEPROM and 1 Rx structure for Temperature Sensor CPAL TransferTypeDef sEERxStructure SEETxStructure sTSRxStructure uint8 t tEERxBuffer 255 tEETxBuffer 255 TSData Doc ID 023577 Rev 1 a UM1566 CPAL implementation example step by step 5 4 2 Configuration First the transfer and configuration structures should be filled Initiali
42. able a timeout countdown mechanism i e using SysTick It is called at each initialization of a CPAL peripheral when calling CPAL 12C Init function The timeout counter functions as follows The counter generates fixed period ticks and calls CPAL 12C TIMEOUT Manager callback at each tick The CPAL 12C TIMEOUT Manager checks the value of wCPAL_Timeout of all the available 1 C peripheral structures If wCPAL_Timeout CPAL 12C TIMEOUT DEFAULT then no action is performed If wCPAL_Timeout CPAL 12C TIMEOUT MIN then the CPAL structure state is set to CPAL STATE ERROR and CPAL TIMEOUT UserCallback is called to manage the error fwCPAL Timeout has any other value the function decrements its value by 1 and exit The User may implement his own timeout mechanism i e using SysTick timer or other timers The counting unit should preferably be set to 1 millisecond ms This function should configure the counting unit and enable the counting start Other timeout initialization procedures may be implemented depending on application needs This macro is used to deinitialize the countdown mechanism It is called whenever a peripheral is deinitialized when calling CPAL_I2C_DeInit function Other timeout initialization procedures may be implemented depending on application needs This function may be performed for each peripheral separately a UM1566 CPAL architecture
43. al conf h file is divided into independent sections Section 1 Select peripherals to be used Section 2 Configure transfer options Section 3 Select and configure user and error callbacks Section 4 Configure timeout management Section 5 Global interrupt priority offsets Section 6 Configure the log macro Select peripherals to be used The first section of stm32xxxx 12c cpal conf h allows a selection of the peripherals which will be used and enabled by the CPAL library When a peripheral is not used its related define should be commented in order to save memory space and execution time Example 12C1 used and I2C2 not used define CPAL USE I2C1 lt Uncomment to use I2C1 peripheral define CPAL USE 12C2 lt Uncomment to use I2C2 peripheral Doc ID 023577 Rev 1 ky UM1566 How to use and customize the CPAL library step by step 4 1 2 Caution Configure transfer options This section allows a choice of some transfer options Transfer options are different from the options set to the wePAL Options field of the CPAL peripheral structures The transfer options are static defines which are used to remove the section of code handling the related communication option and thus to reduce the code size When a transfer option is disabled all the related code in the CPAL driver is disabled so the option is no more available for the wcPAL_Options field For example if the CPAL_16BIT_REG_OPTION option is
44. amp I12C2_DevStructure Set all fields to default values I2C2 DevStructure CPAL Mode CPAL MODE MASTER I2C2 DevStructure CPAL ProgModel CPAL_PROGMODEL_INTERRUPT I2C2 DevStructure pCPAL I2C Struct 512C Timing 0xC062121F 50 KHz I2C2 DevStructure pCPAL TransferRx amp SEERxStructure I2C2 DevStructure pCPAL TransferTx pNULL Not needed Initialize CPAL peripheral with the selected parameters CPAL_I2C_TInit amp I12C2_DevStructure 4 Doc ID 023577 Rev 1 53 66 CPAL implementation example step by step UM1566 5 4 3 54 66 Communication In the example below each peripheral communication will be managed in separate code sections Then each section could be implemented in a single infinite loop in separate interrupt handlers in tasks This only depends on the application architecture Write 100 data to EEPROM at address 0x30 sEETxStructure wNumData 100 Number of data to be written sEETxStructure wAddr2 0x30 Address into EEPROM if CPAL I2C Write s12C1 DevStructure CPAL PASS I2C bus or peripheral is not able to start communication Error management Wait the end of transfer while I2C1_DevStructure gt CPAL State CPAL STATE READY Read temperature value sTSRxStructure wNumData 1 if CPAL_I2C_Read amp I2C2_DevStructure CPAL PASS I2C bus or peripheral is n
45. any resource shared between multiple peripherals are correctly configured after deinitialization i e if a DMA channel TC interrupt is used by PC and one other peripheral then make sure to re enable this DMA channel and its interrupt after calling CPAL I2C Delnit function CPAL 12C StructIn it This function initializes the related peripheral structure pointed by pDevInitStruct by filling all fields with their default values Caution Pointer fields are filled with CPAL local variable pointers To avoid any risks it is recommended to declare application local global variables and fill these fields with their pointers CPAL_I2C_Read This function reads receives a data buffer through the related peripheral All information on the read transfer parameters and current status are extracted from the pCPAL_Transferkx field described in Table 8 In each step of communication the CPAL_State field of the structure pointed by pDevInitStruct is continuously updated to report the current state and the potential errors CPAL_I2C_Write This function writes sends a data buffer through the related peripheral All information on the write transfer parameters and current status are extracted from pCPAL_TransferTx field described in Table 8 In each step of communication the CPAL_State field of the structure pointed by pDevInitStruct is continuously updated to report the current state and the potential errors CPAL 12C List
46. ary provides template files for implementing the User Application interface You can modify these files or not according to your application requirements Each product family have a specific CPAL library package This package consists of STM32xxxx CPAL Driver folder located in the Libraries repository at the same level as CMSIS Cortex microcontroller software interface standard and the STM32 standard peripheral drivers This folder contains all the CPAL drivers and header files as well as templates for user files Also some examples illustrating the use of CPAL drivers are located in the project folder under folder containing examples based on the standard peripheral drivers Doc ID 023577 Rev 1 7 66 CPAL architecture description UM1566 Table 2 Figure 2 CPAL driver hierarchy STM32F37x CPAL Driver 3 inc stm32f37x i2c cpalh stm32f37x i2c cpal cont template h stm32f37x i2c cpal halh rafal N3 2 fi 0 3 stm32f37 _i2c_cpal c stm32f37 _i2c_cpal_hal c stm32f37 _i2c_cpal_usercallback_template c maa The library files are listed in the following table They are described in detail in the next sections CPAL file descriptions Layer User Application Interface File name Description stm32xxxx_i2c_cpal_c User file which can be modified to customize and or configure onf template h the CPAL library drivers This file is provided with each example stm32xxxx i2c cpal u User file
47. ating stop CPAL_OPT_I2C_OA2_MASK Contain Own Address 2 Mask OA2MSK is coded on 3 bit CPAL_OPT_I2C_10BIT_HEADR Enable the send of slave address 10bit header only when switching from master transmitter to master receiver mode with No stop generation option enabled CPAL_OPT_l2C_WAKEUP_STOP Enable the WakeUp from stop capability for the IZC slave device CPAL_OPT_I2C_NACK_ADD Enable the Initialization of the I C Slave device without enabling the acknowledgement of its own address This option must not be used with No Stop generation mode Reserved All reserved bits values are ignored Their use is reserved for future needs 1 To enable this option proceed as follows to assign the Own Address 2 and enable other options wCPAL_Options Own Address 2 Value CPAL_OPT_I2C_DUALADDR Other Options 2 This option is available only for IC peripherals in Master mode The physical address is an address into the slave peripheral into from which the write read operation is performed that is memory address physical register address 3 This option is available only when CPAL OPT NO MEM ADDR is disabled Otherwise when CPAL OPT NO MEM ADDR is enabled this option is ignored 2 2 2 CPAL communication functions stm32xxxx i2c cpal c All Communication Layer interface functions are built following the scheme detailed in the following table Table 12 Type Returned value uint32 t Result o
48. ble the Circular mode for the Rx DMA transfers on the related peripheral CPAL OPT NO MEM ADDR Enable No Memory addressing mode for the peripheral related 1 C This means that the master sends only the peripheral slave address no physical addresses into the slave 2 CPAL OPT 16BIT REG CPAL OPT I2C GENCALL Enable 16 bit register addressing mode Thus the register physical address sent after the peripheral slave address is considered as a 2 byte address Enable the IC General Call mode for the related peripheral CPAL_OPT_I2C_AUTOMATIC_END Enable Automatic end mode of STOP generation for master CPAL_OPT_I2C_ERRIT_DISABLE Disable the I2C error interrupt Bus error Arbitration loss Acknowledge failure and Overrun Underrun errors By default the error interrupts are enabled ng Doc ID 023577 Rev 1 15 66 CPAL architecture description UM1566 Table 11 wCPAL_Options field values continued Field value CPAL_OPT_I2C_NOSTOP Description Disable the sending of STOP condition at the end of the current buffer transfer for the relative IZC device This option may be enabled when multiple packets have to be sent consecutively without STOP generation This option can be used only if software end mode is selected CPAL_OPT_I2C_AUTOMATIC_END option is disabled CPAL_OPT_I2C_NOSTOP_MODE Start communication in No STOP generation mode and close communication by Gener
49. channel interrupt i e EVT ERR DMATX DMARX Modify the related define value to set the level of interrupt sub priority l2CX IT WWW PREPRIO Where X is the peripheral instance 1 2 or 3 and WWW is the peripheral interrupt or DMA channel interrupt i e EVT ERR DMATX DMARX Modify the related define value to set the level of interrupt sub priority sa Doc ID 023577 Rev 1 25 66 CPAL architecture description UM1566 The HAL layer provides basic functions enabling the control and configuration of all components required for communication These functions are detailed in the following table Table 17 CPAL low layer interface function description Function name CPAL_I2C_HAL_CLKInit Argument type CPAL_DevTypeDef Argument name Device Description This function configures and enables all IC peripheral clocks CPAL I2C HAL CLKDeInit CPAL DevTypeDef Device This function disables the 1 C peripheral clock CPAL_I2C_HAL_GPIOInit CPAL_DevTypeDef Device This function configures and enables all the I O pins used by the I2C peripheral as well as the GPIO port clocks CPAL_I2C_HAL_GPIODeInit CPAL_DevTypeDef Device This function de initializes all the 1 0 pins used by the I2C peripheral configure them to their default values The related GPIO port clocks are not disabled CPAL_I2C_HAL_DMATnit CPAL_DevTypeDef Device
50. channels priorities To configure the timeout mechanism correctly three steps can be followed e Set the Initialization and De Initialization functions map the CPAL TIMEOUT INIT and CPAL TIMEOUT DEINIT functions to a counter initialization function i e SysTick_Config SystemCoreClock 1000 and SysTick gt CTRL 0 These functions will be called respectively in CPAL 12C Init and CPAL I2C Delnit functions Map the CPAl I2C TIMEOUT Manager function to a user function ideally this function could be directly mapped to the counter interrupt in order to be called each time the specified period of time has elapsed that is define CPAL 12C TIMEOUT Manager SysTick Handler e Then it is possible optionally to modify the maximum timeout value associated to each operation in order to meet the application constraints To modify the maximum timeout value for an operation set the required value in ms to the define related to this operation for example if the application should wait a maximum of 10 ms for the Start Bit flag define CPAL 12C TIMEOUT BUSY 5 Doc ID 023577 Rev 1 43 66 How to use and customize the CPAL library step by step UM1566 44 66 Example Timeout mechanism implemented through SysTick interrupt configured to be generated each 1 ms define CPAL TIMEOUT INIT SysTick Config SystemCoreClock 1000 define CPAL TIMEOUT D
51. d to the configuration are cCPAL_I2C_Init CPAI I2C Delnit cCPAL_I2C_StructInit It is possible to configure and use more than one peripheral simultaneously since each peripheral has its own state control CPAL 12C Init functional description CPAL 12C Init function should be called at the startup of the application before performing any communication operations It should be called after filling the related 12Cx peripheral structure fields I2Cx_DevStructure with the required parameters The CPAL_I2C_Init function performs the following actions e Disable the I2Cx peripheral and reset its APB clock e Disable then enable and configure the GPIO ports and pins used for the 12Cx peripheral e Enable and initialize the 2Cx peripheral according to parameters in initialization structure pointed by the pCPAI 12C Struct field and the additional configuration set into the field wCPAL Options General Call mode Dual Address mode e Enable the DMA and or the interrupts and their related clocks and channels according to the values in the fields CPAL Direction CPAL ProgModel and wCPAL Options Initialize the Timeout mechanism as described in Section 3 3 1 This function can be called as many times as required i e when some configuration parameters are modified but in all cases it must be called at least once before starting any communication operation Doc ID 02357
52. description Table 14 CPAL configuration sections continued Section Options Description This define may be used when SysTick timer or one other timer is managed in interrupt mode for the timeout procedure It routes the SysTick or the timer interrupt to the CPAI I2C TIMEOUT UserCall1back function handling timeout errors In case of multiple peripheral types managed by the same interrupt handler an intermediate function may be implemented and called into the interrupt handler Example In stm32xxxx i2c cpal conf h CPAL 12C TIMEOUT Manager define CPAL I2C TIMEOUT Manager UserFunctionl In stm32fxxx it c file void SysTick Handler void f UserFunctionl Section 4 Pi Timeout F When another timeout mechanism based on interrupt is configuration continued 4 implemented the user should route the interrupt IRQ handler to the same callback CPAL_I2C_TIMEOUT_Manager CPAL I2C TIMEOUT MIN The minimum timeout value for the peripheral timeout counter when enabled this value is applied to the device structure timeout field wCPAL Timeout CPAL 12C TIMEOUT DEFAULT The default value for the timeout counter When the counter is set to this value no decrement is performed on the field wCPAL_Timeout of the peripheral structure CPAL I2C TIMEOUT WWW Where WWW can be replaced by the peripheral event i e SB ADDR These defines determine the maximum timeout allowed for t
53. description Figure 3 CPAL option fields JAO dOLSON 92 LdO Wdd dOlS dNIAYM IZI LdO Wd MOVIH 1190 921 LdO Wdo CAY YOYN 92 LdO di ASV ZWO 921 LdO Wdd dOLSON 221 LdO Wdod wz a vm o 3 o a aN SILWMIOLAW IZI LdO Wd AAVSiIO 11333 921 LdO Wdd YYINIYII KIWA LdO Wd YVINIYII XIVWO LdO Wdo yaay WIH ON LdO Wdo YOOYIYNO OZ LdO Idi TIYINIO OZ LdO dd Paklasay 9IN 1199 LdO Wdd LILH KUWA LdO Wedd PaAlasay a POAIASIY panlasay panlasay 4 POMIBsaY ssalppy Ng 4 LILH XIVWO LdO Twdo The table below describes in detail the meaning of each bit field When a bit is set to 1 the related option is enabled fit is reset the related option is disabled except for the bits 1 7 which hold the 7 bit address Table 11 wCPAL Options field values Field value CPAL OPT l2C DUALADDR Description Enable the 1 C Dual Addressing mode for the related peripheral 7 Bit Address This is the value of the Own Address 2 This value will be configured and used only if the CPAL OPT I2C DUALADDR option is enabled CPAL OPT DMATX HTIT Enable the DMA Tx Half Transfer Complete interrupt for the related peripheral CPAL OPT DMARX HTIT Enable the DMA Rx Half Transfer Complete interrupt for the related peripheral CPAL OPT DMATX CIRCULAR CPAL OPT DMARX CIRCULAR Enable the Circular mode for the Tx DMA transfers on the related peripheral Ena
54. ed callbacks should be implemented In this application 4 callbacks are used CPAL_I2C_ERR_UserCallback CPAL_I2C_TXTC_UserCallback CPAL_I2C_RXTC_UserCallback and CPAL_TIMEOUT_UserCallback As detailed above the error callbacks just have to reset the system in case of errors brief User callback that manages the Timeout error param pDevinitStruct retval None uint32_t CPAL_TIMEOUT_UserCallback CPAL_InitTypeDef pDevInitStruct NVIC_SystemReset Generate a system reset return CPAL PASS This statement will not be reached brief User callback that manages the I2C peripheral errors note Make sure that the define USE_SINGLE_ERROR_CALLBACK is uncommented in the stm32xxxx_i2c_cpal_conf h file otherwise this callback will not be functional param pDevInitStruct param DeviceError Doc ID 023577 Rev 1 51 66 CPAL implementation example step by step UM1566 5 4 5 4 1 52 66 retval None uint32 t CPAL_I2C_ERR_UserCallback CPAL_InitTypeDef pDevInitStruct f NVIC SystemReset Generate a system reset return CPAL PASS This statement will not be reached The Rx and Tx transfer complete callbacks may be used to inform the user application layer that the transfer is completed in order to start a new transfer x4 brief Manages the End of Rx transfer event x param pDevInitStruct x retval None EJ void CPAL_I2C_R
55. en This function allows a slave to start a communication without knowing in advance the type of operation Read or Write The slave enters in an idle state and waits until it is addressed Depending on the requested operation User Callbacks specific to this mode are called All information required for transfer read and write parameters DMA and Interrupts configuration must be implemented in these Callbacks by the user CPAL_I2C_IsDevice Ready This function can be used to Wait until the target peripheral is ready for communication i e for memories Verify that the external slave peripheral is connected to the bus using its address This function sends the peripheral slave address on the bus then waits till the peripheral responds to this address meaning that the previous operation was successfully completed or and the peripheral is connected to the bus If no response is received after a timeout period the function exits and returns the CPAL FAIL result If the peripheral responds correctly then the function exits and returns the CPAL_PASS result This function can be called once to verify that the Slave peripheral is connected or is ina loop to wait till the peripheral responds correctly 1 When CPAL_I2C_Read function is called the user application may perform other tasks while the transfer is ongoing and the CPAL_State field can be used to monitor transfer ky Doc ID 023577 Rev 1 17 66
56. en detection of failures within a defined time frame is required When an operation takes more time than expected the timeout user callback function is called Basic recovery operations are already performed by the CPAL drivers before calling this function clear error sources when possible stop communication reset the CPAL state fields The user application should then try to restore lost buffers data or reset the whole system when recovery is not possible CPAL TIMEOUT INIT This callback is used to configure and enable the timeout counter peripheral function used to generate periodic ticks interrupts i e enable and configure SysTick timer and its related interrupt This function is called into CPAL I2C Init function This callback is used to free the counter resource when the peripheral is CPAL TIMEOUT DEINIT de initialized i e disable SysTick timer and its interrupt This function is called into CPAL 12C Delnit function This function is called when a timeout condition occurs for a peripheral It is CPAL TIMEOUT UserCallback not called when timeout occurs simultaneously with a peripheral error BERR OVR because in this case only the error callback is called 3 3 1 40 66 Timeout management For a communication to start in most cases the application must wait until some events occur These events may depend on external devices and may not occur in case of a device or bus failure In thi
57. ers and all the DMA related interrupt handlers are declared and managed exclusively by the CPAL library The user application does not need and Doc ID 023577 Rev 1 ky UM1566 CPAL architecture description 2 2 1 ng should not declare these interrupt handlers If these handlers are needed for other purposes for example a DMA interrupt shared by several peripherals the user application may use the related callbacks e Interrupt priority groups and preemption orders are also managed by the CPAL driver To configure these parameters modify the stm32xxxx i2c cpal conf h file CPAL main structures stm32xxxx i2c cpal h The CPAL library provides a unique structure grouping all parameters needed to e Configure a peripheral e Use it for communication e Monitor the state of the CPAL driver and the peripheral This structure is declared in the stm32xxxx i2c cpal h file and is used as the unique argument for all driver functions Each peripheral instance has a separate structure holding its configuration parameters and all the related transfer arguments and status These structures are declared in the driver file and are also declared as extern in the stm32xxxx i2c cpal h file so no need for you to declare them in your application files Example ifdef CPAL USE I2C1 extern CPAL InitTypeDef I2C1_DevStructure endif CPAL USE I2C1 ifdef CPAL USE I2C2 extern CPAL InitTypeDef I2C2_DevStructure endif CP
58. et value for example define I2C1 IT EVT SUBPRIO 12C1_IT_OFFSET_SUBPRIO t0 define I2C1 IT ERR SUBPRIO I2C1 IT OFFSI 0 define I2C1_IT_DMATX_SUBPRIO I2C1 IT OFFSET SUBPRIO 0 EF T SUBPRIO Uncomment this define to enable an event log coded into the CPAL drivers The event log can be re directed through the CPAI LOG Str macro When this define is enabled then an additional time is inserted in several places in the code which may affect the performance of the library and even the correctness of the communication CPAL_LOG Str This macro is valid only when the CPAL_DEBUG define is enabled It allows you to re direct the logging function to the user defined output stream i e using printf and re directing printf to the USART peripheral or IDE tool log window 2 3 2 22 66 User callback interface The callback interface stm32xxxx i2c cpal usercallback c allows the implementation of user callbacks when needed A template file is provided in the library stm32xxxx_i2c_cpal_usercallback_template c with empty callback functions This file contains all supported user callbacks It is not mandatory to implement callbacks Only callbacks that are needed by the user application may be implemented the other ones may be kept commented If a callback is implemented then its related define in the stm32xxxx 12c cpal conf h file should be commented Doc ID 023577 Rev 1 a UM1566
59. f the operation CPAL PASS if operation is successful and a different value if operation failed Architecture of CPAL Communication Layer functions Name Type Arguments CPAL I2C xxxx CPAL_InitTypeDef pDevInitStruct All functions accept one single argument the pointer to the CPAL peripheral configuration structure Where xxxx the operation name i e Init Read Write 16 66 a Doc ID 023577 Rev 1 UM1566 CPAL architecture description The CPAL Communication Layer functions are described in the following table Table 13 CPAL Communication Layer function list Function name CPAL_1I2C_Init Description This function initializes the related peripheral and all needed resources GPIOs clocks DMA and interrupts depending on the parameters configured in the configuration structure pointed by pDevInitStructure CPAL 12C Delnit This function frees the resources used by the related peripheral GPIOs clocks DMA interrupts and disables then deinitializes the peripheral itself Thus every used resource is configured to its default state If a resource has not been used by the peripheral then it is not deinitialized Thus if a peripheral is configured in DMA mode then configured again in Interrupt mode when this function is called it only deinitializes interrupt related resources DMA resources Will remain configured Note When calling this function make sure that
60. field values 13 wCPAL_DevError field values for IC peripherals 13 wCPAL_Options field values 15 Architecture of CPAL Communication Layer functions 16 CPAL Communication Layer function list 17 CPAL configuration sections 19 CPAL configuration sections 23 HAL configuration sections 25 CPAL low layer interface function description 26 CPAL_I2C_Struct_Init default values 31 I2C interrupt managementorder 36 DMA interrupt management order 37 CPAL I2C user callback list 38 Hardware resources used in CPAL examples 55 Memory footprint of CPAL components 59 Frequently asked questions aaa anaana anaana naaa 61 Document revision history tees 65 Doc ID 023577 Rev 1 ky UM1566 List of figures List of figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figu
61. find I2C interrupt handler in the stm32xxxx_it c file and if add it have compiler warnings errors CPAL drivers already declare and implement internally all needed interrupt handlers for the communication peripheral i e 12C 12Cx EV IRQHandler and When implement CPAL drivers into my application have warnings errors related to KG interrupt I2C ER IRQHandler There is no need for additional configuration You just have to use the CPAL callbacks provided for this peripheral in cpal_usercallbacks c file and comment the related callback define in stm32xxxx i2c cpal conf h file section 3 10 need to use a DMA interrupt handler but if implement it have compiler warnings errors 11 12 When implement CPAL drivers into my application have warnings errors related to DMA interrupt handlers How Why can select the right interrupt priority level for communication peripherals As for communication peripheral IRQ handlers CPAL drivers already declare and implement internally all needed interrupt handlers for the used DMA channels i e DMAx Channely IRQHandler if DMAx Channely is used by CPAL drivers This is true only if DMA configuration is enabled in stm32xxxx i2c cpal conf h file CPAL I2C DMA PROGMODEL If these handlers are needed only for the communication peripheral controlled by the CPAL driver then there is no need for any additional configuration If you want to use thi
62. fy the I O selection the DMA channels the interrupt priorities ng Doc ID 023577 Rev 1 61 66 Frequently asked questions FAQ UM1566 Table 24 Frequently asked questions continued No Question Possible answers solutions Which header files should include in my application in order to use the CPAL library Only stm32xxxx i2c cpal h file has to be included Topic 2 Configuration The easiest way is to call the function CPAL_I2C_StructInit to initialize the structure with default values Then you have to set the following fields pCPAL_TransferTx and or pCPAL TransferRx How many fields are mandatory to fill for the should be filled with pointers to the Tx Rx transfer CPAL initialization structure structures These structures should be updated during execution with new values of buffers and addresses For all other fields you can keep default values in most cases check Section 2 3 2 for more details on default values The CPAL drivers use a unique structure for each peripheral These structures are exported as external variables to the user application code In this structure some fields are pointers to initialization structures When you call CPAL_StructInit functions all fields are set to default values but pointers are set as follows use more than one I2C peripherals and they Transfer structure pointers are set to Null value 6 are not configured correctly after call the
63. he specified event this value is added to the CPAL_I2C_TIMEOUT_MIN to calculate the allowed timeout period The user may specify different timeout periods for each event in order to meet the requirements and constraints of the application Doc ID 023577 Rev 1 21 66 CPAL architecture description UM1566 Table 14 CPAL configuration sections continued Section Section 5 Interrupt priority selection Section 6 CPAL debug configuration Options CPAL_NVIC_PRIOGROUP Description Uncomment one of the available defines to set the level of preemption and sub priority groups This configuration is applied to all interrupt handlers If the user application modifies the interrupt priority group configuration in other locations then it impacts the CPAL functions I2CX_IT_OFFSET_PREPRIO Modify the related define value to set the level of interrupt preemption priority All preemption priorities of the 2Cx peripheral will be set in the HAL layer relatively to this offset value for example define I2C1 IT EVT PREPRIO I2C1 IT OFFSET PREPRIO 0 define I2C1 IT ERR PREPRIO 12C1_IT_OFFSET_PREPRIO 2 define I2C1_IT_DMATX_PREPRIO I2C1_IT_OFFSET_PREPRIO 1 I2CX_IT_OFFSET_SUBPRIO CPAL_DEBUG Modify the related define value to set the level of interrupt sub priority offset All sub priorities of the 2Cx peripheral are set in the HAL layer relatively to this offs
64. her options disabled aga so CPAL Core All options disabled CPAL USE 12C1 2 Devices CPAL USE I2C2 1748 128 All other options disabled Master CPAL 12C MASTER MODE 1408 4 Mode Option Slave without OPAL ic SLAVE MODE 496 0 p Listen mode oS T Slave with CPAL I2C SLAVE MODE pa A Listen mode CPAL_I2C_LISTEN_MODE DMA CPAL_I2C_DMA_PROGMODEL 1005 68 Programming Model Option 1 Interrupt CPAL_I2C_IT_PROGMODEL 332 0 ky Doc ID 023577 Rev 1 59 66 Memory footprint of CPAL components UM1566 Table 23 Memory footprint of CPAL components continued Code Size Bytes Options Define Flash RAM Memor CPAL_16BIT_REG_OPTION 608 0 Address Addressing Mode Option 16 Bit CPAL_16BIT_REG_OPTION 344 0 10 Bit CPAL_I2C_10BIT_ADDR_MODE 76 0 CPAL USE 12C1 i T ke 4 1 LONG All other options enabled eve r ATER a CPAL USE 12C1 All Options enabled Full nG with listen GPAL_USE_12C1 4779 200 CPAL set All other options enabled CPAL USE I2C1 2 Devices CPAL USE 12C1 4691 200 All other options enabled CPAL I2C MASTER MODE Master Mode disabled All other options enabled KE 3283 196 disabled CPAL I2C SLAVE MODE Slave Mode disabled All other options enabled Li aa 4195 200 disabled Slave in Listen Mode disabled All other options CPAL_I2C_LISTEN_MODE 2 E 4691 200 enabled disabled CPAL_I2C_DMA_PROGMODEL DMA Mode disabled All other options enabled a 3686
65. ication does not need to read less than one byte from the EEPROM memory So CPAL_I2C_DMA_PROGMODEL and CPAL 12C IT PROGMODEL must be kept enabled Both I Cs use simple 7 bit addressing Consequently CPAL 12C 10BIT ADDR MODE can be commented In the same way if EEPROM locations and the Temperature Sensor register Doc ID 023577 Rev 1 49 66 CPAL implementation example step by step UM1566 50 66 are addressed through 8 bits only memory size lt OxFF n there is no need for CPAL_16BIT_REG_OPTION It can then be commented Section 3 If no specific error management is required the application may just reset the system whatever the error type Consequently USE_MULTIPLE_ERROR_CALLBACK can be commented Then CPAI 12C ERR UserCal1back define should be uncommented and CPAL_I2C_ERR_UserCallback define should be commented For EEPROM DMA mode is used for both directions read and write and for Temperature Sensor Interrupt mode is used only in reception direction So it is easier to use the callbacks common to DMA and Interrupt CPAL_I2C_TXTC_UserCallback and CPAL_I2C_RXTC_UserCallback defines should then be commented Section 4 No need to modify this section for this application Note that it is strongly recommended to use CPAL_TIMEOUT_UserCallback function For this application it could just reset the system In other cases if the ap
66. ir description is provided in the following table Table 21 CPAL 12C user callback list Callback name Description Communication User Callbacks These functions are called when correct communication events occur They are generally used to prepare data before transmitting or processing them after reception Thus they should be as short as possible in order to avoid affecting the communication process This function is called when the TXE interrupt handler is entered and CPAL I2C_TX UserCallback before writing data to the peripheral DR register This callback shall be used to prepare the next data to be sent This function is called when the RXNE interrupt handler is entered and CPAL I2C RX UserCallback after reading the received data from the peripheral DR register This callback shall be used to manage the last received data This function is called when data transmission is completed and L T 11 k PAKO A CPAD TAC Usereal 196 communication is closed in the Interrupt and DMA Programming model This function is called when data reception is completed and L T 11 k PEE A CPAN 12C _RXTO UserCallbac communication is closed in Interrupt and DMA Programming Model CPAL_I2C_DMATXTC_UserCallbac k DMA TX callbacks are available if the DMA programming model is selected for at least one peripheral These functions are called when a DMA interrupt is entered for the configured DMA channel and the related event Pood as occ
67. le 18 CPAL I2C Struct Init default values Modify only some fields after calling CPAL_I2C_StructInit Example CPAL 12C StructInit sI2C1 DevStructure I2C1 DevStructure CPAL Direction CPAL DIRECTION RX I2C1 DevStructure CPAL Mode CPAL MODE SLAVE CPAL 12C Init amp I12C1_DevStructure Set all fields of the structure to required values After setting the configuration structure values user application should call CPAL 12C Init function in order to configure the peripheral and all related peripherals I Os interrupts DMA clocks with the required settings The fields pcPAL_TransferTx and pCPAL TransferRx are set by default to local structures with null pointers In order to avoid issues due to memory overflow or addressing errors these two fields should be set to point to valid structures declared in the user application When the device has to be stopped the CPAL_I2C_DeInit function can be called in order to free all resources used by this peripheral I Os interrupts DMA In this case the configuration structure keeps the last used values Communication After the configuration phase peripherals are ready to be used for communication Before starting to communicate with an external device the application may check its availability on the bus using the function CPAL_I2C_IsDeviceReady If this function
68. listed in Table 6 can be assigned to this field CPAL_ProgModelTypeDef CPAL_ProgModel Select the programming model for the next transfers Interrupt peripheral transfer interrupts will manage all the transactions and peripheral and driver states or DMA all data transfers are managed by DMA channels CPU is then free to perform other user tasks Any value listed in Table 7 can be assigned to this field Note For FC when DMA mode is enabled the addressing phase cannot be managed by DMA but only by interrupts CPAL_TransferTypeDef pCPAL_TransferTx This field points to a structure holding all the transmission transfer parameters buffer addresses and number of data bytes A value can be assigned to this field as described in Table 8 CPAL_TransferTypeDef pCPAL_TransferRx This field points to a structure holding all the reception transfer parameters buffer addresses and number of data bytes A value can be assigned to this field as described in Table 8 IO CPAL_StateTypeDef CPAL State The state field holds the current state of the CPAL driver for the related peripheral instantiated by the CPAL Dev field These values are described in more detail in Section 3 3 One of the values listed in Table 9 can be assigned to this field Note After managing a peripheral error by clearing the error flag and returning to the transfer correct status update this field in order to continue n
69. n to start read write operation After calling this function the transfer starts through the related peripheral using the interrupts or DMA depending on the programming model set In addition the application may perform other parallel tasks while the CPAL driver is handling transfer through DMA or interrupts Monitor the end of transfer this can be performed using two basic methods Directly monitor the state of the peripheral through the wCPAL State field The communication is completed when the state returns to CPAL STATE READY Usethe CPAL_I2C_TXTC_UserCallback and or CPAL_I2C_RXTC_UserCallback callback functions which are called when transfer is completed in both DMA and interrupt modes Two other advanced possibilities exist provide more control on data handling If DMA mode is selected the Transfer complete interrupt callbacks CPAL_I2C_DMATXTC_UserCallback and CPAL_I2C_DMARXTC_UserCallback may be used They are called when the DMA has completed the transfer operation but transfer is still not completed on the I2C bus Ifthe Interrupt mode is selected the CPAL 12C TX UserCallback and CPAL_I2C_RX_UserCallback callbacks may be used to monitor the number of remaining data At the end of the transfer a new transfer may be started or the peripheral may be de initialized and free all the used resources using the function CPAL_I2C_DeInit
70. ndition is detected and is not located after a multiple of 9 SCL clock pulses A START or a STOP condition is detected when a SDA edge occurs while SCL is high The bus error flag is set only in case the I2C is involved in the transfer as master or addressed slave i e not during address phase in slave mode In case of a misplaced START or ReSTART detection in slave mode the 1 C enters address recognition state as for a correct START condition When a bus error is detected BERR flag is set in I2C_ISR register and an interrupt is generated if ERRIE is set in 12C_CR1 register Doc ID 023577 Rev 1 13 66 CPAL architecture description UM1566 Table 10 wCPAL DevError field values for I2C peripherals continued Field value Description An arbitration loss is detected when a high level is sent on SDA but a low level is sampled on the SCL rising edge In master mode the arbitration loss is detected during address phase data phase and data acknowledge phase In that case SDA and SCL lines are released START control bit is cleared by hardware and the master switches automatically to slave CPAL_I2C_ERR_ARLO mode In slave mode arbitration loss is detected during data phase and data acknowledge phase In that case the transfer is stopped and SCL and SDA lines are released When an arbitration loss is detected ARLO flag is set in 12C ISR register and an interrupt is generated if ERRIE is set in I2C_CR1 registe
71. ntained therein UNLESS OTHERWISE SET FORTH IN ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT UNLESS EXPRESSLY APPROVED IN WRITING BY TWO AUTHORIZED ST REPRESENTATIVES ST PRODUCTS ARE NOT RECOMMENDED AUTHORIZED OR WARRANTED FOR USE IN MILITARY AIR CRAFT SPACE LIFE SAVING OR LIFE SUSTAINING APPLICATIONS NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY DEATH OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE ST PRODUCTS WHICH ARE NOT SPECIFIED AS AUTOMOTIVE GRADE MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER S OWN RISK Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in this document supersedes and replaces all information previously supplied The ST logo is a registered trademark of STMicroelectronics All other names are the property of their
72. onal description 4 Figure 6 CPAL_I2C_Read function flowchart C CPAL_I2C_Read a A tate is eady yes v Set State to Ready Rx Configure RX DMA Channel Send Target Memory Address Set State to Busy Rx Interrupt v Master Mode yes AA Configure Slave address and Generate Start Prog Model Enable Interrupt DMA v Enable RX DMA Request a Return U CPAL_PASS Return CPAL_FAIL Doc ID 023577 Rev 1 33 66 CPAL functional description UM1566 3 2 2 CPAL 12C Write functional description The CPAL 12C Write function uses the information configured in the peripheral structure and the information pointed by pCPAL Trans ferTx to perform the write of the selected buffer through the selected I2Cx peripheral Figure 7 CPAL 12C Write function flowchart a CPAL 12C Write D tate is eady yes y Set State to Ready_Tx Yes Configure TX DMA No Channel Send Target Memory no Address Set State to Busy_Tx Master Mode yes y Configure Slave address and Generate Start Prog Interrupt Model DMA Y AA Enable Interrupt Enable TX
73. or the related transfer direction DMA channel CPAL_I2C_DMAZZTE_ UserCallback Where ZZ is the transfer direction TX or RX These functions are called when a Transfer Error interrupt occurs for the related transfer direction DMA channel CPAL_I2C_SLAVE_ZZ _UserCallback Where ZZ is the transfer direction Read or Write These functions are called when the slave receives its own address in listen mode Error Callbacks For the error callbacks there are two possible configurations depending on two exclusive defines only one of these defines should be enabled never both of them USE_SINGLE_ERROR_CALLBACK USE_MULTIPLE_ERROR_CALLBACK Enable USE_SINGLE_ERROR_CALLBACK to use only one callback for all peripheral errors The User must check which error caused a call of the error function by using the related error status fields in the CPAL structure When this define is enabled only CPAL_I2C_ERR_UserCallback can be activated Enable USE_MULTIPLE_ERROR_CALLBACK to use a separate error callback for each peripheral error event When this define is enabled CPAL_I2C_ERR_UserCallback is not available CPAL_I2C_ERR_User Callback This callback is valid only when USE_SINGLE CPAL accepts two arguments to this function pDevinstance instance of the related peripheral i e CPAL_I2C1 DeviceError error code i e CPAL_I2C_ERR_BERR This function is called when any error occurs on
74. ormal operations 10 66 Doc ID 023577 Rev 1 a UM1566 CPAL architecture description Table 3 CPAL InitTypeDef structure continued Field type Field name Description This field holds the peripheral related error code instantiated by the field CPAI Dev One of the values listed in Table 10 can be assigned to this field JO uint32 t wCPAL_DevError Note After managing the peripheral error by clearing the error flag and returning to the transfer correct status update this field and set it to CPAL_I2C_ERR_NONE in order to continue normal operations This field allows you to configure additional options for the transfer configuration These options are described in more detail in Table 11 Any combination of the specified values can be used for this field with respect to the conditions related to each option uint32_t wCPAL Options This field is used for timeout detection It holds the current _ lO uint32_t wCPAL_Timeout value of the timeout counter for the peripheral controlled by this structure This field points to a peripheral configuration structure as I2C InitTypeDef PCPAL 12C Struct defined in the standard peripheral library Only one value can be assigned to this field The tables below describe the possible values in detail for each structure field Table 4 CPAL Dev field values Field value Description X peripheral instance 1 or 2 or 3 CPAL_I2
75. ot able to start communication Error management Wait for the end of transfer while I2C2_DevStructure gt CPAL State CPAL STATE READY Check the temperature value range if sTSRxStructure pbBuffer 0 CRITICAL VALUE Stop communication or switch to low power mode Read back the 100 data from EEPROM at address 0x30 sEERxStructure wNumData 100 Number of data to be read sEERxStructure wAddr2 0x30 Address into EEPROM if CPAL_I2C_Read amp I2C1_DevStructure CPAL PASS f I2C bus or peripheral is not able to start communication Error management Wait the end of transfer while I2C1_DevStructure gt CPAL State CPAL STATE READY Application may perform other tasks while CPAL read operation is ongoing At this point data has been received they can be used by the application compare process Doc ID 023577 Rev 1 a UM1566 CPAL Examples 6 CPAL Examples In addition to the CPAL firmware library the CPAL package provides a set of examples for IC peripheral aiming at providing different levels of implementation complexity This release comes with three examples running on STM320518 EVAL STM32FOxx STM32373C EVAL STM32F37x and STM32303C EVAL STM32F30x evaluation boards and can be easily tailored to any other supported device and development board The following table
76. plication is implemented with RTOS structure or if the SysTick timer is already used for other purposes then this section can be modified as follows Define new macro for the timeout initialization CPAL TIMEOUT INIT and the timeout de initialization CPAI TIMEOUT DEINIT Example use the TIM3 timer to generate regular ticks interrupts managing timeout mechanism define _CPAL TIMEOUT INIT APP InitTimer No initialization needed define _CPAL TIMEOUT INIT APP DelnitTimer No deinitialization needed define CPAL I2C TIMEOUT Manager TIM3 IRQHandler Use the IRQ handler of TIM3 void APP InitTimer void User function declaration void APP_DeInitTimer void User function declaration In this case two functions should be implemented in the user application APP_InitTimer and APP DelnitTimer They can be implemented using standard peripheral library drivers refer to the Timer TimeBase example for more details Finally adjust the values of CPAL TIMEOUT WWW where WWW is the I C event i e SB ADDR according to the timebase value Section 5 No need to modify this section for this application In other cases when multiple interrupts are managed by the application the interrupt group and priority configuration may be adjusted in this section Section 6 No need to modify this section for this application In other cases where debug tools are
77. r It is cleared by software by setting ARLOCF bit Not Acknowledge is detected as an error only in master mode when a NACK is received after sending slave address CPAL_I2C_ERR_AF NACKF flag is set in I2C_ISR register and an interrupt is generated if NACKIE is set in l2C CR1 register It is cleared by software by setting NACKCF bit An overrun or underrun error is detected in slave mode when NOSTRETCH 1 and In reception when a new byte is received and the RXDR register has not been read yet New received byte is lost and a NACK is automatically sent as a response to the new byte In transmission when STOPF 1 and the first data should be sent The content of TXDATA is sent if TXE 0 OxFF if not when a new byte should be sent and the TXDR register has not been written yet OxFF is sent When an overrun or underrun error is detected OVR flag is set in I2C_ISR register and an interrupt is generated if ERRIE is set in 12C_CR1 register It is cleared by software by setting OVRCF bit CPAL_I2C_ERR_OVR The wCPAL_Options field in the CPAL device structure can be used to manage additional configuration options for peripheral initialization and communications The options are bit field values each option is coded on 1 bit into the 32 bit word field WCPAL Options Multiple options may be assigned to the wCPAL Options field at the same time a 14 66 Doc ID 023577 Rev 1 UM1566 CPAL architecture
78. r your application needs This is not mandatory to modify this file the default configuration may be used without any modification Only some parameters can be modified To configure this single file stm32xxxx_i2c_cpal_conf h you should enable disable or modify some options or group of options by un commenting commenting or modifying values of the related defines The CPAL configuration steps are grouped in sections and detailed in the following table Section 1 Peripheral selection Section 2 Transfer option configuration Section 3 User callback configuration Section 4 Timeout configuration Section 5 Interrupt priority selection Section 6 CPAL debug configuration Doc ID 023577 Rev 1 ky UM1566 CPAL architecture description Table 14 CPAL configuration sections Section Section 1 Peripheral selection Options Description X device instance 1 or 2or3 Uncomment a define to enable the related peripheral When commented the peripheral cannot be used and all related resources are not declared by the CPAL library Thus less memory space is used CPAL USE I2CX Section 2 Transfer option configuration The following options are static configurations allowing you to reduce the code size when some features are not used by the application Uncomment this define to enable Master mode use for IZC peripherals When this define is commented none of Master mode features and operations
79. re 10 Figure 11 CPAL library architecture 7 CPAL driver hierarchy 8 CPAL option fields seima tea a a eee sea ey Ae KNA Bie mand ee aoe DAANG KNA 15 CPAL_I2C_Init function flowchart 29 CPAL_I2C_Delnit function flowchart 30 CPAL_I2C_Read function flowchart 33 CPAL 12C Write function flowchart 34 CPAL 12C Listen functionflowchart 35 CPAL I2C timeout manager flowchart 41 WakeUp from stop example architecture 56 Two board example architecture 57 Doc ID 023577 Rev 1 5 66 CPAL overview UM1566 6 66 CPAL overview The purpose of this document is to explain the architecture and the implementation of the CPAL Library Communication Peripheral Application Library CPAL v2 is a Library providing high layer API for STM32F0 F3 communication peripherals C It provides CPAL drivers for each device some illustrating examples showing how to use and customize the CPAL drivers It mainly aims to e Provide intuitive easy to use and sufficient API Init Deinit Read Write All configurations needed
80. re already performed by the CPAL drivers before calling the error Callbacks clear error flag and source when possible reset the CPAL state fields and timeout mechanism The user application should then try to restore lost buffers data or reset the whole system when recovery is not possible CPAL 12C BERR UserCallback CPAL 12C ARLO UserCallback CPAL 12C OVR UserCallback CPAL 12C AF UserCallback Multiple Error callbacks are available only when the define USE MULTIPLE ERROR CALLBACK is enabled in the file stm32xxxx i2c cpal conf h Each function is called when the peripheral error interrupt is entered and the error is identified to be one of the following BERR Bus Error ARLO Arbitration Loss OVR Overrun or Underrun and AF Acknowledge Failure ky Doc ID 023577 Rev 1 39 66 CPAL functional description UM1566 Table 21 CPAL 12C user callback list Callback name Description Single Error callback is available only when the define USE SINGLE ERROR CALLBACK is enabled in the I stm32xxxx i2c cpal conf h file This function is called when the CPAL 12C ERR UserCallback peripheral error interrupt is entered and before identifying the error source BERR ARLO OVR or AF The user application may check the error using the parameter passed to the callback pointer to the peripheral structure Timeout User Callbacks Timeout functions are called by the CPAL drivers wh
81. respective owners 2012 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com 66 66 Doc ID 023577 Rev 1 ky
82. risks due to non initialized pointers and memory allocation errors Once the CPAL_I2C_Read CPAL_I2C_Write and CPAL_I2C_Listen function is called the user application may e Wait till the end of transfer by monitoring the wCPAL_State field value or the number of data in the wNumData field of the pCPAL_TransferRx or pCPAL_TransferTx structure orthe DMA transfer complete callbacks or the interrupt transfer callbacks e Perform other tasks while the transfer is ongoing transfer is handled by interrupts or DMA channels and check periodically the state of the transfer as explained above e Move to other tasks and control the CPAL transfer only through DMA Transfer complete callbacks described in Section 2 3 2 This method is preferred for continuous communication with DMA circular mode option enabled The CPAL_I2C_Read CPAL_I2C_Write and CPAL_I2C_Listen functions just prepare and configure the communication The effective transfer operation transmission reception event management error management is handled by interrupts and DMA functions as described in Section 3 2 5 CPAL_I2C_Read functional description The cPAL 12C Read function use the information configured in the peripheral structure and the information pointed by pCPAL TransferRx to perform the read of the received buffer through the selected 2Cx peripheral Doc ID 023577 Rev 1 ky UM1566 CPAL functi
83. rivers This example shows how the I2C bus arbitration between multiple masters can be managed with the CPAL library and how the errors can be managed and recovered using the CPAL error callbacks and timeout mechanism Doc ID 023577 Rev 1 ky UM1566 CPAL Examples 6 3 Figure 11 Two board example architecture BoardA Board B LCD LCD optional optional STM32 STM32 microcontroller microcontroller KEY TAMPER KEY TAMPER The two STM32 devices are configured as Slaves at the example startup When the user pushes Key or Tamper push buttons the activated STM32 device switches to Master mode and remains in this mode till the next reset It periodically sends status messages to the other Slave The period of these messages depends on the last pushed button If a device receives a message while it is not configured yet in Master mode it remains in Slave mode till the next reset When a button is pushed the activated STM32 device sends a message specific to each button and different from the status message The message reception and transmission status as well as the error detection and recovery status are displayed on the LCD screen For more details about the hardware requirements and the supported devices and boards refer to the readme file located in the example directory Two board Listen mode example This example shows how two microcontrollers can communicate on the same I2C bus using the CPAL dri
84. rogModel CPAL PROGMODEL DMA CPAL State CPAL STATE DISABLED WCPAL DevError CPAL_I2C_ERR_NONE wCPAL_ Options 0x00000000 all options disabled pCPAL_I2C_Struct wCPAL_Timeout CPAL TIMEOUT DEFAULT pCPAL_TransferTx pNull pCPAL_TransferRx pNull I2C Timing 0 I2C Mode l2C Mode I2C I2C AnalogFilter I2C AnalogFilter Enable I2C DigitalFilter 0 I2C OwnAddress1 0x00 I2C Ack I2C Ack Enable I2C AcknowledgedAddress I2C_AcknowledgedAddress_7bit 3 2 Communication Once the configuration step is performed successfully the application is able to perform communication operations using the functions 5 CPAL I2C Read 5 CPAL I2C Write 5 CPAL I2C Listen 5 CPAL I2C IsDeviceReady The CPAL_1 2C_Read and CPAL 1I2C Write functions require that the peripheral transfer structures should be already configured as described in Table 8 CPAL TransferTypeDef structure fields Transfer structures which are used with CPAL_1 before calling this function or after calling it in CPAL Or CPAL 12C SLAVE READ UserCallback Doc ID 023577 Rev 1 2C Listen function may be configured I2C SLAVE WRITE UserCallback 31 66 CPAL functional description UM1566 3 2 1 32 66 It is advised that these fields point to local or global variables initialized by the application in order to avoid
85. s a Write operation This callback must be implemented to configure pCPAL_TransferTx with transfer parameters DMA and interrupts must be also configured in this callback depending on the selected programming model User should call CPAL_I2C_HAL DMATXConfig CPAL 12C HAL ENABLE DMATX and CPAL I2C HAL ENABLE TXDMAREQ in DMA mode In interrupt mode only CPAL I2C HAL ENABLE SLAVE TXIT should be called In these cases these functions should be called after configuring Transfer parameters CPAL 12C SLAVE READ UserCall back This function is called in slave listen mode when a master device requests a Read operation This callback must be implemented to configure pCPAL TransferRx with transfer parameters DMA and interrupts must also be configured in this callback depending on the selected programming model User should call CPAL 12C HAL DMARXConfig CPAL 12C HAL ENABLE DMARX and CPAL I2C HAL ENABLE RXDMAREQ in DMA mode In interrupt mode only CPAL I2C HAL ENABLE SLAVE RXIT should be called In these cases these functions should be called after configuring Transfer parameters pDevinitStruct Error User Callbacks These functions are called when an error occurs during communication The user application should implement these functions to recover from the error and restore communication Basic recovery operations a
86. s case the only way to detect the error is to limit the time during which the system can wait for the event to occur CPAL drivers implement a Timeout mechanism used to achieve this control and prevent the application from being blocked because of any communication failure The timeout mechanism is based on three elements Timeout counter A peripheral function should be used to count and generate periodic and equal ticks i e SysTick or Timer This peripheral function may generate an interrupt or be scheduled for a specified period of time and call the CPAL peripheral timeout manager function CPAL_I2C_TIMEOUT_Manager at each tick The initialization of the counter mechanism is performed by the callback CPAL_TIMEOUT_INIT which should be implemented by the user application It triggers all initialization procedures required for the counter peripheral function i e configure and enable the SysTick timer and its interrupt This function is called in CPAL_I2C_Init function One other callback is available to free the counter resource CPAL TIMEOUT DEINIT and is called in the CPAI I2C Init function The Timeout Manager This function is implemented in the CPAL driver The Timeout Manager checks all the I2C peripheral structures and verify the value of wCPAL Timeout If it is different from CPAL 2C TIMEOUT DEFAULT and other than 0 it decrements the wCPAI Timeout value by 1 If it reaches 0 then the specified
87. s handler you can implement related DMA callbacks in stm32xxxx i2c cpal usercallback c file CPAL_I2C_DMATXTC_UserCallback If these handlers are needed for other purposes then try to change the configuration of the DMA channels in cpal ppp stm32xxxx h file configuration section 2 in order to free the requested channels FC peripherals require specific interrupt scheme Error interrupts should have the highest priority and should be able to interrupt other processes Then DMA interrupts if DMA mode is enabled have the second priority level because they are used for closing communication and this phase is time sensitive Finally IPC event interrupts may have the lowest priority and may be interruptible Regarding other interrupts the interrupt order and grouping entirely depend on application requirements and environment Topic 3 Hardware 13 Which STM32F0 F3 series devices are supported by the CPAL Library Refer to the Release Notes of the CPAL package for the complete list of supported STM32F0 F3 series devices 4 Doc ID 023577 Rev 1 63 66 Naming conventions UM1566 9 64 66 Naming conventions The communication peripheral access library CPAL uses the following device naming conventions STM32F37Xx is used to refer to STM32F37x and STM32F38x devices STM32F30X is used to refer to STM32F30x and STM32F31x devices STM32F3 is used to refer to STM32F37x and STM32F30x S
88. se operations are different according to the peripheral mode Master Slave the programming model Interrupt DMA and the option configuration No memory addressing mode General call mode Regardless of the selected programming model CPAL_PROGMODEL_DMA or CPAL_PROGMODEL_INTERRUPT the event and error interrupts are always enabled and used to control the communication flow Transfer interrupt will be enabled only when CPAL_PROGMODEL_INTERRUPT mode is selected The priority of events and error management corresponds to the order in which they are tested into the interrupt functions Table 19 12C interrupt management order Interrupt Details Callback Manages the event Transmit Interrupt Status which TXIS means a new data shall be written in the 1 C data register CPAL_I2C_TX_UserCallback for the next transfer Manages the event Receive Buffer Not Empty which CPAL_I2C_RX_UserCallback RXNE_ means a data has been received and should be read from piga KP k the data register CPAL_I2C_RXTC_UserCa ac Available in Master mode only Manages Transfer Complete Reload event which means TCR f NA the master or slave received or transmitted nbytes and Reload 1 Available in Master mode only Manages Transfer Complete event which means the CPAL I2C TXTC UserCallback master received or transmitted all data and CPAL 126 RXTC UserCallback communication will be closed Generate stop or another one will start Repeated start
89. shows the hardware resources used in these four examples Table 22 Hardware resources used in CPAL examples Used Resources Example Board LCD Buttons LED STM320518 EVAL STM32373C_EVAL X X X STM32303C_EVAL STM320518_EVAL Two Boards STM32373C_EVAL X X X STM32303C_EVAL STM320518_EVAL STM32373C_EVAL X X X STM32303C_EVAL WakeUp from Stop mode Two Boards Listen mode Doc ID 023577 Rev 1 55 66 CPAL Examples UM1566 6 1 6 2 56 66 Wakeup from Stop mode example This example shows how to use the Wakeup from Stop feature implemented in PC peripheral using the CPAL drivers Figure 10 WakeUp from stop example architecture Master Board Slave Board STM32 STM32 microcontroller microcontroller KEY One of the STM32 devices is configured as slave and the other one as master At the example startup the slave enters in Stop mode and wait until it detects its own address on the IC bus line User should push button key of the master board to send slave address and data When the slave board detects its own address it wakes up from Stop shows a message on LCD display then returns to Stop mode For more details about the hardware requirements and the supported devices and boards refer to the readme file located in the example directory Two board example This example shows how two microcontrollers may communicate on the same I C bus using the CPAL d
90. temperature value e Both interfaces are used simultaneously e EEPROM interface uses DMA mode Temperature Sensor interface uses Interrupt mode Note The CPAL package already provides ready to use EEPROM and Temperature Sensor drivers with more advanced features as well as examples showing how to use them This section just provides illustrating implementation example from scratch 5 1 Starting point The typical starting point is one of the example provided within the CPAL package Project STM32_CPAL_Template This folder contains all needed template files as well as the project files for different IDEs In this folder three files should be modified stm32xxxx i2c cpal conf h this file is updated according to the needs of the application in order to reduce code size and meet the required features stm32xxxx i2c cpal usercallback c this file is updated to implement the functions needed by the user application and that will be called by CPAL drivers e main ci this file contains the main program of the application 5 2 stm32xxxx i2c cpal conf h In order to optimize the code size of the CPAL library this file is used to disable the unused features Section 1 The application needs two I Cs Consequently CPAL USE I2C1 and CPAL USE 12C2 defines are kept enabled Section 2 Slave mode is not needed Consequently CPAL 12C SLAVE MODE can be commented Both DMA and Interrupt modes are needed But the appl
91. ters are related to each device family so they are located in the stm32xxxx_i2c_cpal_hal h file which is specific for each device family Note that a modification in this file applies to all programs using CPAL drivers stm32xxxx 12c cpal hal h file configuration is divided into independent sections e Select Peripheral I O pins Select TX and RX DMA Channels e Set Events Errors and DMA Interrupts Preemption and Sub Priorities Select peripheral I O pins This section allows a selection of the I O pins which will be used for each peripheral For each pin set the define value to use the related configuration Only one configuration may be used for each I O pin Example PB6 and PB7 used for I C SCL and SDA pins define CPAI I2C1 SCI GPIO PORT GPIOB define CPAL_I2C1_SCL_GPIO_CLK RCC_APB2Periph_GPIOB define CPAL_I2C1_SCL_GPIO_PIN GPIO_Pin_6 define CPAI I2C1 SCI GPIO PINSOURCE GPIO PinSourceb define CPAL I2C1 SDA GPIO PORT GPIOB define CPAL 12C1 SDA GPIO CLIK RCC APB2Periph GPIOB define CPAL 12C1 SDA GPIO PIN GPIO Pin 7 define CPAL I2C1 SDA GPIO PINSOURCE GPIO PinSource7 Select TX and RX DMA channels This section is used to select which DMA channels will be used for each peripheral direction Only one define should be used for each peripheral direction Example DMA1 Channel6 and Channel7 used for I2C1 peripheral I2C1 peripheral define CPAL I2C1 DMA TX
92. urred for the transmitting direction DMA channel TC Transfer CPAL I2C DMATXTE UserCallbac Complete HT Half Transfer Complete or TE DMA Transfer Error CPAL 12C DMATXHT UserCallbac 38 66 Doc ID 023577 Rev 1 ky UM1566 CPAL functional description Table 21 CPAL 12C user callback list Callback name CPAL_I2C_DMARXTC_UserCallbac CPAL_I2C_DMARXHT_UserCallbac CPAL_I2C_DMARXTE_UserCallbac Description DMA RX callbacks are available if the DMA programming model is selected for at least one peripheral These functions are called when a DMA interrupt is entered for the configured DMA channel and the related event has occurred for the receiving direction DMA channel TC Transfer Complete HT Half Transfer Complete or TE DMA Transfer Error CPAL 12C GENCALL UserCallbac k General Call event callback is available only when the option CPAL OPT I2C GENCALI is enabled for the peripheral This function is called when a General Call address is correctly received for a slave C peripheral CPAL_I2C_DUALF_UserCallback Dual Address Flag callback is available only when the option CPAL_OPT_I2C_DUALADDR is enabled for the peripheral This function is called when the peripheral in Slave mode receives correctly a header with its second address CPAL_I2C_SLAVE_WRITE_UserCal lback This function is called in slave listen mode when a master device request
93. vers and how a slave device communicates in Listen mode Also it shows how the 12C bus arbitration between multiple masters can be managed with the CPAL library and how errors can be managed and recovered using the CPAL error callbacks and timeout mechanism This example use the same architecture as the Two board example in Section 6 2 refer to Figure 11 for more details Doc ID 023577 Rev 1 57 66 CPAL Examples UM1566 58 66 The two STM32 devices are configured as slaves in listen mode at the startup of the example When the user pushes the Key button the activated STM32 device switches to master transmitter mode It periodically sends a request to transmit status messages to the other slave When the user pushes the Tamper button the activated STM32 device switches to master receiver mode It periodically sends a request to receive status messages from the other slave If a device receives a message while it is not configured yet in master mode it remains in slave mode till the next reset When a button is pushed the activated STM32 device sends or receives a message specific to each button and different from the status message The message reception and transmission status as well as the error detection and recovery status are displayed on the LCD screen For more details about the hardware requirements and the supported devices and boards refer to the readme file located in the example directory Doc ID 023577 Rev 1 k
94. y UM1566 Memory footprint of CPAL components 7 Memory footprint of CPAL components The table below details the footprint of each CPAL component in terms of Flash size and RAM size These figures have been determined using the IAR EWARM 6 40 tool with High Size optimization level and are valid for STM32F37x devices The footprint may change slightly for other devices All options are controlled by the defines listed in table below All these defines are located in the sim32xxxx i2c cpal cont h file that should be extracted from stm32xxxx i2c cpal conf template h file Notes 1 Option means all controlling defines listed below except CPAL USE I2Cx where x can be 1 or 2 for the PC peripheral instance 2 When not specified the options are independent of the number of supported devices CPAL USE I2Cx 3 All options are enabled by uncommenting the related define and disabled by commenting the related define 4 The main configurations all options disabled and all options enabled are greyed 5 Except for addressing mode options CPAL 16BIT REG OPTION and CPAL I2C 10BIT ADDR MODE for all other option groups it is mandatory to select at least one of the provided options i e in Mode option group it is mandatory to enable Master mode or Slave mode or both It is not allowed to disable both Table 23 Memory footprint of CPAL components Code Size Bytes Options Define l Flash RAM A CPAL USE I2C1 oes All ot
95. y function can be called by Master device to verify that a Slave device is connected to the bus or to check if when the last operation has been successfully completed i e for memory devices Thus it could be called once or into a loop It sends the communication headers depending on the peripheral mode and the configuration with the peripheral address and waits for the slave to respond Doc ID 023577 Rev 1 35 66 CPAL functional description UM1566 If the peripheral responds correctly to this address the function exits and returns CPAL_PASS If an incorrect answer is received or no answer is received during the timeout period then the timeout mechanism is triggered and used to exit the function with CPAL FAIL value In case of success the function closes the communication so that a new communication can start with the selected peripheral This function does not use or affect the transfer parameters of reception or transmission structures pointed by pCPAL TransferTx and pCPAL_TransferTx fields 3 2 5 CPAL interrupts and DMA management Once the CPAL_I2C_Read and CPAL_I2C_Write functions are called the communication is configured and prepared DMA or interrupt channels enabled communication header sent in Master mode Then the effective transmission reception operations as well as the event and error management is performed by interrupts and DMA functions The
96. ze local Reception structures for EEPROM sEERxStructure pbBuffer tEERxBuffer EEPROM Receive buffer sEERxStructure wAddr1 EE ADDRESS EEPROM Address Initialize local Transmission structures for EEPROM sEETxStructure pbBuffer tEETxBuffer EEPROM Tx buffer sEETxStructure wAddr1 EE ADDRESS EEPROM Address Initialize local Transmission structures for Temperature Sensor sTSRxStructure pbBuffer TSData Temperature Sensor Receive buffer one byte needed sTSRxStructure wAddr1 TS ADDRESS Temperature Sensor Address Then the CPAL IC structures should be initialized note that for each IC peripheral a structure is already declared by CPAL drivers and exported as extern to application layer Configure the peripheral structure CPAL_I2C_StructInit amp I2C1_DevStructure Set all fields to default values I2C1 DevStructure CPAL Mode CPAL MODE MASTER I2C1 DevStructure wCPAL Options CPAL OPT NO MEM ADDR I2C1 DevStructure CPAL ProgModel CPAL PROGMODEL DMA I2C1 DevStructure pCPAL I2C Struct 512C Timing 0xC062121F I2C1 DevStructure pCPAL TransferRx 4 SEERxStructure I2C1 DevStructure pCPAL TransferTx amp SEETxStructure Initialize CPAL peripheral with the selected parameters CPAL 12C Init amp I2C1_DevStructure Pa Configure the peripheral structure CPAL_I2C_StructInit

CPAL v2 - STMicroelectronics

Contents

Download Pdf Manuals

Related Search

Related Contents