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 // Internal includes for this interface
  186 #include "le_flash_common.h"
  187 /** @addtogroup le_flash le_flash API Reference
  188  * @{
  189  * @file le_flash_common.h
  190  * @file le_flash_interface.h **/
  191 //--------------------------------------------------------------------------------------------------
  192 /**
  193  * Type for handler called when a server disconnects.
  194  */
  195 //--------------------------------------------------------------------------------------------------
  196 typedef void (*le_flash_DisconnectHandler_t)(void *);
  197 
  198 //--------------------------------------------------------------------------------------------------
  199 /**
  200  *
  201  * Connect the current client thread to the service providing this API. Block until the service is
  202  * available.
  203  *
  204  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  205  * called before any other functions in this API.  Normally, ConnectService is automatically called
  206  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  207  *
  208  * This function is created automatically.
  209  */
  210 //--------------------------------------------------------------------------------------------------
  211 void le_flash_ConnectService
  212 (
  213     void
  214 );
  215 
  216 //--------------------------------------------------------------------------------------------------
  217 /**
  218  *
  219  * Try to connect the current client thread to the service providing this API. Return with an error
  220  * if the service is not available.
  221  *
  222  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  223  * called before any other functions in this API.  Normally, ConnectService is automatically called
  224  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  225  *
  226  * This function is created automatically.
  227  *
  228  * @return
  229  *  - LE_OK if the client connected successfully to the service.
  230  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  231  *    bound.
  232  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  233  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  234  */
  235 //--------------------------------------------------------------------------------------------------
  236 le_result_t le_flash_TryConnectService
  237 (
  238     void
  239 );
  240 
  241 //--------------------------------------------------------------------------------------------------
  242 /**
  243  * Set handler called when server disconnection is detected.
  244  *
  245  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  246  * to continue without exiting, it should call longjmp() from inside the handler.
  247  */
  248 //--------------------------------------------------------------------------------------------------
  249 LE_FULL_API void le_flash_SetServerDisconnectHandler
  250 (
  251     le_flash_DisconnectHandler_t disconnectHandler,
  252     void *contextPtr
  253 );
  254 
  255 //--------------------------------------------------------------------------------------------------
  256 /**
  257  *
  258  * Disconnect the current client thread from the service providing this API.
  259  *
  260  * Normally, this function doesn't need to be called. After this function is called, there's no
  261  * longer a connection to the service, and the functions in this API can't be used. For details, see
  262  * @ref apiFilesC_client.
  263  *
  264  * This function is created automatically.
  265  */
  266 //--------------------------------------------------------------------------------------------------
  267 void le_flash_DisconnectService
  268 (
  269     void
  270 );
  271 
  272 
  273 //--------------------------------------------------------------------------------------------------
  274 /**
  275  * Open mode.
  276  */
  277 //--------------------------------------------------------------------------------------------------
  278 
  279 
  280 //--------------------------------------------------------------------------------------------------
  281 /**
  282  * UBI volume type mode.
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 
  286 
  287 //--------------------------------------------------------------------------------------------------
  288 /**
  289  * Declare a reference type for referring a partition.
  290  */
  291 //--------------------------------------------------------------------------------------------------
  292 
  293 
  294 //--------------------------------------------------------------------------------------------------
  295 /**
  296  * Handler for bad image detection.
  297  *
  298  * @note The image names are platform dependent.
  299  */
  300 //--------------------------------------------------------------------------------------------------
  301 
  302 
  303 //--------------------------------------------------------------------------------------------------
  304 /**
  305  * Reference type used by Add/Remove functions for EVENT 'le_flash_BadImageDetection'
  306  */
  307 //--------------------------------------------------------------------------------------------------
  308 
  309 
  310 //--------------------------------------------------------------------------------------------------
  311 /**
  312  * Add handler function for EVENT 'le_flash_BadImageDetection'
  313  *
  314  * This event provides information on bad image status.
  315  *
  316  */
  317 //--------------------------------------------------------------------------------------------------
  318 le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler
  319 (
  320     le_flash_BadImageDetectionHandlerFunc_t handlerPtr,
  321         ///< [IN]
  322     void* contextPtr
  323         ///< [IN]
  324 );
  325 
  326 //--------------------------------------------------------------------------------------------------
  327 /**
  328  * Remove handler function for EVENT 'le_flash_BadImageDetection'
  329  */
  330 //--------------------------------------------------------------------------------------------------
  331 void le_flash_RemoveBadImageDetectionHandler
  332 (
  333     le_flash_BadImageDetectionHandlerRef_t handlerRef
  334         ///< [IN]
  335 );
  336 
  337 //--------------------------------------------------------------------------------------------------
  338 /**
  339  * Request the flash access authorization. This is required to avoid race operations.
  340  *
  341  * @return
  342  *      - LE_OK            On success
  343  *      - LE_UNAVAILABLE   The flash access is temporarily unavailable
  344  *      - LE_DUPLICATE     If the a request access for the client was already performed
  345  *      - LE_FAULT         On failure
  346  *
  347  */
  348 //--------------------------------------------------------------------------------------------------
  349 le_result_t le_flash_RequestAccess
  350 (
  351     void
  352 );
  353 
  354 //--------------------------------------------------------------------------------------------------
  355 /**
  356  * Release the flash access requested by le_flash_RequestAccess API.
  357  *
  358  * @return
  359  *      - LE_OK            On success
  360  *      - LE_FAULT         On failure
  361  *
  362  */
  363 //--------------------------------------------------------------------------------------------------
  364 le_result_t le_flash_ReleaseAccess
  365 (
  366     void
  367 );
  368 
  369 //--------------------------------------------------------------------------------------------------
  370 /**
  371  * Open a flash partition at the block layer for the given operation and return a descriptor.
  372  * The read and write operation will be done using MTD.
  373  *
  374  * @return
  375  *      - LE_OK            On success
  376  *      - LE_BAD_PARAMETER If a parameter is invalid
  377  *      - LE_NOT_FOUND     If the flash partition is not found
  378  *      - LE_FAULT         On failure
  379  *
  380  */
  381 //--------------------------------------------------------------------------------------------------
  382 le_result_t le_flash_OpenMtd
  383 (
  384     const char* LE_NONNULL partitionName,
  385         ///< [IN] Partition to be opened.
  386     le_flash_OpenMode_t mode,
  387         ///< [IN] Opening mode.
  388     le_flash_PartitionRef_t* partitionRefPtr
  389         ///< [OUT] Partition reference.
  390 );
  391 
  392 //--------------------------------------------------------------------------------------------------
  393 /**
  394  * Open a UBI volume for the given operation and return a descriptor. The read and write
  395  * operation will be done using MTD, UBI metadata will be updated.
  396  *
  397  * @return
  398  *      - LE_OK            On success
  399  *      - LE_BAD_PARAMETER If a parameter is invalid
  400  *      - LE_NOT_FOUND     If the flash partition is not found
  401  *      - LE_FAULT         On failure
  402  *
  403  */
  404 //--------------------------------------------------------------------------------------------------
  405 le_result_t le_flash_OpenUbi
  406 (
  407     const char* LE_NONNULL partitionName,
  408         ///< [IN] Partition to be opened.
  409     le_flash_OpenMode_t mode,
  410         ///< [IN] Opening mode.
  411     le_flash_PartitionRef_t* partitionRefPtr
  412         ///< [OUT] Partition reference.
  413 );
  414 
  415 //--------------------------------------------------------------------------------------------------
  416 /**
  417  * Open the UBI volume of an UBI image to be used for the read and write operations. When open for
  418  * writing and a volumeSize is given, the UBI volume will be adjusted to this size by freeing the
  419  * PEBs over this size. If the data inside the volume require more PEBs, they will be added
  420  * by the le_flash_Write() API.
  421  *
  422  * @return
  423  *      - LE_OK            On success
  424  *      - LE_BAD_PARAMETER If a parameter is invalid
  425  *      - LE_NOT_FOUND     If the volume name is not found
  426  *      - LE_FAULT         On failure
  427  *
  428  */
  429 //--------------------------------------------------------------------------------------------------
  430 le_result_t le_flash_OpenUbiVolume
  431 (
  432     le_flash_PartitionRef_t partitionRef,
  433         ///< [IN] Partition reference.
  434     const char* LE_NONNULL volumeName,
  435         ///< [IN] Volume name to be used.
  436     int32_t volumeSize
  437         ///< [IN] Volume size to set if open for writing
  438 );
  439 
  440 //--------------------------------------------------------------------------------------------------
  441 /**
  442  * Close the used UBI volume of an UBI image.
  443  *
  444  * @return
  445  *      - LE_OK            On success
  446  *      - LE_BAD_PARAMETER If a parameter is invalid
  447  *      - LE_FAULT         On failure
  448  *
  449  */
  450 //--------------------------------------------------------------------------------------------------
  451 le_result_t le_flash_CloseUbiVolume
  452 (
  453     le_flash_PartitionRef_t partitionRef
  454         ///< [IN] Partition reference.
  455 );
  456 
  457 //--------------------------------------------------------------------------------------------------
  458 /**
  459  * Close a flash partition
  460  *
  461  * @return
  462  *      - LE_OK            On success
  463  *      - LE_BAD_PARAMETER If a parameter is invalid
  464  */
  465 //--------------------------------------------------------------------------------------------------
  466 le_result_t le_flash_Close
  467 (
  468     le_flash_PartitionRef_t partitionRef
  469         ///< [IN] Partition reference to be closed.
  470 );
  471 
  472 //--------------------------------------------------------------------------------------------------
  473 /**
  474  * Erase a block inside a flash partition. If the erase fails, the block is marked bad.
  475  *
  476  * @return
  477  *      - LE_OK            On success
  478  *      - LE_BAD_PARAMETER If a parameter is invalid
  479  *      - LE_FAULT         On other error
  480  */
  481 //--------------------------------------------------------------------------------------------------
  482 le_result_t le_flash_EraseBlock
  483 (
  484     le_flash_PartitionRef_t partitionRef,
  485         ///< [IN] Partition reference to be closed.
  486     uint32_t blockIndex
  487         ///< [IN] Logical block index to be erased.
  488 );
  489 
  490 //--------------------------------------------------------------------------------------------------
  491 /**
  492  * Read data from a flash partition. The read data are:
  493  * - at the logical block index given by blockIndex.
  494  * - the maximum read data length is:
  495  *      - an erase block size for MTD usage partition
  496  *      - an erase block size minus 2 pages for UBI partitions
  497  *
  498  * @return
  499  *      - LE_OK            On success
  500  *      - LE_BAD_PARAMETER If a parameter is invalid
  501  *      - LE_FAULT         On other error
  502  */
  503 //--------------------------------------------------------------------------------------------------
  504 le_result_t le_flash_Read
  505 (
  506     le_flash_PartitionRef_t partitionRef,
  507         ///< [IN] Partition reference to be used.
  508     uint32_t blockIndex,
  509         ///< [IN] Logical block index to be read.
  510     uint8_t* readDataPtr,
  511         ///< [OUT] Data buffer to copy the read data.
  512     size_t* readDataSizePtr
  513         ///< [INOUT]
  514 );
  515 
  516 //--------------------------------------------------------------------------------------------------
  517 /**
  518  * Write data to a flash partition.
  519  * - the block is firstly erased, so no call to le_flash_EraseBlock() is needed.
  520  * - if the erase or the write reports an error, the block is marked "bad" and the write starts
  521  *   again at the next physical block.
  522  * - the data are programmed at the logical block index given by blockIndex.
  523  * - the maximum written data length is:
  524  *      - an erase block size for MTD usage partition. This is the eraseBlockSize returned by
  525  *        le_flash_GetInformation().
  526  *      - an erase block size minus 2 pages for UBI partitions. These are the eraseBlockSize and
  527  *        pageSize returned by le_flash_GetInformation().
  528  * If the write addresses an UBI volume and more PEBs are required to write the new data, new PEBs
  529  * will be added into this volume.
  530  *
  531  * @note
  532  *      The addressed block is automatically erased before to be written.
  533  *
  534  * @return
  535  *      - LE_OK            On success
  536  *      - LE_BAD_PARAMETER If a parameter is invalid
  537  *      - LE_FAULT         On other error
  538  */
  539 //--------------------------------------------------------------------------------------------------
  540 le_result_t le_flash_Write
  541 (
  542     le_flash_PartitionRef_t partitionRef,
  543         ///< [IN] Partition reference to be used.
  544     uint32_t blockIndex,
  545         ///< [IN] Logical block index to be write.
  546     const uint8_t* writeDataPtr,
  547         ///< [IN] Data buffer to be written.
  548     size_t writeDataSize
  549         ///< [IN]
  550 );
  551 
  552 //--------------------------------------------------------------------------------------------------
  553 /**
  554  * Retrieve information about the partition opened: the number of bad blocks found inside the
  555  * partition, the number of erase blocks, the size of the erase block and the size of the page.
  556  *
  557  * @return
  558  *      - LE_OK            On success
  559  *      - LE_BAD_PARAMETER If a parameter is invalid
  560  *      - LE_FAULT         On other error
  561  */
  562 //--------------------------------------------------------------------------------------------------
  563 le_result_t le_flash_GetBlockInformation
  564 (
  565     le_flash_PartitionRef_t partitionRef,
  566         ///< [IN] Partition reference to be used.
  567     uint32_t* badBlocksNumberPtr,
  568         ///< [OUT] Bad blocks number inside the partition
  569     uint32_t* eraseBlocksNumberPtr,
  570         ///< [OUT] Erase blocks number
  571     uint32_t* eraseBlockSizePtr,
  572         ///< [OUT] Erase block size
  573     uint32_t* pageSizePtr
  574         ///< [OUT] Page size
  575 );
  576 
  577 //--------------------------------------------------------------------------------------------------
  578 /**
  579  * Retrieve information about the UBI volume opened: the number of free blocks for the UBI,
  580  * the number of currently allocated blocks to the volume and its real size in bytes.
  581  *
  582  * @return
  583  *      - LE_OK            On success
  584  *      - LE_BAD_PARAMETER If a parameter is invalid
  585  *      - LE_FAULT         On other error
  586  */
  587 //--------------------------------------------------------------------------------------------------
  588 le_result_t le_flash_GetUbiVolumeInformation
  589 (
  590     le_flash_PartitionRef_t partitionRef,
  591         ///< [IN] Partition reference to be used.
  592     uint32_t* freeBlockNumberPtr,
  593         ///< [OUT] Free blocks number on the UBI partition
  594     uint32_t* allocatedBlockNumberPtr,
  595         ///< [OUT] Allocated blocks number to the UBI volume
  596     uint32_t* sizeInBytesPtr
  597         ///< [OUT] Real size in bytes of the UBI volume
  598 );
  599 
  600 //--------------------------------------------------------------------------------------------------
  601 /**
  602  * Create an UBI partition.
  603  * If the partition is already an UBI, an error is raised except if the flag isForcedCreate is set
  604  * to true. In this case, the whole UBI partition is recreated and the previous content is lost.
  605  * If the operation succeed, the partition is opened in write-only and this is not necessary to
  606  * call le_flash_OpenUbi().
  607  *
  608  * @return
  609  *      - LE_OK            On success
  610  *      - LE_BAD_PARAMETER If a parameter is invalid
  611  *      - LE_NOT_FOUND     If the flash partition is not found
  612  *      - LE_DUPLICATE     If the partition is already an UBI partition and isForcedCreate is not
  613  *                         set to true
  614  *      - LE_FAULT         On failure
  615  *
  616  */
  617 //--------------------------------------------------------------------------------------------------
  618 le_result_t le_flash_CreateUbi
  619 (
  620     const char* LE_NONNULL partitionName,
  621         ///< [IN] Partition to be opened.
  622     bool isForcedCreate,
  623         ///< [IN] Force the UBI recreation and
  624         ///< overwrite the previous content.
  625     le_flash_PartitionRef_t* partitionRefPtr
  626         ///< [OUT] Partition reference.
  627 );
  628 
  629 //--------------------------------------------------------------------------------------------------
  630 /**
  631  * Create a new UBI volume into an UBI partition.
  632  * If the volume name or the volume ID already exists, an error is raised except if the flag
  633  * isForcedCreate is set to true. In this case, the whole UBI volume is recreated and the previous
  634  * content is lost. If the operation succeed, UBI volume is opened and this is not necessary to
  635  * call le_flash_OpenUbiVolume().
  636  * Note that the UBI partition should be opened in write-only or read-write mode, else an error is
  637  * raised.
  638  * The volumeName is the same parameter as le_flash_OpenUbiVolume().
  639  * A static volume cannot be extended when mounted, so it is generally used for SQUASHFS or others
  640  * immutables and R/O filesystems. A dynamic volume is extensible like UBIFS volumes.
  641  * The volume ID is the number of the UBI volume to be created. If set to NO_UBI_VOLUME_ID, the
  642  * first free volume ID will be used.
  643  *
  644  * @return
  645  *      - LE_OK            On success
  646  *      - LE_BAD_PARAMETER If a parameter is invalid
  647  *      - LE_NOT_PERMITTED If the UBI partition is not opened in write-only or read-write mode
  648  *      - LE_DUPLICATE     If the UBI volume already exists with a same name or a same volume ID
  649  *                         and isForcedCreate is not set to true
  650  *      - LE_FAULT         On failure
  651  *
  652  */
  653 //--------------------------------------------------------------------------------------------------
  654 le_result_t le_flash_CreateUbiVolume
  655 (
  656     le_flash_PartitionRef_t partitionRef,
  657         ///< [IN] Partition reference.
  658     bool isForcedCreate,
  659         ///< [IN] Force the UBI volume recreation and
  660         ///< overwrite the previous content.
  661     uint32_t volumeID,
  662         ///< [IN] Volume ID to set.
  663     le_flash_UbiVolumeType_t volumeType,
  664         ///< [IN] Volume type to set.
  665     const char* LE_NONNULL volumeName,
  666         ///< [IN] Volume name to be created.
  667     int32_t volumeSize
  668         ///< [IN] Volume size to set.
  669 );
  670 
  671 //--------------------------------------------------------------------------------------------------
  672 /**
  673  * Delete an UBI volume from an UBI partition.
  674  * If the volume is currently opened by le_flash_OpenUbiVolume(), it is closed first.
  675  * Note that the UBI partition should be opened in write-only or read-write mode, else an error is
  676  * raised.
  677  *
  678  * @return
  679  *      - LE_OK            On success
  680  *      - LE_BAD_PARAMETER If a parameter is invalid
  681  *      - LE_NOT_PERMITTED If the UBI partition is not open in write-only or read-write mode
  682  *      - LE_NOT_FOUND     If the volume name is not found
  683  *      - LE_FAULT         On failure
  684  *
  685  */
  686 //--------------------------------------------------------------------------------------------------
  687 le_result_t le_flash_DeleteUbiVolume
  688 (
  689     le_flash_PartitionRef_t partitionRef,
  690         ///< [IN] Partition reference.
  691     const char* LE_NONNULL volumeName
  692         ///< [IN] Volume name to be deleted.
  693 );
  694 
  695 /** @} **/
  696 
  697 #endif // LE_FLASH_INTERFACE_H_INCLUDE_GUARD
le_flash_OpenMode_t
le_flash_OpenMode_t
Definition: le_flash_common.h:114
le_flash_RemoveBadImageDetectionHandler
void le_flash_RemoveBadImageDetectionHandler(le_flash_BadImageDetectionHandlerRef_t handlerRef)
le_flash_ReleaseAccess
le_result_t le_flash_ReleaseAccess(void)
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_ConnectService
void le_flash_ConnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:46
le_flash_PartitionRef_t
struct le_flash_Partition * le_flash_PartitionRef_t
Definition: le_flash_common.h:146
le_flash_SetServerDisconnectHandler
LE_FULL_API void le_flash_SetServerDisconnectHandler(le_flash_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_flash_UbiVolumeType_t
le_flash_UbiVolumeType_t
Definition: le_flash_common.h:131
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_CloseUbiVolume
le_result_t le_flash_CloseUbiVolume(le_flash_PartitionRef_t partitionRef)
le_flash_DisconnectService
void le_flash_DisconnectService(void)
le_flash_TryConnectService
le_result_t le_flash_TryConnectService(void)
le_flash_AddBadImageDetectionHandler
le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler(le_flash_BadImageDetectionHandlerFunc_t handlerPtr, void *contextPtr)
le_flash_CreateUbi
le_result_t le_flash_CreateUbi(const char *LE_NONNULL partitionName, bool isForcedCreate, le_flash_PartitionRef_t *partitionRefPtr)
le_flash_DisconnectHandler_t
void(* le_flash_DisconnectHandler_t)(void *)
Definition: le_flash_interface.h:196
le_flash_DeleteUbiVolume
le_result_t le_flash_DeleteUbiVolume(le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName)
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_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_Close
le_result_t le_flash_Close(le_flash_PartitionRef_t partitionRef)
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_OpenUbi
le_result_t le_flash_OpenUbi(const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
le_flash_EraseBlock
le_result_t le_flash_EraseBlock(le_flash_PartitionRef_t partitionRef, uint32_t blockIndex)
le_flash_OpenUbiVolume
le_result_t le_flash_OpenUbiVolume(le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName, int32_t volumeSize)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
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_BadImageDetectionHandlerRef_t
struct le_flash_BadImageDetectionHandler * le_flash_BadImageDetectionHandlerRef_t
Definition: le_flash_common.h:154
le_flash_BadImageDetectionHandlerFunc_t
void(* le_flash_BadImageDetectionHandlerFunc_t)(const char *LE_NONNULL imageName, void *contextPtr)
Definition: le_flash_common.h:165
le_flash_common.h
le_flash_RequestAccess
le_result_t le_flash_RequestAccess(void)