Elijah Stanger-Jones / mbed-dev

Lightweight Mbed Library for STM F4 and F7

hal/i2c_api.h@2:0edeaf13dfb2, 2021-02-04 (annotated)

Committer:
elijahsj
Date:
Thu Feb 04 20:44:34 2021 +0000
Revision:
2:0edeaf13dfb2
Parent:
0:083111ae2a11 
modfiied for spine board;

Who changed what in which revision?

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