-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathcybtldr_api.h
260 lines (244 loc) · 12.2 KB
/
cybtldr_api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
/*******************************************************************************
* 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
* securitykeyBuf - The 6 byte or null bootloader security key
*
* 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, const unsigned char* securityKeyBuf);
/*******************************************************************************
* 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