KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
update.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  * ----------------------
4  *
5  * Copyright 2013 KM3NeT Collaboration
6  *
7  * All Rights Reserved.
8  *
9  *
10  * File : storage.h
11  * Created : 8 okt. 2013
12  * Author : Vincent van Beveren
13  */
14 
15 #ifndef UPDATE_H_
16 #define UPDATE_H_
17 
18 /**
19  * @file
20  *
21  * @ingroup kernel
22  *
23  * Facilitates the update process.
24  */
25 #include <stdbool.h>
26 #include <stdint.h>
27 #include <cfg_soc.h>
28 
29 #include "errorcode.h"
30 
31 
32 #define UPD_CHUNK_SIZE 512 //!< chunk size for updates, in bytes
33 #define UPD_CHUNK_MAX ( FLASH_SPACING / UPD_CHUNK_SIZE )
34 
35 #define E_UPD_SOMECHUNKS ( E_UPD + 0x01 ) ///< Some chunks lost, check chunkLostList.
36 #define E_UPD_SOMECHUNKS_DESCR "Some chunks lost"
37 
38 #define E_UPD_MANYCHUNKS ( E_UPD + 0x02 ) ///< Too many chunks lost, redo update.
39 #define E_UPD_MANYCHUNKS_DESCR "Too many chunks lost"
40 
41 #define E_UPD_CHECKSUM ( E_UPD + 0x03 ) ///< The checksum failed, redo update.
42 #define E_UPD_CHECKSUM_DESCR "Image checksum invalid"
43 
44 #define E_UPD_PROTECTED ( E_UPD + 0x04 ) ///< Protection is not cleared
45 #define E_UPD_PROTECTED_DESCR "Protection present"
46 
47 /// Maximum no of images.
48 extern const int updMaxImages;
49 
50 /**
51  * Initializes the update module. Check whether or not protection of golden image is in place,
52  * and if not, puts it there.
53  */
54 bool updInit();
55 
56 /**
57  * Starts an image update.
58  *
59  * The password is required for the golden image (image index 0), once it is protected using
60  * the updProtectGolden() command.
61  *
62  * @param imageIdx The image index you wish to update.
63  * @param chunkCount The no of chunks send.
64  *
65  * @retval true System is ready to receive the updates.
66  * @retval false System is not ready to recieve the updates, check errCode().
67  */
68 bool updStart(int imageIdx, uint32_t chunkCount);
69 
70 /**
71  * Write a update chunk.
72  *
73  * @param chunkNo The index of the chunk to write.
74  * @param chunk Pointer to a array of chunkSize bytes.
75  *
76  * @retval true Update chunk written.
77  * @retval false The update could not be written, check errCode().
78  */
79 bool updWrite(uint32_t chunkNo, uint8_t * chunk);
80 
81 /**
82  * Ends the update. Returns an array of chunks which have not been received or written
83  * correctly. When this function returns `false` the update process will not be stopped.
84  *
85  *
86  * @param chunkLostList A pointer to an array of lost chunk indexes.
87  * @param chunksCount The number of lost chunks.
88  *
89  * @retval true Update completed, image valid.
90  * @retval false The update was not completed, update not ended.
91  */
92 bool updEnd(uint32_t * chunkLostList, uint32_t * chunksCount);
93 
94 /**
95  * Aborts the update. May leave an invalid image in he persistent storage.
96  */
97 void updCancel();
98 
99 /**
100  * Verify a chunk.
101  *
102  * @param imgNo The image number.
103  * @param chunkNo The chunk number
104  * @param chunk The chunk data
105  * @param result pointer to the result, either true - they are the same,
106  * false - there are differences
107  *
108  * @retval true Command successful.
109  * @retval false Command failed, check error module for code and message
110  */
111 bool updVerify(uint32_t imgNo, uint32_t chunkNo, uint8_t * chunk, bool * result);
112 
113 /**
114  * Returns whether or not the storage is in update mode.
115  *
116  * @param index The pointer is filled with the image currently updated,
117  * if at all. Index may be null.
118  *
119  * @retval true The system is in update mode.
120  * @retval false The system is not in update mode.
121  */
122 bool updIsUpdating(int * index);
123 
124 
125 /**
126  * Unlocks the golden image for writing.
127  *
128  * @retval true The image was unlocked.
129  * @retval false The image was not unlocked.
130  */
131 bool updUnlock();
132 
133 
134 #define UPD_IMGTYPE_NONE ((int8_t)-1) //!< There is no image at the specified location
135 #define UPD_IMGTYPE_UNKNOWN 0 //!< There is an image, but it has no meta-data
136 #define UPD_IMGTYPE_GOLDEN 1 //!< Golden image
137 #define UPD_IMGTYPE_RUNTIME 2 //!< Runtime image
138 #define UPD_IMGTYPE_BASE 3 //!< Base image
139 #define UPD_IMGTYPE_CALIB 4 //!< Calibration image
140 
141 typedef struct _UpdImgInfo
142 {
143  uint32_t fwRev; //!< Firmware revision
144  uint32_t swRev; //!< Software revision
145  int8_t imgType; //!< Image type
146 } UpdImgInfo;
147 
148 /**
149  * Retrieve image information for the specified location
150  *
151  * @param imgNo The image number.
152  * @param imgInfo Pointer to an image information structure to fill.
153  *
154  * @retval true Command successful.
155  * @retval false Command failed, check error module for code and message
156  */
157 bool updImgInfo(uint32_t imgNo, UpdImgInfo * imgInfo);
158 
159 /**
160  * Locks the golden image for writing. Normally the golden image is locked after a succesful
161  * update.
162  *
163  * @retval true The image was locked
164  * @retval false The image was not locked.
165  */
166 bool updLock();
167 
168 #endif /* UPDATE_H_ */
bool updVerify(uint32_t imgNo, uint32_t chunkNo, uint8_t *chunk, bool *result)
Verify a chunk.
Definition: update.c:143
bool updWrite(uint32_t chunkNo, uint8_t *chunk)
Write a update chunk.
Definition: update.c:102
Defines the configuration of the LM32 SOC for the CLBv2.
bool updUnlock()
Unlocks the golden image for writing.
Definition: update.c:225
bool updImgInfo(uint32_t imgNo, UpdImgInfo *imgInfo)
Retrieve image information for the specified location.
Definition: update.c:193
bool updIsUpdating(int *index)
Returns whether or not the storage is in update mode.
Definition: update.c:188
int8_t imgType
Image type.
Definition: update.h:145
bool updInit()
Initializes the update module.
Definition: update.c:64
bool updEnd(uint32_t *chunkLostList, uint32_t *chunksCount)
Ends the update.
Definition: update.c:163
bool updLock()
Locks the golden image for writing.
Definition: update.c:230
bool updStart(int imageIdx, uint32_t chunkCount)
Starts an image update.
Definition: update.c:81
void updCancel()
Aborts the update.
Definition: update.c:178
uint32_t swRev
Software revision.
Definition: update.h:144
uint32_t fwRev
Firmware revision.
Definition: update.h:143
This module is responsible for distributing error codes.
const int updMaxImages
Maximum no of images.
Definition: update.c:43