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