HAL Generic Flash Driver Interface. More...

Collaboration diagram for Generic Flash Interface:

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

Macros
#define	_base_flash_methods_alone
	`BaseFlash` specific methods. More...

#define	_base_flash_methods
	`BaseFlash` specific methods with inherited ones. More...

#define	_base_flash_data
	`BaseFlash` specific data. More...

Flash attributes
#define	FLASH_ATTR_ERASED_IS_ONE 0x00000001U
	Defines one as the erased bit state. More...

#define	FLASH_ATTR_MEMORY_MAPPED 0x00000002U
	The memory is accessible in a memory mapped mode. More...

#define	FLASH_ATTR_REWRITABLE 0x00000004U
	Programmed pages can be programmed again. More...

#define	FLASH_ATTR_ECC_CAPABLE 0x00000008U
	The memory is protected by an ECC mechanism. More...

#define	FLASH_ATTR_ECC_ZERO_LINE_CAPABLE 0x00000010U
	The device is able to overwrite zero to a line. More...

#define	FLASH_ATTR_SUSPEND_ERASE_CAPABLE 0x00000020U
	The device is able to suspend erase operations. More...

Macro Functions (BaseFlash)
#define	getBaseFlash(ip) ((BaseFlash *)&(ip)->vmt)
	Instance getter. More...

#define	flashGetDescriptor(ip) (ip)->vmt->get_descriptor(ip)
	Gets the flash descriptor structure. More...

#define	flashRead(ip, offset, n, rp) (ip)->vmt->read(ip, offset, n, rp)
	Read operation. More...

#define	flashProgram(ip, offset, n, pp) (ip)->vmt->program(ip, offset, n, pp)
	Program operation. More...

#define	flashStartEraseAll(ip) (ip)->vmt->start_erase_all(ip)
	Starts a whole-device erase operation. More...

#define	flashStartEraseSector(ip, sector) (ip)->vmt->start_erase_sector(ip, sector)
	Starts an sector erase operation. More...

#define	flashQueryErase(ip, msec) (ip)->vmt->query_erase(ip, msec)
	Queries the driver for erase operation progress. More...

#define	flashVerifyErase(ip, sector) (ip)->vmt->verify_erase(ip, sector)
	Returns the erase state of a sector. More...

Typedefs
typedef uint32_t	flash_offset_t
	Type of a flash offset. More...

typedef uint32_t	flash_sector_t
	Type of a flash sector number. More...

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

Functions
flash_error_t	flashWaitErase (BaseFlash *devp)
	Waits until the current erase operation is finished. More...

flash_offset_t	flashGetSectorOffset (BaseFlash *devp, flash_sector_t sector)
	Returns the offset of a sector. More...

uint32_t	flashGetSectorSize (BaseFlash *devp, flash_sector_t sector)
	Returns the size of a sector. More...

Enumerations
enum	flash_state_t
	Driver state machine possible states. More...

enum	flash_error_t
	Type of a flash error code. More...

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.

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

◆ 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 59 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 65 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 69 of file hal_flash.h.

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

BaseFlash specific methods.

Definition at line 176 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 197 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 211 of file hal_flash.h.

◆ getBaseFlash

#define getBaseFlash ( ip ) ((BaseFlash *)&(ip)->vmt)

Instance getter.

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

Definition at line 240 of file hal_flash.h.

◆ flashGetDescriptor

#define flashGetDescriptor ( ip ) (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 250 of file hal_flash.h.

◆ flashRead

#define flashRead	(	ip,
		offset,
		n,
		rp
	)	(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 268 of file hal_flash.h.

◆ flashProgram

#define flashProgram	(	ip,
		offset,
		n,
		pp
	)	(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 286 of file hal_flash.h.

◆ flashStartEraseAll

#define flashStartEraseAll ( ip ) (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 300 of file hal_flash.h.

◆ flashStartEraseSector

#define flashStartEraseSector	(	ip,
		sector
	)	(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 315 of file hal_flash.h.

◆ flashQueryErase

#define flashQueryErase	(	ip,
		msec
	)	(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 333 of file hal_flash.h.

◆ flashVerifyErase

#define flashVerifyErase	(	ip,
		sector
	)	(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 349 of file hal_flash.h.

Typedef Documentation

◆ flash_offset_t

typedef uint32_t flash_offset_t

Type of a flash offset.

Definition at line 113 of file hal_flash.h.

◆ flash_sector_t

typedef uint32_t flash_sector_t

Type of a flash sector number.

Definition at line 118 of file hal_flash.h.

Enumeration Type Documentation

◆ flash_state_t

enum flash_state_t

Driver state machine possible states.

Definition at line 87 of file hal_flash.h.

◆ flash_error_t

enum flash_error_t

Type of a flash error code.

Definition at line 99 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.

Definition at line 59 of file hal_flash.c.

References flashQueryErase.

◆ 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: the offset of the sector

Definition at line 84 of file hal_flash.c.

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

◆ 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: the size of the sector

Definition at line 109 of file hal_flash.c.

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

Detailed Description

Driver State Machine

Macros

Flash attributes

Macro Functions (BaseFlash)

Typedefs

Data Structures

Functions

Enumerations

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

Typedef Documentation

◆ flash_offset_t

◆ flash_sector_t

Enumeration Type Documentation

◆ flash_state_t

◆ flash_error_t

Function Documentation

◆ flashWaitErase()

◆ flashGetSectorOffset()

◆ flashGetSectorSize()