wms_memory_area.h File Reference

Detailed Description

This library gives read, write and erase access to User defined or Application memory areas. The areas can be located in internal flash or on an external flash chipset. See document WP-RM-131 - Wirepas Mesh bootloader development guide for more information about bootloader external flash support.

Library services are accessed via lib_memory_area handle.

Definition in file wms_memory_area.h.

Go to the source code of this file.

Typedefs
typedef uint32_t	app_lib_mem_area_id_t
	Memory Area id definition. More...
typedef app_lib_mem_area_res_e(*	app_lib_mem_area_startRead_f) (app_lib_mem_area_id_t id, void *to, uint32_t from, size_t amount)
	Block read from a memory area. More...
typedef app_lib_mem_area_res_e(*	app_lib_mem_area_startWrite_f) (app_lib_mem_area_id_t id, uint32_t to, const void *from, size_t amount)
	Block write to a memory area. More...
typedef app_lib_mem_area_res_e(*	app_lib_mem_area_startErase_f) (app_lib_mem_area_id_t id, uint32_t *sector_base, size_t *number_of_sector)
	Erase one or multiple sectors in the memory area. More...
typedef bool(*	app_lib_mem_area_isBusy_f) (app_lib_mem_area_id_t id)
	Checks if underlying flash driver is busy. More...
typedef app_lib_mem_area_res_e(*	app_lib_mem_area_getAreaInfo_f) (app_lib_mem_area_id_t id, app_lib_mem_area_info_t *info)
	Fills a structure with info about memory area and flash timings and topology. More...
typedef void(*	app_lib_mem_area_getAreaList_f) (app_lib_mem_area_id_t *list, uint8_t *num_areas)
	Returns the list of areas defined in the bootloader and accessible from the application. More...

Data Structures
struct	app_lib_mem_area_flash_info_t
	Information on flash peripheral. More...
struct	app_lib_mem_area_info_t
	memory area information More...
struct	app_lib_memory_area_t
	List of library functions. More...

Enumerations
enum	app_lib_mem_area_res_e {   APP_LIB_MEM_AREA_RES_OK = 0, APP_LIB_MEM_AREA_RES_ERROR = 1, APP_LIB_MEM_AREA_RES_BUSY = 2, APP_LIB_MEM_AREA_RES_NODRIVER = 3,   APP_LIB_MEM_AREA_RES_PARAM = 4, APP_LIB_MEM_AREA_RES_INVALID_AREA = 5 }
	memory area operations result More...
enum	app_lib_mem_area_type_e { APP_LIB_MEM_AREA_TYPE_APPLICATION = 0, APP_LIB_MEM_AREA_TYPE_USER = 1 }
	Lists the types of areas accessible from application side. More...

Macros
#define	APP_LIB_MEMORY_AREA_NAME   0x01fd3b49
	Library symbolic name More...
#define	APP_LIB_MEMORY_AREA_VERSION   0x200
	Maximum supported library version. More...
#define	APP_LIB_MEM_AREA_MAX_AREAS   8
	Maximum number of areas that can defined in the bootloader. More...

Typedef Documentation

app_lib_mem_area_getAreaInfo_f

typedef app_lib_mem_area_res_e(* app_lib_mem_area_getAreaInfo_f) (app_lib_mem_area_id_t id, app_lib_mem_area_info_t *info)

Fills a structure with info about memory area and flash timings and topology.

Parameters

id	Id of the memory area to get info from.
info	pointer to an app_lib_mem_area_info_t structure.

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful. See app_lib_mem_area_res_e for other result codes.

Definition at line 236 of file wms_memory_area.h.

app_lib_mem_area_getAreaList_f

typedef void(* app_lib_mem_area_getAreaList_f) (app_lib_mem_area_id_t *list, uint8_t *num_areas)

Returns the list of areas defined in the bootloader and accessible from the application.

Parameters

list	pointer to an array of areas.
num_areas	In: size of the array list. Out: number of defined areas.

Returns

none

Definition at line 249 of file wms_memory_area.h.

app_lib_mem_area_id_t

typedef uint32_t app_lib_mem_area_id_t

Memory Area id definition.

Definition at line 61 of file wms_memory_area.h.

app_lib_mem_area_isBusy_f

typedef bool(* app_lib_mem_area_isBusy_f) (app_lib_mem_area_id_t id)

Checks if underlying flash driver is busy.

Parameters

id	Id of the memory area to check.

Returns

true: driver is busy, false otherwise.

Definition at line 223 of file wms_memory_area.h.

app_lib_mem_area_startErase_f

typedef app_lib_mem_area_res_e(* app_lib_mem_area_startErase_f) (app_lib_mem_area_id_t id, uint32_t *sector_base, size_t *number_of_sector)

Erase one or multiple sectors in the memory area.

Erasing is asynchronous and lib_memory_area->isBusy() must be checked for operation completion.

Parameters

id	Id of the memory area to erase to.
sector_base	pointer to the base address of the sector to be erased. If the flash driver cannot erase all requested sector, return the base address of the next sector to be erased.
number_of_sector	Pointer to number of sector to erase. Returns the number of remaining sector to erase.

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful. See app_lib_mem_area_res_e for other result codes.

Definition at line 212 of file wms_memory_area.h.

app_lib_mem_area_startRead_f

typedef app_lib_mem_area_res_e(* app_lib_mem_area_startRead_f) (app_lib_mem_area_id_t id, void *to, uint32_t from, size_t amount)

Block read from a memory area.

Reading is asynchronous and lib_memory_area->isBusy() must be checked for operation completion.

Parameters

id	Id of the memory area to read from.
to	Pointer in RAM to store read data.
from	Address in memory area to read data from.
amount	Number of bytes to read.

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful. See app_lib_mem_area_res_e for other result codes.

Definition at line 159 of file wms_memory_area.h.

app_lib_mem_area_startWrite_f

typedef app_lib_mem_area_res_e(* app_lib_mem_area_startWrite_f) (app_lib_mem_area_id_t id, uint32_t to, const void *from, size_t amount)

Block write to a memory area.

Writing to a flash memory takes time (5ms typical for a page). The call to the function must be asynchronous, meaning that the write to the memory area is accepted and will succeed but MAY not be finished. lib_memory_area->isBusy() must be used to check if the write operation has terminated.

Parameters

id	Id of the memory area to write to.
to	Address in memory area to write data to.
from	Pointer in RAM to the data to be written.
amount	Number of bytes to write.

Note

Depending on flash chipset 1 byte write are not possible. Parameters to and amount must be aligned on write_alignement field of app_lib_mem_area_flash_info_t.

Returns

Result code, APP_LIB_MEM_AREA_RES_OK if successful. See app_lib_mem_area_res_e for other result codes.

Definition at line 188 of file wms_memory_area.h.

---

Data Structure Documentation

app_lib_mem_area_flash_info_t

struct app_lib_mem_area_flash_info_t

Information on flash peripheral.

The structure containing flash topology and timings returned by the lib_memory_area->getAreaInfo() function

Definition at line 83 of file wms_memory_area.h.

Data Fields
uint32_t	byte_write_call_time	Time taken by lib_memory_area->startWrite() call for one byte in useconds
uint32_t	byte_write_time	Time taken by the Flash chipset to write one byte in uS. Note For internal flash driver write (erase) time is 0. Due to hardware limitation the driver is fully synchronous so the write (erase) to flash is finished when lib_memory_area->startWrite() (lib_memory_area->startErase()) returns.
size_t	erase_sector_size	Size of an erase sector
uint32_t	is_busy_call_time	Time taken by lib_memory_area->isBusy() call in useconds
uint32_t	page_write_call_time	Time taken by lib_memory_area->startWrite() call for one page in useconds
uint32_t	page_write_time	Time taken by the Flash chipset write one page in useconds
uint32_t	sector_erase_call_time	Time taken by lib_memory_area->startErase() call for one sector in useconds
uint32_t	sector_erase_time	Time taken by the Flash chipset to erase on sector in useconds
size_t	write_alignment	Minimum write alignment supported by the flash hardware. Write address must be aligned on write_alignment and write amount must be a multiple of write_alignment bytes.
size_t	write_page_size	Size of a write page

app_lib_mem_area_info_t

struct app_lib_mem_area_info_t

memory area information

The structure containing memory area information returned by the lib_memory_area->getAreaInfo() function

Definition at line 126 of file wms_memory_area.h.

Data Fields
app_lib_mem_area_id_t	area_id	Id of the area
size_t	area_size	Size in bytes of the area
bool	external_flash	true if area is located in external flash
app_lib_mem_area_flash_info_t	flash	Description of the flash memory where the area is located
app_lib_mem_area_type_e	type	Type of memory area

app_lib_memory_area_t

struct app_lib_memory_area_t

List of library functions.

Definition at line 255 of file wms_memory_area.h.

Data Fields
app_lib_mem_area_getAreaInfo_f	getAreaInfo
app_lib_mem_area_getAreaList_f	getAreaList
app_lib_mem_area_isBusy_f	isBusy
app_lib_mem_area_startErase_f	startErase
app_lib_mem_area_startRead_f	startRead
app_lib_mem_area_startWrite_f	startWrite

Enumeration Type Documentation

app_lib_mem_area_res_e

enum app_lib_mem_area_res_e

memory area operations result

Enumerator
APP_LIB_MEM_AREA_RES_OK	Operation is successful
APP_LIB_MEM_AREA_RES_ERROR	Error during operation. Mostly bus communication (I2C/SPI) error, or external flash chipset is not responding.
APP_LIB_MEM_AREA_RES_BUSY	Underneath flash driver is busy
APP_LIB_MEM_AREA_RES_NODRIVER	There is no external flash driver implemented in the bootloader.
APP_LIB_MEM_AREA_RES_PARAM	Invalid parameters
APP_LIB_MEM_AREA_RES_INVALID_AREA	Area doesn't exist

Definition at line 36 of file wms_memory_area.h.

{
    APP_LIB_MEM_AREA_RES_OK        = 0,
    APP_LIB_MEM_AREA_RES_ERROR     = 1,
    APP_LIB_MEM_AREA_RES_BUSY      = 2,
    APP_LIB_MEM_AREA_RES_NODRIVER  = 3,
    APP_LIB_MEM_AREA_RES_PARAM     = 4,
    APP_LIB_MEM_AREA_RES_INVALID_AREA  = 5,
} app_lib_mem_area_res_e;

app_lib_mem_area_type_e

enum app_lib_mem_area_type_e

Lists the types of areas accessible from application side.

Used when querying type of the memory area with service lib_memory_area->getAreaInfo().

Enumerator
APP_LIB_MEM_AREA_TYPE_APPLICATION	Application area
APP_LIB_MEM_AREA_TYPE_USER	User defined area

Definition at line 69 of file wms_memory_area.h.

{
    APP_LIB_MEM_AREA_TYPE_APPLICATION = 0,
    APP_LIB_MEM_AREA_TYPE_USER        = 1,
} app_lib_mem_area_type_e;

Macro Definition Documentation

APP_LIB_MEM_AREA_MAX_AREAS

#define APP_LIB_MEM_AREA_MAX_AREAS   8

Maximum number of areas that can defined in the bootloader.

Used as a absolute maximum value for app_lib_mem_area_id_t.

Definition at line 58 of file wms_memory_area.h.

APP_LIB_MEMORY_AREA_NAME

#define APP_LIB_MEMORY_AREA_NAME   0x01fd3b49

Library symbolic name

Definition at line 30 of file wms_memory_area.h.

APP_LIB_MEMORY_AREA_VERSION

#define APP_LIB_MEMORY_AREA_VERSION   0x200

Maximum supported library version.

Definition at line 33 of file wms_memory_area.h.