Toyomasa Watarai / simple-mbed-cloud-client

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:  

mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Services-API/pal_update.h@0:276e7a263c35, 2018-07-02 (annotated)

Committer:
MACRUM
Date:
Mon Jul 02 06:30:39 2018 +0000
Revision:
0:276e7a263c35
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MACRUM 0:276e7a263c35 1 /*******************************************************************************
MACRUM 0:276e7a263c35 2 * Copyright 2016, 2017 ARM Ltd.
MACRUM 0:276e7a263c35 3 *
MACRUM 0:276e7a263c35 4 * Licensed under the Apache License, Version 2.0 (the "License");
MACRUM 0:276e7a263c35 5 * you may not use this file except in compliance with the License.
MACRUM 0:276e7a263c35 6 * You may obtain a copy of the License at
MACRUM 0:276e7a263c35 7 *
MACRUM 0:276e7a263c35 8 * http://www.apache.org/licenses/LICENSE-2.0
MACRUM 0:276e7a263c35 9 *
MACRUM 0:276e7a263c35 10 * Unless required by applicable law or agreed to in writing, software
MACRUM 0:276e7a263c35 11 * distributed under the License is distributed on an "AS IS" BASIS,
MACRUM 0:276e7a263c35 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
MACRUM 0:276e7a263c35 13 * See the License for the specific language governing permissions and
MACRUM 0:276e7a263c35 14 * limitations under the License.
MACRUM 0:276e7a263c35 15 *******************************************************************************/
MACRUM 0:276e7a263c35 16
MACRUM 0:276e7a263c35 17 #ifndef SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_
MACRUM 0:276e7a263c35 18 #define SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_
MACRUM 0:276e7a263c35 19
MACRUM 0:276e7a263c35 20 #ifndef _PAL_H
MACRUM 0:276e7a263c35 21 #error "Please do not include this file directly, use pal.h instead"
MACRUM 0:276e7a263c35 22 #endif
MACRUM 0:276e7a263c35 23
MACRUM 0:276e7a263c35 24 #ifdef __cplusplus
MACRUM 0:276e7a263c35 25 extern "C" {
MACRUM 0:276e7a263c35 26 #endif
MACRUM 0:276e7a263c35 27
MACRUM 0:276e7a263c35 28 /*! \file pal_update.h
MACRUM 0:276e7a263c35 29 * \brief PAL update.
MACRUM 0:276e7a263c35 30 * This file contains the firmware update APIs and is a part of the PAL service API.
MACRUM 0:276e7a263c35 31 * It provides the read/write and activation functionalities for the firmware.
MACRUM 0:276e7a263c35 32 */
MACRUM 0:276e7a263c35 33
MACRUM 0:276e7a263c35 34
MACRUM 0:276e7a263c35 35 typedef uint32_t palImageId_t;
MACRUM 0:276e7a263c35 36
MACRUM 0:276e7a263c35 37 typedef struct _palImageHeaderDeails_t
MACRUM 0:276e7a263c35 38 {
MACRUM 0:276e7a263c35 39 size_t imageSize;
MACRUM 0:276e7a263c35 40 palBuffer_t hash;
MACRUM 0:276e7a263c35 41 uint64_t version;
MACRUM 0:276e7a263c35 42 } palImageHeaderDeails_t;
MACRUM 0:276e7a263c35 43
MACRUM 0:276e7a263c35 44 typedef enum _palImagePlatformData_t
MACRUM 0:276e7a263c35 45 {
MACRUM 0:276e7a263c35 46 PAL_IMAGE_DATA_FIRST = 0,
MACRUM 0:276e7a263c35 47 PAL_IMAGE_DATA_HASH = PAL_IMAGE_DATA_FIRST,
MACRUM 0:276e7a263c35 48 PAL_IMAGE_DATA_LAST
MACRUM 0:276e7a263c35 49 } palImagePlatformData_t;
MACRUM 0:276e7a263c35 50
MACRUM 0:276e7a263c35 51 typedef enum _palImageEvents_t
MACRUM 0:276e7a263c35 52 {
MACRUM 0:276e7a263c35 53 PAL_IMAGE_EVENT_FIRST = -1,
MACRUM 0:276e7a263c35 54 PAL_IMAGE_EVENT_ERROR = PAL_IMAGE_EVENT_FIRST,
MACRUM 0:276e7a263c35 55 PAL_IMAGE_EVENT_INIT ,
MACRUM 0:276e7a263c35 56 PAL_IMAGE_EVENT_PREPARE,
MACRUM 0:276e7a263c35 57 PAL_IMAGE_EVENT_WRITE,
MACRUM 0:276e7a263c35 58 PAL_IMAGE_EVENT_FINALIZE,
MACRUM 0:276e7a263c35 59 PAL_IMAGE_EVENT_READTOBUFFER,
MACRUM 0:276e7a263c35 60 PAL_IMAGE_EVENT_ACTIVATE,
MACRUM 0:276e7a263c35 61 PAL_IMAGE_EVENT_ACTIVATE_ERROR,
MACRUM 0:276e7a263c35 62 PAL_IMAGE_EVENT_GETACTIVEHASH,
MACRUM 0:276e7a263c35 63 PAL_IMAGE_EVENT_GETACTIVEVERSION,
MACRUM 0:276e7a263c35 64 PAL_IMAGE_EVENT_WRITEDATATOMEMORY,
MACRUM 0:276e7a263c35 65 PAL_IMAGE_EVENT_LAST
MACRUM 0:276e7a263c35 66 } palImageEvents_t;
MACRUM 0:276e7a263c35 67
MACRUM 0:276e7a263c35 68 typedef void (*palImageSignalEvent_t)( palImageEvents_t event);
MACRUM 0:276e7a263c35 69
MACRUM 0:276e7a263c35 70 #define SIZEOF_SHA256 256/8
MACRUM 0:276e7a263c35 71 #define FIRMWARE_HEADER_MAGIC 0x5a51b3d4UL
MACRUM 0:276e7a263c35 72 #define FIRMWARE_HEADER_VERSION 1
MACRUM 0:276e7a263c35 73 #define ACTIVE_IMAGE_INDEX 0xFFFFFFFF
MACRUM 0:276e7a263c35 74
MACRUM 0:276e7a263c35 75 typedef struct FirmwareHeader {
MACRUM 0:276e7a263c35 76 uint32_t magic; /** Metadata-header specific magic code. */
MACRUM 0:276e7a263c35 77 uint32_t version; /** Revision number for this generic metadata header. */
MACRUM 0:276e7a263c35 78 uint32_t checksum; /** A checksum of this header. This field should be considered to be zeroed out for
MACRUM 0:276e7a263c35 79 * the sake of computing the checksum. */
MACRUM 0:276e7a263c35 80 uint32_t totalSize; /** Total space (in bytes) occupied by the firmware BLOB, including headers and any padding. */
MACRUM 0:276e7a263c35 81 uint64_t firmwareVersion; /** Version number for the accompanying firmware. Larger numbers imply more preferred (recent)
MACRUM 0:276e7a263c35 82 * versions. This defines the selection order when multiple versions are available. */
MACRUM 0:276e7a263c35 83 uint8_t firmwareSHA256[SIZEOF_SHA256]; /** A SHA-2 using a block-size of 256-bits of the firmware, including any firmware-padding. */
MACRUM 0:276e7a263c35 84 } FirmwareHeader_t;
MACRUM 0:276e7a263c35 85
MACRUM 0:276e7a263c35 86
MACRUM 0:276e7a263c35 87 typedef FirmwareHeader_t palFirmwareHeader_t;
MACRUM 0:276e7a263c35 88 /*! Sets the callback function that is called before the end of each API (except `imageGetDirectMemAccess`).
MACRUM 0:276e7a263c35 89 *
MACRUM 0:276e7a263c35 90 * WARNING: Do not change this function!
MACRUM 0:276e7a263c35 91 * This function loads a callback function received from the upper layer (service).
MACRUM 0:276e7a263c35 92 * The callback should be called at the end of each function (except `pal_plat_imageGetDirectMemAccess`).
MACRUM 0:276e7a263c35 93 * The callback receives the event type that just occurred, defined by the ENUM `palImageEvents_t`.
MACRUM 0:276e7a263c35 94 *
MACRUM 0:276e7a263c35 95 * If you do not call the callback at the end, the service behaviour will be undefined.
MACRUM 0:276e7a263c35 96 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 97 *
MACRUM 0:276e7a263c35 98 * @param[in] CBfunction A pointer to the callback function.
MACRUM 0:276e7a263c35 99 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 100 */
MACRUM 0:276e7a263c35 101 palStatus_t pal_imageInitAPI(palImageSignalEvent_t CBfunction);
MACRUM 0:276e7a263c35 102
MACRUM 0:276e7a263c35 103
MACRUM 0:276e7a263c35 104 /*! Clears all the resources used by the `pal_update` APIs.
MACRUM 0:276e7a263c35 105 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 106 */
MACRUM 0:276e7a263c35 107 palStatus_t pal_imageDeInit(void);
MACRUM 0:276e7a263c35 108
MACRUM 0:276e7a263c35 109 /*! Prepares to write an image with an ID (`imageId`) and size (`imageSize`) in a suitable memory region. The space available is verified and reserved.
MACRUM 0:276e7a263c35 110 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 111 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 112 * @param[in] headerDetails The size of the image.
MACRUM 0:276e7a263c35 113 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 114 */
MACRUM 0:276e7a263c35 115 palStatus_t pal_imagePrepare(palImageId_t imageId, palImageHeaderDeails_t* headerDetails);
MACRUM 0:276e7a263c35 116
MACRUM 0:276e7a263c35 117 /*! Writes the data to the chunk buffer with the chunk `bufferLength` in the location of `imageId` adding the relative offset.
MACRUM 0:276e7a263c35 118 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 119 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 120 * @param[in] offset The offset to write the data into.
MACRUM 0:276e7a263c35 121 * @param[in] chunk A pointer to struct containing the data and the data length to write.
MACRUM 0:276e7a263c35 122 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 123 */
MACRUM 0:276e7a263c35 124 palStatus_t pal_imageWrite (palImageId_t imageId, size_t offset, palConstBuffer_t *chunk);
MACRUM 0:276e7a263c35 125
MACRUM 0:276e7a263c35 126 /*! Flushes the image data and sets the version of `imageId` to `imageVersion`.
MACRUM 0:276e7a263c35 127 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 128 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 129 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 130 */
MACRUM 0:276e7a263c35 131 palStatus_t pal_imageFinalize(palImageId_t imageId);
MACRUM 0:276e7a263c35 132
MACRUM 0:276e7a263c35 133 /*! 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.
MACRUM 0:276e7a263c35 134 * In case of failure, sets `imagePtr` to NULL and returns the relevant `palStatus_t` error.
MACRUM 0:276e7a263c35 135 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 136 * @param[out] imagePtr A pointer to the beginning of the image.
MACRUM 0:276e7a263c35 137 * @param[out] imageSizeInBytes The size of the image.
MACRUM 0:276e7a263c35 138 * \return PAL_SUCCESS(0) in case of success and a negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 139 */
MACRUM 0:276e7a263c35 140 palStatus_t pal_imageGetDirectMemoryAccess(palImageId_t imageId, void** imagePtr, size_t *imageSizeInBytes);
MACRUM 0:276e7a263c35 141
MACRUM 0:276e7a263c35 142 /*! Reads the maximum of chunk (`maxBufferLength`) bytes from the image (`imageId`) with relative offset and stores it in the chunk buffer.
MACRUM 0:276e7a263c35 143 * Also sets the chunk `bufferLength` value to the actual number of bytes read.
MACRUM 0:276e7a263c35 144 * \note Use this API in the case image is not directly accessible via the `imageGetDirectMemAccess` function.
MACRUM 0:276e7a263c35 145 *
MACRUM 0:276e7a263c35 146 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 147 *
MACRUM 0:276e7a263c35 148 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 149 * @param[in] offset The offset to start reading from.
MACRUM 0:276e7a263c35 150 * @param[out] chunk A struct containing the data and actual bytes read.
MACRUM 0:276e7a263c35 151 */
MACRUM 0:276e7a263c35 152 palStatus_t pal_imageReadToBuffer(palImageId_t imageId, size_t offset, palBuffer_t* chunk);
MACRUM 0:276e7a263c35 153
MACRUM 0:276e7a263c35 154 /*! Sets an image (`imageId`) as the active image (after the device reset).
MACRUM 0:276e7a263c35 155 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 156 *
MACRUM 0:276e7a263c35 157 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 158 */
MACRUM 0:276e7a263c35 159 palStatus_t pal_imageActivate(palImageId_t imageId);
MACRUM 0:276e7a263c35 160
MACRUM 0:276e7a263c35 161 /*! 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`.
MACRUM 0:276e7a263c35 162 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 163 * @param[out] hash A struct containing the hash and actual size of hash read.
MACRUM 0:276e7a263c35 164 */
MACRUM 0:276e7a263c35 165 palStatus_t pal_imageGetActiveHash(palBuffer_t* hash);
MACRUM 0:276e7a263c35 166
MACRUM 0:276e7a263c35 167
MACRUM 0:276e7a263c35 168 /*! Retrieves the data value of the image header.
MACRUM 0:276e7a263c35 169 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 170 * @param[in] imageId The image ID.
MACRUM 0:276e7a263c35 171 * @param[out] headerData A struct containing the headerData and actual size of header.
MACRUM 0:276e7a263c35 172 */
MACRUM 0:276e7a263c35 173 palStatus_t pal_imageGetFirmwareHeaderData(palImageId_t imageId, palBuffer_t *headerData);
MACRUM 0:276e7a263c35 174
MACRUM 0:276e7a263c35 175
MACRUM 0:276e7a263c35 176 /*! Retrieves the version of the active image to the version buffer with the size set to version `bufferLength`.
MACRUM 0:276e7a263c35 177 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 178 * @param[out] version A struct containing the version and actual size of version read.
MACRUM 0:276e7a263c35 179 */
MACRUM 0:276e7a263c35 180 palStatus_t pal_imageGetActiveVersion(palBuffer_t* version);
MACRUM 0:276e7a263c35 181
MACRUM 0:276e7a263c35 182 /*! Writes the data of `dataId` stored in `dataBuffer` to a memory accessible to the bootloader. Currently, only hash is available.
MACRUM 0:276e7a263c35 183 * The function must call `g_palUpdateServiceCBfunc` before completing an event.
MACRUM 0:276e7a263c35 184 * @param[in] dataId One of the members of the `palImagePlatformData_t` enum.
MACRUM 0:276e7a263c35 185 * @param[in] dataBuffer A struct containing the data and actual bytes to be written.
MACRUM 0:276e7a263c35 186 */
MACRUM 0:276e7a263c35 187 palStatus_t pal_imageWriteDataToMemory(palImagePlatformData_t dataId, const palConstBuffer_t* const dataBuffer);
MACRUM 0:276e7a263c35 188
MACRUM 0:276e7a263c35 189
MACRUM 0:276e7a263c35 190 /*! \brief This function gets the firmware working directory.
MACRUM 0:276e7a263c35 191 *
MACRUM 0:276e7a263c35 192 * \return full path of the firmware working folder
MACRUM 0:276e7a263c35 193 */
MACRUM 0:276e7a263c35 194 char* pal_imageGetFolder(void);
MACRUM 0:276e7a263c35 195
MACRUM 0:276e7a263c35 196 #ifdef __cplusplus
MACRUM 0:276e7a263c35 197 }
MACRUM 0:276e7a263c35 198 #endif
MACRUM 0:276e7a263c35 199 #endif /* SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_ */