ns_nvm_helper.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 /**
00020  * NanoStack NVM helper functions to read, write and delete key-value pairs to platform NVM.
00021  *
00022  * Client can use following methods:
00023  * -ns_nvm_data_write to write data to a key in platform NVM
00024  * -ns_nvm_data_read to read data from key in platform NVM
00025  * -ns_nvm_key_delete to delete a key from platform NVM
00026  *
00027  * If a API call returns NS_NVM_OK then a provided callback function will be called
00028  * and status argument indicates success or failure of the operation. If API call
00029  * returns error then callback will not be called.
00030  *
00031  * When client writes data this module will:
00032  * -initialize the NVM if not already initialized
00033  * -(re)create the key with a given size
00034  * -write data to the key
00035  * -flush data to the NVM
00036  *
00037  * When client reads data this module will:
00038  * -initialize the NVM if not initialized
00039  * -read data from the key
00040  *
00041  * When client deletes a key this module will:
00042  * -initialize the NVM if not initialized
00043  * -delete the key from NVM
00044  */
00045 
00046 /*
00047  * API function and callback function return statuses
00048  */
00049 #define NS_NVM_OK               0
00050 #define NS_NVM_DATA_NOT_FOUND   -1
00051 #define NS_NVM_ERROR            -2
00052 #define NS_NVM_MEMORY           -3
00053 
00054 /**
00055  *  callback type for NanoStack NVM
00056  */
00057 typedef void (ns_nvm_callback)(int status, void *context);
00058 
00059 /**
00060  * \brief Delete key from NVM
00061  *
00062  * \param callback function to be called when key deletion is ready
00063  * \param key_name Name of the key to be deleted from NVM
00064  * \param context argument will be provided as an argument when callback is called
00065  *
00066  * \return NS_NVM_OK if key deletion is in progress and callback will be called
00067  * \return NS_NVM_ERROR in error case, callback will not be called
00068  * \return provided callback function will be called with status indicating success or failure.
00069  */
00070 int ns_nvm_key_delete(ns_nvm_callback *callback, const char *key_name, void *context);
00071 
00072 /**
00073  * \brief Read data from NVM
00074  *
00075  * \param callback function to be called when data is read
00076  * \param key_name Name of the key whose data will be read
00077  * \param buf buffer where data will be stored
00078  * \param buf_len address of variable containing provided buffer length
00079  * \param context argument will be provided as an argument when callback is called
00080  *
00081  * \return NS_NVM_OK if read is in progress and callback will be called
00082  * \return NS_NVM_ERROR in error case, callback will not be called
00083  * \return provided callback function will be called with status indicating success or failure.
00084  */
00085 int ns_nvm_data_read(ns_nvm_callback *callback, const char *key_name, uint8_t *buf, uint16_t *buf_len, void *context);
00086 
00087 /**
00088  * \brief Write data to NVM
00089  *
00090  * \param callback function to be called when data writing is completed
00091  * \param key_name Name of the key whose data will be read
00092  * \param buf buffer where data will be stored
00093  * \param buf_len address of variable containing provided buffer length
00094  * \param context argument will be provided as an argument when callback is called
00095  *
00096  * \return NS_NVM_OK if read is in progress and callback will be called
00097  * \return NS_NVM_ERROR in error case, callback will not be called
00098  * \return provided callback function will be called with status indicating success or failure.
00099  */
00100 int ns_nvm_data_write(ns_nvm_callback *callback, const char *key_name, uint8_t *buf, uint16_t *buf_len, void *context);