oranges and enhance strats
[aversive.git] / modules / comm / i2c / i2c.h
1 /*  
2  *  Copyright Droids Corporation, Microb Technology, Eirbot (2007)
3  * 
4  *  This program is free software; you can redistribute it and/or modify
5  *  it under the terms of the GNU General Public License as published by
6  *  the Free Software Foundation; either version 2 of the License, or
7  *  (at your option) any later version.
8  *
9  *  This program is distributed in the hope that it will be useful,
10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  *  GNU General Public License for more details.
13  *
14  *  You should have received a copy of the GNU General Public License
15  *  along with this program; if not, write to the Free Software
16  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
17  *
18  *  Revision : $Id: i2c.h,v 1.1.2.9 2009-01-23 22:57:17 zer0 Exp $
19  *
20  */
21
22 /* Author Zer0, based on Tof old i2c module */
23
24 /** please read carefully !
25  *
26  *
27  * this implementation of the i2c interface is very specific this is a
28  * multi bus implementation. The multi bus operation is done by
29  * implementing software i2c modules (slave only)
30  *
31  * HARDWARE I2C :
32  * --------------
33  *
34  * This module implements i2c using the hardware twi interface of AVR
35  * devices. It can operates in slave and/or master mode, depending on
36  * the initialisation parameter. This module is interrupt driven only.
37  *
38  * In master mode, buffer can be transmitted/received on demand (with
39  * start and stop conditions). In slave mode, operations are done
40  * asynchronously. Like some other modules in aversive, callback
41  * functions can be registered and are called on transmission or
42  * reception events.
43  *
44  * This module should support multimaster mode, send() or recv() depends
45  * on the address parameter.
46  */
47 #ifndef _I2C_H_
48 #define _I2C_H_
49
50 #include <aversive.h>
51 #include <i2c_config.h>
52
53 #define I2C_DEBUG 1
54
55 #define I2C_ADD_GENCALL 0x00
56
57 /* this is not a valid address regarding the I2C protocol, but is used
58  * as a magic for addressing the master from the slave */
59 #define I2C_ADD_MASTER  0x80
60
61
62
63
64 /* I2C modes */
65 typedef enum { I2C_MODE_UNINIT,      /**< not initialized */
66                I2C_MODE_SLAVE,       /**< Slave */
67 #ifdef CONFIG_MODULE_I2C_MASTER
68                I2C_MODE_MASTER,      /**< Master */
69 #endif
70 #ifdef CONFIG_MODULE_I2C_MULTIMASTER
71                I2C_MODE_MULTIMASTER, /**< Master, but allow multimaster mode */
72 #endif
73 } i2c_mode_t ;
74
75 /* control flags */
76 #define I2C_CTRL_GENERIC            0x00
77 /** Error code is returned instead of beeing sent as a callback. Note
78  *  that the send_event callback is _not_ called if it is
79  *  registered. This functions waits and only returns when the
80  *  transmission is finished or if it failed. Note that there is no
81  *  timeout, so it can loop forever... WARNING : irq MUST be
82  *  allowed */
83 #define I2C_CTRL_SYNC               0x01
84 /** when the operation is finished as a master, don't release the bus
85  *  (don't send any stop condition). You can send several commands
86  *  without beeing interrupted by another master. To release it, send
87  *  another command without this flag or just call
88  *  i2c_release_bus(). This has no effect on a slave. */
89 #define I2C_CTRL_DONT_RELEASE_BUS   0x02
90
91
92 /* status flags */
93 #define I2C_STATUS_READY            0x00
94 #define I2C_STATUS_MASTER_XMIT      0x01
95 #define I2C_STATUS_MASTER_RECV      0x02
96 #define I2C_STATUS_SLAVE_XMIT_WAIT  0x04
97 #define I2C_STATUS_SLAVE_XMIT       0x08
98 #define I2C_STATUS_SLAVE_RECV       0x10
99 #define I2C_STATUS_OP_FINISHED      0x20
100 #define I2C_STATUS_NEED_XMIT_EVT    0x40
101 #define I2C_STATUS_NEED_RECV_EVT    0x80
102
103
104 /**
105  * mode is I2C_MODE_UNINIT, I2C_MODE_MASTER, I2C_MODE_MULTIMASTER or
106  * I2C_MODE_SLAVE. Parameter add is the address in slave mode, it is
107  * composed from: 
108  *   b7  : true if the uC can be addressed with GENCALL
109  *   b0-6: slave address
110  */
111 void i2c_init(i2c_mode_t mode, uint8_t add);
112
113
114 /** 
115  * Register a function that is called when a buffer is received. The
116  * user application is always notified when data frame is received.
117  * Arguments of the callback are:
118  *   - (recv_buf, n>0) if transmission succedded. The first parameter 
119  *                     contains the address of the reception buffer and
120  *                     the second contains the number of received bytes.
121  *   - (NULL, err<0)   if the transmission failed (slave not answering
122  *                     or arbiteration lost). The first parameter is 
123  *                     NULL and the second contains the error code.
124  */
125 void i2c_register_recv_event(void (*event)(uint8_t *, int8_t));
126
127 /** 
128  * Register a function that is called when a byte is received.
129  * Arguments of the callback are: (hwstatus, numbyte, byte).  The user
130  * app can modify the g_size value, which is the number of bytes to be
131  * received in the frame: this can be done by calling
132  * i2c_set_recv_size().
133  */
134 void i2c_register_recv_byte_event(void (*event)(uint8_t, uint8_t, uint8_t));
135
136
137 /**
138  * register a function that is called when a buffer is sent (or an
139  * error occured while sending) on the i2c bus. The event function is
140  * always called by software if the i2c_send() function returned 0.
141  * The parameter of the event function is the error code:
142  *   -  0 if the number of transmitted bytes is equal to the size 
143  *      of the original send buffer, without NACK. 
144  *   -  <0 if 0 byte has been transmitted (slave not answering or
145  *      arbiteration lost)
146  *   -  Else, the number of transmitted bytes is given, including the
147  *      one that was not acked.
148  */
149 void i2c_register_send_event(void (*event)(int8_t));
150
151
152 /**
153  * Send a buffer. Return 0 if xmit starts correctly.
154  * On error, return < 0.
155  * - If mode is slave, dest_add should be I2C_ADD_MASTER, and transmission 
156  *   starts when the master transmits a clk. 
157  * - If mode is master and if dest_add != I2C_ADD_MASTER, it will transmit 
158  *   a START condition if bus is available (the uc will act as a 
159  *   master)
160  * - If mode is master and if dest_add == I2C_ADD_MASTER, the uC will
161  *   act as a slave, and data will be sent when the uC will be
162  *   addressed.
163  * The transmission will be processed with these params until a
164  * i2c_flush() is called. 
165  * The 'ctrl' parameter is composed by the flags I2C_CTRL_SYNC and 
166  * I2C_CTRL_DONT_RELEASE_BUS
167  */
168 int8_t i2c_send(uint8_t dest_add, uint8_t *buf, uint8_t size, uint8_t ctrl);
169
170 /**
171  * Resend the same buffer. This call is equivalent to i2c_send() with
172  * the same parameters as the last call. It safe to call it from the
173  * send_event, but else the send buffer may have been overwritten.
174  */
175 int8_t i2c_resend(void);
176
177 /**
178  * same but for recv
179  */
180 int8_t i2c_rerecv(void);
181
182 /**
183  * release the bus
184  */
185 void i2c_release_bus(void);
186
187 /**
188  * In slave mode, it returns error and is useless (all data is
189  * received trough the callback). In master mode, if dest_add is
190  * between 0 and 127, it will start to read the addressed slave. The
191  * size of the buffer to read must be specified. Return 0 on success.
192  * The 'ctrl' parameter is composed by the flags I2C_CTRL_SYNC and
193  * I2C_CTRL_DONT_RELEASE_BUS
194  */
195 int8_t i2c_recv(uint8_t dest_add, uint8_t size, uint8_t ctrl);
196
197
198 /**
199  * Try to flush the current operation, before it is started. The
200  * i2c module is then tagged as ready. If it returns 0, the flush was 
201  * a success, and i2c_send() can be called. Else, it means that 
202  * a transmission was running. 
203  */
204 int8_t i2c_flush(void);
205
206 /**
207  * In MASTER RECEIVER mode, it is possible that the user application
208  * does not know the size of the buffer. You can adjust this size
209  * during transmission (generally the size can be specified at the
210  * beginning of received data, so the user app can be notified thanks
211  * to recv_byte_event(). Note that i2c_set_recv_size() function has to
212  * be used with careful, making sure you understand i2c protocol and
213  * this code. Return 0 on success. Note than in SLAVE RECEIVER mode,
214  * you don't have to use this function, because the master can end the
215  * transmission by sending a stop condition on the bus.
216  */
217 uint8_t i2c_set_recv_size(uint8_t size);
218
219 /**
220  * return the current mode of the i2c module.
221  */
222 i2c_mode_t i2c_mode(void);
223
224 /**
225  * return the status of the i2c module.
226  */
227 uint8_t i2c_status(void);
228
229 /**
230  * Copy the received buffer in the buffer given as parameter. Return
231  * number of copied bytes or < 0 on error.
232  */
233 uint8_t i2c_get_recv_buffer(uint8_t *buf, uint8_t size);
234
235 /**
236  * recover from error states
237  */
238 void i2c_reset(void);
239
240 #if I2C_DEBUG == 1
241 /**
242  * display debug infos
243  */
244 void i2c_debug(void);
245 #endif
246
247
248 #endif