BlueSCSI-v2/lib/SCSI2SD/software/bootloaderhost/cybootloaderutils/cybtldr_api.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_API_H__
#define __CYBTLDR_API_H__

#include "cybtldr_utils.h"

/*
 * This struct defines all of the items necessary for the bootloader
 * host to communicate over an arbitrary communication protocol. The
 * caller must provide implementations of these items to use their
 * deisred communication protocol.
 */
typedef struct
{
    /* Function used to open the communications connection */
    int (*OpenConnection)(void);
    /* Function used to close the communications connection */
    int (*CloseConnection)(void);
    /* Function used to read data over the communications connection */
    int (*ReadData)(unsigned char*, int);
    /* Function used to write data over the communications connection */
    int (*WriteData)(unsigned char*, int);
    /* Value used to specify the maximum number of bytes that can be trasfered at a time */
    unsigned int MaxTransferSize;
} CyBtldr_CommunicationsData;



/*******************************************************************************
* Function Name: CyBtldr_TransferData
********************************************************************************
* Summary:
*   This function is responsible for transfering a buffer of data to the target
*   device and then reading a response packet back from the device.
*
* Parameters:
*   inBuf   - The buffer containing data to send to the target device
*   inSize  - The number of bytes to send to the target device
*   outBuf  - The buffer to store the data read from the device
*   outSize - The number of bytes to read from the target device
*
* Returns:
*   CYRET_SUCCESS  - The transfer completed successfully
*   CYRET_ERR_COMM - There was a communication error talking to the device
*
*******************************************************************************/
int CyBtldr_TransferData(unsigned char* inBuf, int inSize, unsigned char* outBuf, int outSize);

/*******************************************************************************
* Function Name: CyBtldr_ValidateRow
********************************************************************************
* Summary:
*   This function is responsible for verifying that the provided arrayId and
*   row number are valid for a bootload operation.
*
* Parameters:
*   arrayId - The array to check
*   rowNum  - The row number within the array to check
*
* Returns:
*   CYRET_SUCCESS   - The array and row are available for communication
*   CYRET_ERR_ARRAY - The array is not valid for communication
*   CYRET_ERR_ROW   - The array/row number is not valid for communication
*
*******************************************************************************/
int CyBtldr_ValidateRow(unsigned char arrayId, unsigned short rowNum);

/*******************************************************************************
* Function Name: CyBtldr_StartBootloadOperation
********************************************************************************
* Summary:
*   Initiates a new bootload operation.  This must be called before any other 
*   request to send data to the bootloader.  A corresponding call to 
*   CyBtldr_EndBootloadOperation() should be made once all transactions are 
*   complete.
*
* Parameters:
*   comm     – Communication struct used for communicating with the target device
*   expSiId  - The Silicon ID of the device we expect to communicate with
*   expSiRev - The Silicon Rev of the device we expect to communicate with
*   blVer    - The Bootloader version that is running on the device
*
* Returns:
*   CYRET_SUCCESS     - The start request was sent successfully
*   CYRET_ERR_DEVICE  - The detected device does not match the desired device
*   CYRET_ERR_VERSION - The detected bootloader version is not compatible
*   CYRET_ERR_BTLDR   - The bootloader experienced an error
*   CYRET_ERR_COMM    - There was a communication error talking to the device
*
*******************************************************************************/
EXTERN int CyBtldr_StartBootloadOperation(CyBtldr_CommunicationsData* comm, unsigned long expSiId, unsigned char expSiRev, unsigned long* blVer);

/*******************************************************************************
* Function Name: CyBtldr_EndBootloadOperation
********************************************************************************
* Summary:
*   Terminates the current bootload operation.  This should be called once all 
*   bootload commands have been sent and no more communication is desired.
*
* Parameters:
*   void.
*
* Returns:
*   CYRET_SUCCESS   - The end request was sent successfully
*   CYRET_ERR_BTLDR - The bootloader experienced an error
*   CYRET_ERR_COMM  - There was a communication error talking to the device
*
*******************************************************************************/
EXTERN int CyBtldr_EndBootloadOperation(void);

/*******************************************************************************
* Function Name: CyBtldr_GetApplicationStatus
********************************************************************************
* Summary:
*   Gets the status for the provided application id. The status includes whether
*   the application is valid and whether it is currently marked as active.  This
*   should be called immediatly after enter bootloader in order to determine if
*   the application is suitable for bootloading.
*   NOTE: This is only valid for multi application bootloaders.
*
* Parameters:
*   appID    - The application ID to get status information for
*   isValid  - Is the provided application valid to be executed
*   isActive - Is the provided application already marked as the active app
*
* Returns:
*   CYRET_SUCCESS   - The end request was sent successfully
*   CYRET_ERR_BTLDR - The bootloader experienced an error
*   CYRET_ERR_COMM  - There was a communication error talking to the device
*   CYRET_ERR_LENGTH- The result packet does not have enough data
*   CYRET_ERR_DATA  - The result packet does not contain valid data
*
*******************************************************************************/
EXTERN int CyBtldr_GetApplicationStatus(unsigned char appID, unsigned char* isValid, unsigned char* isActive);

/*******************************************************************************
* Function Name: CyBtldr_SetApplicationStatus
********************************************************************************
* Summary:
*   Sets the application that the bootloader will run.  This should be called
*   after a new application has been programmed in and verified 
*   NOTE: This is only valid for multi application bootloaders.
*
* Parameters:
*   appID    - The application ID to set as the active application 
*
* Returns:
*   CYRET_SUCCESS   - The end request was sent successfully
*   CYRET_ERR_BTLDR - The bootloader experienced an error
*   CYRET_ERR_COMM  - There was a communication error talking to the device
*   CYRET_ERR_LENGTH- The result packet does not have enough data
*   CYRET_ERR_DATA  - The result packet does not contain valid data
*   CYRET_ERR_APP   - The application is not valid and cannot be set as active
*
*******************************************************************************/
EXTERN int CyBtldr_SetApplicationStatus(unsigned char appID);

/*******************************************************************************
* Function Name: CyBtldr_ProgramRow
********************************************************************************
* Summary:
*   Sends a single row of data to the bootloader to be programmed into flash
*
* Parameters:
*   arrayID – The flash array that is to be reprogrammed
*   rowNum  – The row number within the array that is to be reprogrammed
*   buf     – The buffer of data to program into the devices flash
*   size    – The number of bytes in data that need to be sent to the bootloader
*
* Returns:
*   CYRET_SUCCESS    - The row was programmed successfully
*   CYRET_ERR_LENGTH - The result packet does not have enough data
*   CYRET_ERR_DATA   - The result packet does not contain valid data
*   CYRET_ERR_ARRAY  - The array is not valid for programming
*   CYRET_ERR_ROW    - The array/row number is not valid for programming
*   CYRET_ERR_BTLDR  - The bootloader experienced an error
*   CYRET_ERR_ACTIVE - The application is currently marked as active
*
*******************************************************************************/
EXTERN int CyBtldr_ProgramRow(unsigned char arrayID, unsigned short rowNum, unsigned char* buf, unsigned short size);

/*******************************************************************************
* Function Name: CyBtldr_EraseRow
********************************************************************************
* Summary:
*   Erases a single row of flash data from the device.
*
* Parameters:
*   arrayID – The flash array that is to have a row erased
*   rowNum  – The row number within the array that is to be erased
*
* Returns:
*   CYRET_SUCCESS    - The row was erased successfully
*   CYRET_ERR_LENGTH - The result packet does not have enough data
*   CYRET_ERR_DATA   - The result packet does not contain valid data
*   CYRET_ERR_ARRAY  - The array is not valid for programming
*   CYRET_ERR_ROW    - The array/row number is not valid for programming
*   CYRET_ERR_BTLDR  - The bootloader experienced an error
*   CYRET_ERR_COMM   - There was a communication error talking to the device
*   CYRET_ERR_ACTIVE - The application is currently marked as active
*
*******************************************************************************/
EXTERN int CyBtldr_EraseRow(unsigned char arrayID, unsigned short rowNum);

/*******************************************************************************
* Function Name: CyBtldr_VerifyRow
********************************************************************************
* Summary:
*   Verifies that the data contained within the specified flash array and row 
*   matches the expected value.
*
* Parameters:
*   arrayID  – The flash array that is to be verified
*   rowNum   – The row number within the array that is to be verified
*   checksum – The expected checksum value for the row
*
* Returns:
*   CYRET_SUCCESS      - The row was verified successfully
*   CYRET_ERR_LENGTH   - The result packet does not have enough data
*   CYRET_ERR_DATA     - The result packet does not contain valid data
*   CYRET_ERR_ARRAY	   - The array is not valid for programming
*   CYRET_ERR_ROW      - The array/row number is not valid for programming
*   CYRET_ERR_CHECKSUM - The checksum does not match the expected value
*   CYRET_ERR_BTLDR    - The bootloader experienced an error
*   CYRET_ERR_COMM     - There was a communication error talking to the device
*
*******************************************************************************/
EXTERN int CyBtldr_VerifyRow(unsigned char arrayID, unsigned short rowNum, unsigned char checksum);

/*******************************************************************************
* Function Name: CyBtldr_VerifyApplication
********************************************************************************
* Summary:
*   Verifies that the checksum for the entire bootloadable application matches 
*   the expected value.  This is used to verify that the entire bootloadable
*   image is valid and ready to execute.
*
* Parameters:
*   void
*
* Returns:
*   CYRET_SUCCESS      - The application was verified successfully
*   CYRET_ERR_LENGTH   - The result packet does not have enough data
*   CYRET_ERR_DATA     - The result packet does not contain valid data
*   CYRET_ERR_CHECKSUM - The checksum does not match the expected value
*   CYRET_ERR_BTLDR    - The bootloader experienced an error
*   CYRET_ERR_COMM     - There was a communication error talking to the device
*
*******************************************************************************/
EXTERN int CyBtldr_VerifyApplication();

#endif