Bootloaders/DFU/BootloaderDFU.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  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 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
  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
  52                 #include <LUFA/Drivers/USB/USB.h>
  53
  54         /* Macros: */
  55                 /** Configuration define. Define this token to true to case the bootloader to reject all memory commands
  56                  *  until a memory erase has been performed. When used in conjunction with the lockbits of the AVR, this
  57                  *  can protect the AVR's firmware from being dumped from a secured AVR. When false, memory operations are
  58                  *  allowed at any time.
  59                  */
  60                 #define SECURE_MODE              false
  61
  62                 /** Major bootloader version number. */
  63                 #define BOOTLOADER_VERSION_MINOR 2
  64
  65                 /** Minor bootloader version number. */
  66                 #define BOOTLOADER_VERSION_REV   0
  67
  68                 /** Complete bootloader version number expressed as a packed byte, constructed from the
  69                  *  two individual bootloader version macros.
  70                  */
  71                 #define BOOTLOADER_VERSION       ((BOOTLOADER_VERSION_MINOR << 4) | BOOTLOADER_VERSION_REV)
  72
  73                 /** First byte of the bootloader identification bytes, used to identify a device's bootloader. */
  74                 #define BOOTLOADER_ID_BYTE1      0xDC
  75
  76                 /** Second byte of the bootloader identification bytes, used to identify a device's bootloader. */
  77                 #define BOOTLOADER_ID_BYTE2      0xFB
  78
  79                 /** Convenience macro, used to determine if the issued command is the given one-byte long command.
  80                  *
  81                  *  \param[in] dataarr  Command byte array to check against
  82                  *  \param[in] cb1      First command byte to check
  83                  */
  84                 #define IS_ONEBYTE_COMMAND(dataarr, cb1)       (dataarr[0] == (cb1))
  85
  86                 /** Convenience macro, used to determine if the issued command is the given two-byte long command.
  87                  *
  88                  *  \param[in] dataarr  Command byte array to check against
  89                  *  \param[in] cb1      First command byte to check
  90                  *  \param[in] cb2      Second command byte to check
  91                  */
  92                 #define IS_TWOBYTE_COMMAND(dataarr, cb1, cb2) ((dataarr[0] == (cb1)) && (dataarr[1] == (cb2)))
  93
  94                 /** Length of the DFU file suffix block, appended to the end of each complete memory write command.
  95                  *  The DFU file suffix is currently unused (but is designed to give extra file information, such as
  96                  *  a CRC of the complete firmware for error checking) and so is discarded.
  97                  */
  98                 #define DFU_FILE_SUFFIX_SIZE     16
  99
 100                 /** Length of the DFU file filler block, appended to the start of each complete memory write command.
 101                  *  Filler bytes are added to the start of each complete memory write command, and must be discarded.
 102                  */
 103                 #define DFU_FILLER_BYTES_SIZE    26
 104
 105                 /** DFU class command request to detach from the host. */
 106                 #define REQ_DFU_DETATCH          0x00
 107
 108                 /** DFU class command request to send data from the host to the bootloader. */
 109                 #define REQ_DFU_DNLOAD           0x01
 110
 111                 /** DFU class command request to send data from the bootloader to the host. */
 112                 #define REQ_DFU_UPLOAD           0x02
 113
 114                 /** DFU class command request to get the current DFU status and state from the bootloader. */
 115                 #define REQ_DFU_GETSTATUS        0x03
 116
 117                 /** DFU class command request to reset the current DFU status and state variables to their defaults. */
 118                 #define REQ_DFU_CLRSTATUS        0x04
 119
 120                 /** DFU class command request to get the current DFU state of the bootloader. */
 121                 #define REQ_DFU_GETSTATE         0x05
 122
 123                 /** DFU class command request to abort the current multi-request transfer and return to the dfuIDLE state. */
 124                 #define REQ_DFU_ABORT            0x06
 125
 126                 /** DFU command to begin programming the device's memory. */
 127                 #define COMMAND_PROG_START       0x01
 128
 129                 /** DFU command to begin reading the device's memory. */
 130                 #define COMMAND_DISP_DATA        0x03
 131
 132                 /** DFU command to issue a write command. */
 133                 #define COMMAND_WRITE            0x04
 134
 135                 /** DFU command to issue a read command. */
 136                 #define COMMAND_READ             0x05
 137
 138                 /** DFU command to issue a memory base address change command, to set the current 64KB flash page
 139                  *  that subsequent flash operations should use. */
 140                 #define COMMAND_CHANGE_BASE_ADDR 0x06
 141
 142         /* Type Defines: */
 143                 /** Type define for a non-returning function pointer to the loaded application. */
 144                 typedef void (*AppPtr_t)(void) ATTR_NO_RETURN;
 145
 146                 /** Type define for a structure containing a complete DFU command issued by the host. */
 147                 typedef struct
 148                 {
 149                         uint8_t  Command; /**< Single byte command to perform, one of the COMMAND_* macro values */
 150                         uint8_t  Data[5]; /**< Command parameters */
 151                         uint16_t DataSize; /**< Size of the command parameters */
 152                 } DFU_Command_t;
 153
 154         /* Enums: */
 155                 /** DFU bootloader states. Refer to the DFU class specification for information on each state. */
 156                 enum DFU_State_t
 157                 {
 158                         appIDLE                      = 0,
 159                         appDETACH                    = 1,
 160                         dfuIDLE                      = 2,
 161                         dfuDNLOAD_SYNC               = 3,
 162                         dfuDNBUSY                    = 4,
 163                         dfuDNLOAD_IDLE               = 5,
 164                         dfuMANIFEST_SYNC             = 6,
 165                         dfuMANIFEST                  = 7,
 166                         dfuMANIFEST_WAIT_RESET       = 8,
 167                         dfuUPLOAD_IDLE               = 9,
 168                         dfuERROR                         = 10
 169                 };
 170
 171                 /** DFU command status error codes. Refer to the DFU class specification for information on each error code. */
 172                 enum DFU_Status_t
 173                 {
 174                         OK                           = 0,
 175                         errTARGET                    = 1,
 176                         errFILE                      = 2,
 177                         errWRITE                     = 3,
 178                         errERASE                     = 4,
 179                         errCHECK_ERASED              = 5,
 180                         errPROG                      = 6,
 181                         errVERIFY                    = 7,
 182                         errADDRESS                   = 8,
 183                         errNOTDONE                   = 9,
 184                         errFIRMWARE                  = 10,
 185                         errVENDOR                    = 11,
 186                         errUSBR                      = 12,
 187                         errPOR                       = 13,
 188                         errUNKNOWN                   = 14,
 189                         errSTALLEDPKT                = 15
 190                 };
 191
 192         /* Function Prototypes: */
 193                 void SetupHardware(void);
 194                 void ResetHardware(void);
 195
 196                 void EVENT_USB_Device_ControlRequest(void);
 197
 198                 #if defined(INCLUDE_FROM_BOOTLOADER_C)
 199                         static void DiscardFillerBytes(uint8_t NumberOfBytes);
 200                         static void ProcessBootloaderCommand(void);
 201                         static void LoadStartEndAddresses(void);
 202                         static void ProcessMemProgCommand(void);
 203                         static void ProcessMemReadCommand(void);
 204                         static void ProcessWriteCommand(void);
 205                         static void ProcessReadCommand(void);
 206                 #endif
 207
 208 #endif
 209