/* * 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" /** * @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_ */