LUFA/ManPages/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 snippet 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  *  \code
  22  *  #include <avr/wdt.h>
  23  *  #include <avr/io.h>
  24  *  #include <util/delay.h>
  25  *
  26  *  #include <LUFA/Common/Common.h>
  27  *  #include <LUFA/Drivers/USB/USB.h>
  28  *
  29  *  uint32_t Boot_Key ATTR_NO_INIT;
  30  *
  31  *  #define MAGIC_BOOT_KEY            0xDC42ACCA
  32  *  #define BOOTLOADER_START_ADDRESS  ({FLASH_SIZE_BYTES} - {BOOTLOADER_SEC_SIZE_BYTES})
  33  *
  34  *  void Bootloader_Jump_Check(void) ATTR_INIT_SECTION(3);
  35  *  void Bootloader_Jump_Check(void)
  36  *  {
  37  *      // If the reset source was the bootloader and the key is correct, clear it and jump to the bootloader
  38  *      if ((MCUSR & (1<<WDRF)) && (Boot_Key == MAGIC_BOOT_KEY))
  39  *      {
  40  *          Boot_Key = 0;
  41  *          ((void (*)(void))BOOTLOADER_START_ADDRESS)();
  42  *      }
  43  *  }
  44  *
  45  *  void Jump_To_Bootloader(void)
  46  *  {
  47  *      // If USB is used, detatch from the bus and wait 2 seconds for the host to register it
  48  *      USB_ShutDown();
  49  *      for (uint8_t i = 0; i < 128; i++)
  50  *        _delay_ms(16);
  51  *
  52  *      // Set the bootloader key to the magic value and force a reset
  53  *      Boot_Key = MAGIC_BOOT_KEY;
  54  *      wdt_enable(WDTO_250MS);
  55  *      for (;;);
  56  *  }
  57  *  \endcode
  58  *
  59  *  Note that the bootloader magic key can be any arbitrary value. The {FLASH_SIZE_BYTES} and
  60  *  {BOOTLOADER_SEC_SIZE_BYTES} tokens should be replaced with the total flash size of the AVR
  61  *  in bytes, and the allocated size of the bootloader section for the target AVR.
  62  *
  63  */