le_flash_common.h

Go to the documentation of this file.
1 
2 /*
3  * ====================== WARNING ======================
4  *
5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
6  * DO NOT MODIFY IN ANY WAY.
7  *
8  * ====================== WARNING ======================
9  */
10 /**
11  * @file le_flash_common.h
12  *
13  * Type definitions for le_flash.
14  *
15  */
16 #ifndef LE_FLASH_COMMON_H_INCLUDE_GUARD
17 #define LE_FLASH_COMMON_H_INCLUDE_GUARD
18 
19 
20 #include "legato.h"
21 
22 #define IFGEN_LE_FLASH_PROTOCOL_ID "a36a81bca852297786086f08a8884cda"
23 #define IFGEN_LE_FLASH_MSG_SIZE 262164
24 /** @addtogroup le_flash
25  * @{ **/
26 
27 
28 //--------------------------------------------------------------------------------------------------
29 /**
30  * Image length maximum length.
31  *
32  */
33 //--------------------------------------------------------------------------------------------------
34 #define LE_FLASH_IMAGE_NAME_MAX_LEN 32
35 
36 //--------------------------------------------------------------------------------------------------
37 /**
38  * Image length maximum length.
39  * One extra byte is added for the null character.
40  */
41 //--------------------------------------------------------------------------------------------------
42 #define LE_FLASH_IMAGE_NAME_MAX_BYTES 33
43 
44 //--------------------------------------------------------------------------------------------------
45 /**
46  * Maximum partition name length
47  */
48 //--------------------------------------------------------------------------------------------------
49 #define LE_FLASH_PARTITION_NAME_MAX_LEN 50
50 
51 //--------------------------------------------------------------------------------------------------
52 /**
53  * Maximum partition name length
54  * One extra byte is added for the null character.
55  */
56 //--------------------------------------------------------------------------------------------------
57 #define LE_FLASH_PARTITION_NAME_MAX_BYTES 51
58 
59 //--------------------------------------------------------------------------------------------------
60 /**
61  * Maximum volume name length
62  */
63 //--------------------------------------------------------------------------------------------------
64 #define LE_FLASH_VOLUME_NAME_MAX_LEN 50
65 
66 //--------------------------------------------------------------------------------------------------
67 /**
68  * Maximum volume name length
69  * One extra byte is added for the null character.
70  */
71 //--------------------------------------------------------------------------------------------------
72 #define LE_FLASH_VOLUME_NAME_MAX_BYTES 51
73 
74 //--------------------------------------------------------------------------------------------------
75 /**
76  * Max byte storage size for write buffer
77  */
78 //--------------------------------------------------------------------------------------------------
79 #define LE_FLASH_MAX_WRITE_SIZE 262144
80 
81 //--------------------------------------------------------------------------------------------------
82 /**
83  * Max byte storage size for read buffer
84  */
85 //--------------------------------------------------------------------------------------------------
86 #define LE_FLASH_MAX_READ_SIZE 262144
87 
88 //--------------------------------------------------------------------------------------------------
89 /**
90  * Default volume size to keep the current volume size untouched
91  */
92 //--------------------------------------------------------------------------------------------------
93 #define LE_FLASH_UBI_VOL_NO_SIZE -1
94 
95 //--------------------------------------------------------------------------------------------------
96 /**
97  * Default volume ID to specify the automatic allocation of volume ID
98  */
99 //--------------------------------------------------------------------------------------------------
100 #define LE_FLASH_UBI_VOL_NO_ID -1
101 
102 //--------------------------------------------------------------------------------------------------
103 /**
104  * Maximum volume ID
105  */
106 //--------------------------------------------------------------------------------------------------
107 #define LE_FLASH_UBI_VOL_ID_MAX 127
108 
109 //--------------------------------------------------------------------------------------------------
110 /**
111  * Open mode.
112  */
113 //--------------------------------------------------------------------------------------------------
114 typedef enum
115 {
116  LE_FLASH_READ_ONLY = 0,
117  ///<
118  LE_FLASH_WRITE_ONLY = 1,
119  ///<
120  LE_FLASH_READ_WRITE = 2
121  ///<
122 }
124 
125 
126 //--------------------------------------------------------------------------------------------------
127 /**
128  * UBI volume type mode.
129  */
130 //--------------------------------------------------------------------------------------------------
131 typedef enum
132 {
133  LE_FLASH_DYNAMIC = 0,
134  ///<
135  LE_FLASH_STATIC = 1
136  ///<
137 }
139 
140 
141 //--------------------------------------------------------------------------------------------------
142 /**
143  * Declare a reference type for referring a partition.
144  */
145 //--------------------------------------------------------------------------------------------------
146 typedef struct le_flash_Partition* le_flash_PartitionRef_t;
147 
148 
149 //--------------------------------------------------------------------------------------------------
150 /**
151  * Reference type used by Add/Remove functions for EVENT 'le_flash_BadImageDetection'
152  */
153 //--------------------------------------------------------------------------------------------------
154 typedef struct le_flash_BadImageDetectionHandler* le_flash_BadImageDetectionHandlerRef_t;
155 
156 
157 //--------------------------------------------------------------------------------------------------
158 /**
159  * Handler for bad image detection.
160  *
161  * @note The image names are platform dependent.
162  */
163 //--------------------------------------------------------------------------------------------------
165 (
166  const char* LE_NONNULL imageName,
167  ///< bad image name
168  void* contextPtr
169  ///<
170 );
171 
172 
173 //--------------------------------------------------------------------------------------------------
174 /**
175  * Get if this client bound locally.
176  */
177 //--------------------------------------------------------------------------------------------------
178 LE_SHARED bool ifgen_le_flash_HasLocalBinding
179 (
180  void
181 );
182 
183 
184 //--------------------------------------------------------------------------------------------------
185 /**
186  * Init data that is common across all threads
187  */
188 //--------------------------------------------------------------------------------------------------
189 LE_SHARED void ifgen_le_flash_InitCommonData
190 (
191  void
192 );
193 
194 
195 //--------------------------------------------------------------------------------------------------
196 /**
197  * Perform common initialization and open a session
198  */
199 //--------------------------------------------------------------------------------------------------
200 LE_SHARED le_result_t ifgen_le_flash_OpenSession
201 (
202  le_msg_SessionRef_t _ifgen_sessionRef,
203  bool isBlocking
204 );
205 
206 //--------------------------------------------------------------------------------------------------
207 /**
208  * Add handler function for EVENT 'le_flash_BadImageDetection'
209  *
210  * This event provides information on bad image status.
211  *
212  */
213 //--------------------------------------------------------------------------------------------------
214 LE_SHARED le_flash_BadImageDetectionHandlerRef_t ifgen_le_flash_AddBadImageDetectionHandler
215 (
216  le_msg_SessionRef_t _ifgen_sessionRef,
218  ///< [IN]
219  void* contextPtr
220  ///< [IN]
221 );
222 
223 //--------------------------------------------------------------------------------------------------
224 /**
225  * Remove handler function for EVENT 'le_flash_BadImageDetection'
226  */
227 //--------------------------------------------------------------------------------------------------
228 LE_SHARED void ifgen_le_flash_RemoveBadImageDetectionHandler
229 (
230  le_msg_SessionRef_t _ifgen_sessionRef,
232  ///< [IN]
233 );
234 
235 //--------------------------------------------------------------------------------------------------
236 /**
237  * Request the flash access authorization. This is required to avoid race operations.
238  *
239  * @return
240  * - LE_OK On success
241  * - LE_UNAVAILABLE The flash access is temporarily unavailable
242  * - LE_DUPLICATE If the a request access for the client was already performed
243  * - LE_FAULT On failure
244  *
245  */
246 //--------------------------------------------------------------------------------------------------
247 LE_SHARED le_result_t ifgen_le_flash_RequestAccess
248 (
249  le_msg_SessionRef_t _ifgen_sessionRef
250 );
251 
252 //--------------------------------------------------------------------------------------------------
253 /**
254  * Release the flash access requested by le_flash_RequestAccess API.
255  *
256  * @return
257  * - LE_OK On success
258  * - LE_FAULT On failure
259  *
260  */
261 //--------------------------------------------------------------------------------------------------
262 LE_SHARED le_result_t ifgen_le_flash_ReleaseAccess
263 (
264  le_msg_SessionRef_t _ifgen_sessionRef
265 );
266 
267 //--------------------------------------------------------------------------------------------------
268 /**
269  * Open a flash partition at the block layer for the given operation and return a descriptor.
270  * The read and write operation will be done using MTD.
271  *
272  * @return
273  * - LE_OK On success
274  * - LE_BAD_PARAMETER If a parameter is invalid
275  * - LE_NOT_FOUND If the flash partition is not found
276  * - LE_FAULT On failure
277  *
278  */
279 //--------------------------------------------------------------------------------------------------
280 LE_SHARED le_result_t ifgen_le_flash_OpenMtd
281 (
282  le_msg_SessionRef_t _ifgen_sessionRef,
283  const char* LE_NONNULL partitionName,
284  ///< [IN] Partition to be opened.
285  le_flash_OpenMode_t mode,
286  ///< [IN] Opening mode.
287  le_flash_PartitionRef_t* partitionRefPtr
288  ///< [OUT] Partition reference.
289 );
290 
291 //--------------------------------------------------------------------------------------------------
292 /**
293  * Open a UBI volume for the given operation and return a descriptor. The read and write
294  * operation will be done using MTD, UBI metadata will be updated.
295  *
296  * @return
297  * - LE_OK On success
298  * - LE_BAD_PARAMETER If a parameter is invalid
299  * - LE_NOT_FOUND If the flash partition is not found
300  * - LE_FAULT On failure
301  *
302  */
303 //--------------------------------------------------------------------------------------------------
304 LE_SHARED le_result_t ifgen_le_flash_OpenUbi
305 (
306  le_msg_SessionRef_t _ifgen_sessionRef,
307  const char* LE_NONNULL partitionName,
308  ///< [IN] Partition to be opened.
309  le_flash_OpenMode_t mode,
310  ///< [IN] Opening mode.
311  le_flash_PartitionRef_t* partitionRefPtr
312  ///< [OUT] Partition reference.
313 );
314 
315 //--------------------------------------------------------------------------------------------------
316 /**
317  * Open the UBI volume of an UBI image to be used for the read and write operations. When open for
318  * writing and a volumeSize is given, the UBI volume will be adjusted to this size by freeing the
319  * PEBs over this size. If the data inside the volume require more PEBs, they will be added
320  * by the le_flash_Write() API.
321  *
322  * @return
323  * - LE_OK On success
324  * - LE_BAD_PARAMETER If a parameter is invalid
325  * - LE_NOT_FOUND If the volume name is not found
326  * - LE_FAULT On failure
327  *
328  */
329 //--------------------------------------------------------------------------------------------------
330 LE_SHARED le_result_t ifgen_le_flash_OpenUbiVolume
331 (
332  le_msg_SessionRef_t _ifgen_sessionRef,
333  le_flash_PartitionRef_t partitionRef,
334  ///< [IN] Partition reference.
335  const char* LE_NONNULL volumeName,
336  ///< [IN] Volume name to be used.
337  int32_t volumeSize
338  ///< [IN] Volume size to set if open for writing
339 );
340 
341 //--------------------------------------------------------------------------------------------------
342 /**
343  * Close the used UBI volume of an UBI image.
344  *
345  * @return
346  * - LE_OK On success
347  * - LE_BAD_PARAMETER If a parameter is invalid
348  * - LE_FAULT On failure
349  *
350  */
351 //--------------------------------------------------------------------------------------------------
352 LE_SHARED le_result_t ifgen_le_flash_CloseUbiVolume
353 (
354  le_msg_SessionRef_t _ifgen_sessionRef,
355  le_flash_PartitionRef_t partitionRef
356  ///< [IN] Partition reference.
357 );
358 
359 //--------------------------------------------------------------------------------------------------
360 /**
361  * Close a flash partition
362  *
363  * @return
364  * - LE_OK On success
365  * - LE_BAD_PARAMETER If a parameter is invalid
366  */
367 //--------------------------------------------------------------------------------------------------
368 LE_SHARED le_result_t ifgen_le_flash_Close
369 (
370  le_msg_SessionRef_t _ifgen_sessionRef,
371  le_flash_PartitionRef_t partitionRef
372  ///< [IN] Partition reference to be closed.
373 );
374 
375 //--------------------------------------------------------------------------------------------------
376 /**
377  * Erase a block inside a flash partition. If the erase fails, the block is marked bad.
378  *
379  * @return
380  * - LE_OK On success
381  * - LE_BAD_PARAMETER If a parameter is invalid
382  * - LE_FAULT On other error
383  */
384 //--------------------------------------------------------------------------------------------------
385 LE_SHARED le_result_t ifgen_le_flash_EraseBlock
386 (
387  le_msg_SessionRef_t _ifgen_sessionRef,
388  le_flash_PartitionRef_t partitionRef,
389  ///< [IN] Partition reference to be closed.
390  uint32_t blockIndex
391  ///< [IN] Logical block index to be erased.
392 );
393 
394 //--------------------------------------------------------------------------------------------------
395 /**
396  * Read data from a flash partition. The read data are:
397  * - at the logical block index given by blockIndex.
398  * - the maximum read data length is:
399  * - an erase block size for MTD usage partition
400  * - an erase block size minus 2 pages for UBI partitions
401  *
402  * @return
403  * - LE_OK On success
404  * - LE_BAD_PARAMETER If a parameter is invalid
405  * - LE_FAULT On other error
406  */
407 //--------------------------------------------------------------------------------------------------
408 LE_SHARED le_result_t ifgen_le_flash_Read
409 (
410  le_msg_SessionRef_t _ifgen_sessionRef,
411  le_flash_PartitionRef_t partitionRef,
412  ///< [IN] Partition reference to be used.
413  uint32_t blockIndex,
414  ///< [IN] Logical block index to be read.
415  uint8_t* readDataPtr,
416  ///< [OUT] Data buffer to copy the read data.
417  size_t* readDataSizePtr
418  ///< [INOUT]
419 );
420 
421 //--------------------------------------------------------------------------------------------------
422 /**
423  * Write data to a flash partition.
424  * - the block is firstly erased, so no call to le_flash_EraseBlock() is needed.
425  * - if the erase or the write reports an error, the block is marked "bad" and the write starts
426  * again at the next physical block.
427  * - the data are programmed at the logical block index given by blockIndex.
428  * - the maximum written data length is:
429  * - an erase block size for MTD usage partition. This is the eraseBlockSize returned by
430  * le_flash_GetInformation().
431  * - an erase block size minus 2 pages for UBI partitions. These are the eraseBlockSize and
432  * pageSize returned by le_flash_GetInformation().
433  * If the write addresses an UBI volume and more PEBs are required to write the new data, new PEBs
434  * will be added into this volume.
435  *
436  * @note
437  * The addressed block is automatically erased before to be written.
438  *
439  * @return
440  * - LE_OK On success
441  * - LE_BAD_PARAMETER If a parameter is invalid
442  * - LE_FAULT On other error
443  */
444 //--------------------------------------------------------------------------------------------------
445 LE_SHARED le_result_t ifgen_le_flash_Write
446 (
447  le_msg_SessionRef_t _ifgen_sessionRef,
448  le_flash_PartitionRef_t partitionRef,
449  ///< [IN] Partition reference to be used.
450  uint32_t blockIndex,
451  ///< [IN] Logical block index to be write.
452  const uint8_t* writeDataPtr,
453  ///< [IN] Data buffer to be written.
454  size_t writeDataSize
455  ///< [IN]
456 );
457 
458 //--------------------------------------------------------------------------------------------------
459 /**
460  * Retrieve information about the partition opened: the number of bad blocks found inside the
461  * partition, the number of erase blocks, the size of the erase block and the size of the page.
462  *
463  * @return
464  * - LE_OK On success
465  * - LE_BAD_PARAMETER If a parameter is invalid
466  * - LE_FAULT On other error
467  */
468 //--------------------------------------------------------------------------------------------------
469 LE_SHARED le_result_t ifgen_le_flash_GetBlockInformation
470 (
471  le_msg_SessionRef_t _ifgen_sessionRef,
472  le_flash_PartitionRef_t partitionRef,
473  ///< [IN] Partition reference to be used.
474  uint32_t* badBlocksNumberPtr,
475  ///< [OUT] Bad blocks number inside the partition
476  uint32_t* eraseBlocksNumberPtr,
477  ///< [OUT] Erase blocks number
478  uint32_t* eraseBlockSizePtr,
479  ///< [OUT] Erase block size
480  uint32_t* pageSizePtr
481  ///< [OUT] Page size
482 );
483 
484 //--------------------------------------------------------------------------------------------------
485 /**
486  * Retrieve information about the UBI volume opened: the number of free blocks for the UBI,
487  * the number of currently allocated blocks to the volume and its real size in bytes.
488  *
489  * @return
490  * - LE_OK On success
491  * - LE_BAD_PARAMETER If a parameter is invalid
492  * - LE_FAULT On other error
493  */
494 //--------------------------------------------------------------------------------------------------
495 LE_SHARED le_result_t ifgen_le_flash_GetUbiVolumeInformation
496 (
497  le_msg_SessionRef_t _ifgen_sessionRef,
498  le_flash_PartitionRef_t partitionRef,
499  ///< [IN] Partition reference to be used.
500  uint32_t* freeBlockNumberPtr,
501  ///< [OUT] Free blocks number on the UBI partition
502  uint32_t* allocatedBlockNumberPtr,
503  ///< [OUT] Allocated blocks number to the UBI volume
504  uint32_t* sizeInBytesPtr
505  ///< [OUT] Real size in bytes of the UBI volume
506 );
507 
508 //--------------------------------------------------------------------------------------------------
509 /**
510  * Create an UBI partition.
511  * If the partition is already an UBI, an error is raised except if the flag isForcedCreate is set
512  * to true. In this case, the whole UBI partition is recreated and the previous content is lost.
513  * If the operation succeed, the partition is opened in write-only and this is not necessary to
514  * call le_flash_OpenUbi().
515  *
516  * @return
517  * - LE_OK On success
518  * - LE_BAD_PARAMETER If a parameter is invalid
519  * - LE_NOT_FOUND If the flash partition is not found
520  * - LE_DUPLICATE If the partition is already an UBI partition and isForcedCreate is not
521  * set to true
522  * - LE_FAULT On failure
523  *
524  */
525 //--------------------------------------------------------------------------------------------------
526 LE_SHARED le_result_t ifgen_le_flash_CreateUbi
527 (
528  le_msg_SessionRef_t _ifgen_sessionRef,
529  const char* LE_NONNULL partitionName,
530  ///< [IN] Partition to be opened.
531  bool isForcedCreate,
532  ///< [IN] Force the UBI recreation and
533  ///< overwrite the previous content.
534  le_flash_PartitionRef_t* partitionRefPtr
535  ///< [OUT] Partition reference.
536 );
537 
538 //--------------------------------------------------------------------------------------------------
539 /**
540  * Create a new UBI volume into an UBI partition.
541  * If the volume name or the volume ID already exists, an error is raised except if the flag
542  * isForcedCreate is set to true. In this case, the whole UBI volume is recreated and the previous
543  * content is lost. If the operation succeed, UBI volume is opened and this is not necessary to
544  * call le_flash_OpenUbiVolume().
545  * Note that the UBI partition should be opened in write-only or read-write mode, else an error is
546  * raised.
547  * The volumeName is the same parameter as le_flash_OpenUbiVolume().
548  * A static volume cannot be extended when mounted, so it is generally used for SQUASHFS or others
549  * immutables and R/O filesystems. A dynamic volume is extensible like UBIFS volumes.
550  * The volume ID is the number of the UBI volume to be created. If set to NO_UBI_VOLUME_ID, the
551  * first free volume ID will be used.
552  *
553  * @return
554  * - LE_OK On success
555  * - LE_BAD_PARAMETER If a parameter is invalid
556  * - LE_NOT_PERMITTED If the UBI partition is not opened in write-only or read-write mode
557  * - LE_DUPLICATE If the UBI volume already exists with a same name or a same volume ID
558  * and isForcedCreate is not set to true
559  * - LE_FAULT On failure
560  *
561  */
562 //--------------------------------------------------------------------------------------------------
563 LE_SHARED le_result_t ifgen_le_flash_CreateUbiVolume
564 (
565  le_msg_SessionRef_t _ifgen_sessionRef,
566  le_flash_PartitionRef_t partitionRef,
567  ///< [IN] Partition reference.
568  bool isForcedCreate,
569  ///< [IN] Force the UBI volume recreation and
570  ///< overwrite the previous content.
571  uint32_t volumeID,
572  ///< [IN] Volume ID to set.
573  le_flash_UbiVolumeType_t volumeType,
574  ///< [IN] Volume type to set.
575  const char* LE_NONNULL volumeName,
576  ///< [IN] Volume name to be created.
577  int32_t volumeSize
578  ///< [IN] Volume size to set.
579 );
580 
581 //--------------------------------------------------------------------------------------------------
582 /**
583  * Delete an UBI volume from an UBI partition.
584  * If the volume is currently opened by le_flash_OpenUbiVolume(), it is closed first.
585  * Note that the UBI partition should be opened in write-only or read-write mode, else an error is
586  * raised.
587  *
588  * @return
589  * - LE_OK On success
590  * - LE_BAD_PARAMETER If a parameter is invalid
591  * - LE_NOT_PERMITTED If the UBI partition is not open in write-only or read-write mode
592  * - LE_NOT_FOUND If the volume name is not found
593  * - LE_FAULT On failure
594  *
595  */
596 //--------------------------------------------------------------------------------------------------
597 LE_SHARED le_result_t ifgen_le_flash_DeleteUbiVolume
598 (
599  le_msg_SessionRef_t _ifgen_sessionRef,
600  le_flash_PartitionRef_t partitionRef,
601  ///< [IN] Partition reference.
602  const char* LE_NONNULL volumeName
603  ///< [IN] Volume name to be deleted.
604 );
605 /** @} **/
606 #endif // LE_FLASH_COMMON_H_INCLUDE_GUARD
le_flash_OpenMode_t
Definition: le_flash_common.h:114
#define LE_SHARED
Definition: le_basics.h:287
le_result_t
Definition: le_basics.h:46
struct le_flash_Partition * le_flash_PartitionRef_t
Definition: le_flash_common.h:146
le_flash_UbiVolumeType_t
Definition: le_flash_common.h:131
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
struct le_flash_BadImageDetectionHandler * le_flash_BadImageDetectionHandlerRef_t
Definition: le_flash_common.h:154
void(* le_flash_BadImageDetectionHandlerFunc_t)(const char *LE_NONNULL imageName, void *contextPtr)
Definition: le_flash_common.h:165