Microchip® Advanced Software Framework

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]bufThe pointer to uint8_t size buffer to calculate crc
[in]lenThe 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_instanceInitialized PDS environment structure,
Return values
PDS_SUCCESSPDS Compact operation successfully completed.
forother 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_instanceInitialized PDS environment structure,
[in]item_id16-bit item Identifier
Returns
Status of the PDS Delete procedure
Return values
PDS_SUCCESSPDS Item id found and deleted successfully
forother 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_instanceInitialized PDS environment structure,
Return values
PDS_SUCCESSPDS sector's and contents are erased and initialized
forother 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_instanceInitialized PDS environment structure
Returns
Status of the PDS Initialize procedure
Return values
PDS_SUCCESSPDS Initialize procedure is completed
PDS_INIT_ERRORPDS initialization failed, due to inactive sector or NVM Init failures
forother 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_instanceInitialized PDS environment structure,
[in]item_id16-bit item Identifier
Returns
Status of the item existence in the active sector
Return values
PDS_SUCCESSPDS Item id found in the PDS
forother 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_instanceInitialized PDS environment structure,
[in]item_id16-bit item Identifier
[in]item_id_bufbuffer to store the item id that's matched
[in]lenmaximum 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_instanceInitialized PDS environment structure,
[in]item_id16-bit item Identifier
[out]bufbuffer to store the item values that's matched
[in]buf_lenmaximum length of the buffer to store the valid value
[out]read_sizeActual 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_SUCCESSPDS Item id found and item read success
forother 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_instanceInitialized PDS environment structure,
[in]item_id16-bit item Identifier
[in]bufbuffer to write the item values in to NVM
[in]lenitem buffer length
Returns
Status of the PDS Write procedure
Return values
PDS_SUCCESSPDS Item id and it's values are written successfully
forother 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().