1
/* Modified to use out for SPM access
2
** Peter Knight, Optiboot project http://optiboot.googlecode.com
6
** "_short" routines execute 1 cycle faster and use 1 less word of flash
7
** by using "out" instruction instead of "sts".
9
** Additional elpm variants that trust the value of RAMPZ
12
/* Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007 Eric B. Weddington
15
Redistribution and use in source and binary forms, with or without
16
modification, are permitted provided that the following conditions are met:
18
* Redistributions of source code must retain the above copyright
19
notice, this list of conditions and the following disclaimer.
20
* Redistributions in binary form must reproduce the above copyright
21
notice, this list of conditions and the following disclaimer in
22
the documentation and/or other materials provided with the
24
* Neither the name of the copyright holders nor the names of
25
contributors may be used to endorse or promote products derived
26
from this software without specific prior written permission.
28
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
29
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
30
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
31
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
32
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
33
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
34
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
35
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
36
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
37
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38
POSSIBILITY OF SUCH DAMAGE. */
40
/* $Id: boot.h,v 1.27.2.3 2008/09/30 13:58:48 arcanum Exp $ */
43
#define _AVR_BOOT_H_ 1
46
/** \defgroup avr_boot <avr/boot.h>: Bootloader Support Utilities
52
The macros in this module provide a C language interface to the
53
bootloader support functionality of certain AVR processors. These
54
macros are designed to work with all sizes of flash memory.
56
Global interrupts are not automatically disabled for these macros. It
57
is left up to the programmer to do this. See the code example below.
58
Also see the processor datasheet for caveats on having global interrupts
59
enabled during writing of the Flash.
61
\note Not all AVR processors provide bootloader support. See your
62
processor datasheet to see if it provides bootloader support.
64
\todo From email with Marek: On smaller devices (all except ATmega64/128),
65
__SPM_REG is in the I/O space, accessible with the shorter "in" and "out"
66
instructions - since the boot loader has a limited size, this could be an
67
important optimization.
69
\par API Usage Example
70
The following code shows typical usage of the boot API.
74
#include <avr/interrupt.h>
75
#include <avr/pgmspace.h>
77
void boot_program_page (uint32_t page, uint8_t *buf)
82
// Disable interrupts.
89
boot_page_erase (page);
90
boot_spm_busy_wait (); // Wait until the memory is erased.
92
for (i=0; i<SPM_PAGESIZE; i+=2)
94
// Set up little-endian word.
99
boot_page_fill (page + i, w);
102
boot_page_write (page); // Store buffer in flash page.
103
boot_spm_busy_wait(); // Wait until the memory is written.
105
// Reenable RWW-section again. We need this if we want to jump back
106
// to the application after bootloading.
110
// Re-enable interrupts (if they were ever enabled).
115
#include <avr/eeprom.h>
117
#include <inttypes.h>
120
/* Check for SPM Control Register in processor. */
122
# define __SPM_REG SPMCSR
123
#elif defined (SPMCR)
124
# define __SPM_REG SPMCR
126
# error AVR processor does not provide bootloader support!
130
/* Check for SPM Enable bit. */
132
# define __SPM_ENABLE SPMEN
133
#elif defined(SELFPRGEN)
134
# define __SPM_ENABLE SELFPRGEN
136
# error Cannot find SPM Enable bit definition!
139
/** \ingroup avr_boot
140
\def BOOTLOADER_SECTION
142
Used to declare a function or variable to be placed into a
143
new section called .bootloader. This section and its contents
144
can then be relocated to any address (such as the bootloader
145
NRWW area) at link-time. */
147
#define BOOTLOADER_SECTION __attribute__ ((section (".bootloader")))
149
/* Create common bit definitions. */
151
#define __COMMON_ASB ASB
153
#define __COMMON_ASB RWWSB
157
#define __COMMON_ASRE ASRE
159
#define __COMMON_ASRE RWWSRE
162
/* Define the bit positions of the Boot Lock Bits. */
169
/** \ingroup avr_boot
170
\def boot_spm_interrupt_enable()
171
Enable the SPM interrupt. */
173
#define boot_spm_interrupt_enable() (__SPM_REG |= (uint8_t)_BV(SPMIE))
175
/** \ingroup avr_boot
176
\def boot_spm_interrupt_disable()
177
Disable the SPM interrupt. */
179
#define boot_spm_interrupt_disable() (__SPM_REG &= (uint8_t)~_BV(SPMIE))
181
/** \ingroup avr_boot
182
\def boot_is_spm_interrupt()
183
Check if the SPM interrupt is enabled. */
185
#define boot_is_spm_interrupt() (__SPM_REG & (uint8_t)_BV(SPMIE))
187
/** \ingroup avr_boot
189
Check if the RWW section is busy. */
191
#define boot_rww_busy() (__SPM_REG & (uint8_t)_BV(__COMMON_ASB))
193
/** \ingroup avr_boot
195
Check if the SPM instruction is busy. */
197
#define boot_spm_busy() (__SPM_REG & (uint8_t)_BV(__SPM_ENABLE))
199
/** \ingroup avr_boot
200
\def boot_spm_busy_wait()
201
Wait while the SPM instruction is busy. */
203
#define boot_spm_busy_wait() do{}while(boot_spm_busy())
205
#define __BOOT_PAGE_ERASE (_BV(__SPM_ENABLE) | _BV(PGERS))
206
#define __BOOT_PAGE_WRITE (_BV(__SPM_ENABLE) | _BV(PGWRT))
207
#define __BOOT_PAGE_FILL _BV(__SPM_ENABLE)
208
#define __BOOT_RWW_ENABLE (_BV(__SPM_ENABLE) | _BV(__COMMON_ASRE))
209
#define __BOOT_LOCK_BITS_SET (_BV(__SPM_ENABLE) | _BV(BLBSET))
211
#define __boot_page_fill_short(address, data) \
213
__asm__ __volatile__ \
220
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
221
"r" ((uint8_t)__BOOT_PAGE_FILL), \
222
"z" ((uint16_t)address), \
223
"r" ((uint16_t)data) \
228
#define __boot_page_fill_normal(address, data) \
230
__asm__ __volatile__ \
237
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
238
"r" ((uint8_t)__BOOT_PAGE_FILL), \
239
"z" ((uint16_t)address), \
240
"r" ((uint16_t)data) \
245
#define __boot_page_fill_alternate(address, data)\
247
__asm__ __volatile__ \
256
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
257
"r" ((uint8_t)__BOOT_PAGE_FILL), \
258
"z" ((uint16_t)address), \
259
"r" ((uint16_t)data) \
264
#define __boot_page_fill_extended(address, data) \
266
__asm__ __volatile__ \
269
"movw r30, %A3\n\t" \
275
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
276
"i" (_SFR_MEM_ADDR(RAMPZ)), \
277
"r" ((uint8_t)__BOOT_PAGE_FILL), \
278
"r" ((uint32_t)address), \
279
"r" ((uint16_t)data) \
280
: "r0", "r30", "r31" \
284
#define __boot_page_fill_extended_short(address, data) \
286
__asm__ __volatile__ \
289
"movw r30, %A3\n\t" \
295
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
296
"i" (_SFR_IO_ADDR(RAMPZ)), \
297
"r" ((uint8_t)__BOOT_PAGE_FILL), \
298
"r" ((uint32_t)address), \
299
"r" ((uint16_t)data) \
300
: "r0", "r30", "r31" \
304
#define __boot_page_erase_short(address) \
306
__asm__ __volatile__ \
311
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
312
"r" ((uint8_t)__BOOT_PAGE_ERASE), \
313
"z" ((uint16_t)address) \
318
#define __boot_page_erase_normal(address) \
320
__asm__ __volatile__ \
325
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
326
"r" ((uint8_t)__BOOT_PAGE_ERASE), \
327
"z" ((uint16_t)address) \
331
#define __boot_page_erase_alternate(address) \
333
__asm__ __volatile__ \
340
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
341
"r" ((uint8_t)__BOOT_PAGE_ERASE), \
342
"z" ((uint16_t)address) \
346
#define __boot_page_erase_extended(address) \
348
__asm__ __volatile__ \
350
"movw r30, %A3\n\t" \
355
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
356
"i" (_SFR_MEM_ADDR(RAMPZ)), \
357
"r" ((uint8_t)__BOOT_PAGE_ERASE), \
358
"r" ((uint32_t)address) \
362
#define __boot_page_erase_extended_short(address) \
364
__asm__ __volatile__ \
366
"movw r30, %A3\n\t" \
371
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
372
"i" (_SFR_IO_ADDR(RAMPZ)), \
373
"r" ((uint8_t)__BOOT_PAGE_ERASE), \
374
"r" ((uint32_t)address) \
379
#define __boot_page_write_short(address) \
381
__asm__ __volatile__ \
386
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
387
"r" ((uint8_t)__BOOT_PAGE_WRITE), \
388
"z" ((uint16_t)address) \
392
#define __boot_page_write_normal(address) \
394
__asm__ __volatile__ \
399
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
400
"r" ((uint8_t)__BOOT_PAGE_WRITE), \
401
"z" ((uint16_t)address) \
405
#define __boot_page_write_alternate(address) \
407
__asm__ __volatile__ \
414
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
415
"r" ((uint8_t)__BOOT_PAGE_WRITE), \
416
"z" ((uint16_t)address) \
420
#define __boot_page_write_extended(address) \
422
__asm__ __volatile__ \
424
"movw r30, %A3\n\t" \
429
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
430
"i" (_SFR_MEM_ADDR(RAMPZ)), \
431
"r" ((uint8_t)__BOOT_PAGE_WRITE), \
432
"r" ((uint32_t)address) \
436
#define __boot_page_write_extended_short(address) \
438
__asm__ __volatile__ \
440
"movw r30, %A3\n\t" \
445
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
446
"i" (_SFR_IO_ADDR(RAMPZ)), \
447
"r" ((uint8_t)__BOOT_PAGE_WRITE), \
448
"r" ((uint32_t)address) \
453
#define __boot_rww_enable_short() \
455
__asm__ __volatile__ \
460
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
461
"r" ((uint8_t)__BOOT_RWW_ENABLE) \
465
#define __boot_rww_enable() \
467
__asm__ __volatile__ \
472
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
473
"r" ((uint8_t)__BOOT_RWW_ENABLE) \
477
#define __boot_rww_enable_alternate() \
479
__asm__ __volatile__ \
486
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
487
"r" ((uint8_t)__BOOT_RWW_ENABLE) \
491
/* From the mega16/mega128 data sheets (maybe others):
493
Bits by SPM To set the Boot Loader Lock bits, write the desired data to
494
R0, write "X0001001" to SPMCR and execute SPM within four clock cycles
495
after writing SPMCR. The only accessible Lock bits are the Boot Lock bits
496
that may prevent the Application and Boot Loader section from any
497
software update by the MCU.
499
If bits 5..2 in R0 are cleared (zero), the corresponding Boot Lock bit
500
will be programmed if an SPM instruction is executed within four cycles
501
after BLBSET and SPMEN (or SELFPRGEN) are set in SPMCR. The Z-pointer is
502
don't care during this operation, but for future compatibility it is
503
recommended to load the Z-pointer with $0001 (same as used for reading the
504
Lock bits). For future compatibility It is also recommended to set bits 7,
505
6, 1, and 0 in R0 to 1 when writing the Lock bits. When programming the
506
Lock bits the entire Flash can be read during the operation. */
508
#define __boot_lock_bits_set_short(lock_bits) \
510
uint8_t value = (uint8_t)(~(lock_bits)); \
511
__asm__ __volatile__ \
519
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
520
"r" ((uint8_t)__BOOT_LOCK_BITS_SET), \
522
: "r0", "r30", "r31" \
526
#define __boot_lock_bits_set(lock_bits) \
528
uint8_t value = (uint8_t)(~(lock_bits)); \
529
__asm__ __volatile__ \
537
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
538
"r" ((uint8_t)__BOOT_LOCK_BITS_SET), \
540
: "r0", "r30", "r31" \
544
#define __boot_lock_bits_set_alternate(lock_bits) \
546
uint8_t value = (uint8_t)(~(lock_bits)); \
547
__asm__ __volatile__ \
557
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
558
"r" ((uint8_t)__BOOT_LOCK_BITS_SET), \
560
: "r0", "r30", "r31" \
565
Reading lock and fuse bits:
567
Similarly to writing the lock bits above, set BLBSET and SPMEN (or
568
SELFPRGEN) bits in __SPMREG, and then (within four clock cycles) issue an
574
0x0002 extended fuse bits
575
0x0003 high fuse bits
577
Sounds confusing, doesn't it?
579
Unlike the macros in pgmspace.h, no need to care for non-enhanced
580
cores here as these old cores do not provide SPM support anyway.
583
/** \ingroup avr_boot
584
\def GET_LOW_FUSE_BITS
585
address to read the low fuse bits, using boot_lock_fuse_bits_get
587
#define GET_LOW_FUSE_BITS (0x0000)
588
/** \ingroup avr_boot
590
address to read the lock bits, using boot_lock_fuse_bits_get
592
#define GET_LOCK_BITS (0x0001)
593
/** \ingroup avr_boot
594
\def GET_EXTENDED_FUSE_BITS
595
address to read the extended fuse bits, using boot_lock_fuse_bits_get
597
#define GET_EXTENDED_FUSE_BITS (0x0002)
598
/** \ingroup avr_boot
599
\def GET_HIGH_FUSE_BITS
600
address to read the high fuse bits, using boot_lock_fuse_bits_get
602
#define GET_HIGH_FUSE_BITS (0x0003)
604
/** \ingroup avr_boot
605
\def boot_lock_fuse_bits_get(address)
607
Read the lock or fuse bits at \c address.
609
Parameter \c address can be any of GET_LOW_FUSE_BITS,
610
GET_LOCK_BITS, GET_EXTENDED_FUSE_BITS, or GET_HIGH_FUSE_BITS.
612
\note The lock and fuse bits returned are the physical values,
613
i.e. a bit returned as 0 means the corresponding fuse or lock bit
616
#define boot_lock_fuse_bits_get_short(address) \
619
__asm__ __volatile__ \
626
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
627
"r" ((uint8_t)__BOOT_LOCK_BITS_SET), \
629
: "r0", "r30", "r31" \
634
#define boot_lock_fuse_bits_get(address) \
637
__asm__ __volatile__ \
644
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
645
"r" ((uint8_t)__BOOT_LOCK_BITS_SET), \
647
: "r0", "r30", "r31" \
652
/** \ingroup avr_boot
653
\def boot_signature_byte_get(address)
655
Read the Signature Row byte at \c address. For some MCU types,
656
this function can also retrieve the factory-stored oscillator
659
Parameter \c address can be 0-0x1f as documented by the datasheet.
660
\note The values are MCU type dependent.
663
#define __BOOT_SIGROW_READ (_BV(__SPM_ENABLE) | _BV(SIGRD))
665
#define boot_signature_byte_get_short(addr) \
667
uint16_t __addr16 = (uint16_t)(addr); \
669
__asm__ __volatile__ \
674
: "i" (_SFR_IO_ADDR(__SPM_REG)), \
675
"r" ((uint8_t) __BOOT_SIGROW_READ), \
681
#define boot_signature_byte_get(addr) \
683
uint16_t __addr16 = (uint16_t)(addr); \
685
__asm__ __volatile__ \
690
: "i" (_SFR_MEM_ADDR(__SPM_REG)), \
691
"r" ((uint8_t) __BOOT_SIGROW_READ), \
697
/** \ingroup avr_boot
698
\def boot_page_fill(address, data)
700
Fill the bootloader temporary page buffer for flash
701
address with data word.
703
\note The address is a byte address. The data is a word. The AVR
704
writes data to the buffer a word at a time, but addresses the buffer
705
per byte! So, increment your address by 2 between calls, and send 2
706
data bytes in a word format! The LSB of the data is written to the lower
707
address; the MSB of the data is written to the higher address.*/
709
/** \ingroup avr_boot
710
\def boot_page_erase(address)
712
Erase the flash page that contains address.
714
\note address is a byte address in flash, not a word address. */
716
/** \ingroup avr_boot
717
\def boot_page_write(address)
719
Write the bootloader temporary page buffer
720
to flash page that contains address.
722
\note address is a byte address in flash, not a word address. */
724
/** \ingroup avr_boot
725
\def boot_rww_enable()
727
Enable the Read-While-Write memory section. */
729
/** \ingroup avr_boot
730
\def boot_lock_bits_set(lock_bits)
732
Set the bootloader lock bits.
734
\param lock_bits A mask of which Boot Loader Lock Bits to set.
736
\note In this context, a 'set bit' will be written to a zero value.
737
Note also that only BLBxx bits can be programmed by this command.
739
For example, to disallow the SPM instruction from writing to the Boot
740
Loader memory section of flash, you would use this macro as such:
743
boot_lock_bits_set (_BV (BLB11));
746
\note Like any lock bits, the Boot Loader Lock Bits, once set,
747
cannot be cleared again except by a chip erase which will in turn
748
also erase the boot loader itself. */
750
/* Normal versions of the macros use 16-bit addresses.
751
Extended versions of the macros use 32-bit addresses.
752
Alternate versions of the macros use 16-bit addresses and require special
753
instruction sequences after LPM.
755
FLASHEND is defined in the ioXXXX.h file.
756
USHRT_MAX is defined in <limits.h>. */
758
#if defined(__AVR_ATmega161__) || defined(__AVR_ATmega163__) \
759
|| defined(__AVR_ATmega323__)
761
/* Alternate: ATmega161/163/323 and 16 bit address */
762
#define boot_page_fill(address, data) __boot_page_fill_alternate(address, data)
763
#define boot_page_erase(address) __boot_page_erase_alternate(address)
764
#define boot_page_write(address) __boot_page_write_alternate(address)
765
#define boot_rww_enable() __boot_rww_enable_alternate()
766
#define boot_lock_bits_set(lock_bits) __boot_lock_bits_set_alternate(lock_bits)
768
#elif (FLASHEND > USHRT_MAX)
770
/* Extended: >16 bit address */
771
#define boot_page_fill(address, data) __boot_page_fill_extended_short(address, data)
772
#define boot_page_erase(address) __boot_page_erase_extended_short(address)
773
#define boot_page_write(address) __boot_page_write_extended_short(address)
774
#define boot_rww_enable() __boot_rww_enable_short()
775
#define boot_lock_bits_set(lock_bits) __boot_lock_bits_set_short(lock_bits)
779
/* Normal: 16 bit address */
780
#define boot_page_fill(address, data) __boot_page_fill_short(address, data)
781
#define boot_page_erase(address) __boot_page_erase_short(address)
782
#define boot_page_write(address) __boot_page_write_short(address)
783
#define boot_rww_enable() __boot_rww_enable_short()
784
#define boot_lock_bits_set(lock_bits) __boot_lock_bits_set_short(lock_bits)
788
/** \ingroup avr_boot
790
Same as boot_page_fill() except it waits for eeprom and spm operations to
791
complete before filling the page. */
793
#define boot_page_fill_safe(address, data) \
795
boot_spm_busy_wait(); \
796
eeprom_busy_wait(); \
797
boot_page_fill(address, data); \
800
/** \ingroup avr_boot
802
Same as boot_page_erase() except it waits for eeprom and spm operations to
803
complete before erasing the page. */
805
#define boot_page_erase_safe(address) \
807
boot_spm_busy_wait(); \
808
eeprom_busy_wait(); \
809
boot_page_erase (address); \
812
/** \ingroup avr_boot
814
Same as boot_page_write() except it waits for eeprom and spm operations to
815
complete before writing the page. */
817
#define boot_page_write_safe(address) \
819
boot_spm_busy_wait(); \
820
eeprom_busy_wait(); \
821
boot_page_write (address); \
824
/** \ingroup avr_boot
826
Same as boot_rww_enable() except waits for eeprom and spm operations to
827
complete before enabling the RWW mameory. */
829
#define boot_rww_enable_safe() \
831
boot_spm_busy_wait(); \
832
eeprom_busy_wait(); \
836
/** \ingroup avr_boot
838
Same as boot_lock_bits_set() except waits for eeprom and spm operations to
839
complete before setting the lock bits. */
841
#define boot_lock_bits_set_safe(lock_bits) \
843
boot_spm_busy_wait(); \
844
eeprom_busy_wait(); \
845
boot_lock_bits_set (lock_bits); \
848
#endif /* _AVR_BOOT_H_ */