Macros | Typedefs | Enumerations | Functions

le_flash_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros

#define LE_FLASH_IMAGE_NAME_MAX_LEN   32
 
#define LE_FLASH_IMAGE_NAME_MAX_BYTES   33
 
#define LE_FLASH_PARTITION_NAME_MAX_LEN   50
 
#define LE_FLASH_PARTITION_NAME_MAX_BYTES   51
 
#define LE_FLASH_VOLUME_NAME_MAX_LEN   50
 
#define LE_FLASH_VOLUME_NAME_MAX_BYTES   51
 
#define LE_FLASH_MAX_WRITE_SIZE   262144
 
#define LE_FLASH_MAX_READ_SIZE   262144
 
#define LE_FLASH_UBI_VOL_NO_SIZE   -1
 
#define LE_FLASH_UBI_VOL_NO_ID   -1
 
#define LE_FLASH_UBI_VOL_ID_MAX   127
 

Typedefs

typedef void(* le_flash_DisconnectHandler_t) (void *)
 
typedef struct le_flash_Partition * le_flash_PartitionRef_t
 
typedef struct le_flash_BadImageDetectionHandler * le_flash_BadImageDetectionHandlerRef_t
 
typedef void(* le_flash_BadImageDetectionHandlerFunc_t) (const char *LE_NONNULL imageName, void *contextPtr)
 

Enumerations

enum  le_flash_OpenMode_t { LE_FLASH_READ_ONLY = 0, LE_FLASH_WRITE_ONLY = 1, LE_FLASH_READ_WRITE = 2 }
 
enum  le_flash_UbiVolumeType_t { LE_FLASH_DYNAMIC = 0, LE_FLASH_STATIC = 1 }
 

Functions

void le_flash_ConnectService (void)
 
le_result_t le_flash_TryConnectService (void)
 
void le_flash_SetServerDisconnectHandler (le_flash_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_flash_DisconnectService (void)
 
le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler (le_flash_BadImageDetectionHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_flash_RemoveBadImageDetectionHandler (le_flash_BadImageDetectionHandlerRef_t handlerRef)
 
le_result_t le_flash_RequestAccess (void)
 
le_result_t le_flash_ReleaseAccess (void)
 
le_result_t le_flash_OpenMtd (const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
 
le_result_t le_flash_OpenUbi (const char *LE_NONNULL partitionName, le_flash_OpenMode_t mode, le_flash_PartitionRef_t *partitionRefPtr)
 
le_result_t le_flash_OpenUbiVolume (le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName, int32_t volumeSize)
 
le_result_t le_flash_CloseUbiVolume (le_flash_PartitionRef_t partitionRef)
 
le_result_t le_flash_Close (le_flash_PartitionRef_t partitionRef)
 
le_result_t le_flash_EraseBlock (le_flash_PartitionRef_t partitionRef, uint32_t blockIndex)
 
le_result_t le_flash_Read (le_flash_PartitionRef_t partitionRef, uint32_t blockIndex, uint8_t *readDataPtr, size_t *readDataSizePtr)
 
le_result_t le_flash_Write (le_flash_PartitionRef_t partitionRef, uint32_t blockIndex, const uint8_t *writeDataPtr, size_t writeDataSize)
 
le_result_t le_flash_GetBlockInformation (le_flash_PartitionRef_t partitionRef, uint32_t *badBlocksNumberPtr, uint32_t *eraseBlocksNumberPtr, uint32_t *eraseBlockSizePtr, uint32_t *pageSizePtr)
 
le_result_t le_flash_GetUbiVolumeInformation (le_flash_PartitionRef_t partitionRef, uint32_t *freeBlockNumberPtr, uint32_t *allocatedBlockNumberPtr, uint32_t *sizeInBytesPtr)
 
le_result_t le_flash_CreateUbi (const char *LE_NONNULL partitionName, bool isForcedCreate, le_flash_PartitionRef_t *partitionRefPtr)
 
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_result_t le_flash_DeleteUbiVolume (le_flash_PartitionRef_t partitionRef, const char *LE_NONNULL volumeName)
 

Detailed Description

Legato Flash API include file.

Copyright (C) Sierra Wireless Inc.

Macro Definition Documentation

#define LE_FLASH_IMAGE_NAME_MAX_BYTES   33

Image length maximum length. One extra byte is added for the null character.

#define LE_FLASH_IMAGE_NAME_MAX_LEN   32

Image length maximum length.

#define LE_FLASH_MAX_READ_SIZE   262144

Max byte storage size for read buffer

#define LE_FLASH_MAX_WRITE_SIZE   262144

Max byte storage size for write buffer

#define LE_FLASH_PARTITION_NAME_MAX_BYTES   51

Maximum partition name length One extra byte is added for the null character.

#define LE_FLASH_PARTITION_NAME_MAX_LEN   50

Maximum partition name length

#define LE_FLASH_UBI_VOL_ID_MAX   127

Maximum volume ID

#define LE_FLASH_UBI_VOL_NO_ID   -1

Default volume ID to specify the automatic allocation of volume ID

#define LE_FLASH_UBI_VOL_NO_SIZE   -1

Default volume size to keep the current volume size untouched

#define LE_FLASH_VOLUME_NAME_MAX_BYTES   51

Maximum volume name length One extra byte is added for the null character.

#define LE_FLASH_VOLUME_NAME_MAX_LEN   50

Maximum volume name length

Typedef Documentation

typedef void(* le_flash_BadImageDetectionHandlerFunc_t) (const char *LE_NONNULL imageName,void *contextPtr)

Handler for bad image detection.

Note
The image names are platform dependent.
typedef struct le_flash_BadImageDetectionHandler* le_flash_BadImageDetectionHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_flash_BadImageDetection'

typedef void(* le_flash_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

typedef struct le_flash_Partition* le_flash_PartitionRef_t

Declare a reference type for referring a partition.

Enumeration Type Documentation

enum le_flash_OpenMode_t

Open mode.

enum le_flash_UbiVolumeType_t

UBI volume type mode.

Function Documentation

le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler ( le_flash_BadImageDetectionHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_flash_BadImageDetection'

This event provides information on bad image status.

Parameters
[in]handlerPtr
[in]contextPtr
le_result_t le_flash_Close ( le_flash_PartitionRef_t  partitionRef)

Close a flash partition

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
Parameters
[in]partitionRefPartition reference to be closed.
le_result_t le_flash_CloseUbiVolume ( le_flash_PartitionRef_t  partitionRef)

Close the used UBI volume of an UBI image.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_FAULT On failure
Parameters
[in]partitionRefPartition reference.
void le_flash_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_flash_CreateUbi ( const char *LE_NONNULL  partitionName,
bool  isForcedCreate,
le_flash_PartitionRef_t *  partitionRefPtr 
)

Create an UBI partition. If the partition is already an UBI, an error is raised except if the flag isForcedCreate is set to true. In this case, the whole UBI partition is recreated and the previous content is lost. If the operation succeed, the partition is opened in write-only and this is not necessary to call le_flash_OpenUbi().

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_NOT_FOUND If the flash partition is not found
  • LE_DUPLICATE If the partition is already an UBI partition and isForcedCreate is not set to true
  • LE_FAULT On failure
Parameters
[in]partitionNamePartition to be opened.
[in]isForcedCreateForce the UBI recreation and overwrite the previous content.
[out]partitionRefPtrPartition reference.
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 
)

Create a new UBI volume into an UBI partition. If the volume name or the volume ID already exists, an error is raised except if the flag isForcedCreate is set to true. In this case, the whole UBI volume is recreated and the previous content is lost. If the operation succeed, UBI volume is opened and this is not necessary to call le_flash_OpenUbiVolume(). Note that the UBI partition should be opened in write-only or read-write mode, else an error is raised. The volumeName is the same parameter as le_flash_OpenUbiVolume(). A static volume cannot be extended when mounted, so it is generally used for SQUASHFS or others immutables and R/O filesystems. A dynamic volume is extensible like UBIFS volumes. The volume ID is the number of the UBI volume to be created. If set to NO_UBI_VOLUME_ID, the first free volume ID will be used.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_NOT_PERMITTED If the UBI partition is not opened in write-only or read-write mode
  • LE_DUPLICATE If the UBI volume already exists with a same name or a same volume ID and isForcedCreate is not set to true
  • LE_FAULT On failure
Parameters
[in]partitionRefPartition reference.
[in]isForcedCreateForce the UBI volume recreation and overwrite the previous content.
[in]volumeIDVolume ID to set.
[in]volumeTypeVolume type to set.
[in]volumeNameVolume name to be created.
[in]volumeSizeVolume size to set.
le_result_t le_flash_DeleteUbiVolume ( le_flash_PartitionRef_t  partitionRef,
const char *LE_NONNULL  volumeName 
)

Delete an UBI volume from an UBI partition. If the volume is currently opened by le_flash_OpenUbiVolume(), it is closed first. Note that the UBI partition should be opened in write-only or read-write mode, else an error is raised.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_NOT_PERMITTED If the UBI partition is not open in write-only or read-write mode
  • LE_NOT_FOUND If the volume name is not found
  • LE_FAULT On failure
Parameters
[in]partitionRefPartition reference.
[in]volumeNameVolume name to be deleted.
void le_flash_DisconnectService ( void  )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_flash_EraseBlock ( le_flash_PartitionRef_t  partitionRef,
uint32_t  blockIndex 
)

Erase a block inside a flash partition. If the erase fails, the block is marked bad.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_FAULT On other error
Parameters
[in]partitionRefPartition reference to be closed.
[in]blockIndexLogical block index to be erased.
le_result_t le_flash_GetBlockInformation ( le_flash_PartitionRef_t  partitionRef,
uint32_t *  badBlocksNumberPtr,
uint32_t *  eraseBlocksNumberPtr,
uint32_t *  eraseBlockSizePtr,
uint32_t *  pageSizePtr 
)

Retrieve information about the partition opened: the number of bad blocks found inside the partition, the number of erase blocks, the size of the erase block and the size of the page.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_FAULT On other error
Parameters
[in]partitionRefPartition reference to be used.
[out]badBlocksNumberPtrBad blocks number inside the partition
[out]eraseBlocksNumberPtrErase blocks number
[out]eraseBlockSizePtrErase block size
[out]pageSizePtrPage size
le_result_t le_flash_GetUbiVolumeInformation ( le_flash_PartitionRef_t  partitionRef,
uint32_t *  freeBlockNumberPtr,
uint32_t *  allocatedBlockNumberPtr,
uint32_t *  sizeInBytesPtr 
)

Retrieve information about the UBI volume opened: the number of free blocks for the UBI, the number of currently allocated blocks to the volume and its real size in bytes.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_FAULT On other error
Parameters
[in]partitionRefPartition reference to be used.
[out]freeBlockNumberPtrFree blocks number on the UBI partition
[out]allocatedBlockNumberPtrAllocated blocks number to the UBI volume
[out]sizeInBytesPtrReal size in bytes of the UBI volume
le_result_t le_flash_OpenMtd ( const char *LE_NONNULL  partitionName,
le_flash_OpenMode_t  mode,
le_flash_PartitionRef_t *  partitionRefPtr 
)

Open a flash partition at the block layer for the given operation and return a descriptor. The read and write operation will be done using MTD.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_NOT_FOUND If the flash partition is not found
  • LE_FAULT On failure
Parameters
[in]partitionNamePartition to be opened.
[in]modeOpening mode.
[out]partitionRefPtrPartition reference.
le_result_t le_flash_OpenUbi ( const char *LE_NONNULL  partitionName,
le_flash_OpenMode_t  mode,
le_flash_PartitionRef_t *  partitionRefPtr 
)

Open a UBI volume for the given operation and return a descriptor. The read and write operation will be done using MTD, UBI metadata will be updated.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_NOT_FOUND If the flash partition is not found
  • LE_FAULT On failure
Parameters
[in]partitionNamePartition to be opened.
[in]modeOpening mode.
[out]partitionRefPtrPartition reference.
le_result_t le_flash_OpenUbiVolume ( le_flash_PartitionRef_t  partitionRef,
const char *LE_NONNULL  volumeName,
int32_t  volumeSize 
)

Open the UBI volume of an UBI image to be used for the read and write operations. When open for writing and a volumeSize is given, the UBI volume will be adjusted to this size by freeing the PEBs over this size. If the data inside the volume require more PEBs, they will be added by the le_flash_Write() API.

Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_NOT_FOUND If the volume name is not found
  • LE_FAULT On failure
Parameters
[in]partitionRefPartition reference.
[in]volumeNameVolume name to be used.
[in]volumeSizeVolume size to set if open for writing
le_result_t le_flash_Read ( le_flash_PartitionRef_t  partitionRef,
uint32_t  blockIndex,
uint8_t *  readDataPtr,
size_t *  readDataSizePtr 
)

Read data from a flash partition. The read data are:

  • at the logical block index given by blockIndex.
  • the maximum read data length is:
    • an erase block size for MTD usage partition
    • an erase block size minus 2 pages for UBI partitions
Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_FAULT On other error
Parameters
[in]partitionRefPartition reference to be used.
[in]blockIndexLogical block index to be read.
[out]readDataPtrData buffer to copy the read data.
[in,out]readDataSizePtr
le_result_t le_flash_ReleaseAccess ( void  )

Release the flash access requested by le_flash_RequestAccess API.

Returns
  • LE_OK On success
  • LE_FAULT On failure
void le_flash_RemoveBadImageDetectionHandler ( le_flash_BadImageDetectionHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_flash_BadImageDetection'

Parameters
[in]handlerRef
le_result_t le_flash_RequestAccess ( void  )

Request the flash access authorization. This is required to avoid race operations.

Returns
  • LE_OK On success
  • LE_UNAVAILABLE The flash access is temporarily unavailable
  • LE_DUPLICATE If the a request access for the client was already performed
  • LE_FAULT On failure
void le_flash_SetServerDisconnectHandler ( le_flash_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

le_result_t le_flash_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.
le_result_t le_flash_Write ( le_flash_PartitionRef_t  partitionRef,
uint32_t  blockIndex,
const uint8_t *  writeDataPtr,
size_t  writeDataSize 
)

Write data to a flash partition.

  • the block is firstly erased, so no call to le_flash_EraseBlock() is needed.
  • if the erase or the write reports an error, the block is marked "bad" and the write starts again at the next physical block.
  • the data are programmed at the logical block index given by blockIndex.
  • the maximum written data length is:
    • an erase block size for MTD usage partition. This is the eraseBlockSize returned by le_flash_GetInformation().
    • an erase block size minus 2 pages for UBI partitions. These are the eraseBlockSize and pageSize returned by le_flash_GetInformation(). If the write addresses an UBI volume and more PEBs are required to write the new data, new PEBs will be added into this volume.
Note
The addressed block is automatically erased before to be written.
Returns
  • LE_OK On success
  • LE_BAD_PARAMETER If a parameter is invalid
  • LE_FAULT On other error
Parameters
[in]partitionRefPartition reference to be used.
[in]blockIndexLogical block index to be write.
[in]writeDataPtrData buffer to be written.
[in]writeDataSize