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