]> git.gir.st - tmk_keyboard.git/blob - protocol/lufa/LUFA-120730/LUFA/DoxygenPages/SoftwareBootloaderJump.txt
Squashed 'tmk_core/' content from commit 05caacc
[tmk_keyboard.git] / protocol / lufa / LUFA-120730 / LUFA / DoxygenPages / SoftwareBootloaderJump.txt
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
Imprint / Impressum