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/v1/cslr_i2c.h>
#include <drivers/hw_include/hw_types.h>
#include <drivers/hw_include/cslr_i2c.h>
 
/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */
 
#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_RESTART                     ((int32_t)-7)
 
#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_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)
 
#define I2C_CFG_MASK_TX                      (CSL_I2C_ICMDR_TRX_MASK)
#define I2C_CFG_MASK_RX                      (CSL_I2C_ICMDR_TRX_MASK)
#define I2C_CFG_MASK_STOP                    (CSL_I2C_ICMDR_STP_MASK)
#define I2C_CFG_MASK_START                   (CSL_I2C_ICMDR_STT_MASK)
#define I2C_CFG_MASK_RUN_FREE                (CSL_I2C_ICMDR_FREE_MASK)
#define I2C_CFG_MASK_REPEAT_MODE             (CSL_I2C_ICMDR_RM_MASK)
#define I2C_CFG_MASK_LOOP_BACK               (CSL_I2C_ICMDR_DLB_MASK)
#define I2C_CFG_MASK_XA                      (CSL_I2C_ICMDR_XA_MASK)
 
#define I2C_CFG_CMD_TX                       (CSL_I2C_ICMDR_TRX_MASK)
#define I2C_CFG_CMD_RX                       (0U)
#define I2C_CFG_CMD_STOP                     (CSL_I2C_ICMDR_STP_MASK)
#define I2C_CFG_CMD_START                    (CSL_I2C_ICMDR_STT_MASK)
#define I2C_CFG_CMD_RUN_FREE_ON              (CSL_I2C_ICMDR_FREE_MASK)
#define I2C_CFG_CMD_RUN_FREE_OFF             (0U)
#define I2C_CFG_CMD_REPEAT_MODE_ON           (CSL_I2C_ICMDR_RM_MASK)
#define I2C_CFG_CMD_REPEAT_MODE_OFF          (0U)
#define I2C_CFG_CMD_LOOP_BACK_ON             (CSL_I2C_ICMDR_DLB_MASK)
#define I2C_CFG_CMD_LOOP_BACK_OFF            (0U)
#define I2C_CFG_CMD_10BIT_ADDRESS            (I2C_CFG_MASK_XA)
#define I2C_CFG_CMD_7BIT_ADDRESS             (0U)
 
#define I2C_INT_ARBITRATION_LOST            (CSL_I2C_ICSTR_AL_MASK)
#define I2C_INT_NO_ACK                      (CSL_I2C_ICSTR_NACK_MASK)
#define I2C_INT_ADRR_READY_ACESS            (CSL_I2C_ICSTR_ARDY_MASK)
#define I2C_INT_RECV_READY                  (CSL_I2C_ICSTR_ICRRDY_MASK)
#define I2C_INT_TRANSMIT_READY              (CSL_I2C_ICSTR_ICXRDY_MASK)
#define I2C_INT_STOP_CONDITION              (CSL_I2C_ICSTR_SCD_MASK)
#define I2C_INT_ADRR_ZERO                   (CSL_I2C_ICSTR_AD0_MASK)
#define I2C_INT_ADRR_TARGET                 (CSL_I2C_ICSTR_AAS_MASK)
#define I2C_INT_TRANSMIT_UNDER_FLOW         (CSL_I2C_ICSTR_XSMT_MASK)
#define I2C_INT_RECV_OVER_RUN               (CSL_I2C_ICSTR_RSFULL_MASK)
#define I2C_INT_BUS_BUSY                    (CSL_I2C_ICSTR_BB_MASK)
#define I2C_INT_NO_ACK_SENT                 (CSL_I2C_ICSTR_NACKSNT_MASK)
#define I2C_INT_TARGET_DIRECTION            (CSL_I2C_ICSTR_SDIR_MASK)
 
#define I2C_ALL_INTS                        (   I2C_INT_ARBITRATION_LOST        |   \
                                                I2C_INT_NO_ACK                  |   \
                                                I2C_INT_ADRR_READY_ACESS        |   \
                                                I2C_INT_RECV_READY              |   \
                                                I2C_INT_TRANSMIT_READY          |   \
                                                I2C_INT_STOP_CONDITION          |   \
                                                I2C_INT_ADRR_ZERO               |   \
                                                I2C_INT_ADRR_TARGET             |   \
                                                I2C_INT_TRANSMIT_UNDER_FLOW     |   \
                                                I2C_INT_RECV_OVER_RUN           |   \
                                                I2C_INT_BUS_BUSY                |   \
                                                I2C_INT_NO_ACK_SENT             |   \
                                                I2C_INT_TARGET_DIRECTION            \
                                            )
 
#define I2C_INT_MASK_ARBITRATION_LOST       (CSL_I2C_ICIMR_AL_MASK)
#define I2C_INT_MASK_NO_ACK                 (CSL_I2C_ICIMR_NACK_MASK)
#define I2C_INT_MASK_ADRR_READY_ACESS       (CSL_I2C_ICIMR_ARDY_MASK)
#define I2C_INT_MASK_RECV_READY             (CSL_I2C_ICIMR_ICRRDY_MASK)
#define I2C_INT_MASK_TRANSMIT_READY         (CSL_I2C_ICIMR_ICXRDY_MASK)
#define I2C_INT_MASK_STOP_CONDITION         (CSL_I2C_ICIMR_SCD_MASK)
#define I2C_INT_MASK_ADRR_TARGET            (CSL_I2C_ICIMR_AAS_MASK)
 
#define I2C_ALL_INTS_MASK                   (   I2C_INT_MASK_ARBITRATION_LOST   |   \
                                                I2C_INT_MASK_NO_ACK             |   \
                                                I2C_INT_MASK_ADRR_READY_ACESS   |   \
                                                I2C_INT_MASK_RECV_READY         |   \
                                                I2C_INT_MASK_TRANSMIT_READY     |   \
                                                I2C_INT_MASK_STOP_CONDITION     |   \
                                                I2C_INT_MASK_ADRR_TARGET            \
                                            )
 
/* ========================================================================== */
/*                         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_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_target_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_target_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_target_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_target_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);
 
/* ========================================================================== */
/*                        ISR Function Declarations                           */
/* ========================================================================== */
 
void I2C_lld_controllerIsr(void *args);
 
void I2C_lld_targetIsr(void *args);
 
/* ========================================================================== */
/*                   Low-level hardware function declarations                 */
/* ========================================================================== */
 
void I2CControllerControl(uint32_t baseAddr, uint32_t ctrlMask, uint32_t ctrlCmds);
void I2CSetDataCount(uint32_t baseAddr, uint32_t count);
void I2CControllerStart(uint32_t baseAddr);
void I2CControllerIntEnableEx(uint32_t baseAddr, uint32_t intFlag);
void I2CControllerTargetAddrSet(uint32_t baseAddr, uint32_t targetAddr);
void I2CControllerIntClearEx(uint32_t baseAddr, uint32_t intFlag);
void I2CModeControl(uint32_t baseAddr, uint32_t ctrlMask, uint32_t ctrlCmds);
void I2CTargetEnable(uint32_t baseAddr);
 
#ifdef __cplusplus
}
#endif
 
#endif /* I2C_LLD_H_ */