forked from Linaro/freertos-ota-pal-psa
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ota_pal.h
249 lines (232 loc) · 11.1 KB
/
ota_pal.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
/*
* FreeRTOS V202107.00
* Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
* http://aws.amazon.com/freertos
* http://www.FreeRTOS.org
*/
/**
* @file ota_pal.h
* @brief Function declarations for the functions in ota_pal.c
*/
#ifndef OTA_PAL_H_
#define OTA_PAL_H_
#include "ota.h"
/* OTA PAL signing algorithm configurations. */
#define OTA_PAL_CODE_SIGNING_RSA ( 0 )
#define OTA_PAL_CODE_SIGNING_ECDSA ( 1 )
/* Choose code signing algorithm. */
#ifndef OTA_PAL_CODE_SIGNING_ALGO
#define OTA_PAL_CODE_SIGNING_ALGO ( OTA_PAL_CODE_SIGNING_ECDSA )
#endif
/* OTA PAL signature format configurations. */
#define OTA_PAL_SIGNATURE_RAW ( 0 )
#define OTA_PAL_SIGNATURE_ASN1_DER ( 1 )
/* Choose the signature format. */
/* The OTA_PAL_SIGNATURE_ASN1_DER enables to convert ASN1/DER signature to raw data. */
#ifndef OTA_PAL_SIGNATURE_FORMAT
#define OTA_PAL_SIGNATURE_FORMAT ( OTA_PAL_SIGNATURE_ASN1_DER )
#endif
/**
* @brief Abort an OTA transfer.
*
* Aborts access to an existing open file represented by the OTA file context pFileContext. This is
* only valid for jobs that started successfully.
*
* @note The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this
* function is called.
*
* This function may be called before the file is opened, so the file pointer pFileContext->fileHandle
* may be NULL when this function is called.
*
* @param[in] pFileContext OTA file context information.
*
* @return The OtaPalStatus_t error code is a combination of the main OTA PAL interface error and
* the MCU specific sub error code. See ota_platform_interface.h for the OtaPalMainStatus_t
* error codes and your specific PAL implementation for the sub error code.
*
* Major error codes returned are:
*
* OtaPalSuccess: Aborting access to the open file was successful.
* OtaPalFileAbort: Aborting access to the open file context was unsuccessful.
*/
OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const pFileContext );
/**
* @brief Create a new receive file.
*
* @note Opens the file indicated in the OTA file context in the MCU file system.
*
* @note The previous image may be present in the designated image download partition or file, so the
* partition or file must be completely erased or overwritten in this routine.
*
* @note The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this
* function is called.
* The device file path is a required field in the OTA job document, so pFileContext->pFilePath is
* checked for NULL by the OTA agent before this function is called.
*
* @param[in] pFileContext OTA file context information.
*
* @return The OtaPalStatus_t error code is a combination of the main OTA PAL interface error and
* the MCU specific sub error code. See ota_platform_interface.h for the OtaPalMainStatus_t
* error codes and your specific PAL implementation for the sub error code.
*
* Major error codes returned are:
*
* OtaPalSuccess: File creation was successful.
* OtaPalRxFileTooLarge: The OTA receive file is too big for the platform to support.
* OtaPalBootInfoCreateFailed: The bootloader information file creation failed.
* OtaPalRxFileCreateFailed: Returned for other errors creating the file in the device's
* non-volatile memory. If this error is returned, then the sub error
* should be set to the appropriate platform specific value.
*/
OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const pFileContext );
/**
* @brief Authenticate and close the underlying receive file in the specified OTA context.
*
* @note The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this
* function is called. This function is called only at the end of block ingestion.
* otaPAL_CreateFileForRx() must succeed before this function is reached, so
* pFileContext->fileHandle(or pFileContext->pFile) is never NULL.
* The file signature key is required job document field in the OTA Agent, so pFileContext->pSignature will
* never be NULL.
*
* If the signature verification fails, file close should still be attempted.
*
* @param[in] pFileContext OTA file context information.
*
* @return The OtaPalStatus_t error code is a combination of the main OTA PAL interface error and
* the MCU specific sub error code. See ota_platform_interface.h for the OtaPalMainStatus_t
* error codes and your specific PAL implementation for the sub error code.
*
* Major error codes returned are:
*
* OtaPalSuccess on success.
* OtaPalSignatureCheckFailed: The signature check failed for the specified file.
* OtaPalBadSignerCert: The signer certificate was not readable or zero length.
* OtaPalFileClose: Error in low level file close.
*/
OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const pFileContext );
/**
* @brief Write a block of data to the specified file at the given offset.
*
* @note The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this
* function is called.
* The file pointer/handle pFileContext->pFile, is checked for NULL by the OTA agent before this
* function is called.
* pData is checked for NULL by the OTA agent before this function is called.
* blockSize is validated for range by the OTA agent before this function is called.
* offset is validated by the OTA agent before this function is called.
*
* @param[in] pFileContext OTA file context information.
* @param[in] ulOffset Byte offset to write to from the beginning of the file.
* @param[in] pData Pointer to the byte array of data to write.
* @param[in] ulBlockSize The number of bytes to write.
*
* @return The number of bytes written successfully, or a negative error code from the platform
* abstraction layer.
*/
int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext,
uint32_t ulOffset,
uint8_t * const pData,
uint32_t ulBlockSize );
/**
* @brief Activate the newest MCU image received via OTA.
*
* This function shall take necessary actions to activate the newest MCU
* firmware received via OTA. It is typically just a reset of the device.
*
* @note This function SHOULD NOT return. If it does, the platform does not support
* an automatic reset or an error occurred.
*
* @param[in] pFileContext OTA file context information.
*
* @return The OtaPalStatus_t error code is a combination of the main OTA PAL interface error and
* the MCU specific sub error code. See ota_platform_interface.h for the OtaPalMainStatus_t
* error codes and your specific PAL implementation for the sub error code.
*
* Major error codes returned are:
*
* OtaPalSuccess on success.
* OtaPalActivateFailed: The activation of the new OTA image failed.
*/
OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const pFileContext );
/**
* @brief Attempt to set the state of the OTA update image.
*
* Take required actions on the platform to Accept/Reject the OTA update image (or bundle).
* Refer to the PAL implementation to determine what happens on your platform.
*
* @param[in] pFileContext File context of type OtaFileContext_t.
* @param[in] eState The desired state of the OTA update image.
*
* @return The OtaPalStatus_t error code is a combination of the main OTA PAL interface error and
* the MCU specific sub error code. See ota_platform_interface.h for the OtaPalMainStatus_t
* error codes and your specific PAL implementation for the sub error code.
*
* Major error codes returned are:
*
* OtaPalSuccess on success.
* OtaPalBadImageState: if you specify an invalid OtaImageState_t. No sub error code.
* OtaPalAbortFailed: failed to roll back the update image as requested by OtaImageStateAborted.
* OtaPalRejectFailed: failed to roll back the update image as requested by OtaImageStateRejected.
* OtaPalCommitFailed: failed to make the update image permanent as requested by OtaImageStateAccepted.
*/
OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext,
OtaImageState_t eState );
/**
* @brief Get the state of the OTA update image.
*
* We read this at OTA_Init time and when the latest OTA job reports itself in self
* test. If the update image is in the "pending commit" state, we start a self test
* timer to assure that we can successfully connect to the OTA services and accept
* the OTA update image within a reasonable amount of time (user configurable). If
* we don't satisfy that requirement, we assume there is something wrong with the
* firmware and automatically reset the device, causing it to roll back to the
* previously known working code.
*
* If the update image state is not in "pending commit," the self test timer is
* not started.
*
* @param[in] pFileContext File context of type OtaFileContext_t.
*
* @return An OtaPalImageState_t. One of the following:
* OtaPalImageStatePendingCommit (the new firmware image is in the self test phase)
* OtaPalImageStateValid (the new firmware image is already committed)
* OtaPalImageStateInvalid (the new firmware image is invalid or non-existent)
*
* NOTE: OtaPalImageStateUnknown should NEVER be returned and indicates an implementation error.
*/
OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const pFileContext );
/**
* @brief Reset the device.
*
* This function shall reset the MCU and cause a reboot of the system.
*
* @note This function SHOULD NOT return. If it does, the platform does not support
* an automatic reset or an error occurred.
*
* @param[in] pFileContext OTA file context information.
*
* @return The OtaPalStatus_t error code is a combination of the main OTA PAL interface error and
* the MCU specific sub error code. See ota_platform_interface.h for the OtaPalMainStatus_t
* error codes and your specific PAL implementation for the sub error code.
*/
OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const pFileContext );
#endif /* ifndef OTA_PAL_H_ */