ble_sdk/services/pds/pds.h File Reference

This file for Persistent Data Storage management.

Copyright (c) 2017-2018 Microchip Technology Inc. and its subsidiaries.

#include "pds_nvm.h"

Functions
uint16_t	pds_calc_crc (uint8_t *buf, uint16_t len)
	Calculate crc of the given buffer. More...
pds_status_t	pds_compact_sector (pds_env_t *pds_instance)
	PDS Sector compact operation involves moving of valid item from one sector to another sector (new sector). More...
pds_status_t	pds_delete (pds_env_t *pds_instance, uint16_t item_id)
	Delete PDS item from active sector. More...
pds_status_t	pds_delete_all (pds_env_t *pds_instance)
	Delete all the PDS sector and initialize the sector's again. More...
pds_status_t	pds_init (pds_env_t *pds_instance)
	Initialize the PDS sectors and NVM memory controller. More...
pds_status_t	pds_item_exist (pds_env_t *pds_instance, uint16_t item_id)
	Check item id exists in the active sector. More...
uint16_t	pds_list_item (pds_env_t *pds_instance, uint16_t item_id, uint16_t *item_id_buf, uint16_t len)
	List PDS similar Major item ID's from active sector. More...
pds_status_t	pds_read (pds_env_t *pds_instance, uint16_t item_id, uint8_t *buf, uint16_t buf_len, uint16_t *read_size)
	Read the PDS item from active sector. More...
pds_status_t	pds_write (pds_env_t *pds_instance, uint16_t item_id, uint8_t *buf, uint16_t len)
	Write PDS item into active sector. More...

uint16_t pds_calc_crc	(	uint8_t *	buf,
		uint16_t	len
	)

Calculate crc of the given buffer.

Parameters

[in]	buf	The pointer to uint8_t size buffer to calculate crc
[in]	len	The length of the buffer

Returns

crc

References pbuf::len.

Referenced by pds_compact_sector(), pds_read(), and pds_write().

pds_status_t pds_compact_sector

(

pds_env_t *

pds_instance

)

PDS Sector compact operation involves moving of valid item from one sector to another sector (new sector).

This requires erase of new sector and writing new sector header and copying all the valid items into new sector one by one. Once the old sector items are copied into new sector, then new sector will be activated at the end of the compact operation.

Parameters

[in]

pds_instance

Initialized PDS environment structure,

Return values

PDS_SUCCESS	PDS Compact operation successfully completed.
for	other return values, check pds_status_t enum values

References active_sector, Assert, DBG_LOG, NULL, sector_header::number, PDS_BLOCK_ACTIVE_MASK, PDS_BLOCK_DELETE_MASK, pds_calc_crc(), PDS_COMPACT_FAILED, pds_init_status, PDS_INVALID_SECTOR, PDS_NEW_SECTOR_INITIALIZED, pds_nvm_erase(), pds_nvm_read(), pds_env::pds_nvm_start_address, pds_nvm_write(), pds_env::pds_sector_count, pds_env::pds_sector_size, PDS_SUCCESS, and sector_header::status.

Referenced by ble_store_bonding_info().

pds_status_t pds_delete	(	pds_env_t *	pds_instance,
		uint16_t	item_id
	)

Delete PDS item from active sector.

Scan the Item id from PDS active sector and if the item is valid, update the status deletion flag.

Parameters

[in]	pds_instance	Initialized PDS environment structure,
[in]	item_id	16-bit item Identifier

Returns

Status of the PDS Delete procedure

Return values

PDS_SUCCESS	PDS Item id found and deleted successfully
for	other return values, check pds_status_t enum values

References active_sector, Assert, NULL, PDS_BLOCK_DELETE_FLAG_Pos, pds_init_status, PDS_ITEM_NOT_FOUND, pds_nvm_read(), pds_env::pds_nvm_start_address, pds_nvm_write(), pds_env::pds_sector_size, and PDS_SUCCESS.

Referenced by ble_remove_bonding_info().

pds_status_t pds_delete_all

(

pds_env_t *

pds_instance

)

Delete all the PDS sector and initialize the sector's again.

Delete the PDS sectors and erase it's contents. Also initialize the PDS sector as the new device. The sector header number set to lowest valid value.

Parameters

[in]

pds_instance

Initialized PDS environment structure,

Return values

PDS_SUCCESS	PDS sector's and contents are erased and initialized
for	other return values, check pds_status_t enum values

References active_sector, Assert, sector_header::number, pds_init_status, pds_nvm_erase(), pds_env::pds_nvm_start_address, pds_nvm_write(), pds_env::pds_sector_count, pds_env::pds_sector_size, PDS_SUCCESS, sector_header::signature, and sector_header::status.

Referenced by pds_init().

pds_status_t pds_init

(

pds_env_t *

pds_instance

)

Initialize the PDS sectors and NVM memory controller.

If the device is new and not initialized, then need to initialize the sector by erasing the complete sector and writing the sector header. Also the sector header status is set to valid status, Initial sector number will be set to 1. If sector's are initialized then all sector's of the PDS must be scanned and the active sector is decided based on the higher value of the sector header number.

Parameters

[in]

pds_instance

Initialized PDS environment structure

Returns

Status of the PDS Initialize procedure

Return values

PDS_SUCCESS	PDS Initialize procedure is completed
PDS_INIT_ERROR	PDS initialization failed, due to inactive sector or NVM Init failures
for	other return values check pds_status_t enum values

References active_sector, Assert, DBG_LOG_DEV, NULL, sector_header::number, pds_delete_all(), PDS_INIT_ERROR, pds_init_status, PDS_INVALID_SECTOR, pds_nvm_init(), pds_nvm_read(), pds_env::pds_nvm_start_address, pds_env::pds_sector_count, pds_env::pds_sector_size, PDS_SUCCESS, sector_header::signature, and sector_header::status.

Referenced by pds_module_init().

pds_status_t pds_item_exist	(	pds_env_t *	pds_instance,
		uint16_t	item_id
	)

Check item id exists in the active sector.

Scan the Item id from PDS active sector and if the item is valid return the status as item found

Parameters

[in]	pds_instance	Initialized PDS environment structure,
[in]	item_id	16-bit item Identifier

Returns

Status of the item existence in the active sector

Return values

PDS_SUCCESS	PDS Item id found in the PDS
for	other return values, check pds_status_t enum values

References active_sector, Assert, NULL, PDS_BLOCK_ACTIVE_MASK, PDS_BLOCK_DELETE_MASK, pds_init_status, PDS_ITEM_NOT_FOUND, pds_nvm_read(), pds_env::pds_nvm_start_address, pds_env::pds_sector_size, and PDS_SUCCESS.

uint16_t pds_list_item	(	pds_env_t *	pds_instance,
		uint16_t	item_id,
		uint16_t *	item_id_buf,
		uint16_t	len
	)

List PDS similar Major item ID's from active sector.

Scan the major (MSB) Item id's from PDS active sector & ignore the minor id's (Sub ID or LSB of Item ID) and if the item is valid and matched copy the entire item id's into buffer and update the matched item counts

Parameters

[in]	pds_instance	Initialized PDS environment structure,
[in]	item_id	16-bit item Identifier
[in]	item_id_buf	buffer to store the item id that's matched
[in]	len	maximum length of the buffer to store the complete item id's

Returns

count return the number of matched major item id's. If no item id matches then it returns the count 0 or any error.

References active_sector, Assert, count, NULL, PDS_BLOCK_ACTIVE_MASK, PDS_BLOCK_DELETE_MASK, pds_init_status, pds_nvm_read(), pds_env::pds_nvm_start_address, pds_env::pds_sector_size, and PDS_SUCCESS.

Referenced by ble_remove_bonding_info(), ble_restore_bonding_info(), and ble_store_bonding_info().

pds_status_t pds_read	(	pds_env_t *	pds_instance,
		uint16_t	item_id,
		uint8_t *	buf,
		uint16_t	buf_len,
		uint16_t *	read_size
	)

Read the PDS item from active sector.

Read the item id value from the active sector. Which will scan the entire sector to find the valid block header of the item. If the item id in the block header matches, further it checks for non deletion and CRC matches.

Parameters

[in]	pds_instance	Initialized PDS environment structure,
[in]	item_id	16-bit item Identifier
[out]	buf	buffer to store the item values that's matched
[in]	buf_len	maximum length of the buffer to store the valid value
[out]	read_size	Actual valid size of the item read into buffer, This helps the application to retrieve and identify the variable size of similar item category. Where application can store variable size of data items into PDS and reduces wastage of PDS memory. The read size set 0 in case valid item not found. otherwise a valid item matched then the item size will be set to read_size referenced variable pointer.

Returns

Status of the PDS Read procedure

Return values

PDS_SUCCESS	PDS Item id found and item read success
for	other return values, check pds_status_t enum values

References active_sector, Assert, NULL, PDS_BLOCK_ACTIVE_MASK, PDS_BLOCK_DELETE_MASK, pds_calc_crc(), pds_init_status, PDS_ITEM_BIGGER_SIZE, PDS_ITEM_INVALID, PDS_ITEM_NOT_FOUND, pds_nvm_read(), pds_env::pds_nvm_start_address, pds_env::pds_sector_size, and PDS_SUCCESS.

Referenced by ble_restore_bonding_info().

pds_status_t pds_write	(	pds_env_t *	pds_instance,
		uint16_t	item_id,
		uint8_t *	buf,
		uint16_t	len
	)

Write PDS item into active sector.

Scan the empty space in active sector. If the empty space is found the item of the block header will be written with calculated CRC. once the item is written the block is activated.

Parameters

[in]	pds_instance	Initialized PDS environment structure,
[in]	item_id	16-bit item Identifier
[in]	buf	buffer to write the item values in to NVM
[in]	len	item buffer length

Returns

Status of the PDS Write procedure

Return values

PDS_SUCCESS	PDS Item id and it's values are written successfully
for	other return values, check pds_status_t enum values

References active_sector, Assert, block_header::checksum, block_header::id, block_header::item_size, pbuf::len, NULL, PDS_BLOCK_ACTIVE_FLAG_Pos, PDS_BLOCK_DELETE_FLAG_Pos, pds_calc_crc(), pds_init_status, PDS_ITEM_EXISTS, PDS_NVM_NO_MEMORY, pds_nvm_read(), pds_env::pds_nvm_start_address, pds_nvm_write(), PDS_SECTOR_ITEM_ERROR, pds_env::pds_sector_size, PDS_SUCCESS, and block_header::status.

Referenced by ble_store_bonding_info().