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 a low-priority interrupt;
  48 ;   * From the main loop with low-priority interrupts disabled; or
  49 ;   * From within an i2c?u_... routine (which are always called
  50 ;     from within i2c?_interrupt).
  51 ; This is to avoid having one i2c_... routine running in an interrupt
  52 ; which interrupted the middle of another i2c_... routine.
  53
  54 ; Some time between calling i2cs_init and waiting for the first event,
  55 ; the main program should of course enable interrupts.
  56
  57 ;============================================================
  58 ; COMMON ADMINISTRATIVE ROUTINES
  59
  60 ;--------------------
  61 extern i2cm_init
  62 ;
  63 ; Initialises the i2c system for use by a master PIC.  Must be called
  64 ; exactly once, which must be before any other i2c?_... function.
  65 ;                               At call                 On return
  66 ;   i2c controller              any                     for use by i2clib
  67 ;   i2c interrupt config        any                     enabled, low priority
  68 ;   global interrupt enable     disabled                unchanged
  69 ;   State                       Not-in-use              Idle
  70
  71 ;--------------------
  72 extern i2cs_init
  73 ;
  74 ; Initialises the i2c system for use by a slave PIC.  Must be called
  75 ; exactly once, which must be before any other i2c?_... function.
  76 ; W is the slave number.
  77 ;                               At call                 On return
  78 ;   i2c controller              any                     for use by i2clib
  79 ;   i2c interrupt config        any                     enabled, low priority
  80 ;   global interrupt enable     disabled                unchanged
  81 ;   State                       Not-in-use              Idle
  82 ;   W                           slave number            any
  83
  84 extern i2cs_interrupt
  85 extern i2cm_interrupt
  86 ;
  87 ; Must be called by the main program's low priority interrupt handler.
  88 ; The main program's interrupt handler is responsible for saving W and
  89 ; the flags register and other interrupt-related administrivia.  If
  90 ; there is an i2c interrupt, this routine will service it, taking any
  91 ; necessary action including calling appropriate i2c?u_... routines,
  92 ; and clear the interrupt flag[*].
  93 ;
  94 ;                               At call                 On return
  95 ;   State                       any except Not-in-use   may change
  96 ;   i2c interrupt state         any                     cleared[*]
  97 ;
  98 ; [*] The interrupt event on entry, if any, will be dealt with.  If
  99 ; interrupt processing takes a long time, another interrupt will occur
 100 ; and this may result in the i2c interrupt flag being set on return
 101 ; from i2c?_inerrupt.
 102
 103
 104 ;======================================================================
 105 ; SLAVE
 106 ;
 107 ; States:
 108 ;
 109 ;                   [Not-in-use]
 110 ;                        |
 111 ;                        |init
 112 ;                        v
 113 ;                      [Idle]<-------------------------.
 114 ;           write_begin/    \                          |
 115 ;                     /      \read_begin               |
 116 ;                    V        V                        |
 117 ;        ,->[Receiving]      [Transmitting]<-.         |
 118 ;        `-----'     |             |  `------'         |
 119 ;    write_another   |             |   read_another    |
 120 ;                    |    read_done|                   |
 121 ;          write_done|             \                   |
 122                      `--------------+->----------------'
 123
 124 ;========================================
 125 ; SLAVE - WRITES (ie, reception of data from the master)
 126
 127 ;--------------------
 128 extern i2csu_write_begin
 129 ;
 130 ; Called to notify the main program that the master PIC has selected this
 131 ; slave to talk to, for writing.  Provides the first byte of data
 132 ; we received from the master PIC.
 133 ;
 134 ;               Beforehand      At call                 On return
 135 ;   State       Idle            Receiving               Receiving
 136 ;   W                           data from master        any
 137
 138 ;--------------------
 139 extern i2csu_write_another
 140 ;
 141 ; Called to notify the main program that the master PIC has continued
 142 ; by transmitting another byte of data.  Provides the byte we received.
 143 ;
 144 ;               Beforehand      At call                 On return
 145 ;   State       Receiving       Receiving               Receiving
 146 ;   W                           data from master        any
 147
 148 ;--------------------
 149 extern i2csu_write_done
 150 ;
 151 ; Called to notify the main program that the master PIC has stopped
 152 ; transmitting data (ie, finished the i2c conversation).
 153 ;
 154 ;               Beforehand      At call                 On return
 155 ;   State       Receiving       Idle
 156
 157 ;========================================
 158 ; SLAVE - READS (ie, transmission of data to the master)
 159
 160 ;--------------------
 161 extern i2csu_read_begin
 162 ;
 163 ; Called to notify the main program that the master PIC has selected
 164 ; this slave to talk to, for reading, and to obtain the first byte of
 165 ; data that we should transmit to the master.
 166 ;
 167 ;               Beforehand      At call                 On return
 168 ;   State       Idle            Transmitting            Transmitting
 169 ;   W                           any                     data for master
 170
 171 ;--------------------
 172 extern i2csu_read_another
 173 ;
 174 ; Called to notify the main program that the master PIC has continued
 175 ; by asking for another byte of data.  Must provide the byte.
 176 ;
 177 ;               Beforehand      At call                 On return
 178 ;   State       Transmitting    Transmitting            Transmitting
 179 ;   W                           any                     data for master
 180
 181 ;--------------------
 182 extern i2csu_read_done
 183 ;
 184 ; Called to notify the main program that the master PIC has stopped
 185 ; asking for data (ie, finished receiving).
 186 ;
 187 ;               Beforehand      At call                 On return
 188 ;   State       Transmitting    Idle
 189
 190 ;======================================================================
 191 ; MASTER
 192 ;
 193 ; States:
 194 ;                       [Not-in-use]
 195 ;                            |
 196 ;                            |init
 197 ;                            v
 198 ;                          [Idle]<-----------------------------.
 199 ;               write_start/    \                              |
 200 ;                         /      \                             |
 201 ;                        V        V                            |
 202 ;            [Writing-Setup]    [Reading-Busy]<---------.      |
 203 ;                   |                 |                 |      |
 204 ;    write_next_byte|                 |read_got_byte    |      |
 205 ;    must return NZ |                 |                 |      |
 206 ;                   V                 V                 |      |
 207 ;           ,-->[Writing]         [Reading-Wait]        |      |
 208 ;           `-------'  \            /     `-------------'      |
 209 ;    write_next_byte    \          /       read_another        |
 210 ;       returns NZ       |        /                            |
 211 ;                        |       /read_done                    |
 212 ;         write_next_byte|      |                              |
 213 ;             returns Z  |      |                              |
 214 ;                        V      V                              |
 215 ;                       [Stopping]                             |
 216 ;                           |           done                   |
 217 ;                           `----------------------------------'
 218
 219 ;--------------------
 220 extern i2cmu_done
 221
 222 ; Called to notify that the previous conversation with the slave has
 223 ; been finished as requested.  The i2c system is now available and
 224 ; i2cm_*_start can be called.
 225 ;
 226 ;               Beforehand      At call
 227 ;   State       Stopping        Idle
 228
 229 ;========================================
 230 ; MASTER - WRITES (ie, transmission of data to the slave)
 231
 232 ;--------------------
 233 extern i2cm_write_start
 234 ;
 235 ; Requests that a slave be contacted for writing.  When communication
 236 ; has been established, i2cmu_write_next_byte will be called.
 237 ;
 238 ;                               At call         On return
 239 ;   State                       Idle            Writing-Setup
 240 ;   W                           slave number    any
 241
 242 extern i2cmu_write_next_byte
 243 ;
 244 ; Called to notify the main program that we are now ready to transmit
 245 ; a byte to the slave that we're currently talking to.  This may be
 246 ; either because i2cm_write_start was previously called and
 247 ; communication has been established, or because tranmission of the
 248 ; previous byte is complete.
 249 ;
 250 ; The main program must immediately supply the actual data byte.  This
 251 ; byte will then be transmitted to the slave, and then
 252 ; i2cmu_write_next_byte will be called again.
 253
 254 ; Alternatively the main program may indicate that the tranmission
 255 ; should finish by setting the Z flag on return.  In this case the
 256 ; slave will be told that this is the end of the message and the i2c
 257 ; conversation will be finished.  When the conversation is finished
 258 ; and the bus and i2c controller are free again, i2cmu_done will be
 259 ; called.
 260 ;
 261 ;  When transmission should continue:
 262 ;
 263 ;               Beforehand      At call         On return       After return
 264 ;   State       Writing[-Setup] Writing         Writing         Writing
 265 ;   Status Z                    any             0 (NZ, not zero, not equal)
 266 ;   W                           any             data for slave
 267 ;
 268 ;  When transmission should finish:
 269 ;
 270 ;               Beforehand      At call         On return       After return
 271 ;   State       Writing         Writing         Writing         Stopping
 272 ;   Status Z                    any             1 (Z, zero, equal)
 273 ;   W                           any             any
 274
 275 ;========================================
 276 ; MASTER - READS (ie, reception of data from the slave)
 277
 278 ;--------------------
 279 extern i2cm_read_start
 280 ;
 281 ; Requests that a slave be contacted for reading.  When communication
 282 ; has been established and the first byte received,
 283 ; i2cmu_read_got_byte will be called.
 284 ;
 285 ;                               At call         On return
 286 ;   State                       Idle            Reading-Busy
 287 ;   W                           slave number    any
 288
 289 extern i2cmu_read_got_byte
 290 ;
 291 ; Called to notify the main program that a byte has been recieved from
 292 ; the slave PIC.  The byte value is supplied.  Communication with the
 293 ; slave will be suspended (with the i2c bus blocked) until the main
 294 ; program calls i2cm_read_another or i2cm_read_done.  The main program
 295 ; must call one of these two before doing anything else with the i2c.
 296 ;
 297 ;               Beforehand      At call
 298 ;   State       Reading         Reading-Wait
 299 ;   W                           data from slave
 300
 301 extern i2cm_read_another
 302 ;
 303 ; Requests that the communication with the slave continue and another
 304 ; byte be read.  When this is complete, i2cmu_read_got_byte will be
 305 ; called.
 306 ;
 307 ;                               At call         On return
 308 ;   State                       Reading-Wait    Reading-Busy
 309
 310 extern i2cm_read_done
 311 ;
 312 ; Requests that reading from the slave be terminated.  When the
 313 ; conversation is finished and the bus and i2c controller are free
 314 ; again, i2cmu_done will be called.
 315 ;
 316 ;                               At call         On return
 317 ;   State                       Reading-Wait    Stopping
 318
 319 ;======================================================================