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