Takaaki Numai / mbed-dev

inport from local

Dependents:   Hobbyking_Cheetah_0511

hal/i2c_api.h@0:85b3fd62ea1a, 2020-03-16 (annotated)

Committer:
NYX
Date:
Mon Mar 16 06:35:48 2020 +0000
Revision:
0:85b3fd62ea1a
reinport to mbed;

Who changed what in which revision?

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