Kenji Arai / mbed-os_TYBLE16

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.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

hal/i2c_api.h@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
Child:
1:9db0e321a9f4
mbed-os5 only for TYBLE16

Who changed what in which revision?

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