detpic/common.inc

   1 ;======================================================================
   2 ; common.inc
   3 ; common macros & equs etc.
   4 ; generally include this at the top of each file.
   5
   6 ;----------------------------------------------------------------------
   7 ; COMMON INCLUDES and BOILERPLATE
   8         include         p18f458.inc
   9         radix           dec
  10         include         panic.inc
  11         include         morse+auto.inc
  12         include         ../iwjpictest/insn-aliases.inc
  13         include         ../iwjpictest/clockvaries.inc
  14         include         variables+vars.inc
  15         include         pindata.inc
  16         include         program+clocks.inc
  17         include         i2clib.incm
  18
  19 tickdiv equ 16
  20 tickdiv_us equ tick_us * tickdiv
  21
  22 ;----------------------------------------------------------------------
  23 ; Common conventions for function register notation:
  24
  25 ;                       Master                  Slave
  26 ; Registers etc.
  27 ;   W                   Trashed                 Trashed
  28 ;   STATUS              Trashed                 Trashed
  29 ;   BSR                 Not used                Not used
  30 ;   t,u,v               Low ISR                 Low ISR
  31 ;   TBLPTR*,TABLAT      Low ISR                 Low ISR
  32 ;   PROD*               Low ISR                 Low ISR
  33 ;   FSR0                Low ISR                 Low ISR
  34 ;   PCLATU              Always set to 0         Not used
  35 ;   PCLATH              Low ISR                 Not used
  36 ;   t_dolocal           Low ISR                 High ISR
  37 ;   FSR1                Low ISR                 High ISR (detect[1])
  38 ;   FSR2                High ISR (nmra[1])      High ISR (detect[1])
  39 ;
  40 ;   Main loop           detection scan          detection scan
  41 ;   High ISR            NMRA output             I2C service
  42 ;   Low ISRs            everything else         everything else
  43 ;
  44 ; Trashed       May be trashed by any routine anywhere.  Saved
  45 ;               during every ISR entry/exit.
  46 ;
  47 ; Low ISR       May be used/trashed by any routine run in low-priority
  48 ;               interrupt, or any routine run during initialisation.
  49 ;               May therefore not be used in background loop with
  50 ;               interrupts enabled.  May not be used by high-priority
  51 ;               ISR (unless explicitly saved, eg isrh_fsr0_{save,restore}).
  52 ;
  53 ; High ISR      May be used/trashed by any routine run in high-priority
  54 ;               interrupt, or any routine run during initialisation.
  55 ;               May therefore not be used elsewhere with interrupts
  56 ;               enabled.
  57 ;
  58 ;               Only the routines specially noted as intended to
  59 ;               be called from the High ISR are safe.
  60 ;
  61 ; ... (subsystem)
  62 ;               Register is reserved for use by this subsystem, which
  63 ;               is allowed to expect the value to be preserved.
  64 ;               Anything else which uses it must save and restore (and
  65 ;               may also need to disable interrupts, depending on its
  66 ;               relative status).
  67 ;
  68 ; Not High      May be used by any routine not running in high-priority
  69 ;               interrupt.  Not saved by high-priority interrupt
  70 ;               entry/exit, so any high-priority interrupt routine which
  71 ;               uses this register must save and restore it.
  72 ;
  73 ; A routine which is allowed to trash a register may document that it
  74 ; saves that register for the benefit of its callers.
  75 ;
  76 ;  [1]  FSR1 and FSR2 on slave pics are reserved exclusively for the
  77 ;       I2C response and detection code (detect.asm), after
  78 ;       detect_slave_init.  Likewise FSR2 is reserved exclusively
  79 ;       for the NMRA output ISR after nmra_init.
  80 ;
  81 ; General-purpose hardware allocation:
  82 ;
  83 ;                       Master                  Slave
  84 ;  Timer 0              nmra                    Disabled
  85 ;  Timer 2              tick, int. low          -
  86 ;  Timer 1              -                       -
  87 ;  CCP1                 -                       -
  88 ;  Timer 3              point fire timer        point fire timer
  89 ;  ECCP                 -                       -
  90 ;
  91 ;   (...) indicates that this is a projected use, NYI
  92
  93 ;----------------------------------------------------------------------
  94 ; Conventional routine names:
  95 ;
  96 ; <periph>_local_do     Process a master-to-slave command to activate
  97 ;                       a local peripheral, in High ISR.  Also called
  98 ;                       on master in Low ISR to activate its own
  99 ;                       local peripherals.  NB strange calling convention!
 100 ;
 101 ; <periph>_local_init   Initialises RAM tables for local peripheral
 102 ;                       and arranges for pins to be set in appropriate
 103 ;                       quiescent state.  Configures pic built-in
 104 ;                       peripherals.
 105 ;
 106 ; <periph>_local_intrl  Low ISR service routine for peripheral (see below).
 107 ;
 108 ; command_<periph>      Called when an appropriate message has been
 109 ;                       received from the host.
 110 ;
 111 ; <something>_intrl     Low ISR service routine.
 112 ;                       Checks for any relevant interrupt.
 113 ;                       If not, just returns.
 114 ;                       If found, services it and then does either
 115 ;                        intrl_handled or intrl_handled_nostack
 116 ;                        neither of which return; the latter is
 117 ;                        faster but implies a promise
 118 ;
 119 ;----------------------------------------------------------------------
 120 ; MACROS
 121
 122 @ macro
 123   endm
 124
 125 ;----------------------------------------
 126 ; For adding a byte to the debug buffer.
 127 ; Not for use in High ISR.  In all cases:
 128 ;
 129 ;  STATUS       any             trashed
 130 ;  all others   any             preserved
 131
 132   ifndef NDEBUG
 133 ;----------
 134 Dv macro  ; sorry, but assembler's dw directive isn't case-sensitive
 135 ;
 136 ;  W            message byte    preserved
 137 ;
 138         call    debugbyte
 139         endm
 140
 141 ;----------
 142 Dl macro debug_literal_value
 143 ;
 144 ;  W            any             literal value as specified
 145 ;
 146         mov_lw  debug_literal_value
 147         Dv
 148         endm
 149
 150 ;----------
 151 Df macro debug_register_file_address
 152 ;
 153 ;  W            any             value from specified memory location
 154 ;
 155         mov_fw  debug_register_file_address
 156         Dv
 157         endm
 158   else
 159 Dv macro
 160    endm
 161 Dl macro debug_literal_value
 162    endm
 163 Df macro debug_register_file_address
 164    endm
 165   endif
 166
 167 ;----------------------------------------
 168 ; For entering and leaving Low ISR, saving and restoring STATUS and W
 169 ; See above under <something>_intrl, and {master,slave}_interrupt_low
 170
 171 enter_interrupt_low macro
 172         mov_ff  STATUS, isr_low_save_status
 173         mov_wf  isr_low_save_w
 174         mov_ff  STKPTR, isr_low_save_stkptr
 175         endm
 176
 177 intrh_fsr0_save macro
 178         mov_ff  FSR0L, isr_high_save_fsr0
 179         mov_ff  FSR0H, isr_high_save_fsr0+1
 180         endm
 181
 182 intrh_fsr0_restore macro
 183         mov_ff  isr_high_save_fsr0,   FSR0L
 184         mov_ff  isr_high_save_fsr0+1, FSR0H
 185         endm
 186
 187 intrl_handled_core macro ; for internal use only
 188         mov_fw  isr_low_save_w
 189         mov_ff  isr_low_save_status, STATUS
 190         retfie
 191         endm
 192
 193 intrl_handled_nostack macro
 194         pop     ; undo the `call' from the original ISR
 195         intrl_handled_core
 196         endm
 197
 198 intrl_handled macro
 199         goto    intrl_handled_routine
 200         endm
 201
 202 ;----------------------------------------
 203 ; For disabling all interrupts, to make a critical section:
 204 ; (for use from main program and Low ISR only)
 205 ;
 206 ;  GIEH                 modified appropriately
 207 ;  everything else      preserved
 208
 209 intrh_mask macro
 210         bc_f    INTCON,GIEH
 211         endm
 212
 213 intrh_unmask macro
 214         bs_f    INTCON,GIEH
 215         endm
 216
 217 ;----------------------------------------
 218 ; For the fix specified in the silicon errata:
 219 ; silicon revision B4 issue 4
 220 ;
 221 ;                       Before          After
 222 ;  TABLAT               any             data from flash
 223 ;  TBLPTR*              correct         incremented/decremented
 224 ;  everything else      any             preserved
 225
 226 tblrd_postinc_fixup macro
 227         tblrd   *+
 228         dw      0xffff
 229         endm
 230
 231 tblrd_postdec_fixup macro
 232         tblrd   *-
 233         dw      0xffff
 234         endm
 235
 236 ;----------------------------------------
 237 ; For setting up TBLPTR
 238
 239 load_tblptr macro value
 240 ;
 241 ;                       Before          After
 242 ;  TBLPTR*              any             set
 243 ;  W, STATUS            any             undefined
 244 ;
 245         mov_lw  value & 0xff
 246         mov_wf  TBLPTRL
 247
 248         mov_lw  value >> 8
 249         mov_wf  TBLPTRH
 250
 251   if value > 0xffff
 252         mov_lw  value >> 16
 253         mov_wf  TBLPTRU
 254   else
 255         clr_f   TBLPTRU
 256   endif
 257         endm
 258
 259 load_perpic_tblptr macro flash_map_base, perpic_entry_size
 260 ;
 261 ;                       Before          After
 262 ;  TBLPTR*              any             set
 263 ;  W, STATUS, PROD*     any             undefined
 264 ;  everything else      any             preserved
 265 ;
 266         mov_lw  perpic_entry_size
 267         mul_wf  picno
 268
 269         mov_lw  flash_map_base & 0xff
 270         add_wfw PRODL
 271         mov_wf  TBLPTRL
 272
 273         mov_lw  flash_map_base >> 8
 274         addc_wfw PRODH
 275         mov_wf  TBLPTRH
 276
 277         clr_f   TBLPTRU         ; TBLPTR* -> our point data
 278         endm
 279
 280 ;----------------------------------------------------------------------
 281 ; PINSPECS stuff
 282 ;
 283 ; A PINSPEC is a constant 0x<bit><port> where <port> is a b c d e
 284 ; and <port> is 0 1 2 3 4 5 6 7.  Generally p<picno>_<subsystem>_<pin>
 285 ; are equ'd for this.
 286
 287   radix hex
 288 p0_cdu_enable           equ     5b
 289 p0_rs232_fcin           equ     4b
 290 p0_booster_shutdown     equ     2b
 291 p0_booster_overload     equ     1b
 292 p0_booster_userfault    equ     0b
 293 p0_spare2               equ     6d
 294 p0_spare1               equ     5d
 295 p0_rs232_fcout          equ     5c
 296 pall_perpicled          equ     2d
 297 pall_pt0reverse         equ     7b
 298 p0_spare0               equ     0a
 299 p0_booster_dirn         equ     0c
 300 p0_booster_pwm          equ     1c
 301   radix dec
 302
 303 ;
 304 ;  LAT*                 may be subject to read-modify-write, see below
 305 ;  TRIS*                may be subject to read-modify-write, see below
 306 ;  PORT*                may be read, see below
 307 ;  everything else      untouched
 308 ;
 309 ;                       LAT*<bit>       TRIS*<bit>      PORT*
 310 ;  pin_z                untouched       set             untouched
 311 ;  pin_h                set             cleared         untouched
 312 ;  pin_l                cleared         cleared         untouched
 313 ;  pin_nz               untouched       cleared         untouched
 314 ;  pin_vh               set             untouched       untouched
 315 ;  pin_vl               cleared         untouched       untouched
 316 ;  pin_ifh              untouched       untouched       read
 317 ;  pin_ifl              untouched       untouched       read
 318
 319 pin_z   macro   pinspec
 320         bs_f    TRISA + (TRISB-TRISA)*((pinspec-0xa) & 15), pinspec >> 4
 321         endm
 322
 323 pin_nz  macro   pinspec
 324         bc_f    TRISA + (TRISB-TRISA)*((pinspec-0xa) & 15), pinspec >> 4
 325         endm
 326
 327 pin_znz macro   pinspec
 328         btg_f   TRISA + (TRISB-TRISA)*((pinspec-0xa) & 15), pinspec >> 4
 329         endm
 330
 331 pin_vh  macro   pinspec
 332         bs_f    LATA + (LATB-LATA)*((pinspec-0xa) & 15), pinspec >> 4
 333         endm
 334
 335 pin_vl  macro   pinspec
 336         bc_f    LATA + (LATB-LATA)*((pinspec-0xa) & 15), pinspec >> 4
 337         endm
 338
 339 pin_vhl macro   pinspec
 340         btg_f   LATA + (LATB-LATA)*((pinspec-0xa) & 15), pinspec >> 4
 341         endm
 342
 343 pin_h   macro   pinspec
 344         pin_vh  pinspec
 345         pin_nz  pinspec
 346         endm
 347
 348 pin_l   macro   pinspec
 349         pin_vl  pinspec
 350         pin_nz  pinspec
 351         endm
 352
 353 pin_ifh macro   pinspec
 354         bt_f_if1 PORTA + (PORTB-PORTA)*((pinspec-0xa) & 15), pinspec >> 4
 355         endm
 356
 357 pin_ifl macro   pinspec
 358         bt_f_if0 PORTA + (PORTB-PORTA)*((pinspec-0xa) & 15), pinspec >> 4
 359         endm
 360
 361 pinlat_ifh macro        pinspec
 362         bt_f_if1 LATA + (LATB-LATA)*((pinspec-0xa) & 15), pinspec >> 4
 363         endm
 364
 365 pinlat_ifl      macro   pinspec
 366         bt_f_if0 LATA + (LATB-LATA)*((pinspec-0xa) & 15), pinspec >> 4
 367         endm
 368
 369 ;----------------------------------------------------------------------