hal_nv.h File Reference

Non-volatile memory API. More...

Detailed Description

Non-volatile memory API.

HAL non-volatile memory module.

Purpose

HALFRED Hardware Abstraction Layer

Version

Revision

1500

License

$License$

Copyright

$Copyright$

#include <stdbool.h>
#include "hal_config.h"
#include "hal_os.h"
#include "hal_bp.h"

Go to the source code of this file.

Data Structures
struct	NV_AddressMap_Tag
struct	NV_MemPeripheral_Tag
struct	NV_MemDevice_Tag
struct	NV_Memory_Tag

Macros
#define	NV_INIT_MEMORY(mem_map, phy_data, dev_ops)   { NULL, &(mem_map), (void*)(phy_data), &(dev_ops) }
#define	NV_INIT_MEMDEVICE(devs, no_devs)   { (devs), (no_devs), NULL, false, false, false }

Typedefs
typedef uint32_t	NV_Addressable
typedef uint32_t	NV_DevId
typedef struct NV_Memory_Tag *	NV_Memory
typedef struct NV_AddressMap_Tag	NV_AddressMap_T
typedef NV_AddressMap_T *	NV_AddressMap
typedef struct NV_MemPeripheral_Tag	NV_MemPeripheral_T
typedef NV_MemPeripheral_T *	NV_MemPeripheral
typedef struct NV_MemDevice_Tag	NV_MemDevice_T
typedef NV_MemDevice_T *	NV_MemDevice
typedef struct NV_Memory_Tag	NV_Memory_T

Enumerations
enum	NV_OpResult {   NVOP_OK, NVOP_IN_PROGRESS, NVOP_BAD_REQUEST, NVOP_NO_SEM_AVAIL,   NVOP_NO_BUF_AVAIL, NVOP_TOO_MANY_REQ, NVOP_DEVOP_RD_ERR, NVOP_DEVOP_WR_ERR,   NVOP_DEVOP_ER_ERR, NVOP_LOCKED }

Functions
void	NV_MemDeviceInit (NV_MemDevice mdev, uint8_t *buffer)
void	NV_MemDeviceDeInit (NV_MemDevice mdev)
NV_OpResult	NV_MemDeviceLock (NV_MemDevice mdev)
void	NV_MemDeviceUnlock (NV_MemDevice mdev)
NV_OpResult	NV_ReadSync (NV_Memory nv_mem, NV_Addressable addr, NV_Addressable size, void *dst)
NV_OpResult	NV_WriteSync (NV_Memory nv_mem, NV_Addressable addr, NV_Addressable size, const void *src)
NV_OpResult	NV_Erase (NV_Memory nv_mem)

Macro Definition Documentation

#define NV_INIT_MEMORY	(		mem_map,
			phy_data,
			dev_ops
	)		{ NULL, &(mem_map), (void*)(phy_data), &(dev_ops) }

Initializer ("constructor") for the the NvMemory object. It should be used as initializer in declaration of the NV_Memory_T object.

Parameters

mem_map	an NV_AddressMap_T object with definition of memory layout (for some devices its content is initialized automatically)
phy_data	a pointer to physical data associated with NV_Memory object (e.g. NV_AT45DB_PhyData)
dev_ops	an NV_MemPeripheral object with definitions of operations for given NV_Memory type of device

#define NV_INIT_MEMDEVICE	(		devs,
			no_devs
	)		{ (devs), (no_devs), NULL, false, false, false }

Initializer ("constructor") for the the NV_MemDevice object. It should be used as initializer in declaration of the NV_MemDevice_T object.

Parameters

devs	an array of pointers to NV_Memory objects
no_devs	length of the devs array

Typedef Documentation

typedef uint32_t NV_Addressable

Type for values used as addresses or offsets in the NV memory devices.

typedef uint32_t NV_DevId

Type for values used as device IDs.

typedef struct NV_AddressMap_Tag NV_AddressMap_T

Type for keeping the properties of the logical NV memory device. The properties are: start_addr: it is a base address used to access data on device end_addr: the end data address available in the device (the addressing between start_addr and end_addr is continous) write_len_unit: length of the physical write operation for described device

typedef NV_AddressMap_T* NV_AddressMap

Type for handle used to access the NVMemory objects.

typedef struct NV_MemPeripheral_Tag NV_MemPeripheral_T

Type for properties of the MemPeripheral object.

typedef NV_MemPeripheral_T* NV_MemPeripheral

Type for handle used to access the NVMemory objects.

typedef struct NV_MemDevice_Tag NV_MemDevice_T

Type for properties of the NV_MemDevice object.

typedef NV_MemDevice_T* NV_MemDevice

Type for handle used to access the NVMemory objects.

typedef struct NV_Memory_Tag NV_Memory_T

Type for properties of the NvMemory object.

Enumeration Type Documentation

enum NV_OpResult

Possible values returned by the API functions from this module.

Function Documentation

void NV_MemDeviceInit	(	NV_MemDevice	mdev,
		uint8_t *	buffer
	)

Initializes the NV_MemDevice object. This functions initializes memory device and associated NvMemory objects. In case when asynchronous operations are enabled then it also allocates request queue and semaphore pool objects. This function shall to be called before using any other API functions from this module.

Parameters

mdev	NV memory device handle
buffer	buffer used for physical operations, its size have to be large enough to keep the whole write unit for a given physical device (i.e. page size)
req_queue_len	length of the requests queue (only when asynchronous operations are enabled) - the request queue should be large enough to keep requests from all tasks using NV module, in case of asynchronous requests this parameter should be carefully tuned
sem_pool_len	size of the semaphore pool (only when asynchronous operations are enabled) - the semaphores from pool are used for handling synchronous requests, this pool should be large enough to allow as many as designed of the synchronous operations
bpool	buffer pool (only when asynchronous operations are enabled) - these buffers are used to keep asynchronous requests data (until is is serviced)

void NV_MemDeviceDeInit

(

NV_MemDevice

mdev

)

Deinitializes the NV_MemDevice object. After this function is called no further API calls will be allowed for given NV_MemDevice.

Parameters

mdev	a memory device handle

NV_OpResult NV_MemDeviceLock

(

NV_MemDevice

mdev

)

Temporary locks the NV_MemDevice object. All API functions called for locked object will immediately return with NVOP_LOCKED error code. To unlock device the NV_MemDeviceUnlock should be called.

Parameters

mdev	a memory device handle
flush	a flag to indicate if all operations should be finished before the device is locked (only when asynchronous operations are enabled)

Returns

NVOP_OK if there was no errors or NVOP_BAD_REQUEST if parameters are worng or NVOP_IN_PROGRESS if there is (physical) operation in progress (only if asynchronous operations are enabled )

void NV_MemDeviceUnlock

(

NV_MemDevice

mdev

)

Unlocks previously locked the NV_MemDevice object. If given object was not locked by the NV_MemDeviceLock function then no action is taken.

Parameters

mdev	a memory device handle

NV_OpResult NV_ReadSync	(	NV_Memory	nv_mem,
		NV_Addressable	addr,
		NV_Addressable	size,
		void *	dst
	)

This function synchronously reads data from the NV memory.

Parameters

nv_mem	a NV memory handle
addr	address to read from
size	the length of read operation
dst	the destination location for read data (its length should be at least "size" bytes)

Returns

status of the read operation

NV_OpResult NV_WriteSync	(	NV_Memory	nv_mem,
		NV_Addressable	addr,
		NV_Addressable	size,
		const void *	src
	)

This function synchronously writes data to the NV memory.

Parameters

nv_mem	a NV memory handle
addr	address to write to
size	the length of write operation
src	the source location for written data (its length should be at least "size" bytes)

Returns

status of the write operation

NV_OpResult NV_Erase

(

NV_Memory

nv_mem

)

This function synchronously erases the whole device. The value placed in the NV memory after the operation is dependent on attached physical device.

Parameters

nv_mem

a NV memory handle

Returns

status of the erase operation