avrprog-spi.mu4

| This file is part of muforth: https://muforth.dev/
|
| Copyright 2002-2024 David Frech. (Read the LICENSE for details.)

loading AVR programming over SPI

variable fuses  ( fuse at byte 0; hfuse @ 1; efuse @ 2)
variable locks  ( lock bits)

| comment %%
| We need to have loaded a "driver" that defines the following words:
|
|   avr.Hello
|   avr.Bye
|
|   avr.ResetHigh
|   avr.ResetLow
|
|   avr.SlowClock
|   avr.FastClock
|
|   avr.Read       ( avr-cmd addr data)  ( leaves result in pad)
|   avr.Write      ( avr-cmd addr data)
|   avr.BulkRead   ( avr-cmd addr toggle buf len)
|   avr.BulkWrite  ( avr-cmd addr toggle buf len)
| %%

.ifdef avr.Hello

hex

| Having loaded a simple driver that talks to either a serial-connected or
| USB-connected device that can talk SPI to an AVR target, load the bulk of
| the commands for talking to the target.

: avr2  ( cmd addr data - r2)  ( do command; return second-to-last byte of response)
   avr.Read  pad 2 + c@ ;

: avr3  ( cmd addr data - r3)  ( do command; return last byte of response)
   avr.Read  pad 3 + c@ ;

: us  #1000 *  ( ns)  0 swap  nanosleep ;
: ms  #1000 *  us ;

: +reset  avr.ResetLow   #100 ms ;
: -reset  avr.ResetHigh  #100 ms ;
: reset  avr.Hello  +reset -reset  avr.Bye ;

| Sets slow-clock! If you want fast-clock, you have to call it *after*
| +prog.

: +prog  ( enable programming)
   avr.Hello  avr.SlowClock
   4 for  +reset  0ac 53_00 0 avr2  53 = if  pop drop ^ then
          -reset  next
   ." Couldn't enable serial programming" ;

: -prog  ( disable programming)
   -reset  avr.Bye ;

: fast-clock
.ifndef spi-slow  avr.FastClock
.else             avr.SlowClock
.then             ;

: read-sig  ( - s0:s1:s2)
   30 2 0 avr3
   30 1 0 avr3
   30 0 0 avr3
   lohi>  lohi> ;

| NOTE: wait polling is *not* available on the mega8515. You have to simply
| delay instead. Also, the 8515 lacks an efuse, so let's reflect that here
| as well.

.ifdef mega8515

( 8515 doesn't have wait polling, so we have to delay instead.)

: wait-fuse     #4500 us ;  ( 4.5ms)
: wait-flash    #4500 us ;
: wait-eeprom   #9000 us ;  ( 9ms)
: wait-erase    #9000 us ;

( efuse doesn't exist on 8515)
: read-fuses  ( - fuses = fuse at byte 0; hfuse @ 1)
   50 00_00 0 avr3
   58 08_00 0 avr3  ( fuse hfuse)
   lohi> ;

: write-fuses  ( fuses = fuse at byte 0; hfuse @ 1)
   >hilo push  0ac 0a0_00  pop  avr.Write  ( write fuse bits)   wait-fuse
         push  0ac 0a8_00  pop  avr.Write  ( write hfuse bits)  wait-fuse ;

| Since the datasheet is silent on the topic of how long it takes to
| program the lock bits, we assume it's the same as writing the fuses.

: write-locks  ( locks)
   push  0ac 0e0_00  pop  avr.Write  wait-fuse ;

.else  ( everything but the 8515)

( Use wait polling.)
: ?busy
   begin  0f0 0 0 avr3  1 and  0= until ;

: wait-eeprom   ?busy ;
: wait-flash    ?busy ;
: wait-erase    ?busy ;

: read-fuses  ( - fuses = fuse at byte 0; hfuse @ 1; efuse @ 2)
   50 00_00 0 avr3
   58 08_00 0 avr3
   50 08_00 0 avr3  ( fuse hfuse efuse)
   lohi>  lohi> ;

: write-fuses  ( fuses = fuse at byte 0; hfuse @ 1; efuse @ 2)
   >hilo push  0ac 0a0_00  pop  avr.Write  ( write fuse bits)   ?busy
   >hilo push  0ac 0a8_00  pop  avr.Write  ( write hfuse bits)  ?busy
         push  0ac 0a4_00  pop  avr.Write  ( write efuse bits)  ?busy ;

: write-locks  ( locks)
   push  0ac 0e0_00  pop  avr.Write  ?busy ;

.then

: prog-fuses
   fuses @ =if  ( if fuses to program...)
      dup read-fuses xor if  ( ...and if different from chip's)
      cr  ." Writing fuses"
      write-fuses
   ^ then  then  drop ;

: read-locks  ( - locks)
   58 0 0 avr3 ;

: prog-locks
   locks @ =if  ( if locks to program...)
      dup read-locks xor if  ( ...and if different from chip's)
      cr  ." Writing lock bits"
      write-locks
   ^ then  then  drop ;

( This leaves the fuses alone but resets the lock bits.)
: erase-chip
   0ac 80_00 0 avr.Write  wait-erase ;


| Instead of reusing the memory dump's p pointer - the semantics of which
| are different than they were originally - let's create our own.

variable pp ( programming pointer - contains a target address)
: pp&  ( b)    pp @  image-c!  1 pp +! ;
: pp*  ( - b)  pp @  image-c@  1 pp +! ;

: pp-byte  ( - byte-addr)  pp @         ; ( pp, as byte pointer)
: pp-word  ( - word-addr)  pp @  u2/    ; ( pp, as word pointer)
: pp-host  ( - host-addr)  pp @  image+ ; ( pp, as host [image] pointer)


| Read just the first few kb of the chip. This is _really_ slow, and is
| mostly here to test that the fast code does the right thing. Both
| versions print a . for every 128 bytes read.

: read-flash-slowly
   flash  0ff fill-image  0 pp !
   +prog  fast-clock
   [ 1 Ki #64 / #] for
      #64 for  ( 64 words, 128 bytes)
         20  pp-word  0  avr3  pp&  ( read flash lo byte)
         28  pp-word  0  avr3  pp&  ( read flash hi byte)
      next  char . emit
   next
   -prog ;

| We read the chip in chunks, but the buffer size does not need to match
| the flash page size, and in fact this would fail for the mega644, since
| the page size is 256 bytes, but my USB code will break if asked for a
| buffer this size! So let's always read 128 byte chunks instead.

: read-flash
   flash  0ff fill-image  0 pp !
   [ #flash #128 / #] for
      20  pp-word  8  pp-host  #128  avr.BulkRead
      #128 pp +!
      char . emit
   next ;

: read-eeprom
   eeprom  0 fill-image  0 pp !
   [ #eeprom #128 / #] for  ( read in 128 byte chunks)
      0a0  pp-byte  0  pp-host  #128  avr.BulkRead
      #128 pp +!
      char . emit
   next ;

: read-eeprom-slowly
   eeprom  0 fill-image  0 pp !
   #eeprom for
      0a0  pp-byte  0  avr3  pp&
      char . emit
   next ;

: read-chip
   h preserve
   +prog  fast-clock
   read-flash  read-eeprom  read-fuses fuses !  read-locks locks !
   -prog ;

( This checks to see if the _image_, not the chip, is blank.)
: blank?
   0 pp !
   0ff  #image for  pp* and  next  0ff = ;

b/page 2/  constant w/page

| lo-addr is the _word_ offset within a flash page.
| hi-addr is the _word_ address of a flash page.
|
| Both hi-addr and lo-addr are broken into bytes - big-endian! - to send
| via SPI to the chip.

: lo-addr   pp-word  [ w/page 1-     #]  and ;
: hi-addr   pp-word  [ w/page negate #]  and ;

| NOTE: prog-region and prog-eeprom are _not_ standalone; they can only be
| called after prog mode is set and the SPI clock set properly.

: prog-region
   region  swap pp !  ( len)
   b/page 1- + ( round up)  b/page / for  ( program flash pages)
      cr ."    page "  pp-byte  u.
      40  lo-addr  8  pp-host  b/page  avr.BulkWrite
      4c  hi-addr  0                   avr.Write  wait-flash  ( program page)
      b/page pp +!
   next ;

: prog-flash
   cr  ." Writing application"  flash  prog-region
   cr  ." Writing bootloader"  boot  prog-region ;

| NOTE: We program eeprom a byte at a time since the 8515 lacks page
| access. It's also simpler this way to determine whether to program a
| byte, rather than checking if the entire page is FF.

: prog-ee-byte
   pp-byte  pp*  ( addr byte)
   dup  0ff =  if  2drop ^  then  ( skip if byte is 0ff)
   0c0 -rot  avr.Write  wait-eeprom ;

: prog-eeprom
   cr ." Writing eeprom"
   eeprom region  swap pp !  ( len)
   for  ( program eeprom bytes)
      prog-ee-byte
   next ;

| NOTE: The application part of the flash - but *not* the bootloader! - can
| be programmed via serial chat. We have a nice word for this: prog.
|
| Since it's nice to have both tools in our toolbox at the same time, let's
| give the SPI version a slightly different name.

: spi-prog
   cr  warn"
You should commit your changes *before* programming the flash
if you want the signature to reference the correct commits!
"  radix preserve  hex
   h preserve
   +prog              prog-fuses  erase-chip               -prog
   +prog  fast-clock  prog-flash  prog-eeprom  prog-locks  -prog ;

| In order to test that this code works with "factory fresh" chips, let's
| restore to a default state the fuses that affect the EEPROM and the
| clock: EESAVE unprogrammed, CKDIV8 programmed, and CKSEL=2 (to use the
| on-chip RC oscillator.)

: factory-fresh
   +prog  read-fuses  0ff bic  862 or  write-fuses  erase-chip  -prog ;

: verify-pad
   pad  #128 for  dup c@  pp*  xor  if  pp-byte -1 +a u.  then
                  1+ next  drop ;

| NOTE: verify-flash and verify-eeprom are _not_ standalone; they can only
| be called after prog mode is set and the SPI clock set properly.

: spi-verify-region
   region  swap pp !  ( len)
   #127 +  #128 /  for
      20  pp-word  8  pad  #128  avr.BulkRead
      verify-pad
   next ;

: spi-verify-flash
   cr  ." Verifying application "  flash  spi-verify-region
   cr  ." Verifying bootloader "  boot  spi-verify-region ;

: spi-verify-eeprom
   cr  ." Verifying eeprom "
   eeprom region  swap pp !  ( len)
   #127 +  #128 /  for
      0a0  pp-byte  0  pad  #128  avr.BulkRead
      verify-pad
   next ;

| Since fuses and locks can't be verified over chat, they don't need "spi-"
| prefixes.

: verify-fuses
   cr  ." Verifying fuses "
   read-fuses  fuses @  2dup = if  2drop ^  then  ( ok)
   swap u.  u.  ( chip, then saved) ;

: verify-locks
   cr  ." Verifying lock bits "
   read-locks  locks @  2dup = if  2drop ^  then  ( ok)
   swap u.  u.  ( chip, then saved) ;

: spi-verify
   radix preserve  hex
   h preserve
   +prog                  verify-fuses                                   -prog
   +prog  fast-clock  spi-verify-flash  spi-verify-eeprom  verify-locks  -prog ;

.then  ( avr.Hello)

: save-image
   h preserve
   token, create-file ( fd)
   ( header)  dup  " muforth AVR img "  write
   ( flash)   dup  flash   'image  #image  write
   ( eeprom)  dup  eeprom  'image  #image  write
   ( fuses)   dup                 fuses  8       write
   ( lock bits)  dup              locks  8       write
   close-file ;

: load-image
   wipe
   flash   #flash   \m allot ( appear to have filled the flash and eeprom)
   eeprom  #eeprom  \m allot ( ... so prog and verify will work)

   token, r/o open-file? ?abort  ( fd)
   ( check header)  dup  pad #16  read  #16 xor if  error" no header"  then
      " muforth AVR img " pad #16  string= not if  error" not an AVR image"  then
   ( read flash)   dup  flash   'image  #image  read  u.
   ( read eeprom)  dup  eeprom  'image  #image  read  u.
   ( read fuses)   dup                 fuses  8       read  u.
   ( read lock bits)  dup              locks  8       read  u.
   close-file  flash ;