net_nvm_api.h

00001 /*
00002  * Copyright (c) 2013-2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 /**
00018  * \file net_nvm_api.h
00019  * \brief Library PANA NVM API for Client and Server.
00020  *
00021  * \section server-api Server NVM API
00022  *
00023  *  - pana_server_nvm_callback_set(),  Initialize PANA server NVM functionality.
00024  *  - pana_server_restore_from_nvm(), Load PANA server base and security material from NVM.
00025  *  - pana_server_nvm_client_session_load(), Load client session from NVM.
00026  *
00027  * \section client-api Client NVM API
00028  *
00029  * nw_nvm.c use already this API and the application can just use net_nvm_api.h.
00030  *
00031  * - pana_client_nvm_callback_set(), Initialize PANA session NVM.
00032  *
00033  */
00034 #ifndef PANA_NVM_API_H_
00035 #define PANA_NVM_API_H_
00036 
00037 #include "ns_types.h"
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif
00042 
00043 
00044 /**
00045  * \brief Pana client and common data structure for get / Update callback's
00046  *
00047  * Client: [session address 16-bytes] + [session data 70-bytes] , Total 86 bytes
00048  *
00049  * Server: [offset 2-bytes] + [session address 16-bytes] + [session port 2-bytes] + [session id 4-bytes] + [session data 92-bytes], Total 116 bytes
00050  */
00051 
00052 /**
00053  * Size of Pana client session data without session address
00054  */
00055 #define PANA_CLIENT_NVM_SESSION_BUF_SIZE 70
00056 /**
00057  * Size of Pana client session data with session address
00058  */
00059 #define PANA_CLIENT_NVM_SESSION_BUF_SIZE_WITH_ADDRESS 86
00060 
00061 /**
00062  * Size of data for Server client Uodate and get callback
00063  *
00064  */
00065 #define PANA_SERVER_CLIENT_NVM_SESSION_BUF_SIZE 116
00066 
00067 /**
00068  * Size of data for Server material update and restore operation
00069  *
00070  */
00071 #define PANA_SERVER_MATERIAL_BUF_SIZE 90
00072 /*!
00073  * \enum pana_nvm_update_process_t
00074  * \brief PANA server NVM update states.
00075  */
00076 typedef enum pana_nvm_update_process_t {
00077     PANA_SERVER_MATERIAL_UPDATE,                /**< PANA server security material update. */
00078     PANA_SERVER_CLIENT_SESSION_UPDATE,          /**< PANA client session update. */
00079     PANA_SERVER_CLIENT_SESSION_REMOVE_UPDATE,   /**< PANA client session remove. */
00080 } pana_nvm_update_process_t;
00081 
00082 /*!
00083  * \enum pana_client_nvm_update_process_t
00084  * \brief PANA client NVM update states.
00085  */
00086 typedef enum pana_client_nvm_update_process_t {
00087     PANA_CLIENT_SESSION_UPDATE,          /**< PANA client session update. */
00088     PANA_CLIENT_SESSION_REMOVE,   /**< PANA client session remove. */
00089 } pana_client_nvm_update_process_t;
00090 
00091 /*!
00092  * \struct wpan_nvm_params_t
00093  * \brief Network nvm parameters.
00094  */
00095 typedef struct wpan_nvm_params {
00096     uint16_t pan_id;     /**< WPAN Pan-id.  */
00097     uint32_t mac_security_frame_counter; /**< Mac security counter. */
00098     uint32_t mle_securit_counter; /**< MLE security counter. */
00099 } wpan_nvm_params_t;
00100 
00101 /**
00102  * \brief NVM memory user callback for updated parameters
00103  *
00104  * \param parameters Updated wpan parameters
00105  */
00106 typedef void wpan_params_updated(wpan_nvm_params_t *parameters);
00107 
00108 /**
00109  * \brief NVM memory user for get parameter->pan_id network setup
00110  *
00111  * \param parameters Pointer for request parameters parameter->pan_id is configured for proper setup
00112  *
00113  * \return true when configure is loaded to buffer
00114  * \return false when there is no proper data for current wpan
00115  */
00116 typedef bool wpan_params_get(wpan_nvm_params_t *parameters);
00117 
00118 /**
00119  * \brief Pana client session update callback
00120  *
00121  * \param pan_id define which pan session is
00122  * \param process PANA_CLIENT_SESSION_UPDATE or PANA_CLIENT_SESSION_REMOVE
00123  */
00124 typedef void pana_client_session_update_cb(uint16_t pan_id, pana_client_nvm_update_process_t process);
00125 
00126 /**
00127  * \brief Pana client discover session from NVM user based on pan id
00128  *
00129  * \param pan_id define which pan session is
00130  *
00131  * \return true When Session is stored to behind given session buffer
00132  * \return false NVM can't detect session for given pan id
00133  */
00134 typedef bool pana_client_session_get_cb(uint16_t pan_id);
00135 
00136 /**
00137  * \brief Pana server call this when it create /Update / delete client session or update Server material
00138  *
00139  * \param operation Pana server NVM update
00140  *
00141  * \return session offset . Requirement for operation PANA_SERVER_CLIENT_SESSION_UPDATE
00142  */
00143 typedef uint16_t pana_server_update_cb(pana_nvm_update_process_t operation);
00144 
00145 /**
00146  * \brief Pana server call this when discover client session from NVM for given address
00147  *
00148  * \param linklocal_address Link local address for sesion
00149  *
00150  * \return true When Session is stored to behind given session buffer
00151  * \return false NVM can't detect session for given address
00152  */
00153 typedef bool pana_server_session_get_cb(uint8_t *linklocal_address);
00154 
00155 /**
00156  * \brief Pana server call this when discover client session from NVM for pana session
00157  *
00158  * \param session_id Pana session Id
00159  *
00160  * \return true When Session is stored to behind given session buffer
00161  * \return false NVM can't detect session for given session id
00162  */
00163 typedef bool pana_server_session_get_by_id_cb(uint32_t session_id);
00164 
00165 /* NVM API PART */
00166 /**
00167  * \brief PANA server NVM functionality initialization.
00168  *
00169  * \param update_cb A function pointer to NVM update process.
00170  * \param nvm_get A function pointer for discover session data from NVM by link local address
00171  * \param nvm_session_get A function pointer for discover session data from NVM by pana session id
00172  * \param nvm_static_buffer A pointer to application allocated static memory, minimum size PANA_SERVER_CLIENT_NVM_SESSION_BUF_SIZE (116 bytes).
00173  *
00174  *
00175  * \return 0, Init OK.
00176  * \return -1, Null parameter detect.
00177  *
00178  */
00179 extern int8_t pana_server_nvm_callback_set(pana_server_update_cb *update_cb, pana_server_session_get_cb *nvm_get, pana_server_session_get_by_id_cb *nvm_session_get, uint8_t *nvm_static_buffer);
00180 /**
00181  * \brief PANA server base restore from NVM.
00182  *
00183  * \param nvm_data A pointer to PANA server base data.
00184  * \param interface_id Interface ID.
00185  *
00186  * \return 0, Restore OK.
00187  * \return -1, Memory allocation fail.
00188  *
00189  */
00190 extern int8_t pana_server_restore_from_nvm(uint8_t *nvm_data, int8_t interface_id);
00191 /**
00192  * \brief PANA client session load from NVM API.
00193  *
00194  * \param nvm_pointer A pointer  PANA client session.
00195  *
00196  * \return 0, Restore OK.
00197  * \return -1, Memory allocation fail.
00198  *
00199  */
00200 extern int8_t pana_server_nvm_client_session_load(uint8_t *nvm_pointer);
00201 
00202 /**
00203  * \brief PANA client NVM functionality init.
00204  *
00205  * \param nvm_update A function pointer to NVM update process.
00206  * \param nvm_get A function pointer for discover session from NVM for given Pan-id
00207  * \param nvm_static_buffer A pointer to application allocated static memory, minimum size for session 86 bytes + 16-bit pan-id.
00208  *
00209  *
00210  * \return 0, Init OK.
00211  * \return -1, Null parameter detect.
00212  *
00213  */
00214 extern int8_t pana_client_nvm_callback_set(pana_client_session_update_cb *nvm_update, pana_client_session_get_cb *nvm_get, uint8_t *nvm_static_buffer);
00215 
00216 /**
00217  * \brief Clean node persistent data and all PANA client sessions from the stack.
00218  *
00219  * This function disables the network ID filter, sets EUID-16 to 0xffff and removes PANA client sessions. It is only for client purposes.
00220  *
00221  *
00222  * \return 0, Clean OK.
00223  * \return -1, Stack is active.
00224  *
00225  */
00226 extern int8_t net_nvm_data_clean(int8_t interface_id);
00227 
00228 /**
00229  * \brief Enable and init network NVM parameter automatic update.
00230  *
00231  * This function enables MAC and MLE protocol critical components update process to NVM memory user.
00232  *
00233  * \param interface_id Interface ID.
00234  * \param nvm_update_cb Function pointer for update NVM
00235  * \param nvm_get_cb Function for stack to request setup from NVM.
00236  *
00237  *
00238  * \return 0, Init OK.
00239  * \return -1, Unknown Interface.
00240  * \return -2, Memory allocation fail.
00241  *
00242  */
00243 extern int8_t net_nvm_wpan_params_storage_enable(int8_t interface_id, wpan_params_updated *nvm_update_cb, wpan_params_get *nvm_get_cb);
00244 
00245 /**
00246  * \brief Reset stored WPAN parameter's at interface .
00247  *
00248  * This function clean state at WPAN params at stack. Force Request from NVM
00249  *
00250  *\param interface_id Interface ID.
00251  *
00252  * \return 0, reset OK.
00253  * \return -1, Unknown Interface.
00254  *
00255  */
00256 extern int8_t net_nvm_wpan_params_storage_reset(int8_t interface_id);
00257 
00258 
00259 /**
00260  * \brief Disable stored WPAN parameter's to interface .
00261  *
00262  *
00263  *\param interface_id Interface ID.
00264  *
00265  * \return 0, Disable OK.
00266  * \return -1, Unknown Interface.
00267  *
00268  */
00269 extern int8_t net_nvm_wpan_params_storage_disable(int8_t interface_id);
00270 
00271 
00272 #ifdef __cplusplus
00273 }
00274 #endif
00275 #endif /* PANA_NVM_API_H_ */