EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

hal/i2c_api.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

UserRevisionLine numberNew contents of line
be_bryan 0:b74591d5ab33 1
be_bryan 0:b74591d5ab33 2 /** \addtogroup hal */
be_bryan 0:b74591d5ab33 3 /** @{*/
be_bryan 0:b74591d5ab33 4 /* mbed Microcontroller Library
be_bryan 0:b74591d5ab33 5 * Copyright (c) 2006-2015 ARM Limited
be_bryan 0:b74591d5ab33 6 *
be_bryan 0:b74591d5ab33 7 * Licensed under the Apache License, Version 2.0 (the "License");
be_bryan 0:b74591d5ab33 8 * you may not use this file except in compliance with the License.
be_bryan 0:b74591d5ab33 9 * You may obtain a copy of the License at
be_bryan 0:b74591d5ab33 10 *
be_bryan 0:b74591d5ab33 11 * http://www.apache.org/licenses/LICENSE-2.0
be_bryan 0:b74591d5ab33 12 *
be_bryan 0:b74591d5ab33 13 * Unless required by applicable law or agreed to in writing, software
be_bryan 0:b74591d5ab33 14 * distributed under the License is distributed on an "AS IS" BASIS,
be_bryan 0:b74591d5ab33 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
be_bryan 0:b74591d5ab33 16 * See the License for the specific language governing permissions and
be_bryan 0:b74591d5ab33 17 * limitations under the License.
be_bryan 0:b74591d5ab33 18 */
be_bryan 0:b74591d5ab33 19 #ifndef MBED_I2C_API_H
be_bryan 0:b74591d5ab33 20 #define MBED_I2C_API_H
be_bryan 0:b74591d5ab33 21
be_bryan 0:b74591d5ab33 22 #include "device.h"
be_bryan 0:b74591d5ab33 23 #include "hal/buffer.h"
be_bryan 0:b74591d5ab33 24
be_bryan 0:b74591d5ab33 25 #if DEVICE_I2C_ASYNCH
be_bryan 0:b74591d5ab33 26 #include "hal/dma_api.h"
be_bryan 0:b74591d5ab33 27 #endif
be_bryan 0:b74591d5ab33 28
be_bryan 0:b74591d5ab33 29 #if DEVICE_I2C
be_bryan 0:b74591d5ab33 30
be_bryan 0:b74591d5ab33 31 /**
be_bryan 0:b74591d5ab33 32 * @defgroup hal_I2CEvents I2C Events Macros
be_bryan 0:b74591d5ab33 33 *
be_bryan 0:b74591d5ab33 34 * @{
be_bryan 0:b74591d5ab33 35 */
be_bryan 0:b74591d5ab33 36 #define I2C_EVENT_ERROR (1 << 1)
be_bryan 0:b74591d5ab33 37 #define I2C_EVENT_ERROR_NO_SLAVE (1 << 2)
be_bryan 0:b74591d5ab33 38 #define I2C_EVENT_TRANSFER_COMPLETE (1 << 3)
be_bryan 0:b74591d5ab33 39 #define I2C_EVENT_TRANSFER_EARLY_NACK (1 << 4)
be_bryan 0:b74591d5ab33 40 #define I2C_EVENT_ALL (I2C_EVENT_ERROR | I2C_EVENT_TRANSFER_COMPLETE | I2C_EVENT_ERROR_NO_SLAVE | I2C_EVENT_TRANSFER_EARLY_NACK)
be_bryan 0:b74591d5ab33 41
be_bryan 0:b74591d5ab33 42 /**@}*/
be_bryan 0:b74591d5ab33 43
be_bryan 0:b74591d5ab33 44 #if DEVICE_I2C_ASYNCH
be_bryan 0:b74591d5ab33 45 /** Asynch I2C HAL structure
be_bryan 0:b74591d5ab33 46 */
be_bryan 0:b74591d5ab33 47 typedef struct {
be_bryan 0:b74591d5ab33 48 struct i2c_s i2c; /**< Target specific I2C structure */
be_bryan 0:b74591d5ab33 49 struct buffer_s tx_buff; /**< Tx buffer */
be_bryan 0:b74591d5ab33 50 struct buffer_s rx_buff; /**< Rx buffer */
be_bryan 0:b74591d5ab33 51 } i2c_t;
be_bryan 0:b74591d5ab33 52
be_bryan 0:b74591d5ab33 53 #else
be_bryan 0:b74591d5ab33 54 /** Non-asynch I2C HAL structure
be_bryan 0:b74591d5ab33 55 */
be_bryan 0:b74591d5ab33 56 typedef struct i2c_s i2c_t;
be_bryan 0:b74591d5ab33 57
be_bryan 0:b74591d5ab33 58 #endif
be_bryan 0:b74591d5ab33 59
be_bryan 0:b74591d5ab33 60 enum {
be_bryan 0:b74591d5ab33 61 I2C_ERROR_NO_SLAVE = -1,
be_bryan 0:b74591d5ab33 62 I2C_ERROR_BUS_BUSY = -2
be_bryan 0:b74591d5ab33 63 };
be_bryan 0:b74591d5ab33 64
be_bryan 0:b74591d5ab33 65 #ifdef __cplusplus
be_bryan 0:b74591d5ab33 66 extern "C" {
be_bryan 0:b74591d5ab33 67 #endif
be_bryan 0:b74591d5ab33 68
be_bryan 0:b74591d5ab33 69 /**
be_bryan 0:b74591d5ab33 70 * \defgroup hal_GeneralI2C I2C Configuration Functions
be_bryan 0:b74591d5ab33 71 * @{
be_bryan 0:b74591d5ab33 72 */
be_bryan 0:b74591d5ab33 73
be_bryan 0:b74591d5ab33 74 /** Initialize the I2C peripheral. It sets the default parameters for I2C
be_bryan 0:b74591d5ab33 75 * peripheral, and configures its specifieds pins.
be_bryan 0:b74591d5ab33 76 *
be_bryan 0:b74591d5ab33 77 * @param obj The I2C object
be_bryan 0:b74591d5ab33 78 * @param sda The sda pin
be_bryan 0:b74591d5ab33 79 * @param scl The scl pin
be_bryan 0:b74591d5ab33 80 */
be_bryan 0:b74591d5ab33 81 void i2c_init(i2c_t *obj, PinName sda, PinName scl);
be_bryan 0:b74591d5ab33 82
be_bryan 0:b74591d5ab33 83 /** Configure the I2C frequency
be_bryan 0:b74591d5ab33 84 *
be_bryan 0:b74591d5ab33 85 * @param obj The I2C object
be_bryan 0:b74591d5ab33 86 * @param hz Frequency in Hz
be_bryan 0:b74591d5ab33 87 */
be_bryan 0:b74591d5ab33 88 void i2c_frequency(i2c_t *obj, int hz);
be_bryan 0:b74591d5ab33 89
be_bryan 0:b74591d5ab33 90 /** Send START command
be_bryan 0:b74591d5ab33 91 *
be_bryan 0:b74591d5ab33 92 * @param obj The I2C object
be_bryan 0:b74591d5ab33 93 */
be_bryan 0:b74591d5ab33 94 int i2c_start(i2c_t *obj);
be_bryan 0:b74591d5ab33 95
be_bryan 0:b74591d5ab33 96 /** Send STOP command
be_bryan 0:b74591d5ab33 97 *
be_bryan 0:b74591d5ab33 98 * @param obj The I2C object
be_bryan 0:b74591d5ab33 99 */
be_bryan 0:b74591d5ab33 100 int i2c_stop(i2c_t *obj);
be_bryan 0:b74591d5ab33 101
be_bryan 0:b74591d5ab33 102 /** Blocking reading data
be_bryan 0:b74591d5ab33 103 *
be_bryan 0:b74591d5ab33 104 * @param obj The I2C object
be_bryan 0:b74591d5ab33 105 * @param address 7-bit address (last bit is 1)
be_bryan 0:b74591d5ab33 106 * @param data The buffer for receiving
be_bryan 0:b74591d5ab33 107 * @param length Number of bytes to read
be_bryan 0:b74591d5ab33 108 * @param stop Stop to be generated after the transfer is done
be_bryan 0:b74591d5ab33 109 * @return Number of read bytes
be_bryan 0:b74591d5ab33 110 */
be_bryan 0:b74591d5ab33 111 int i2c_read(i2c_t *obj, int address, char *data, int length, int stop);
be_bryan 0:b74591d5ab33 112
be_bryan 0:b74591d5ab33 113 /** Blocking sending data
be_bryan 0:b74591d5ab33 114 *
be_bryan 0:b74591d5ab33 115 * @param obj The I2C object
be_bryan 0:b74591d5ab33 116 * @param address 7-bit address (last bit is 0)
be_bryan 0:b74591d5ab33 117 * @param data The buffer for sending
be_bryan 0:b74591d5ab33 118 * @param length Number of bytes to write
be_bryan 0:b74591d5ab33 119 * @param stop Stop to be generated after the transfer is done
be_bryan 0:b74591d5ab33 120 * @return
be_bryan 0:b74591d5ab33 121 * zero or non-zero - Number of written bytes
be_bryan 0:b74591d5ab33 122 * negative - I2C_ERROR_XXX status
be_bryan 0:b74591d5ab33 123 */
be_bryan 0:b74591d5ab33 124 int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop);
be_bryan 0:b74591d5ab33 125
be_bryan 0:b74591d5ab33 126 /** Reset I2C peripheral. TODO: The action here. Most of the implementation sends stop()
be_bryan 0:b74591d5ab33 127 *
be_bryan 0:b74591d5ab33 128 * @param obj The I2C object
be_bryan 0:b74591d5ab33 129 */
be_bryan 0:b74591d5ab33 130 void i2c_reset(i2c_t *obj);
be_bryan 0:b74591d5ab33 131
be_bryan 0:b74591d5ab33 132 /** Read one byte
be_bryan 0:b74591d5ab33 133 *
be_bryan 0:b74591d5ab33 134 * @param obj The I2C object
be_bryan 0:b74591d5ab33 135 * @param last Acknoledge
be_bryan 0:b74591d5ab33 136 * @return The read byte
be_bryan 0:b74591d5ab33 137 */
be_bryan 0:b74591d5ab33 138 int i2c_byte_read(i2c_t *obj, int last);
be_bryan 0:b74591d5ab33 139
be_bryan 0:b74591d5ab33 140 /** Write one byte
be_bryan 0:b74591d5ab33 141 *
be_bryan 0:b74591d5ab33 142 * @param obj The I2C object
be_bryan 0:b74591d5ab33 143 * @param data Byte to be written
be_bryan 0:b74591d5ab33 144 * @return 0 if NAK was received, 1 if ACK was received, 2 for timeout.
be_bryan 0:b74591d5ab33 145 */
be_bryan 0:b74591d5ab33 146 int i2c_byte_write(i2c_t *obj, int data);
be_bryan 0:b74591d5ab33 147
be_bryan 0:b74591d5ab33 148 /**@}*/
be_bryan 0:b74591d5ab33 149
be_bryan 0:b74591d5ab33 150 #if DEVICE_I2CSLAVE
be_bryan 0:b74591d5ab33 151
be_bryan 0:b74591d5ab33 152 /**
be_bryan 0:b74591d5ab33 153 * \defgroup SynchI2C Synchronous I2C Hardware Abstraction Layer for slave
be_bryan 0:b74591d5ab33 154 * @{
be_bryan 0:b74591d5ab33 155 */
be_bryan 0:b74591d5ab33 156
be_bryan 0:b74591d5ab33 157 /** Configure I2C as slave or master.
be_bryan 0:b74591d5ab33 158 * @param obj The I2C object
be_bryan 0:b74591d5ab33 159 * @param enable_slave Enable i2c hardware so you can receive events with ::i2c_slave_receive
be_bryan 0:b74591d5ab33 160 * @return non-zero if a value is available
be_bryan 0:b74591d5ab33 161 */
be_bryan 0:b74591d5ab33 162 void i2c_slave_mode(i2c_t *obj, int enable_slave);
be_bryan 0:b74591d5ab33 163
be_bryan 0:b74591d5ab33 164 /** Check to see if the I2C slave has been addressed.
be_bryan 0:b74591d5ab33 165 * @param obj The I2C object
be_bryan 0:b74591d5ab33 166 * @return The status - 1 - read addresses, 2 - write to all slaves,
be_bryan 0:b74591d5ab33 167 * 3 write addressed, 0 - the slave has not been addressed
be_bryan 0:b74591d5ab33 168 */
be_bryan 0:b74591d5ab33 169 int i2c_slave_receive(i2c_t *obj);
be_bryan 0:b74591d5ab33 170
be_bryan 0:b74591d5ab33 171 /** Configure I2C as slave or master.
be_bryan 0:b74591d5ab33 172 * @param obj The I2C object
be_bryan 0:b74591d5ab33 173 * @param data The buffer for receiving
be_bryan 0:b74591d5ab33 174 * @param length Number of bytes to read
be_bryan 0:b74591d5ab33 175 * @return non-zero if a value is available
be_bryan 0:b74591d5ab33 176 */
be_bryan 0:b74591d5ab33 177 int i2c_slave_read(i2c_t *obj, char *data, int length);
be_bryan 0:b74591d5ab33 178
be_bryan 0:b74591d5ab33 179 /** Configure I2C as slave or master.
be_bryan 0:b74591d5ab33 180 * @param obj The I2C object
be_bryan 0:b74591d5ab33 181 * @param data The buffer for sending
be_bryan 0:b74591d5ab33 182 * @param length Number of bytes to write
be_bryan 0:b74591d5ab33 183 * @return non-zero if a value is available
be_bryan 0:b74591d5ab33 184 */
be_bryan 0:b74591d5ab33 185 int i2c_slave_write(i2c_t *obj, const char *data, int length);
be_bryan 0:b74591d5ab33 186
be_bryan 0:b74591d5ab33 187 /** Configure I2C address.
be_bryan 0:b74591d5ab33 188 * @param obj The I2C object
be_bryan 0:b74591d5ab33 189 * @param idx Currently not used
be_bryan 0:b74591d5ab33 190 * @param address The address to be set
be_bryan 0:b74591d5ab33 191 * @param mask Currently not used
be_bryan 0:b74591d5ab33 192 */
be_bryan 0:b74591d5ab33 193 void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask);
be_bryan 0:b74591d5ab33 194
be_bryan 0:b74591d5ab33 195 #endif
be_bryan 0:b74591d5ab33 196
be_bryan 0:b74591d5ab33 197 /**@}*/
be_bryan 0:b74591d5ab33 198
be_bryan 0:b74591d5ab33 199 #if DEVICE_I2C_ASYNCH
be_bryan 0:b74591d5ab33 200
be_bryan 0:b74591d5ab33 201 /**
be_bryan 0:b74591d5ab33 202 * \defgroup hal_AsynchI2C Asynchronous I2C Hardware Abstraction Layer
be_bryan 0:b74591d5ab33 203 * @{
be_bryan 0:b74591d5ab33 204 */
be_bryan 0:b74591d5ab33 205
be_bryan 0:b74591d5ab33 206 /** Start I2C asynchronous transfer
be_bryan 0:b74591d5ab33 207 *
be_bryan 0:b74591d5ab33 208 * @param obj The I2C object
be_bryan 0:b74591d5ab33 209 * @param tx The transmit buffer
be_bryan 0:b74591d5ab33 210 * @param tx_length The number of bytes to transmit
be_bryan 0:b74591d5ab33 211 * @param rx The receive buffer
be_bryan 0:b74591d5ab33 212 * @param rx_length The number of bytes to receive
be_bryan 0:b74591d5ab33 213 * @param address The address to be set - 7bit or 9bit
be_bryan 0:b74591d5ab33 214 * @param stop If true, stop will be generated after the transfer is done
be_bryan 0:b74591d5ab33 215 * @param handler The I2C IRQ handler to be set
be_bryan 0:b74591d5ab33 216 * @param event Event mask for the transfer. See \ref hal_I2CEvents
be_bryan 0:b74591d5ab33 217 * @param hint DMA hint usage
be_bryan 0:b74591d5ab33 218 */
be_bryan 0:b74591d5ab33 219 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);
be_bryan 0:b74591d5ab33 220
be_bryan 0:b74591d5ab33 221 /** The asynchronous IRQ handler
be_bryan 0:b74591d5ab33 222 *
be_bryan 0:b74591d5ab33 223 * @param obj The I2C object which holds the transfer information
be_bryan 0:b74591d5ab33 224 * @return Event flags if a transfer termination condition was met, otherwise return 0.
be_bryan 0:b74591d5ab33 225 */
be_bryan 0:b74591d5ab33 226 uint32_t i2c_irq_handler_asynch(i2c_t *obj);
be_bryan 0:b74591d5ab33 227
be_bryan 0:b74591d5ab33 228 /** Attempts to determine if the I2C peripheral is already in use
be_bryan 0:b74591d5ab33 229 *
be_bryan 0:b74591d5ab33 230 * @param obj The I2C object
be_bryan 0:b74591d5ab33 231 * @return Non-zero if the I2C module is active or zero if it is not
be_bryan 0:b74591d5ab33 232 */
be_bryan 0:b74591d5ab33 233 uint8_t i2c_active(i2c_t *obj);
be_bryan 0:b74591d5ab33 234
be_bryan 0:b74591d5ab33 235 /** Abort asynchronous transfer
be_bryan 0:b74591d5ab33 236 *
be_bryan 0:b74591d5ab33 237 * This function does not perform any check - that should happen in upper layers.
be_bryan 0:b74591d5ab33 238 * @param obj The I2C object
be_bryan 0:b74591d5ab33 239 */
be_bryan 0:b74591d5ab33 240 void i2c_abort_asynch(i2c_t *obj);
be_bryan 0:b74591d5ab33 241
be_bryan 0:b74591d5ab33 242 #endif
be_bryan 0:b74591d5ab33 243
be_bryan 0:b74591d5ab33 244 /**@}*/
be_bryan 0:b74591d5ab33 245
be_bryan 0:b74591d5ab33 246 #ifdef __cplusplus
be_bryan 0:b74591d5ab33 247 }
be_bryan 0:b74591d5ab33 248 #endif
be_bryan 0:b74591d5ab33 249
be_bryan 0:b74591d5ab33 250 #endif
be_bryan 0:b74591d5ab33 251
be_bryan 0:b74591d5ab33 252 #endif
be_bryan 0:b74591d5ab33 253
be_bryan 0:b74591d5ab33 254 /** @}*/