AM261x MCU+ SDK: i2c.h Source File

| AM261x MCU+ SDK 26.00.00 |

i2c.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2021-2024 Texas Instruments Incorporated
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the
14 * distribution.
15 *
16 * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
102 #ifndef I2C_H_
103 #define I2C_H_
104
105 /* ========================================================================== */
106 /* Include Files */
107 /* ========================================================================== */
108
109 #ifdef __cplusplus
110 extern "C" {
111 #endif
112
113 #include <stdint.h>
114 #include <stdbool.h>
115 #include <stddef.h>
116 #include <stdlib.h>
117 #include <kernel/dpl/SemaphoreP.h>
118 #include <kernel/dpl/HwiP.h>
119 #include <drivers/i2c/v1/lld/i2c_lld.h>
120
121 /* ========================================================================== */
122 /* Macros & Typedefs */
123 /* ========================================================================== */
124
136 #define I2C_MODE_BLOCKING ((uint8_t) 0U)
137 #define I2C_MODE_CALLBACK ((uint8_t) 1U)
138
150 #define I2C_MEM_TXN_DIR_INVALID ((uint8_t) 0U)
151
152 #define I2C_MEM_TXN_DIR_TX ((uint8_t) 1U)
153
154 #define I2C_MEM_TXN_DIR_RX ((uint8_t) 2U)
155
158 /* ========================================================================== */
159 /* Structure Declarations */
160 /* ========================================================================== */
161
165 typedef struct I2C_Config_s *I2C_Handle;
166
170 typedef struct I2C_HwAttrs_s {
172 uint32_t baseAddr;
174 uint32_t intNum;
176 uint16_t eventId;
178 uint32_t funcClk;
180 bool enableIntr;
182 uint32_t ownTargetAddr;
183 } I2C_HwAttrs;
184
185
193 typedef struct {
194
195 uint32_t memAddr;
197 uint8_t memAddrSize;
199 uint8_t *buffer;
201 uint32_t size;
203 uint8_t memDataDir;
205 } I2C_Mem_Transaction;
206
229 typedef struct I2C_Transaction_s {
230
233 const void *writeBuf;
236 size_t writeCount;
239 void *readBuf;
242 size_t readCount;
247 uint32_t targetAddress;
249 void *nextPtr;
251 void *arg;
253 uint32_t timeout;
255 bool controllerMode;
258 bool expandSA;
261 bool memTxnEnable;
263 I2C_Mem_Transaction *memTransaction;
265 int32_t status;
266
267 } I2C_Transaction;
268
288 typedef struct I2C_Params_s {
290 uint8_t transferMode;
292 void (*transferCallbackFxn)(I2C_Handle i2cHnd, I2C_Transaction * msg,
293 int32_t transferStatus);
295 uint8_t bitRate;
296 } I2C_Params;
297
303 typedef struct I2C_Object_s {
304
306 SemaphoreP_Object mutex;
308 SemaphoreP_Object transferComplete;
310 HwiP_Object hwiObj;
312 I2C_Params i2cParams;
314 uint8_t state;
317 I2C_Transaction *currentTransaction;
318 /* I2C transaction pointers for I2C_MODE_CALLBACK */
319 /* Head ptr for queued transactions */
320 I2C_Transaction *headPtr;
321 /* Tail ptr for queued transactions */
322 I2C_Transaction *tailPtr;
323 /* flag to indicate module is open */
324 bool isOpen;
325 /* interrupt status error */
326 uint32_t intStatusErr;
327 /* I2C driver object for lld */
328 I2CLLD_Object i2cLldObject;
329 I2CLLD_Handle i2cLldHandle;
330
331 } I2C_Object;
332
343 typedef struct I2C_Config_s {
345 I2C_Object *object;
347 I2C_HwAttrs const *hwAttrs;
348 } I2C_Config;
349
366 typedef void (*I2C_CallbackFxn) (I2C_Handle handle, I2C_Transaction * msg,
367 int32_t transferStatus);
368
369 /* ========================================================================== */
370 /* Function Declarations */
371 /* ========================================================================== */
372
376 void I2C_init(void);
377
381 void I2C_deinit(void);
382
388 void I2C_Params_init(I2C_Params *params);
389
398 I2C_Handle I2C_open(uint32_t idx, const I2C_Params *params);
399
409 void I2C_close(I2C_Handle handle);
410
417 void I2C_Memory_Transaction_init(I2C_Mem_Transaction *memTransaction);
418
424 void I2C_Transaction_init(I2C_Transaction *transaction);
425
435 int32_t I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction);
436
446 int32_t I2C_memory_transfer(I2C_Handle handle,
447 I2C_Mem_Transaction *transaction);
448
457 int32_t I2C_probe(I2C_Handle handle, uint32_t targetAddr);
458
467 int32_t I2C_setBusFrequency(I2C_Handle handle, uint32_t busFrequency);
468
480 I2C_Handle I2C_getHandle(uint32_t index);
481
482 #ifdef __cplusplus
483 }
484 #endif
485
486 #endif /* I2C_H_ */
487
I2C_Params_init
void I2C_Params_init(I2C_Params *params)
API to set default values of I2C_Params in params.
I2C_Transaction::arg
void * arg
Definition: i2c.h:251
I2C_Mem_Transaction::memAddrSize
uint8_t memAddrSize
Definition: i2c.h:197
I2C_Mem_Transaction::buffer
uint8_t * buffer
Definition: i2c.h:199
I2C_Memory_Transaction_init
void I2C_Memory_Transaction_init(I2C_Mem_Transaction *memTransaction)
API to set default values of I2C_Mem_Transaction in memTransaction.
I2C_HwAttrs::ownTargetAddr
uint32_t ownTargetAddr
Definition: i2c.h:182
I2C_Object
I2C Object.
Definition: i2c.h:303
I2C_Transaction::status
int32_t status
Definition: i2c.h:265
I2C_HwAttrs
I2C Hardware attributes.
Definition: i2c.h:170
I2C_Object::tailPtr
I2C_Transaction * tailPtr
Definition: i2c.h:322
i2c_lld.h
I2C LLD Driver API/interface file.
I2C_probe
int32_t I2C_probe(I2C_Handle handle, uint32_t targetAddr)
API to probe I2C Device.
I2C_Transaction::nextPtr
void * nextPtr
Definition: i2c.h:249
I2C_Object::transferComplete
SemaphoreP_Object transferComplete
Definition: i2c.h:308
I2C_Config
I2C Global configuration.
Definition: i2c.h:343
I2C_Object::isOpen
bool isOpen
Definition: i2c.h:324
I2C_Object::i2cLldObject
I2CLLD_Object i2cLldObject
Definition: i2c.h:328
I2C_memory_transfer
int32_t I2C_memory_transfer(I2C_Handle handle, I2C_Mem_Transaction *transaction)
API to initiate a memory transfer from I2C Instance.
I2C_Transaction::writeBuf
const void * writeBuf
Definition: i2c.h:233
I2C_HwAttrs::eventId
uint16_t eventId
Definition: i2c.h:176
SemaphoreP.h
I2C_Object::i2cLldHandle
I2CLLD_Handle i2cLldHandle
Definition: i2c.h:329
I2C_Object::headPtr
I2C_Transaction * headPtr
Definition: i2c.h:320
I2C_Config::hwAttrs
I2C_HwAttrs const * hwAttrs
Definition: i2c.h:347
I2C_Handle
struct I2C_Config_s * I2C_Handle
A handle that is returned from a I2C_open() call.
Definition: i2c.h:165
I2C_Mem_Transaction::memAddr
uint32_t memAddr
Definition: i2c.h:195
I2C_HwAttrs::enableIntr
bool enableIntr
Definition: i2c.h:180
I2C_transfer
int32_t I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction)
API to initiate a transfer from I2C Instance.
I2C_Transaction::targetAddress
uint32_t targetAddress
Definition: i2c.h:247
I2C_Object::intStatusErr
uint32_t intStatusErr
Definition: i2c.h:326
I2C_Transaction::memTransaction
I2C_Mem_Transaction * memTransaction
Definition: i2c.h:263
I2C_Transaction
I2C Transaction.
Definition: i2c.h:229
I2C_Params
I2C Parameters.
Definition: i2c.h:288
I2C_open
I2C_Handle I2C_open(uint32_t idx, const I2C_Params *params)
API to Open I2C at index idx with parameters params.
I2C_Mem_Transaction::size
uint32_t size
Definition: i2c.h:201
I2C_Object::mutex
SemaphoreP_Object mutex
Definition: i2c.h:306
I2C_Mem_Transaction::memDataDir
uint8_t memDataDir
Definition: i2c.h:203
I2C_Transaction::timeout
uint32_t timeout
Definition: i2c.h:253
I2C_Transaction::expandSA
bool expandSA
Definition: i2c.h:258
HwiP.h
I2C_Object::i2cParams
I2C_Params i2cParams
Definition: i2c.h:312
I2C_Config::object
I2C_Object * object
Definition: i2c.h:345
I2C_HwAttrs::intNum
uint32_t intNum
Definition: i2c.h:174
I2C_Transaction_init
void I2C_Transaction_init(I2C_Transaction *transaction)
API to set default values of I2C_Transaction in transaction.
I2C_Transaction::controllerMode
bool controllerMode
Definition: i2c.h:255
I2C_setBusFrequency
int32_t I2C_setBusFrequency(I2C_Handle handle, uint32_t busFrequency)
API to set the bus frequency of I2C Instance.
I2C_Transaction::readBuf
void * readBuf
Definition: i2c.h:239
I2C_deinit
void I2C_deinit(void)
De-nitialize the I2C module.
HwiP_Object
Opaque Hwi object used with the Hwi APIs.
Definition: HwiP.h:142
I2C_Transaction::writeCount
size_t writeCount
Definition: i2c.h:236
I2C_CallbackFxn
void(* I2C_CallbackFxn)(I2C_Handle handle, I2C_Transaction *msg, int32_t transferStatus)
I2C Callback Function.
Definition: i2c.h:366
I2C_Mem_Transaction
I2C Memory Transaction.
Definition: i2c.h:193
I2C_HwAttrs::baseAddr
uint32_t baseAddr
Definition: i2c.h:172
I2C_HwAttrs::funcClk
uint32_t funcClk
Definition: i2c.h:178
I2C_Transaction::memTxnEnable
bool memTxnEnable
Definition: i2c.h:261
I2C_Transaction::readCount
size_t readCount
Definition: i2c.h:242
I2CLLD_Object
I2C Driver Object.
Definition: i2c_lld.h:461
I2C_close
void I2C_close(I2C_Handle handle)
API to close the I2C instance specified by the handle passed.
I2C_Object::state
uint8_t state
Definition: i2c.h:314
I2C_Params::bitRate
uint8_t bitRate
Definition: i2c.h:295
I2C_Object::currentTransaction
I2C_Transaction * currentTransaction
Definition: i2c.h:317
I2C_Params::transferMode
uint8_t transferMode
Definition: i2c.h:290
I2C_init
void I2C_init(void)
Initialize the I2C module.
I2C_Object::hwiObj
HwiP_Object hwiObj
Definition: i2c.h:310
I2C_getHandle
I2C_Handle I2C_getHandle(uint32_t index)
API to get the handle of an open I2C instance from the instance index.