detpic/i2clib.inc

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