Statistics
| Branch: | Tag: | Revision:

root / LUFA / ManPages / SoftwareBootloaderJump.txt @ 978b99e5

History | View | Annotate | Download (2.77 KB)

1
/** \file
2
 *
3
 *  This file contains special DoxyGen information for the generation of the main page and other special
4
 *  documentation pages. It is not a project source file.
5
 */
6

    
7
/**
8
 *  \page Page_SoftwareBootloaderStart Entering the Bootloader via Software
9
 *
10
 *  A common requirement of many applications is the ability to jump to the programmed bootloader of a chip
11
 *  on demand, via the code's firmware (i.e. not as a result of any physical user interaction with the
12
 *  hardware). This might be required because the device does not have any physical user input, or simply
13
 *  just to streamline the device upgrade process on the host PC.
14
 *
15
 *  The following C code snippets may be used to enter the bootloader upon request by the user application.
16
 *  By using the watchdog to physically reset the controller, it is ensured that all system hardware is
17
 *  completely reset to their defaults before the bootloader is run. This is important; since bootloaders
18
 *  are written to occupy a very limited space, they usually make assumptions about the register states based
19
 *  on the default values after a hard-reset of the chip.
20
 *
21
 *  \section Sec_SoftareBootAVR8 AVR8 Architecture
22
 *  The following software bootloader jump code is written for the AVR8 architecture.
23
 *
24
 *  \code
25
 *  #include <avr/wdt.h>
26
 *  #include <avr/io.h>
27
 *  #include <util/delay.h>
28
 *
29
 *  #include <LUFA/Common/Common.h>
30
 *  #include <LUFA/Drivers/USB/USB.h>
31
 *
32
 *  uint32_t Boot_Key ATTR_NO_INIT;
33
 *
34
 *  #define MAGIC_BOOT_KEY            0xDC42ACCA
35
 *  #define BOOTLOADER_START_ADDRESS  (FLASH_SIZE_BYTES - BOOTLOADER_SEC_SIZE_BYTES)
36
 *
37
 *  void Bootloader_Jump_Check(void) ATTR_INIT_SECTION(3);
38
 *  void Bootloader_Jump_Check(void)
39
 *  {
40
 *      // If the reset source was the bootloader and the key is correct, clear it and jump to the bootloader
41
 *      if ((MCUSR & (1 << WDRF)) && (Boot_Key == MAGIC_BOOT_KEY))
42
 *      {
43
 *          Boot_Key = 0;
44
 *          ((void (*)(void))BOOTLOADER_START_ADDRESS)();
45
 *      }
46
 *  }
47
 *
48
 *  void Jump_To_Bootloader(void)
49
 *  {
50
 *      // If USB is used, detach from the bus and reset it
51
 *      USB_Disable();
52
 *
53
 *      // Disable all interrupts
54
 *      cli();
55
 *
56
 *      // Wait two seconds for the USB detachment to register on the host
57
 *      Delay_MS(2000);
58
 *
59
 *      // Set the bootloader key to the magic value and force a reset
60
 *      Boot_Key = MAGIC_BOOT_KEY;
61
 *      wdt_enable(WDTO_250MS);
62
 *      for (;;);
63
 *  }
64
 *  \endcode
65
 *
66
 *  Note that the bootloader magic key can be any arbitrary value. The <em>FLASH_SIZE_BYTES</em> and
67
 *  <em>BOOTLOADER_SEC_SIZE_BYTES</em> tokens should be replaced with the total flash size of the AVR
68
 *  in bytes, and the allocated size of the bootloader section for the target AVR.
69
 *
70
 */
71