Simon Cooksey / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

hal/i2c_api.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

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