Managed Flash Storage Driver. More...

Collaboration diagram for Managed Flash Storage Driver:

Detailed Description

Managed Flash Storage Driver.

This module implements a managed flash storage able to store a finite number of variable-size records. Records are retrieved by their index number.
The driver is automatically performs:

Wear leveling.
Auto repair after power loss.
Garbage collection in order to remove erased data.

Macros
#define	ALIGNED_REC_SIZE(n) (flash_offset_t)MFS_ALIGN_NEXT(sizeof (mfs_data_header_t) + (size_t)(n))
	Data record size aligned. More...

#define	ALIGNED_DHDR_SIZE ALIGNED_REC_SIZE(0)
	Data record header size aligned. More...

#define	ALIGNED_SIZEOF(t) (((sizeof (t) - 1U) \| MFS_ALIGN_MASK) + 1U)
	Aligned size of a type. More...

#define	PAIR(a, b) (((unsigned)(a) << 2U) \| (unsigned)(b))
	Combines two values (0..3) in one (0..15). More...

#define	RET_ON_ERROR(err)
	Error check helper. More...

Configuration options
#define	MFS_CFG_MAX_RECORDS 32
	Maximum number of indexed records in the managed storage. More...

#define	MFS_CFG_MAX_REPAIR_ATTEMPTS 3
	Maximum number of repair attempts on partition mount. More...

#define	MFS_CFG_WRITE_VERIFY TRUE
	Verify written data. More...

#define	MFS_CFG_STRONG_CHECKING TRUE
	Enables a stronger and slower check procedure on mount. More...

#define	MFS_CFG_BUFFER_SIZE 32
	Size of the buffer used for data copying. More...

#define	MFS_CFG_MEMORY_ALIGNMENT 2
	Enforced memory alignment. More...

#define	MFS_CFG_TRANSACTION_MAX 16
	Maximum number of objects writable in a single transaction. More...

Error codes handling macros
#define	MFS_IS_ERROR(err) ((err) < MFS_NO_ERROR)

#define	MFS_IS_WARNING(err) ((err) > MFS_NO_ERROR)

Alignment macros
#define	MFS_ALIGN_MASK ((uint32_t)MFS_CFG_MEMORY_ALIGNMENT - 1U)

#define	MFS_IS_ALIGNED(v) (((uint32_t)(v) & MFS_ALIGN_MASK) == 0U)

#define	MFS_ALIGN_PREV(v) ((uint32_t)(v) & ~MFS_ALIGN_MASK)

#define	MFS_ALIGN_NEXT(v)

Typedefs
typedef uint32_t	mfs_id_t
	Type of a record identifier. More...

Data Structures
union	mfs_bank_header_t
	Type of a bank header. More...

union	mfs_data_header_t
	Type of a data block header. More...

struct	MFSConfig
	Type of a MFS configuration structure. More...

struct	mfs_transaction_op_t
	Type of a buffered write/erase operation within a transaction. More...

struct	MFSDriver
	Type of an MFS instance. More...

Functions
static mfs_error_t	mfs_flash_read (MFSDriver mfsp, flash_offset_t offset, size_t n, uint8_t rp)
	Flash read. More...

static mfs_error_t	mfs_flash_write (MFSDriver mfsp, flash_offset_t offset, size_t n, const uint8_t wp)
	Flash write. More...

static mfs_error_t	mfs_flash_copy (MFSDriver *mfsp, flash_offset_t doffset, flash_offset_t soffset, uint32_t n)
	Flash copy. More...

static mfs_error_t	mfs_bank_erase (MFSDriver *mfsp, mfs_bank_t bank)
	Erases and verifies all sectors belonging to a bank. More...

static mfs_error_t	mfs_bank_verify_erase (MFSDriver *mfsp, mfs_bank_t bank)
	Erases and verifies all sectors belonging to a bank. More...

static mfs_error_t	mfs_bank_write_header (MFSDriver *mfsp, mfs_bank_t bank, uint32_t cnt)
	Writes the validation header in a bank. More...

static mfs_bank_state_t	mfs_bank_check_header (MFSDriver *mfsp)
	Checks integrity of the header in the shared buffer. More...

static mfs_error_t	mfs_bank_scan_records (MFSDriver mfsp, mfs_bank_t bank, bool wflagp)
	Scans blocks searching for records. More...

static mfs_error_t	mfs_bank_get_state (MFSDriver mfsp, mfs_bank_t bank, mfs_bank_state_t statep, uint32_t *cntp)
	Determines the state of a bank. More...

static mfs_error_t	mfs_garbage_collect (MFSDriver *mfsp)
	Enforces a garbage collection. More...

static mfs_error_t	mfs_try_mount (MFSDriver *mfsp)
	Performs a flash partition mount attempt. More...

mfs_error_t	mfs_mount (MFSDriver *mfsp)
	Configures and activates a MFS driver. More...

void	mfsObjectInit (MFSDriver *mfsp)
	Initializes an instance. More...

mfs_error_t	mfsStart (MFSDriver mfsp, const MFSConfig config)
	Configures and activates a MFS driver. More...

void	mfsStop (MFSDriver *mfsp)
	Deactivates a MFS driver. More...

mfs_error_t	mfsErase (MFSDriver *mfsp)
	Destroys the state of the managed storage by erasing the flash. More...

mfs_error_t	mfsReadRecord (MFSDriver mfsp, mfs_id_t id, size_t np, uint8_t *buffer)
	Retrieves and reads a data record. More...

mfs_error_t	mfsWriteRecord (MFSDriver mfsp, mfs_id_t id, size_t n, const uint8_t buffer)
	Creates or updates a data record. More...

mfs_error_t	mfsEraseRecord (MFSDriver *mfsp, mfs_id_t id)
	Erases a data record. More...

mfs_error_t	mfsPerformGarbageCollection (MFSDriver *mfsp)
	Enforces a garbage collection operation. More...

mfs_error_t	mfsStartTransaction (MFSDriver *mfsp, size_t size)
	Puts the driver in transaction mode. More...

mfs_error_t	mfsCommitTransaction (MFSDriver *mfsp)
	A transaction is committed and finalized atomically. More...

mfs_error_t	mfsRollbackTransaction (MFSDriver *mfsp)
	A transaction is rolled back atomically. More...

Enumerations

Macro Definition Documentation

#define ALIGNED_REC_SIZE ( n ) (flash_offset_t)MFS_ALIGN_NEXT(sizeof (mfs_data_header_t) + (size_t)(n))

Data record size aligned.

Definition at line 50 of file hal_mfs.c.

Referenced by mfs_bank_scan_records(), mfs_garbage_collect(), mfs_try_mount(), mfsCommitTransaction(), mfsEraseRecord(), and mfsWriteRecord().

#define ALIGNED_DHDR_SIZE ALIGNED_REC_SIZE(0)

Data record header size aligned.

Definition at line 56 of file hal_mfs.c.

Referenced by mfs_bank_scan_records(), mfsEraseRecord(), mfsStartTransaction(), and mfsWriteRecord().

#define ALIGNED_SIZEOF ( t ) (((sizeof (t) - 1U) | MFS_ALIGN_MASK) + 1U)

Aligned size of a type.

Definition at line 62 of file hal_mfs.c.

Referenced by mfs_bank_scan_records(), mfs_garbage_collect(), and mfs_try_mount().

#define PAIR	(	a,
		b
	)	(((unsigned)(a) << 2U) \| (unsigned)(b))

Combines two values (0..3) in one (0..15).

Definition at line 68 of file hal_mfs.c.

Referenced by mfs_try_mount().

#define RET_ON_ERROR ( err )

Value:

do {                                              \
  mfs_error_t e = (err);                                                    \
  if (e != MFS_NO_ERROR) {                                                  \
    return e;                                                               \
  }                                                                         \
} while (false)

Error check helper.

Definition at line 73 of file hal_mfs.c.

Referenced by mfs_bank_get_state(), mfs_bank_scan_records(), mfs_flash_copy(), mfs_flash_write(), mfs_garbage_collect(), mfs_try_mount(), mfsCommitTransaction(), mfsErase(), mfsEraseRecord(), mfsReadRecord(), mfsStartTransaction(), and mfsWriteRecord().

#define MFS_CFG_MAX_RECORDS 32

Maximum number of indexed records in the managed storage.

Note: Record indexes go from 1 to MFS_CFG_MAX_RECORDS.

Definition at line 55 of file hal_mfs.h.

Referenced by mfs_bank_scan_records(), mfs_garbage_collect(), mfs_try_mount(), mfsEraseRecord(), mfsReadRecord(), and mfsWriteRecord().

#define MFS_CFG_MAX_REPAIR_ATTEMPTS 3

Maximum number of repair attempts on partition mount.

Definition at line 62 of file hal_mfs.h.

Referenced by mfs_mount().

#define MFS_CFG_WRITE_VERIFY TRUE

Verify written data.

Definition at line 69 of file hal_mfs.h.

#define MFS_CFG_STRONG_CHECKING TRUE

Enables a stronger and slower check procedure on mount.

Strong checking requires reading of the whole written data and this can be slow, normal checking only checks integrity of metadata, data errors would be detected on read.

Definition at line 79 of file hal_mfs.h.

#define MFS_CFG_BUFFER_SIZE 32

Size of the buffer used for data copying.

Note: The buffer size must be a power of two and not smaller than 16 bytes.; Larger buffers improve performance, buffers with size multiple of the flash program page size work better.

Definition at line 90 of file hal_mfs.h.

Referenced by mfs_bank_scan_records(), mfs_flash_copy(), and mfs_flash_write().

#define MFS_CFG_MEMORY_ALIGNMENT 2

Enforced memory alignment.

This value must be a power of two, it enforces a memory alignment for records in the flash array. This is required when alignment constraints exist, for example when using a DTR mode on OSPI devices.

Definition at line 101 of file hal_mfs.h.

#define MFS_CFG_TRANSACTION_MAX 16

Maximum number of objects writable in a single transaction.

Definition at line 108 of file hal_mfs.h.

Referenced by mfsEraseRecord(), and mfsWriteRecord().

Typedef Documentation

typedef uint32_t mfs_id_t

Type of a record identifier.

Definition at line 202 of file hal_mfs.h.

Enumeration Type Documentation

enum mfs_bank_t

Type of a flash bank.

Definition at line 154 of file hal_mfs.h.

enum mfs_state_t

Type of driver state machine states.

Definition at line 162 of file hal_mfs.h.

enum mfs_error_t

Type of an MFS error code.

Note: Errors are negative integers, informative warnings are positive integers.

Definition at line 175 of file hal_mfs.h.

enum mfs_bank_state_t

Type of a bank state assessment.

Definition at line 193 of file hal_mfs.h.

Function Documentation

static mfs_error_t mfs_flash_read	(	MFSDriver *	mfsp,
		flash_offset_t	offset,
		size_t	n,
		uint8_t *	rp
	)

static

Flash read.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	offset	flash offset
[in]	n	number of bytes to be read
[out]	rp	pointer to the data buffer

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 172 of file hal_mfs.c.

References MFSDriver::config, MFSConfig::flashp, flashRead, and MFSDriver::state.

Referenced by mfs_bank_get_state(), mfs_bank_scan_records(), mfs_flash_copy(), mfs_flash_write(), mfs_try_mount(), and mfsReadRecord().

static mfs_error_t mfs_flash_write	(	MFSDriver *	mfsp,
		flash_offset_t	offset,
		size_t	n,
		const uint8_t *	wp
	)

static

Flash write.

Note: If the option MFS_CFG_WRITE_VERIFY is enabled then the flash is also read back for verification.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	offset	flash offset
[in]	n	number of bytes to be written
[in]	wp	pointer to the data buffer

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 198 of file hal_mfs.c.

References MFSDriver::buffer, MFSDriver::config, MFSConfig::flashp, flashProgram, MFS_CFG_BUFFER_SIZE, mfs_flash_read(), RET_ON_ERROR, and MFSDriver::state.

Referenced by mfs_bank_write_header(), mfs_flash_copy(), mfsCommitTransaction(), mfsEraseRecord(), and mfsWriteRecord().

Here is the call graph for this function:

static mfs_error_t mfs_flash_copy	(	MFSDriver *	mfsp,
		flash_offset_t	doffset,
		flash_offset_t	soffset,
		uint32_t	n
	)

static

Flash copy.

Note: If the option MFS_CFG_WRITE_VERIFY is enabled then the flash is also read back for verification.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	doffset	destination flash offset
[in]	soffset	source flash offset
[in]	n	number of bytes to be copied

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 243 of file hal_mfs.c.

References MFSDriver::buffer, MFS_CFG_BUFFER_SIZE, mfs_flash_read(), mfs_flash_write(), and RET_ON_ERROR.

Referenced by mfs_garbage_collect().

Here is the call graph for this function:

static mfs_error_t mfs_bank_erase	(	MFSDriver *	mfsp,
		mfs_bank_t	bank
	)

static

Erases and verifies all sectors belonging to a bank.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	bank	bank to be erased

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 279 of file hal_mfs.c.

References MFSConfig::bank0_sectors, MFSConfig::bank0_start, MFSConfig::bank1_sectors, MFSConfig::bank1_start, MFSDriver::config, MFSConfig::flashp, flashStartEraseSector, flashVerifyErase, flashWaitErase(), and MFSDriver::state.

Referenced by mfs_garbage_collect(), mfs_try_mount(), and mfsErase().

Here is the call graph for this function:

static mfs_error_t mfs_bank_verify_erase	(	MFSDriver *	mfsp,
		mfs_bank_t	bank
	)

static

Erases and verifies all sectors belonging to a bank.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	bank	bank to be verified

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 325 of file hal_mfs.c.

References MFSConfig::bank0_sectors, MFSConfig::bank0_start, MFSConfig::bank1_sectors, MFSConfig::bank1_start, MFSDriver::config, MFSConfig::flashp, flashVerifyErase, and MFSDriver::state.

Referenced by mfs_bank_get_state().

static mfs_error_t mfs_bank_write_header	(	MFSDriver *	mfsp,
		mfs_bank_t	bank,
		uint32_t	cnt
	)

static

Writes the validation header in a bank.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	bank	bank to be validated
[in]	cnt	value for the flash usage counter

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 365 of file hal_mfs.c.

References MFSConfig::bank0_start, MFSConfig::bank1_start, MFSDriver::config, mfs_bank_header_t::counter, mfs_bank_header_t::crc, MFSConfig::erased, flashGetSectorOffset(), MFSConfig::flashp, mfs_bank_header_t::magic1, mfs_bank_header_t::magic2, mfs_flash_write(), and mfs_bank_header_t::reserved1.

Referenced by mfs_garbage_collect(), and mfs_try_mount().

Here is the call graph for this function:

static mfs_bank_state_t mfs_bank_check_header ( MFSDriver * mfsp )

static

Checks integrity of the header in the shared buffer.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The header state.

Function Class:Not an API, this function is for internal use only.

Definition at line 399 of file hal_mfs.c.

References MFSDriver::buffer, MFSDriver::config, mfs_bank_header_t::counter, mfs_bank_header_t::crc, MFSConfig::erased, mfs_bank_header_t::magic1, mfs_bank_header_t::magic2, and mfs_bank_header_t::reserved1.

Referenced by mfs_bank_get_state(), and mfs_try_mount().

static mfs_error_t mfs_bank_scan_records	(	MFSDriver *	mfsp,
		mfs_bank_t	bank,
		bool *	wflagp
	)

static

Scans blocks searching for records.

Note: The block integrity is strongly checked.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	bank	the bank identifier
[out]	wflagp	warning flag on anomalies

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 439 of file hal_mfs.c.

References ALIGNED_DHDR_SIZE, ALIGNED_REC_SIZE, ALIGNED_SIZEOF, MFSConfig::bank_size, MFSDriver::buffer, MFSDriver::config, MFSDriver::descriptors, MFSConfig::erased, MFS_CFG_BUFFER_SIZE, MFS_CFG_MAX_RECORDS, mfs_flash_read(), MFSDriver::next_offset, and RET_ON_ERROR.

Referenced by mfs_try_mount().

Here is the call graph for this function:

static mfs_error_t mfs_bank_get_state	(	MFSDriver *	mfsp,
		mfs_bank_t	bank,
		mfs_bank_state_t *	statep,
		uint32_t *	cntp
	)

static

Determines the state of a bank.

Note: This function does not test the bank integrity by scanning the data area, it just checks the header.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	bank	bank to be checked
[out]	statep	bank state, it can be: MFS_BANK_ERASED MFS_BANK_GARBAGE MFS_BANK_OK
[out]	cntp	bank counter

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 549 of file hal_mfs.c.

References MFSDriver::buffer, mfs_bank_header_t::counter, mfs_bank_check_header(), mfs_bank_verify_erase(), mfs_flash_read(), and RET_ON_ERROR.

Referenced by mfs_try_mount().

Here is the call graph for this function:

static mfs_error_t mfs_garbage_collect ( MFSDriver * mfsp )

static

Enforces a garbage collection.

Storage data is compacted into a single bank.

Parameters

[out] mfsp pointer to the MFSDriver object

Returns: The operation status.

Function Class:Not an API, this function is for internal use only.

Definition at line 587 of file hal_mfs.c.

References ALIGNED_REC_SIZE, ALIGNED_SIZEOF, MFSDriver::current_bank, MFSDriver::current_counter, MFSDriver::descriptors, mfs_bank_erase(), mfs_bank_write_header(), MFS_CFG_MAX_RECORDS, mfs_flash_copy(), MFSDriver::next_offset, and RET_ON_ERROR.

Referenced by mfs_try_mount(), mfsEraseRecord(), mfsPerformGarbageCollection(), mfsRollbackTransaction(), mfsStartTransaction(), and mfsWriteRecord().

Here is the call graph for this function:

static mfs_error_t mfs_try_mount ( MFSDriver * mfsp )

static

Performs a flash partition mount attempt.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The operation status.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 638 of file hal_mfs.c.

References ALIGNED_REC_SIZE, ALIGNED_SIZEOF, MFSDriver::buffer, mfs_bank_header_t::counter, MFSDriver::current_bank, MFSDriver::current_counter, MFSDriver::descriptors, mfs_bank_check_header(), mfs_bank_erase(), mfs_bank_get_state(), mfs_bank_scan_records(), mfs_bank_write_header(), MFS_CFG_MAX_RECORDS, mfs_flash_read(), mfs_garbage_collect(), PAIR, RET_ON_ERROR, and MFSDriver::used_space.

Referenced by mfs_mount().

Here is the call graph for this function:

mfs_error_t mfs_mount ( MFSDriver * mfsp )

Configures and activates a MFS driver.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_WARN_GC	if the operation triggered a garbage collection.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 785 of file hal_mfs.c.

References MFS_CFG_MAX_REPAIR_ATTEMPTS, mfs_try_mount(), and MFSDriver::state.

Referenced by mfsErase(), and mfsStart().

Here is the call graph for this function:

void mfsObjectInit ( MFSDriver * mfsp )

Initializes an instance.

Parameters

[out] mfsp pointer to the MFSDriver object

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 824 of file hal_mfs.c.

References MFSDriver::config, osalDbgCheck, and MFSDriver::state.

mfs_error_t mfsStart	(	MFSDriver *	mfsp,
		const MFSConfig *	config
	)

Configures and activates a MFS driver.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	config	pointer to the configuration

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been completed.
MFS_WARN_GC	if the operation triggered a garbage collection.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 849 of file hal_mfs.c.

References MFSDriver::config, mfs_mount(), osalDbgAssert, osalDbgCheck, and MFSDriver::state.

Here is the call graph for this function:

void mfsStop ( MFSDriver * mfsp )

Deactivates a MFS driver.

Parameters

[in] mfsp pointer to the MFSDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 868 of file hal_mfs.c.

References MFSDriver::config, osalDbgAssert, osalDbgCheck, and MFSDriver::state.

mfs_error_t mfsErase ( MFSDriver * mfsp )

Destroys the state of the managed storage by erasing the flash.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The operation status.

Return values

MFS_ERR_INV_STATE	if the driver is in not in `MFS_READY` state.
MFS_NO_ERROR	if the operation has been successfully completed.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 894 of file hal_mfs.c.

References mfs_bank_erase(), mfs_mount(), osalDbgCheck, RET_ON_ERROR, and MFSDriver::state.

Here is the call graph for this function:

mfs_error_t mfsReadRecord	(	MFSDriver *	mfsp,
		mfs_id_t	id,
		size_t *	np,
		uint8_t *	buffer
	)

Retrieves and reads a data record.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	id	record numeric identifier, the valid range is between `1` and `MFS_CFG_MAX_RECORDS`
[in,out]	np	on input is the maximum buffer size, on return it is the size of the data copied into the buffer
[out]	buffer	pointer to a buffer for record data

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_READY` state.
MFS_ERR_INV_SIZE	if the passed buffer is not large enough to contain the record data.
MFS_ERR_NOT_FOUND	if the specified id does not exists.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 932 of file hal_mfs.c.

References MFSDriver::buffer, mfs_data_header_t::crc, MFSDriver::descriptors, MFS_CFG_MAX_RECORDS, mfs_flash_read(), osalDbgCheck, RET_ON_ERROR, and MFSDriver::state.

Here is the call graph for this function:

mfs_error_t mfsWriteRecord	(	MFSDriver *	mfsp,
		mfs_id_t	id,
		size_t	n,
		const uint8_t *	buffer
	)

Creates or updates a data record.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	id	record numeric identifier, the valid range is between `1` and `MFS_CFG_MAX_RECORDS`
[in]	n	size of data to be written, it cannot be zero
[in]	buffer	pointer to a buffer for record data

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_WARN_GC	if the operation triggered a garbage collection.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_READY` state.
MFS_ERR_OUT_OF_MEM	if there is not enough flash space for the operation.
MFS_ERR_TRANSACTION_NUM	if the transaction operations buffer space has been exceeded.
MFS_ERR_TRANSACTION_SIZE	if the transaction allocated space has been exceeded.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1005 of file hal_mfs.c.

References ALIGNED_DHDR_SIZE, ALIGNED_REC_SIZE, MFSConfig::bank_size, MFSDriver::buffer, MFSDriver::config, mfs_data_header_t::crc, MFSDriver::current_bank, MFSDriver::descriptors, mfs_data_header_t::id, mfs_transaction_op_t::id, mfs_data_header_t::magic1, mfs_data_header_t::magic2, MFS_CFG_MAX_RECORDS, MFS_CFG_TRANSACTION_MAX, mfs_flash_write(), mfs_garbage_collect(), MFSDriver::next_offset, mfs_transaction_op_t::offset, osalDbgCheck, RET_ON_ERROR, mfs_data_header_t::size, mfs_transaction_op_t::size, MFSDriver::state, MFSDriver::tr_limit_offet, MFSDriver::tr_next_offset, MFSDriver::tr_nops, MFSDriver::tr_ops, and MFSDriver::used_space.

Here is the call graph for this function:

mfs_error_t mfsEraseRecord	(	MFSDriver *	mfsp,
		mfs_id_t	id
	)

Erases a data record.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	id	record numeric identifier, the valid range is between `1` and `MFS_CFG_MAX_RECORDS`

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_WARN_GC	if the operation triggered a garbage collection.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_READY` state.
MFS_ERR_OUT_OF_MEM	if there is not enough flash space for the operation.
MFS_ERR_TRANSACTION_NUM	if the transaction operations buffer space has been exceeded.
MFS_ERR_TRANSACTION_SIZE	if the transaction allocated space has been exceeded.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1154 of file hal_mfs.c.

References ALIGNED_DHDR_SIZE, ALIGNED_REC_SIZE, MFSConfig::bank_size, MFSDriver::buffer, MFSDriver::config, mfs_data_header_t::crc, MFSDriver::current_bank, MFSDriver::descriptors, mfs_data_header_t::id, mfs_transaction_op_t::id, mfs_data_header_t::magic1, mfs_data_header_t::magic2, MFS_CFG_MAX_RECORDS, MFS_CFG_TRANSACTION_MAX, mfs_flash_write(), mfs_garbage_collect(), MFSDriver::next_offset, mfs_transaction_op_t::offset, osalDbgCheck, RET_ON_ERROR, mfs_data_header_t::size, mfs_transaction_op_t::size, MFSDriver::state, MFSDriver::tr_limit_offet, MFSDriver::tr_next_offset, MFSDriver::tr_nops, MFSDriver::tr_ops, and MFSDriver::used_space.

Here is the call graph for this function:

mfs_error_t mfsPerformGarbageCollection ( MFSDriver * mfsp )

Enforces a garbage collection operation.

Garbage collection involves: integrity check, optionally repairs, obsolete data removal, data compaction and a flash bank swap.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_READY` state.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1278 of file hal_mfs.c.

References mfs_garbage_collect(), osalDbgCheck, and MFSDriver::state.

Here is the call graph for this function:

mfs_error_t mfsStartTransaction	(	MFSDriver *	mfsp,
		size_t	size
	)

Puts the driver in transaction mode.

Note

The parameters n and size are used to make an estimation of the space required for the transaction to succeed. Note that the estimated size must include also the extra space required by alignment enforcement option. If the estimated size is wrong (by defect) what could happen is that there is a failure in the middle of a transaction and a roll-back would be required.

The conditions for starting a transaction are:

The driver must be started.
There must be enough compacted storage to accommodate the whole transaction. If the required space is available but it is not compacted then a garbage collect operation is performed.

Parameters

[in]	mfsp	pointer to the `MFSDriver` object
[in]	size	estimated total size of written records in transaction, this includes, data, headers and alignment gaps

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_READY` state.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1320 of file hal_mfs.c.

References ALIGNED_DHDR_SIZE, MFSConfig::bank_size, MFSDriver::config, MFSDriver::current_bank, mfs_garbage_collect(), MFSDriver::next_offset, osalDbgCheck, RET_ON_ERROR, MFSDriver::state, MFSDriver::tr_limit_offet, MFSDriver::tr_next_offset, MFSDriver::tr_nops, and MFSDriver::used_space.

Here is the call graph for this function:

mfs_error_t mfsCommitTransaction ( MFSDriver * mfsp )

A transaction is committed and finalized atomically.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_TRANSACTION` state.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1376 of file hal_mfs.c.

References ALIGNED_REC_SIZE, MFSDriver::buffer, MFSDriver::descriptors, mfs_transaction_op_t::id, mfs_data_header_t::magic1, mfs_data_header_t::magic2, mfs_flash_write(), MFSDriver::next_offset, mfs_transaction_op_t::offset, osalDbgCheck, RET_ON_ERROR, mfs_transaction_op_t::size, MFSDriver::state, MFSDriver::tr_next_offset, MFSDriver::tr_nops, MFSDriver::tr_ops, and MFSDriver::used_space.

Here is the call graph for this function:

mfs_error_t mfsRollbackTransaction ( MFSDriver * mfsp )

A transaction is rolled back atomically.

This function performs a garbage collection in order to discard all written data that has not been finalized.

Parameters

[in] mfsp pointer to the MFSDriver object

Returns: The operation status.

Return values

MFS_NO_ERROR	if the operation has been successfully completed.
MFS_ERR_INV_STATE	if the driver is in not in `MFS_TRANSACTION` state.
MFS_ERR_FLASH_FAILURE	if the flash memory is unusable because HW failures. Makes the driver enter the `MFS_ERROR` state.
MFS_ERR_INTERNAL	if an internal logic failure is detected.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 1457 of file hal_mfs.c.

References mfs_garbage_collect(), osalDbgCheck, MFSDriver::state, and MFSDriver::tr_nops.

Here is the call graph for this function:

Detailed Description

Macros

Configuration options

Error codes handling macros

Alignment macros

Typedefs

Data Structures

Functions

Enumerations

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation