EFL Driver

Generic Embedded Flash Driver. More...

Detailed Description

Generic Embedded Flash Driver.

This module implements a generic embedded flash driver.

Precondition

In order to use the EFL driver the HAL_USE_EFL option must be enabled in halconf.h.

Collaboration diagram for EFL Driver:

PLATFORM configuration options
#define	PLATFORM_EFL_USE_EFL1   FALSE
	EFL1 driver enable switch.

Data Structures
struct	EFlashDriverVMT
	EFlash virtual methods table. More...
struct	hal_efl_config
	Type of a structure representing a flash driver configuration. More...
struct	hal_efl_driver
	Structure representing an embedded flash driver. More...

Macros
#define	EFL_USE_MUTUAL_EXCLUSION   TRUE
	Enables the eflAcquireUse() and eflReleaseUse() APIs.
#define	_efl_flash_methods_alone
	EFlashDriver specific methods.
#define	_efl_flash_methods
	EFlashDriver specific methods with inherited ones.
#define	_efl_driver_data
	EFlashDriver specific data.
#define	efl_lld_driver_fields
	Low level fields of the embedded flash driver structure.
#define	efl_lld_config_fields
	Low level fields of the embedded flash configuration structure.

Typedefs
typedef struct hal_efl_driver	EFlashDriver
	Type of external flash driver class.
typedef struct hal_efl_config	EFlashConfig
	Type of a structure representing a flash driver configuration.

Functions
static flash_error_t	efl_acquire_exclusive (void *instance)
static flash_error_t	efl_release_exclusive (void *instance)
void	eflInit (void)
	Embedded Flash Driver initialization.
void	eflObjectInit (EFlashDriver *eflp)
	Initializes a generic EFlashDriver object.
msg_t	eflStart (EFlashDriver *eflp, const EFlashConfig *config)
	Configures and starts the driver.
void	eflStop (EFlashDriver *eflp)
	Stops the driver.
void	efl_lld_init (void)
	Low level Embedded Flash driver initialization.
void	efl_lld_start (EFlashDriver *eflp)
	Configures and activates the Embedded Flash peripheral.
void	efl_lld_stop (EFlashDriver *eflp)
	Deactivates the Embedded Flash peripheral.
const flash_descriptor_t *	efl_lld_get_descriptor (void *instance)
	Gets the flash descriptor structure.
flash_error_t	efl_lld_read (void *instance, flash_offset_t offset, size_t n, uint8_t *rp)
	Read operation.
flash_error_t	efl_lld_program (void *instance, flash_offset_t offset, size_t n, const uint8_t *pp)
	Program operation.
flash_error_t	efl_lld_start_erase_all (void *instance)
	Starts a whole-device erase operation.
flash_error_t	efl_lld_start_erase_sector (void *instance, flash_sector_t sector)
	Starts an sector erase operation.
flash_error_t	efl_lld_query_erase (void *instance, uint32_t *msec)
	Queries the driver for erase operation progress.
flash_error_t	efl_lld_verify_erase (void *instance, flash_sector_t sector)
	Returns the erase state of a sector.

Variables
static const struct EFlashDriverVMT	vmt
EFlashDriver	EFLD1
	EFL1 driver identifier.
static const flash_descriptor_t	efl_lld_descriptor

Macro Definition Documentation

EFL_USE_MUTUAL_EXCLUSION

#define EFL_USE_MUTUAL_EXCLUSION   TRUE

Enables the eflAcquireUse() and eflReleaseUse() APIs.

Note

Disabling this option saves both code and data space.

Definition at line 43 of file hal_efl.h.

_efl_flash_methods_alone

#define _efl_flash_methods_alone

EFlashDriver specific methods.

Definition at line 66 of file hal_efl.h.

_efl_flash_methods

#define _efl_flash_methods

Value:

  _base_flash_methods                                                       \
  _efl_flash_methods_alone

EFlashDriver specific methods with inherited ones.

Definition at line 71 of file hal_efl.h.

_efl_driver_data

#define _efl_driver_data

Value:

  _base_flash_data                                                          \
  /* Current configuration data.*/                                          \
  const EFlashConfig            *config;

EFlashDriver specific data.

Definition at line 78 of file hal_efl.h.

PLATFORM_EFL_USE_EFL1

#define PLATFORM_EFL_USE_EFL1   FALSE

EFL1 driver enable switch.

If set to TRUE the support for EFL1 is included.

Note

The default is FALSE.

Definition at line 48 of file hal_efl_lld.h.

efl_lld_driver_fields

#define efl_lld_driver_fields

Value:

  /* Dummy field, it is not needed.*/                                       \
  uint32_t                  dummy;

Low level fields of the embedded flash driver structure.

Definition at line 67 of file hal_efl_lld.h.

efl_lld_config_fields

#define efl_lld_config_fields

Value:

  /* Dummy configuration, it is not needed.*/                               \
  uint32_t                  dummy;

Low level fields of the embedded flash configuration structure.

Definition at line 74 of file hal_efl_lld.h.

Typedef Documentation

EFlashDriver

typedef struct hal_efl_driver EFlashDriver

Type of external flash driver class.

Definition at line 59 of file hal_efl.h.

EFlashConfig

typedef struct hal_efl_config EFlashConfig

Type of a structure representing a flash driver configuration.

Function Documentation

efl_acquire_exclusive()

flash_error_t efl_acquire_exclusive ( void * instance )

static

Definition at line 41 of file hal_efl.c.

References FLASH_ERROR_UNIMPLEMENTED, FLASH_NO_ERROR, hal_efl_driver::mutex, osalDbgAssert, and osalMutexLock().

Here is the call graph for this function:

efl_release_exclusive()

flash_error_t efl_release_exclusive ( void * instance )

static

Definition at line 54 of file hal_efl.c.

References FLASH_ERROR_UNIMPLEMENTED, FLASH_NO_ERROR, hal_efl_driver::mutex, osalDbgAssert, and osalMutexUnlock().

Here is the call graph for this function:

eflInit()

void eflInit

(

void

)

Embedded Flash Driver initialization.

Note

This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:

Object or module nitializer function.

Definition at line 95 of file hal_efl.c.

References efl_lld_init().

Referenced by halInit().

Here is the call graph for this function:

eflObjectInit()

void eflObjectInit

(

EFlashDriver *

eflp

)

Initializes a generic EFlashDriver object.

Parameters

[out]

eflp

pointer to a EFlashDriver structure

Function Class:

Object or module nitializer function.

Definition at line 107 of file hal_efl.c.

References FLASH_STOP, hal_efl_driver::mutex, osalMutexObjectInit(), hal_efl_driver::vmt, and vmt.

Referenced by efl_lld_init().

Here is the call graph for this function:

eflStart()

msg_t eflStart	(	EFlashDriver *	eflp,
		const EFlashConfig *	config )

Configures and starts the driver.

Parameters

[in]	eflp	pointer to a EFlashDriver structure
[in]	config	pointer to a configuration structure. If this parameter is set to NULL then a default configuration is used.

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 127 of file hal_efl.c.

References efl_lld_start(), FLASH_READY, FLASH_STOP, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

eflStop()

void eflStop

(

EFlashDriver *

eflp

)

Stops the driver.

Parameters

[in]

eflp

pointer to a EFlashDriver structure

Function Class:

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

Definition at line 165 of file hal_efl.c.

References efl_lld_stop(), FLASH_READY, FLASH_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

efl_lld_init()

void efl_lld_init

(

void

)

Low level Embedded Flash driver initialization.

Function Class:

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

Definition at line 78 of file hal_efl_lld.c.

References EFLD1, and eflObjectInit().

Referenced by eflInit().

Here is the call graph for this function:

efl_lld_start()

void efl_lld_start

(

EFlashDriver *

eflp

)

Configures and activates the Embedded Flash peripheral.

Parameters

[in]

eflp

pointer to a EFlashDriver structure

Function Class:

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

Definition at line 93 of file hal_efl_lld.c.

References EFLD1, and FLASH_STOP.

Referenced by eflStart().

efl_lld_stop()

void efl_lld_stop

(

EFlashDriver *

eflp

)

Deactivates the Embedded Flash peripheral.

Parameters

[in]

eflp

pointer to a EFlashDriver structure

Function Class:

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

Definition at line 114 of file hal_efl_lld.c.

References EFLD1, and FLASH_READY.

Referenced by eflStop().

efl_lld_get_descriptor()

const flash_descriptor_t * efl_lld_get_descriptor

(

void *

instance

)

Gets the flash descriptor structure.

Parameters

[in]

instance

pointer to a EFlashDriver instance

Returns

A flash device descriptor.

Function Class:

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

Definition at line 136 of file hal_efl_lld.c.

References efl_lld_descriptor.

efl_lld_read()

flash_error_t efl_lld_read	(	void *	instance,
		flash_offset_t	offset,
		size_t	n,
		uint8_t *	rp )

Read operation.

Parameters

[in]	instance	pointer to a EFlashDriver instance
[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:

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

Definition at line 158 of file hal_efl_lld.c.

References efl_lld_descriptor, FLASH_BUSY_ERASING, FLASH_ERASE, FLASH_NO_ERROR, FLASH_READ, FLASH_READY, osalDbgAssert, and osalDbgCheck.

efl_lld_program()

flash_error_t efl_lld_program	(	void *	instance,
		flash_offset_t	offset,
		size_t	n,
		const uint8_t *	pp )

Program operation.

Note

The device supports ECC, it is only possible to write erased pages once except when writing all zeroes.

Parameters

[in]	instance	pointer to a EFlashDriver instance
[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:

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

Definition at line 202 of file hal_efl_lld.c.

References efl_lld_descriptor, FLASH_BUSY_ERASING, FLASH_ERASE, FLASH_NO_ERROR, FLASH_PGM, FLASH_READY, osalDbgAssert, and osalDbgCheck.

efl_lld_start_erase_all()

flash_error_t efl_lld_start_erase_all

(

void *

instance

)

Starts a whole-device erase operation.

Note

This function only erases bank 2 if it is present. Bank 1 is not touched because it is where the program is running on. Pages on bank 1 can be individually erased.

Parameters

[in]

instance

pointer to a EFlashDriver instance

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:

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

Definition at line 243 of file hal_efl_lld.c.

References FLASH_BUSY_ERASING, FLASH_ERASE, FLASH_NO_ERROR, FLASH_READY, osalDbgAssert, and osalDbgCheck.

efl_lld_start_erase_sector()

flash_error_t efl_lld_start_erase_sector	(	void *	instance,
		flash_sector_t	sector )

Starts an sector erase operation.

Parameters

[in]	instance	pointer to a EFlashDriver instance
[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:

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

Definition at line 275 of file hal_efl_lld.c.

References efl_lld_descriptor, FLASH_BUSY_ERASING, FLASH_ERASE, FLASH_NO_ERROR, FLASH_READY, osalDbgAssert, and osalDbgCheck.

efl_lld_query_erase()

flash_error_t efl_lld_query_erase	(	void *	instance,
		uint32_t *	msec )

Queries the driver for erase operation progress.

Parameters

[in]	instance	pointer to a EFlashDriver instance
[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 312 of file hal_efl_lld.c.

References FLASH_ERASE, and FLASH_NO_ERROR.

efl_lld_verify_erase()

flash_error_t efl_lld_verify_erase	(	void *	instance,
		flash_sector_t	sector )

Returns the erase state of a sector.

Parameters

[in]	instance	pointer to a EFlashDriver instance
[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:

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

Definition at line 341 of file hal_efl_lld.c.

References efl_lld_descriptor, FLASH_BUSY_ERASING, FLASH_ERASE, FLASH_NO_ERROR, FLASH_READY, osalDbgAssert, and osalDbgCheck.

Variable Documentation

vmt

const struct EFlashDriverVMT vmt

static

Initial value:

= {
  (size_t)0,
  efl_lld_get_descriptor,
  efl_lld_read,
  efl_lld_program,
  efl_lld_start_erase_all,
  efl_lld_start_erase_sector,
  efl_lld_query_erase,
  efl_lld_verify_erase,
  efl_acquire_exclusive,
  efl_release_exclusive
}

Definition at line 71 of file hal_efl.c.

Referenced by __buffered_serial_objinit_impl(), __mx25_objinit_impl(), __n25q_objinit_impl(), __xsnor_objinit_impl(), bsaObjectInit(), bsioObjectInit(), eflObjectInit(), msObjectInit(), nullObjectInit(), sdObjectInit(), sduObjectInit(), and sioObjectInit().

EFLD1

EFlashDriver EFLD1

EFL1 driver identifier.

Definition at line 41 of file hal_efl_lld.c.

Referenced by efl_lld_init(), efl_lld_start(), and efl_lld_stop().

efl_lld_descriptor

const flash_descriptor_t efl_lld_descriptor

static

Initial value:

= {
 .attributes        = FLASH_ATTR_ERASED_IS_ONE |
                      FLASH_ATTR_MEMORY_MAPPED |
                      FLASH_ATTR_ECC_CAPABLE   |
                      FLASH_ATTR_ECC_ZERO_LINE_CAPABLE,
 .page_size         = 0,
 .sectors_count     = 0,
 .sectors           = NULL,
 .sectors_size      = 0,
 .address           = (uint8_t *)0,
 .size              = 0
}

Definition at line 48 of file hal_efl_lld.c.

Referenced by efl_lld_get_descriptor(), efl_lld_program(), efl_lld_read(), efl_lld_start_erase_sector(), and efl_lld_verify_erase().