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