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