BootloaderDFU.h 7.51 KB
Newer Older
1 2 3
/*
             LUFA Library
     Copyright (C) Dean Camera, 2010.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7 8 9 10 11
*/

/*
  Copyright 2010  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 17 18
  permission notice and warranty disclaimer appear in supporting
  documentation, and that the name of the author not be used in
  advertising or publicity pertaining to distribution of the
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
  software without specific, written prior permission.

  The author disclaim all warranties with regard to this
  software, including all implied warranties of merchantability
  and fitness.  In no event shall the author be liable for any
  special, indirect or consequential damages or any damages
  whatsoever resulting from loss of use, data or profits, whether
  in an action of contract, negligence or other tortious action,
  arising out of or in connection with the use or performance of
  this software.
*/

/** \file
 *
 *  Header file for BootloaderDFU.c.
 */

#ifndef _BOOTLOADER_H_
#define _BOOTLOADER_H_

	/* Includes: */
		#include <avr/io.h>
		#include <avr/wdt.h>
		#include <avr/boot.h>
		#include <avr/pgmspace.h>
		#include <avr/eeprom.h>
		#include <avr/power.h>
		#include <avr/interrupt.h>
		#include <stdbool.h>
48

49
		#include "Descriptors.h"
50

51
		#include <LUFA/Drivers/USB/USB.h>
52

53 54 55 56 57 58 59 60 61 62 63 64 65 66
	/* Macros: */
		/** Configuration define. Define this token to true to case the bootloader to reject all memory commands
		 *  until a memory erase has been performed. When used in conjunction with the lockbits of the AVR, this
		 *  can protect the AVR's firmware from being dumped from a secured AVR. When false, memory operations are
		 *  allowed at any time.
		 */
		#define SECURE_MODE              false

		/** Major bootloader version number. */
		#define BOOTLOADER_VERSION_MINOR 2

		/** Minor bootloader version number. */
		#define BOOTLOADER_VERSION_REV   0

67
		/** Complete bootloader version number expressed as a packed byte, constructed from the
68 69 70 71 72 73 74 75 76
		 *  two individual bootloader version macros.
		 */
		#define BOOTLOADER_VERSION       ((BOOTLOADER_VERSION_MINOR << 4) | BOOTLOADER_VERSION_REV)

		/** First byte of the bootloader identification bytes, used to identify a device's bootloader. */
		#define BOOTLOADER_ID_BYTE1      0xDC

		/** Second byte of the bootloader identification bytes, used to identify a device's bootloader. */
		#define BOOTLOADER_ID_BYTE2      0xFB
77

78 79 80 81 82 83 84 85 86 87 88 89 90 91
		/** Convenience macro, used to determine if the issued command is the given one-byte long command.
		 *
		 *  \param[in] dataarr  Command byte array to check against
		 *  \param[in] cb1      First command byte to check
		 */
		#define IS_ONEBYTE_COMMAND(dataarr, cb1)       (dataarr[0] == (cb1))

		/** Convenience macro, used to determine if the issued command is the given two-byte long command.
		 *
		 *  \param[in] dataarr  Command byte array to check against
		 *  \param[in] cb1      First command byte to check
		 *  \param[in] cb2      Second command byte to check
		 */
		#define IS_TWOBYTE_COMMAND(dataarr, cb1, cb2) ((dataarr[0] == (cb1)) && (dataarr[1] == (cb2)))
92

93 94 95 96 97 98 99 100 101 102
		/** Length of the DFU file suffix block, appended to the end of each complete memory write command.
		 *  The DFU file suffix is currently unused (but is designed to give extra file information, such as
		 *  a CRC of the complete firmware for error checking) and so is discarded.
		 */
		#define DFU_FILE_SUFFIX_SIZE     16

		/** Length of the DFU file filler block, appended to the start of each complete memory write command.
		 *  Filler bytes are added to the start of each complete memory write command, and must be discarded.
		 */
		#define DFU_FILLER_BYTES_SIZE    26
103

104
		/** DFU class command request to detach from the host. */
105
		#define REQ_DFU_DETATCH          0x00
106 107

		/** DFU class command request to send data from the host to the bootloader. */
108
		#define REQ_DFU_DNLOAD           0x01
109 110

		/** DFU class command request to send data from the bootloader to the host. */
111
		#define REQ_DFU_UPLOAD           0x02
112 113

		/** DFU class command request to get the current DFU status and state from the bootloader. */
114
		#define REQ_DFU_GETSTATUS        0x03
115 116

		/** DFU class command request to reset the current DFU status and state variables to their defaults. */
117
		#define REQ_DFU_CLRSTATUS        0x04
118 119

		/** DFU class command request to get the current DFU state of the bootloader. */
120
		#define REQ_DFU_GETSTATE         0x05
121 122

		/** DFU class command request to abort the current multi-request transfer and return to the dfuIDLE state. */
123
		#define REQ_DFU_ABORT            0x06
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143

		/** DFU command to begin programming the device's memory. */
		#define COMMAND_PROG_START       0x01

		/** DFU command to begin reading the device's memory. */
		#define COMMAND_DISP_DATA        0x03

		/** DFU command to issue a write command. */
		#define COMMAND_WRITE            0x04

		/** DFU command to issue a read command. */
		#define COMMAND_READ             0x05

		/** DFU command to issue a memory base address change command, to set the current 64KB flash page
		 *  that subsequent flash operations should use. */
		#define COMMAND_CHANGE_BASE_ADDR 0x06

	/* Type Defines: */
		/** Type define for a non-returning function pointer to the loaded application. */
		typedef void (*AppPtr_t)(void) ATTR_NO_RETURN;
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 189
		/** Type define for a structure containing a complete DFU command issued by the host. */
		typedef struct
		{
			uint8_t  Command; /**< Single byte command to perform, one of the COMMAND_* macro values */
			uint8_t  Data[5]; /**< Command parameters */
			uint16_t DataSize; /**< Size of the command parameters */
		} DFU_Command_t;

	/* Enums: */
		/** DFU bootloader states. Refer to the DFU class specification for information on each state. */
		enum DFU_State_t
		{
			appIDLE                      = 0,
			appDETACH                    = 1,
			dfuIDLE                      = 2,
			dfuDNLOAD_SYNC               = 3,
			dfuDNBUSY                    = 4,
			dfuDNLOAD_IDLE               = 5,
			dfuMANIFEST_SYNC             = 6,
			dfuMANIFEST                  = 7,
			dfuMANIFEST_WAIT_RESET       = 8,
			dfuUPLOAD_IDLE               = 9,
			dfuERROR	                 = 10
		};

		/** DFU command status error codes. Refer to the DFU class specification for information on each error code. */
		enum DFU_Status_t
		{
			OK                           = 0,
			errTARGET                    = 1,
			errFILE                      = 2,
			errWRITE                     = 3,
			errERASE                     = 4,
			errCHECK_ERASED              = 5,
			errPROG                      = 6,
			errVERIFY                    = 7,
			errADDRESS                   = 8,
			errNOTDONE                   = 9,
			errFIRMWARE                  = 10,
			errVENDOR                    = 11,
			errUSBR                      = 12,
			errPOR                       = 13,
			errUNKNOWN                   = 14,
			errSTALLEDPKT	             = 15
		};
190

191 192 193 194
	/* Function Prototypes: */
		void SetupHardware(void);
		void ResetHardware(void);

195
		void EVENT_USB_Device_ControlRequest(void);
196 197 198 199 200 201 202 203 204 205

		#if defined(INCLUDE_FROM_BOOTLOADER_C)
			static void DiscardFillerBytes(uint8_t NumberOfBytes);
			static void ProcessBootloaderCommand(void);
			static void LoadStartEndAddresses(void);
			static void ProcessMemProgCommand(void);
			static void ProcessMemReadCommand(void);
			static void ProcessWriteCommand(void);
			static void ProcessReadCommand(void);
		#endif
206

207
#endif
208