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