iLLD_TC27xC  1.0
IfxI2c_I2c.h
Go to the documentation of this file.
1 /**
2  * \file IfxI2c_I2c.h
3  * \brief I2C I2C details
4  * \ingroup IfxLld_I2c
5  *
6  * \version iLLD_0_1_0_10
7  * \copyright Copyright (c) 2013 Infineon Technologies AG. All rights reserved.
8  *
9  *
10  * IMPORTANT NOTICE
11  *
12  *
13  * Infineon Technologies AG (Infineon) is supplying this file for use
14  * exclusively with Infineon's microcontroller products. This file can be freely
15  * distributed within development tools that are supporting such microcontroller
16  * products.
17  *
18  * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED
19  * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
21  * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL,
22  * OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
23  *
24  * \defgroup IfxLld_I2c_I2c_Usage How to use the I2c driver?
25  * \ingroup IfxLld_I2c
26  *
27  * The I2c driver provides a default configuration for 8bit wide data transfers in Master mode.
28  *
29  * NOTE: Interrupts are disabled during data transfers as long as the driver operates on the I2C hardware FIFO,
30  * except for reading 32 bytes or less. This is due to imperfections of the I2c Module.
31  *
32  * In the following sections it will be described, how to integrate the driver into the application framework.
33  *
34  * \section IfxLld_I2c_I2c Preparation Preparation
35  * \subsection IfxLld_I2c_I2c_Include Include Files
36  *
37  * Include following header file into your C code:
38  * \code
39  * #include <I2c/I2c/IfxI2c_I2c.h>
40  * \endcode
41  *
42  * \subsection IfxLld_I2c_I2c_Variables Variables
43  *
44  * Declare the I2c handle, the I2c device handle and the data buffer in your C code:
45  *
46  * \code
47  * // used globally
48  * static IfxI2c_I2c i2c; // i2c handle
49  * static IfxI2c_I2c_Device i2cDev; // slave device handle
50  * uint8 data[128]; // data buffer
51  * \endcode
52  *
53  * \subsection IfxLld_I2c_I2c_Init Module Initialisation
54  *
55  * \code
56  * // create config structure
57  * IfxI2c_I2c_Config config;
58  *
59  * // fill structure with default values and Module address
60  * IfxI2c_I2c_initConfig(&coinfig, &MODULE_I2C0);
61  *
62  * // configure pins
63  * const IfxI2c_Pins pins = {
64  * &IfxI2c0_SCL_P02_5_INOUT,
65  * &IfxI2c0_SDA_P02_4_INOUT,
66  * IfxPort_PadDriver_cmosAutomotiveSpeed1
67  * };
68  *
69  * config.pins = &pins;
70  * config.baudrate = 400000; // 400 kHz
71  *
72  * // initialize module
73  * IfxI2c_I2c_initModule(&i2c, &config);
74  * \endcode
75  *
76  * \subsection IfxLld_I2c_I2c_InitDevice Device Initialisation
77  * Here the i2c device handle is initialized.
78  * \code
79  * // create device config
80  * IfxI2c_I2c_deviceConfig i2cDeviceConfig;
81  *
82  * // fill structure with default values and i2c Handler
83  * IfxI2c_I2c_initDeviceConfig(&i2cDeviceConfig, &i2c);
84  *
85  * // set device specifig values
86  * i2cDeviceConfig.deviceAdddress = 0xa0;
87  *
88  * // initialize the i2c device handle
89  * IfxI2c_I2c_initDevice(&i2cDeviceConfig, &i2cDev);
90  * \endcode
91  *
92  * \section IfxLld_I2c_I2c_DataTransfers Data Transfers
93  * Example for an i2c EEPROM.
94  *
95  * \subsection IfxLld_I2c_I2c_Write Write
96  *
97  * \code
98  * uint16 addr = 0x0000;
99  *
100  * // setup the device's internal address
101  * data[0] = addr >> 8; // High byte
102  * data[1] = (uint8)addr; // Low byte
103  * // setup data to be written
104  * data[2] = 0x01;
105  * data[3] = 0x02;
106  * data[4] = 0x03;
107  *
108  * uint8 size = 5; // 5 bytes to transmit to i2cDev (data and internal address)
109  *
110  * // write data to device as soon as it is ready
111  * while(IfxI2c_I2c_write(&i2cDev, data, size) == IfxI2c_I2c_Status_nak);
112  * \endcode
113  *
114  * \subsection IfxLld_I2c_I2c_Read Read
115  *
116  * \code
117  * Ifx_SizeT size;
118  * uint16 addr = 0x0000;
119  *
120  * // setup internal address to be read from
121  * data[0] = addr >> 8; // High byte
122  * data[1] = (uint8)addr; // Low byte
123  * size = 2;
124  * while(IfxI2c_I2c_write(&i2cDev, data, size) == IfxI2c_I2c_Status_nak);
125  *
126  * size = 8; // 8 bytes to read
127  *
128  * // read device data to data array
129  * while(IfxI2c_I2c_read(&i2cDev, data, size) == IfxI2c_I2c_Status_nak);
130  * \endcode
131  *
132  * \subsection IfxLld_I2c_I2c_ACK Acknowledge Polling
133  * It is also possible to poll explicitly for NAK.
134  *
135  * By using write operations:
136  * \code
137  * // size = 0;
138  * while(IfxI2c_I2c_write(&i2cDev, data, 0) == IfxI2c_I2c_Status_nak)); // where data is just a dummy pointer
139  * \endcode
140  *
141  * By using read operations:
142  * \code
143  * // size = 0;
144  * while(IfxI2c_I2c_read(&i2cDev, data, 0) == IfxI2c_I2c_Status_nak)); // where data is just a dummy pointer
145  * \endcode
146  *
147  * \defgroup IfxLld_I2c_I2c I2c
148  * \ingroup IfxLld_I2c
149  * \defgroup IfxLld_I2c_I2c_Functions Module Functions
150  * \ingroup IfxLld_I2c_I2c
151  * \defgroup IfxLld_I2c_I2c_Enum Enumerations
152  * \ingroup IfxLld_I2c_I2c
153  * \defgroup IfxLld_I2c_I2c_DataStructures Data Structures
154  * \ingroup IfxLld_I2c_I2c
155  */
156 
157 #ifndef IFXI2C_I2C_H
158 #define IFXI2C_I2C_H 1
159 
160 /******************************************************************************/
161 /*----------------------------------Includes----------------------------------*/
162 /******************************************************************************/
163 
164 #include "I2c/Std/IfxI2c.h"
165 
166 /******************************************************************************/
167 /*--------------------------------Enumerations--------------------------------*/
168 /******************************************************************************/
169 
170 /** \addtogroup IfxLld_I2c_I2c_Enum
171  * \{ */
172 typedef enum
173 {
174  IfxI2c_I2c_Status_ok = 0, /**< \brief ok */
175  IfxI2c_I2c_Status_nak = 1, /**< \brief NAK */
176  IfxI2c_I2c_Status_al = 2, /**< \brief Arbitration Lost */
177  IfxI2c_I2c_Status_busNotFree = 3, /**< \brief bus is not free */
178  IfxI2c_I2c_Status_error = 4 /**< \brief error */
180 
181 /** \} */
182 
183 /******************************************************************************/
184 /*-----------------------------Data Structures--------------------------------*/
185 /******************************************************************************/
186 
187 /** \addtogroup IfxLld_I2c_I2c_DataStructures
188  * \{ */
189 /** \brief Handler
190  */
191 typedef struct
192 {
193  Ifx_I2C *i2c; /**< \brief Module Pointer */
194  IfxI2c_BusStatus busStatus; /**< \brief Status of the bus */
195  IfxI2c_I2c_Status status; /**< \brief Status of the last bus operation */
196  float32 baudrate; /**< \brief Baudrate */
197 } IfxI2c_I2c;
198 
199 /** \brief Structure to configure the Module
200  */
201 typedef struct
202 {
203  Ifx_I2C *i2c; /**< \brief Module Pointer */
204  float32 baudrate; /**< \brief Baudrate */
205  const IfxI2c_Pins *pins; /**< \brief Pins */
207 
208 /** \brief Structure with slave device data
209  */
210 typedef struct
211 {
212  IfxI2c_I2c *i2c; /**< \brief Module Pionter */
215 
216 /** \brief Structure to configure the device's data structure
217  */
218 typedef struct
219 {
220  IfxI2c_I2c *i2c; /**< \brief Module Pointer */
221  uint8 deviceAddress; /**< \brief the slave device's address */
223 
224 /** \} */
225 
226 /** \addtogroup IfxLld_I2c_I2c_Functions
227  * \{ */
228 
229 /******************************************************************************/
230 /*-------------------------Global Function Prototypes-------------------------*/
231 /******************************************************************************/
232 
233 /** \brief Fills the config structure with default values
234  * \param config Structure to configure the Module
235  * \param i2c Module address
236  * \return None
237  */
238 IFX_EXTERN void IfxI2c_I2c_initConfig(IfxI2c_I2c_Config *config, Ifx_I2C *i2c);
239 
240 /** \brief Initializes the device Handler
241  * \param i2cDeviceConfig Structure to configure the device's data structure
242  * \param i2cDevice I2c device Handler
243  * \return None
244  *
245  * Usage Example:
246  * \code
247  * // create device config
248  * IfxI2c_I2c_deviceConfig i2cDeviceConfig;
249  * // fill structure with default values and i2c Handler
250  * IfxI2c_I2c_initDeviceConfig(&i2cDeviceConfig, &i2c);
251  *
252  * // set device specifig values
253  * i2cDeviceConfig.deviceAdddress = devAddr // i2c device address
254  *
255  * // IfxI2c_I2c_Device i2cDev // device Handler, defined globally
256  * IfxI2c_I2c_initDevice(&i2cDeviceConfig, &i2cDev);
257  * \endcode
258  *
259  */
260 IFX_EXTERN void IfxI2c_I2c_initDevice(const IfxI2c_I2c_deviceConfig *i2cDeviceConfig, IfxI2c_I2c_Device *i2cDevice);
261 
262 /** \brief Fills the config structure of the slave device with default values.
263  * \param i2cDeviceConfig Structure to configure the device's data structure
264  * \param i2c Handler
265  * \return None
266  */
268 
269 /** \brief Initializes the Module
270  * \param i2c Handler
271  * \param config Configuration structure
272  * \return None
273  *
274  * Usage Example:
275  * \code
276  * // create config structure
277  * IfxI2c_I2c_Config config;
278  * // fill structure with default values and Module address
279  * IfxI2c_I2c_initConfig(&coinfig, &MODULE_I2C0);
280  *
281  * // configure pins
282  * const IfxI2c_Pins pins = {
283  * &IfxI2c0_SCL_P02_5_INOUT,
284  * &IfxI2c0_SDA_P02_4_INOUT,
285  * IfxPort_PadDriver_cmosAutomotiveSpeed1
286  * };
287  *
288  * config.pins = &pins;
289  * config.baudrate = 400000; // 400 kHz
290  *
291  * // initialize module
292  * // IfxI2c_I2c i2c; // Handler, defined globally
293  * IfxI2c_I2c_initModule(&i2c, &config);
294  * \endcode
295  *
296  */
298 
299 /** \brief reads the I2c device
300  *
301  * Usage Example:
302  * \code
303  * uint8 data[64];
304  * uint16 addr = 0x0000;
305  * IfxI2c_I2c_Status s;
306  *
307  * // setup internal address to be read from
308  * data[0] = addr >> 8; // High byte
309  * data[1] = (uint8)addr; // Low byte
310  *
311  * while((s = IfxI2c_I2c_write(&i2cDev, data, 2)) == IfxI2c_I2c_Status_nak);
312  *
313  *
314  * uint8 size = 8; // 8 bytes to read
315  *
316  * // read
317  * IfxI2c_I2c_read(&i2cDev, data, size);
318  * \endcode
319  *
320  */
322 
323 /** \brief writes to the I2c device
324  *
325  * Usage Example:
326  * \code
327  * uint8 data[64];
328  * uint16 addr = 0x0000;
329  *
330  * // setup the device's internal address
331  * data[0] = addr >> 8; // High byte
332  * data[1] = (uint8)addr; // Low byte
333  *
334  * // setup data to be written
335  * data[2] = 0x01;
336  * data[3] = 0x02;
337  * data[4] = 0x03;
338  *
339  * uint8 size = 5; // 5 bytes to transmit to i2cDev
340  *
341  * // write
342  * IfxI2c_I2c_write(&i2cDev, &data, size);
343  * \endcode
344  *
345  */
347 
348 /** \} */
349 
350 #endif /* IFXI2C_I2C_H */