i2c_11xx.h

00001 /*
00002  * @brief LPC11xx I2C driver
00003  *
00004  * @note
00005  * Copyright(C) NXP Semiconductors, 2012
00006  * All rights reserved.
00007  *
00008  * @par
00009  * Software that is described herein is for illustrative purposes only
00010  * which provides customers with programming information regarding the
00011  * LPC products.  This software is supplied "AS IS" without any warranties of
00012  * any kind, and NXP Semiconductors and its licensor disclaim any and
00013  * all warranties, express or implied, including all implied warranties of
00014  * merchantability, fitness for a particular purpose and non-infringement of
00015  * intellectual property rights.  NXP Semiconductors assumes no responsibility
00016  * or liability for the use of the software, conveys no license or rights under any
00017  * patent, copyright, mask work right, or any other intellectual property rights in
00018  * or to any products. NXP Semiconductors reserves the right to make changes
00019  * in the software without notification. NXP Semiconductors also makes no
00020  * representation or warranty that such application will be suitable for the
00021  * specified use without further testing or modification.
00022  *
00023  * @par
00024  * Permission to use, copy, modify, and distribute this software and its
00025  * documentation is hereby granted, under NXP Semiconductors' and its
00026  * licensor's relevant copyrights in the software, without fee, provided that it
00027  * is used in conjunction with NXP Semiconductors microcontrollers.  This
00028  * copyright, permission, and disclaimer notice must appear in all copies of
00029  * this code.
00030  */
00031 
00032 #ifndef __I2C_11XX_H_
00033 #define __I2C_11XX_H_
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif
00038 
00039 /** @defgroup I2C_11XX CHIP: LPC11xx I2C driver
00040  * @ingroup CHIP_11XX_Drivers
00041  * @{
00042  */
00043 
00044 #if !defined(CHIP_LPC110X)
00045 
00046 /**
00047  * @brief I2C register block structure
00048  */
00049 typedef struct {                /* I2C0 Structure         */
00050     __IO uint32_t CONSET ;       /*!< I2C Control Set Register. When a one is written to a bit of this register, the corresponding bit in the I2C control register is set. Writing a zero has no effect on the corresponding bit in the I2C control register. */
00051     __I  uint32_t STAT ;         /*!< I2C Status Register. During I2C operation, this register provides detailed status codes that allow software to determine the next action needed. */
00052     __IO uint32_t DAT ;          /*!< I2C Data Register. During master or slave transmit mode, data to be transmitted is written to this register. During master or slave receive mode, data that has been received may be read from this register. */
00053     __IO uint32_t ADR0 ;         /*!< I2C Slave Address Register 0. Contains the 7-bit slave address for operation of the I2C interface in slave mode, and is not used in master mode. The least significant bit determines whether a slave responds to the General Call address. */
00054     __IO uint32_t SCLH ;         /*!< SCH Duty Cycle Register High Half Word. Determines the high time of the I2C clock. */
00055     __IO uint32_t SCLL ;         /*!< SCL Duty Cycle Register Low Half Word. Determines the low time of the I2C clock. SCLL and SCLH together determine the clock frequency generated by an I2C master and certain times used in slave mode. */
00056     __O  uint32_t CONCLR ;       /*!< I2C Control Clear Register. When a one is written to a bit of this register, the corresponding bit in the I2C control register is cleared. Writing a zero has no effect on the corresponding bit in the I2C control register. */
00057     __IO uint32_t MMCTRL ;       /*!< Monitor mode control register. */
00058     __IO uint32_t ADR1 ;         /*!< I2C Slave Address Register. Contains the 7-bit slave address for operation of the I2C interface in slave mode, and is not used in master mode. The least significant bit determines whether a slave responds to the General Call address. */
00059     __IO uint32_t ADR2 ;         /*!< I2C Slave Address Register. Contains the 7-bit slave address for operation of the I2C interface in slave mode, and is not used in master mode. The least significant bit determines whether a slave responds to the General Call address. */
00060     __IO uint32_t ADR3 ;         /*!< I2C Slave Address Register. Contains the 7-bit slave address for operation of the I2C interface in slave mode, and is not used in master mode. The least significant bit determines whether a slave responds to the General Call address. */
00061     __I  uint32_t DATA_BUFFER ;  /*!< Data buffer register. The contents of the 8 MSBs of the DAT shift register will be transferred to the DATA_BUFFER automatically after every nine bits (8 bits of data plus ACK or NACK) has been received on the bus. */
00062     __IO uint32_t MASK[4];      /*!< I2C Slave address mask register */
00063 } LPC_I2C_T;
00064 
00065 /**
00066  * @brief   Return values for SLAVE handler
00067  * @note
00068  * Chip drivers will usally be designed to match their events with this value
00069  */
00070 #define RET_SLAVE_TX    6   /**< Return value, when 1 byte TX'd successfully */
00071 #define RET_SLAVE_RX    5   /**< Return value, when 1 byte RX'd successfully */
00072 #define RET_SLAVE_IDLE  2   /**< Return value, when slave enter idle mode */
00073 #define RET_SLAVE_BUSY  0   /**< Return value, when slave is busy */
00074 
00075 /**
00076  * @brief I2C state handle return values
00077  */
00078 #define I2C_STA_STO_RECV            0x20
00079 
00080 /*
00081  * @brief I2C Control Set register description
00082  */
00083 #define I2C_I2CONSET_AA             ((0x04))/*!< Assert acknowledge flag */
00084 #define I2C_I2CONSET_SI             ((0x08))/*!< I2C interrupt flag */
00085 #define I2C_I2CONSET_STO            ((0x10))/*!< STOP flag */
00086 #define I2C_I2CONSET_STA            ((0x20))/*!< START flag */
00087 #define I2C_I2CONSET_I2EN           ((0x40))/*!< I2C interface enable */
00088 
00089 /*
00090  * @brief I2C Control Clear register description
00091  */
00092 #define I2C_I2CONCLR_AAC            ((1 << 2))  /*!< Assert acknowledge Clear bit */
00093 #define I2C_I2CONCLR_SIC            ((1 << 3))  /*!< I2C interrupt Clear bit */
00094 #define I2C_I2CONCLR_STOC           ((1 << 4))  /*!< I2C STOP Clear bit */
00095 #define I2C_I2CONCLR_STAC           ((1 << 5))  /*!< START flag Clear bit */
00096 #define I2C_I2CONCLR_I2ENC          ((1 << 6))  /*!< I2C interface Disable bit */
00097 
00098 /*
00099  * @brief   I2C Common Control register description
00100  */
00101 #define I2C_CON_AA            (1UL << 2)    /*!< Assert acknowledge bit */
00102 #define I2C_CON_SI            (1UL << 3)    /*!< I2C interrupt bit */
00103 #define I2C_CON_STO           (1UL << 4)    /*!< I2C STOP bit */
00104 #define I2C_CON_STA           (1UL << 5)    /*!< START flag bit */
00105 #define I2C_CON_I2EN          (1UL << 6)    /*!< I2C interface bit */
00106 
00107 /*
00108  * @brief I2C Status Code definition (I2C Status register)
00109  */
00110 #define I2C_STAT_CODE_BITMASK       ((0xF8))/*!< Return Code mask in I2C status register */
00111 #define I2C_STAT_CODE_ERROR         ((0xFF))/*!< Return Code error mask in I2C status register */
00112 
00113 /*
00114  * @brief I2C return status code definitions
00115  */
00116 #define I2C_I2STAT_NO_INF                       ((0xF8))/*!< No relevant information */
00117 #define I2C_I2STAT_BUS_ERROR                    ((0x00))/*!< Bus Error */
00118 
00119 /*
00120  * @brief I2C Master transmit mode
00121  */
00122 #define I2C_I2STAT_M_TX_START                   ((0x08))/*!< A start condition has been transmitted */
00123 #define I2C_I2STAT_M_TX_RESTART                 ((0x10))/*!< A repeat start condition has been transmitted */
00124 #define I2C_I2STAT_M_TX_SLAW_ACK                ((0x18))/*!< SLA+W has been transmitted, ACK has been received */
00125 #define I2C_I2STAT_M_TX_SLAW_NACK               ((0x20))/*!< SLA+W has been transmitted, NACK has been received */
00126 #define I2C_I2STAT_M_TX_DAT_ACK                 ((0x28))/*!< Data has been transmitted, ACK has been received */
00127 #define I2C_I2STAT_M_TX_DAT_NACK                ((0x30))/*!< Data has been transmitted, NACK has been received */
00128 #define I2C_I2STAT_M_TX_ARB_LOST                ((0x38))/*!< Arbitration lost in SLA+R/W or Data bytes */
00129 
00130 /*
00131  * @brief I2C Master receive mode
00132  */
00133 #define I2C_I2STAT_M_RX_START                   ((0x08))/*!< A start condition has been transmitted */
00134 #define I2C_I2STAT_M_RX_RESTART                 ((0x10))/*!< A repeat start condition has been transmitted */
00135 #define I2C_I2STAT_M_RX_ARB_LOST                ((0x38))/*!< Arbitration lost */
00136 #define I2C_I2STAT_M_RX_SLAR_ACK                ((0x40))/*!< SLA+R has been transmitted, ACK has been received */
00137 #define I2C_I2STAT_M_RX_SLAR_NACK               ((0x48))/*!< SLA+R has been transmitted, NACK has been received */
00138 #define I2C_I2STAT_M_RX_DAT_ACK                 ((0x50))/*!< Data has been received, ACK has been returned */
00139 #define I2C_I2STAT_M_RX_DAT_NACK                ((0x58))/*!< Data has been received, NACK has been returned */
00140 
00141 /*
00142  * @brief I2C Slave receive mode
00143  */
00144 #define I2C_I2STAT_S_RX_SLAW_ACK                ((0x60))/*!< Own slave address has been received, ACK has been returned */
00145 #define I2C_I2STAT_S_RX_ARB_LOST_M_SLA          ((0x68))/*!< Arbitration lost in SLA+R/W as master */
00146 // #define I2C_I2STAT_S_RX_SLAW_ACK             ((0x68)) /*!< Own SLA+W has been received, ACK returned */
00147 #define I2C_I2STAT_S_RX_GENCALL_ACK             ((0x70))/*!< General call address has been received, ACK has been returned */
00148 #define I2C_I2STAT_S_RX_ARB_LOST_M_GENCALL      ((0x78))/*!< Arbitration lost in SLA+R/W (GENERAL CALL) as master */
00149 // #define I2C_I2STAT_S_RX_GENCALL_ACK              ((0x78)) /*!< General call address has been received, ACK has been returned */
00150 #define I2C_I2STAT_S_RX_PRE_SLA_DAT_ACK         ((0x80))/*!< Previously addressed with own SLA; Data has been received, ACK has been returned */
00151 #define I2C_I2STAT_S_RX_PRE_SLA_DAT_NACK        ((0x88))/*!< Previously addressed with own SLA;Data has been received and NOT ACK has been returned */
00152 #define I2C_I2STAT_S_RX_PRE_GENCALL_DAT_ACK     ((0x90))/*!< Previously addressed with General Call; Data has been received and ACK has been returned */
00153 #define I2C_I2STAT_S_RX_PRE_GENCALL_DAT_NACK    ((0x98))/*!< Previously addressed with General Call; Data has been received and NOT ACK has been returned */
00154 #define I2C_I2STAT_S_RX_STA_STO_SLVREC_SLVTRX   ((0xA0))/*!< A STOP condition or repeated START condition has been received while still addressed as SLV/REC (Slave Receive) or
00155                                                            SLV/TRX (Slave Transmit) */
00156 
00157 /*
00158  * @brief I2C Slave transmit mode
00159  */
00160 #define I2C_I2STAT_S_TX_SLAR_ACK                ((0xA8))/*!< Own SLA+R has been received, ACK has been returned */
00161 #define I2C_I2STAT_S_TX_ARB_LOST_M_SLA          ((0xB0))/*!< Arbitration lost in SLA+R/W as master */
00162 // #define I2C_I2STAT_S_TX_SLAR_ACK             ((0xB0)) /*!< Own SLA+R has been received, ACK has been returned */
00163 #define I2C_I2STAT_S_TX_DAT_ACK                 ((0xB8))/*!< Data has been transmitted, ACK has been received */
00164 #define I2C_I2STAT_S_TX_DAT_NACK                ((0xC0))/*!< Data has been transmitted, NACK has been received */
00165 #define I2C_I2STAT_S_TX_LAST_DAT_ACK            ((0xC8))/*!< Last data byte in I2DAT has been transmitted (AA = 0); ACK has been received */
00166 #define I2C_SLAVE_TIME_OUT                      0x10000000UL/*!< Time out in case of using I2C slave mode */
00167 
00168 /*
00169  * @brief I2C Data register definition
00170  */
00171 #define I2C_I2DAT_BITMASK           ((0xFF))/*!< Mask for I2DAT register */
00172 #define I2C_I2DAT_IDLE_CHAR         (0xFF)  /*!< Idle data value will be send out in slave mode in case of the actual expecting data requested from the master is greater than
00173                                                  its sending data length that can be supported */
00174 
00175 /*
00176  * @brief I2C Monitor mode control register description
00177  */
00178 #define I2C_I2MMCTRL_MM_ENA         ((1 << 0))          /**< Monitor mode enable */
00179 #define I2C_I2MMCTRL_ENA_SCL        ((1 << 1))          /**< SCL output enable */
00180 #define I2C_I2MMCTRL_MATCH_ALL      ((1 << 2))          /**< Select interrupt register match */
00181 #define I2C_I2MMCTRL_BITMASK        ((0x07))        /**< Mask for I2MMCTRL register */
00182 
00183 /*
00184  * @brief I2C Data buffer register description
00185  */
00186 #define I2DATA_BUFFER_BITMASK       ((0xFF))/*!< I2C Data buffer register bit mask */
00187 
00188 /*
00189  * @brief I2C Slave Address registers definition
00190  */
00191 #define I2C_I2ADR_GC                ((1 << 0))  /*!< General Call enable bit */
00192 #define I2C_I2ADR_BITMASK           ((0xFF))/*!< I2C Slave Address registers bit mask */
00193 
00194 /*
00195  * @brief I2C Mask Register definition
00196  */
00197 #define I2C_I2MASK_MASK(n)          ((n & 0xFE))/*!< I2C Mask Register mask field */
00198 
00199 /*
00200  * @brief I2C SCL HIGH duty cycle Register definition
00201  */
00202 #define I2C_I2SCLH_BITMASK          ((0xFFFF))  /*!< I2C SCL HIGH duty cycle Register bit mask */
00203 
00204 /*
00205  * @brief I2C SCL LOW duty cycle Register definition
00206  */
00207 #define I2C_I2SCLL_BITMASK          ((0xFFFF))  /*!< I2C SCL LOW duty cycle Register bit mask */
00208 
00209 /*
00210  * @brief I2C status values
00211  */
00212 #define I2C_SETUP_STATUS_ARBF   (1 << 8)    /**< Arbitration false */
00213 #define I2C_SETUP_STATUS_NOACKF (1 << 9)    /**< No ACK returned */
00214 #define I2C_SETUP_STATUS_DONE   (1 << 10)   /**< Status DONE */
00215 
00216 /*
00217  * @brief I2C state handle return values
00218  */
00219 #define I2C_OK                      0x00
00220 #define I2C_BYTE_SENT               0x01
00221 #define I2C_BYTE_RECV               0x02
00222 #define I2C_LAST_BYTE_RECV          0x04
00223 #define I2C_SEND_END                0x08
00224 #define I2C_RECV_END                0x10
00225 #define I2C_STA_STO_RECV            0x20
00226 
00227 #define I2C_ERR                     (0x10000000)
00228 #define I2C_NAK_RECV                (0x10000000 | 0x01)
00229 
00230 #define I2C_CheckError(ErrorCode)   (ErrorCode & 0x10000000)
00231 
00232 /*
00233  * @brief I2C monitor control configuration defines
00234  */
00235 #define I2C_MONITOR_CFG_SCL_OUTPUT  I2C_I2MMCTRL_ENA_SCL        /**< SCL output enable */
00236 #define I2C_MONITOR_CFG_MATCHALL    I2C_I2MMCTRL_MATCH_ALL      /**< Select interrupt register match */
00237 
00238 /**
00239  * @brief   I2C Slave Identifiers
00240  */
00241 typedef enum {
00242     I2C_SLAVE_GENERAL,  /**< Slave ID for general calls */
00243     I2C_SLAVE_0,        /**< Slave ID fo Slave Address 0 */
00244     I2C_SLAVE_1,        /**< Slave ID fo Slave Address 1 */
00245     I2C_SLAVE_2,        /**< Slave ID fo Slave Address 2 */
00246     I2C_SLAVE_3,        /**< Slave ID fo Slave Address 3 */
00247     I2C_SLAVE_NUM_INTERFACE /**< Number of slave interfaces */
00248 } I2C_SLAVE_ID;
00249 
00250 /**
00251  * @brief   I2C transfer status
00252  */
00253 typedef enum {
00254     I2C_STATUS_DONE,    /**< Transfer done successfully */
00255     I2C_STATUS_NAK,     /**< NAK received during transfer */
00256     I2C_STATUS_ARBLOST, /**< Aribitration lost during transfer */
00257     I2C_STATUS_BUSERR,  /**< Bus error in I2C transfer */
00258     I2C_STATUS_BUSY,    /**< I2C is busy doing transfer */
00259 } I2C_STATUS_T;
00260 
00261 /**
00262  * @brief Master transfer data structure definitions
00263  */
00264 typedef struct {
00265     uint8_t slaveAddr;      /**< 7-bit I2C Slave address */
00266     const uint8_t *txBuff;  /**< Pointer to array of bytes to be transmitted */
00267     int     txSz;           /**< Number of bytes in transmit array,
00268                                if 0 only receive transfer will be carried on */
00269     uint8_t *rxBuff;        /**< Pointer memory where bytes received from I2C be stored */
00270     int     rxSz;           /**< Number of bytes to received,
00271                                if 0 only transmission we be carried on */
00272     I2C_STATUS_T status;    /**< Status of the current I2C transfer */
00273 } I2C_XFER_T;
00274 
00275 /**
00276  * @brief   I2C interface IDs
00277  * @note
00278  * All Chip functions will take this as the first parameter,
00279  * I2C_NUM_INTERFACE must never be used for calling any Chip
00280  * functions, it is only used to find the number of interfaces
00281  * available in the Chip.
00282  */
00283 typedef enum I2C_ID {
00284     I2C0,               /**< ID I2C0 */
00285     I2C_NUM_INTERFACE   /**< Number of I2C interfaces in the chip */
00286 } I2C_ID_T;
00287 
00288 /**
00289  * @brief   I2C master events
00290  */
00291 typedef enum {
00292     I2C_EVENT_WAIT = 1, /**< I2C Wait event */
00293     I2C_EVENT_DONE,     /**< Done event that wakes up Wait event */
00294     I2C_EVENT_LOCK,     /**< Re-entrency lock event for I2C transfer */
00295     I2C_EVENT_UNLOCK,   /**< Re-entrency unlock event for I2C transfer */
00296     I2C_EVENT_SLAVE_RX, /**< Slave receive event */
00297     I2C_EVENT_SLAVE_TX, /**< Slave transmit event */
00298 } I2C_EVENT_T;
00299 
00300 /**
00301  * @brief   Event handler function type
00302  */
00303 typedef void (*I2C_EVENTHANDLER_T)(I2C_ID_T, I2C_EVENT_T);
00304 
00305 /**
00306  * @brief   Initializes the LPC_I2C peripheral with specified parameter.
00307  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00308  * @return  Nothing
00309  */
00310 void Chip_I2C_Init(I2C_ID_T id);
00311 
00312 /**
00313  * @brief   De-initializes the I2C peripheral registers to their default reset values
00314  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00315  * @return  Nothing
00316  */
00317 void Chip_I2C_DeInit(I2C_ID_T id);
00318 
00319 /**
00320  * @brief   Set up clock rate for LPC_I2C peripheral.
00321  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00322  * @param   clockrate   : Target clock rate value to initialized I2C peripheral (Hz)
00323  * @return  Nothing
00324  * @note
00325  * Parameter @a clockrate for I2C0 should be from 1000 up to 1000000
00326  * (1 KHz to 1 MHz), as I2C0 support Fast Mode Plus. If the @a clockrate
00327  * is more than 400 KHz (Fast Plus Mode) Board_I2C_EnableFastPlus()
00328  * must be called prior to calling this function.
00329  */
00330 void Chip_I2C_SetClockRate(I2C_ID_T id, uint32_t clockrate);
00331 
00332 /**
00333  * @brief   Get current clock rate for LPC_I2C peripheral.
00334  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00335  * @return  The current I2C peripheral clock rate
00336  */
00337 uint32_t Chip_I2C_GetClockRate(I2C_ID_T id);
00338 
00339 /**
00340  * @brief   Transmit and Receive data in master mode
00341  * @param   id      : I2C peripheral selected (I2C0, I2C1 etc)
00342  * @param   xfer    : Pointer to a I2C_XFER_T structure see notes below
00343  * @return
00344  * Any of #I2C_STATUS_T values, xfer->txSz will have number of bytes
00345  * not sent due to error, xfer->rxSz will have the number of bytes yet
00346  * to be received.
00347  * @note
00348  * The parameter @a xfer should have its member @a slaveAddr initialized
00349  * to the 7-Bit slave address to which the master will do the xfer, Bit0
00350  * to bit6 should have the address and Bit8 is ignored. During the transfer
00351  * no code (like event handler) must change the content of the memory
00352  * pointed to by @a xfer. The member of @a xfer, @a txBuff and @a txSz be
00353  * initialized to the memory from which the I2C must pick the data to be
00354  * transfered to slave and the number of bytes to send respectively, similarly
00355  * @a rxBuff and @a rxSz must have pointer to memroy where data received
00356  * from slave be stored and the number of data to get from slave respectilvely.
00357  */
00358 int Chip_I2C_MasterTransfer(I2C_ID_T id, I2C_XFER_T *xfer);
00359 
00360 /**
00361  * @brief   Transmit data to I2C slave using I2C Master mode
00362  * @param   id          : I2C peripheral ID (I2C0, I2C1 .. etc)
00363  * @param   slaveAddr   : Slave address to which the data be written
00364  * @param   buff        : Pointer to buffer having the array of data
00365  * @param   len         : Number of bytes to be transfered from @a buff
00366  * @return  Number of bytes successfully transfered
00367  */
00368 int Chip_I2C_MasterSend(I2C_ID_T id, uint8_t slaveAddr, const uint8_t *buff, uint8_t len);
00369 
00370 /**
00371  * @brief   Transfer a command to slave and receive data from slave after a repeated start
00372  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00373  * @param   slaveAddr   : Slave address of the I2C device
00374  * @param   cmd         : Command (Address/Register) to be written
00375  * @param   buff        : Pointer to memory that will hold the data received
00376  * @param   len         : Number of bytes to receive
00377  * @return  Number of bytes successfully received
00378  */
00379 int Chip_I2C_MasterCmdRead(I2C_ID_T id, uint8_t slaveAddr, uint8_t cmd, uint8_t *buff, int len);
00380 
00381 /**
00382  * @brief   Get pointer to current function handling the events
00383  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00384  * @return  Pointer to function handing events of I2C
00385  */
00386 I2C_EVENTHANDLER_T Chip_I2C_GetMasterEventHandler(I2C_ID_T id);
00387 
00388 /**
00389  * @brief   Set function that must handle I2C events
00390  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00391  * @param   event       : Pointer to function that will handle the event (Should not be NULL)
00392  * @return  1 when successful, 0 when a transfer is on going with its own event handler
00393  */
00394 int Chip_I2C_SetMasterEventHandler(I2C_ID_T id, I2C_EVENTHANDLER_T event);
00395 
00396 /**
00397  * @brief   Set function that must handle I2C events
00398  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00399  * @param   slaveAddr   : Slave address from which data be read
00400  * @param   buff        : Pointer to memory where data read be stored
00401  * @param   len         : Number of bytes to read from slave
00402  * @return  Number of bytes read successfully
00403  */
00404 int Chip_I2C_MasterRead(I2C_ID_T id, uint8_t slaveAddr, uint8_t *buff, int len);
00405 
00406 /**
00407  * @brief   Default event handler for polling operation
00408  * @param   id      : I2C peripheral ID (I2C0, I2C1 ... etc)
00409  * @param   event   : Event ID of the event that called the function
00410  * @return  Nothing
00411  */
00412 void Chip_I2C_EventHandlerPolling(I2C_ID_T id, I2C_EVENT_T event);
00413 
00414 /**
00415  * @brief   Default event handler for interrupt base operation
00416  * @param   id      : I2C peripheral ID (I2C0, I2C1 ... etc)
00417  * @param   event   : Event ID of the event that called the function
00418  * @return  Nothing
00419  */
00420 void Chip_I2C_EventHandler(I2C_ID_T id, I2C_EVENT_T event);
00421 
00422 /**
00423  * @brief   I2C Master transfer state change handler
00424  * @param   id      : I2C peripheral ID (I2C0, I2C1 ... etc)
00425  * @return  Nothing
00426  * @note    Usually called from the appropriate Interrupt handler
00427  */
00428 void Chip_I2C_MasterStateHandler(I2C_ID_T id);
00429 
00430 /**
00431  * @brief   Disable I2C peripheral's operation
00432  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00433  * @return  Nothing
00434  */
00435 void Chip_I2C_Disable(I2C_ID_T id);
00436 
00437 /**
00438  * @brief   Checks if master xfer in progress
00439  * @param   id      : I2C peripheral ID (I2C0, I2C1 ... etc)
00440  * @return  1 if master xfer in progress 0 otherwise
00441  * @note
00442  * This API is generally used in interrupt handler
00443  * of the application to decide whether to call
00444  * master state handler or to call slave state handler
00445  */
00446 int Chip_I2C_IsMasterActive(I2C_ID_T id);
00447 
00448 /**
00449  * @brief   Setup a slave I2C device
00450  * @param   id          : I2C peripheral ID (I2C0, I2C1 ... etc)
00451  * @param   sid         : I2C Slave peripheral ID (I2C_SLAVE_0, I2C_SLAVE_1 etc)
00452  * @param   xfer        : Pointer to transfer structure (see note below for more info)
00453  * @param   event       : Event handler for slave transfers
00454  * @param   addrMask    : Address mask to use along with slave address (see notes below for more info)
00455  * @return  Nothing
00456  * @note
00457  * Parameter @a xfer should point to a valid I2C_XFER_T structure object
00458  * and must have @a slaveAddr initialized with 7bit Slave address (From Bit1 to Bit7),
00459  * Bit0 when set enables general call handling, @a slaveAddr along with @a addrMask will
00460  * be used to match the slave address. @a rxBuff and @a txBuff must point to valid buffers
00461  * where slave can receive or send the data from, size of which will be provided by
00462  * @a rxSz and @a txSz respectively. Function pointed to by @a event will be called
00463  * for the following events #I2C_EVENT_SLAVE_RX (One byte of data received successfully
00464  * from the master and stored inside memory pointed by xfer->rxBuff, incremented
00465  * the pointer and decremented the @a xfer->rxSz), #I2C_EVENT_SLAVE_TX (One byte of
00466  * data from xfer->txBuff was sent to master successfully, incremented the pointer
00467  * and decremented xfer->txSz), #I2C_EVENT_DONE (Master is done doing its transfers
00468  * with the slave).<br>
00469  * <br>Bit-0 of the parameter @a addrMask is reserved and should always be 0. Any bit (BIT1
00470  * to BIT7) set in @a addrMask will make the corresponding bit in *xfer->slaveAddr* as
00471  * don't care. Thit is, if *xfer->slaveAddr* is (0x10 << 1) and @a addrMask is (0x03 << 1) then
00472  * 0x10, 0x11, 0x12, 0x13 will all be considered as valid slave addresses for the registered
00473  * slave. Upon receving any event *xfer->slaveAddr* (BIT1 to BIT7) will hold the actual
00474  * address which was received from master.<br>
00475  * <br><b>General Call Handling</b><br>
00476  * Slave can receive data from master using general call address (0x00). General call
00477  * handling must be setup as given below
00478  *      - Call Chip_I2C_SlaveSetup() with argument @a sid as I2C_SLAVE_GENERAL
00479  *          - xfer->slaveAddr ignored, argument @a addrMask ignored
00480  *          - function provided by @a event will registered to be called when slave received data using addr 0x00
00481  *          - xfer->rxBuff and xfer->rxSz should be valid in argument @a xfer
00482  *      - To handle General Call only (No other slaves are configured)
00483  *          - Call Chip_I2C_SlaveSetup() with sid as I2C_SLAVE_X (X=0,1,2,3)
00484  *          - setup @a xfer with slaveAddr member set to 0, @a event is ignored hence can be NULL
00485  *          - provide @a addrMask (typically 0, if not you better be knowing what you are doing)
00486  *      - To handler General Call when other slave is active
00487  *          - Call Chip_I2C_SlaveSetup() with sid as I2C_SLAVE_X (X=0,1,2,3)
00488  *          - setup @a xfer with slaveAddr member set to 7-Bit Slave address [from Bit1 to 7]
00489  *          - Set Bit0 of @a xfer->slaveAddr as 1
00490  *          - Provide appropriate @a addrMask
00491  *          - Argument @a event must point to function, that handles events from actual slaveAddress and not the GC
00492  * @warning
00493  * If the slave has only one byte in its txBuff, once that byte is transfered to master the event handler
00494  * will be called for event #I2C_EVENT_DONE. If the master attempts to read more bytes in the same transfer
00495  * then the slave hardware will send 0xFF to master till the end of transfer, event handler will not be
00496  * called to notify this. For more info see section below<br>
00497  * <br><b> Last data handling in slave </b><br>
00498  * If the user wants to implement a slave which will read a byte from a specific location over and over
00499  * again whenever master reads the slave. If the user initializes the xfer->txBuff as the location to read
00500  * the byte from and xfer->txSz as 1, then say, if master reads one byte; slave will send the byte read from
00501  * xfer->txBuff and will call the event handler with #I2C_EVENT_DONE. If the master attempts to read another
00502  * byte instead of sending the byte read from xfer->txBuff the slave hardware will send 0xFF and no event will
00503  * occur. To handle this issue, slave should set xfer->txSz to 2, in which case when master reads the byte
00504  * event handler will be called with #I2C_EVENT_SLAVE_TX, in which the slave implementation can reset the buffer
00505  * and size back to original location (i.e, xfer->txBuff--, xfer->txSz++), if the master reads another byte
00506  * in the same transfer, byte read from xfer->txBuff will be sent and #I2C_EVENT_SLAVE_TX will be called again, and
00507  * the process repeats.
00508  */
00509 void Chip_I2C_SlaveSetup(I2C_ID_T id,
00510                          I2C_SLAVE_ID sid,
00511                          I2C_XFER_T *xfer,
00512                          I2C_EVENTHANDLER_T event,
00513                          uint8_t addrMask);
00514 
00515 /**
00516  * @brief   I2C Slave event handler
00517  * @param   id      : I2C peripheral ID (I2C0, I2C1 ... etc)
00518  * @return  Nothing
00519  */
00520 void Chip_I2C_SlaveStateHandler(I2C_ID_T id);
00521 
00522 /**
00523  * @brief   I2C peripheral state change checking
00524  * @param   id      : I2C peripheral ID (I2C0, I2C1 ... etc)
00525  * @return  1 if I2C peripheral @a id has changed its state,
00526  *          0 if there is no state change
00527  * @note
00528  * This function must be used by the application when
00529  * the polling has to be done based on state change.
00530  */
00531 int Chip_I2C_IsStateChanged(I2C_ID_T id);
00532 
00533 #endif /* !defined(CHIP_LPC110X) */
00534 
00535 /**
00536  * @}
00537  */
00538 
00539  #ifdef __cplusplus
00540 }
00541 #endif
00542 
00543 #endif /* __I2C_11XX_H_ */