pal_update.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 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 SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_
00020 #define SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_
00021 
00022 #ifndef _PAL_H
00023     #error "Please do not include this file directly, use pal.h instead"
00024 #endif
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 /*! \file pal_update.h
00031 *  \brief PAL update.
00032 *   This file contains the firmware update APIs and is a part of the PAL service API.
00033 *
00034 *   It provides the read, write and activation functionalities for the firmware.
00035 */
00036 
00037 
00038 typedef uint32_t palImageId_t;
00039 
00040 typedef struct _palImageHeaderDeails_t
00041 {
00042     size_t imageSize;
00043     palBuffer_t hash;
00044     uint64_t version;
00045 } palImageHeaderDeails_t;
00046 
00047 typedef enum _palImagePlatformData_t
00048 {
00049     PAL_IMAGE_DATA_FIRST = 0,
00050     PAL_IMAGE_DATA_HASH = PAL_IMAGE_DATA_FIRST,
00051     PAL_IMAGE_DATA_LAST
00052 } palImagePlatformData_t;
00053 
00054 typedef enum _palImageEvents_t
00055 {
00056     PAL_IMAGE_EVENT_FIRST = -1,
00057     PAL_IMAGE_EVENT_ERROR = PAL_IMAGE_EVENT_FIRST,
00058     PAL_IMAGE_EVENT_INIT ,
00059     PAL_IMAGE_EVENT_PREPARE,
00060     PAL_IMAGE_EVENT_WRITE,
00061     PAL_IMAGE_EVENT_FINALIZE,
00062     PAL_IMAGE_EVENT_READTOBUFFER,
00063     PAL_IMAGE_EVENT_ACTIVATE,
00064     PAL_IMAGE_EVENT_ACTIVATE_ERROR,
00065     PAL_IMAGE_EVENT_GETACTIVEHASH,
00066     PAL_IMAGE_EVENT_GETACTIVEVERSION,
00067     PAL_IMAGE_EVENT_WRITEDATATOMEMORY,
00068     PAL_IMAGE_EVENT_LAST
00069 } palImageEvents_t;
00070 
00071 typedef void (*palImageSignalEvent_t)( palImageEvents_t event);
00072 
00073 #define SIZEOF_SHA256               256/8
00074 #define FIRMWARE_HEADER_MAGIC       0x5a51b3d4UL
00075 #define FIRMWARE_HEADER_VERSION     1
00076 #define ACTIVE_IMAGE_INDEX          0xFFFFFFFF
00077 
00078 typedef struct FirmwareHeader {
00079     uint32_t magic;                         ///< Metadata-header specific magic code. */
00080     uint32_t version;                       ///< Revision number for this generic metadata header. */
00081     uint32_t checksum;                      ///< A checksum of this header. This field should be considered to be zeroed out for the sake of computing the checksum.
00082     uint32_t totalSize;                     ///< Total space (in bytes) occupied by the firmware BLOB, including headers and any padding. */
00083     uint64_t firmwareVersion;               ///< Version number for the accompanying firmware. Larger numbers imply more recent and thus preferred versions. This defines the selection order when multiple versions are available.
00084     uint8_t  firmwareSHA256[SIZEOF_SHA256]; ///< A SHA-2 using a block-size of 256-bits of the firmware, including any firmware-padding. */
00085 } FirmwareHeader_t;
00086 
00087 
00088 typedef FirmwareHeader_t palFirmwareHeader_t;
00089 /*! \brief Sets the callback function that is called before the end of each API except `imageGetDirectMemAccess`.
00090  *
00091  * \b WARNING: Do not change this function!
00092  * This function loads a callback function received from the upper layer, the service.
00093  * The callback should be called at the end of each function except `pal_plat_imageGetDirectMemAccess`.
00094  * The callback receives the event type that just occurred, defined by the ENUM `palImageEvents_t`.
00095  *
00096  * If you do not call the callback at the end, the service behavior will be undefined.
00097  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00098  *
00099  * @param[in] CBfunction A pointer to the callback function.
00100  * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00101  */
00102 palStatus_t pal_imageInitAPI(palImageSignalEvent_t CBfunction);
00103 
00104 
00105 /*! \brief Clears all the resources used by the `pal_update` APIs.
00106  * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00107  */
00108 palStatus_t pal_imageDeInit(void);
00109 
00110 /*!\brief  Prepares to write an image with an ID (`imageId`) and size (`imageSize`) in a suitable memory region.
00111  *
00112  * The space available is verified and reserved.
00113  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00114  * @param[in] imageId The image ID.
00115  * @param[in] headerDetails The size of the image.
00116  * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00117  */
00118 palStatus_t pal_imagePrepare(palImageId_t imageId, palImageHeaderDeails_t* headerDetails);
00119 
00120 /*! \brief Writes the data to the chunk buffer with the chunk `bufferLength` in the location of `imageId`, adding the relative offset.
00121  *
00122  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00123  * @param[in] imageId The image ID.
00124  * @param[in] offset The offset to write the data into.
00125  * @param[in] chunk A pointer to struct containing the data and the data length to write.
00126  * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00127  */
00128 palStatus_t pal_imageWrite (palImageId_t imageId, size_t offset, palConstBuffer_t *chunk);
00129 
00130 /*! \brief Flushes the image data and sets the version of `imageId` to `imageVersion`.
00131  *
00132  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00133  * @param[in] imageId The image ID.
00134  * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00135  */
00136 palStatus_t pal_imageFinalize(palImageId_t imageId);
00137 
00138 /*! \brief Verifies whether the image (`imageId`) is readable and sets `imagePtr` to point to the beginning of the image in the memory and `imageSizeInBytes` to the image size.
00139  *
00140  * In case of failure, sets `imagePtr` to NULL and returns the relevant `palStatus_t` error.
00141  * @param[in] imageId The image ID.
00142  * @param[out] imagePtr A pointer to the beginning of the image.
00143  * @param[out] imageSizeInBytes The size of the image.
00144  * \return PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.
00145  */
00146 palStatus_t pal_imageGetDirectMemoryAccess(palImageId_t imageId, void** imagePtr, size_t *imageSizeInBytes);
00147 
00148 /*! \brief Reads the maximum of chunk (`maxBufferLength`) bytes from the image with relative offset and stores it in the chunk buffer.
00149  *
00150  * Also sets the chunk `bufferLength` value to the actual number of bytes read.
00151  * \note Use this API in case an image is not directly accessible via the `imageGetDirectMemAccess` function.
00152  *
00153  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00154  *
00155  * @param[in] imageId The image ID.
00156  * @param[in] offset The offset to start reading from.
00157  * @param[out] chunk A struct containing the data and actual bytes read.
00158  */
00159 palStatus_t pal_imageReadToBuffer(palImageId_t imageId, size_t offset, palBuffer_t* chunk);
00160 
00161 /*! \brief Sets an image as the active image used after the device reset.
00162  *
00163  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00164  *
00165  * @param[in] imageId The image ID.
00166  */
00167 palStatus_t pal_imageActivate(palImageId_t imageId);
00168 
00169 /*! \brief Retrieves the hash value of the active image to the hash buffer with the max size hash (`maxBufferLength`) and sets the hash size to hash `bufferLength`.
00170  *
00171  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00172  * @param[out] hash A struct containing the hash and actual size of hash read.
00173  */
00174 palStatus_t pal_imageGetActiveHash(palBuffer_t* hash);
00175 
00176 /*! \brief Retrieves the data value of the image header.
00177  *
00178  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00179  * @param[in] imageId The image ID.
00180  * @param[out] headerData A struct containing the headerData and actual size of header.
00181  */
00182 palStatus_t pal_imageGetFirmwareHeaderData(palImageId_t imageId, palBuffer_t *headerData);
00183 
00184 /*! \brief Retrieves the version of the active image to the version buffer with the size set to version `bufferLength`.
00185  *
00186  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00187  * @param[out] version A struct containing the version and actual size of version read.
00188  */
00189 palStatus_t pal_imageGetActiveVersion(palBuffer_t* version);
00190 
00191 /*! \brief Writes data to a memory accessible to the bootloader. Currently, only hash is available.
00192  *
00193  * The function must call `g_palUpdateServiceCBfunc` before completing an event.
00194  * @param[in] dataId The data to be written to memory. One of the members of the `palImagePlatformData_t` enum.
00195  * @param[in] dataBuffer A struct containing the data and actual bytes to be written.
00196  */
00197 palStatus_t pal_imageWriteDataToMemory(palImagePlatformData_t dataId, const palConstBuffer_t* const dataBuffer);
00198 
00199 /*! \brief This function gets the working directory for the firmware.
00200  *
00201  * \return full path of the firmware working folder
00202  */
00203 char* pal_imageGetFolder(void);
00204 
00205 #ifdef __cplusplus
00206 }
00207 #endif
00208 #endif /* SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_ */