#include "legato.h"
#include "le_flash_common.h"

Typedefs
typedef void(*	le_flash_DisconnectHandler_t) (void *)

Functions
void	le_flash_ConnectService (void)

le_result_t	le_flash_TryConnectService (void)

LE_FULL_API 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.

Typedef Documentation

◆ le_flash_DisconnectHandler_t

typedef void(* le_flash_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Function Documentation

◆ le_flash_AddBadImageDetectionHandler()

le_flash_BadImageDetectionHandlerRef_t le_flash_AddBadImageDetectionHandler	(	le_flash_BadImageDetectionHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Open mode. UBI volume type mode. Declare a reference type for referring a partition. Handler for bad image detection.

Note: The image names are platform dependent. Reference type used by Add/Remove functions for EVENT 'le_flash_BadImageDetection' Add handler function for EVENT 'le_flash_BadImageDetection'

This event provides information on bad image status.

Parameters

[in]	handlerPtr
[in]	contextPtr

◆ le_flash_Close()

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] partitionRef Partition reference to be closed.

◆ le_flash_CloseUbiVolume()

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] partitionRef Partition reference.

◆ le_flash_ConnectService()

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_flash_CreateUbi()

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]	partitionName	Partition to be opened.
[in]	isForcedCreate	Force the UBI recreation and overwrite the previous content.
[out]	partitionRefPtr	Partition reference.

◆ 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
	)

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]	partitionRef	Partition reference.
[in]	isForcedCreate	Force the UBI volume recreation and overwrite the previous content.
[in]	volumeID	Volume ID to set.
[in]	volumeType	Volume type to set.
[in]	volumeName	Volume name to be created.
[in]	volumeSize	Volume size to set.

◆ le_flash_DeleteUbiVolume()

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]	partitionRef	Partition reference.
[in]	volumeName	Volume name to be deleted.

◆ le_flash_DisconnectService()

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_flash_EraseBlock()

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]	partitionRef	Partition reference to be closed.
[in]	blockIndex	Logical block index to be erased.

◆ 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
	)

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]	partitionRef	Partition reference to be used.
[out]	badBlocksNumberPtr	Bad blocks number inside the partition
[out]	eraseBlocksNumberPtr	Erase blocks number
[out]	eraseBlockSizePtr	Erase block size
[out]	pageSizePtr	Page size

◆ le_flash_GetUbiVolumeInformation()

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]	partitionRef	Partition reference to be used.
[out]	freeBlockNumberPtr	Free blocks number on the UBI partition
[out]	allocatedBlockNumberPtr	Allocated blocks number to the UBI volume
[out]	sizeInBytesPtr	Real size in bytes of the UBI volume

◆ le_flash_OpenMtd()

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]	partitionName	Partition to be opened.
[in]	mode	Opening mode.
[out]	partitionRefPtr	Partition reference.

◆ le_flash_OpenUbi()

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]	partitionName	Partition to be opened.
[in]	mode	Opening mode.
[out]	partitionRefPtr	Partition reference.

◆ le_flash_OpenUbiVolume()

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]	partitionRef	Partition reference.
[in]	volumeName	Volume name to be used.
[in]	volumeSize	Volume size to set if open for writing

◆ le_flash_Read()

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]	partitionRef	Partition reference to be used.
[in]	blockIndex	Logical block index to be read.
[out]	readDataPtr	Data buffer to copy the read data.
[in,out]	readDataSizePtr

◆ le_flash_ReleaseAccess()

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

◆ le_flash_RemoveBadImageDetectionHandler()

void le_flash_RemoveBadImageDetectionHandler ( le_flash_BadImageDetectionHandlerRef_t handlerRef )

Remove handler function for EVENT 'le_flash_BadImageDetection'

Parameters

[in] handlerRef

◆ le_flash_RequestAccess()

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

◆ le_flash_SetServerDisconnectHandler()

LE_FULL_API 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_flash_TryConnectService()

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_flash_Write()

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]	partitionRef	Partition reference to be used.
[in]	blockIndex	Logical block index to be write.
[in]	writeDataPtr	Data buffer to be written.
[in]	writeDataSize

/ Legato Documentation

le_flash_interface.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ le_flash_DisconnectHandler_t

Function Documentation

◆ le_flash_AddBadImageDetectionHandler()

◆ le_flash_Close()

◆ le_flash_CloseUbiVolume()

◆ le_flash_ConnectService()

◆ le_flash_CreateUbi()

◆ le_flash_CreateUbiVolume()

◆ le_flash_DeleteUbiVolume()

◆ le_flash_DisconnectService()

◆ le_flash_EraseBlock()

◆ le_flash_GetBlockInformation()

◆ le_flash_GetUbiVolumeInformation()

◆ le_flash_OpenMtd()

◆ le_flash_OpenUbi()

◆ le_flash_OpenUbiVolume()

◆ le_flash_Read()

◆ le_flash_ReleaseAccess()

◆ le_flash_RemoveBadImageDetectionHandler()

◆ le_flash_RequestAccess()

◆ le_flash_SetServerDisconnectHandler()

◆ le_flash_TryConnectService()

◆ le_flash_Write()