aboutsummaryrefslogtreecommitdiffstats
path: root/Bootloaders/DFU/BootloaderDFU.txt
blob: a01b1d9fd39cbcb6024db301c22088f188f532e6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
/** \file
 *
 *  This file contains special DoxyGen information for the generation of the main page and other special
 *  documentation pages. It is not a project source file.
 */

/** \mainpage DFU Class USB AVR Bootloader
 *
 *  \section Sec_Compat Demo Compatibility:
 *
 *  The following list indicates what microcontrollers are compatible with this demo.
 *
 *  \li Series 7 USB AVRs (AT90USBxxx7)
 *  \li Series 6 USB AVRs (AT90USBxxx6)
 *  \li Series 4 USB AVRs (ATMEGAxxU4)
 *  \li Series 2 USB AVRs (AT90USBxx2, ATMEGAxxU2)
 *
 *  \section Sec_Info USB Information:
 *
 *  The following table gives a rundown of the USB utilization of this demo.
 *
 * <table>
 *  <tr>
 *   <td><b>USB Mode:</b></td>
 *   <td>Device</td>
 *  </tr>
 *  <tr>
 *   <td><b>USB Class:</b></td>
 *   <td>Device Firmware Update Class (DFU)</td>
 *  </tr>
 *  <tr>
 *   <td><b>USB Subclass:</b></td>
 *   <td>None</td>
 *  </tr>
 *  <tr>
 *   <td><b>Relevant Standards:</b></td>
 *   <td>USBIF DFU Class Standard, Atmel USB Bootloader Datasheet</td>
 *  </tr>
 *  <tr>
 *   <td><b>Supported USB Speeds:</b></td>
 *   <td>Full Speed Mode</td>
 *  </tr>
 * </table>
 *
 *  \section Sec_Description Project Description:
 *
 *  This bootloader enumerates to the host as a DFU Class device, allowing for DFU-compatible programming
 *  software to load firmware onto the AVR.
 *
 *  Out of the box this bootloader builds for the AT90USB1287 with an 8KB bootloader section size, and will fit
 *  into 4KB of bootloader space. If you wish to alter this size and/or change the AVR model, you will need to
 *  edit the MCU, FLASH_SIZE_KB and BOOT_SECTION_SIZE_KB values in the accompanying makefile.
 *
 *  When the bootloader is running, the board's LED(s) will flash at regular intervals to distinguish the
 *  bootloader from the normal user application.
 *
 *  \section Sec_Installation Driver Installation
 *
 *  This bootloader is designed to be compatible with Atmel's provided Windows DFU class drivers. You will need to
 *  install Atmel's DFU drivers prior to using this bootloader on Windows platforms. If you are using a 64 bit Windows
 *  OS, you will need to either disable the driver signing requirement (see online tutorials for details) or use a
 *  digitally signed version of the official Atmel driver provided by a third party AVR user at
 *  <a>http://www.avrfreaks.net/index.php?module=Freaks%20Academy&func=viewItem&item_id=2196&item_type=project</a>.
 *
 *  \note This device spoofs Atmel's DFU Bootloader USB VID and PID so that the Atmel DFU bootloader
 *        drivers included with FLIP will work. If you do not wish to use Atmel's ID codes, please
 *        manually change them in Descriptors.c and alter your driver's INF file accordingly.
 *
 *  \section Sec_HostApp Host Controller Application
 *  
 *  This bootloader is compatible with Atmel's FLIP utility on Windows machines, and dfu-programmer on Linux machines.
 *
 *  \subsection SSec_FLIP FLIP (Windows)
 *
 *  FLIP (Flexible In-System Programmer) is a utility written by Atmel, and distributed for free on the Atmel website.
 *  The FLIP utility is designed to assist in the bootloader programming of a range of Atmel devices, through several
 *  popular physical interfaces including USB. It is written in Java, however makes use of native extensions for USB
 *  support and thus is only offered on Windows.
 *
 *  To program a device using FLIP, refer to the Atmel FLIP documentation.
 *
 *  \subsection SSec_DFUProgrammer dfu-programmer (Linux)
 *
 *  dfu-programmer is an open-source command line solution for the bootloader programming of Atmel devices through a
 *  USB connection, using the DFU protocol, available for download at <a>http://sourceforge.net/projects/dfu-programmer/</a>.
 *
 *  The following example loads a HEX file into the AVR's FLASH memory using dfu-programmer:
 *  \code
 *  dfu-programmer at90usb1287 erase flash Mouse.hex
 *  \endcode
 *
 *  \section Sec_API User Application API
 *
 *  Several user application functions for FLASH and other special memory area manipulations are exposed by the bootloader,
 *  allowing the user application to call into the bootloader at runtime to read and write FLASH data.
 *
 *  \warning The APIs exposed by the DFU class bootloader are \b NOT compatible with the API exposed by the official Atmel DFU bootloader.
 *
 *  By default, the bootloader API jump table is located 32 bytes from the end of the device's FLASH memory, and follows the
 *  following layout:
 *
 *  \code
 *  #define BOOTLOADER_API_TABLE_SIZE          32
 *  #define BOOTLOADER_API_TABLE_START         ((FLASHEND + 1UL) - BOOTLOADER_API_TABLE_SIZE)
 *  #define BOOTLOADER_API_CALL(Index)         (void*)((BOOTLOADER_API_TABLE_START + (Index * 2)) / 2)
 *  
 *  void    (*BootloaderAPI_ErasePage)(uint32_t Address)               = BOOTLOADER_API_CALL(0);
 *  void    (*BootloaderAPI_WritePage)(uint32_t Address)               = BOOTLOADER_API_CALL(1);
 *  void    (*BootloaderAPI_FillWord)(uint32_t Address, uint16_t Word) = BOOTLOADER_API_CALL(2);
 *  uint8_t (*BootloaderAPI_ReadSignature)(uint16_t Address)           = BOOTLOADER_API_CALL(3);
 *  uint8_t (*BootloaderAPI_ReadFuse)(uint16_t Address)                = BOOTLOADER_API_CALL(4);
 *  uint8_t (*BootloaderAPI_ReadLock)(void)                            = BOOTLOADER_API_CALL(5);
 *  void    (*BootloaderAPI_WriteLock)(uint8_t LockBits)               = BOOTLOADER_API_CALL(6);
 *  
 *  #define BOOTLOADER_MAGIC_SIGNATURE_START   (BOOTLOADER_API_TABLE_START + (BOOTLOADER_API_TABLE_SIZE - 2))
 *  #define BOOTLOADER_MAGIC_SIGNATURE         0xDCFB
 *  
 *  #define BOOTLOADER_CLASS_SIGNATURE_START   (BOOTLOADER_API_TABLE_START + (BOOTLOADER_API_TABLE_SIZE - 4))
 *  #define BOOTLOADER_CDC_SIGNATURE           0xDFB1
 *  
 *  #define BOOTLOADER_ADDRESS_START           (BOOTLOADER_API_TABLE_START + (BOOTLOADER_API_TABLE_SIZE - 8))
 *  #define BOOTLOADER_ADDRESS_LENGTH          4
 *  \endcode
 *
 *  From the application the API support of the bootloader can be detected by reading the FLASH memory bytes located at address
 *  \c BOOTLOADER_MAGIC_SIGNATURE_START and comparing them to the value \c BOOTLOADER_MAGIC_SIGNATURE. The class of bootloader
 *  can be determined by reading the FLASH memory bytes located at address \c BOOTLOADER_CLASS_SIGNATURE_START and comparing them
 *  to the value \c BOOTLOADER_CDC_SIGNATURE. The start address of the bootloader can be retrieved by reading the bytes of FLASH
 *  memory starting from address \c BOOTLOADER_ADDRESS_START.
 *
 *  \subsection SSec_API_MemLayout Device Memory Map
 *  The following illustration indicates the final memory map of the device when loaded with the bootloader.
 *
 *  \verbatim
 *  +----------------------------+ 0x0000
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |      User Application      |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  |                            |
 *  +----------------------------+ FLASHEND - BOOT_SECTION_SIZE
 *  |                            |
 *  |   Bootloader Application   |
 *  | (Not User App. Accessible) |
 *  |                            |
 *  +----------------------------+ FLASHEND - 96
 *  |   API Table Trampolines    |
 *  | (Not User App. Accessible) |
 *  +----------------------------+ FLASHEND - 32
 *  |    Bootloader API Table    |
 *  |   (User App. Accessible)   |
 *  +----------------------------+ FLASHEND - 8
 *  |   Bootloader ID Constants  |
 *  |   (User App. Accessible)   |
 *  +----------------------------+ FLASHEND
 *  \endverbatim
 *
 *  \section Sec_Options Project Options
 *
 *  The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value.
 *
 *  <table>
 *   <tr>
 *    <td><b>Define Name:</b></td>
 *    <td><b>Location:</b></td>
 *    <td><b>Description:</b></td>
 *   </tr>
 *   <tr>
 *    <td>SECURE_MODE</td>
 *    <td>BootloaderDFU.h</td>
 *    <td>If defined to true, the bootloader will not accept any memory commands other than a chip erase on start-up, until an
 *        erase has been performed. This can be used in conjunction with the AVR's lockbits to prevent the AVRs firmware from
 *        being dumped by unauthorized persons.</td>
 *   </tr>
 *  </table>
 */