//*****************************************************************************
//
// TIDFUprot.h : Private header file containing definitions of Luminary-
//               specific DFU protocol extensions.
//
// Copyright (c) 2008-2011 Texas Instruments Incorporated.  All rights reserved.
// Software License Agreement
// 
// Texas Instruments (TI) is supplying this software for use solely and
// exclusively on TI's microcontroller products. The software is owned by
// TI and/or its suppliers, and is protected under applicable copyright
// laws. You may not combine this software with "viral" open-source
// software in order to form a larger program.
// 
// THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
// NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
// NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
// CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
// DAMAGES, FOR ANY REASON WHATSOEVER.
// 
// This is part of revision 7611 of the TI Firmware Development Package.
//
//*****************************************************************************

#ifndef __TIDFUPROT_H__
#define __TIDFUPROT_H__

//*****************************************************************************
//
// We wait up to 8 seconds for a control transaction to complete before
// timing out.
//
//*****************************************************************************
#define CONTROL_TIMEOUT 8000

//*****************************************************************************
//
// 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

//*****************************************************************************
//
// 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(tTIDFUQueryTIProtocol)
//
//*****************************************************************************
#define USBD_DFU_REQUEST_TI    0x42
#define REQUEST_TI_VALUE 0x23

#define LM_DFU_PROTOCOL_MARKER    0x4C4D
#define LM_DFU_PROTOCOL_VERSION_1 0x2001

#ifndef DEPRECATED
//
// Deprecated definitions included for backwards compatibility
//
#define USBD_DFU_REQUEST_LUMINARY USBD_DFU_REQUEST_TI
#define REQUEST_LUMINARY_VALUE REQUEST_TI_VALUE
#endif

//*****************************************************************************
//
// 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;

//*****************************************************************************
//
// Masks and shifts related to the ulClassInfo field of tDFUDeviceInfo
//
//*****************************************************************************
#define TI_INFO_VER_M       0x70000000  // ClassInfo version mask
#define TI_INFO_VER_SHIFT   28
#define TI_INFO_VER_0       0x00000000  // ClassInfo version 0
#define TI_INFO_VER_1       0x10000000  // ClassInfo version 1
#define TI_INFO_CLASS_M     0x00FF0000  // TI Device Class
#define TI_INFO_CLASS_SHIFT 16
#define TI_INFO_CLASS_DUSTDEVIL \
                                0x00030000    // DustDevil-class Device
#define TI_INFO_CLASS_TEMPEST   \
                                0x00040000    // Tempest-class Device
#define TI_INFO_MAJ_M       0x0000FF00  // Major revision mask
#define TI_INFO_MAJ_SHIFT   8
#define TI_INFO_MIN_M       0x000000FF  // Minor revision mask
#define TI_INFO_MIN_SHIFT   0

#define TI_PART_M           0x00FF0000
#define TI_PART_SHIFT       16

#define TI_ERASE_ALL   1
#define TI_ERASE_BLOCK 0

#ifndef DEPRECATED
//
// Deprecated definitions included for backwards compatibility
//
#define LUMINARY_INFO_VER_M             TI_INFO_VER_M
#define LUMINARY_INFO_VER_SHIFT         TI_INFO_VER_SHIFT
#define LUMINARY_INFO_VER_0             TI_INFO_VER_0
#define LUMINARY_INFO_VER_1             TI_INFO_VER_1
#define LUMINARY_INFO_CLASS_M           TI_INFO_CLASS_M
#define LUMINARY_INFO_CLASS_SHIFT       TI_INFO_CLASS_SHIFT
#define LUMINARY_INFO_CLASS_DUSTDEVIL   TI_INFO_CLASS_DUSTDEVIL
#define LUMINARY_INFO_MAJ_M             TI_INFO_MAJ_M
#define LUMINARY_INFO_MAJ_SHIFT         TI_INFO_MAJ_SHIFT
#define LUMINARY_INFO_MIN_M             TI_INFO_MIN_M
#define LUMINARY_INFO_MIN_SHIFT         TI_INFO_MIN_SHIFT

#define LUMINARY_PART_M                 TI_PART_M
#define LUMINARY_PART_SHIFT             TI_PART_SHIFT

#define LUMINARY_ERASE_ALL              TI_ERASE_ALL
#define LUMINARY_ERASE_BLOCK            TI_ERASE_BLOCK
#endif

//*****************************************************************************
//
// TI-specific command identifiers.  These are passed to the device
// in standard DFU download requests.
//
//*****************************************************************************
#define TI_CMD_PROG  0x01
#define TI_CMD_READ  0x02
#define TI_CMD_CHECK 0x03
#define TI_CMD_ERASE 0x04
#define TI_CMD_INFO  0x05
#define TI_CMD_BIN   0x06
#define TI_CMD_RESET 0x07

#ifndef DEPRECATED
//
// Deprecated definitions included for backwards compatibility
//
#define LUMINARY_CMD_PROG   TI_CMD_PROG
#define LUMINARY_CMD_READ   TI_CMD_READ
#define LUMINARY_CMD_CHECK  TI_CMD_CHECK
#define LUMINARY_CMD_ERASE  TI_CMD_ERASE
#define LUMINARY_CMD_INFO   TI_CMD_INFO
#define LUMINARY_CMD_BIN    TI_CMD_BIN
#define LUMINARY_CMD_RESET  TI_CMD_RESET
#endif

//*****************************************************************************
//
// The structure sent to the host when a valid USBD_DFU_REQUEST_TI is
// received while the DFU device is in idle state.
//
//*****************************************************************************
#pragma pack(1)
typedef struct
{
    unsigned short usMarker;        // LM_DFU_PROTOCOL_MARKER
    unsigned short usVersion;       // LM_DFU_PROTOCOL_VERSION_1
}
tDFUQueryTIProtocol;

#ifndef DEPRECATED
//
// Deprecated definition included for backwards compatibility
//
#define tDFUQueryLuminaryProtocol tDFUQueryTIProtocol
#endif

//****************************************************************************
//
// Generic download command header.
//
//***************************************************************************
typedef struct
{
    unsigned char ucCommand;     // Command identifier.
    unsigned char ucData[7];     // Command-specific data elements.
}
tDFUDownloadHeader;

#define TI_CMD_LEN (sizeof(tDFUDownloadHeader))

#ifndef DEPRECATED
//
// Deprecated definition included for backwards compatibility
//
#define LUMINARY_CMD_LEN TI_CMD_LEN
#endif

//*****************************************************************************
//
// Header for the TI_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 TI_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 TI_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;   // TI_CMD_PROG
    unsigned char  ucReserved;  // Reserved - set to 0x00.
    unsigned short usStartAddr; // Block start address / 1024
    unsigned long  ulLength;    // Total length, in bytes, of following data
                                // for the complete download operation.
}
tDFUDownloadProgHeader;

//****************************************************************************
//
// Header for the TI_CMD_READ and TI_CMD_CHECK commands.
//
// The TI_CMD_READ 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 TI_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 in this way contains no header or suffix.
//
// To check that a region of flash is erased, the TI_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 multiple of 4.  If this is not the case, the value will be truncated
// before the check is performed.
//
//****************************************************************************
typedef struct
{
    unsigned char  ucCommand;    // TI_CMD_READ or TI_CMD_CHECK
    unsigned char  ucReserved;   // Reserved - write to 0
    unsigned short usStartAddr;  // Block start address / 1024
    unsigned long  ulLength;     // The number of bytes of data to read back or
                                 // check.
}
tDFUDownloadReadCheckHeader;

//****************************************************************************
//
// Header for the TI_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 TI_CMD_INFO command.
//
//*****************************************************************************
typedef struct
{
    unsigned char  ucCommand;      // TI_CMD_ERASE
    unsigned char  ucReserved;     // Reserved - set to 0.
    unsigned short usStartAddr;    // Block start address / 1024
    unsigned short usNumBlocks;    // The number of blocks to erase.
    unsigned char  ucReserved2[2]; // Reserved - set to 0.
}
tDFUDownloadEraseHeader;

//****************************************************************************
//
// Header for the TI_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;     // TI_CMD_INFO
    unsigned char ucReserved[7]; // Reserved - set to 0.
}
tDFUDownloadInfoHeader;

//****************************************************************************
//
// Header for the TI_CMD_BIN command.
//
// This command may be used to tell the device whether or not to include the
// TI_CMD_PROG header before downloaded data.  By default, this is the
// behaviour used.  The DFU spec states that it must be possible to
// download an uploaded image back to the target and the header contains
// information on the image length and start address but in some cases it is
// convenient to be able to upload an image without this header.
//
//****************************************************************************
typedef struct
{
    unsigned char ucCommand;     // TI_CMD_BIN
    unsigned bBinary;            // Zero to include the DFU header, non-zero to
                                 // omit it and send binary data.
    unsigned char ucReserved[6]; // Reserved - set to 0.
}
tDFUDownloadBinHeader;

//*****************************************************************************
//
// Payload returned in response to the TI_CMD_INFO command.
//
// This is structure is returned in response to the first
// USBD_DFU_REQUEST_UPLOAD request following a TI_CMD_INFO command.
//
//*****************************************************************************
typedef struct
{
    unsigned short usFlashBlockSize;  // The size of a flash block in bytes.
    unsigned short usNumFlashBlocks;  // The number of blocks of flash in the
                                      // device.  Total flash size is
                                      // usNumFlashBlocks * usFlashBlockSize.
    unsigned long ulPartInfo;         // Information on the part number,
                                      // family, version and package as
                                      // read from SYSCTL register DID1.
    unsigned long ulClassInfo;        // Information on the part class as read
                                      // from SYSCTL register DID0.
    unsigned long ulFlashTop;         // Address 1 byte above the highest
                                      // location the boot loader can access.
    unsigned long ulAppStartAddr;     // Lowest address the boot loader can
                                      // write or erase.
}
tDFUDeviceInfo;

//*****************************************************************************
//
// 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;
}
tDFUGetStatusResponse;

#pragma pack()

//*****************************************************************************
//
// LIBUSB return codes that are missing from the Windows version of errno.h.
//
//*****************************************************************************
#define ETIMEDOUT 116

#endif // __TIDFUPROT_H__

//
// End of File
//