1 /** 2 * \file 3 * 4 * \brief Sync I2C Hardware Abstraction Layer(HAL) declaration. 5 * 6 * Copyright (c) 2014-2018 Microchip Technology Inc. and its subsidiaries. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Subject to your compliance with these terms, you may use Microchip 13 * software and any derivatives exclusively with Microchip products. 14 * It is your responsibility to comply with third party license terms applicable 15 * to your use of third party software (including open source software) that 16 * may accompany Microchip software. 17 * 18 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, 19 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, 20 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, 21 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE 22 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL 23 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE 24 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE 25 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT 26 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY 27 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, 28 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. 29 * 30 * \asf_license_stop 31 * 32 */ 33 34 #ifndef _HAL_I2C_M_SYNC_H_INCLUDED 35 #define _HAL_I2C_M_SYNC_H_INCLUDED 36 37 #include <hpl_i2c_m_sync.h> 38 #include <hal_io.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * \addtogroup doc_driver_hal_i2c_master_sync 46 * 47 * @{ 48 */ 49 50 #define I2C_M_MAX_RETRY 1 51 52 /** 53 * \brief I2C descriptor structure, embed i2c_device & i2c_interface 54 */ 55 struct i2c_m_sync_desc { 56 struct _i2c_m_sync_device device; 57 struct io_descriptor io; 58 uint16_t slave_addr; 59 }; 60 61 /** 62 * \brief Initialize synchronous I2C interface 63 * 64 * This function initializes the given I/O descriptor to be used as a 65 * synchronous I2C interface descriptor. 66 * It checks if the given hardware is not initialized and if the given hardware 67 * is permitted to be initialized. 68 * 69 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 70 * \param[in] hw The pointer to hardware instance 71 * 72 * \return Initialization status. 73 * \retval -1 The passed parameters were invalid or the interface is already initialized 74 * \retval 0 The initialization is completed successfully 75 */ 76 int32_t i2c_m_sync_init(struct i2c_m_sync_desc *i2c, void *hw); 77 78 /** 79 * \brief Deinitialize I2C interface 80 * 81 * This function deinitializes the given I/O descriptor. 82 * It checks if the given hardware is initialized and if the given hardware is permitted to be deinitialized. 83 * 84 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 85 * 86 * \return Uninitialization status. 87 * \retval -1 The passed parameters were invalid or the interface is already deinitialized 88 * \retval 0 The de-initialization is completed successfully 89 */ 90 int32_t i2c_m_sync_deinit(struct i2c_m_sync_desc *i2c); 91 92 /** 93 * \brief Set the slave device address 94 * 95 * This function sets the next transfer target slave I2C device address. 96 * It takes no effect to any already started access. 97 * 98 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 99 * \param[in] addr The slave address to access 100 * \param[in] addr_len The slave address length, can be I2C_M_TEN or I2C_M_SEVEN 101 * 102 * \return Masked slave address. The mask is a maximum 10-bit address, and 10th 103 * bit is set if a 10-bit address is used 104 */ 105 int32_t i2c_m_sync_set_slaveaddr(struct i2c_m_sync_desc *i2c, int16_t addr, int32_t addr_len); 106 107 /** 108 * \brief Set baudrate 109 * 110 * This function sets the I2C device to the specified baudrate. 111 * It only takes effect when the hardware is disabled. 112 * 113 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 114 * \param[in] clkrate Unused parameter. Should always be 0 115 * \param[in] baudrate The baudrate value set to master 116 * 117 * \return Whether successfully set the baudrate 118 * \retval -1 The passed parameters were invalid or the device is already enabled 119 * \retval 0 The baudrate set is completed successfully 120 */ 121 int32_t i2c_m_sync_set_baudrate(struct i2c_m_sync_desc *i2c, uint32_t clkrate, uint32_t baudrate); 122 123 /** 124 * \brief Sync version of enable hardware 125 * 126 * This function enables the I2C device, and then waits for this enabling operation to be done 127 * 128 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 129 * 130 * \return Whether successfully enable the device 131 * \retval -1 The passed parameters were invalid or the device enable failed 132 * \retval 0 The hardware enabling is completed successfully 133 */ 134 int32_t i2c_m_sync_enable(struct i2c_m_sync_desc *i2c); 135 136 /** 137 * \brief Sync version of disable hardware 138 * 139 * This function disables the I2C device and then waits for this disabling operation to be done 140 * 141 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 142 * 143 * \return Whether successfully disable the device 144 * \retval -1 The passed parameters were invalid or the device disable failed 145 * \retval 0 The hardware disabling is completed successfully 146 */ 147 int32_t i2c_m_sync_disable(struct i2c_m_sync_desc *i2c); 148 149 /** 150 * \brief Sync version of write command to I2C slave 151 * 152 * This function will write the value to a specified register in the I2C slave device and 153 * then wait for this operation to be done. 154 * 155 * The sequence of this routine is 156 * sta->address(write)->ack->reg address->ack->resta->address(write)->ack->reg value->nack->stt 157 * 158 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 159 * \param[in] reg The internal address/register of the I2C slave device 160 * \param[in] buffer The buffer holding data to write to the I2C slave device 161 * \param[in] length The length (in bytes) to write to the I2C slave device 162 * 163 * \return Whether successfully write to the device 164 * \retval <0 The passed parameters were invalid or write fail 165 * \retval 0 Writing to register is completed successfully 166 */ 167 int32_t i2c_m_sync_cmd_write(struct i2c_m_sync_desc *i2c, uint8_t reg, uint8_t *buffer, uint8_t length); 168 169 /** 170 * \brief Sync version of read register value from I2C slave 171 * 172 * This function will read a byte value from a specified register in the I2C slave device and 173 * then wait for this operation to be done. 174 * 175 * The sequence of this routine is 176 * sta->address(write)->ack->reg address->ack->resta->address(read)->ack->reg value->nack->stt 177 * 178 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 179 * \param[in] reg The internal address/register of the I2C slave device 180 * \param[in] buffer The buffer to hold the read data from the I2C slave device 181 * \param[in] length The length (in bytes) to read from the I2C slave device 182 * 183 * \return Whether successfully read from the device 184 * \retval <0 The passed parameters were invalid or read fail 185 * \retval 0 Reading from register is completed successfully 186 */ 187 int32_t i2c_m_sync_cmd_read(struct i2c_m_sync_desc *i2c, uint8_t reg, uint8_t *buffer, uint8_t length); 188 189 /** 190 * \brief Sync version of transfer message to/from the I2C slave 191 * 192 * This function will transfer a message between the I2C slave and the master. This function will wait for the operation 193 * to be done. 194 * 195 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 196 * \param[in] msg An i2c_m_msg struct 197 * 198 * \return The status of the operation 199 * \retval 0 Operation completed successfully 200 * \retval <0 Operation failed 201 */ 202 int32_t i2c_m_sync_transfer(struct i2c_m_sync_desc *const i2c, struct _i2c_m_msg *msg); 203 204 /** 205 * \brief Sync version of send stop condition on the i2c bus 206 * 207 * This function will create a stop condition on the i2c bus to release the bus 208 * 209 * \param[in] i2c An I2C descriptor, which is used to communicate through I2C 210 * 211 * \return The status of the operation 212 * \retval 0 Operation completed successfully 213 * \retval <0 Operation failed 214 */ 215 int32_t i2c_m_sync_send_stop(struct i2c_m_sync_desc *const i2c); 216 217 /** 218 * \brief Return I/O descriptor for this I2C instance 219 * 220 * This function will return a I/O instance for this I2C driver instance 221 * 222 * \param[in] i2c_m_sync_desc An I2C descriptor, which is used to communicate through I2C 223 * \param[in] io_descriptor A pointer to an I/O descriptor pointer type 224 * 225 * \return Error code 226 * \retval 0 No error detected 227 * \retval <0 Error code 228 */ 229 int32_t i2c_m_sync_get_io_descriptor(struct i2c_m_sync_desc *const i2c, struct io_descriptor **io); 230 231 /** 232 * \brief Retrieve the current driver version 233 * 234 * \return Current driver version. 235 */ 236 uint32_t i2c_m_sync_get_version(void); 237 238 /**@}*/ 239 240 #ifdef __cplusplus 241 } 242 #endif 243 244 #endif 245
