HAL Generic Flash Driver Interface. More...

Detailed Description

HAL Generic Flash Driver Interface.

Driver State Machine

The flash driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

Collaboration diagram for Generic Flash Interface:

Flash attributes
#define	FLASH_ATTR_ERASED_IS_ONE 0x00000001U
	Defines one as the erased bit state.
#define	FLASH_ATTR_MEMORY_MAPPED 0x00000002U
	The memory is accessible in a memory mapped mode.
#define	FLASH_ATTR_REWRITABLE 0x00000004U
	Programmed pages can be programmed again.
#define	FLASH_ATTR_ECC_CAPABLE 0x00000008U
	The memory is protected by an ECC mechanism.
#define	FLASH_ATTR_ECC_ZERO_LINE_CAPABLE 0x00000010U
	The device is able to overwrite zero to a line.
#define	FLASH_ATTR_SUSPEND_ERASE_CAPABLE 0x00000020U
	The device is able to suspend erase operations.

Macro Functions (BaseFlash)
#define	getBaseFlash(ip)
	Instance getter.
#define	flashGetDescriptor(ip)
	Gets the flash descriptor structure.
#define	flashRead(ip, offset, n, rp)
	Read operation.
#define	flashProgram(ip, offset, n, pp)
	Program operation.
#define	flashStartEraseAll(ip)
	Starts a whole-device erase operation.
#define	flashStartEraseSector(ip, sector)
	Starts an sector erase operation.
#define	flashQueryErase(ip, msec)
	Queries the driver for erase operation progress.
#define	flashVerifyErase(ip, sector)
	Returns the erase state of a sector.
#define	flashAcquireExclusive(ip)
	Acquires exclusive access to flash.
#define	flashReleaseExclusive(ip)
	Releases exclusive access to flash.

Data Structures
struct	flash_sector_descriptor_t
	Flash sector descriptor. More...
struct	flash_descriptor_t
	Type of a flash device descriptor. More...
struct	BaseFlashVMT
	`BaseFlash` virtual methods table. More...
struct	BaseFlash
	Base flash class. More...

Macros
#define	_base_flash_methods_alone
	`BaseFlash` specific methods.
#define	_base_flash_methods
	`BaseFlash` specific methods with inherited ones.
#define	_base_flash_data
	`BaseFlash` specific data.

Typedefs
typedef uint32_t	flash_offset_t
	Type of a flash offset.
typedef uint32_t	flash_sector_t
	Type of a flash sector number.

Enumerations
enum	flash_state_t { FLASH_UNINIT = 0 , FLASH_STOP = 1 , FLASH_READY = 2 , FLASH_READ = 3 , FLASH_PGM = 4 , FLASH_ERASE = 5 }
	Driver state machine possible states. More...
enum	flash_error_t { FLASH_NO_ERROR = 0 , FLASH_BUSY_ERASING = 1 , FLASH_ERROR_READ = 2 , FLASH_ERROR_PROGRAM = 3 , FLASH_ERROR_ERASE = 4 , FLASH_ERROR_VERIFY = 5 , FLASH_ERROR_HW_FAILURE = 6 , FLASH_ERROR_UNIMPLEMENTED = 7 }
	Type of a flash error code. More...

Functions
flash_error_t	flashWaitErase (BaseFlash *devp)
	Waits until the current erase operation is finished.
flash_offset_t	flashGetSectorOffset (BaseFlash *devp, flash_sector_t sector)
	Returns the offset of a sector.
uint32_t	flashGetSectorSize (BaseFlash *devp, flash_sector_t sector)
	Returns the size of a sector.
flash_sector_t	flashGetOffsetSector (BaseFlash *devp, flash_offset_t offset)
	Returns the sector of an offset.
void *	flashGetOffsetAddress (BaseFlash *devp, flash_offset_t offset)
	Get absolute address from offset.
flash_offset_t	flashGetAddressOffset (BaseFlash devp, void addr)
	Get offset from absolute address.

Macro Definition Documentation

◆ FLASH_ATTR_ERASED_IS_ONE

#define FLASH_ATTR_ERASED_IS_ONE 0x00000001U

Defines one as the erased bit state.

Definition at line 39 of file hal_flash.h.

Referenced by __mx25_objinit_impl(), and __n25q_objinit_impl().

◆ FLASH_ATTR_MEMORY_MAPPED

#define FLASH_ATTR_MEMORY_MAPPED 0x00000002U

The memory is accessible in a memory mapped mode.

Definition at line 43 of file hal_flash.h.

◆ FLASH_ATTR_REWRITABLE

#define FLASH_ATTR_REWRITABLE 0x00000004U

Programmed pages can be programmed again.

Note: This is incompatible and alternative to FLASH_ATTR_ECC_CAPABLE.

Definition at line 48 of file hal_flash.h.

Referenced by __mx25_objinit_impl(), and __n25q_objinit_impl().

◆ FLASH_ATTR_ECC_CAPABLE

#define FLASH_ATTR_ECC_CAPABLE 0x00000008U

The memory is protected by an ECC mechanism.

Note

This usually puts restrictions on the program operations.

Program operations can only happen at offsets aligned to write page boundaries.
The programmed data size must be a multiple of the write page size.
Programmed pages cannot be re-programmed.

Definition at line 58 of file hal_flash.h.

◆ FLASH_ATTR_ECC_ZERO_LINE_CAPABLE

#define FLASH_ATTR_ECC_ZERO_LINE_CAPABLE 0x00000010U

The device is able to overwrite zero to a line.

Note: This attribute is only meaningful for those devices that support ECC, so also FLASH_ATTR_ECC_CAPABLE must be specified.

Definition at line 64 of file hal_flash.h.

◆ FLASH_ATTR_SUSPEND_ERASE_CAPABLE

#define FLASH_ATTR_SUSPEND_ERASE_CAPABLE 0x00000020U

The device is able to suspend erase operations.

Definition at line 68 of file hal_flash.h.

Referenced by __mx25_objinit_impl(), and __n25q_objinit_impl().

◆ _base_flash_methods_alone

#define _base_flash_methods_alone

Value:

  /* Get flash device attributes.*/                                         \
  const flash_descriptor_t * (*get_descriptor)(void *instance);             \
  /* Read operation.*/                                                      \
  flash_error_t (*read)(void *instance, flash_offset_t offset,              \
                        size_t n, uint8_t *rp);                             \
  /* Program operation.*/                                                   \
  flash_error_t (*program)(void *instance, flash_offset_t offset,           \
                           size_t n, const uint8_t *pp);                    \
  /* Erase whole flash device.*/                                            \
  flash_error_t (*start_erase_all)(void *instance);                         \
  /* Erase single sector.*/                                                 \
  flash_error_t (*start_erase_sector)(void *instance,                       \
                                      flash_sector_t sector);               \
  flash_error_t (*query_erase)(void *instance, uint32_t *wait_time);        \
  /* Verify erase single sector.*/                                          \
  flash_error_t (*verify_erase)(void *instance, flash_sector_t sector);     \
  /* Acquire exclusive use of flash.*/                                      \
  flash_error_t (*acquire_exclusive)(void *instance);                       \
  /* Release exclusive use of flash.*/                                      \
  flash_error_t (*release_exclusive)(void *instance);

BaseFlash specific methods.

Definition at line 175 of file hal_flash.h.

◆ _base_flash_methods

#define _base_flash_methods

Value:

_base_object_methods \

_base_flash_methods_alone

BaseFlash specific methods with inherited ones.

Definition at line 200 of file hal_flash.h.

◆ _base_flash_data

#define _base_flash_data

Value:

  _base_object_data                                                         \
  /* Driver state.*/                                                        \
  flash_state_t         state;

BaseFlash specific data.

Definition at line 214 of file hal_flash.h.

◆ getBaseFlash

#define getBaseFlash ( ip )

Value:

((BaseFlash *)&(ip)->vmt)

vmt

static const struct EFlashDriverVMT vmt

Definition hal_efl.c:71

BaseFlash

Base flash class.

Definition hal_flash.h:224

Instance getter.

This special method is used to get the instance of this class object from a derived class.

Definition at line 243 of file hal_flash.h.

◆ flashGetDescriptor

#define flashGetDescriptor ( ip )

Value:

(ip)->vmt->get_descriptor(ip)

Gets the flash descriptor structure.

Parameters

[in] ip pointer to a BaseFlash or derived class

Returns: A flash device descriptor.

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

Definition at line 253 of file hal_flash.h.

Referenced by flashGetAddressOffset(), flashGetOffsetAddress(), flashGetOffsetSector(), flashGetSectorOffset(), and flashGetSectorSize().

◆ flashRead

#define flashRead	(	ip,
		offset,
		n,
		rp )

Value:

(ip)->vmt->read(ip, offset, n, rp)

Read operation.

Parameters

[in]	ip	pointer to a `BaseFlash` or derived class
[in]	offset	flash offset
[in]	n	number of bytes to be read
[out]	rp	pointer to the data buffer

Returns: An error code.

Return values

FLASH_NO_ERROR	if there is no erase operation in progress.
FLASH_BUSY_ERASING	if there is an erase operation in progress.
FLASH_ERROR_READ	if the read operation failed.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 271 of file hal_flash.h.

Referenced by mfs_flash_read().

◆ flashProgram

#define flashProgram	(	ip,
		offset,
		n,
		pp )

Value:

(ip)->vmt->program(ip, offset, n, pp)

Program operation.

Parameters

[in]	ip	pointer to a `BaseFlash` or derived class
[in]	offset	flash offset
[in]	n	number of bytes to be programmed
[in]	pp	pointer to the data buffer

Returns: An error code.

Return values

FLASH_NO_ERROR	if there is no erase operation in progress.
FLASH_BUSY_ERASING	if there is an erase operation in progress.
FLASH_ERROR_PROGRAM	if the program operation failed.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 289 of file hal_flash.h.

Referenced by mfs_flash_write().

◆ flashStartEraseAll

#define flashStartEraseAll ( ip )

Value:

(ip)->vmt->start_erase_all(ip)

Starts a whole-device erase operation.

Parameters

[in] ip pointer to a BaseFlash or derived class

Returns: An error code.

Return values

FLASH_NO_ERROR	if there is no erase operation in progress.
FLASH_BUSY_ERASING	if there is an erase operation in progress.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 303 of file hal_flash.h.

◆ flashStartEraseSector

#define flashStartEraseSector	(		ip,
			sector )

Value:

(ip)->vmt->start_erase_sector(ip, sector)

Starts an sector erase operation.

Parameters

[in]	ip	pointer to a `BaseFlash` or derived class
[in]	sector	sector to be erased

Returns: An error code.

Return values

FLASH_NO_ERROR	if there is no erase operation in progress.
FLASH_BUSY_ERASING	if there is an erase operation in progress.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 318 of file hal_flash.h.

Referenced by mfs_bank_erase().

◆ flashQueryErase

#define flashQueryErase	(		ip,
			msec )

Value:

(ip)->vmt->query_erase(ip, msec)

Queries the driver for erase operation progress.

Parameters

[in]	ip	pointer to a `BaseFlash` or derived class
[out]	msec	recommended time, in milliseconds, that should be spent before calling this function again, can be `NULL`

Returns: An error code.

Return values

FLASH_NO_ERROR	if there is no erase operation in progress.
FLASH_BUSY_ERASING	if there is an erase operation in progress.
FLASH_ERROR_ERASE	if the erase operation failed.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 336 of file hal_flash.h.

Referenced by flashWaitErase().

◆ flashVerifyErase

#define flashVerifyErase	(		ip,
			sector )

Value:

(ip)->vmt->verify_erase(ip, sector)

Returns the erase state of a sector.

Parameters

[in]	ip	pointer to a `BaseFlash` or derived class
[in]	sector	sector to be verified

Returns: An error code.

Return values

FLASH_NO_ERROR	if the sector is erased.
FLASH_BUSY_ERASING	if there is an erase operation in progress.
FLASH_ERROR_VERIFY	if the verify operation failed.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 352 of file hal_flash.h.

Referenced by mfs_bank_erase(), and mfs_bank_verify_erase().

◆ flashAcquireExclusive

#define flashAcquireExclusive ( ip )

Value:

(ip)->vmt->acquire_exclusive(ip)

Acquires exclusive access to flash.

Parameters

[in] ip pointer to a BaseFlash or derived class

Returns: An error code.

Return values

FLASH_NO_ERROR	if the access is obtained.
FLASH_ERROR_UNIMPLEMENTED	if exclusive access not enabled

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

Definition at line 364 of file hal_flash.h.

◆ flashReleaseExclusive

#define flashReleaseExclusive ( ip )

Value:

(ip)->vmt->release_exclusive(ip)

Releases exclusive access to flash.

Parameters

[in] ip pointer to a BaseFlash or derived class

Returns: An error code.

Return values

FLASH_NO_ERROR	if the access is released.
FLASH_ERROR_UNIMPLEMENTED	if exclusive access not enabled

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

Definition at line 376 of file hal_flash.h.

Typedef Documentation

◆ flash_offset_t

typedef uint32_t flash_offset_t

Type of a flash offset.

Definition at line 112 of file hal_flash.h.

◆ flash_sector_t

typedef uint32_t flash_sector_t

Type of a flash sector number.

Definition at line 117 of file hal_flash.h.

Enumeration Type Documentation

◆ flash_state_t

enum flash_state_t

Driver state machine possible states.

Enumerator
FLASH_UNINIT
FLASH_STOP
FLASH_READY
FLASH_READ
FLASH_PGM
FLASH_ERASE

Definition at line 86 of file hal_flash.h.

◆ flash_error_t

enum flash_error_t

Type of a flash error code.

Enumerator
FLASH_NO_ERROR
FLASH_BUSY_ERASING
FLASH_ERROR_READ
FLASH_ERROR_PROGRAM
FLASH_ERROR_ERASE
FLASH_ERROR_VERIFY
FLASH_ERROR_HW_FAILURE
FLASH_ERROR_UNIMPLEMENTED

Definition at line 98 of file hal_flash.h.

Function Documentation

◆ flashWaitErase()

flash_error_t flashWaitErase ( BaseFlash * devp )

Waits until the current erase operation is finished.

Parameters

[in] devp pointer to a BaseFlash object

Returns: An error code.

Return values

FLASH_NO_ERROR	if there is no erase operation in progress.
FLASH_ERROR_ERASE	if the erase operation failed.
FLASH_ERROR_HW_FAILURE	if access to the memory failed.

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

Definition at line 61 of file hal_flash.c.

References FLASH_BUSY_ERASING, flashQueryErase, and osalThreadSleepMilliseconds.

Referenced by mfs_bank_erase().

◆ flashGetSectorOffset()

flash_offset_t flashGetSectorOffset	(	BaseFlash *	devp,
		flash_sector_t	sector )

Returns the offset of a sector.

Parameters

[in]	devp	pointer to a `BaseFlash` object
[in]	sector	flash sector number

Returns: Sector offset.

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

Definition at line 87 of file hal_flash.c.

References flashGetDescriptor, flash_sector_descriptor_t::offset, osalDbgAssert, flash_descriptor_t::sectors, and flash_descriptor_t::sectors_size.

Referenced by mfs_bank_write_header(), and mfs_flash_get_bank_offset().

◆ flashGetSectorSize()

uint32_t flashGetSectorSize	(	BaseFlash *	devp,
		flash_sector_t	sector )

Returns the size of a sector.

Parameters

[in]	devp	pointer to a `BaseFlash` object
[in]	sector	flash sector number

Returns: Sector size.

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

Definition at line 113 of file hal_flash.c.

References flashGetDescriptor, osalDbgAssert, flash_descriptor_t::sectors, flash_descriptor_t::sectors_size, and flash_sector_descriptor_t::size.

◆ flashGetOffsetSector()

flash_sector_t flashGetOffsetSector	(	BaseFlash *	devp,
		flash_offset_t	offset )

Returns the sector of an offset.

Parameters

[in]	devp	pointer to a `BaseFlash` object
[in]	offset	flash offset

Returns: Flash sector.

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

Definition at line 139 of file hal_flash.c.

References FALSE, flashGetDescriptor, flash_sector_descriptor_t::offset, osalDbgAssert, flash_descriptor_t::sectors, flash_descriptor_t::sectors_count, flash_descriptor_t::sectors_size, and flash_sector_descriptor_t::size.

◆ flashGetOffsetAddress()

void * flashGetOffsetAddress	(	BaseFlash *	devp,
		flash_offset_t	offset )

Get absolute address from offset.

Parameters

[in]	devp	pointer to a `BaseFlash` object
[in]	offset	flash offset

Returns: A pointer to the offset.

Deprecated

Definition at line 176 of file hal_flash.c.

References flash_descriptor_t::address, flashGetDescriptor, and osalDbgAssert.

◆ flashGetAddressOffset()

flash_offset_t flashGetAddressOffset	(	BaseFlash *	devp,
		void *	addr )

Get offset from absolute address.

Parameters

[in]	devp	pointer to a `BaseFlash` object
[in]	addr	pointer

Returns: flash offset

Deprecated

Definition at line 193 of file hal_flash.c.

References flash_descriptor_t::address, flashGetDescriptor, osalDbgAssert, and flash_descriptor_t::size.

Detailed Description

Driver State Machine

Flash attributes

Macro Functions (BaseFlash)

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ FLASH_ATTR_ERASED_IS_ONE

◆ FLASH_ATTR_MEMORY_MAPPED

◆ FLASH_ATTR_REWRITABLE

◆ FLASH_ATTR_ECC_CAPABLE

◆ FLASH_ATTR_ECC_ZERO_LINE_CAPABLE

◆ FLASH_ATTR_SUSPEND_ERASE_CAPABLE

◆ _base_flash_methods_alone

◆ _base_flash_methods

◆ _base_flash_data

◆ getBaseFlash

◆ flashGetDescriptor

◆ flashRead

◆ flashProgram

◆ flashStartEraseAll

◆ flashStartEraseSector

◆ flashQueryErase

◆ flashVerifyErase

◆ flashAcquireExclusive

◆ flashReleaseExclusive

Typedef Documentation

◆ flash_offset_t

◆ flash_sector_t

Enumeration Type Documentation

◆ flash_state_t

◆ flash_error_t

Function Documentation

◆ flashWaitErase()

◆ flashGetSectorOffset()

◆ flashGetSectorSize()

◆ flashGetOffsetSector()

◆ flashGetOffsetAddress()

◆ flashGetAddressOffset()