Bootloaders/DFU/BootloaderDFU.h

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