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 i2cm_interrupt_definite
  92   extern i2cs_interrupt
  93 ;
  94 ; Must be called by the main program's interrupt handler;
  95 ; high-priority for the slave or low-priority for the master.
  96 ;
  97 ; For i2cm_interrupt, the main program's interrupt handler is
  98 ; responsible for saving W and the flags register and other
  99 ; interrupt-related administrivia.  i2cm_interrupt checks for
 100 ; SSPIF and handles any interrupt.  i2cm_interrupt_definite
 101 ; should only be called if SSPIF is set and handles it.  In
 102 ; both cases the ISR returns with `return'.
 103 ;
 104 ; For i2cs_interrupt, it must be the only high-priority interrupt
 105 ; source and expects to be called from the interrupt handler (and it
 106 ; will return; the caller must retfie_r).
 107 ;
 108 ; If there is an i2c interrupt, the i2c?_interrupt will service it, taking
 109 ; any necessary action including calling appropriate
 110 ; i2c?u_... routines, and clear the interrupt flag[*].
 111 ;
 112 ;                               At call                 On return
 113 ;   State                       any except Not-in-use   may change
 114 ;   i2c interrupt state         any                     cleared[*]
 115 ;
 116 ; [*] The interrupt event on entry, if any, will be dealt with.  If
 117 ; interrupt processing takes a long time, another interrupt will occur
 118 ; and this may result in the i2c interrupt flag being set on return
 119 ; from i2c?_interrupt.
 120
 121
 122 ;======================================================================
 123 ; MASTER
 124 ;
 125 ; States:
 126 ;                       [Not-in-use]
 127 ;                            |
 128 ;                            |init
 129 ;                            v
 130 ;                          [Idle]<-------------------------<------.
 131 ;                           / \                                   |
 132 ;                          / _ \ _____________________<______     |
 133 ;                         /,'   \                            `.   |
 134 ;             write_start//      \read_start                  |   |
 135 ;                       //        \  ,------------------<---. |   |
 136 ;                      //          \ |                      | |   |
 137 ;                     VV            VV                      | |   |
 138 ;            [Writing-Setup]    [Reading-Busy]<---------.   | |   |
 139 ;                   |                 |                 |   | |   |
 140 ;    write_next_byte|                 |read_got_byte    |   | |   |
 141 ;    must return NZ |                 |                 |   | |   |
 142 ;                   V                 V                 |   | |   |
 143 ;           ,-->[Writing]         [Reading-Wait]        |   | |   |
 144 ;           `-------'  \            / ||  `.___________,'   | |   |
 145 ;    write_next_byte    \          /  ||   read_another     | |   |
 146 ;       returns NZ       |        /   ||                    | |   |
 147 ;                        |       /    |`.__________________,' |   |
 148 ;                        |      |     |        read_start     |   |
 149 ;         write_next_byte|      |     `._____________________,'   |
 150 ;             returns Z  |      |               write_start       |
 151 ;                        |      |read_done                        |
 152 ;                        V      V                                 |
 153 ;                       [Stopping]                                |
 154 ;                           |           done                      |
 155 ;                           `-------------------------------------'
 156
 157 ;--------------------
 158   extern i2cmu_done
 159
 160 ; Called to notify that the previous conversation with the slave has
 161 ; been finished as requested.  The i2c system is now available and
 162 ; i2cm_*_start can be called.
 163 ;
 164 ; (Note: If this arrangment means that main program ends up needing to
 165 ; keep track of whether the I2C is Idle or not, it would probably be
 166 ; straightforward to enhance the interface to be enhanced to make that
 167 ; unnecessary, since this information is already tracked by i2clib.)
 168 ;
 169 ;               Beforehand      At call
 170 ;   State       Stopping        Idle
 171
 172 ;========================================
 173 ; MASTER - WRITES (ie, transmission of data to the slave)
 174
 175 ;--------------------
 176   extern i2cm_write_start
 177 ;
 178 ; Requests that a slave be contacted for writing.  When communication
 179 ; has been established, i2cmu_write_next_byte will be called.
 180 ;
 181 ;                               At call         On return
 182 ;   State                    Idle/Reading-Wait  Writing-Setup
 183 ;   W                           slave number    any
 184
 185   extern i2cmu_write_next_byte
 186 ;
 187 ; Called to notify the main program that we are now ready to transmit
 188 ; a byte to the slave that we're currently talking to.  This may be
 189 ; either because i2cm_write_start was previously called and
 190 ; communication has been established, or because tranmission of the
 191 ; previous byte is complete.
 192 ;
 193 ; The main program must immediately supply the actual data byte.  This
 194 ; byte will then be transmitted to the slave, and then
 195 ; i2cmu_write_next_byte will be called again.
 196
 197 ; Alternatively the main program may indicate that the tranmission
 198 ; should finish by setting the Z flag on return.  In this case the
 199 ; slave will be told that this is the end of the message and the i2c
 200 ; conversation will be finished.  When the conversation is finished
 201 ; and the bus and i2c controller are free again, i2cmu_done will be
 202 ; called.
 203 ;
 204 ;  When transmission should continue:
 205 ;
 206 ;               Beforehand      At call         On return       After return
 207 ;   State       Writing[-Setup] Writing         Writing         Writing
 208 ;   Status Z                    any             0 (NZ, not zero, not equal)
 209 ;   W                           any             data for slave
 210 ;
 211 ;  When transmission should finish:
 212 ;
 213 ;               Beforehand      At call         On return       After return
 214 ;   State       Writing         Writing         Writing         Stopping
 215 ;   Status Z                    any             1 (Z, zero, equal)
 216 ;   W                           any             any
 217
 218 ;========================================
 219 ; MASTER - READS (ie, reception of data from the slave)
 220
 221 ;--------------------
 222   extern i2cm_read_start
 223 ;
 224 ; Requests that a slave be contacted for reading.  When communication
 225 ; has been established and the first byte received,
 226 ; i2cmu_read_got_byte will be called.
 227 ;
 228 ;                               At call         On return
 229 ;   State                    Idle/Reading-Wait  Reading-Busy
 230 ;   W                           slave number    any
 231
 232   extern i2cmu_read_got_byte
 233 ;
 234 ; Called to notify the main program that a byte has been recieved from
 235 ; the slave PIC.  The byte value is supplied.  Communication with the
 236 ; slave will be suspended (with the i2c bus blocked) until the main
 237 ; program calls i2cm_read_another or i2cm_read_done.  The main program
 238 ; must call one of these two before doing anything else with the i2c.
 239 ;
 240 ;               Beforehand      At call
 241 ;   State       Reading         Reading-Wait
 242 ;   W                           data from slave
 243
 244   extern i2cm_read_another
 245 ;
 246 ; Requests that the communication with the slave continue and another
 247 ; byte be read.  When this is complete, i2cmu_read_got_byte will be
 248 ; called.
 249 ;
 250 ;                               At call         On return
 251 ;   State                       Reading-Wait    Reading-Busy
 252
 253   extern i2cm_read_done
 254 ;
 255 ; Requests that reading from the slave be terminated.  When the
 256 ; conversation is finished and the bus and i2c controller are free
 257 ; again, i2cmu_done will be called.
 258 ;
 259 ;                               At call         On return
 260 ;   State                       Reading-Wait    Stopping
 261
 262
 263 ;======================================================================
 264 ; SLAVE
 265 ;
 266 ; States:
 267 ;
 268 ;                   [Not-in-use]
 269 ;                        |
 270 ;                        |init
 271 ;                        |
 272 ;                        V
 273 ;                      [Idle]
 274 ;                        |
 275 ;                        |<----------------------------.
 276 ;                        +                             |
 277 ;                       / \                            |
 278 ;                      /   \                           |
 279 ;          write_begin/     \read_begin                |
 280 ;                    /       \                         |
 281 ;                   V         V                        |
 282 ;       ,->[Receiving]      [Transmit-Wait]<-.         |
 283 ;       `-----'     |         |              |         |
 284 ;     write_data    |         |read_data     |         |
 285 ;                   |         V              |         |
 286 ;                   |       [Transmit-Busy]  |         |
 287 ;                   |         |       `------'         |
 288 ;                   |         |        read_another    |
 289 ;                   |         \                        |
 290 ;                   `----------+->---------------------'
 291
 292 ;========================================
 293 ; SLAVE - WRITES (ie, reception of data from the master)
 294
 295 ;--------------------
 296   extern i2csu_write_begin
 297 ;
 298 ; Called to notify the main program that the master PIC has selected this
 299 ; slave to talk to, for writing.  There is no data at this stage; when
 300 ; data is received, i2csu_write_data will be called.
 301 ;
 302 ;               Beforehand      At call                 On return
 303 ;   State       Idle            Receiving               Receiving
 304
 305 ;--------------------
 306   extern i2csu_write_data
 307 ;
 308 ; Called to notify the main program that the master PIC has
 309 ; transmitted a byte of data.  Provides the byte we received.
 310 ;
 311 ;               Beforehand      At call                 On return
 312 ;   State       Receiving       Receiving               Receiving
 313 ;   W                           data from master        any
 314
 315 ;========================================
 316 ; SLAVE - READS (ie, transmission of data to the master)
 317
 318 ;--------------------
 319   extern i2csu_read_begin
 320 ;
 321 ; Called to notify the main program that the master PIC has selected
 322 ; this slave to talk to, for reading.  The main program should invoke
 323 ; i2cs_read_data with first byte of data that we should transmit to
 324 ; the master.
 325 ;
 326 ;               Beforehand      At call
 327 ;   State       Idle            Transmit-Wait
 328
 329 ;--------------------
 330   extern i2cs_read_data
 331 ; Transmits the byte of data to the master
 332 ;
 333 ;               Beforehand      At call                 On return
 334 ;   State       Transmit-Wait   Transmit-Busy           Transmit-Busy
 335 ;   W                           byte for master         any
 336 ;
 337 ; There is also a macro  i2cs_read_data_macro
 338 ; in i2clib.incm, which does the same thing.
 339
 340 ;--------------------
 341   extern i2csu_read_another
 342 ;
 343 ; Called to notify the main program that the master PIC has continued
 344 ; by asking for another byte of data.  The main program should once
 345 ; more invoke i2cs_read_data.
 346 ;
 347 ;               Beforehand      At call
 348 ;   State       Transmit-Busy   Transmit-Wait