Nicolas Borla / Mbed OS ROME2_Robot_Firmware

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.

mbed-os/hal/i2c_api.h@0:4beb2ea291ec, 2020-03-16 (annotated)

Committer:
boro
Date:
Mon Mar 16 13:12:31 2020 +0000
Revision:
0:4beb2ea291ec
a

Who changed what in which revision?

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