protocol/lufa/LUFA-120730/LUFA/DoxygenPages/SoftwareBootloaderJump.txt

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