Mistake on this page? Email us
pal_update.h
Go to the documentation of this file.
1 // ----------------------------------------------------------------------------
2 // Copyright 2016-2019 ARM Ltd.
3 //
4 // SPDX-License-Identifier: Apache-2.0
5 //
6 // Licensed under the Apache License, Version 2.0 (the "License");
7 // you may not use this file except in compliance with the License.
8 // You may obtain a copy of the License at
9 //
10 // http://www.apache.org/licenses/LICENSE-2.0
11 //
12 // Unless required by applicable law or agreed to in writing, software
13 // distributed under the License is distributed on an "AS IS" BASIS,
14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 // See the License for the specific language governing permissions and
16 // limitations under the License.
17 // ----------------------------------------------------------------------------
18 
19 #ifndef SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_
20 #define SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_
21 
22 #ifndef _PAL_H
23  #error "Please do not include this file directly, use pal.h instead"
24 #endif
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
38 typedef uint32_t palImageId_t;
39 
41 {
42  size_t imageSize;
44  uint64_t version;
46 
48 {
53 
54 typedef enum _palImageEvents_t
55 {
70 
71 typedef void (*palImageSignalEvent_t)( palImageEvents_t event);
72 
73 #define SIZEOF_SHA256 256/8
74 #define FIRMWARE_HEADER_MAGIC 0x5a51b3d4UL
75 #define FIRMWARE_HEADER_VERSION 1
76 #define ACTIVE_IMAGE_INDEX 0xFFFFFFFF
77 
78 typedef struct FirmwareHeader {
79  uint32_t magic;
80  uint32_t version;
81  uint32_t checksum;
82  uint32_t totalSize;
83  uint64_t firmwareVersion;
84  uint8_t firmwareSHA256[SIZEOF_SHA256];
86 
87 
103 
104 
109 
118 palStatus_t pal_imagePrepare(palImageId_t imageId, palImageHeaderDeails_t* headerDetails);
119 
128 palStatus_t pal_imageWrite (palImageId_t imageId, size_t offset, palConstBuffer_t *chunk);
129 
136 palStatus_t pal_imageFinalize(palImageId_t imageId);
137 
146 palStatus_t pal_imageGetDirectMemoryAccess(palImageId_t imageId, void** imagePtr, size_t *imageSizeInBytes);
147 
159 palStatus_t pal_imageReadToBuffer(palImageId_t imageId, size_t offset, palBuffer_t* chunk);
160 
167 palStatus_t pal_imageActivate(palImageId_t imageId);
168 
175 
182 palStatus_t pal_imageGetFirmwareHeaderData(palImageId_t imageId, palBuffer_t *headerData);
183 
190 
197 palStatus_t pal_imageWriteDataToMemory(palImagePlatformData_t dataId, const palConstBuffer_t* const dataBuffer);
198 
203 char* pal_imageGetFolder(void);
204 
205 #ifdef __cplusplus
206 }
207 #endif
208 #endif /* SOURCE_PAL_IMPL_SERVICES_API_PAL_UPDATE_H_ */
palStatus_t pal_imageDeInit(void)
Clears all the resources used by the pal_update APIs.
char * pal_imageGetFolder(void)
This function gets the working directory for the firmware.
Definition: pal_types.h:57
Definition: pal_update.h:58
struct _palImageHeaderDeails_t palImageHeaderDeails_t
size_t imageSize
Definition: pal_update.h:42
Definition: pal_update.h:57
palStatus_t pal_imageWriteDataToMemory(palImagePlatformData_t dataId, const palConstBuffer_t *const dataBuffer)
Writes data to a memory accessible to the bootloader. Currently, only hash is available.
Definition: pal_update.h:66
Definition: pal_update.h:64
palStatus_t pal_imageWrite(palImageId_t imageId, size_t offset, palConstBuffer_t *chunk)
Writes the data to the chunk buffer with the chunk bufferLength in the location of imageId...
palStatus_t pal_imageGetDirectMemoryAccess(palImageId_t imageId, void **imagePtr, size_t *imageSizeInBytes)
Verifies whether the image (imageId) is readable and sets imagePtr to point to the beginning of the i...
Definition: pal_update.h:62
Definition: pal_update.h:40
Definition: pal_update.h:65
Definition: pal_update.h:68
Definition: pal_update.h:78
_palImagePlatformData_t
Definition: pal_update.h:47
uint32_t checksum
A checksum of this header. This field should be considered to be zeroed out for the sake of computing...
Definition: pal_update.h:81
uint32_t magic
Metadata-header specific magic code. */.
Definition: pal_update.h:79
palStatus_t pal_imagePrepare(palImageId_t imageId, palImageHeaderDeails_t *headerDetails)
Prepares to write an image with an ID (imageId) and size (imageSize) in a suitable memory region...
palStatus_t pal_imageActivate(palImageId_t imageId)
Sets an image as the active image used after the device reset.
Definition: pal_update.h:56
palStatus_t pal_imageReadToBuffer(palImageId_t imageId, size_t offset, palBuffer_t *chunk)
Reads the maximum of chunk (maxBufferLength) bytes from the image with relative offset and stores it ...
Definition: pal_update.h:63
uint32_t version
Revision number for this generic metadata header. */.
Definition: pal_update.h:80
Definition: pal_update.h:51
Definition: pal_types.h:64
palStatus_t pal_imageInitAPI(palImageSignalEvent_t CBfunction)
Sets the callback function that is called before the end of each API except imageGetDirectMemAccess.
uint64_t version
Definition: pal_update.h:44
void(* palImageSignalEvent_t)(palImageEvents_t event)
Definition: pal_update.h:71
Definition: pal_update.h:61
_palImageEvents_t
Definition: pal_update.h:54
enum _palImagePlatformData_t palImagePlatformData_t
#define SIZEOF_SHA256
Definition: pal_update.h:73
uint32_t palImageId_t
Definition: pal_update.h:38
FirmwareHeader_t palFirmwareHeader_t
Definition: pal_update.h:88
palStatus_t pal_imageGetFirmwareHeaderData(palImageId_t imageId, palBuffer_t *headerData)
Retrieves the data value of the image header.
Definition: pal_update.h:49
Definition: pal_update.h:60
palBuffer_t hash
Definition: pal_update.h:43
Definition: pal_update.h:50
Definition: pal_update.h:67
uint64_t firmwareVersion
Version number for the accompanying firmware. Larger numbers imply more recent and thus preferred ver...
Definition: pal_update.h:83
palStatus_t pal_imageGetActiveHash(palBuffer_t *hash)
Retrieves the hash value of the active image to the hash buffer with the max size hash (maxBufferLeng...
enum _palImageEvents_t palImageEvents_t
int32_t palStatus_t
Definition: pal_types.h:55
uint32_t totalSize
Total space (in bytes) occupied by the firmware BLOB, including headers and any padding. */.
Definition: pal_update.h:82
struct FirmwareHeader FirmwareHeader_t
palStatus_t pal_imageFinalize(palImageId_t imageId)
Flushes the image data and sets the version of imageId to imageVersion.
palStatus_t pal_imageGetActiveVersion(palBuffer_t *version)
Retrieves the version of the active image to the version buffer with the size set to version bufferLe...
Definition: pal_update.h:59