From 6097be8409a508c81a9a719678bfc9c2ce45b8d7 Mon Sep 17 00:00:00 2001
From: ian <ian>
Date: Fri, 11 Nov 2005 01:07:59 +0000
Subject: [PATCH] first cut of master i2c interface doc

---
 detpic/i2clib.inc | 142 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 122 insertions(+), 20 deletions(-)

diff --git a/detpic/i2clib.inc b/detpic/i2clib.inc
index 8feda28..d214932 100644
--- a/detpic/i2clib.inc
+++ b/detpic/i2clib.inc
@@ -108,8 +108,8 @@ extern i2cm_interrupt
 ;
 ;                   [Not-in-use]
 ;		       	 |
-;		     	 |init			   
-;		     	 v			   
+;		     	 |init
+;		     	 v
 ;                      [Idle]<-------------------------.
 ;           write_begin/    \                          |
 ;	              /	     \read_begin               |
@@ -187,29 +187,131 @@ extern i2csu_read_done
 ;   		Beforehand	At call			On return
 ;   State	Transmitting	Idle
 
+;======================================================================
+; MASTER
+;
+; States:
+;	 	       	[Not-in-use]
+;	       	    	     |
+;	    		     |init
+;      	    		     v
+;	 		   [Idle]<-----------------------------.
+;	 	write_start/    \			       |
+;                         /    	 \			       |
+;	 	   	 V	  V			       |
+;            [Writing-Setup]    [Reading-Busy]<---------.      |
+;                   |		      |	       	 	|      |
+;    write_next_byte|		      |read_got_byte	|      |
+;    must return NZ |		      |        	    	|      |
+;    	       	    V  	       	      V	       	 	|      |
+;           ,-->[Writing]         [Reading-Wait]	|      |
+;           `-------'  \ 	    /  	  `-------------'      |
+;    write_next_byte    \ 	   /   	   read_another	       |
+;       returns NZ       |	  /    	      	       	       |
+;                        |       /read_done    	       	       |
+;         write_next_byte|      |			       |
+;             returns Z  |      |      			       |
+;                        V      V			       |
+;      	               	[Stopping]	    		       |
+;	 	       	    |		done		       |
+;	 		    `----------------------------------'
+
+;--------------------
+extern i2cmu_done
+
+; Called to notify that the previous conversation with the slave has
+; been finished as requested.  The i2c system is now available and
+; i2cm_*_start can be called.
+;
+;		Beforehand	At call
+;   State	Stopping	Idle
+
+;========================================
+; MASTER - WRITES (ie, transmission of data to the slave)
+
+;--------------------
+extern i2cm_write_start
+;
+; Requests that a slave be contacted for writing.  When communication
+; has been established, i2cmu_write_next_byte will be called.
+;
+;   				At call		On return
+;   State	  		Idle		Writing-Setup
+;   W		      		slave number	any
+
+extern i2cmu_write_next_byte
+;
+; Called to notify the main program that we are now ready to transmit
+; a byte to the slave that we're currently talking to.  This may be
+; either because i2cm_write_start was previously called and
+; communication has been established, or because tranmission of the
+; previous byte is complete.
+;
+; The main program must immediately supply the actual data byte.  This
+; byte will then be transmitted to the slave, and then
+; i2cmu_write_next_byte will be called again.
 
+; Alternatively the main program may indicate that the tranmission
+; should finish by setting the Z flag on return.  In this case the
+; slave will be told that this is the end of the message and the i2c
+; conversation will be finished.  When the conversation is finished
+; and the bus and i2c controller are free again, i2cmu_done will be
+; called.
+;
+;  When transmission should continue:
+;
+;   		Beforehand	At call		On return	After return
+;   State	Writing[-Setup]	Writing		Writing		Writing
+;   Status Z			any		0 (NZ, not zero, not equal)
+;   W				any		data for slave
+;
+;  When transmission should finish:
+;
+;   		Beforehand	At call		On return	After return
+;   State	Writing		Writing		Writing		Stopping
+;   Status Z			any		1 (Z, zero, equal)
+;   W				any		any
 
+;========================================
+; MASTER - READS (ie, reception of data from the slave)
 
+;--------------------
+extern i2cm_read_start
+;
+; Requests that a slave be contacted for reading.  When communication
+; has been established and the first byte received,
+; i2cmu_read_got_byte will be called.
+;
+;   				At call		On return
+;   State	  		Idle		Reading-Busy
+;   W		      		slave number	any
 
-; junky bits after here need turning into MASTER sections.
+extern i2cmu_read_got_byte
+;
+; Called to notify the main program that a byte has been recieved from
+; the slave PIC.  The byte value is supplied.  Communication with the
+; slave will be suspended (with the i2c bus blocked) until the main
+; program calls i2cm_read_another or i2cm_read_done.  The main program
+; must call one of these two before doing anything else with the i2c.
+;
+;   		Beforehand	At call
+;   State	Reading		Reading-Wait
+;   W				data from slave
 
+extern i2cm_read_another
+;
+; Requests that the communication with the slave continue and another
+; byte be read.  When this is complete, i2cmu_read_got_byte will be
+; called.
+;
+;   				At call		On return
+;   State	  		Reading-Wait	Reading-Busy
 
+extern i2cm_read_done
 ;
-; i2cm_write_start
-;	slave no.
-;   causes
-; i2cmu_write_next_byte
-;	must return byte to transmit
-;	must say whether to stop
-;   stop causes
-; i2cmu_done
+; Requests that reading from the slave be terminated.  When the
+; conversation is finished and the bus and i2c controller are free
+; again, i2cmu_done will be called.
 ;
-; i2cm_read_start
-;	slave no.
-;   causes
-; i2cmu_read_got_byte
-;	byte value
-;   causes
-; i2cm_read_another or i2cm_read_done
-;  causes               causes
-;  i2cmu_done		i2cmu_done
+;   				At call		On return
+;   State	  		Reading-Wait   	Stopping
-- 
2.30.2