le_flash_interface.h

    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 //--------------------------------------------------------------------------------------------------
  206 void le_flash_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  231 le_result_t le_flash_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  244 void le_flash_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  262 void le_flash_DisconnectService
  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 }
  363 le_flash_OpenMode_t;
  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 }
  378 le_flash_UbiVolumeType_t;
  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 //--------------------------------------------------------------------------------------------------
  404 typedef void (*le_flash_BadImageDetectionHandlerFunc_t)
  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 //--------------------------------------------------------------------------------------------------
  420 le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler
  421 (
  422     le_flash_BadImageDetectionHandlerFunc_t handlerPtr,
  423         ///< [IN]
  424     void* contextPtr
  425         ///< [IN]
  426 );
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  * Remove handler function for EVENT 'le_flash_BadImageDetection'
  431  */
  432 //--------------------------------------------------------------------------------------------------
  433 void le_flash_RemoveBadImageDetectionHandler
  434 (
  435     le_flash_BadImageDetectionHandlerRef_t handlerRef
  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 //--------------------------------------------------------------------------------------------------
  451 le_result_t le_flash_RequestAccess
  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 //--------------------------------------------------------------------------------------------------
  466 le_result_t le_flash_ReleaseAccess
  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 //--------------------------------------------------------------------------------------------------
  484 le_result_t le_flash_OpenMtd
  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 //--------------------------------------------------------------------------------------------------
  507 le_result_t le_flash_OpenUbi
  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 //--------------------------------------------------------------------------------------------------
  532 le_result_t le_flash_OpenUbiVolume
  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 //--------------------------------------------------------------------------------------------------
  553 le_result_t le_flash_CloseUbiVolume
  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 //--------------------------------------------------------------------------------------------------
  568 le_result_t le_flash_Close
  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 //--------------------------------------------------------------------------------------------------
  584 le_result_t le_flash_EraseBlock
  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 //--------------------------------------------------------------------------------------------------
  606 le_result_t le_flash_Read
  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 //--------------------------------------------------------------------------------------------------
  642 le_result_t le_flash_Write
  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 //--------------------------------------------------------------------------------------------------
  665 le_result_t le_flash_GetBlockInformation
  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 //--------------------------------------------------------------------------------------------------
  690 le_result_t le_flash_GetUbiVolumeInformation
  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 //--------------------------------------------------------------------------------------------------
  720 le_result_t le_flash_CreateUbi
  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 //--------------------------------------------------------------------------------------------------
  756 le_result_t le_flash_CreateUbiVolume
  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 //--------------------------------------------------------------------------------------------------
  789 le_result_t le_flash_DeleteUbiVolume
  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_AddBadImageDetectionHandler
le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler(le_flash_BadImageDetectionHandlerFunc_t handlerPtr, void *contextPtr)
le_flash_EraseBlock
le_result_t le_flash_EraseBlock(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex)
le_flash_GetBlockInformation
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
le_result_t
Definition: le_basics.h:35
le_flash_BadImageDetectionHandlerFunc_t
void(* le_flash_BadImageDetectionHandlerFunc_t)(const char *LE_NONNULL imageName, void *contextPtr)
Definition: le_flash_interface.h:405
le_flash_RequestAccess
le_result_t le_flash_RequestAccess(void)
le_flash_CloseUbiVolume
le_result_t le_flash_CloseUbiVolume(le_flash_PartitionRef_t partitionRef)
le_flash_Write
le_result_t le_flash_Write(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex, const uint8_t *writeDataPtr, size_t writeDataSize)
le_flash_OpenUbiVolume
le_result_t le_flash_OpenUbiVolume(le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName, int32_t volumeSize)
le_flash_CreateUbiVolume
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)
le_flash_DisconnectHandler_t
void(* le_flash_DisconnectHandler_t)(void *)
Definition: le_flash_interface.h:191
le_flash_ReleaseAccess
le_result_t le_flash_ReleaseAccess(void)
le_flash_UbiVolumeType_t
le_flash_UbiVolumeType_t
Definition: le_flash_interface.h:371
le_flash_GetUbiVolumeInformation
le_result_t le_flash_GetUbiVolumeInformation(le_flash_PartitionRef_t partitionRef, uint32_t *freeBlockNumberPtr, uint32_t *allocatedBlockNumberPtr, uint32_t *sizeInBytesPtr)
le_flash_OpenMode_t
le_flash_OpenMode_t
Definition: le_flash_interface.h:354
le_flash_Read
le_result_t le_flash_Read(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex, uint8_t *readDataPtr, size_t *readDataSizePtr)
le_flash_DisconnectService
void le_flash_DisconnectService(void)
le_flash_BadImageDetectionHandlerRef_t
struct le_flash_BadImageDetectionHandler * le_flash_BadImageDetectionHandlerRef_t
Definition: le_flash_interface.h:394
le_flash_OpenMtd
le_result_t le_flash_OpenMtd(const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
le_flash_PartitionRef_t
struct le_flash_Partition * le_flash_PartitionRef_t
Definition: le_flash_interface.h:386
le_flash_SetServerDisconnectHandler
void le_flash_SetServerDisconnectHandler(le_flash_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_flash_CreateUbi
le_result_t le_flash_CreateUbi(const char *LE_NONNULL partitionName, bool isForcedCreate, le_flash_PartitionRef_t *partitionRefPtr)
legato.h
le_flash_ConnectService
void le_flash_ConnectService(void)
le_flash_RemoveBadImageDetectionHandler
void le_flash_RemoveBadImageDetectionHandler(le_flash_BadImageDetectionHandlerRef_t handlerRef)
le_flash_Close
le_result_t le_flash_Close(le_flash_PartitionRef_t partitionRef)
le_flash_OpenUbi
le_result_t le_flash_OpenUbi(const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
le_flash_TryConnectService
le_result_t le_flash_TryConnectService(void)
le_flash_DeleteUbiVolume
le_result_t le_flash_DeleteUbiVolume(le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName)