KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
i2c.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  * ----------------------
4  *
5  * Copyright 2013 KM3NeT Collaboration
6  *
7  * All Rights Reserved.
8  *
9  *
10  * File : i2c.h
11  * Created : 8 mrt. 2013
12  * Author : Vincent van Beveren
13  */
14 
15 
16 #ifndef I2C_H_
17 #define I2C_H_
18 /**
19  * @file
20  *
21  * @ingroup wbdrivers
22  *
23  * OpenCores I2C device driver.
24  *
25  * Because there are multiple I2C devices in the memory, you will need to provide the device
26  * pointer for each one.
27  * @see dev_soc.h
28  *
29  * Sample code for fictive device providing 4 bytes of data.
30  * @code
31  * // Example initialization
32  * if (!i2cInit(I2C1, I2C_BITRATE_NORMAL)) {
33  * errPrint(true); // print error
34  * return;
35  * }
36  *
37  * // Read from device.
38  * int devId = 0x75;
39  * uint8_t buf[4];
40  * if (!i2cRead(I2C1, devId, buf, sizeof(buf))) {
41  * errPrint(true);
42  * return;
43  * }
44  *
45  * @endcode
46  *
47  */
48 
49 #include <stdint.h>
50 #include <stdbool.h>
51 #include <errorcode.h>
52 #include <kernel/err.h>
53 
54 #include <lm32soc/dev_soc.h>
55 
56 #define I2C_BITRATE_SLOW 10000 ///< I2C normal speed
57 #define I2C_BITRATE_NORMAL 100000 ///< I2C normal speed
58 #define I2C_BITRATE_FAST 400000 ///< I2C fast speed
59 #define I2C_BITRATE_HIGHSPEED 3500000 ///< I2C high speed
60 
61 
62 #define E_I2C_INIT ( E_I2C + 1 ) ///< I2C WB device failed to initialize properly.
63 #define E_I2C_INIT_DESCR "Initialization error"
64 
65 
66 #define E_I2C_ARB_LOST ( E_I2C + 2 ) ///< Arbitration on the I2C bus lost
67 #define E_I2C_ARB_LOST_DESCR "Arbitration Lost"
68 
69 #define E_I2C_NO_ACK ( E_I2C + 3 ) ///< I2C device did not acknowledge TX
70 #define E_I2C_NO_ACK_DESCR "No acknowledge"
71 
72 
73 
74 #define E_I2C_TIME_OUT ( E_I2C + 4 ) ///< I2C device timed out.
75  ///< (for example: clock stretching indefinitely
76  ///< or pull up/down issue)
77 #define E_I2C_TIME_OUT_DESCR "Transmission time out"
78 
79 // ------------------------------------------------------------------------------------
80 // Usage errors
81 //
82 // These errors are not bus issues, but IC's which do not adhere to the protocol
83 // specified in the datasheet. These errors are only emitted by drivers.
84 // ------------------------------------------------------------------------------------
85 
86 /// Protocol error. Driver error if I2C device does not respond as expected.
87 #define E_I2C_IC_PROTO ( E_I2C + 10 )
88 #define E_I2C_IC_PROTO_DESCR "IC did not respond corrctly"
89 
90 /**
91  * I2C address type.
92  */
93 typedef uint8_t i2cAddr;
94 
95 /**
96  * Initializes the I2C device with the specified bitrate.
97  *
98  * @param dev The device to initialize.
99  * @param bitrate The bitrate to set, see I2C_BITRATE_* defines.
100  */
101 bool i2cInit(I2C_Device * dev, uint32_t bitrate);
102 
103 /**
104  * Writes to the I2C device.
105  *
106  * @param dev The WB device.
107  * @param addr The address of the I2C device
108  * @param byte The bytes to send
109  * @param len The no of bytes to send
110  *
111  * @retval true Write was succesful
112  * @retval false Write was unsuccessful, check errCode() for the exact error.
113  */
114 bool i2cWrite(I2C_Device * dev, i2cAddr addr, uint8_t * bytes, int len);
115 
116 /**
117  * Reads from the I2C device.
118  *
119  * @param dev The WB device.
120  * @param addr The address of the I2C device
121  * @param byte The buffer to write into, must be atleast the size of the no of bytes to read.
122  * @param len The no of bytes to read.
123  *
124  * @retval true Write was succesful
125  * @retval false Write was unsuccessful, check errCode() for the exact error.
126  */
127 bool i2cRead(I2C_Device * dev, i2cAddr addr, uint8_t * bytes, int len);
128 
129 /**
130  * Writes and Reads To and from the I2C device.
131  *
132  * @param dev The WB device.
133  * @param addr The address of the I2C device
134  *
135  * @param wr The bytes to send
136  * @param wrLen The no of bytes to send
137  * @param rd The buffer to write into, must be at least the size of the no of bytes to read.
138  * @param rdLen The no of bytes to read.
139  *
140  * @retval true Write was succesful
141  * @retval false Write was unsuccessful, check errCode() for the exact error.
142  */
143 bool i2cWriteRead(I2C_Device * dev, i2cAddr addr, uint8_t * wr, int wrLen, uint8_t * rd, int rdLen);
144 
145 
146 /**
147  * Reads from the I2C device register.
148  *
149  * @param dev The WB device.
150  * @param addr The address of the I2C device
151  * @param reg The register to read.
152  * @param byte The buffer to write into, must be atleast the size of the no of bytes to read.
153  * @param len The no of bytes to read.
154  *
155  * @retval true Write was succesful
156  * @retval false Write was unsuccessful, check errCode() for the exact error.
157  */
158 bool i2cReadReg(I2C_Device * dev, i2cAddr addr, uint8_t regNo, uint8_t * rd, int rdLen);
159 
160 /**
161  * Writes to the I2C device register.
162  *
163  * @param dev The WB device.
164  * @param addr The address of the I2C device
165  * @param reg The register to write.
166  * @param byte The bytes to send
167  * @param len The no of bytes to send
168  *
169  * @retval true Write was succesful
170  * @retval false Write was unsuccessful, check errCode() for the exact error.
171  */
172 bool i2cWriteReg(I2C_Device * dev, i2cAddr addr, uint8_t regNo, uint8_t * wr, int wrLen);
173 
174 
175 /**
176  * Writes a command to the I2C device and receive the answer.
177  * !! alternative protocol mode. Not standard I2C !!
178  *
179  *
180  * @param dev The WB device.
181  * @param addr The address of the I2C device
182  * @param cmd The command to send
183  * @param cmd_len The no of bytes to send in the command
184  * @param answer The buffer to write into, must be at least the size of the no of byte of the answer
185  * @param answer_len The no of bytes to read in the answer
186  *
187  * @retval true Write was succesful
188  * @retval false Write was unsuccessful, check errCode() for the exact error.
189  */
190 bool i2cSendCmdAlt(I2C_Device * dev, i2cAddr addr, uint8_t * cmd, int cmd_len, uint8_t * answer, int answer_len);
191 
192 /**
193  * Reads a register from a I2C device.
194  * !! Alternative protocol mode. Not standard I2C !!
195  *
196  * @param dev The WB device.
197  * @param addr The address of the I2C device
198  * @param reg_addr The register address to read
199  * @param answer The buffer to write into, must be at least the size of the no of byte of the answer
200  * @param len The no of bytes to read in the answer
201  *
202  * @retval true Read was succesful
203  * @retval false Read was unsuccessful, check errCode() for the exact error.
204  */
205 bool i2cReadRegAlt(I2C_Device * dev, i2cAddr addr, uint8_t reg_addr, uint8_t * answer, int len);
206 
207 /**
208  * Checks whether or not an I2C address is present on the bus.
209  *
210  * @param dev I2C Device
211  * @param addr The address to check.
212  * @param canRead Returns whether or not the device can be read
213  * true - The device can be read
214  * false - The device can not be read
215  * @param canWrite Returns whether or not the device can be written
216  * true - The device can be written
217  * false - The device can not be written
218  *
219  * @retval true There was no error (no acks are not returned as errors by this function)
220  * @retval false There was an error. Check error module for exact error.
221  */
222 bool i2cExists(I2C_Device * dev, i2cAddr addr, bool * canRead, bool * canWrite);
223 
224 
225 void i2cDebug(bool enable);
226 
227 #endif /* I2C_H_ */
bool i2cWrite(I2C_Device *dev, i2cAddr addr, uint8_t *bytes, int len)
Writes to the I2C device.
Definition: i2c.c:219
bool i2cExists(I2C_Device *dev, i2cAddr addr, bool *canRead, bool *canWrite)
Checks whether or not an I2C address is present on the bus.
Definition: i2c.c:326
Structure defines OpenCores I2C Device.
Definition: dev_i2c.h:55
bool i2cSendCmdAlt(I2C_Device *dev, i2cAddr addr, uint8_t *cmd, int cmd_len, uint8_t *answer, int answer_len)
Writes a command to the I2C device and receive the answer.
Definition: i2c.c:287
uint8_t i2cAddr
I2C address type.
Definition: i2c.h:93
bool i2cReadReg(I2C_Device *dev, i2cAddr addr, uint8_t regNo, uint8_t *rd, int rdLen)
Reads from the I2C device register.
Definition: i2c.c:188
bool i2cWriteRead(I2C_Device *dev, i2cAddr addr, uint8_t *wr, int wrLen, uint8_t *rd, int rdLen)
Writes and Reads To and from the I2C device.
Definition: i2c.c:280
bool i2cWriteReg(I2C_Device *dev, i2cAddr addr, uint8_t regNo, uint8_t *wr, int wrLen)
Writes to the I2C device register.
Definition: i2c.c:247
Manages the global system error.
bool i2cInit(I2C_Device *dev, uint32_t bitrate)
Initializes the I2C device with the specified bitrate.
Definition: i2c.c:122
bool i2cReadRegAlt(I2C_Device *dev, i2cAddr addr, uint8_t reg_addr, uint8_t *answer, int len)
Reads a register from a I2C device.
Definition: i2c.c:356
This module is responsible for distributing error codes.
bool i2cRead(I2C_Device *dev, i2cAddr addr, uint8_t *bytes, int len)
Reads from the I2C device.
Definition: i2c.c:161
This file assigns all device structures to memory mapped structures.