Takaaki Numai / mbed-dev

inport from local

Dependents:   Hobbyking_Cheetah_0511

drivers/I2C.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 /* mbed Microcontroller Library
NYX 0:85b3fd62ea1a 2 * Copyright (c) 2006-2015 ARM Limited
NYX 0:85b3fd62ea1a 3 *
NYX 0:85b3fd62ea1a 4 * Licensed under the Apache License, Version 2.0 (the "License");
NYX 0:85b3fd62ea1a 5 * you may not use this file except in compliance with the License.
NYX 0:85b3fd62ea1a 6 * You may obtain a copy of the License at
NYX 0:85b3fd62ea1a 7 *
NYX 0:85b3fd62ea1a 8 * http://www.apache.org/licenses/LICENSE-2.0
NYX 0:85b3fd62ea1a 9 *
NYX 0:85b3fd62ea1a 10 * Unless required by applicable law or agreed to in writing, software
NYX 0:85b3fd62ea1a 11 * distributed under the License is distributed on an "AS IS" BASIS,
NYX 0:85b3fd62ea1a 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
NYX 0:85b3fd62ea1a 13 * See the License for the specific language governing permissions and
NYX 0:85b3fd62ea1a 14 * limitations under the License.
NYX 0:85b3fd62ea1a 15 */
NYX 0:85b3fd62ea1a 16 #ifndef MBED_I2C_H
NYX 0:85b3fd62ea1a 17 #define MBED_I2C_H
NYX 0:85b3fd62ea1a 18
NYX 0:85b3fd62ea1a 19 #include "platform/platform.h"
NYX 0:85b3fd62ea1a 20
NYX 0:85b3fd62ea1a 21 #if defined (DEVICE_I2C) || defined(DOXYGEN_ONLY)
NYX 0:85b3fd62ea1a 22
NYX 0:85b3fd62ea1a 23 #include "hal/i2c_api.h"
NYX 0:85b3fd62ea1a 24 #include "platform/SingletonPtr.h"
NYX 0:85b3fd62ea1a 25 #include "platform/PlatformMutex.h"
NYX 0:85b3fd62ea1a 26 #include "platform/NonCopyable.h"
NYX 0:85b3fd62ea1a 27
NYX 0:85b3fd62ea1a 28 #if DEVICE_I2C_ASYNCH
NYX 0:85b3fd62ea1a 29 #include "platform/CThunk.h"
NYX 0:85b3fd62ea1a 30 #include "hal/dma_api.h"
NYX 0:85b3fd62ea1a 31 #include "platform/FunctionPointer.h"
NYX 0:85b3fd62ea1a 32 #endif
NYX 0:85b3fd62ea1a 33
NYX 0:85b3fd62ea1a 34 namespace mbed {
NYX 0:85b3fd62ea1a 35 /** \addtogroup drivers */
NYX 0:85b3fd62ea1a 36
NYX 0:85b3fd62ea1a 37 /** An I2C Master, used for communicating with I2C slave devices
NYX 0:85b3fd62ea1a 38 *
NYX 0:85b3fd62ea1a 39 * @note Synchronization level: Thread safe
NYX 0:85b3fd62ea1a 40 *
NYX 0:85b3fd62ea1a 41 * Example:
NYX 0:85b3fd62ea1a 42 * @code
NYX 0:85b3fd62ea1a 43 * // Read from I2C slave at address 0x62
NYX 0:85b3fd62ea1a 44 *
NYX 0:85b3fd62ea1a 45 * #include "mbed.h"
NYX 0:85b3fd62ea1a 46 *
NYX 0:85b3fd62ea1a 47 * I2C i2c(p28, p27);
NYX 0:85b3fd62ea1a 48 *
NYX 0:85b3fd62ea1a 49 * int main() {
NYX 0:85b3fd62ea1a 50 * int address = 0x62;
NYX 0:85b3fd62ea1a 51 * char data[2];
NYX 0:85b3fd62ea1a 52 * i2c.read(address, data, 2);
NYX 0:85b3fd62ea1a 53 * }
NYX 0:85b3fd62ea1a 54 * @endcode
NYX 0:85b3fd62ea1a 55 * @ingroup drivers
NYX 0:85b3fd62ea1a 56 */
NYX 0:85b3fd62ea1a 57 class I2C : private NonCopyable<I2C> {
NYX 0:85b3fd62ea1a 58
NYX 0:85b3fd62ea1a 59 public:
NYX 0:85b3fd62ea1a 60 enum RxStatus {
NYX 0:85b3fd62ea1a 61 NoData,
NYX 0:85b3fd62ea1a 62 MasterGeneralCall,
NYX 0:85b3fd62ea1a 63 MasterWrite,
NYX 0:85b3fd62ea1a 64 MasterRead
NYX 0:85b3fd62ea1a 65 };
NYX 0:85b3fd62ea1a 66
NYX 0:85b3fd62ea1a 67 enum Acknowledge {
NYX 0:85b3fd62ea1a 68 NoACK = 0,
NYX 0:85b3fd62ea1a 69 ACK = 1
NYX 0:85b3fd62ea1a 70 };
NYX 0:85b3fd62ea1a 71
NYX 0:85b3fd62ea1a 72 /** Create an I2C Master interface, connected to the specified pins
NYX 0:85b3fd62ea1a 73 *
NYX 0:85b3fd62ea1a 74 * @param sda I2C data line pin
NYX 0:85b3fd62ea1a 75 * @param scl I2C clock line pin
NYX 0:85b3fd62ea1a 76 */
NYX 0:85b3fd62ea1a 77 I2C(PinName sda, PinName scl);
NYX 0:85b3fd62ea1a 78
NYX 0:85b3fd62ea1a 79 /** Set the frequency of the I2C interface
NYX 0:85b3fd62ea1a 80 *
NYX 0:85b3fd62ea1a 81 * @param hz The bus frequency in hertz
NYX 0:85b3fd62ea1a 82 */
NYX 0:85b3fd62ea1a 83 void frequency(int hz);
NYX 0:85b3fd62ea1a 84
NYX 0:85b3fd62ea1a 85 /** Read from an I2C slave
NYX 0:85b3fd62ea1a 86 *
NYX 0:85b3fd62ea1a 87 * Performs a complete read transaction. The bottom bit of
NYX 0:85b3fd62ea1a 88 * the address is forced to 1 to indicate a read.
NYX 0:85b3fd62ea1a 89 *
NYX 0:85b3fd62ea1a 90 * @param address 8-bit I2C slave address [ addr | 1 ]
NYX 0:85b3fd62ea1a 91 * @param data Pointer to the byte-array to read data in to
NYX 0:85b3fd62ea1a 92 * @param length Number of bytes to read
NYX 0:85b3fd62ea1a 93 * @param repeated Repeated start, true - don't send stop at end
NYX 0:85b3fd62ea1a 94 *
NYX 0:85b3fd62ea1a 95 * @returns
NYX 0:85b3fd62ea1a 96 * 0 on success (ack),
NYX 0:85b3fd62ea1a 97 * non-0 on failure (nack)
NYX 0:85b3fd62ea1a 98 */
NYX 0:85b3fd62ea1a 99 int read(int address, char *data, int length, bool repeated = false);
NYX 0:85b3fd62ea1a 100
NYX 0:85b3fd62ea1a 101 /** Read a single byte from the I2C bus
NYX 0:85b3fd62ea1a 102 *
NYX 0:85b3fd62ea1a 103 * @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
NYX 0:85b3fd62ea1a 104 *
NYX 0:85b3fd62ea1a 105 * @returns
NYX 0:85b3fd62ea1a 106 * the byte read
NYX 0:85b3fd62ea1a 107 */
NYX 0:85b3fd62ea1a 108 int read(int ack);
NYX 0:85b3fd62ea1a 109
NYX 0:85b3fd62ea1a 110 /** Write to an I2C slave
NYX 0:85b3fd62ea1a 111 *
NYX 0:85b3fd62ea1a 112 * Performs a complete write transaction. The bottom bit of
NYX 0:85b3fd62ea1a 113 * the address is forced to 0 to indicate a write.
NYX 0:85b3fd62ea1a 114 *
NYX 0:85b3fd62ea1a 115 * @param address 8-bit I2C slave address [ addr | 0 ]
NYX 0:85b3fd62ea1a 116 * @param data Pointer to the byte-array data to send
NYX 0:85b3fd62ea1a 117 * @param length Number of bytes to send
NYX 0:85b3fd62ea1a 118 * @param repeated Repeated start, true - do not send stop at end
NYX 0:85b3fd62ea1a 119 *
NYX 0:85b3fd62ea1a 120 * @returns
NYX 0:85b3fd62ea1a 121 * 0 on success (ack),
NYX 0:85b3fd62ea1a 122 * non-0 on failure (nack)
NYX 0:85b3fd62ea1a 123 */
NYX 0:85b3fd62ea1a 124 int write(int address, const char *data, int length, bool repeated = false);
NYX 0:85b3fd62ea1a 125
NYX 0:85b3fd62ea1a 126 /** Write single byte out on the I2C bus
NYX 0:85b3fd62ea1a 127 *
NYX 0:85b3fd62ea1a 128 * @param data data to write out on bus
NYX 0:85b3fd62ea1a 129 *
NYX 0:85b3fd62ea1a 130 * @returns
NYX 0:85b3fd62ea1a 131 * '0' - NAK was received
NYX 0:85b3fd62ea1a 132 * '1' - ACK was received,
NYX 0:85b3fd62ea1a 133 * '2' - timeout
NYX 0:85b3fd62ea1a 134 */
NYX 0:85b3fd62ea1a 135 int write(int data);
NYX 0:85b3fd62ea1a 136
NYX 0:85b3fd62ea1a 137 /** Creates a start condition on the I2C bus
NYX 0:85b3fd62ea1a 138 */
NYX 0:85b3fd62ea1a 139
NYX 0:85b3fd62ea1a 140 void start(void);
NYX 0:85b3fd62ea1a 141
NYX 0:85b3fd62ea1a 142 /** Creates a stop condition on the I2C bus
NYX 0:85b3fd62ea1a 143 */
NYX 0:85b3fd62ea1a 144 void stop(void);
NYX 0:85b3fd62ea1a 145
NYX 0:85b3fd62ea1a 146 /** Acquire exclusive access to this I2C bus
NYX 0:85b3fd62ea1a 147 */
NYX 0:85b3fd62ea1a 148 virtual void lock(void);
NYX 0:85b3fd62ea1a 149
NYX 0:85b3fd62ea1a 150 /** Release exclusive access to this I2C bus
NYX 0:85b3fd62ea1a 151 */
NYX 0:85b3fd62ea1a 152 virtual void unlock(void);
NYX 0:85b3fd62ea1a 153
NYX 0:85b3fd62ea1a 154 virtual ~I2C() {
NYX 0:85b3fd62ea1a 155 // Do nothing
NYX 0:85b3fd62ea1a 156 }
NYX 0:85b3fd62ea1a 157
NYX 0:85b3fd62ea1a 158 #if DEVICE_I2C_ASYNCH
NYX 0:85b3fd62ea1a 159
NYX 0:85b3fd62ea1a 160 /** Start non-blocking I2C transfer.
NYX 0:85b3fd62ea1a 161 *
NYX 0:85b3fd62ea1a 162 * This function locks the deep sleep until any event has occured
NYX 0:85b3fd62ea1a 163 *
NYX 0:85b3fd62ea1a 164 * @param address 8/10 bit I2c slave address
NYX 0:85b3fd62ea1a 165 * @param tx_buffer The TX buffer with data to be transfered
NYX 0:85b3fd62ea1a 166 * @param tx_length The length of TX buffer in bytes
NYX 0:85b3fd62ea1a 167 * @param rx_buffer The RX buffer which is used for received data
NYX 0:85b3fd62ea1a 168 * @param rx_length The length of RX buffer in bytes
NYX 0:85b3fd62ea1a 169 * @param event The logical OR of events to modify
NYX 0:85b3fd62ea1a 170 * @param callback The event callback function
NYX 0:85b3fd62ea1a 171 * @param repeated Repeated start, true - do not send stop at end
NYX 0:85b3fd62ea1a 172 * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
NYX 0:85b3fd62ea1a 173 */
NYX 0:85b3fd62ea1a 174 int transfer(int address, const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length, const event_callback_t& callback, int event = I2C_EVENT_TRANSFER_COMPLETE, bool repeated = false);
NYX 0:85b3fd62ea1a 175
NYX 0:85b3fd62ea1a 176 /** Abort the on-going I2C transfer
NYX 0:85b3fd62ea1a 177 */
NYX 0:85b3fd62ea1a 178 void abort_transfer();
NYX 0:85b3fd62ea1a 179 protected:
NYX 0:85b3fd62ea1a 180 void irq_handler_asynch(void);
NYX 0:85b3fd62ea1a 181 event_callback_t _callback;
NYX 0:85b3fd62ea1a 182 CThunk<I2C> _irq;
NYX 0:85b3fd62ea1a 183 DMAUsage _usage;
NYX 0:85b3fd62ea1a 184 #endif
NYX 0:85b3fd62ea1a 185
NYX 0:85b3fd62ea1a 186 protected:
NYX 0:85b3fd62ea1a 187 void aquire();
NYX 0:85b3fd62ea1a 188
NYX 0:85b3fd62ea1a 189 i2c_t _i2c;
NYX 0:85b3fd62ea1a 190 static I2C *_owner;
NYX 0:85b3fd62ea1a 191 int _hz;
NYX 0:85b3fd62ea1a 192 static SingletonPtr<PlatformMutex> _mutex;
NYX 0:85b3fd62ea1a 193 };
NYX 0:85b3fd62ea1a 194
NYX 0:85b3fd62ea1a 195 } // namespace mbed
NYX 0:85b3fd62ea1a 196
NYX 0:85b3fd62ea1a 197 #endif
NYX 0:85b3fd62ea1a 198
NYX 0:85b3fd62ea1a 199 #endif