detpic/i2clib.inc

   1 ;######################################################################
   2 ; i2clib.inc - I2C LIBRARY - DECLARATIONS AND DOCUMENTATION
   3 ;
   4 ;
   5 ;============================================================
   6 ; GENERAL INFORMATION
   7 ;
   8 ; Naming scheme:
   9 ;  i2cm_...  on master   or  i2cmu_... for upcalls
  10 ;  i2cs_...  on slave    or  i2csu_... for upcalls
  11 ; ie,
  12 ;  i2c?_...     are for use by the rest of the program and
  13 ;                are the entrypoints which enable I2C use.
  14 ;  i2c?u_...    must be defined in the rest of the program
  15 ;                with the functionality and behaviour described.
  16 ;  i2cm_...     may only be called on the master PIC.
  17 ;  i2cs_...     may only be called on slave PICs.
  18
  19 ; At all times following i2c[ms]_init, the i2c hardware in the PIC is
  20 ; completely reserved to the routines defined in i2clib.asm.  Nothing
  21 ; else is allowed to read or modify the i2c controller state.
  22 ; Likewise, the memory locations (variables) defined there are for use
  23 ; by those routines only and must not be touched by the main program.
  24
  25 ; Unless otherwise stated, all routines accept any value in, and may
  26 ; trash, W and the flags.  All other registers and locations not
  27 ; specifically mentioned here will be preserved by the
  28 ; i2c?_... routines (and are therefore reserved for the rest of the
  29 ; program).  In all cases, routines are called with CALL or RCALL or
  30 ; the equivalent, and routines are allowed to have subroutines (ie, to
  31 ; use the call/return address stack).
  32
  33 ; Slave numbers (PIC numbers) are the actual PIC number, not the i2c
  34 ; address.  So, they start at 1 for the first slave.  (PIC #0 is the
  35 ; master but the master doesn't have an i2c address and its PIC number
  36 ; is never required by or supplied to i2clib.)
  37 ; They must be between 1 and 63 inclusive.
  38
  39 ; i2c?_... routines except i2c?_interrupt will never _directly_ call
  40 ; any i2c?u_... routine; when we say `causes' this means that the
  41 ; relevant i2c?u_... routine will be called at some later point from
  42 ; i2c?_interrupt.  i2c?u_... routines are allowed to call appropriate
  43 ; i2c?_... routines (except i2c?_interrupt) directly if the context
  44 ; and State allows.
  45
  46 ; All routines except i2c?_init must be called only:
  47 ;   * During an appropriate interrupt (high-priority for the slave;
  48 ;     low-priority for the master).
  49 ;   * From the main loop with those interrupts disabled; or
  50 ;   * From within an i2c?u_... routine (which are always called
  51 ;     from within i2c?_interrupt).
  52 ; This is to avoid having one i2c_... routine running in an interrupt
  53 ; which interrupted the middle of another i2c_... routine.
  54
  55 ; Some time between calling i2cs_init and waiting for the first event,
  56 ; the main program should of course enable interrupts.
  57
  58 ;============================================================
  59 ; COMMON ADMINISTRATIVE ROUTINES
  60
  61 ;--------------------
  62   extern i2cm_init
  63 ;
  64 ; Initialises the i2c system for use by a master PIC.  Must be called
  65 ; exactly once, which must be before any other i2c?_... function.
  66 ;                               At call                 On return
  67 ;   i2c controller              any                     for use by i2clib
  68 ;   i2c interrupt config        any                     enabled, low priority
  69 ;   global interrupt enable     disabled                unchanged
  70 ;   State                       Not-in-use              Idle (as master)
  71
  72 ;--------------------
  73   extern i2cs_init
  74 ;
  75 ; Initialises the i2c system for use by a slave PIC.  Must be called
  76 ; exactly once, which must be before any other i2c?_... function.
  77 ; W is the slave number.
  78 ;                               At call                 On return
  79 ;   i2c controller              any                     for use by i2clib
  80 ;   i2c interrupt config        any                     enabled, low priority
  81 ;   global interrupt enable     disabled                unchanged
  82 ;   State                       Not-in-use              Idle (as slave)
  83 ;   W                           slave number            any
  84
  85 ;--------------------
  86   extern i2cm_interrupt
  87   extern i2cm_interrupt_definite
  88   extern i2cs_interrupt
  89 ;
  90 ; Must be called by the main program's interrupt handler;
  91 ; high-priority for the slave or low-priority for the master.
  92 ;
  93 ; For i2cm_interrupt, the main program's interrupt handler is
  94 ; responsible for saving W and the flags register and other
  95 ; interrupt-related administrivia.  i2cm_interrupt checks for
  96 ; SSPIF and handles any interrupt.  i2cm_interrupt_definite
  97 ; should only be called if SSPIF is set and handles it.  In
  98 ; both cases the ISR returns with `return'.
  99 ;
 100 ; For i2cs_interrupt, it must be the only high-priority interrupt
 101 ; source and expects to be called from the interrupt handler (and it
 102 ; will return; the caller must retfie_r).
 103 ;
 104 ; If there is an i2c interrupt, the i2c?_interrupt will service it, taking
 105 ; any necessary action including calling appropriate
 106 ; i2c?u_... routines, and clear the interrupt flag[*].
 107 ;
 108 ;                               At call                 On return
 109 ;   State                       any except Not-in-use   may change
 110 ;   i2c interrupt state         any                     cleared[*]
 111 ;
 112 ; [*] The interrupt event on entry, if any, will be dealt with.  If
 113 ; interrupt processing takes a long time, another interrupt will occur
 114 ; and this may result in the i2c interrupt flag being set on return
 115 ; from i2c?_interrupt.
 116
 117
 118 ;======================================================================
 119 ; MASTER
 120 ;
 121 ; States:
 122 ;                       [Not-in-use]
 123 ;                            |
 124 ;                            |init
 125 ;                            v
 126 ;                          [Idle]<-------------------------<------.
 127 ;                           / \                                   |
 128 ;                          / _ \ _____________________<______     |
 129 ;                         /,'   \                            `.   |
 130 ;             write_start//      \read_start                  |   |
 131 ;                       //        \  ,------------------<---. |   |
 132 ;                      //          \ |                      | |   |
 133 ;                     VV            VV                      | |   |
 134 ;            [Writing-Setup]    [Reading-Busy]<---------.   | |   |
 135 ;                   |                 |                 |   | |   |
 136 ;    write_next_byte|                 |read_got_byte    |   | |   |
 137 ;    must return NZ |                 |                 |   | |   |
 138 ;                   V                 V                 |   | |   |
 139 ;           ,-->[Writing]         [Reading-Wait]        |   | |   |
 140 ;           `-------'  \            / ||  `.___________,'   | |   |
 141 ;    write_next_byte    \          /  ||   read_another     | |   |
 142 ;       returns NZ       |        /   ||                    | |   |
 143 ;                        |       /    |`.__________________,' |   |
 144 ;                        |      |     |        read_start     |   |
 145 ;         write_next_byte|      |     `._____________________,'   |
 146 ;             returns Z  |      |               write_start       |
 147 ;                        |      |read_done                        |
 148 ;                        V      V                                 |
 149 ;                       [Stopping]                                |
 150 ;                           |           done                      |
 151 ;                           `-------------------------------------'
 152
 153 ;--------------------
 154   extern i2cmu_done
 155
 156 ; Called to notify that the previous conversation with the slave has
 157 ; been finished as requested.  The i2c system is now available and
 158 ; i2cm_*_start can be called.
 159 ;
 160 ; (Note: If this arrangment means that main program ends up needing to
 161 ; keep track of whether the I2C is Idle or not, it would probably be
 162 ; straightforward to enhance the interface to be enhanced to make that
 163 ; unnecessary, since this information is already tracked by i2clib.)
 164 ;
 165 ;               Beforehand      At call
 166 ;   State       Stopping        Idle
 167
 168 ;========================================
 169 ; MASTER - WRITES (ie, transmission of data to the slave)
 170
 171 ;--------------------
 172   extern i2cm_write_start
 173 ;
 174 ; Requests that a slave be contacted for writing.  When communication
 175 ; has been established, i2cmu_write_next_byte will be called.
 176 ;
 177 ;                               At call         On return
 178 ;   State                    Idle/Reading-Wait  Writing-Setup
 179 ;   W                           slave number    any
 180
 181   extern i2cmu_write_next_byte
 182 ;
 183 ; Called to notify the main program that we are now ready to transmit
 184 ; a byte to the slave that we're currently talking to.  This may be
 185 ; either because i2cm_write_start was previously called and
 186 ; communication has been established, or because tranmission of the
 187 ; previous byte is complete.
 188 ;
 189 ; The main program must immediately supply the actual data byte.  This
 190 ; byte will then be transmitted to the slave, and then
 191 ; i2cmu_write_next_byte will be called again.
 192
 193 ; Alternatively the main program may indicate that the tranmission
 194 ; should finish by setting the Z flag on return.  In this case the
 195 ; slave will be told that this is the end of the message and the i2c
 196 ; conversation will be finished.  When the conversation is finished
 197 ; and the bus and i2c controller are free again, i2cmu_done will be
 198 ; called.
 199 ;
 200 ;  When transmission should continue:
 201 ;
 202 ;               Beforehand      At call         On return       After return
 203 ;   State       Writing[-Setup] Writing         Writing         Writing
 204 ;   Status Z                    any             0 (NZ, not zero, not equal)
 205 ;   W                           any             data for slave
 206 ;
 207 ;  When transmission should finish:
 208 ;
 209 ;               Beforehand      At call         On return       After return
 210 ;   State       Writing         Writing         Writing         Stopping
 211 ;   Status Z                    any             1 (Z, zero, equal)
 212 ;   W                           any             any
 213
 214 ;========================================
 215 ; MASTER - READS (ie, reception of data from the slave)
 216
 217 ;--------------------
 218   extern i2cm_read_start
 219 ;
 220 ; Requests that a slave be contacted for reading.  When communication
 221 ; has been established and the first byte received,
 222 ; i2cmu_read_got_byte will be called.
 223 ;
 224 ;                               At call         On return
 225 ;   State                    Idle/Reading-Wait  Reading-Busy
 226 ;   W                           slave number    any
 227
 228   extern i2cmu_read_got_byte
 229 ;
 230 ; Called to notify the main program that a byte has been recieved from
 231 ; the slave PIC.  The byte value is supplied.  Communication with the
 232 ; slave will be suspended (with the i2c bus blocked) until the main
 233 ; program calls i2cm_read_another or i2cm_read_done.  The main program
 234 ; must call one of these two before doing anything else with the i2c.
 235 ;
 236 ;               Beforehand      At call
 237 ;   State       Reading         Reading-Wait
 238 ;   W                           data from slave
 239
 240   extern i2cm_read_another
 241 ;
 242 ; Requests that the communication with the slave continue and another
 243 ; byte be read.  When this is complete, i2cmu_read_got_byte will be
 244 ; called.
 245 ;
 246 ;                               At call         On return
 247 ;   State                       Reading-Wait    Reading-Busy
 248
 249   extern i2cm_read_done
 250 ;
 251 ; Requests that reading from the slave be terminated.  When the
 252 ; conversation is finished and the bus and i2c controller are free
 253 ; again, i2cmu_done will be called.
 254 ;
 255 ;                               At call         On return
 256 ;   State                       Reading-Wait    Stopping
 257
 258
 259 ;======================================================================
 260 ; SLAVE
 261 ;
 262 ; States:
 263 ;
 264 ;                   [Not-in-use]
 265 ;                        |
 266 ;                        |init
 267 ;                        |
 268 ;                        V
 269 ;                      [Idle]
 270 ;                        |
 271 ;                        |<----------------------------.
 272 ;                        +                             |
 273 ;                       / \                            |
 274 ;                      /   \                           |
 275 ;          write_begin/     \read_begin                |
 276 ;                    /       \                         |
 277 ;                   V         V                        |
 278 ;       ,->[Receiving]      [Transmit-Wait]<-.         |
 279 ;       `-----'     |         |              |         |
 280 ;     write_data    |         |read_data     |         |
 281 ;                   |         V              |         |
 282 ;                   |       [Transmit-Busy]  |         |
 283 ;                   |         |       `------'         |
 284 ;                   |         |        read_another    |
 285 ;                   |         \                        |
 286 ;                   `----------+->---------------------'
 287
 288 ;========================================
 289 ; SLAVE - WRITES (ie, reception of data from the master)
 290
 291 ;--------------------
 292   extern i2csu_write_begin
 293 ;
 294 ; Called to notify the main program that the master PIC has selected this
 295 ; slave to talk to, for writing.  There is no data at this stage; when
 296 ; data is received, i2csu_write_data will be called.
 297 ;
 298 ;               Beforehand      At call                 On return
 299 ;   State       Idle            Receiving               Receiving
 300
 301 ;--------------------
 302   extern i2csu_write_data
 303 ;
 304 ; Called to notify the main program that the master PIC has
 305 ; transmitted a byte of data.  Provides the byte we received.
 306 ;
 307 ;               Beforehand      At call                 On return
 308 ;   State       Receiving       Receiving               Receiving
 309 ;   W                           data from master        any
 310
 311 ;========================================
 312 ; SLAVE - READS (ie, transmission of data to the master)
 313
 314 ;--------------------
 315   extern i2csu_read_begin
 316 ;
 317 ; Called to notify the main program that the master PIC has selected
 318 ; this slave to talk to, for reading.  The main program should invoke
 319 ; i2cs_read_data with first byte of data that we should transmit to
 320 ; the master.
 321 ;
 322 ;               Beforehand      At call
 323 ;   State       Idle            Transmit-Wait
 324
 325 ;--------------------
 326   extern i2cs_read_data
 327 ; Transmits the byte of data to the master
 328 ;
 329 ;               Beforehand      At call                 On return
 330 ;   State       Transmit-Wait   Transmit-Busy           Transmit-Busy
 331 ;   W                           byte for master         any
 332 ;
 333 ; There is also a macro  i2cs_read_data_macro
 334 ; in i2clib.incm, which does the same thing.
 335
 336 ;--------------------
 337   extern i2csu_read_another
 338 ;
 339 ; Called to notify the main program that the master PIC has continued
 340 ; by asking for another byte of data.  The main program should once
 341 ; more invoke i2cs_read_data.
 342 ;
 343 ;               Beforehand      At call
 344 ;   State       Transmit-Busy   Transmit-Wait