le_flash_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_flash Flash API
14  *
15  * @ref le_flash_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * This file contains data structures and prototypes definitions for high level Flash APIs.
20  *
21  * The goal is to provide an API to update an image recorded:
22  * - in a flash partition in RAW mode at the block layer, using a Memory Technology Device (MTD).
23  * - in an Unsorted Block Images (UBI) volume, using a MTD and updating UBI information and headers.
24  *
25  *
26  * @section le_flash_binding IPC interfaces binding
27  *
28  * All the functions of this API are provided by the @b fwupdateService.
29  *
30  * Here's a code sample binding to the flash service:
31  * @verbatim
32  bindings:
33  {
34  clientExe.clientComponent.le_flash -> fwupdateService.le_flash
35  }
36  @endverbatim
37  *
38  * @warning These APIs are not available for all platforms. Please refer to the Product Technical
39  * Specification document of your platform for further details.
40  * Please refer to @subpage platformConstraintsFlash for details.
41  *
42  * @section le_flash_BadImageDetection Bad image detection
43  *
44  * This functionality allows the user to be notified when an image becomes bad.
45  *
46  * - le_flash_AddBadImageDetectionHandler() API adds a handler to notify when an image becomes bad
47  * - le_flash_RemoveBadImageDetectionHandler() API removes the bad image handler
48  *
49  * @section flash_Protection Flash access protection
50  * To address race conditions, le_flash_RequestAccess() has to be called first before trying to
51  * access to the flash. When all flash modifications are done, le_flash_ReleaseAccess() is required.
52  *
53  * @section le_flash_Open Open a partition
54  * Depending on how the read/write operations have to be done, the correct open API has to be used:
55  * - le_flash_OpenMtd() when the flash image is reachable at the block layer.
56  * - le_flash_OpenUbi() when the image is reachable through a UBI. Then le_flash_OpenUbiVolume()
57  * needs to be called to set the volume to be accessed. Volume can be set several time
58  * successively. le_flash_CloseUbiVolume() has to be called before changing the volume.
59  * Please refer to @subpage platformConstraintsFlash for details.
60  *
61  * A sample code showing how to open, retrieve information and close can be seen below:
62  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" Info
63  *
64  * A sample code showing how to open UBI, retrieve UBI information and close UBI can be seen below:
65  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiInfo
66  *
67  * @section le_flash_Close Close a partition
68  * When the read/write operation are over, the application has to call le_flash_Close() API to
69  * release resources and make the partition usable.
70  *
71  * @section le_flash_EraseBlock Erase a block inside a partition
72  * When a block needs to be erased; the application has to call le_flash_EraseBlock() API to perform
73  * the erase operation on the given block index. If the erase fails, the block is marked "bad".
74  *
75  * @section le_flash_Read Read a data chunk
76  * To read data, le_flash_Read() has to be called. The data are read at the specified block index.
77  * Note that this index is not the index of the block into the partition, but a logical block index:
78  * - the bad blocks are skipped.
79  * - the blocks are not into a consecutive order for UBI volume.
80  *
81  * The data length to be read can't be higher than:
82  * - an erase block size for MTD usage partition
83  * - an erase block size minus 2 pages for UBI partitions (UBI uses 2 pages for its internal
84  * need)
85  *
86  * A sample code showing how to read a whole partition can be seen below:
87  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" Dump
88  *
89  * A sample code showing how to read a whole UBI volume inside an UBI partition can be seen below:
90  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiDump
91  *
92  * @section le_flash_Write Write a data chunk
93  * To write some data, le_flash_Write() can be used. The data are written at a specified block
94  * index. This index is a logical block index (see @ref le_flash_Read).
95  * The block is firstly erased, so no call to le_flash_EraseBlock() is needed.
96  * If the erase or the write reports an error, the block is marked "bad" and the write starts
97  * again at the next physical block.
98  * The data length to be written can't be higher than:
99  * - an erase block size for MTD usage partition
100  * - an erase block size minus 2 pages for UBI partitions (UBI uses 2 pages for its internal
101  * need)
102  *
103  * A sample code showing how to write a whole partition can be seen below:
104  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" FlashErase
105  *
106  * A sample code showing how to write a whole UBI volume inside an UBI partition can be seen below:
107  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiFlash
108  *
109  * @section le_flash_GetBlockInformation Retrieve information about blocks and pages for a
110  * partition.
111  * To get information about blocks and pages, call le_flash_GetBlockInformation(). The API
112  * will return:
113  * - The number of bad blocks belonging to this partition
114  * - The number of erase blocks belonging to this partition
115  * - The erase block size
116  * - The page size
117  * The whole partition size in bytes can be computed by:
118  * number of erase blocks * erase block size
119  * The whole partition available size for read and write purpose can be computed by:
120  * (number of erase blocks - number of bad blocks) * erase block size
121  *
122  * A sample code showing how to open, retrieve information and close a partition can be seen below:
123  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" Info
124  *
125  * @section le_flash_GetUbiVolumeInformation Retrieve UBI information.
126  * To get information about an UBI volume, call le_flash_GetUbiVolumeInformation(). The API
127  * will return:
128  * - The number of free blocks in the whole UBI partition
129  * - The currently number of blocks allocated to the UBI volume
130  * - The real size of the UBI volume
131  * This API must be called after the UBI volume has been open by le_flash_OpenUbiVolume().
132  *
133  * A sample code showing how to open UBI, retrieve UBI information and close UBI can be seen below:
134  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiInfo
135  *
136  * @section le_flash_CreateUbi Create an UBI partition and volume
137  * le_flash_CreateUbi() is used to create an UBI partition. If the partition is already an UBI,
138  * an error LE_DUPLICATE will be reported. The overwrite of the partition can be forced by setting
139  * the flag isForcedCreate to true (all previous content will be lost).
140  *
141  * When the creation succeeded, the UBI device is opened using le_flash_OpenUbi() with
142  * LE_FLASH_READWRITE mode.
143  *
144  * To create a new volume in the created UBI partition, le_flash_CreateUbiVolume() has to be
145  * called. If a volume already exists with the same name or same ID, an error LE_DUPLICATE will
146  * be reported. The flag isForcedCreate permits to re-create the volume, but the previous content
147  * of the volume will be lost.
148  *
149  * The created volume can be opened using the le_flash_OpenUbiVolume() API.
150  *
151  * An existing volume can be deleted thanks to le_flash_DeleteUbiVolume().
152  *
153  * Please refer to @subpage platformConstraintsFlash for details.
154  *
155  * A sample code showing how to create an UBI partition can be seen below:
156  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiCreate
157  *
158  * A sample code showing how to create an UBI volume inside an UBI partition can be seen below:
159  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiCreateVol
160  *
161  * A sample code showing how to delete an UBI volume from an UBI partition can be seen below:
162  * @snippet "apps/test/fwupdate/fwupdateIntegrationTest/flashApiTest/main.c" UbiDeleteVol
163  *
164  * This API is synchronous: it is blocking until the write is over. After the end of the write, the
165  * data are read to ensure the data has been saved correctly.
166  *
167  * <HR>
168  *
169  * Copyright (C) Sierra Wireless Inc.
170  */
171 /**
172  * @file le_flash_interface.h
173  *
174  * Legato @ref c_flash include file.
175  *
176  * Copyright (C) Sierra Wireless Inc.
177  */
178 
179 #ifndef LE_FLASH_INTERFACE_H_INCLUDE_GUARD
180 #define LE_FLASH_INTERFACE_H_INCLUDE_GUARD
181 
182 
183 #include "legato.h"
184 
185 
186 //--------------------------------------------------------------------------------------------------
187 /**
188  * Type for handler called when a server disconnects.
189  */
190 //--------------------------------------------------------------------------------------------------
191 typedef void (*le_flash_DisconnectHandler_t)(void *);
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  *
196  * Connect the current client thread to the service providing this API. Block until the service is
197  * available.
198  *
199  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
200  * called before any other functions in this API. Normally, ConnectService is automatically called
201  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
202  *
203  * This function is created automatically.
204  */
205 //--------------------------------------------------------------------------------------------------
207 (
208  void
209 );
210 
211 //--------------------------------------------------------------------------------------------------
212 /**
213  *
214  * Try to connect the current client thread to the service providing this API. Return with an error
215  * if the service is not available.
216  *
217  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
218  * called before any other functions in this API. Normally, ConnectService is automatically called
219  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
220  *
221  * This function is created automatically.
222  *
223  * @return
224  * - LE_OK if the client connected successfully to the service.
225  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
226  * bound.
227  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
228  * - LE_COMM_ERROR if the Service Directory cannot be reached.
229  */
230 //--------------------------------------------------------------------------------------------------
232 (
233  void
234 );
235 
236 //--------------------------------------------------------------------------------------------------
237 /**
238  * Set handler called when server disconnection is detected.
239  *
240  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
241  * to continue without exiting, it should call longjmp() from inside the handler.
242  */
243 //--------------------------------------------------------------------------------------------------
245 (
246  le_flash_DisconnectHandler_t disconnectHandler,
247  void *contextPtr
248 );
249 
250 //--------------------------------------------------------------------------------------------------
251 /**
252  *
253  * Disconnect the current client thread from the service providing this API.
254  *
255  * Normally, this function doesn't need to be called. After this function is called, there's no
256  * longer a connection to the service, and the functions in this API can't be used. For details, see
257  * @ref apiFilesC_client.
258  *
259  * This function is created automatically.
260  */
261 //--------------------------------------------------------------------------------------------------
263 (
264  void
265 );
266 
267 
268 //--------------------------------------------------------------------------------------------------
269 /**
270  * Image length maximum length.
271  *
272  */
273 //--------------------------------------------------------------------------------------------------
274 #define LE_FLASH_IMAGE_NAME_MAX_LEN 32
275 
276 //--------------------------------------------------------------------------------------------------
277 /**
278  * Image length maximum length.
279  * One extra byte is added for the null character.
280  */
281 //--------------------------------------------------------------------------------------------------
282 #define LE_FLASH_IMAGE_NAME_MAX_BYTES 33
283 
284 //--------------------------------------------------------------------------------------------------
285 /**
286  * Maximum partition name length
287  */
288 //--------------------------------------------------------------------------------------------------
289 #define LE_FLASH_PARTITION_NAME_MAX_LEN 50
290 
291 //--------------------------------------------------------------------------------------------------
292 /**
293  * Maximum partition name length
294  * One extra byte is added for the null character.
295  */
296 //--------------------------------------------------------------------------------------------------
297 #define LE_FLASH_PARTITION_NAME_MAX_BYTES 51
298 
299 //--------------------------------------------------------------------------------------------------
300 /**
301  * Maximum volume name length
302  */
303 //--------------------------------------------------------------------------------------------------
304 #define LE_FLASH_VOLUME_NAME_MAX_LEN 50
305 
306 //--------------------------------------------------------------------------------------------------
307 /**
308  * Maximum volume name length
309  * One extra byte is added for the null character.
310  */
311 //--------------------------------------------------------------------------------------------------
312 #define LE_FLASH_VOLUME_NAME_MAX_BYTES 51
313 
314 //--------------------------------------------------------------------------------------------------
315 /**
316  * Max byte storage size for write buffer
317  */
318 //--------------------------------------------------------------------------------------------------
319 #define LE_FLASH_MAX_WRITE_SIZE 262144
320 
321 //--------------------------------------------------------------------------------------------------
322 /**
323  * Max byte storage size for read buffer
324  */
325 //--------------------------------------------------------------------------------------------------
326 #define LE_FLASH_MAX_READ_SIZE 262144
327 
328 //--------------------------------------------------------------------------------------------------
329 /**
330  * Default volume size to keep the current volume size untouched
331  */
332 //--------------------------------------------------------------------------------------------------
333 #define LE_FLASH_UBI_VOL_NO_SIZE -1
334 
335 //--------------------------------------------------------------------------------------------------
336 /**
337  * Default volume ID to specify the automatic allocation of volume ID
338  */
339 //--------------------------------------------------------------------------------------------------
340 #define LE_FLASH_UBI_VOL_NO_ID -1
341 
342 //--------------------------------------------------------------------------------------------------
343 /**
344  * Maximum volume ID
345  */
346 //--------------------------------------------------------------------------------------------------
347 #define LE_FLASH_UBI_VOL_ID_MAX 127
348 
349 //--------------------------------------------------------------------------------------------------
350 /**
351  * Open mode.
352  */
353 //--------------------------------------------------------------------------------------------------
354 typedef enum
355 {
356  LE_FLASH_READ_ONLY = 0,
357  ///<
358  LE_FLASH_WRITE_ONLY = 1,
359  ///<
360  LE_FLASH_READ_WRITE = 2
361  ///<
362 }
364 
365 
366 //--------------------------------------------------------------------------------------------------
367 /**
368  * UBI volume type mode.
369  */
370 //--------------------------------------------------------------------------------------------------
371 typedef enum
372 {
373  LE_FLASH_DYNAMIC = 0,
374  ///<
375  LE_FLASH_STATIC = 1
376  ///<
377 }
379 
380 
381 //--------------------------------------------------------------------------------------------------
382 /**
383  * Declare a reference type for referring a partition.
384  */
385 //--------------------------------------------------------------------------------------------------
386 typedef struct le_flash_Partition* le_flash_PartitionRef_t;
387 
388 
389 //--------------------------------------------------------------------------------------------------
390 /**
391  * Reference type used by Add/Remove functions for EVENT 'le_flash_BadImageDetection'
392  */
393 //--------------------------------------------------------------------------------------------------
394 typedef struct le_flash_BadImageDetectionHandler* le_flash_BadImageDetectionHandlerRef_t;
395 
396 
397 //--------------------------------------------------------------------------------------------------
398 /**
399  * Handler for bad image detection.
400  *
401  * @note The image names are platform dependent.
402  */
403 //--------------------------------------------------------------------------------------------------
405 (
406  const char* LE_NONNULL imageName,
407  ///< bad image name
408  void* contextPtr
409  ///<
410 );
411 
412 //--------------------------------------------------------------------------------------------------
413 /**
414  * Add handler function for EVENT 'le_flash_BadImageDetection'
415  *
416  * This event provides information on bad image status.
417  *
418  */
419 //--------------------------------------------------------------------------------------------------
421 (
423  ///< [IN]
424  void* contextPtr
425  ///< [IN]
426 );
427 
428 //--------------------------------------------------------------------------------------------------
429 /**
430  * Remove handler function for EVENT 'le_flash_BadImageDetection'
431  */
432 //--------------------------------------------------------------------------------------------------
434 (
436  ///< [IN]
437 );
438 
439 //--------------------------------------------------------------------------------------------------
440 /**
441  * Request the flash access authorization. This is required to avoid race operations.
442  *
443  * @return
444  * - LE_OK On success
445  * - LE_UNAVAILABLE The flash access is temporarily unavailable
446  * - LE_DUPLICATE If the a request access for the client was already performed
447  * - LE_FAULT On failure
448  *
449  */
450 //--------------------------------------------------------------------------------------------------
452 (
453  void
454 );
455 
456 //--------------------------------------------------------------------------------------------------
457 /**
458  * Release the flash access requested by le_flash_RequestAccess API.
459  *
460  * @return
461  * - LE_OK On success
462  * - LE_FAULT On failure
463  *
464  */
465 //--------------------------------------------------------------------------------------------------
467 (
468  void
469 );
470 
471 //--------------------------------------------------------------------------------------------------
472 /**
473  * Open a flash partition at the block layer for the given operation and return a descriptor.
474  * The read and write operation will be done using MTD.
475  *
476  * @return
477  * - LE_OK On success
478  * - LE_BAD_PARAMETER If a parameter is invalid
479  * - LE_NOT_FOUND If the flash partition is not found
480  * - LE_FAULT On failure
481  *
482  */
483 //--------------------------------------------------------------------------------------------------
485 (
486  const char* LE_NONNULL partitionName,
487  ///< [IN] Partition to be opened.
488  le_flash_OpenMode_t mode,
489  ///< [IN] Opening mode.
490  le_flash_PartitionRef_t* partitionRefPtr
491  ///< [OUT] Partition reference.
492 );
493 
494 //--------------------------------------------------------------------------------------------------
495 /**
496  * Open a UBI volume for the given operation and return a descriptor. The read and write
497  * operation will be done using MTD, UBI metadata will be updated.
498  *
499  * @return
500  * - LE_OK On success
501  * - LE_BAD_PARAMETER If a parameter is invalid
502  * - LE_NOT_FOUND If the flash partition is not found
503  * - LE_FAULT On failure
504  *
505  */
506 //--------------------------------------------------------------------------------------------------
508 (
509  const char* LE_NONNULL partitionName,
510  ///< [IN] Partition to be opened.
511  le_flash_OpenMode_t mode,
512  ///< [IN] Opening mode.
513  le_flash_PartitionRef_t* partitionRefPtr
514  ///< [OUT] Partition reference.
515 );
516 
517 //--------------------------------------------------------------------------------------------------
518 /**
519  * Open the UBI volume of an UBI image to be used for the read and write operations. When open for
520  * writing and a volumeSize is given, the UBI volume will be adjusted to this size by freeing the
521  * PEBs over this size. If the data inside the volume require more PEBs, they will be added
522  * by the le_flash_Write() API.
523  *
524  * @return
525  * - LE_OK On success
526  * - LE_BAD_PARAMETER If a parameter is invalid
527  * - LE_NOT_FOUND If the volume name is not found
528  * - LE_FAULT On failure
529  *
530  */
531 //--------------------------------------------------------------------------------------------------
533 (
534  le_flash_PartitionRef_t partitionRef,
535  ///< [IN] Partition reference.
536  const char* LE_NONNULL volumeName,
537  ///< [IN] Volume name to be used.
538  int32_t volumeSize
539  ///< [IN] Volume size to set if open for writing
540 );
541 
542 //--------------------------------------------------------------------------------------------------
543 /**
544  * Close the used UBI volume of an UBI image.
545  *
546  * @return
547  * - LE_OK On success
548  * - LE_BAD_PARAMETER If a parameter is invalid
549  * - LE_FAULT On failure
550  *
551  */
552 //--------------------------------------------------------------------------------------------------
554 (
555  le_flash_PartitionRef_t partitionRef
556  ///< [IN] Partition reference.
557 );
558 
559 //--------------------------------------------------------------------------------------------------
560 /**
561  * Close a flash partition
562  *
563  * @return
564  * - LE_OK On success
565  * - LE_BAD_PARAMETER If a parameter is invalid
566  */
567 //--------------------------------------------------------------------------------------------------
569 (
570  le_flash_PartitionRef_t partitionRef
571  ///< [IN] Partition reference to be closed.
572 );
573 
574 //--------------------------------------------------------------------------------------------------
575 /**
576  * Erase a block inside a flash partition. If the erase fails, the block is marked bad.
577  *
578  * @return
579  * - LE_OK On success
580  * - LE_BAD_PARAMETER If a parameter is invalid
581  * - LE_FAULT On other error
582  */
583 //--------------------------------------------------------------------------------------------------
585 (
586  le_flash_PartitionRef_t partitionRef,
587  ///< [IN] Partition reference to be closed.
588  uint32_t blockIndex
589  ///< [IN] Logical block index to be erased.
590 );
591 
592 //--------------------------------------------------------------------------------------------------
593 /**
594  * Read data from a flash partition. The read data are:
595  * - at the logical block index given by blockIndex.
596  * - the maximum read data length is:
597  * - an erase block size for MTD usage partition
598  * - an erase block size minus 2 pages for UBI partitions
599  *
600  * @return
601  * - LE_OK On success
602  * - LE_BAD_PARAMETER If a parameter is invalid
603  * - LE_FAULT On other error
604  */
605 //--------------------------------------------------------------------------------------------------
607 (
608  le_flash_PartitionRef_t partitionRef,
609  ///< [IN] Partition reference to be used.
610  uint32_t blockIndex,
611  ///< [IN] Logical block index to be read.
612  uint8_t* readDataPtr,
613  ///< [OUT] Data buffer to copy the read data.
614  size_t* readDataSizePtr
615  ///< [INOUT]
616 );
617 
618 //--------------------------------------------------------------------------------------------------
619 /**
620  * Write data to a flash partition.
621  * - the block is firstly erased, so no call to le_flash_EraseBlock() is needed.
622  * - if the erase or the write reports an error, the block is marked "bad" and the write starts
623  * again at the next physical block.
624  * - the data are programmed at the logical block index given by blockIndex.
625  * - the maximum written data length is:
626  * - an erase block size for MTD usage partition. This is the eraseBlockSize returned by
627  * le_flash_GetInformation().
628  * - an erase block size minus 2 pages for UBI partitions. These are the eraseBlockSize and
629  * pageSize returned by le_flash_GetInformation().
630  * If the write addresses an UBI volume and more PEBs are required to write the new data, new PEBs
631  * will be added into this volume.
632  *
633  * @note
634  * The addressed block is automatically erased before to be written.
635  *
636  * @return
637  * - LE_OK On success
638  * - LE_BAD_PARAMETER If a parameter is invalid
639  * - LE_FAULT On other error
640  */
641 //--------------------------------------------------------------------------------------------------
643 (
644  le_flash_PartitionRef_t partitionRef,
645  ///< [IN] Partition reference to be used.
646  uint32_t blockIndex,
647  ///< [IN] Logical block index to be write.
648  const uint8_t* writeDataPtr,
649  ///< [IN] Data buffer to be written.
650  size_t writeDataSize
651  ///< [IN]
652 );
653 
654 //--------------------------------------------------------------------------------------------------
655 /**
656  * Retrieve information about the partition opened: the number of bad blocks found inside the
657  * partition, the number of erase blocks, the size of the erase block and the size of the page.
658  *
659  * @return
660  * - LE_OK On success
661  * - LE_BAD_PARAMETER If a parameter is invalid
662  * - LE_FAULT On other error
663  */
664 //--------------------------------------------------------------------------------------------------
666 (
667  le_flash_PartitionRef_t partitionRef,
668  ///< [IN] Partition reference to be used.
669  uint32_t* badBlocksNumberPtr,
670  ///< [OUT] Bad blocks number inside the partition
671  uint32_t* eraseBlocksNumberPtr,
672  ///< [OUT] Erase blocks number
673  uint32_t* eraseBlockSizePtr,
674  ///< [OUT] Erase block size
675  uint32_t* pageSizePtr
676  ///< [OUT] Page size
677 );
678 
679 //--------------------------------------------------------------------------------------------------
680 /**
681  * Retrieve information about the UBI volume opened: the number of free blocks for the UBI,
682  * the number of currently allocated blocks to the volume and its real size in bytes.
683  *
684  * @return
685  * - LE_OK On success
686  * - LE_BAD_PARAMETER If a parameter is invalid
687  * - LE_FAULT On other error
688  */
689 //--------------------------------------------------------------------------------------------------
691 (
692  le_flash_PartitionRef_t partitionRef,
693  ///< [IN] Partition reference to be used.
694  uint32_t* freeBlockNumberPtr,
695  ///< [OUT] Free blocks number on the UBI partition
696  uint32_t* allocatedBlockNumberPtr,
697  ///< [OUT] Allocated blocks number to the UBI volume
698  uint32_t* sizeInBytesPtr
699  ///< [OUT] Real size in bytes of the UBI volume
700 );
701 
702 //--------------------------------------------------------------------------------------------------
703 /**
704  * Create an UBI partition.
705  * If the partition is already an UBI, an error is raised except if the flag isForcedCreate is set
706  * to true. In this case, the whole UBI partition is recreated and the previous content is lost.
707  * If the operation succeed, the partition is opened in write-only and this is not necessary to
708  * call le_flash_OpenUbi().
709  *
710  * @return
711  * - LE_OK On success
712  * - LE_BAD_PARAMETER If a parameter is invalid
713  * - LE_NOT_FOUND If the flash partition is not found
714  * - LE_DUPLICATE If the partition is already an UBI partition and isForcedCreate is not
715  * set to true
716  * - LE_FAULT On failure
717  *
718  */
719 //--------------------------------------------------------------------------------------------------
721 (
722  const char* LE_NONNULL partitionName,
723  ///< [IN] Partition to be opened.
724  bool isForcedCreate,
725  ///< [IN] Force the UBI recreation and
726  ///< overwrite the previous content.
727  le_flash_PartitionRef_t* partitionRefPtr
728  ///< [OUT] Partition reference.
729 );
730 
731 //--------------------------------------------------------------------------------------------------
732 /**
733  * Create a new UBI volume into an UBI partition.
734  * If the volume name or the volume ID already exists, an error is raised except if the flag
735  * isForcedCreate is set to true. In this case, the whole UBI volume is recreated and the previous
736  * content is lost. If the operation succeed, UBI volume is opened and this is not necessary to
737  * call le_flash_OpenUbiVolume().
738  * Note that the UBI partition should be opened in write-only or read-write mode, else an error is
739  * raised.
740  * The volumeName is the same parameter as le_flash_OpenUbiVolume().
741  * A static volume cannot be extended when mounted, so it is generally used for SQUASHFS or others
742  * immutables and R/O filesystems. A dynamic volume is extensible like UBIFS volumes.
743  * The volume ID is the number of the UBI volume to be created. If set to NO_UBI_VOLUME_ID, the
744  * first free volume ID will be used.
745  *
746  * @return
747  * - LE_OK On success
748  * - LE_BAD_PARAMETER If a parameter is invalid
749  * - LE_NOT_PERMITTED If the UBI partition is not opened in write-only or read-write mode
750  * - LE_DUPLICATE If the UBI volume already exists with a same name or a same volume ID
751  * and isForcedCreate is not set to true
752  * - LE_FAULT On failure
753  *
754  */
755 //--------------------------------------------------------------------------------------------------
757 (
758  le_flash_PartitionRef_t partitionRef,
759  ///< [IN] Partition reference.
760  bool isForcedCreate,
761  ///< [IN] Force the UBI volume recreation and
762  ///< overwrite the previous content.
763  uint32_t volumeID,
764  ///< [IN] Volume ID to set.
765  le_flash_UbiVolumeType_t volumeType,
766  ///< [IN] Volume type to set.
767  const char* LE_NONNULL volumeName,
768  ///< [IN] Volume name to be created.
769  int32_t volumeSize
770  ///< [IN] Volume size to set.
771 );
772 
773 //--------------------------------------------------------------------------------------------------
774 /**
775  * Delete an UBI volume from an UBI partition.
776  * If the volume is currently opened by le_flash_OpenUbiVolume(), it is closed first.
777  * Note that the UBI partition should be opened in write-only or read-write mode, else an error is
778  * raised.
779  *
780  * @return
781  * - LE_OK On success
782  * - LE_BAD_PARAMETER If a parameter is invalid
783  * - LE_NOT_PERMITTED If the UBI partition is not open in write-only or read-write mode
784  * - LE_NOT_FOUND If the volume name is not found
785  * - LE_FAULT On failure
786  *
787  */
788 //--------------------------------------------------------------------------------------------------
790 (
791  le_flash_PartitionRef_t partitionRef,
792  ///< [IN] Partition reference.
793  const char* LE_NONNULL volumeName
794  ///< [IN] Volume name to be deleted.
795 );
796 
797 #endif // LE_FLASH_INTERFACE_H_INCLUDE_GUARD
le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler(le_flash_BadImageDetectionHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_flash_EraseBlock(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex)
le_result_t le_flash_GetBlockInformation(le_flash_PartitionRef_t partitionRef, uint32_t *badBlocksNumberPtr, uint32_t *eraseBlocksNumberPtr, uint32_t *eraseBlockSizePtr, uint32_t *pageSizePtr)
le_result_t
Definition: le_basics.h:35
le_result_t le_flash_RequestAccess(void)
void(* le_flash_BadImageDetectionHandlerFunc_t)(const char *LE_NONNULL imageName, void *contextPtr)
Definition: le_flash_interface.h:405
le_result_t le_flash_CloseUbiVolume(le_flash_PartitionRef_t partitionRef)
le_result_t le_flash_Write(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex, const uint8_t *writeDataPtr, size_t writeDataSize)
le_result_t le_flash_OpenUbiVolume(le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName, int32_t volumeSize)
le_result_t le_flash_CreateUbiVolume(le_flash_PartitionRef_t partitionRef, bool isForcedCreate, uint32_t volumeID, le_flash_UbiVolumeType_t volumeType, const char *LE_NONNULL volumeName, int32_t volumeSize)
void(* le_flash_DisconnectHandler_t)(void *)
Definition: le_flash_interface.h:191
le_result_t le_flash_ReleaseAccess(void)
le_flash_UbiVolumeType_t
Definition: le_flash_interface.h:371
le_result_t le_flash_GetUbiVolumeInformation(le_flash_PartitionRef_t partitionRef, uint32_t *freeBlockNumberPtr, uint32_t *allocatedBlockNumberPtr, uint32_t *sizeInBytesPtr)
le_flash_OpenMode_t
Definition: le_flash_interface.h:354
le_result_t le_flash_Read(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex, uint8_t *readDataPtr, size_t *readDataSizePtr)
void le_flash_DisconnectService(void)
struct le_flash_BadImageDetectionHandler * le_flash_BadImageDetectionHandlerRef_t
Definition: le_flash_interface.h:394
le_result_t le_flash_OpenMtd(const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
struct le_flash_Partition * le_flash_PartitionRef_t
Definition: le_flash_interface.h:386
void le_flash_SetServerDisconnectHandler(le_flash_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_flash_CreateUbi(const char *LE_NONNULL partitionName, bool isForcedCreate, le_flash_PartitionRef_t *partitionRefPtr)
void le_flash_ConnectService(void)
void le_flash_RemoveBadImageDetectionHandler(le_flash_BadImageDetectionHandlerRef_t handlerRef)
le_result_t le_flash_Close(le_flash_PartitionRef_t partitionRef)
le_result_t le_flash_OpenUbi(const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
le_result_t le_flash_TryConnectService(void)
le_result_t le_flash_DeleteUbiVolume(le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName)