Generic Flash Driver Interface

HAL Generic Flash Driver Interface. More...

Collaboration diagram for Generic Flash Driver 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   0x00000001
#define	FLASH_ATTR_MEMORY_MAPPED   0x00000002
#define	FLASH_ATTR_REWRITABLE   0x00000004
#define	FLASH_ATTR_READ_ECC_CAPABLE   0x00000008
#define	FLASH_ATTR_SUSPEND_ERASE_CAPABLE   0x00000010

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

Macro Definition Documentation

#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 142 of file hal_flash.h.

#define _base_flash_methods

Value:

_base_object_methods                                                      \
  _base_flash_methods_alone

BaseFlash specific methods with inherited ones.

Definition at line 163 of file hal_flash.h.

#define _base_flash_data

Value:

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

BaseFlash specific data.

Definition at line 177 of file hal_flash.h.

#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 206 of file hal_flash.h.

#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 216 of file hal_flash.h.

Referenced by flashGetSectorOffset(), and flashGetSectorSize().

#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 234 of file hal_flash.h.

Referenced by mfs_flash_read().

#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 252 of file hal_flash.h.

Referenced by mfs_flash_write().

#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 266 of file hal_flash.h.

#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 281 of file hal_flash.h.

Referenced by mfs_bank_erase().

#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 what 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 298 of file hal_flash.h.

Referenced by flashWaitErase().

#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 314 of file hal_flash.h.

Referenced by mfs_bank_erase(), and mfs_bank_verify_erase().

Typedef Documentation

typedef uint32_t flash_offset_t

Type of a flash offset.

Definition at line 83 of file hal_flash.h.

typedef uint32_t flash_sector_t

Type of a flash sector number.

Definition at line 88 of file hal_flash.h.

Enumeration Type Documentation

enum flash_state_t

Driver state machine possible states.

Definition at line 58 of file hal_flash.h.

enum flash_error_t

Type of a flash error code.

Definition at line 70 of file hal_flash.h.

Function Documentation

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, and osalThreadSleepMilliseconds.

Referenced by mfs_bank_erase().

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.

Referenced by mfs_bank_write_header().

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.