LPCOpen Platform for LPC112X microcontrollers  112X
LPCOpen Platform for the NXP LPC112X family of Microcontrollers
Data Structures
i2c_112x.h File Reference
#include "i2c_common_112x.h"

Go to the source code of this file.

Data Structures

struct  I2C_XFER_T
 Master transfer data structure definitions. More...
 

Macro Definition Documentation

#define I2C_BYTE_RECV   0x02

Definition at line 78 of file i2c_112x.h.

#define I2C_BYTE_SENT   0x01

Definition at line 77 of file i2c_112x.h.

#define I2C_CheckError (   ErrorCode)    (ErrorCode & 0x10000000)

Definition at line 87 of file i2c_112x.h.

#define I2C_ERR   (0x10000000)

Definition at line 84 of file i2c_112x.h.

#define I2C_I2STAT_BUS_ERROR   ((0x00))

Bus Error

Definition at line 64 of file i2c_112x.h.

#define I2C_I2STAT_NO_INF   ((0xF8))

No relevant information

Definition at line 63 of file i2c_112x.h.

#define I2C_LAST_BYTE_RECV   0x04

Definition at line 79 of file i2c_112x.h.

#define I2C_MONITOR_CFG_MATCHALL   I2C_I2MMCTRL_MATCH_ALL

Select interrupt register match

Definition at line 93 of file i2c_112x.h.

#define I2C_MONITOR_CFG_SCL_OUTPUT   I2C_I2MMCTRL_ENA_SCL

SCL output enable

Definition at line 92 of file i2c_112x.h.

#define I2C_NAK_RECV   (0x10000000 | 0x01)

Definition at line 85 of file i2c_112x.h.

#define I2C_OK   0x00

Definition at line 76 of file i2c_112x.h.

#define I2C_RECV_END   0x10

Definition at line 81 of file i2c_112x.h.

#define I2C_SEND_END   0x08

Definition at line 80 of file i2c_112x.h.

#define I2C_SETUP_STATUS_ARBF   (1 << 8)

Arbitration false

Definition at line 69 of file i2c_112x.h.

#define I2C_SETUP_STATUS_DONE   (1 << 10)

Status DONE

Definition at line 71 of file i2c_112x.h.

#define I2C_SETUP_STATUS_NOACKF   (1 << 9)

No ACK returned

Definition at line 70 of file i2c_112x.h.

#define I2C_STA_STO_RECV   0x20

I2C state handle return values.

Definition at line 82 of file i2c_112x.h.

#define I2C_STA_STO_RECV   0x20

I2C state handle return values.

Definition at line 82 of file i2c_112x.h.

#define RET_SLAVE_BUSY   0

Return value, when slave is busy

Definition at line 53 of file i2c_112x.h.

#define RET_SLAVE_IDLE   2

Return value, when slave enter idle mode

Definition at line 52 of file i2c_112x.h.

#define RET_SLAVE_RX   5

Return value, when 1 byte RX'd successfully

Definition at line 51 of file i2c_112x.h.

#define RET_SLAVE_TX   6

Return values for SLAVE handler.

Note
Chip drivers will usally be designed to match their events with this valueReturn value, when 1 byte TX'd successfully

Definition at line 50 of file i2c_112x.h.

Typedef Documentation

typedef void(* I2C_EVENTHANDLER_T)(I2C_ID_T, I2C_EVENT_T)

Event handler function type.

Definition at line 161 of file i2c_112x.h.

Enumeration Type Documentation

I2C master events.

Enumerator
I2C_EVENT_WAIT 

I2C Wait event

I2C_EVENT_DONE 

Done event that wakes up Wait event

I2C_EVENT_LOCK 

Re-entrency lock event for I2C transfer

I2C_EVENT_UNLOCK 

Re-entrency unlock event for I2C transfer

I2C_EVENT_SLAVE_RX 

Slave receive event

I2C_EVENT_SLAVE_TX 

Slave transmit event

Definition at line 149 of file i2c_112x.h.

enum I2C_ID_T

I2C interface IDs.

Note
All Chip functions will take this as the first parameter, I2C_NUM_INTERFACE must never be used for calling any Chip functions, it is only used to find the number of interfaces available in the Chip.
Enumerator
I2C0 

ID I2C0

I2C_NUM_INTERFACE 

Number of I2C interfaces in the chip

Definition at line 141 of file i2c_112x.h.

I2C Slave Identifiers.

Enumerator
I2C_SLAVE_GENERAL 

Slave ID for general calls

I2C_SLAVE_0 

Slave ID fo Slave Address 0

I2C_SLAVE_1 

Slave ID fo Slave Address 1

I2C_SLAVE_2 

Slave ID fo Slave Address 2

I2C_SLAVE_3 

Slave ID fo Slave Address 3

I2C_SLAVE_NUM_INTERFACE 

Number of slave interfaces

Definition at line 98 of file i2c_112x.h.

I2C transfer status.

Enumerator
I2C_STATUS_DONE 

Transfer done successfully

I2C_STATUS_NAK 

NAK received during transfer

I2C_STATUS_ARBLOST 

Aribitration lost during transfer

I2C_STATUS_BUSERR 

Bus error in I2C transfer

I2C_STATUS_BUSY 

I2C is busy doing transfer

I2C_STATUS_SLAVENAK 

NAK received after SLA+W or SLA+R

Definition at line 110 of file i2c_112x.h.

Function Documentation

void Chip_I2C_DeInit ( I2C_ID_T  id)

De-initializes the I2C peripheral registers to their default reset values.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
Nothing

Definition at line 374 of file i2c_112x.c.

void Chip_I2C_Disable ( I2C_ID_T  id)

Disable I2C peripheral's operation.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
Nothing

Definition at line 543 of file i2c_112x.c.

void Chip_I2C_EventHandler ( I2C_ID_T  id,
I2C_EVENT_T  event 
)

Default event handler for interrupt base operation.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
event: Event ID of the event that called the function
Returns
Nothing

Definition at line 326 of file i2c_112x.c.

void Chip_I2C_EventHandlerPolling ( I2C_ID_T  id,
I2C_EVENT_T  event 
)

Default event handler for polling operation.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
event: Event ID of the event that called the function
Returns
Nothing

Definition at line 342 of file i2c_112x.c.

uint32_t Chip_I2C_GetClockRate ( I2C_ID_T  id)

Get current clock rate for LPC_I2C peripheral.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
The current I2C peripheral clock rate

Definition at line 393 of file i2c_112x.c.

I2C_EVENTHANDLER_T Chip_I2C_GetMasterEventHandler ( I2C_ID_T  id)

Get pointer to current function handling the events.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
Pointer to function handing events of I2C

Definition at line 409 of file i2c_112x.c.

void Chip_I2C_Init ( I2C_ID_T  id)

Initializes the LPC_I2C peripheral with specified parameter.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
Nothing

Definition at line 362 of file i2c_112x.c.

int Chip_I2C_IsMasterActive ( I2C_ID_T  id)

Checks if master xfer in progress.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
1 if master xfer in progress 0 otherwise
Note
This API is generally used in interrupt handler of the application to decide whether to call master state handler or to call slave state handler

Definition at line 480 of file i2c_112x.c.

int Chip_I2C_IsStateChanged ( I2C_ID_T  id)

I2C peripheral state change checking.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
1 if I2C peripheral id has changed its state, 0 if there is no state change
Note
This function must be used by the application when the polling has to be done based on state change.

Definition at line 549 of file i2c_112x.c.

int Chip_I2C_MasterCmdRead ( I2C_ID_T  id,
uint8_t  slaveAddr,
uint8_t  cmd,
uint8_t *  buff,
int  len 
)

Transfer a command to slave and receive data from slave after a repeated start.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
slaveAddr: Slave address of the I2C device
cmd: Command (Address/Register) to be written
buff: Pointer to memory that will hold the data received
len: Number of bytes to receive
Returns
Number of bytes successfully received

Definition at line 456 of file i2c_112x.c.

int Chip_I2C_MasterRead ( I2C_ID_T  id,
uint8_t  slaveAddr,
uint8_t *  buff,
int  len 
)

Set function that must handle I2C events.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
slaveAddr: Slave address from which data be read
buff: Pointer to memory where data read be stored
len: Number of bytes to read from slave
Returns
Number of bytes read successfully

Definition at line 469 of file i2c_112x.c.

int Chip_I2C_MasterSend ( I2C_ID_T  id,
uint8_t  slaveAddr,
const uint8_t *  buff,
uint8_t  len 
)

Transmit data to I2C slave using I2C Master mode.

Parameters
id: I2C peripheral ID (I2C0, I2C1 .. etc)
slaveAddr: Slave address to which the data be written
buff: Pointer to buffer having the array of data
len: Number of bytes to be transfered from buff
Returns
Number of bytes successfully transfered

Definition at line 443 of file i2c_112x.c.

void Chip_I2C_MasterStateHandler ( I2C_ID_T  id)

I2C Master transfer state change handler.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
Nothing
Note
Usually called from the appropriate Interrupt handler

Definition at line 486 of file i2c_112x.c.

int Chip_I2C_MasterTransfer ( I2C_ID_T  id,
I2C_XFER_T xfer 
)

Transmit and Receive data in master mode.

Parameters
id: I2C peripheral selected (I2C0, I2C1 etc)
xfer: Pointer to a I2C_XFER_T structure see notes below
Returns
Any of I2C_STATUS_T values, xfer->txSz will have number of bytes not sent due to error, xfer->rxSz will have the number of bytes yet to be received.
Note
The parameter xfer should have its member slaveAddr initialized to the 7-Bit slave address to which the master will do the xfer, Bit0 to bit6 should have the address and Bit8 is ignored. During the transfer no code (like event handler) must change the content of the memory pointed to by xfer. The member of xfer, txBuff and txSz be initialized to the memory from which the I2C must pick the data to be transfered to slave and the number of bytes to send respectively, similarly rxBuff and rxSz must have pointer to memroy where data received from slave be stored and the number of data to get from slave respectilvely.

Definition at line 415 of file i2c_112x.c.

void Chip_I2C_SetClockRate ( I2C_ID_T  id,
uint32_t  clockrate 
)

Set up clock rate for LPC_I2C peripheral.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
clockrate: Target clock rate value to initialized I2C peripheral (Hz)
Returns
Nothing
Note
Parameter clockrate for I2C0 should be from 1000 up to 1000000 (1 KHz to 1 MHz), as I2C0 support Fast Mode Plus. If the clockrate is more than 400 KHz (Fast Plus Mode) Board_I2C_EnableFastPlus() must be called prior to calling this function.

Definition at line 383 of file i2c_112x.c.

int Chip_I2C_SetMasterEventHandler ( I2C_ID_T  id,
I2C_EVENTHANDLER_T  event 
)

Set function that must handle I2C events.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
event: Pointer to function that will handle the event (Should not be NULL)
Returns
1 when successful, 0 when a transfer is on going with its own event handler

Definition at line 399 of file i2c_112x.c.

void Chip_I2C_SlaveSetup ( I2C_ID_T  id,
I2C_SLAVE_ID  sid,
I2C_XFER_T xfer,
I2C_EVENTHANDLER_T  event,
uint8_t  addrMask 
)

Setup a slave I2C device.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
sid: I2C Slave peripheral ID (I2C_SLAVE_0, I2C_SLAVE_1 etc)
xfer: Pointer to transfer structure (see note below for more info)
event: Event handler for slave transfers
addrMask: Address mask to use along with slave address (see notes below for more info)
Returns
Nothing
Note
Parameter xfer should point to a valid I2C_XFER_T structure object and must have slaveAddr initialized with 7bit Slave address (From Bit1 to Bit7), Bit0 when set enables general call handling, slaveAddr along with addrMask will be used to match the slave address. rxBuff and txBuff must point to valid buffers where slave can receive or send the data from, size of which will be provided by rxSz and txSz respectively. Function pointed to by event will be called for the following events I2C_EVENT_SLAVE_RX (One byte of data received successfully from the master and stored inside memory pointed by xfer->rxBuff, incremented the pointer and decremented the xfer->rxSz), I2C_EVENT_SLAVE_TX (One byte of data from xfer->txBuff was sent to master successfully, incremented the pointer and decremented xfer->txSz), I2C_EVENT_DONE (Master is done doing its transfers with the slave).

Bit-0 of the parameter addrMask is reserved and should always be 0. Any bit (BIT1 to BIT7) set in addrMask will make the corresponding bit in xfer->slaveAddr as don't care. Thit is, if xfer->slaveAddr is (0x10 << 1) and addrMask is (0x03 << 1) then 0x10, 0x11, 0x12, 0x13 will all be considered as valid slave addresses for the registered slave. Upon receving any event xfer->slaveAddr (BIT1 to BIT7) will hold the actual address which was received from master.

General Call Handling
Slave can receive data from master using general call address (0x00). General call handling must be setup as given below
  • Call Chip_I2C_SlaveSetup() with argument sid as I2C_SLAVE_GENERAL
    • xfer->slaveAddr ignored, argument addrMask ignored
    • function provided by event will registered to be called when slave received data using addr 0x00
    • xfer->rxBuff and xfer->rxSz should be valid in argument xfer
  • To handle General Call only (No other slaves are configured)
    • Call Chip_I2C_SlaveSetup() with sid as I2C_SLAVE_X (X=0,1,2,3)
    • setup xfer with slaveAddr member set to 0, event is ignored hence can be NULL
    • provide addrMask (typically 0, if not you better be knowing what you are doing)
  • To handler General Call when other slave is active
    • Call Chip_I2C_SlaveSetup() with sid as I2C_SLAVE_X (X=0,1,2,3)
    • setup xfer with slaveAddr member set to 7-Bit Slave address [from Bit1 to 7]
    • Set Bit0 of xfer->slaveAddr as 1
    • Provide appropriate addrMask
    • Argument event must point to function, that handles events from actual slaveAddress and not the GC
Warning
If the slave has only one byte in its txBuff, once that byte is transfered to master the event handler will be called for event I2C_EVENT_DONE. If the master attempts to read more bytes in the same transfer then the slave hardware will send 0xFF to master till the end of transfer, event handler will not be called to notify this. For more info see section below

Last data handling in slave
If the user wants to implement a slave which will read a byte from a specific location over and over again whenever master reads the slave. If the user initializes the xfer->txBuff as the location to read the byte from and xfer->txSz as 1, then say, if master reads one byte; slave will send the byte read from xfer->txBuff and will call the event handler with I2C_EVENT_DONE. If the master attempts to read another byte instead of sending the byte read from xfer->txBuff the slave hardware will send 0xFF and no event will occur. To handle this issue, slave should set xfer->txSz to 2, in which case when master reads the byte event handler will be called with I2C_EVENT_SLAVE_TX, in which the slave implementation can reset the buffer and size back to original location (i.e, xfer->txBuff–, xfer->txSz++), if the master reads another byte in the same transfer, byte read from xfer->txBuff will be sent and I2C_EVENT_SLAVE_TX will be called again, and the process repeats.

Definition at line 494 of file i2c_112x.c.

void Chip_I2C_SlaveStateHandler ( I2C_ID_T  id)

I2C Slave event handler.

Parameters
id: I2C peripheral ID (I2C0, I2C1 ... etc)
Returns
Nothing

Definition at line 517 of file i2c_112x.c.