--- README	2003-06-21 00:10:58.000000000 +0100
+++ README.new	2003-06-30 15:51:30.000000000 +0100
@@ -653,6 +653,9 @@ The following options need to be configu
 		CONFIG_RTC_DS1338	- use Maxim, Inc. DS1338 RTC
 		CONFIG_RTC_DS164x	- use Dallas DS164x RTC
 
+		Note that if the RTC uses I2C, then the I2C interface
+		must also be configured. See I2C Support, below.
+
 - Timestamp Support:
 
 		When CONFIG_TIMESTAMP is selected, the timestamp
@@ -904,29 +907,48 @@ The following options need to be configu
 
 - I2C Support:	CONFIG_HARD_I2C | CONFIG_SOFT_I2C
 
-		Enables I2C serial bus commands.  If this is selected,
-		either CONFIG_HARD_I2C or CONFIG_SOFT_I2C must be defined
-		to include the appropriate I2C driver.
-
-		See also: common/cmd_i2c.c for a description of the
+		These enable I2C serial bus commands. Defining either of
+		(but not both of) CONFIG_HARD_I2C or CONFIG_SOFT_I2C will 
+		include the appropriate I2C driver for the selected cpu. 
+
+		This will allow you to use i2c commands at the u-boot 
+		command line (as long as you set CFG_CMD_I2C in 
+		CONFIG_COMMANDS) and communicate with i2c based realtime
+		clock chips. See common/cmd_i2c.c for a description of the
 		command line interface.
 
+		CONFIG_HARD_I2C	selects the CPM hardware driver for I2C. 
 
-		CONFIG_HARD_I2C
-
-		Selects the CPM hardware driver for I2C.
-
-		CONFIG_SOFT_I2C
-
-		Use software (aka bit-banging) driver instead of CPM
-		or similar hardware support for I2C.  This is configured
-		via the following defines.
+		CONFIG_SOFT_I2C configures u-boot to use a software (aka 
+		bit-banging) driver instead of CPM or similar hardware
+		support for I2C.
+
+		There are several other quantities that must also be 
+		defined when you define CONFIG_HARD_I2C or CONFIG_SOFT_I2C.
+
+		In both cases you will need to define CFG_I2C_SPEED
+		to be the frequency (in Hz) at which you wish your i2c bus 
+		to run and CFG_I2C_SLAVE to be the address of this node (ie 
+		the cpu's i2c node address). 
+		
+		Now, the u-boot i2c code for the mpc8xx (cpu/mpc8xx/i2c.c)
+		sets the cpu up as a master node and so its address should
+		therefore be cleared to 0 (See, eg, MPC823e User's Manual
+		p.16-473). So, set CFG_I2C_SLAVE to 0.  
+
+		That's all that's required for CONFIG_HARD_I2C. 
+
+		If you use the software i2c interface (CONFIG_SOFT_I2C)
+		then the following macros need to be defined (examples are
+		from include/configs/lwmon.h):
 
 		I2C_INIT
 
-		(Optional). Any commands necessary to enable I2C
+		(Optional). Any commands necessary to enable the I2C
 		controller or configure ports.
 
+		eg: #define I2C_INIT (immr->im_cpm.cp_pbdir |=  PB_SCL)
+
 		I2C_PORT
 
 		(Only for MPC8260 CPU). The I/O port to use (the code
@@ -939,32 +961,49 @@ The following options need to be configu
 		(driven).  If the data line is open collector, this
 		define can be null.
 
+		eg: #define I2C_ACTIVE (immr->im_cpm.cp_pbdir |=  PB_SDA)
+
 		I2C_TRISTATE
 
 		The code necessary to make the I2C data line tri-stated
 		(inactive).  If the data line is open collector, this
 		define can be null.
 
+		eg: #define I2C_TRISTATE (immr->im_cpm.cp_pbdir &= ~PB_SDA)
+
 		I2C_READ
 
 		Code that returns TRUE if the I2C data line is high,
 		FALSE if it is low.
 
+		eg: #define I2C_READ ((immr->im_cpm.cp_pbdat & PB_SDA) != 0)
+
 		I2C_SDA(bit)
 
 		If <bit> is TRUE, sets the I2C data line high. If it
 		is FALSE, it clears it (low).
 
+		eg: #define I2C_SDA(bit) \
+		         if(bit) immr->im_cpm.cp_pbdat |=  PB_SDA; \
+		         else    immr->im_cpm.cp_pbdat &= ~PB_SDA
+
 		I2C_SCL(bit)
 
 		If <bit> is TRUE, sets the I2C clock line high. If it
 		is FALSE, it clears it (low).
 
+		eg: #define I2C_SCL(bit) \
+		         if(bit) immr->im_cpm.cp_pbdat |=  PB_SCL; \
+		         else    immr->im_cpm.cp_pbdat &= ~PB_SCL 
+
 		I2C_DELAY
 
 		This delay is invoked four times per clock cycle so this
 		controls the rate of data transfer.  The data rate thus
-		is 1 / (I2C_DELAY * 4).
+		is 1 / (I2C_DELAY * 4). Often defined to be something
+		like: 
+		
+		#define I2C_DELAY  udelay(2)
 
 		CFG_I2C_INIT_BOARD