3 Copyright (C) Dean Camera, 2011.
5 dean [at] fourwalledcubicle [dot] com
10 Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
33 * Main source file for the DFU class bootloader. This file contains the complete bootloader logic.
36 #define INCLUDE_FROM_BOOTLOADER_C
37 #include "BootloaderDFU.h"
39 /** Flag to indicate if the bootloader is currently running in secure mode, disallowing memory operations
40 * other than erase. This is initially set to the value set by SECURE_MODE, and cleared by the bootloader
41 * once a memory erase has completed in a bootloader session.
43 static bool IsSecure
= SECURE_MODE
;
45 /** Flag to indicate if the bootloader should be running, or should exit and allow the application code to run
46 * via a soft reset. When cleared, the bootloader will abort, the USB interface will shut down and the application
47 * jumped to via an indirect jump to location 0x0000 (or other location specified by the host).
49 static bool RunBootloader
= true;
51 /** Flag to indicate if the bootloader is waiting to exit. When the host requests the bootloader to exit and
52 * jump to the application address it specifies, it sends two sequential commands which must be properly
53 * acknowledged. Upon reception of the first the RunBootloader flag is cleared and the WaitForExit flag is set,
54 * causing the bootloader to wait for the final exit command before shutting down.
56 static bool WaitForExit
= false;
58 /** Current DFU state machine state, one of the values in the DFU_State_t enum. */
59 static uint8_t DFU_State
= dfuIDLE
;
61 /** Status code of the last executed DFU command. This is set to one of the values in the DFU_Status_t enum after
62 * each operation, and returned to the host when a Get Status DFU request is issued.
64 static uint8_t DFU_Status
= OK
;
66 /** Data containing the DFU command sent from the host. */
67 static DFU_Command_t SentCommand
;
69 /** Response to the last issued Read Data DFU command. Unlike other DFU commands, the read command
70 * requires a single byte response from the bootloader containing the read data when the next DFU_UPLOAD command
71 * is issued by the host.
73 static uint8_t ResponseByte
;
75 /** Pointer to the start of the user application. By default this is 0x0000 (the reset vector), however the host
76 * may specify an alternate address when issuing the application soft-start command.
78 static AppPtr_t AppStartPtr
= (AppPtr_t
)0x0000;
80 /** 64-bit flash page number. This is concatenated with the current 16-bit address on USB AVRs containing more than
81 * 64KB of flash memory.
83 static uint8_t Flash64KBPage
= 0;
85 /** Memory start address, indicating the current address in the memory being addressed (either FLASH or EEPROM
86 * depending on the issued command from the host).
88 static uint16_t StartAddr
= 0x0000;
90 /** Memory end address, indicating the end address to read from/write to in the memory being addressed (either FLASH
91 * of EEPROM depending on the issued command from the host).
93 static uint16_t EndAddr
= 0x0000;
96 /** Main program entry point. This routine configures the hardware required by the bootloader, then continuously
97 * runs the bootloader processing routine until instructed to soft-exit, or hard-reset via the watchdog to start
98 * the loaded application code.
102 /* Force a reference to the API jump table to prevent the linker from discarding it */
103 uint8_t* volatile Dummy
= BootloaderAPI_JumpTable
;
106 /* Configure hardware required by the bootloader */
109 #if ((BOARD == BOARD_XPLAIN) || (BOARD == BOARD_XPLAIN_REV1))
110 /* Disable JTAG debugging */
114 /* Enable pull-up on the JTAG TCK pin so we can use it to select the mode */
118 /* If the TCK pin is not jumpered to ground, start the user application instead */
119 RunBootloader
= (!(PINF
& (1 << 4)));
121 /* Re-enable JTAG debugging */
122 MCUCR
&= ~(1 << JTD
);
123 MCUCR
&= ~(1 << JTD
);
126 /* Turn on first LED on the board to indicate that the bootloader has started */
127 LEDs_SetAllLEDs(LEDS_LED1
);
129 /* Enable global interrupts so that the USB stack can function */
132 /* Run the USB management task while the bootloader is supposed to be running */
133 while (RunBootloader
|| WaitForExit
)
136 /* Reset configured hardware back to their original states for the user application */
139 /* Start the user application */
143 /** Configures all hardware required for the bootloader. */
144 void SetupHardware(void)
146 /* Disable watchdog if enabled by bootloader/fuses */
147 MCUSR
&= ~(1 << WDRF
);
150 /* Disable clock division */
151 clock_prescale_set(clock_div_1
);
153 /* Relocate the interrupt vector table to the bootloader section */
155 MCUCR
= (1 << IVSEL
);
157 /* Initialize the USB subsystem */
161 /* Bootloader active LED toggle timer initialization */
162 TIMSK1
= (1 << TOIE1
);
163 TCCR1B
= ((1 << CS11
) | (1 << CS10
));
166 /** Resets all configured hardware required for the bootloader back to their original states. */
167 void ResetHardware(void)
169 /* Shut down the USB subsystem */
172 /* Relocate the interrupt vector table back to the application section */
177 /** ISR to periodically toggle the LEDs on the board to indicate that the bootloader is active. */
178 ISR(TIMER1_OVF_vect
, ISR_BLOCK
)
180 LEDs_ToggleLEDs(LEDS_LED1
| LEDS_LED2
);
183 /** Event handler for the USB_ControlRequest event. This is used to catch and process control requests sent to
184 * the device from the USB host before passing along unhandled control requests to the library for processing
187 void EVENT_USB_Device_ControlRequest(void)
189 /* Ignore any requests that aren't directed to the DFU interface */
190 if ((USB_ControlRequest
.bmRequestType
& (CONTROL_REQTYPE_TYPE
| CONTROL_REQTYPE_RECIPIENT
)) !=
191 (REQTYPE_CLASS
| REQREC_INTERFACE
))
196 /* Activity - toggle indicator LEDs */
197 LEDs_ToggleLEDs(LEDS_LED1
| LEDS_LED2
);
199 /* Get the size of the command and data from the wLength value */
200 SentCommand
.DataSize
= USB_ControlRequest
.wLength
;
202 switch (USB_ControlRequest
.bRequest
)
205 Endpoint_ClearSETUP();
207 /* Check if bootloader is waiting to terminate */
210 /* Bootloader is terminating - process last received command */
211 ProcessBootloaderCommand();
213 /* Indicate that the last command has now been processed - free to exit bootloader */
217 /* If the request has a data stage, load it into the command struct */
218 if (SentCommand
.DataSize
)
220 while (!(Endpoint_IsOUTReceived()))
222 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
226 /* First byte of the data stage is the DNLOAD request's command */
227 SentCommand
.Command
= Endpoint_Read_8();
229 /* One byte of the data stage is the command, so subtract it from the total data bytes */
230 SentCommand
.DataSize
--;
232 /* Load in the rest of the data stage as command parameters */
233 for (uint8_t DataByte
= 0; (DataByte
< sizeof(SentCommand
.Data
)) &&
234 Endpoint_BytesInEndpoint(); DataByte
++)
236 SentCommand
.Data
[DataByte
] = Endpoint_Read_8();
237 SentCommand
.DataSize
--;
240 /* Process the command */
241 ProcessBootloaderCommand();
244 /* Check if currently downloading firmware */
245 if (DFU_State
== dfuDNLOAD_IDLE
)
247 if (!(SentCommand
.DataSize
))
253 /* Throw away the filler bytes before the start of the firmware */
254 DiscardFillerBytes(DFU_FILLER_BYTES_SIZE
);
256 /* Throw away the packet alignment filler bytes before the start of the firmware */
257 DiscardFillerBytes(StartAddr
% FIXED_CONTROL_ENDPOINT_SIZE
);
259 /* Calculate the number of bytes remaining to be written */
260 uint16_t BytesRemaining
= ((EndAddr
- StartAddr
) + 1);
262 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x00)) // Write flash
264 /* Calculate the number of words to be written from the number of bytes to be written */
265 uint16_t WordsRemaining
= (BytesRemaining
>> 1);
271 } CurrFlashAddress
= {.Words
= {StartAddr
, Flash64KBPage
}};
273 uint32_t CurrFlashPageStartAddress
= CurrFlashAddress
.Long
;
274 uint8_t WordsInFlashPage
= 0;
276 while (WordsRemaining
--)
278 /* Check if endpoint is empty - if so clear it and wait until ready for next packet */
279 if (!(Endpoint_BytesInEndpoint()))
283 while (!(Endpoint_IsOUTReceived()))
285 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
290 /* Write the next word into the current flash page */
291 boot_page_fill(CurrFlashAddress
.Long
, Endpoint_Read_16_LE());
293 /* Adjust counters */
294 WordsInFlashPage
+= 1;
295 CurrFlashAddress
.Long
+= 2;
297 /* See if an entire page has been written to the flash page buffer */
298 if ((WordsInFlashPage
== (SPM_PAGESIZE
>> 1)) || !(WordsRemaining
))
300 /* Commit the flash page to memory */
301 boot_page_write(CurrFlashPageStartAddress
);
302 boot_spm_busy_wait();
304 /* Check if programming incomplete */
307 CurrFlashPageStartAddress
= CurrFlashAddress
.Long
;
308 WordsInFlashPage
= 0;
310 /* Erase next page's temp buffer */
311 boot_page_erase(CurrFlashAddress
.Long
);
312 boot_spm_busy_wait();
317 /* Once programming complete, start address equals the end address */
320 /* Re-enable the RWW section of flash */
325 while (BytesRemaining
--)
327 /* Check if endpoint is empty - if so clear it and wait until ready for next packet */
328 if (!(Endpoint_BytesInEndpoint()))
332 while (!(Endpoint_IsOUTReceived()))
334 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
339 /* Read the byte from the USB interface and write to to the EEPROM */
340 eeprom_write_byte((uint8_t*)StartAddr
, Endpoint_Read_8());
342 /* Adjust counters */
347 /* Throw away the currently unused DFU file suffix */
348 DiscardFillerBytes(DFU_FILE_SUFFIX_SIZE
);
354 Endpoint_ClearStatusStage();
358 Endpoint_ClearSETUP();
360 while (!(Endpoint_IsINReady()))
362 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
366 if (DFU_State
!= dfuUPLOAD_IDLE
)
368 if ((DFU_State
== dfuERROR
) && IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x01)) // Blank Check
370 /* Blank checking is performed in the DFU_DNLOAD request - if we get here we've told the host
371 that the memory isn't blank, and the host is requesting the first non-blank address */
372 Endpoint_Write_16_LE(StartAddr
);
376 /* Idle state upload - send response to last issued command */
377 Endpoint_Write_8(ResponseByte
);
382 /* Determine the number of bytes remaining in the current block */
383 uint16_t BytesRemaining
= ((EndAddr
- StartAddr
) + 1);
385 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x00)) // Read FLASH
387 /* Calculate the number of words to be written from the number of bytes to be written */
388 uint16_t WordsRemaining
= (BytesRemaining
>> 1);
394 } CurrFlashAddress
= {.Words
= {StartAddr
, Flash64KBPage
}};
396 while (WordsRemaining
--)
398 /* Check if endpoint is full - if so clear it and wait until ready for next packet */
399 if (Endpoint_BytesInEndpoint() == FIXED_CONTROL_ENDPOINT_SIZE
)
403 while (!(Endpoint_IsINReady()))
405 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
410 /* Read the flash word and send it via USB to the host */
411 #if (FLASHEND > 0xFFFF)
412 Endpoint_Write_16_LE(pgm_read_word_far(CurrFlashAddress
.Long
));
414 Endpoint_Write_16_LE(pgm_read_word(CurrFlashAddress
.Long
));
417 /* Adjust counters */
418 CurrFlashAddress
.Long
+= 2;
421 /* Once reading is complete, start address equals the end address */
424 else if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x02)) // Read EEPROM
426 while (BytesRemaining
--)
428 /* Check if endpoint is full - if so clear it and wait until ready for next packet */
429 if (Endpoint_BytesInEndpoint() == FIXED_CONTROL_ENDPOINT_SIZE
)
433 while (!(Endpoint_IsINReady()))
435 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
440 /* Read the EEPROM byte and send it via USB to the host */
441 Endpoint_Write_8(eeprom_read_byte((uint8_t*)StartAddr
));
443 /* Adjust counters */
448 /* Return to idle state */
454 Endpoint_ClearStatusStage();
456 case DFU_REQ_GETSTATUS
:
457 Endpoint_ClearSETUP();
459 /* Write 8-bit status value */
460 Endpoint_Write_8(DFU_Status
);
462 /* Write 24-bit poll timeout value */
464 Endpoint_Write_16_LE(0);
466 /* Write 8-bit state value */
467 Endpoint_Write_8(DFU_State
);
469 /* Write 8-bit state string ID number */
474 Endpoint_ClearStatusStage();
476 case DFU_REQ_CLRSTATUS
:
477 Endpoint_ClearSETUP();
479 /* Reset the status value variable to the default OK status */
482 Endpoint_ClearStatusStage();
484 case DFU_REQ_GETSTATE
:
485 Endpoint_ClearSETUP();
487 /* Write the current device state to the endpoint */
488 Endpoint_Write_8(DFU_State
);
492 Endpoint_ClearStatusStage();
495 Endpoint_ClearSETUP();
497 /* Reset the current state variable to the default idle state */
500 Endpoint_ClearStatusStage();
505 /** Routine to discard the specified number of bytes from the control endpoint stream. This is used to
506 * discard unused bytes in the stream from the host, including the memory program block suffix.
508 * \param[in] NumberOfBytes Number of bytes to discard from the host from the control endpoint
510 static void DiscardFillerBytes(uint8_t NumberOfBytes
)
512 while (NumberOfBytes
--)
514 if (!(Endpoint_BytesInEndpoint()))
518 /* Wait until next data packet received */
519 while (!(Endpoint_IsOUTReceived()))
521 if (USB_DeviceState
== DEVICE_STATE_Unattached
)
527 Endpoint_Discard_8();
532 /** Routine to process an issued command from the host, via a DFU_DNLOAD request wrapper. This routine ensures
533 * that the command is allowed based on the current secure mode flag value, and passes the command off to the
534 * appropriate handler function.
536 static void ProcessBootloaderCommand(void)
538 /* Check if device is in secure mode */
541 /* Don't process command unless it is a READ or chip erase command */
542 if (!(((SentCommand
.Command
== COMMAND_WRITE
) &&
543 IS_TWOBYTE_COMMAND(SentCommand
.Data
, 0x00, 0xFF)) ||
544 (SentCommand
.Command
== COMMAND_READ
)))
546 /* Set the state and status variables to indicate the error */
547 DFU_State
= dfuERROR
;
548 DFU_Status
= errWRITE
;
551 Endpoint_StallTransaction();
553 /* Don't process the command */
558 /* Dispatch the required command processing routine based on the command type */
559 switch (SentCommand
.Command
)
561 case COMMAND_PROG_START
:
562 ProcessMemProgCommand();
564 case COMMAND_DISP_DATA
:
565 ProcessMemReadCommand();
568 ProcessWriteCommand();
571 ProcessReadCommand();
573 case COMMAND_CHANGE_BASE_ADDR
:
574 if (IS_TWOBYTE_COMMAND(SentCommand
.Data
, 0x03, 0x00)) // Set 64KB flash page command
575 Flash64KBPage
= SentCommand
.Data
[2];
581 /** Routine to concatenate the given pair of 16-bit memory start and end addresses from the host, and store them
582 * in the StartAddr and EndAddr global variables.
584 static void LoadStartEndAddresses(void)
590 } Address
[2] = {{.Bytes
= {SentCommand
.Data
[2], SentCommand
.Data
[1]}},
591 {.Bytes
= {SentCommand
.Data
[4], SentCommand
.Data
[3]}}};
593 /* Load in the start and ending read addresses from the sent data packet */
594 StartAddr
= Address
[0].Word
;
595 EndAddr
= Address
[1].Word
;
598 /** Handler for a Memory Program command issued by the host. This routine handles the preparations needed
599 * to write subsequent data from the host into the specified memory.
601 static void ProcessMemProgCommand(void)
603 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x00) || // Write FLASH command
604 IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x01)) // Write EEPROM command
606 /* Load in the start and ending read addresses */
607 LoadStartEndAddresses();
609 /* If FLASH is being written to, we need to pre-erase the first page to write to */
610 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x00))
616 } CurrFlashAddress
= {.Words
= {StartAddr
, Flash64KBPage
}};
618 /* Erase the current page's temp buffer */
619 boot_page_erase(CurrFlashAddress
.Long
);
620 boot_spm_busy_wait();
623 /* Set the state so that the next DNLOAD requests reads in the firmware */
624 DFU_State
= dfuDNLOAD_IDLE
;
628 /** Handler for a Memory Read command issued by the host. This routine handles the preparations needed
629 * to read subsequent data from the specified memory out to the host, as well as implementing the memory
630 * blank check command.
632 static void ProcessMemReadCommand(void)
634 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x00) || // Read FLASH command
635 IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x02)) // Read EEPROM command
637 /* Load in the start and ending read addresses */
638 LoadStartEndAddresses();
640 /* Set the state so that the next UPLOAD requests read out the firmware */
641 DFU_State
= dfuUPLOAD_IDLE
;
643 else if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x01)) // Blank check FLASH command
645 uint32_t CurrFlashAddress
= 0;
647 while (CurrFlashAddress
< BOOT_START_ADDR
)
649 /* Check if the current byte is not blank */
650 #if (FLASHEND > 0xFFFF)
651 if (pgm_read_byte_far(CurrFlashAddress
) != 0xFF)
653 if (pgm_read_byte(CurrFlashAddress
) != 0xFF)
656 /* Save the location of the first non-blank byte for response back to the host */
657 Flash64KBPage
= (CurrFlashAddress
>> 16);
658 StartAddr
= CurrFlashAddress
;
660 /* Set state and status variables to the appropriate error values */
661 DFU_State
= dfuERROR
;
662 DFU_Status
= errCHECK_ERASED
;
672 /** Handler for a Data Write command issued by the host. This routine handles non-programming commands such as
673 * bootloader exit (both via software jumps and hardware watchdog resets) and flash memory erasure.
675 static void ProcessWriteCommand(void)
677 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x03)) // Start application
679 /* Indicate that the bootloader is terminating */
682 /* Check if data supplied for the Start Program command - no data executes the program */
683 if (SentCommand
.DataSize
)
685 if (SentCommand
.Data
[1] == 0x01) // Start via jump
691 } Address
= {.Bytes
= {SentCommand
.Data
[4], SentCommand
.Data
[3]}};
693 /* Load in the jump address into the application start address pointer */
694 AppStartPtr
= Address
.FuncPtr
;
699 if (SentCommand
.Data
[1] == 0x00) // Start via watchdog
701 /* Start the watchdog to reset the AVR once the communications are finalized */
702 wdt_enable(WDTO_250MS
);
704 else // Start via jump
706 /* Set the flag to terminate the bootloader at next opportunity */
707 RunBootloader
= false;
711 else if (IS_TWOBYTE_COMMAND(SentCommand
.Data
, 0x00, 0xFF)) // Erase flash
713 uint32_t CurrFlashAddress
= 0;
715 /* Clear the application section of flash */
716 while (CurrFlashAddress
< BOOT_START_ADDR
)
718 boot_page_erase(CurrFlashAddress
);
719 boot_spm_busy_wait();
720 boot_page_write(CurrFlashAddress
);
721 boot_spm_busy_wait();
723 CurrFlashAddress
+= SPM_PAGESIZE
;
726 /* Re-enable the RWW section of flash as writing to the flash locks it out */
729 /* Memory has been erased, reset the security bit so that programming/reading is allowed */
734 /** Handler for a Data Read command issued by the host. This routine handles bootloader information retrieval
735 * commands such as device signature and bootloader version retrieval.
737 static void ProcessReadCommand(void)
739 const uint8_t BootloaderInfo
[3] = {BOOTLOADER_VERSION
, BOOTLOADER_ID_BYTE1
, BOOTLOADER_ID_BYTE2
};
740 const uint8_t SignatureInfo
[3] = {AVR_SIGNATURE_1
, AVR_SIGNATURE_2
, AVR_SIGNATURE_3
};
742 uint8_t DataIndexToRead
= SentCommand
.Data
[1];
744 if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x00)) // Read bootloader info
745 ResponseByte
= BootloaderInfo
[DataIndexToRead
];
746 else if (IS_ONEBYTE_COMMAND(SentCommand
.Data
, 0x01)) // Read signature byte
747 ResponseByte
= SignatureInfo
[DataIndexToRead
- 0x30];