text: //###########################################################################
  //
  // usbdfu.h - Definitions related to the USB Device Firmware Upgrade class.
  //
  //###########################################################################
  // $TI Release: F2806x Support Library v2.04.00.00 $
  // $Release Date: Thu Oct 18 15:47:20 CDT 2018 $
  // $Copyright:
  // Copyright (C) 2009-2018 Texas Instruments Incorporated - http://www.ti.com/
  //
  // Redistribution and use in source and binary forms, with or without 
  // modification, are permitted provided that the following conditions 
  // are met:
  // 
  //   Redistributions of source code must retain the above copyright 
  //   notice, this list of conditions and the following disclaimer.
  // 
  //   Redistributions in binary form must reproduce the above copyright
  //   notice, this list of conditions and the following disclaimer in the 
  //   documentation and/or other materials provided with the   
  //   distribution.
  // 
  //   Neither the name of Texas Instruments Incorporated nor the names of
  //   its contributors may be used to endorse or promote products derived
  //   from this software without specific prior written permission.
  // 
  // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
  // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
  // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
  // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
  // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
  // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
  // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
  // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  // $
  //###########################################################################
  
  #ifndef __USBDFU_H__
  #define __USBDFU_H__
  
  //*****************************************************************************
  //
  // DFU attributes as published in the functional descriptor.
  //
  //*****************************************************************************
  #define DFU_ATTR_WILL_DETACH        0x08
  #define DFU_ATTR_MANIFEST_TOLERANT  0x04
  #define DFU_ATTR_CAN_UPLOAD         0x02
  #define DFU_ATTR_CAN_DOWNLOAD       0x01
  
  //*****************************************************************************
  //
  // The states that the DFU device can be in.  These values are reported to
  // the host in response to a USBD_DFU_REQUEST_GETSTATE request.
  //
  //*****************************************************************************
  typedef enum
  {
     STATE_APP_IDLE = 0,
     STATE_APP_DETACH,
     STATE_IDLE,
     STATE_DNLOAD_SYNC,
     STATE_DNBUSY,
     STATE_DNLOAD_IDLE,
     STATE_MANIFEST_SYNC,
     STATE_MANIFEST,
     STATE_MANIFEST_WAIT_RESET,
     STATE_UPLOAD_IDLE,
     STATE_ERROR
  }
  tDFUState;
  
  //*****************************************************************************
  //
  // The current error status of the DFU device.  These values are reported to
  // the host in response to a USBD_DFU_REQUEST_GETSTATUS request.
  //
  //*****************************************************************************
  typedef enum
  {
     STATUS_OK = 0,
     STATUS_ERR_TARGET,
     STATUS_ERR_FILE,
     STATUS_ERR_WRITE,
     STATUS_ERR_ERASE,
     STATUS_ERR_CHECK_ERASED,
     STATUS_ERR_PROG,
     STATUS_ERR_VERIFY,
     STATUS_ERR_ADDRESS,
     STATUS_ERR_NOTDONE,
     STATUS_ERR_FIRMWARE,
     STATUS_ERR_VENDOR,
     STATUS_ERR_USBR,
     STATUS_ERR_POR,
     STATUS_ERR_UNKNOWN,
     STATUS_ERR_STALLEDPKT
  }
  tDFUStatus;
  
  //*****************************************************************************
  //
  // The descriptor type for the DFU functional descriptor.
  //
  //*****************************************************************************
  #define USB_DFU_FUNC_DESCRIPTOR_TYPE   0x21
  
  //*****************************************************************************
  //
  // The subclass identifier for DFU as reported to the host in the
  // bInterfaceSubClass field of the DFU interface descriptor.
  //
  //*****************************************************************************
  #define USB_DFU_SUBCLASS                0x01
  
  //*****************************************************************************
  //
  // The protocol identifier for DFU as reported to the host in the
  // bInterfaceProtocol field of the DFU interface descriptor.
  //
  //*****************************************************************************
  #define USB_DFU_PROTOCOL                0x02
  #define USB_DFU_RUNTIME_PROTOCOL        0x01
  
  //*****************************************************************************
  //
  // DFU class-specific request identifiers.
  //
  //*****************************************************************************
  #define USBD_DFU_REQUEST_DETACH         0
  #define USBD_DFU_REQUEST_DNLOAD         1
  #define USBD_DFU_REQUEST_UPLOAD         2
  #define USBD_DFU_REQUEST_GETSTATUS      3
  #define USBD_DFU_REQUEST_CLRSTATUS      4
  #define USBD_DFU_REQUEST_GETSTATE       5
  #define USBD_DFU_REQUEST_ABORT          6
  
  //*****************************************************************************
  //
  // Request 1KB blocks from the host.  This value is published in the USB
  // functional descriptor.
  //
  //*****************************************************************************
  #define DFU_TRANSFER_SIZE       1024
  
  //*****************************************************************************
  //
  // TI-specific request identifier.  This is used to determine whether
  // the target device supports our DFU command protocol.  It is expected that
  // a device not supporting our extensions will stall this request.  This
  // request is only supported while the DFU device is in STATE_IDLE.
  //
  // An IN request containing the following parameters will result in the device
  // sending back a tDFUQueryTIProtocol structure indicating that TI
  // extensions are supported.  The actual values in wValue and wIndex have no
  // meaning other than to act as markers in the unlikely event that another
  // DFU device also choses to use request ID 0x42 for some other purpose.
  //
  // wValue        - 0x23(REQUEST_TI_VALUE)
  // wIndex        - Interface number
  // wLength       - sizeof(tDFUQueryTIProtocol)
  //
  //*****************************************************************************
  #define USBD_DFU_REQUEST_TI    0x42
  
  #define REQUEST_TI_VALUE 0x23
  
  #define TI_DFU_PROTOCOL_MARKER               0x4C4D
  #define TI_DFU_PROTOCOL_VERSION_STELLARIS_1  0x0001
  #define TI_DFU_PROTOCOL_VERSION_C2000_1      0x2001
  
  //*****************************************************************************
  //
  // The various features that the bootloader potentially supports
  //
  //*****************************************************************************
  #define TI_FEATURE_FAILSAFE                  0x00000001
  #define TI_FEATURE_READ                      0x00000004
  #define TI_FEATURE_DECRYPTION                0x00000008
  
  //*****************************************************************************
  //
  // The structure sent to the host when a valid USBD_DFU_REQUEST_TI is
  // received while the DFU device is in idle state.
  //
  //*****************************************************************************
  typedef struct
  {
      tShort usMarker;        // LM_DFU_PROTOCOL_MARKER
      tShort usVersion;       // LM_DFU_PROTOCOL_VERSION_1
  }
  PACKED tDFUQueryTIProtocol;
  
  //*****************************************************************************
  //
  // Structure sent to the host in response to USBD_DFU_REQUEST_GETSTATUS.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char bStatus;
      unsigned char bwPollTimeout[3];
      unsigned char bState;
      unsigned char iString;
  }
  PACKED tDFUGetStatusResponse;
  
  //*****************************************************************************
  //
  // Firmware Download Commands
  //
  // The data passed on a USBD_DFU_REQUEST_DNLOAD request is comprised of a
  // header which instructs the boot loader how to interpret the block and
  // block-specific data.  The following definitions relate to the download
  // block headers.
  //
  //*****************************************************************************
  
  //*****************************************************************************
  //
  // Supported command identifiers
  //
  //*****************************************************************************
  #define DFU_CMD_PROG  0x01
  #define DFU_CMD_READ  0x02
  #define DFU_CMD_CHECK 0x03
  #define DFU_CMD_ERASE 0x04
  #define DFU_CMD_INFO  0x05
  #define DFU_CMD_BIN   0x06
  #define DFU_CMD_RESET 0x07
  #define DFU_CMD_CSM   0x08
  
  //*****************************************************************************
  //
  // Generic download command header.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char ucCommand;     // Command identifier.
      unsigned char ucData[7];     // Command-specific data elements.
  }
  PACKED tDFUDownloadHeader;
  
  //*****************************************************************************
  //
  // Header for the DFU_CMD_PROG command.
  //
  // This command is used to program a section of the flash with the binary data
  // which immediately follows the header. The start address of the data is
  // expressed as a 1KB block number so 0 would represent the bottom of flash
  // (which, incidentally, the USB boot loader will not let you program) and 0x10
  // would represent address 16KB or 16384 (0x4000).  The usLength field contains
  // the total number of bytes of data in the following programming operation.
  // The DFU device will not look for any command header on following
  // USBD_DFU_REQUEST_DNLOAD requests until the operation is completed or
  // aborted.
  //
  // By using this protocol, the DFU_CMD_PROG command header may be used as a
  // simple header on the binary files to be sent to the DFU device for
  // programming.  If we enforce the requirement that the DFU_CMD_PROG header is
  // applied to each USBD_DFU_REQUEST_DNLOAD (one per block), this means that the
  // host-side DFU application must be aware of the underlying protocol and
  // insert these headers dynamically during programming operations.  This could
  // be handled by post processing the binary to insert the headers at the
  // appropriate points but this would then tie the binary structure to the
  // chosen transfer size and break the operation if the transfer size were to
  // change in the future.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char  ucCommand;   // DFU_CMD_PROG
      unsigned char  ucReserved;  // Reserved - set to 0x00.
      tShort         usStartAddr; // Block start address / 1024
      
      //
      // Total length, in bytes, of following data for the complete 
      // download operation.
      //
      tLong          ulLength;
  }
  PACKED tDFUDownloadProgHeader;
  
  //*****************************************************************************
  //
  // Header for the DFU_CMD_READ and DFU_CMD_CHECK commands.
  //
  // This command may be used to set the address range whose content will be
  // returned on subsequent USBD_DFU_REQUEST_UPLOAD requests from the host.
  //
  // To read back a the contents of a region of flash, the host should send
  // USBD_DFU_REQUEST_DNLOAD with ucCommand DFU_CMD_READ, usStartAddr set to the
  // 1KB block start address and ulLength set to the number of bytes to read.
  // The host should then send one or more USBD_DFU_REQUEST_UPLOAD requests
  // to receive the current flash contents from the configured addresses.  Data
  // returned will include an 8 byte DFU_CMD_PROG prefix structure unless
  // the prefix has been disabled by sending a DFU_CMD_BIN command with the
  // bBinary parameter set to 1.
  //
  // To check that a region of flash is erased, the DFU_CMD_CHECK command should
  // be sent with usStartAddr and ulLength set to describe the region to check.
  // The host should then send a USBD_DFU_REQUEST_GETSTATUS.  If the erase check
  // was successful, the returned bStatus value will be STATUS_OK, otherwise it
  // will be STATUS_ERR_CHECK_ERASED. Note that ulLength passed must be a
  // a multiple of 4.  If this is not the case, the value will be truncated before
  // the check is performed.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char  ucCommand;    // DFU_CMD_READ or DFU_CMD_CHECK
      unsigned char  ucReserved;   // Reserved - write to 0
      tShort         usStartAddr;  // Block start address / 1024
      
      //
      // The number of bytes of data to read back or check.
      //
      tLong          ulLength;     
  }
  PACKED tDFUDownloadReadCheckHeader;
  
  //*****************************************************************************
  //
  // Header for the DFU_CMD_ERASE command.
  //
  // This command may be used to erase a number of flash blocks.  The address of
  // the first block to be erased is passed in usStartAddr with usNumBlocks
  // containing the number of blocks to be erased from this address.  The block
  // size of the device may be determined using the DFU_CMD_INFO command.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char  ucCommand;      // DFU_CMD_ERASE
      unsigned char  ucReserved;     // Reserved - set to 0.
      tShort         usStartAddr;    // Block start address / 1024
      tShort         usNumBlocks;    // The number of blocks to erase.
      unsigned char  ucReserved2[2]; // Reserved - set to 0.
  }
  PACKED tDFUDownloadEraseHeader;
  
  //*****************************************************************************
  //
  // Header for the DFU_CMD_INFO command.
  //
  // This command may be used to query information about the connected device.
  // After sending the command, the information is returned on the next
  // USBD_DFU_REQUEST_UPLOAD request.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char ucCommand;     // DFU_CMD_INFO
      unsigned char ucReserved[7]; // Reserved - set to 0.
  }
  PACKED tDFUDownloadInfoHeader;
  
  
  //*****************************************************************************
  //
  // Header for the DFU_CMD_BIN command.
  //
  // This command may be used to set the format of uploaded data.  By default,
  // images read using USBD_DFU_REQUEST_UPLOAD are formatted with the appropriate
  // header to allow the same image to be flashed back to the device and have it
  // located at the address from which it originated.  This is a requirement of
  // the DFU class specification (section 6.2 "the uploaded image must be
  // usable in a subsequent download") but may not be helpful in some cases where
  // the application wishes to receive only the binary image from flash.  To
  // instruct the DFU device to omit the position and size header, send this
  // command with the bBinary field set to \b true prior to issuing a
  // USBD_DFU_REQUEST_UPLOAD for image data.  The format choice remains in effect
  // until the command is sent once again with bBinary set to \b false.
  //
  // Note that the format choice affects only image data sent and not responses
  // read via USBD_DFU_REQUEST_UPLOAD following TI-specific commands such
  // as DFU_CMD_INFO.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char ucCommand;     // DFU_CMD_BIN
      unsigned char bBinary;       // Set to true to omit image header or false
                                   // to include it (the default).
      unsigned char ucReserved[6]; // Reserved - set to 0.
  }
  PACKED tDFUDownloadBinHeader;
  
  //*****************************************************************************
  //
  // The DFU_CMD_RESET command uses a tDFUDownloadHeader structure since
  // only the ucCommand field is important.  This command causes an immediate
  // reset of the the target board.
  //
  //*****************************************************************************
  
  //*****************************************************************************
  //
  // Header for the DFU_CMD_CSM command.
  //
  // This command may be used to lock and unlock the target device.  When ucLock
  // is asserted the device will immediately be locked.  When ucLock false (and 
  // ucSize is 0) the device will generate a 16 byte seed which can be returned 
  // to the host with a DFU_UPLOAD command.  After the host has recieved the 
  // seed, they can calculate the 16 byte key by running 128 bit AES over the 
  // seed.  They key is then returned to the device by sending another
  // another CSM command followed by the key.
  //
  //*****************************************************************************
  typedef struct
  {
      unsigned char  ucCommand;      // DFU_CMD_CSM (0x08)
      unsigned char  ucReserved;     // Reserved - set to 0.
      unsigned char  ucLock;         // Lock device if asserted, otherwise unlock
      unsigned char  ucSize;         // Size of key appended to command
      unsigned char  ucReserved2[4]; // Reserved - set to 0.
  }
  PACKED tDFUDownloadCSMHeader;
  
  //*****************************************************************************
  //
  //! Payload returned in response to the DFU_CMD_INFO command.
  //!
  //! This is structure is returned in response to the first
  //! USBD_DFU_REQUEST_UPLOAD request following a DFU_CMD_INFO command.
  //
  //*****************************************************************************
  typedef struct
  {
      //
      //! The size of a flash block in bytes.
      //
      tShort usFlashBlockSize;
  
      //
      //! The number of blocks of flash in the  device.  Total flash size is
      //! usNumFlashBlocks * usFlashBlockSize.
      //
      tShort usNumFlashBlocks;
  
      //
      //! Information on the part number, family, version and package as
      //! read from the PARTID register.
      //
      tLong ulPartInfo;
  
      //
      //! Information on the part class and revision as read from the CLASSID 
      //! register.
      //
      tLong ulClassInfo;
  
      //
      //! Address 1 byte above the highest location the boot loader can access.
      //
      tLong ulFlashTop;
  
      //
      //! Lowest address the boot loader can write or erase.
      //
      tLong ulAppStartAddr;
      
      //
      //! Features supported by the bootloader
      //
      tLong ulFeatures;
      
      //
      //! If true the device is locked and flash reads/writes are disallowed
      //
      unsigned char ucLocked;
  }
  PACKED tDFUDeviceInfo;
  
  #endif // __USBDFU_H__
  
  //
  // End of File
  //
  
  