Lee Kai Xuan
/
mbed-os
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
mbed-os
by 
erkin yucel
Embed:
(wiki syntax)
Show/hide line numbers
configuration_store.h
Go to the documentation of this file.
00001 /* 00002 * mbed Microcontroller Library 00003 * Copyright (c) 2006-2016 ARM Limited 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 00019 /** @file configuration_store.h 00020 * 00021 * This is the interface file to configuration store. 00022 * 00023 * The following (referred to as [REFERENCE_1] in other parts of the documentation) 00024 * discusses synchronous/asynchronous completion of \ref ARM_CFSTORE_DRIVER methods 00025 * and the inter-relationship of 00026 * \ref ARM_CFSTORE_OPCODE and \ref ARM_CFSTORE_CALLBACK. 00027 * 00028 * Configuration Store driver dispatch methods can operate in 2 modes: 00029 00030 * - Synchronous (i.e. when 00031 * \ref ARM_CFSTORE_CAPABILITIES ::asynchronous_ops == 0) 00032 * then the \ref ARM_CFSTORE_DRIVER ::Dispatch_Method_Xxx() will return: 00033 * - >= 0 => CFSTORE Dispatch_Method_Xxx() completed successfully 00034 * - otherwise CFSTORE Dispatch_Method_Xxx() did not complete successfully 00035 * (return code supplies further details). 00036 * 00037 * In synchronous mode it is optional as to whether the client registers 00038 * a client callback with the Initialize() method. If one is registered, it 00039 * will be called to indicate the synchronous completion status. 00040 * 00041 * - Asynchronous (i.e. when 00042 * \ref ARM_CFSTORE_CAPABILITIES ::asynchronous_ops == 1) 00043 * then the \ref ARM_CFSTORE_DRIVER ::Dispatch_Method_Xxx() will return: 00044 * - return_value = ARM_DRIVER_OK (i.e. ==0) implies CFSTORE 00045 * Dispatch_Method_Xxx() transaction pending. Dispatch_Method_Xxx() 00046 * completion status will be indicated via 00047 * an asynchronous call to \ref ARM_CFSTORE_CALLBACK registered with the 00048 * \ref ARM_CFSTORE_DRIVER ::(*Initialize)(), where the status supplied to 00049 * the callback will be the final status of the call. 00050 * - return_value > ARM_DRIVER_OK (i.e. > 0) implies CFSTORE Dispatch_Method_Xxx() completely 00051 * synchronously and successfully. The return_value has specific 00052 * meaning for the Dispatch_Method_Xxx() e.g. for the Read() method 00053 * return_value is the number of bytes read. 00054 * - otherwise return_value < 0 => CFSTORE Dispatch_Method_Xxx() 00055 * completed unsuccessfully (return code supplies further details). 00056 * 00057 * The client registered asynchronous callback method \ref ARM_CFSTORE_CALLBACK is 00058 * registered by the client using: 00059 * \ref ARM_CFSTORE_DRIVER ::(*Initialize)(\ref ARM_CFSTORE_CALLBACK callback, void* client_context) 00060 * See the (*Initialize) documentation for more details. 00061 * 00062 * The registered callback has the following prototype: 00063 * 00064 * typedef void (* \refARM_CFSTORE_CALLBACK)( 00065 * int32_t status, 00066 * \ref ARM_CFSTORE_OPCODE cmd_code, 00067 * void *client_context, 00068 * \ref ARM_CFSTORE_HANDLE handle); 00069 * 00070 * Before an asynchronous notification is received, a client can check on the 00071 * status of the call by calling \ref ARM_CFSTORE_DRIVER ::(*GetStatus)(). 00072 * 00073 */ 00074 00075 #ifndef __CONFIGURATION_STORE_H 00076 #define __CONFIGURATION_STORE_H 00077 00078 #ifdef __cplusplus 00079 extern "C" { 00080 #endif 00081 00082 #include <stdint.h> 00083 #include <string.h> /* requierd for memset() in ARM_CFSTORE_HANDLE_INIT() */ 00084 00085 #define DEVICE_STORAGE 1 /* enable storage */ 00086 /// @cond CFSTORE_DOXYGEN_DISABLE 00087 #include <Driver_Storage.h> 00088 #include <Driver_Common.h> 00089 00090 #define ARM_CFSTORE_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1,0) /* API version */ 00091 #define ARM_CFSTORE_DRV_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(0,1) /* DRV version */ 00092 00093 /* CFSTORE Specific error codes*/ 00094 #define ARM_CFSTORE_DRIVER_ERROR_UNINITIALISED -1000 /* Start of driver specific errors */ 00095 #define ARM_CFSTORE_DRIVER_ERROR_PREEXISTING_KEY -1001 00096 #define ARM_CFSTORE_DRIVER_ERROR_KEY_NOT_FOUND -1002 00097 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_HANDLE -1003 00098 #define ARM_CFSTORE_DRIVER_ERROR_OUT_OF_MEMORY -1004 00099 #define ARM_CFSTORE_DRIVER_ERROR_PREEXISTING_KEY_DELETING -1005 00100 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_HANDLE_BUF -1006 00101 #define ARM_CFSTORE_DRIVER_ERROR_INTERNAL -1007 00102 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_KEY_NAME -1008 00103 #define ARM_CFSTORE_DRIVER_ERROR_VALUE_SIZE_TOO_LARGE -1009 00104 #define ARM_CFSTORE_DRIVER_ERROR_KEY_READ_ONLY -1010 00105 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_SEEK -1011 00106 #define ARM_CFSTORE_DRIVER_ERROR_KEY_UNREADABLE -1012 00107 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_WRITE_BUFFER -1013 00108 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_KEY_LEN -1014 00109 #define ARM_CFSTORE_DRIVER_ERROR_NOT_SUPPORTED -1015 00110 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_READ_BUFFER -1016 00111 #define ARM_CFSTORE_DRIVER_ERROR_INVALID_KEY_DESCRIPTOR -1017 00112 #define ARM_CFSTORE_DRIVER_ERROR_PERM_NO_READ_ACCESS -1018 00113 #define ARM_CFSTORE_DRIVER_ERROR_PERM_NO_WRITE_ACCESS -1019 00114 #define ARM_CFSTORE_DRIVER_ERROR_PERM_NO_EXECUTE_ACCESS -1020 00115 #define ARM_CFSTORE_DRIVER_ERROR_NO_PERMISSIONS -1021 00116 #define ARM_CFSTORE_DRIVER_ERROR_HANDLE_COUNT_MAX -1022 00117 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_ERROR -1023 00118 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_BUSY -1024 00119 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_TIMEOUT -1025 00120 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_UNSUPPORTED -1026 00121 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_PARAMETER -1027 00122 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_BOUNDED_CAPACITY -1028 00123 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_STORAGE_API_ERROR -1029 00124 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_STORAGE_IO_ERROR -1030 00125 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_NOT_INITIALIZED -1031 00126 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_ATTEMPTING_COMMIT_WITHOUT_WRITE -1032 00127 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_EMPTY -1033 00128 #define ARM_CFSTORE_DRIVER_ERROR_JOURNAL_STATUS_SMALL_LOG_REQUEST -1034 00129 #define ARM_CFSTORE_DRIVER_ERROR_OPERATION_PENDING -1035 00130 #define ARM_CFSTORE_DRIVER_ERROR_UVISOR_BOX_ID -1036 00131 #define ARM_CFSTORE_DRIVER_ERROR_UVISOR_NAMESPACE -1037 00132 /// @endcond 00133 00134 00135 /* Type Definitions */ 00136 typedef void *ARM_CFSTORE_HANDLE ; //!< opaque cfstore handle for manipulating cfstore data objects e.g. KV pairs. 00137 typedef size_t ARM_CFSTORE_SIZE; //!< CFSTORE type for size parameters. 00138 typedef size_t ARM_CFSTORE_OFFSET; //!< CFSTORE type for offset parameters. 00139 00140 /** @brief 00141 * 00142 * Status structure returned from the \ref ARM_CFSTORE_DRIVER (*GetStatus)() function. 00143 */ 00144 typedef struct _ARM_CFSTORE_STATUS { 00145 uint32_t in_progress : 1; //!< indicates a previous \ref ARM_CFSTORE_DRIVER ::Dispatch_Method_Xxx() 00146 //!< function is still in progress and will complete sometime in the future. 00147 uint32_t error : 1; //!< indicates a previous \ref ARM_CFSTORE_DRIVER ::Dispatch_Method_Xxx() 00148 //!< function is errored and will complete sometime in the future. 00149 } ARM_CFSTORE_STATUS; 00150 00151 /* Defines */ 00152 #define CFSTORE_KEY_NAME_MAX_LENGTH 220 //!< The maximum length of the null terminated character 00153 //!< string used as a key name string. 00154 #define CFSTORE_VALUE_SIZE_MAX (1<<26) //!< Max size of the KV value blob (currently 64MB) 00155 #define CFSTORE_HANDLE_BUFSIZE 24 //!< size of the buffer owned and supplied by client 00156 //!< to CFSTORE to hold internal data structures, referenced by the key handle. 00157 00158 /** @brief Helper macro to declare handle and client owned buffer supplied 00159 * to CFSTORE for storing opaque handle state 00160 */ 00161 #define ARM_CFSTORE_HANDLE_INIT(__name) \ 00162 uint8_t (__name##_buf_cFsToRe)[CFSTORE_HANDLE_BUFSIZE]; \ 00163 ARM_CFSTORE_HANDLE (__name) = (ARM_CFSTORE_HANDLE) (__name##_buf_cFsToRe); \ 00164 memset((__name##_buf_cFsToRe), 0, CFSTORE_HANDLE_BUFSIZE) 00165 00166 #if defined __MBED__ && defined TOOLCHAIN_GCC_ARM 00167 /** @brief Helper macro to swap 2 handles, which is useful for the Find() idiom. */ 00168 #define CFSTORE_HANDLE_SWAP(__a_HaNdLe, __b_HaNdLe) \ 00169 do{ ARM_CFSTORE_HANDLE __temp_HaNdLe = (__a_HaNdLe); \ 00170 __asm volatile("" ::: "memory"); \ 00171 (__a_HaNdLe) = (__b_HaNdLe); \ 00172 __asm volatile("" ::: "memory"); \ 00173 (__b_HaNdLe) = (__temp_HaNdLe); \ 00174 __asm volatile("" ::: "memory"); \ 00175 }while(0) 00176 #endif 00177 00178 #if defined __MBED__ && defined TOOLCHAIN_ARM 00179 /** @brief Helper macro to swap 2 handles, which is useful for the Find() idiom. */ 00180 #define CFSTORE_HANDLE_SWAP(__a_HaNdLe, __b_HaNdLe) \ 00181 do{ ARM_CFSTORE_HANDLE __temp_HaNdLe = (__a_HaNdLe); \ 00182 __dmb(0xf); \ 00183 (__a_HaNdLe) = (__b_HaNdLe); \ 00184 __dmb(0xf); \ 00185 (__b_HaNdLe) = (__temp_HaNdLe); \ 00186 __dmb(0xf); \ 00187 }while(0) 00188 #endif 00189 00190 #if defined __MBED__ && defined TOOLCHAIN_IAR 00191 /** @brief Helper macro to swap 2 handles, which is useful for the Find() idiom. */ 00192 /* note, memory barriers may be required in the following implementation */ 00193 #define CFSTORE_HANDLE_SWAP(__a_HaNdLe, __b_HaNdLe) \ 00194 do{ ARM_CFSTORE_HANDLE __temp_HaNdLe = (__a_HaNdLe); \ 00195 (__a_HaNdLe) = (__b_HaNdLe); \ 00196 (__b_HaNdLe) = (__temp_HaNdLe); \ 00197 }while(0) 00198 #endif 00199 00200 /** @brief The access control permissions for the key-value. */ 00201 typedef struct ARM_CFSTORE_ACCESS_CONTROL_LIST 00202 { 00203 uint32_t perm_owner_read : 1; //!< When set this KV is owner readable 00204 uint32_t perm_owner_write : 1; //!< When set this KV is owner writable. The owner should set this bit to be able delete the KV. 00205 uint32_t perm_owner_execute : 1; //!< When set this KV is owner executable 00206 uint32_t perm_other_read : 1; //!< When set this KV is world readable 00207 uint32_t perm_other_write : 1; //!< When set this KV is world writable. If set then a world client can delete this KV. 00208 uint32_t perm_other_execute : 1; //!< When set this KV is world executable (currently not supported) 00209 uint32_t reserved : 26; //!< reserved for future use. 00210 } ARM_CFSTORE_ACCESS_CONTROL_LIST; 00211 00212 00213 /** @brief 00214 * 00215 * File mode bit-field structure for specifying flags for the 00216 * following operations: 00217 * - ARM_CFSTORE_DRIVER::(*Create)(), when creating a KV. 00218 * - ARM_CFSTORE_DRIVER::(*Open)(), when opening a pre-existing KV. 00219 */ 00220 typedef struct ARM_CFSTORE_FMODE 00221 { 00222 uint32_t continuous : 1; //!< If set, the key value should be stored in a continuous sequence 00223 //!< of hardware addresses (not implemented). 00224 uint32_t lazy_flush : 1; //!< If set then configuration store will defer flushing the KV 00225 //!< changes until an optimal time. e.g. to save energy rather than 00226 //!< performing the operation immediately (not implemented). 00227 uint32_t flush_on_close : 1; //!< If set then the key-value should be flushed to the backing store 00228 //!< when the key is closed (not implemented). 00229 uint32_t read : 1; //!< If set then the KV can be read. 00230 uint32_t write : 1; //!< If set then the KV can be written. 00231 uint32_t execute : 1; //!< If set then the KV can be executed (not implemented). 00232 uint32_t storage_detect : 1; //!< If set then the call to ARM_CFSTORE_DRIVER::(*Create)() returns 00233 //!< whether a key could be created with the required storage 00234 //!< characteristics. The key is not created. 00235 uint32_t reserved : 25; //!< Reserved. 00236 } ARM_CFSTORE_FMODE; 00237 00238 00239 /** @brief Descriptor used to create keys */ 00240 typedef struct ARM_CFSTORE_KEYDESC 00241 { 00242 /*key descriptor attributes */ 00243 ARM_CFSTORE_ACCESS_CONTROL_LIST acl; //!< Access Control List specifying the access permissions of the KV. 00244 uint8_t drl; //!< Data retention level for the KV required by the client. 00245 //!< CFSTORE will store the KV in the specified type store/media. 00246 ARM_STORAGE_SECURITY_FEATURES security; //!< flash security properties for the KV required by the client. 00247 //!< CFSTORE will store the KV in a storage media supporting 00248 //!< the specified security attributes. 00249 ARM_CFSTORE_FMODE flags; //!< A bitfield containing the access mode setting for the key. 00250 } ARM_CFSTORE_KEYDESC; 00251 00252 00253 /** @brief 00254 * 00255 * These are the command code values used for the cmd_code argument to the 00256 * \ref ARM_CFSTORE_CALLBACK callback handler. The command code indicates the 00257 * \ref ARM_CFSTORE_DRIVER dispatch method previously invocated. 00258 */ 00259 typedef enum ARM_CFSTORE_OPCODE { 00260 CFSTORE_OPCODE_CLOSE = 1, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Close)() call. 00261 CFSTORE_OPCODE_CREATE, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Create)() call. 00262 CFSTORE_OPCODE_DELETE, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Delete)() call. 00263 CFSTORE_OPCODE_FIND, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Find)() call. 00264 CFSTORE_OPCODE_FLUSH, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Flush)() call. 00265 CFSTORE_OPCODE_GET_KEY_NAME, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*GetKeyName)() call. 00266 CFSTORE_OPCODE_GET_STATUS, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*GetStatus)() call. 00267 CFSTORE_OPCODE_GET_VALUE_LEN, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*GetValueLen)() call. 00268 CFSTORE_OPCODE_INITIALIZE, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Initialize)() call. 00269 CFSTORE_OPCODE_OPEN, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Open)() call. 00270 CFSTORE_OPCODE_POWER_CONTROL, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*PowerControl)() call. 00271 CFSTORE_OPCODE_READ, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Read)() call. 00272 CFSTORE_OPCODE_RSEEK, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Rseek)() call. 00273 CFSTORE_OPCODE_UNINITIALIZE, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Uninitialize)() call. 00274 CFSTORE_OPCODE_WRITE, //!< used for \ref ARM_CFSTORE_CALLBACK ::cmd_code argument when indicating status for a previous \ref ARM_CFSTORE_DRIVER ::(*Write)() call. 00275 CFSTORE_OPCODE_MAX //!< Sentinel 00276 } ARM_CFSTORE_OPCODE; 00277 00278 00279 /** @brief client registered callback type for receiving asynchronous event 00280 * notifications. 00281 * 00282 * @param status 00283 * In the case that cmd_code is one of ARM_CFSTORE_OPCODE then this 00284 * is the asynchronous completion status of the associated 00285 * ARM_CFSTORE_DRIVER::Dispatch_Method_Xxx() 00286 * @param cmd_code 00287 * ARM_CFSTORE_OPCODE for the 00288 * ARM_CFSTORE_DRIVER::Dispatch_Method_Xxx() for which this 00289 * invocation of the callback is an asynchronous completion event. 00290 * @param client_context 00291 * The client ARM_CFSTORE_CALLBACK context registered with the 00292 * ARM_CFSTORE_DRIVER::(*Initialize)() method. 00293 * @param handle 00294 * For certain ARM_CFSTORE_DRIVER::Dispatch_Method_Xxx() e.g. 00295 * ARM_CFSTORE_DRIVER::(*Create)() 00296 * ARM_CFSTORE_DRIVER::(*Open)() 00297 * ARM_CFSTORE_DRIVER::(*Find)() 00298 * then an open key handle is supplied upon asynchronous completion. 00299 * See the documentation of the ARM_CFSTORE_OpCode_e and the 00300 * ARM_CFSTORE_DRIVER::Dispatch_Method_Xxx() for further details. 00301 * 00302 */ 00303 typedef void (*ARM_CFSTORE_CALLBACK)(int32_t status, ARM_CFSTORE_OPCODE cmd_code, void *client_context, ARM_CFSTORE_HANDLE handle); 00304 00305 00306 /** @brief Find the capabilities of the configuration store. */ 00307 typedef struct ARM_CFSTORE_CAPABILITIES 00308 { 00309 uint32_t asynchronous_ops : 1; //!< When set then the configuration store dispatch interface is operating in non-blocking (asynchronous) mode. 00310 //!< When unset then the configuration store dispatch interface is operating in blocking (synchronous) mode. 00311 uint32_t uvisor_support_enabled : 1; //!< The configuration store is using uvisor security contexts. 00312 } ARM_CFSTORE_CAPABILITIES; 00313 00314 00315 /** 00316 * This is the set of operations constituting the Configuration Store driver. 00317 * 00318 * The functions dispatch methods can operate synchronously or asynchronously 00319 * depending on the underlying implementation. The client of this interface 00320 * should not assume one or other mode of operation but use the 00321 * (*GetCapabilities) method to determine the operational mode and then 00322 * behave accordingly. 00323 */ 00324 typedef struct _ARM_DRIVER_CFSTORE 00325 { 00326 /** @brief Get driver version. 00327 * 00328 * The synchronous function GetVersion() returns version information of the 00329 * driver implementation in ARM_DRIVER_VERSION. 00330 * - ARM_DRIVER_VERSION::api 00331 * the version of the CMSIS-Driver specification used to implement 00332 * this driver. 00333 * - ARM_DRIVER_VERSION::drv 00334 * the source code version of the actual configuration store driver 00335 * implementation. 00336 * 00337 * @return \ref ARM_DRIVER_VERSION, the configuration store driver 00338 * version information 00339 */ 00340 ARM_DRIVER_VERSION (*GetVersion)(void); 00341 00342 00343 /** @brief Close the hkey context previously recovered from CFSTORE. 00344 * 00345 * @param hkey 00346 * IN: a previously returned handle from (*Create((), (*Open)() 00347 * or (*Find)() to close. 00348 * 00349 * @return 00350 * 00351 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00352 * ARM_CFSTORE_DRIVER::(*Close)() asynchronous completion command code 00353 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00354 * @param status 00355 * ARM_DRIVER_OK => success, KV deleted, else failure. 00356 * @param cmd_code == CFSTORE_OPCODE_CLOSE 00357 * @param client context 00358 * as registered with ARM_CFSTORE_DRIVER::(*Initialize)() 00359 * @param hkey == NULL 00360 */ 00361 int32_t (*Close)(ARM_CFSTORE_HANDLE hkey); 00362 00363 00364 /** @brief Create a key-value int he configuration strore. 00365 * 00366 * Once created, the following attributes of a KV cannot be changed: 00367 * - the key_name 00368 * - the permissions or attributes specifies by the key descriptor kdesc. 00369 * To change these properties, the key must be deleted and then created 00370 * again with the new properties. 00371 * 00372 * @param key_name 00373 * IN: zero terminated string specifying the key name. 00374 * @param value_len 00375 * the client specifies the length of the value data item in the 00376 * KV being created. 00377 * @param kdesc 00378 * 00379 * IN: key descriptor, specifying how the details of the key 00380 * create operations. Note the following cases: 00381 * - 1) if key_name is not present in the CFSTORE and kdesc is NULL 00382 * (i.e. a new KV pair is being created), 00383 * then CFSTORE will chose the most appropriate defaults 00384 * e.g. CFSTORE will store the KV in nv store if the value size 00385 * is large, with no security guarantees just safety. 00386 * - 2) if key_name is present in the CFSTORE and kdesc is NULL 00387 * (i.e. there is a pre-existing KV pair), 00388 * then CFSTORE will grow/shrink the value data buffer to 00389 * value_len octets. This idiom can be used to increase/decrease 00390 * the size of the KV value storage. 00391 * - 3) If the kdesc->flags.storage_detect == 1 then the function 00392 * does not create the key but reports whether the key 00393 * with the specified size and storage media attributes 00394 * could/could not be created by configuration storage. 00395 * 00396 * @param hkey 00397 * IN: pointer to client owned buffer of CFSTORE_HANDLE_BUFSIZE 00398 * bytes 00399 * OUT: on success, hkey is a valid handle to a KV. 00400 * 00401 * @return 00402 * 00403 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00404 * ARM_CFSTORE_DRIVER::(*Create)() asynchronous completion command code 00405 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00406 * @param status 00407 * ARM_DRIVER_OK => success, KV deleted, else failure. 00408 * @param cmd_code == CFSTORE_OPCODE_CREATE 00409 * @param client context 00410 * as registered with ARM_CFSTORE_DRIVER::(*Initialize)() 00411 * @param hkey now contains returned handle to newly created key. 00412 */ 00413 int32_t (*Create)(const char* key_name, ARM_CFSTORE_SIZE value_len, const ARM_CFSTORE_KEYDESC* kdesc, ARM_CFSTORE_HANDLE hkey); 00414 00415 00416 /** @brief Delete key-value from configuration store 00417 * 00418 * This method is used in the following ways: 00419 * - (*Open)() to get a handle to the key, (*Delete)() to delete the key, 00420 * (*Close)() to close the handle to the key. 00421 * - (*Find)() to get a handle to the key, (*Delete)() to delete the key, 00422 * (*Close)() to close the handle to the key. 00423 * 00424 * @param hkey 00425 * IN: the handle of the key to delete. 00426 * 00427 * @return 00428 * 00429 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00430 * ARM_CFSTORE_DRIVER::(*Delete)() asynchronous completion command code 00431 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00432 * @param status 00433 * ARM_DRIVER_OK => success, KV deleted, else failure. 00434 * @param cmd_code == CFSTORE_OPCODE_DELETE 00435 * @param client context 00436 * as registered with ARM_CFSTORE_DRIVER::(*Initialize)() 00437 * @param hkey, unused. 00438 * 00439 */ 00440 int32_t (*Delete)(ARM_CFSTORE_HANDLE hkey); 00441 00442 00443 /** @brief find stored keys that match a query string 00444 * 00445 * find a list of pre-existing keys according to a query pattern. 00446 * The search pattern can have the following formats 00447 * - 'com.arm.mbed.wifi.accesspoint.essid'. Find whether an object 00448 * exists that has a key matching 00449 * 'com.arm.mbed.wifi.accesspoint.essid' 00450 * - 'com.arm.mbed.wifi.accesspoint*.essid'. Find all keys that 00451 * start with the substring 'com.arm.mbed.wifi.accesspoint' and 00452 * end with the substring '.essid' 00453 * - 'com.arm.mbed.your-registry-module-name.*'. Find all key_name 00454 * strings that begin with the substring 00455 * 'com.arm.mbed.your-registry-module-name.' 00456 * - 'com.arm.mbed.hello-world.animal{dog}{foot}{*}'. Find all key_name 00457 * strings beginning com.arm.mbed.hello-world.animal{dog}{foot} 00458 * - 'com.arm.mbed.hello-world.animal{dog}{foot}*' 00459 * - 'com.arm.mbed.hello-world.animal{dog*3}' 00460 * 00461 * It is possible to iterate over the list of matching keys by 00462 * using the idiom below (in the synchronous case): 00463 * ``` 00464 * int32_t ret = ARM_DRIVER_ERROR; 00465 * const char* key_name_query = "*"; 00466 * char key_name[CFSTORE_KEY_NAME_MAX_LENGTH+1]; 00467 * uint8_t len = CFSTORE_KEY_NAME_MAX_LENGTH+1; 00468 * ARM_CFSTORE_HANDLE_INIT(next); 00469 * ARM_CFSTORE_HANDLE_INIT(prev); 00470 * 00471 * while(drv->Find(key_name_query, prev, next) == ARM_DRIVER_OK) 00472 * { 00473 * len = CFSTORE_KEY_NAME_MAX_LENGTH+1; 00474 * drv->GetKeyName(next, key_name, &len); 00475 * printf("Found matching key-value with key_name=%s\n", key_name); 00476 * CFSTORE_HANDLE_SWAP(prev, next); 00477 * } 00478 * ``` 00479 * The iteration over the find results can be terminated before 00480 * the end of the list is reached by closing the last open 00481 * file handle and not making any further calls to 00482 * find() e.g. 00483 * 00484 * ``` 00485 * int32_t ret = ARM_DRIVER_ERROR; 00486 * const char* key_name_query = "*"; 00487 * char key_name[CFSTORE_KEY_NAME_MAX_LENGTH+1]; 00488 * uint8_t len = CFSTORE_KEY_NAME_MAX_LENGTH+1; 00489 * ARM_CFSTORE_HANDLE_INIT(next); 00490 * ARM_CFSTORE_HANDLE_INIT(prev); 00491 * 00492 * while(drv->Find(key_name_query, prev, next) == ARM_DRIVER_OK) 00493 * { 00494 * len = CFSTORE_KEY_NAME_MAX_LENGTH+1; 00495 * drv->GetKeyName(next, key_name, &len); 00496 * if(strncmp(key_name, "my.key_name", CFSTORE_KEY_NAME_MAX_LENGTH)) 00497 * { 00498 * printf("Found matching key-value with key_name=%s\n", key_name; 00499 * // terminating walk of find results 00500 * drv->Close(next); 00501 * break; 00502 * CFSTORE_HANDLE_SWAP(prev, next); 00503 * } 00504 * ``` 00505 * 00506 * @param key_name_query 00507 * IN: a search string to find. This can include the wildcard '*' 00508 * character 00509 * @param previous 00510 * IN: On the first call to (*Find) then previous is a pointer 00511 * (the handle) to a buffer initialised to 0. 00512 * On the subsequent calls to (*Find), a previously returned 00513 * key handle can be supplied as the previous argument. The next 00514 * available search result will be returned. If no further search 00515 * results are available then (*Find) will return 00516 * ARM_CFSTORE_DRIVER_ERROR_KEY_NOT_FOUND. Once the 00517 * file handle has been supplied to the function as the prev 00518 * argument, CFSTORE close the open file handle. Otherwise, the 00519 * client must call (*Close)() on the open file handle. 00520 * @param next 00521 * IN: pointer to client owned buffer of CFSTORE_HANDLE_BUFSIZE 00522 * bytes to hold the 00523 * OUT: Success: In the case that a match has been found then hkey 00524 * is a valid handle to an open KV. The key must be explicitly closed 00525 * by the client. Note this is a read-only key. 00526 * Async operation: The storage at hkey must be available until after 00527 * the completion notification has been received by the client. 00528 * @return 00529 * On success (finding a KV matching the query) ARM_DRIVER_OK is 00530 * returned. If a KV is not found matching the description then 00531 * ARM_CFSTORE_DRIVER_ERROR_KEY_NOT_FOUND is returned. 00532 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00533 * ARM_CFSTORE_DRIVER::(*Find)() asynchronous completion command code 00534 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00535 * @param status 00536 * ARM_DRIVER_OK => success, hkey contains open key 00537 * else failure. 00538 * @param cmd_code == CFSTORE_OPCODE_FIND 00539 * @param client context 00540 * as registered with ARM_CFSTORE_DRIVER::(*Initialize)() 00541 * @param hkey 00542 * ARM_DRIVER_OK => contains returned handle to newly found key. 00543 * else, indeterminate data. 00544 */ 00545 int32_t (*Find)(const char* key_name_query, const ARM_CFSTORE_HANDLE previous, ARM_CFSTORE_HANDLE next); 00546 00547 00548 /** @brief 00549 * 00550 * Flush (write) the configuration changes to the nv backing store. 00551 * 00552 * All open key handles must be closed before flushing the CFSTORE to nv 00553 * backing store. 00554 * 00555 * @return 00556 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00557 * ARM_CFSTORE_DRIVER::(*Flush)() asynchronous completion command code 00558 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00559 * @param status 00560 * ARM_DRIVER_OK => success, hkey contains open key 00561 * else failure. 00562 * @param cmd_code == CFSTORE_OPCODE_FLUSH 00563 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00564 * @param hkey, unused 00565 */ 00566 int32_t (*Flush)(void); 00567 00568 00569 /** @brief Get configuration store capabilities. 00570 * 00571 * This synchronous function returns a ARM_CFSTORE_CAPABILITIES 00572 * information structure describing configuration store implementation 00573 * attributes. 00574 * 00575 * @return \ref ARM_CFSTORE_CAPABILITIES 00576 */ 00577 ARM_CFSTORE_CAPABILITIES (*GetCapabilities)(void); 00578 00579 00580 /** @brief Get the name of an open key handle. 00581 * 00582 * @param hkey 00583 * open handle of key to get the key_name 00584 * @param key_name. The key name string is guaranteed to be terminated 00585 * with '\0'. 00586 * @param key_len, the length of the buffer available at data to receive 00587 * the key_name string 00588 * @return 00589 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00590 * ARM_CFSTORE_DRIVER::(*GetKeyName)() asynchronous completion command code 00591 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00592 * @param status 00593 * ARM_DRIVER_OK => success, key_name contains key_name string, len 00594 * contains length of string. 00595 * else failure. 00596 * @param cmd_code == CFSTORE_OPCODE_GET_KEY_NAME 00597 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00598 * @param hkey supplied to the GetKeyName() call at hkey. 00599 * @param key_name 00600 * on success, the buffer holds the name of the key 00601 * @param key_len 00602 * on success, the supplied integer is set to strlen(key_name)+1, where 00603 * the additional character corresponds to the terminating null. 00604 * 00605 */ 00606 int32_t (*GetKeyName)(ARM_CFSTORE_HANDLE hkey, char* key_name, uint8_t *key_len); 00607 00608 00609 /** @brief Get the status of the configuration store. 00610 * 00611 * @return 00612 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation 00613 * ARM_DRIVER_OK if the command has been accepted and 00614 * enqueued by the underlying controller, else an appropriate 00615 * error code. Getting a return value of ARM_DRIVER_OK 00616 * implies that basic argument validation was successful, and the 00617 * caller can expect a command completion callback to be invoked 00618 * at a later time. 00619 * 00620 * ARM_CFSTORE_DRIVER::(*GetStatus)() asynchronous completion command code 00621 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00622 * @param status 00623 * status of next command pending completion 00624 * @param cmd_code 00625 * next command pending completion. 00626 * @param client context registered ARM_CFSTORE_DRIVER::(*Initialize)() 00627 * @param hkey 00628 * unused. 00629 */ 00630 ARM_CFSTORE_STATUS (*GetStatus)(void); 00631 00632 00633 /** @brief Get the value length from an open key handle 00634 * 00635 * @param hkey 00636 * open handle of key for which to get value length 00637 * @param value_len, the location in which to store the value length. 00638 * @return 00639 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00640 * ARM_CFSTORE_DRIVER::(*GetValueLen)() asynchronous completion command code 00641 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00642 * @param status 00643 * ARM_DRIVER_OK => success, value_len contains length value. 00644 * else failure. 00645 * @param cmd_code == CFSTORE_OPCODE_GET_VALUE_LEN 00646 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00647 * @param hkey supplied to the GetValueLen() call at hkey. 00648 * 00649 */ 00650 int32_t (*GetValueLen)(ARM_CFSTORE_HANDLE hkey, ARM_CFSTORE_SIZE *value_len); 00651 00652 00653 /** @brief Initialize the Configuration Store 00654 * 00655 * This function: 00656 * - initialised the configuration store service 00657 * - allows the client to subscribe to event notifications, in particular 00658 * the asynchronous completion events for the driver dispatch interface 00659 * (see ARM_CFSTORE_OPCODE). 00660 * 00661 * The configuration store should be initialised as follows: 00662 * drv->initialise(client_callback, client_callback_context); 00663 * drv->PowerControl(ARM_POWER_FULL) 00664 * where: 00665 * - client_callback is a client implemented callback function. 00666 * - client_callback_context is a client registered context that 00667 * will be supplied as an argument to the client_callback 00668 * when called. 00669 * - PowerControl indicates that any underlying system services 00670 * that are in the low power state should be powered up. 00671 * 00672 * The configuration store should be de-initialised as follows: 00673 * drv->PowerControl(ARM_POWER_OFF) 00674 * drv->Deinitialise(); 00675 * 00676 * @param client_callback 00677 * this is a client implemented callback function for 00678 * receiving asynchronous event notifications (see 00679 * ARM_CFSTORE_CALLBACK). NULL indicates client does 00680 * not subscribed to event notifications. 00681 * 00682 * @param client_callback_context 00683 * this is the client registered context that 00684 * will be supplied as an argument to the client_callback 00685 * when called. This argument can be NULL. 00686 * 00687 * @return 00688 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00689 * ARM_CFSTORE_DRIVER::(*Initialize)() asynchronous completion command code 00690 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00691 * @param status 00692 * ARM_DRIVER_OK => success, configuration store initialised, 00693 * else failure 00694 * @param CFSTORE_OPCODE_INITIALIZE 00695 * @param client context registered ARM_CFSTORE_DRIVER::(*Initialize)() 00696 * @param hkey, unused. 00697 * 00698 */ 00699 int32_t (*Initialize)(ARM_CFSTORE_CALLBACK callback, void* client_context); 00700 00701 00702 /** @brief Function to set the target configuration store power state. 00703 * 00704 * @param state 00705 * \ref ARM_POWER_STATE. The target power-state for the 00706 * configuration store. The parameter state can have the 00707 * following values: 00708 * - ARM_POWER_FULL => set the mode to full power state 00709 * - ARM_POWER_LOW => set the mode to low power state 00710 * - ARM_POWER_OFF => set the mode to off power state 00711 * 00712 * @return 00713 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00714 * CFSTORE_OPCODE_POWER_CONTROL 00715 * ARM_CFSTORE_DRIVER::(*PowerControl)() asynchronous completion command code 00716 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00717 * @param status 00718 * ARM_DRIVER_OK => success, power control set, else failure. 00719 * @param cmd_code == CFSTORE_OPCODE_POWER_CONTROL 00720 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00721 * @param hkey, unused. 00722 */ 00723 int32_t (*PowerControl)(ARM_POWER_STATE state); 00724 00725 00726 /** @brief Read the value data associated with a specified key. 00727 * 00728 * @param hkey 00729 * IN: the handle returned from a previous call to (*Open)() to 00730 * get a handle to the key 00731 * @param data 00732 * IN: a pointer to a data buffer supplied by the caller for CFSTORE to 00733 * fill with value data 00734 * OUT: on ARM_DRIVER_OK the data is (or will be when asynchronously 00735 * completed) available in the buffer. The data will be read from 00736 * the current form the current location (see (*Rseek)(). 00737 * @param len 00738 * IN: the client specifies the length of the buffer available at data 00739 * OUT: the CFSTORE specifies how many octets have been stored in the 00740 * supplied buffer. Note fewer octets may be stored than the input len 00741 * depending on the CFSTORE internal representation of the value. 00742 * 00743 * @return 00744 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00745 * return_value == ARM_DRIVER_OK (==0) => asynchronous 00746 * transaction pending. 00747 * return_value > 0 => synchronous completion of read with the 00748 * number of bytes read == return_value 00749 * return_value < 0, error condition. 00750 * 00751 * ARM_CFSTORE_DRIVER::(*Read)() asynchronous completion command code 00752 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00753 * @param status 00754 * >= 0 => success with number of bytes read as indicated by 00755 * the value of status 00756 * < 0 => error, data in the data buffer is undefined, len is 00757 * undefined. 00758 * @param cmd_code == CFSTORE_OPCODE_READ 00759 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00760 * @param hkey, unused. 00761 */ 00762 int32_t (*Read)(ARM_CFSTORE_HANDLE hkey, void* data, ARM_CFSTORE_SIZE* len); 00763 00764 00765 /** @brief Open a key-value object for future operations. 00766 * 00767 * @param key_name 00768 * IN: zero terminated string specifying the key name. 00769 * @param flags 00770 * can open a RW key in read only mode. 00771 * @param hkey 00772 * IN: pointer to client owned buffer of CFSTORE_HANDLE_BUFSIZE 00773 * bytes 00774 * OUT: on success, hkey is a valid handle to an open KV. 00775 * 00776 * @return 00777 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00778 * ARM_CFSTORE_DRIVER::(*Open)() asynchronous completion command code 00779 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00780 * @param status 00781 * ARM_DRIVER_OK => success, KV opened, else failure. 00782 * @param cmd_code == CFSTORE_OPCODE_OPEN 00783 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00784 * @param hkey now contains returned handle to newly opened key. 00785 */ 00786 int32_t (*Open)(const char* key_name, ARM_CFSTORE_FMODE flags, ARM_CFSTORE_HANDLE hkey); 00787 00788 00789 /** @brief Move the position of the read pointer within a value 00790 * 00791 * @param hkey 00792 * IN: the key referencing the value data for which the read 00793 * location should be updated. Note that this function can 00794 * only be called on pre-existing keys opened with read-only 00795 * flag. Performing a seek operation on a writable key will fail. 00796 * @param offset 00797 * IN: the new offset position from the start of the value data 00798 * 00799 * @return 00800 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00801 * ARM_CFSTORE_DRIVER::(*Rseek)() asynchronous completion command code 00802 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00803 * @param status 00804 * >=0 => success, read location set, else failure. 00805 * upon success, the function returns the current read 00806 * location measured from the beginning of the data value. 00807 * <0 => error 00808 * @param cmd_code == CFSTORE_OPCODE_RSEEK 00809 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00810 * @param hkey, unused. 00811 */ 00812 int32_t (*Rseek)(ARM_CFSTORE_HANDLE hkey, ARM_CFSTORE_OFFSET offset); 00813 00814 00815 /** @brief Function to de-initialise the Configuration Store 00816 * 00817 * @return 00818 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00819 * CFSTORE_OPCODE_UNINITIALIZE 00820 * ARM_CFSTORE_DRIVER::(*Uninitialize)() asynchronous completion command code 00821 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00822 * @param status 00823 * ARM_DRIVER_OK => success, read location set, else failure. 00824 * @param cmd_code == CFSTORE_OPCODE_UNINITIALIZE 00825 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00826 * @param hkey, unused. 00827 */ 00828 int32_t (*Uninitialize)(void); 00829 00830 00831 /** @brief Write the value data associated with a specified key 00832 * 00833 * @note Note that Write() only supports sequential-access. 00834 * 00835 * @param hkey 00836 * IN: the key for which value data will be written 00837 * @param data 00838 * IN: a pointer to a data buffer supplied by the caller for CFSTORE to 00839 * write as the binary blob value data. 00840 * Async operation: the buffer must be available until after 00841 * completion notification is received by the client. 00842 * @param len 00843 * IN: the client specifies the length of the data buffer available. 00844 * len must not exceed the value_len field specified when the 00845 * KV pair was created. 00846 * OUT: the CFSTORE specifies how many octets have been stored. 00847 * Note that fewer octets may be stored than the input len 00848 * depending on the CFSTORE internal representation of the value. 00849 * Async operation: the len storage location must be available 00850 * until after completion notification is received by the client. 00851 * 00852 * @return 00853 * See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. 00854 * return_value == ARM_DRIVER_OK (==0) => asynchronous 00855 * transaction pending. 00856 * return_value > 0 => synchronous completion of write with the 00857 * number of bytes written == return_value 00858 * return_value < 0, error condition. 00859 * 00860 * ARM_CFSTORE_DRIVER::(*Write)() asynchronous completion 00861 * (*ARM_CFSTORE_CALLBACK) function argument values on return: 00862 * @param status 00863 * >= 0 => success with the number bytes written equal to the value 00864 * of the return status 00865 * ARM_CFSTORE_CALLBACK status argument < 0 => error 00866 * @param cmd_code == CFSTORE_OPCODE_WRITE 00867 * @param client context, registered ARM_CFSTORE_DRIVER::(*Initialize)() 00868 * @param hkey, unused. 00869 */ 00870 int32_t (*Write)(ARM_CFSTORE_HANDLE hkey, const char* data, ARM_CFSTORE_SIZE* len); 00871 00872 } const ARM_CFSTORE_DRIVER; 00873 00874 00875 00876 extern ARM_CFSTORE_DRIVER cfstore_driver; 00877 00878 #ifdef __cplusplus 00879 } 00880 #endif 00881 00882 #endif /* __CONFIGURATION_STORE_H */
Generated on Tue Jul 12 2022 13:15:40 by
1.7.2