Lancaster University / mbed-src

Lancaster University's (short term!) clone of mbed-src for micro:bit. This is a copy of the github branch https://github.com/lancaster-university/mbed-classic

Fork of mbed-src by mbed official

hal/i2c_api.h@525:c320967f86b9, 2015-04-28 (annotated)

Committer:
mbed_official
Date:
Tue Apr 28 11:45:12 2015 +0100
Revision:
525:c320967f86b9
Parent:
470:07f8455214b5
Child:
563:536c9fb088a0
Synchronized with git revision 299385b8331142b9dc524da7a986536f60b14553



Full URL: https://github.com/mbedmicro/mbed/commit/299385b8331142b9dc524da7a986536f60b14553/



Add in Silicon Labs targets with asynchronous API support

Who changed what in which revision?

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