KVMap.h

00001 /*
00002  * Copyright (c) 2018 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef _KV_MAP
00017 #define _KV_MAP
00018 
00019 #include "features/storage/kvstore/include/KVStore.h"
00020 #include "platform/PlatformMutex.h"
00021 #include "platform/SingletonPtr.h"
00022 #include "features/storage/blockdevice/BlockDevice.h"
00023 #include "features/storage/filesystem/FileSystem.h"
00024 
00025 namespace mbed {
00026 
00027 #define  MAX_ATTACHED_KVS 3
00028 
00029 /**
00030  * This structure represent a KVStore partition configuration
00031  */
00032 typedef struct {
00033     /**
00034      * A Pointer to main instance of the KVStore partition.
00035      * This is also the instance KVStore global API should work with.
00036      * This must not be NULL in a working partition configuration.
00037      */
00038     KVStore *kvstore_main_instance;
00039     /**
00040      * A pointer Internal store of the KVStore partition.
00041      * If no rollback protection is required the pointer may be NULL.
00042      */
00043     KVStore *internal_store;
00044     /**
00045      * A pointer external store of the KVStore partition.
00046      * The pointer can be NULL if external store has been omitted
00047      */
00048     KVStore *external_store;
00049     /**
00050      * A pointer Internal FlashIAP BlockDevice of the KVStore partition.
00051      * The pointer can be NULL if internal store has been omitted
00052      */
00053     BlockDevice *internal_bd;
00054     /**
00055      * A pointer external BlockDevice of the KVStore partition.
00056      * The pointer can be NULL if external store has been omitted
00057      */
00058     BlockDevice *external_bd;
00059     /**
00060      * A pointer external FileSystem of the KVStore partition.
00061      * The pointer can be NULL if FileSystemStore has not been configured.
00062      */
00063     FileSystem *external_fs;
00064     /**
00065      * This is a flag masking value for the KVStore global API.
00066      * The Global API will mask the input flags base on this value to
00067      * prevent errors in case the user choose an different security level.
00068      */
00069     uint32_t flags_mask;
00070 } kvstore_config_t;
00071 
00072 /**
00073  * This structure maps between a string name and a partition configuration.
00074  */
00075 typedef struct {
00076     /**
00077       * Partition name string
00078       */
00079     char *partition_name;
00080     /**
00081      * Configuration struct.
00082      */
00083     kvstore_config_t *kv_config;
00084 } kv_map_entry_t;
00085 
00086 /** KVMap class
00087  *
00088  *  Singleton class to manage the mapping of KVStore partition and its naming.
00089  */
00090 class KVMap : private mbed::NonCopyable<KVMap> {
00091 public:
00092 
00093     /**
00094      * @brief As a singleton, return the single instance of the class.
00095      *        This class is a singleton for the following reasons:
00096      *        - Ease of use, so you don't have to coordinate instantiations.
00097      *        - Lazy instantiation of internal data, (which we can't achieve with simple static classes).
00098      *
00099      * @returns Singleton instance reference.
00100      */
00101     static KVMap &get_instance()
00102     {
00103         // Use this implementation of singleton (Meyer's) rather than the one that allocates
00104         // the instance on the heap because it ensures destruction at program end (preventing warnings
00105         // from memory checking tools, such as valgrind).
00106         static KVMap instance;
00107         return instance;
00108     }
00109 
00110     ~KVMap();
00111 
00112     /**
00113      * @brief Initializes KVMap
00114      *
00115      * @return 0 on success, negative error code on failure
00116      */
00117     int init();
00118 
00119     /**
00120      * @brief Attach a KVStore partition configuration, and add it to the KVMap array
00121      *
00122      * @param partition_name String parameter contains the partition name.
00123      * @param kv_config A configuration struct created by the kv_config or by the user.
00124      * @return 0 on success, negative error code on failure
00125      */
00126     int attach(const char *partition_name, kvstore_config_t *kv_config);
00127 
00128     /**
00129      * @brief Detach a KVStore partition configuration from the KVMap array,
00130      *        and deinitialize its components
00131      *
00132      * @param partition_name String parameter contains the partition name.
00133      * @return 0 on success, negative error code on failure
00134      */
00135     int detach(const char *partition_name);
00136 
00137     /**
00138      * @brief Deinitialize the KVMap array, and deinitialize all the attached partitions.
00139      *
00140      * @return 0 on success, negative error code on failure
00141      */
00142     int deinit();
00143 
00144     /**
00145      * @brief Full name lookup, and then break it into KVStore instance and key
00146      *
00147      * @param[in] full_name  String parameter contains the partition name to look for.
00148      *                   The String should be formated as follow "/partition name/key". The key is optional.
00149      * @param[out] kv_instance Returns the main KVStore instance associated with the required partition name.
00150      * @param[out] key_index Returns an index to the first character of the key.
00151      * @param[out] flags_mask Return the flag masking for the current configuration
00152      * @return 0 on success, negative error code on failure
00153      */
00154     int lookup(const char *full_name, mbed::KVStore **kv_instance, size_t *key_index, uint32_t *flags_mask = NULL);
00155 
00156     /**
00157      * @brief Getter for the internal KVStore instance.
00158      *
00159      * @param name String parameter contains the /partition name/.
00160      *
00161      * @return Pointer to the internal kvstore on success,
00162      *         NULL on failure or if not exist
00163      */
00164     KVStore *get_internal_kv_instance(const char *name);
00165     /**
00166      * @brief Getter for the external KVStore instance.
00167      *
00168      * @param name String parameter contains the /partition name/.
00169      *
00170      * @return Pointer to the external kvstore on success,
00171      *         NULL on failure or if not exist
00172      */
00173     KVStore *get_external_kv_instance(const char *name);
00174     /**
00175      * @brief Getter for the main KVStore instance.
00176      *
00177      * @param name String parameter contains the /partition name/.
00178      *
00179      * @return Pointer to the main kvstore on success,
00180      *         NULL on failure or if not exist
00181      */
00182     KVStore *get_main_kv_instance(const char *name);
00183     /**
00184      * @brief Getter for the internal BlockDevice instance.
00185      *
00186      * @param name String parameter contains the /partition name/.
00187      *
00188      * @return Pointer to the internal BlockDevice on success,
00189      *         NULL on failure or if not exist
00190      */
00191     BlockDevice *get_internal_blockdevice_instance(const char *name);
00192     /**
00193      * @brief Getter for the external BlockDevice instance.
00194      *
00195      * @param name String parameter contains the /partition name/.
00196      *
00197      * @return Pointer to the external BlockDevice on success,
00198      *         NULL on failure or if not exist
00199      */
00200     BlockDevice *get_external_blockdevice_instance(const char *name);
00201     /**
00202      * @brief Getter for the external FileSystem instance.
00203      *
00204      * @param name String parameter contains the /partition name/.
00205      *
00206      * @return Pointer to the external FileSystem on success,
00207      *         NULL on failure or if not exist
00208      */
00209     FileSystem *get_external_filesystem_instance(const char *name);
00210 
00211 #if !defined(DOXYGEN_ONLY)
00212 private:
00213 
00214     /**
00215      * @brief Deinitialize all components of a partition configuration struct.
00216      *
00217      * @param partition  Partition configuration struct.
00218      */
00219     void deinit_partition(kv_map_entry_t *partition);
00220 
00221     /**
00222      * @brief Full name lookup, and then break it into KVStore config and key
00223      *
00224      * @param[in] full_name  String parameter contains the /partition name/key.
00225      * @param[out] kv_config Returns The configuration struct associated with the partition name
00226      * @param[out] key_index Returns an index to the first character of the key.
00227      * @return 0 on success, negative error code on failure
00228      */
00229     int config_lookup(const char *full_name, kvstore_config_t **kv_config, size_t *key_index);
00230 
00231     // Attachment table
00232     kv_map_entry_t _kv_map_table[MAX_ATTACHED_KVS];
00233     int _kv_num_attached_kvs;
00234     int _is_initialized;
00235     SingletonPtr<PlatformMutex>  _mutex;
00236 #endif
00237 };
00238 }
00239 #endif