BlueSCSI-v2/lib/SCSI2SD/software/scsi2sd-util/cybootloaderutils/cybtldr_command.h

/*******************************************************************************
* Copyright 2011-2012, Cypress Semiconductor Corporation.  All rights reserved.
* You may use this file only in accordance with the license, terms, conditions, 
* disclaimers, and limitations in the end user license agreement accompanying 
* the software package with which this file was provided.
********************************************************************************/

#ifndef __CYBTLDR_COMMAND_H__
#define __CYBTLDR_COMMAND_H__

#include "cybtldr_utils.h"

/* Maximum number of bytes to allocate for a single command.  */
#define MAX_COMMAND_SIZE 512


//STANDARD PACKET FORMAT:
// Multi byte entries are encoded in LittleEndian.
/*******************************************************************************
* [1-byte] [1-byte ] [2-byte] [n-byte] [ 2-byte ] [1-byte]
* [ SOP  ] [Command] [ Size ] [ Data ] [Checksum] [ EOP  ]
*******************************************************************************/


/* The first byte of any boot loader command. */
#define CMD_START               0x01
/* The last byte of any boot loader command. */
#define CMD_STOP                0x17
/* The minimum number of bytes in a bootloader command. */
#define BASE_CMD_SIZE           0x07

/* Command identifier for verifying the checksum value of the bootloadable project. */
#define CMD_VERIFY_CHECKSUM     0x31
/* Command identifier for getting the number of flash rows in the target device. */
#define CMD_GET_FLASH_SIZE      0x32
/* Command identifier for getting info about the app status. This is only supported on multi app bootloader. */
#define CMD_GET_APP_STATUS      0x33
/* Command identifier for reasing a row of flash data from the target device. */
#define CMD_ERASE_ROW           0x34
/* Command identifier for making sure the bootloader host and bootloader are in sync. */
#define CMD_SYNC                0x35
/* Command identifier for setting the active application. This is only supported on multi app bootloader. */
#define CMD_SET_ACTIVE_APP      0x36
/* Command identifier for sending a block of data to the bootloader without doing anything with it yet. */
#define CMD_SEND_DATA           0x37
/* Command identifier for starting the boot loader.  All other commands ignored until this is sent. */
#define CMD_ENTER_BOOTLOADER    0x38
/* Command identifier for programming a single row of flash. */
#define CMD_PROGRAM_ROW         0x39
/* Command identifier for verifying the contents of a single row of flash. */
#define CMD_VERIFY_ROW          0x3A
/* Command identifier for exiting the bootloader and restarting the target program. */
#define CMD_EXIT_BOOTLOADER     0x3B

/*
 * This enum defines the different types of checksums that can be 
 * used by the bootloader for ensuring data integrety.
 */
typedef enum
{
    /* Checksum type is a basic inverted summation of all bytes */
    SUM_CHECKSUM = 0x00,
    /* 16-bit CRC checksum using the CCITT implementation */
    CRC_CHECKSUM = 0x01,
} CyBtldr_ChecksumType;

/*******************************************************************************
* Function Name: CyBtldr_ComputeChecksum
********************************************************************************
* Summary:
*   Computes the 2byte checksum for the provided command data.  The checksum is 
*   the 2's complement of the 1-byte sum of all bytes.
*
* Parameters:
*   buf  - The data to compute the checksum on
*   size - The number of bytes contained in buf.
*
* Returns:
*   The checksum for the provided data.
*
*******************************************************************************/
unsigned short CyBtldr_ComputeChecksum(unsigned char* buf, unsigned long size);

/*******************************************************************************
* Function Name: CyBtldr_SetCheckSumType
********************************************************************************
* Summary:
*   Updates what checksum algorithm is used when generating packets
*
* Parameters:
*   chksumType - The type of checksum to use when creating packets
*
* Returns:
*   NA
*
*******************************************************************************/
void CyBtldr_SetCheckSumType(CyBtldr_ChecksumType chksumType);

/*******************************************************************************
* Function Name: CyBtldr_ParseDefaultCmdResult
********************************************************************************
* Summary:
*   Parses the output from any command that returns the default result packet
*   data.  The default result is just a status byte
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   status  - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
int CyBtldr_ParseDefaultCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateEnterBootLoaderCmd
********************************************************************************
* Summary:
*   Creates the command used to startup the bootloader.
*   NB: This command must be sent before the bootloader will respond to any
*       other command.
*
* Parameters:
*   protect - The flash protection settings.
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateEnterBootLoaderCmd(unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseEnterBootLoaderCmdResult
********************************************************************************
* Summary:
*   Parses the output from the EnterBootLoader command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf     - The buffer containing the output from the bootloader.
*   cmdSize    - The number of bytes in cmdBuf.
*   siliconId  - The silicon ID of the device being communicated with.
*   siliconRev - The silicon Revision of the device being communicated with.
*   blVersion  - The bootloader version being communicated with.
*   status     - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseEnterBootLoaderCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned long* siliconId, unsigned char* siliconRev, unsigned long* blVersion, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateExitBootLoaderCmd
********************************************************************************
* Summary:
*   Creates the command used to stop communicating with the boot loader and to
*   trigger the target device to restart, running the new bootloadable 
*   application.
*
* Parameters:
*   resetType - The type of reset to perform (0 = Reset, 1 = Direct Call).
*   cmdBuf    - The preallocated buffer to store command data in.
*   cmdSize   - The number of bytes in the command.
*   resSize   - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateExitBootLoaderCmd(unsigned char resetType, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_CreateProgramRowCmd
********************************************************************************
* Summary:
*   Creates the command used to program a single flash row.
*
* Parameters:
*   arrayId - The array id to program.
*   rowNum  - The row number to program.
*   buf     - The buffer of data to program into the flash row.
*   size    - The number of bytes in data for the row.
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateProgramRowCmd(unsigned char arrayId, unsigned short rowNum, unsigned char* buf, unsigned short size, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseProgramRowCmdResult
********************************************************************************
* Summary:
*   Parses the output from the ProgramRow command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   status  - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseProgramRowCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateVerifyRowCmd
********************************************************************************
* Summary:
*   Creates the command used to verify that the contents of flash match the
*   provided row data.
*
* Parameters:
*   arrayId - The array id to verify.
*   rowNum  - The row number to verify.
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateVerifyRowCmd(unsigned char arrayId, unsigned short rowNum, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseVerifyRowCmdResult
********************************************************************************
* Summary:
*   Parses the output from the VerifyRow command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf   - The preallocated buffer to store command data in.
*   cmdSize  - The number of bytes in the command.
*   checksum - The checksum from the row to verify.
*   status   - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseVerifyRowCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* checksum, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateEraseRowCmd
********************************************************************************
* Summary:
*   Creates the command used to erase a single flash row.
*
* Parameters:
*   arrayId - The array id to erase.
*   rowNum  - The row number to erase.
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateEraseRowCmd(unsigned char arrayId, unsigned short rowNum, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseEraseRowCmdResult
********************************************************************************
* Summary:
*   Parses the output from the EraseRow command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   status  - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseEraseRowCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateVerifyChecksumCmd
********************************************************************************
* Summary:
*   Creates the command used to verify that the checkusm value in flash matches
*   what is expected.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateVerifyChecksumCmd(unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseVerifyChecksumCmdResult
********************************************************************************
* Summary:
*   Parses the output from the VerifyChecksum command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf   - The preallocated buffer to store command data in.
*   cmdSize  - The number of bytes in the command.
*   checksumValid - Whether or not the full checksums match (1 = valid, 0 = invalid)
*   status   - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseVerifyChecksumCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* checksumValid, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateGetFlashSizeCmd
********************************************************************************
* Summary:
*   Creates the command used to retreive the number of flash rows in the device.
*
* Parameters:
*   arrayId - The array ID to get the flash size of.
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateGetFlashSizeCmd(unsigned char arrayId, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseGetFlashSizeCmdResult
********************************************************************************
* Summary:
*   Parses the output from the GetFlashSize command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf   - The preallocated buffer to store command data in.
*   cmdSize  - The number of bytes in the command.
*   startRow - The first available row number in the flash array.
*   endRow   - The last available row number in the flash array.
*   status   - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseGetFlashSizeCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned short* startRow, unsigned short* endRow, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateSendDataCmd
********************************************************************************
* Summary:
*   Creates the command used to send a block of data to the target.
*
* Parameters:
*   buf     - The buffer of data data to program into the flash row.
*   size    - The number of bytes in data for the row.
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateSendDataCmd(unsigned char* buf, unsigned short size, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseSendDataCmdResult
********************************************************************************
* Summary:
*   Parses the output from the SendData command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   status  - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseSendDataCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateSyncBootLoaderCmd
********************************************************************************
* Summary:
*   Creates the command used to ensure that the host application is in sync
*   with the bootloader application.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateSyncBootLoaderCmd(unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_CreateGetAppStatusCmd
********************************************************************************
* Summary:
*   Creates the command used to get information about the application.  This
*   command is only supported by the multi application bootloaader.
*
* Parameters:
*   appId   - The id for the application to get status for
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateGetAppStatusCmd(unsigned char appId, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseGetAppStatusCmdResult
********************************************************************************
* Summary:
*   Parses the output from the GetAppStatus command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   isValid - Is the application valid.
*   isActive- Is the application currently marked as active.
*   status  - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseGetAppStatusCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* isValid, unsigned char* isActive, unsigned char* status);

/*******************************************************************************
* Function Name: CyBtldr_CreateSetActiveAppCmd
********************************************************************************
* Summary:
*   Creates the command used to set the active application for the bootloader 
*   to run.  This command is only supported by the multi application 
*   bootloaader.
*
* Parameters:
*   appId   - The id for the application to get status for
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   resSize - The number of bytes expected in the bootloader's response packet.
*
* Returns:
*   CYRET_SUCCESS  - The command was constructed successfully
*
*******************************************************************************/
EXTERN int CyBtldr_CreateSetActiveAppCmd(unsigned char appId, unsigned char* cmdBuf, unsigned long* cmdSize, unsigned long* resSize);

/*******************************************************************************
* Function Name: CyBtldr_ParseSetActiveAppCmdResult
********************************************************************************
* Summary:
*   Parses the output from the SetActiveApp command to get the resultant
*   data.
*
* Parameters:
*   cmdBuf  - The preallocated buffer to store command data in.
*   cmdSize - The number of bytes in the command.
*   status  - The status code returned by the bootloader.
*
* Returns:
*   CYRET_SUCCESS    - The command was constructed successfully
*   CYRET_ERR_LENGTH - The packet does not contain enough data
*   CYRET_ERR_DATA   - The packet's contents are not correct
*
*******************************************************************************/
EXTERN int CyBtldr_ParseSetActiveAppCmdResult(unsigned char* cmdBuf, unsigned long cmdSize, unsigned char* status);

#endif