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
 192
 193
 194 ; junky bits after here need turning into MASTER sections.
 195
 196
 197 ;
 198 ; i2cm_write_start
 199 ;       slave no.
 200 ;   causes
 201 ; i2cmu_write_next_byte
 202 ;       must return byte to transmit
 203 ;       must say whether to stop
 204 ;   stop causes
 205 ; i2cmu_done
 206 ;
 207 ; i2cm_read_start
 208 ;       slave no.
 209 ;   causes
 210 ; i2cmu_read_got_byte
 211 ;       byte value
 212 ;   causes
 213 ; i2cm_read_another or i2cm_read_done
 214 ;  causes               causes
 215 ;  i2cmu_done           i2cmu_done