435 lines
13 KiB
C
435 lines
13 KiB
C
/*
|
|
## Cypress USB Serial Library header file (CyUSBSerial.h)
|
|
## ===========================
|
|
##
|
|
## Copyright Cypress Semiconductor Corporation, 2012-2013,
|
|
## All Rights Reserved
|
|
## UNPUBLISHED, LICENSED SOFTWARE.
|
|
##
|
|
## CONFIDENTIAL AND PROPRIETARY INFORMATION
|
|
## WHICH IS THE PROPERTY OF CYPRESS.
|
|
##
|
|
## Use of this file is governed
|
|
## by the license agreement included in the file
|
|
##
|
|
## <install>/license/license.txt
|
|
##
|
|
## where <install> is the Cypress software
|
|
## installation root directory path.
|
|
##
|
|
## ===========================
|
|
*/
|
|
|
|
#ifndef _INCLUDED_CYUSBBOOTLOADER_H_
|
|
#define _INCLUDED_CYUSBBOOTLOADER_H_
|
|
|
|
/*This is to export windows API*/
|
|
#ifdef CYWINEXPORT
|
|
#undef CYWINEXPORT
|
|
#endif
|
|
#ifdef WIN32
|
|
|
|
#ifdef CYUSBSERIAL_EXPORTS
|
|
#define CYWINEXPORT extern "C" __declspec(dllexport)
|
|
#define WINCALLCONVEN
|
|
#else
|
|
#define CYWINEXPORT extern "C" __declspec(dllimport)
|
|
#define WINCALLCONVEN
|
|
#endif
|
|
#else /*Linux and MAC*/
|
|
#define CYWINEXPORT
|
|
#define WINCALLCONVEN
|
|
#ifndef BOOL
|
|
typedef bool BOOL;
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
Summary
|
|
Structure to hold Boot mode data buffer information.
|
|
|
|
Description
|
|
This strucuture is used by boot mode data transaction API to perform read, write
|
|
operations.
|
|
|
|
Before using a variable of this strucutre users need to initialize various members appropriately.
|
|
buffer - Need to be initialized to pre-allocated memory only, and user is
|
|
expected to deallocate the memory in his application.
|
|
length - Contains total length the buffer to be used while performing
|
|
read/write operations.
|
|
bytesReturned - Specifies the number of bytes actually read/written.
|
|
address - Address from where the data need to written/read
|
|
|
|
See Also
|
|
CyReadFlash
|
|
CyProgFlash
|
|
CyVerifyFlash
|
|
CyReadMemory
|
|
CyWriteMemory
|
|
|
|
CY_BOOTLOADER_VERSION
|
|
*/
|
|
typedef struct _CY_BOOTLD_BUFFER {
|
|
|
|
UCHAR *buffer; /*Address of the buffer*/
|
|
UINT32 length; /*total length to be read/written */
|
|
UINT32 *bytesReturned; /*Total length of bytes that was written/read*/
|
|
UINT32 address; /*Address from where data needs to be written/read in device*/
|
|
|
|
} CY_BOOTLD_BUFFER,*PCY_BOOTLD_BUFFER;
|
|
|
|
/*
|
|
Summary
|
|
This structure is used to hold Boot loader version.
|
|
|
|
Description
|
|
This data type holds the information of version of the bootloader in device. It has major version,
|
|
minor version and patch number.
|
|
|
|
See Also
|
|
CY_BOOTLD_BUFFER
|
|
*/
|
|
typedef struct _CY_BOOTLOADER_VERSION {
|
|
|
|
UCHAR majorVersion; /*Major version of BootLoader*/
|
|
UCHAR minorVersion; /*Minor version of the BootLoader*/
|
|
UINT16 patchNumber; /*Patch Number of the BootLoader*/
|
|
|
|
} CY_BOOTLOADER_VERSION;
|
|
|
|
|
|
/*************************************************************************************/
|
|
/****************************BOOTLOADER API'S*****************************************/
|
|
/*************************************************************************************/
|
|
|
|
/*@@BOOTLoader API
|
|
|
|
These APIs provide an interface for configuring the device when it is in BOOT mode.
|
|
|
|
The API's under this group gives user to option to configure the device when the device is in BOOT
|
|
mode. The APIs include support for device configuration, SCB level configuration, USB interface
|
|
configuration, checksum, firmware download.
|
|
|
|
*/
|
|
|
|
|
|
/*
|
|
Summary
|
|
This API retrieves the BootLoader version.
|
|
|
|
Description
|
|
This API gets the bootloader version of the USB Serial device.
|
|
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyGetSiliconID
|
|
|
|
CY_BOOTLOADER_VERSION
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyGetBootLoaderVersion (
|
|
CY_HANDLE handle, /*Valid device handle*/
|
|
CY_BOOTLOADER_VERSION *bootLoaderVersion /*Boot Loader version.*/
|
|
);
|
|
/*
|
|
Summary
|
|
This API retrieves the silicon ID.
|
|
|
|
Description
|
|
This API gets the silicon ID of the USB Serial device into the argument siliconID.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyGetBootLoaderVersion
|
|
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyGetSiliconID (
|
|
CY_HANDLE handle, /*Valid device handle*/
|
|
UINT32 *siliconID /*Boot Loader version.*/
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to change the device operational mode from device firmware to bootloader.
|
|
|
|
Description
|
|
This API changes the device operational mode from device firmware to bootloader or
|
|
Manufacturing mode.
|
|
|
|
Call the API GetSignature to identify the current operational mode. This API should be called only
|
|
when the device is in firmware mode.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyGetSignature
|
|
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyJumpToMfgMode (
|
|
CY_HANDLE handle);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to read device configuration
|
|
|
|
Description
|
|
This API reads the device configuration from the device configuration table. It fills the device
|
|
configuration as a series of bytes in the argument deviceConfig
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyWriteDeviceConfig
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyReadDeviceConfig (
|
|
CY_HANDLE handle, /* Valid device handle*/
|
|
UCHAR *deviceConfig /* Device configuration value.*/
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to update the device configuration table.
|
|
|
|
Description;
|
|
This API updates the device configuration in the configuration table of device. The device
|
|
configuration must be supplied as an array of bytes.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyReadDeviceConfig
|
|
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyWriteDeviceConfig (
|
|
CY_HANDLE handle, /*Valid Device handle*/
|
|
UCHAR *deviceConfig /*Device configuration value */
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to read the content of flash from specified address.
|
|
|
|
Description
|
|
The readBuffer structure must be filled and with address to be read from, appropriate buffer
|
|
and number of bytes to be read.
|
|
|
|
The actual bytes read will be available in bytesReturned member of CY_BOOTLD_BUFFER.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CY_BOOTLD_BUFFER
|
|
CyProgFlash
|
|
CyVerifyFlash
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyReadFlash (
|
|
CY_HANDLE handle, /*Valid device handle*/
|
|
CY_BOOTLD_BUFFER *readBuffer, /*Buffer pointer containing buffer address, length and address of flash*/
|
|
UINT32 timeout /*API timeout value*/
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to program the flash at specified address.
|
|
|
|
Description
|
|
The writeBuffer structure must be filled and with address to be written to, appropriate buffer location
|
|
and number of bytes to be written.
|
|
|
|
The actual bytes written will be available in bytesReturned member of CY_BOOTLD_BUFFER.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CY_BOOTLD_BUFFER
|
|
CyReadFlash
|
|
CyVerifyFlash
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyProgFlash (
|
|
CY_HANDLE handle, /*Valid device handle*/
|
|
CY_BOOTLD_BUFFER *writeBuffer, /*Buffer pointer containing the address of buffer pointer, length and address of flash*/
|
|
UINT32 timeout /*API timeout value*/
|
|
);
|
|
/*
|
|
Summary
|
|
This API can be used to read the memory content of SRAM from specified address.
|
|
|
|
Description
|
|
This API reads the content of flash in USB Serial device. The argument readBuffer need to be
|
|
initialized with address, number of bytes to be read and buffer location before invoking
|
|
this API.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CY_BOOTLD_BUFFER
|
|
CyWriteMemory
|
|
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyReadMemory (
|
|
CY_HANDLE handle, /*Valid handle to communicate with device*/
|
|
CY_BOOTLD_BUFFER *readBuffer, /*Bootloader read buffer details*/
|
|
UINT32 timeout /*API timeout value*/
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to write content to SRAM at specified address.
|
|
|
|
Description
|
|
This API writes the buffer content to SRAM. The argument writeBuffer need to be initialized with
|
|
target address, number of bytes to be written and buffer location before invoking this API.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CY_BOOTLD_BUFFER
|
|
CyReadMemory
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyWriteMemory (
|
|
CY_HANDLE handle, /*Valid handle to communicate with device*/
|
|
CY_BOOTLD_BUFFER *writeBuffer, /*Bootloader write buffer details*/
|
|
UINT32 timeout /*API timeout value*/
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used calculate the checksum of the firmware loaded and compares it with the checksum in
|
|
device configuration table.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyUpdateChecksum
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyValidateChecksum (
|
|
CY_HANDLE handle /*Valid handle to communicate with device*/
|
|
);
|
|
/*
|
|
Summary
|
|
This API can be used to read boot configuration.
|
|
|
|
Description
|
|
This API reads the boot configuration from the boot configuration table of device. The bootConfig
|
|
need to be parsed to obtain actual configuration values.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyWriteBootConfig
|
|
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyReadBootConfig (
|
|
CY_HANDLE handle, /*Valid handle to communicate with device*/
|
|
UCHAR *bootConfig /*Current Boot configuration value read back*/
|
|
);
|
|
/*
|
|
Summary
|
|
This API updates the device boot configuration table.
|
|
|
|
Description;
|
|
This API updates the boot configuration in the boot configuration table of device.
|
|
The bootConfig is pointer to an array of bytes contain the configuration.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyReadBootConfig
|
|
*/
|
|
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyWriteBootConfig (
|
|
CY_HANDLE handle, /*Valid handle to communicate with device*/
|
|
UCHAR *bootConfig /*Boot configuration value to be updated*/
|
|
);
|
|
/*
|
|
Summary
|
|
This API can be used to download firmware on to USB Serial device.
|
|
|
|
Description;
|
|
This API downloads the firmware specified in filePath on to flash of the USB Serial device.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyReadBootConfig
|
|
CyWriteBootConfig
|
|
CyReadFlash
|
|
CyProgFlash
|
|
CyReadMemory
|
|
CyWriteMemory
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyDownloadFirmware (
|
|
CY_HANDLE handle, /*Valid handle to communicate with device*/
|
|
CHAR *filePath /*Path of Firmware file*/
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used enable flash configuration on USB Serial device.
|
|
|
|
Description;
|
|
This API configures the the firmware and allows user to enable/diable flash changes.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyReadBootConfig
|
|
CyWriteBootConfig
|
|
CyReadFlash
|
|
CyProgFlash
|
|
CyReadMemory
|
|
CyWriteMemory
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS WINCALLCONVEN CyFlashConfigEnable (
|
|
CY_HANDLE handle, /*Valid handle to communicate with device*/
|
|
BOOL enable /*Set to TRUE to enable flash configuration
|
|
FALSE to disable flash configuration */
|
|
);
|
|
|
|
/*
|
|
Summary
|
|
This API can be used to obtain the Silicon Serial No.
|
|
|
|
Description;
|
|
This API can be used to obtain the Silicon Serial No.
|
|
|
|
Return Value
|
|
CY_SUCCESS on success else error codes as defined in the enumeration CY_RETURN_STATUS.
|
|
|
|
See Also
|
|
CyReadBootConfig
|
|
CyWriteBootConfig
|
|
CyReadFlash
|
|
CyProgFlash
|
|
CyReadMemory
|
|
CyWriteMemory
|
|
*/
|
|
CYWINEXPORT CY_RETURN_STATUS CyGetSiliconSerialID (
|
|
CY_HANDLE handle, /*Valid device handle*/
|
|
UCHAR buffer[8] /*Buffer to contain 8 bytes of data.*/
|
|
);
|
|
|
|
#endif /* _INCLUDED_CYUSBBOOTLOADER_H_ */ |