i2c_lld.h

Go to the documentation of this file.

/*
 * Copyright (C) 2024 Texas Instruments Incorporated
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *   Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 *   Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the
 *   distribution.
 *
 *   Neither the name of Texas Instruments Incorporated nor the names of
 *   its contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef I2C_LLD_H_
#define I2C_LLD_H_
 
/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
#include <stdbool.h>
#include <stdlib.h>
#include <stddef.h>
#include <drivers/i2c/v0/cslr_i2c.h>
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
#define I2C_MAX_NUM_OWN_TARGET_ADDR         (4U)
 
#define I2C_STS_SUCCESS                     ((int32_t) 0)
 
#define I2C_STS_ERR                         ((int32_t)-1)
 
#define I2C_STS_ERR_TIMEOUT                 ((int32_t)-2)
 
#define I2C_STS_ERR_INVALID_PARAM           ((int32_t)-3)
 
#define I2C_STS_ERR_BUS_BUSY                ((int32_t)-4)
 
#define I2C_STS_ERR_NO_ACK                  ((int32_t)-5)
 
#define I2C_STS_ERR_ARBITRATION_LOST        ((int32_t)-6)
 
#define I2C_STS_ERR_ACCESS_ERROR            ((int32_t)-7)
 
#define I2C_STS_RESTART                     ((int32_t)-8)
 
#define I2C_NO_WAIT                         ((uint32_t)0)
 
#define I2C_WAIT_FOREVER                    ((uint32_t)-1)
 
#define I2C_STATE_RESET                     ((uint8_t) 0U)
 
#define I2C_STATE_IDLE                      ((uint8_t) 1U)
 
#define I2C_STATE_BUSY                      ((uint8_t) 2U)
 
#define I2C_STATE_ERROR                     ((uint8_t) 3U)
 
#define I2C_100KHZ                          ((uint8_t) 0U)
 
#define I2C_400KHZ                          ((uint8_t) 1U)
 
#define I2C_1P0MHZ                          ((uint8_t) 2U)
 
#define I2C_3P4MHZ                          ((uint8_t) 3U)
 
#define I2C_MEM_ADDR_SIZE_8_BITS            ((uint8_t) 1U)
 
#define I2C_MEM_ADDR_SIZE_16_BITS           ((uint8_t) 2U)
 
#define I2C_WRITE_STATE                     ((uint8_t) 10U)
 
#define I2C_READ_STATE                      ((uint8_t) 11U)
 
#define I2C_TARGET_XFER_STATE               ((uint8_t) 12U)
 
#define I2C_TARGET_RESTART_STATE            ((uint8_t) 13U)
 
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
 
typedef struct {
 
    uint8_t                                 *writeBuf;
    uint32_t                                writeCount;
    uint8_t                                 *readBuf;
    uint32_t                                readCount;
 
} I2CLLD_Transaction;
 
typedef struct {
 
    I2CLLD_Transaction                      *txn;
    uint32_t                                txnCount;
    uint32_t                                targetAddress;
    void                                    *arg;
    uint32_t                                timeout;
    bool                                    controllerMode;
    bool                                    expandSA;
 
} I2CLLD_Message;
 
typedef struct {
 
    uint32_t                                deviceAddress;
    uint8_t                                 *buffer;
    uint32_t                                size;
    bool                                    expandSA;
} I2C_ExtendedParams;
 
typedef struct {
 
    I2C_ExtendedParams                      extendedParams;
    uint32_t                                memAddr;
    uint8_t                                 memAddrSize;
} I2C_Memory_ExtendedParams;
 
 
typedef struct {
 
    uint8_t                                 *writeBuf;
    uint32_t                                writeCount;
    uint8_t                                 *readBuf;
    uint32_t                                readCount;
    uint32_t                                timeout;
    bool                                    expandSA;
 
} I2CLLD_targetTransaction;
 
/* ========================================================================== */
/*                      Function pointers Declarations                        */
/* ========================================================================== */
 
typedef uint32_t (*I2C_Clock_getTicks) (void);
 
typedef uint32_t (*I2C_Clock_usecToTicks) (uint64_t usecs);
 
typedef void (*I2C_Clock_uSleep) (uint32_t usec);
 
typedef void (*I2C_lld_transferCompleteCallback) (void *args,
                                                  const I2CLLD_Message *msg,
                                                  int32_t transferStatus);
typedef void (*I2C_lld_targetTransferCompleteCallback) (void *args,
                                    const I2CLLD_targetTransaction * targetTxn,
                                    int32_t transferStatus);
 
/* ========================================================================== */
/*                         Structure Declarations                             */
/* ========================================================================== */
 
typedef struct {
 
    uint32_t                                baseAddr;
    uint32_t                                intrNum;
    uint8_t                                 bitRate;
    uint32_t                                funcClk;
    uint32_t                                ownTargetAddr[I2C_MAX_NUM_OWN_TARGET_ADDR];
    I2C_Clock_getTicks                      Clock_getTicks;
    I2C_Clock_usecToTicks                   Clock_usecToTicks;
    I2C_Clock_uSleep                        Clock_uSleep;
    I2C_lld_transferCompleteCallback        transferCompleteCallback;
    I2C_lld_targetTransferCompleteCallback  targetTransferCompleteCallback;
 
    uint8_t                                 state;
    uint32_t                                intStatusErr;
 
    I2CLLD_Message                          *currentMsg;
    I2CLLD_targetTransaction                *currentTargetTransaction;
    uint8_t                                 *writeBufIdx;
    uint32_t                                writeCountIdx;
    uint8_t                                 *readBufIdx;
    uint32_t                                readCountIdx;
    uint32_t                                startTicks;
    uint32_t                                currentTxnCount;
    I2CLLD_Message                          i2cMsg;
    I2CLLD_Transaction                      i2ctxn;
    uint8_t                                 *dataArray;
    uint8_t                                 addBuff[2];
    uint8_t                                 memAddrSize;
    bool                                    memTxnActive;
    I2CLLD_targetTransaction                i2cTargetTransaction;
    void*                                   args;
 
}I2CLLD_Object, *I2CLLD_Handle;
 
/* ========================================================================== */
/*                          Function Declarations                             */
/* ========================================================================== */
 
int32_t I2C_lld_init(I2CLLD_Handle handle);
 
int32_t I2C_lld_deInit(I2CLLD_Handle handle);
 
int32_t I2C_lld_Transaction_init(I2CLLD_Transaction *transaction);
 
int32_t I2C_lld_Message_init(I2CLLD_Message *msg);
 
int32_t I2C_lld_write(I2CLLD_Handle handle,
                      I2C_ExtendedParams *extendedParams,
                      uint32_t timeout);
 
int32_t I2C_lld_writeIntr(I2CLLD_Handle handle,
                          I2C_ExtendedParams *extendedParams);
 
int32_t I2C_lld_read(I2CLLD_Handle handle,
                     I2C_ExtendedParams *extendedParams,
                     uint32_t timeout);
 
int32_t I2C_lld_readIntr(I2CLLD_Handle handle,
                         I2C_ExtendedParams *extendedParams);
 
int32_t I2C_lld_mem_write(I2CLLD_Handle handle,
                          I2C_Memory_ExtendedParams *mem_extendedParams,
                          uint32_t timeout);
 
int32_t I2C_lld_mem_writeIntr(I2CLLD_Handle handle,
                              I2C_Memory_ExtendedParams *mem_extendedParams);
 
int32_t I2C_lld_mem_read(I2CLLD_Handle handle,
                         I2C_Memory_ExtendedParams *mem_extendedParams,
                         uint32_t timeout);
 
int32_t I2C_lld_mem_readIntr(I2CLLD_Handle handle,
                             I2C_Memory_ExtendedParams *mem_extendedParams);
 
int32_t I2C_lld_transferPoll(I2CLLD_Handle handle, I2CLLD_Message *msg);
 
int32_t I2C_lld_transferIntr(I2CLLD_Handle handle, I2CLLD_Message *msg);
 
int32_t I2C_lld_targetTransferIntr(I2CLLD_Handle handle,
                                   I2CLLD_targetTransaction *txn);
 
int32_t I2C_lld_probe(I2CLLD_Handle handle, uint32_t targetAddr);
 
int32_t I2C_lld_setBusFrequency(I2CLLD_Handle handle, uint32_t busFrequency);
 
int32_t     I2C_lld_recoverBus(I2CLLD_Handle handle, uint32_t i2cDelay);
 
/* ========================================================================== */
/*                        ISR Function Declarations                           */
/* ========================================================================== */
 
void I2C_lld_controllerIsr(void *args);
 
void I2C_lld_targetIsr(void *args);
 
#ifdef __cplusplus
}
#endif
 
#endif /* I2C_LLD_H_ */