* Code cleanup:

[u-boot.git] / cpu / mpc824x / drivers / i2c / README

CONTENT:

   i2c.h
   i2c1.c
   i2c2.s

WHAT ARE THESE FILES:

These files contain MPC8240 (Kahlua) I2C
driver routines. The driver routines are not
written for any specific operating system.
They serves the purpose of code sample, and
jump-start for using the MPC8240 I2C unit.

For the reason of correctness of C language
syntax, these files are compiled by Metaware
C compiler and assembler.

ENDIAN NOTATION:

The algorithm is designed for big-endian mode,
software is responsible for byte swapping.

USAGE:

1. The host system that is running on MPC8240
   shall link the files listed here. The memory
   location of driver routines shall take into
   account of that driver routines need to run
   in supervisor mode and they process I2C
   interrupt.

2. The host system is responsible for configuring
   the MPC8240 including Embedded Utilities Memory
   Block. All I2C driver functions require the
   content of Embedded Utilities Memory Block
   Base Address Register, EUMBBAR, as the first
   parameter.

3. Before I2C unit of MPC8240 can be used,
   initialize I2C unit by calling I2C_Init
   with the corresponding parameters.

   Note that the I2CFDR register shall be written
   once during the initialization. If it is written
   in the midst of transers, or after I2C STOPs or
   REPEAT STATRs, depending on the data written,
   a long reset time may be encountered.

4. After I2C unit has been successfully initialized,
   use the Application level API to send data or
   receive data upon the desired mode, Master or
   Slave.

5. If the host system is also using the EPIC unit
   on MPC8240, the system can register the
   I2C_ISR with the EPIC including other
   desired resources.

   If the host system does not using the EPIC unit
   on MPC8240, I2C_Timer_Event function can
   be called for each desired time interval.

   In both cases, the host system is free to provide
   its own timer event handler and interrupt service
   routine.

6. The I2C driver routines contains a set
   of utilities, Set and Get, for host system
   to query and modify the desired I2C registers.

7. It is the host system's responsibility of
   queueing the I2C I/O request. The host
   system shall check the I2C_ISR return code
   for I2C I/O status. If I2C_ISR returns
   I2CBUFFEMPTY or I2CBUFFFULL, it means
   I2C unit has completed a I/O request
   stated by the Application API.

8. If the host system has more than one master
   mode I2C unit I/O requests but doesn't want
   to be intervented by being addressed as slave,
   the host system can use the master mode
   Application API with stop_flag set to 0 in
   conjunction with is_cnt flag set to 1.
   The first API call sets both stop_flag and
   is_cnt to 0, indicating a START condition
   shall be generated but when the end of
   transaction is reached, do not generate a
   STOP condition. Once the host system is
   informed that the transaction has been
   completed, the next Application API call
   shall set is_cnt flag to 1, indicating a
   repeated START condition shall be generated.
   The last Application API call shall set
   stop_flag
   to 1.

9. The I2C_Timer_Event function containes
   a user defined function pointer. It
   serves the purpose of providing the
   host system a way to use its own event
   handler instead of the I2C_ISR provided
   here.