arm_uc_pal_linux_implementation.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef ARM_UC_PAL_LINUX_IMPLEMENTATION_H
00020 #define ARM_UC_PAL_LINUX_IMPLEMENTATION_H
00021 
00022 #include "update-client-paal/arm_uc_paal_update_api.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /**
00029  * @brief Initialize the underlying storage and set the callback handler.
00030  *
00031  * @param callback Function pointer to event handler.
00032  * @return Returns ERR_NONE on accept, and signals the event handler with
00033  *         either DONE or ERROR when complete.
00034  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00035  */
00036 arm_uc_error_t ARM_UC_PAL_Linux_Initialize(ARM_UC_PAAL_UPDATE_SignalEvent_t callback);
00037 
00038 /**
00039  * @brief Get maximum number of supported storage locations.
00040  *
00041  * @return Number of storage locations.
00042  */
00043 uint32_t ARM_UC_PAL_Linux_GetMaxID(void);
00044 
00045 /**
00046  * @brief Prepare the storage layer for a new firmware image.
00047  * @details The storage location is set up to receive an image with
00048  *          the details passed in the details struct.
00049  *
00050  * @param location Storage location ID.
00051  * @param details Pointer to a struct with firmware details.
00052  * @param buffer Temporary buffer for formatting and storing metadata.
00053  * @return Returns ERR_NONE on accept, and signals the event handler with
00054  *         either DONE or ERROR when complete.
00055  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00056  */
00057 arm_uc_error_t ARM_UC_PAL_Linux_Prepare(uint32_t location,
00058                                         const arm_uc_firmware_details_t* details,
00059                                         arm_uc_buffer_t* buffer);
00060 
00061 /**
00062  * @brief Write a fragment to the indicated storage location.
00063  * @details The storage location must have been allocated using the Prepare
00064  *          call. The call is expected to write the entire fragment before
00065  *          signaling completion.
00066  *
00067  * @param location Storage location ID.
00068  * @param offset Offset in bytes to where the fragment should be written.
00069  * @param buffer Pointer to buffer struct with fragment.
00070  * @return Returns ERR_NONE on accept, and signals the event handler with
00071  *         either DONE or ERROR when complete.
00072  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00073  */
00074 arm_uc_error_t ARM_UC_PAL_Linux_Write(uint32_t location,
00075                                       uint32_t offset,
00076                                       const arm_uc_buffer_t* buffer);
00077 
00078 /**
00079  * @brief Close storage location for writing and flush pending data.
00080  *
00081  * @param location Storage location ID.
00082  * @return Returns ERR_NONE on accept, and signals the event handler with
00083  *         either DONE or ERROR when complete.
00084  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00085  */
00086 arm_uc_error_t ARM_UC_PAL_Linux_Finalize(uint32_t location);
00087 
00088 /**
00089  * @brief Read a fragment from the indicated storage location.
00090  * @details The function will read until the buffer is full or the end of
00091  *          the storage location has been reached. The actual amount of
00092  *          bytes read is set in the buffer struct.
00093  *
00094  * @param location Storage location ID.
00095  * @param offset Offset in bytes to read from.
00096  * @param buffer Pointer to buffer struct to store fragment.
00097  * @return Returns ERR_NONE on accept, and signals the event handler with
00098  *         either DONE or ERROR when complete.
00099  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00100  */
00101 arm_uc_error_t ARM_UC_PAL_Linux_Read(uint32_t location,
00102                                      uint32_t offset,
00103                                      arm_uc_buffer_t* buffer);
00104 
00105 /**
00106  * @brief Set the firmware image in the slot to be the new active image.
00107  * @details This call is responsible for initiating the process for
00108  *          applying a new/different image. Depending on the platform this
00109  *          could be:
00110  *           * An empty call, if the installer can deduce which slot to
00111  *             choose from based on the firmware details.
00112  *           * Setting a flag to indicate which slot to use next.
00113  *           * Decompressing/decrypting/installing the firmware image on
00114  *             top of another.
00115  *
00116  * @param location Storage location ID.
00117  * @return Returns ERR_NONE on accept, and signals the event handler with
00118  *         either DONE or ERROR when complete.
00119  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00120  */
00121 arm_uc_error_t ARM_UC_PAL_Linux_Activate(uint32_t location);
00122 
00123 /**
00124  * @brief Get firmware details for the firmware image in the slot passed.
00125  * @details This call populates the passed details struct with information
00126  *          about the firmware image in the slot passed. Only the fields
00127  *          marked as supported in the capabilities bitmap will have valid
00128  *          values.
00129  *
00130  * @param details Pointer to firmware details struct to be populated.
00131  * @return Returns ERR_NONE on accept, and signals the event handler with
00132  *         either DONE or ERROR when complete.
00133  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00134  */
00135 arm_uc_error_t ARM_UC_PAL_Linux_GetFirmwareDetails(uint32_t location,
00136                                                    arm_uc_firmware_details_t* details);
00137 
00138 /**
00139  * @brief Get firmware details for the actively running firmware.
00140  * @details This call populates the passed details struct with information
00141  *          about the currently active firmware image. Only the fields
00142  *          marked as supported in the capabilities bitmap will have valid
00143  *          values.
00144  *
00145  * @param details Pointer to firmware details struct to be populated.
00146  * @return Returns ERR_NONE on accept, and signals the event handler with
00147  *         either DONE or ERROR when complete.
00148  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00149  */
00150 arm_uc_error_t ARM_UC_PAL_Linux_GetActiveFirmwareDetails(arm_uc_firmware_details_t* details);
00151 
00152 /**
00153  * @brief Get details for the component responsible for installation.
00154  * @details This call populates the passed details struct with information
00155  *          about the local installer. Only the fields marked as supported
00156  *          in the capabilities bitmap will have valid values. The
00157  *          installer could be the bootloader, a recovery image, or some
00158  *          other component responsible for applying the new firmware
00159  *          image.
00160  *
00161  * @param details Pointer to installer details struct to be populated.
00162  * @return Returns ERR_NONE on accept, and signals the event handler with
00163  *         either DONE or ERROR when complete.
00164  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00165  */
00166 arm_uc_error_t ARM_UC_PAL_Linux_GetInstallerDetails(arm_uc_installer_details_t* details);
00167 
00168 #ifdef __cplusplus
00169 }
00170 #endif
00171 
00172 #endif /* ARM_UC_PAL_Linux_H */