i2c_api.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_I2C_API_H
00017 #define MBED_I2C_API_H
00018 
00019 #include "device.h"
00020 #include "buffer.h"
00021 
00022 #if DEVICE_I2C
00023 
00024 /**
00025  * @defgroup I2CEvents I2C Events Macros
00026  *
00027  * @{
00028  */
00029 #define I2C_EVENT_ERROR               (1 << 1)
00030 #define I2C_EVENT_ERROR_NO_SLAVE      (1 << 2)
00031 #define I2C_EVENT_TRANSFER_COMPLETE   (1 << 3)
00032 #define I2C_EVENT_TRANSFER_EARLY_NACK (1 << 4)
00033 #define I2C_EVENT_ALL                 (I2C_EVENT_ERROR |  I2C_EVENT_TRANSFER_COMPLETE | I2C_EVENT_ERROR_NO_SLAVE | I2C_EVENT_TRANSFER_EARLY_NACK)
00034 
00035 /**@}*/
00036 
00037 #if DEVICE_I2C_ASYNCH
00038 /** Asynch i2c hal structure
00039  */
00040 typedef struct {
00041     struct i2c_s    i2c;     /**< Target specific i2c structure */
00042     struct buffer_s tx_buff; /**< Tx buffer */
00043     struct buffer_s rx_buff; /**< Rx buffer */
00044 } i2c_t;
00045 
00046 #else
00047 /** Non-asynch i2c hal structure
00048  */
00049 typedef struct i2c_s i2c_t;
00050 
00051 #endif
00052 
00053 enum {
00054   I2C_ERROR_NO_SLAVE = -1,
00055   I2C_ERROR_BUS_BUSY = -2
00056 };
00057 
00058 #ifdef __cplusplus
00059 extern "C" {
00060 #endif
00061 
00062 /**
00063  * \defgroup GeneralI2C I2C Configuration Functions
00064  * @{
00065  */
00066 
00067 /** Initialize the I2C peripheral. It sets the default parameters for I2C
00068  *  peripheral, and configure its specifieds pins.
00069  *  @param obj  The i2c object
00070  *  @param sda  The sda pin
00071  *  @param scl  The scl pin
00072  */
00073 void i2c_init(i2c_t *obj, PinName sda, PinName scl);
00074 
00075 /** Configure the I2C frequency.
00076  *  @param obj The i2c object
00077  *  @param hz  Frequency in Hz
00078  */
00079 void i2c_frequency(i2c_t *obj, int hz);
00080 
00081 /** Send START command.
00082  *  @param obj The i2c object
00083  */
00084 int  i2c_start(i2c_t *obj);
00085 
00086 /** Send STOP command.
00087  *  @param obj The i2c object
00088  */
00089 int  i2c_stop(i2c_t *obj);
00090 
00091 /** Blocking reading data.
00092  *  @param obj     The i2c object
00093  *  @param address 7-bit address (last bit is 1)
00094  *  @param data    The buffer for receiving
00095  *  @param length  Number of bytes to read
00096  *  @param stop    Stop to be generated after the transfer is done
00097  *  @return Number of read bytes
00098  */
00099 int  i2c_read(i2c_t *obj, int address, char *data, int length, int stop);
00100 
00101 /** Blocking sending data.
00102  *  @param obj     The i2c object
00103  *  @param address 7-bit address (last bit is 0)
00104  *  @param data    The buffer for sending
00105  *  @param length  Number of bytes to wrte
00106  *  @param stop    Stop to be generated after the transfer is done
00107  *  @return Number of written bytes
00108  */
00109 int  i2c_write(i2c_t *obj, int address, const char *data, int length, int stop);
00110 
00111 /** Reset I2C peripheral. TODO: The action here. Most of the implementation sends stop().
00112  *  @param obj The i2c object
00113  */
00114 void i2c_reset(i2c_t *obj);
00115 
00116 /** Read one byte.
00117  *  @param obj The i2c object
00118  *  @param last Acknoledge
00119  *  @return The read byte
00120  */
00121 int  i2c_byte_read(i2c_t *obj, int last);
00122 
00123 /** Write one byte.
00124  *  @param obj The i2c object
00125  *  @param data Byte to be written
00126  *  @return 1 if NAK was received, 0 if ACK was received, 2 for timeout.
00127  */
00128 int  i2c_byte_write(i2c_t *obj, int data);
00129 
00130 /**@}*/
00131 
00132 #if DEVICE_I2CSLAVE
00133 
00134 /**
00135  * \defgroup SynchI2C Synchronous I2C Hardware Abstraction Layer for slave
00136  * @{
00137  */
00138 
00139 /** Configure I2C as slave or master.
00140  *  @param obj The I2C object
00141  *  @return non-zero if a value is available
00142  */
00143 void i2c_slave_mode(i2c_t *obj, int enable_slave);
00144 
00145 /** Check to see if the I2C slave has been addressed.
00146  *  @param obj The I2C object
00147  *  @return The status - 1 - read addresses, 2 - write to all slaves,
00148  *         3 write addressed, 0 - the slave has not been addressed
00149  */
00150 int  i2c_slave_receive(i2c_t *obj);
00151 
00152 /** Configure I2C as slave or master.
00153  *  @param obj The I2C object
00154  *  @return non-zero if a value is available
00155  */
00156 int  i2c_slave_read(i2c_t *obj, char *data, int length);
00157 
00158 /** Configure I2C as slave or master.
00159  *  @param obj The I2C object
00160  *  @return non-zero if a value is available
00161  */
00162 int  i2c_slave_write(i2c_t *obj, const char *data, int length);
00163 
00164 /** Configure I2C address.
00165  *  @param obj     The I2C object
00166  *  @param idx     Currently not used
00167  *  @param address The address to be set
00168  *  @param mask    Currently not used
00169  */
00170 void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask);
00171 
00172 #endif
00173 
00174 /**@}*/
00175 
00176 #if DEVICE_I2C_ASYNCH
00177 
00178 /**
00179  * \defgroup AsynchI2C Asynchronous I2C Hardware Abstraction Layer
00180  * @{
00181  */
00182 
00183 /** Start i2c asynchronous transfer.
00184  *  @param obj       The I2C object
00185  *  @param tx        The buffer to send
00186  *  @param tx_length The number of words to transmit
00187  *  @param rx        The buffer to receive
00188  *  @param rx_length The number of words to receive
00189  *  @param address   The address to be set - 7bit or 9 bit
00190  *  @param stop      If true, stop will be generated after the transfer is done
00191  *  @param handler   The I2C IRQ handler to be set
00192  *  @param hint      DMA hint usage
00193  */
00194 void i2c_transfer_asynch(i2c_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint32_t address, uint32_t stop, uint32_t handler, uint32_t event, DMAUsage hint);
00195 
00196 /** The asynchronous IRQ handler
00197  *  @param obj The I2C object which holds the transfer information
00198  *  @return event flags if a transfer termination condition was met or 0 otherwise.
00199  */
00200 uint32_t i2c_irq_handler_asynch(i2c_t *obj);
00201 
00202 /** Attempts to determine if I2C peripheral is already in use.
00203  *  @param obj The I2C object
00204  *  @return non-zero if the I2C module is active or zero if it is not
00205  */
00206 uint8_t i2c_active(i2c_t *obj);
00207 
00208 /** Abort ongoing asynchronous transaction.
00209  *  @param obj The I2C object
00210  */
00211 void i2c_abort_asynch(i2c_t *obj);
00212 
00213 #endif
00214 
00215 /**@}*/
00216 
00217 #ifdef __cplusplus
00218 }
00219 #endif
00220 
00221 #endif
00222 
00223 #endif