Bootloaders/DFU/BootloaderDFU.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2014.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2014  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  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.
  20
  21   The author disclaims 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
  28   this software.
  29 */
  30
  31 /** \file
  32  *
  33  *  Header file for BootloaderDFU.c.
  34  */
  35
  36 #ifndef _BOOTLOADER_H_
  37 #define _BOOTLOADER_H_
  38
  39         /* Includes: */
  40                 #include <avr/io.h>
  41                 #include <avr/wdt.h>
  42                 #include <avr/boot.h>
  43                 #include <avr/pgmspace.h>
  44                 #include <avr/eeprom.h>
  45                 #include <avr/power.h>
  46                 #include <avr/interrupt.h>
  47                 #include <util/delay.h>
  48                 #include <stdbool.h>
  49
  50                 #include "Descriptors.h"
  51                 #include "BootloaderAPI.h"
  52                 #include "Config/AppConfig.h"
  53
  54                 #include <LUFA/Drivers/USB/USB.h>
  55                 #include <LUFA/Drivers/Board/LEDs.h>
  56                 #include <LUFA/Platform/Platform.h>
  57
  58         /* Preprocessor Checks: */
  59                 #if !defined(__OPTIMIZE_SIZE__)
  60                         #error This bootloader requires that it be optimized for size, not speed, to fit into the target device. Change optimization settings and try again.
  61                 #endif
  62
  63         /* Macros: */
  64                 /** Major bootloader version number. */
  65                 #define BOOTLOADER_VERSION_MINOR 2
  66
  67                 /** Minor bootloader version number. */
  68                 #define BOOTLOADER_VERSION_REV   0
  69
  70                 /** Magic bootloader key to unlock forced application start mode. */
  71                 #define MAGIC_BOOT_KEY           0xDC42
  72
  73                 /** Complete bootloader version number expressed as a packed byte, constructed from the
  74                  *  two individual bootloader version macros.
  75                  */
  76                 #define BOOTLOADER_VERSION       ((BOOTLOADER_VERSION_MINOR << 4) | BOOTLOADER_VERSION_REV)
  77
  78                 /** First byte of the bootloader identification bytes, used to identify a device's bootloader. */
  79                 #define BOOTLOADER_ID_BYTE1      0xDC
  80
  81                 /** Second byte of the bootloader identification bytes, used to identify a device's bootloader. */
  82                 #define BOOTLOADER_ID_BYTE2      0xFB
  83
  84                 /** Convenience macro, used to determine if the issued command is the given one-byte long command.
  85                  *
  86                  *  \param[in] dataarr  Command byte array to check against
  87                  *  \param[in] cb1      First command byte to check
  88                  */
  89                 #define IS_ONEBYTE_COMMAND(dataarr, cb1)       (dataarr[0] == (cb1))
  90
  91                 /** Convenience macro, used to determine if the issued command is the given two-byte long command.
  92                  *
  93                  *  \param[in] dataarr  Command byte array to check against
  94                  *  \param[in] cb1      First command byte to check
  95                  *  \param[in] cb2      Second command byte to check
  96                  */
  97                 #define IS_TWOBYTE_COMMAND(dataarr, cb1, cb2) ((dataarr[0] == (cb1)) && (dataarr[1] == (cb2)))
  98
  99                 /** Length of the DFU file suffix block, appended to the end of each complete memory write command.
 100                  *  The DFU file suffix is currently unused (but is designed to give extra file information, such as
 101                  *  a CRC of the complete firmware for error checking) and so is discarded.
 102                  */
 103                 #define DFU_FILE_SUFFIX_SIZE     16
 104
 105                 /** Length of the DFU file filler block, appended to the start of each complete memory write command.
 106                  *  Filler bytes are added to the start of each complete memory write command, and must be discarded.
 107                  */
 108                 #define DFU_FILLER_BYTES_SIZE    26
 109
 110                 /** DFU class command request to detach from the host. */
 111                 #define DFU_REQ_DETATCH          0x00
 112
 113                 /** DFU class command request to send data from the host to the bootloader. */
 114                 #define DFU_REQ_DNLOAD           0x01
 115
 116                 /** DFU class command request to send data from the bootloader to the host. */
 117                 #define DFU_REQ_UPLOAD           0x02
 118
 119                 /** DFU class command request to get the current DFU status and state from the bootloader. */
 120                 #define DFU_REQ_GETSTATUS        0x03
 121
 122                 /** DFU class command request to reset the current DFU status and state variables to their defaults. */
 123                 #define DFU_REQ_CLRSTATUS        0x04
 124
 125                 /** DFU class command request to get the current DFU state of the bootloader. */
 126                 #define DFU_REQ_GETSTATE         0x05
 127
 128                 /** DFU class command request to abort the current multi-request transfer and return to the dfuIDLE state. */
 129                 #define DFU_REQ_ABORT            0x06
 130
 131                 /** DFU command to begin programming the device's memory. */
 132                 #define COMMAND_PROG_START       0x01
 133
 134                 /** DFU command to begin reading the device's memory. */
 135                 #define COMMAND_DISP_DATA        0x03
 136
 137                 /** DFU command to issue a write command. */
 138                 #define COMMAND_WRITE            0x04
 139
 140                 /** DFU command to issue a read command. */
 141                 #define COMMAND_READ             0x05
 142
 143                 /** DFU command to issue a memory base address change command, to set the current 64KB flash page
 144                  *  that subsequent flash operations should use. */
 145                 #define COMMAND_CHANGE_BASE_ADDR 0x06
 146
 147         /* Type Defines: */
 148                 /** Type define for a non-returning function pointer to the loaded application. */
 149                 typedef void (*AppPtr_t)(void) ATTR_NO_RETURN;
 150
 151                 /** Type define for a structure containing a complete DFU command issued by the host. */
 152                 typedef struct
 153                 {
 154                         uint8_t  Command; /**< Single byte command to perform, one of the \c COMMAND_* macro values */
 155                         uint8_t  Data[5]; /**< Command parameters */
 156                         uint16_t DataSize; /**< Size of the command parameters */
 157                 } DFU_Command_t;
 158
 159         /* Enums: */
 160                 /** DFU bootloader states. Refer to the DFU class specification for information on each state. */
 161                 enum DFU_State_t
 162                 {
 163                         appIDLE                      = 0,
 164                         appDETACH                    = 1,
 165                         dfuIDLE                      = 2,
 166                         dfuDNLOAD_SYNC               = 3,
 167                         dfuDNBUSY                    = 4,
 168                         dfuDNLOAD_IDLE               = 5,
 169                         dfuMANIFEST_SYNC             = 6,
 170                         dfuMANIFEST                  = 7,
 171                         dfuMANIFEST_WAIT_RESET       = 8,
 172                         dfuUPLOAD_IDLE               = 9,
 173                         dfuERROR                     = 10
 174                 };
 175
 176                 /** DFU command status error codes. Refer to the DFU class specification for information on each error code. */
 177                 enum DFU_Status_t
 178                 {
 179                         OK                           = 0,
 180                         errTARGET                    = 1,
 181                         errFILE                      = 2,
 182                         errWRITE                     = 3,
 183                         errERASE                     = 4,
 184                         errCHECK_ERASED              = 5,
 185                         errPROG                      = 6,
 186                         errVERIFY                    = 7,
 187                         errADDRESS                   = 8,
 188                         errNOTDONE                   = 9,
 189                         errFIRMWARE                  = 10,
 190                         errVENDOR                    = 11,
 191                         errUSBR                      = 12,
 192                         errPOR                       = 13,
 193                         errUNKNOWN                   = 14,
 194                         errSTALLEDPKT                = 15
 195                 };
 196
 197         /* Function Prototypes: */
 198                 static void SetupHardware(void);
 199                 static void ResetHardware(void);
 200
 201                 void EVENT_USB_Device_ControlRequest(void);
 202
 203                 #if defined(INCLUDE_FROM_BOOTLOADER_C)
 204                         static void DiscardFillerBytes(uint8_t NumberOfBytes);
 205                         static void ProcessBootloaderCommand(void);
 206                         static void LoadStartEndAddresses(void);
 207                         static void ProcessMemProgCommand(void);
 208                         static void ProcessMemReadCommand(void);
 209                         static void ProcessWriteCommand(void);
 210                         static void ProcessReadCommand(void);
 211                 #endif
 212
 213                 void Application_Jump_Check(void) ATTR_INIT_SECTION(3);
 214
 215 #endif
 216