Solution for Bluetooth SIG hands-on training course
Dependencies: BLE_API mbed-dev-bin nRF51822-bluetooth-mdw
Fork of microbit-dal-bluetooth-mdw_starter by
MicroBitStorage.h
00001 /* 00002 The MIT License (MIT) 00003 00004 Copyright (c) 2016 British Broadcasting Corporation. 00005 This software is provided by Lancaster University by arrangement with the BBC. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a 00008 copy of this software and associated documentation files (the "Software"), 00009 to deal in the Software without restriction, including without limitation 00010 the rights to use, copy, modify, merge, publish, distribute, sublicense, 00011 and/or sell copies of the Software, and to permit persons to whom the 00012 Software is furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 00023 DEALINGS IN THE SOFTWARE. 00024 */ 00025 00026 #ifndef MICROBIT_STORAGE_H 00027 #define MICROBIT_STORAGE_H 00028 00029 #include "mbed.h" 00030 #include "MicroBitConfig.h" 00031 #include "ManagedString.h" 00032 #include "ErrorNo.h" 00033 00034 #define MICROBIT_STORAGE_MAGIC 0xCAFE 00035 00036 #define MICROBIT_STORAGE_BLOCK_SIZE 48 00037 #define MICROBIT_STORAGE_KEY_SIZE 16 00038 #define MICROBIT_STORAGE_VALUE_SIZE MICROBIT_STORAGE_BLOCK_SIZE - MICROBIT_STORAGE_KEY_SIZE 00039 00040 #define MICROBIT_STORAGE_STORE_PAGE_OFFSET 17 //Use the page just above the BLE Bond Data. 00041 #define MICROBIT_STORAGE_SCRATCH_PAGE_OFFSET 19 //Use the page just below the BLE Bond Data. 00042 00043 struct KeyValuePair 00044 { 00045 uint8_t key[MICROBIT_STORAGE_KEY_SIZE]; 00046 uint8_t value[MICROBIT_STORAGE_VALUE_SIZE]; 00047 }; 00048 00049 struct KeyValueStore 00050 { 00051 uint32_t magic; 00052 uint32_t size; 00053 00054 KeyValueStore(uint32_t magic, uint32_t size) 00055 { 00056 this->magic = magic; 00057 this->size = size; 00058 } 00059 00060 KeyValueStore() 00061 { 00062 this->magic = 0; 00063 this->size = 0; 00064 } 00065 }; 00066 00067 00068 /** 00069 * Class definition for the MicroBitStorage class. 00070 * This allows reading and writing of small blocks of data to FLASH memory. 00071 * 00072 * This class operates as a key value store, it allows the retrieval, addition 00073 * and deletion of KeyValuePairs. 00074 * 00075 * The first 8 bytes are reserved for the KeyValueStore struct which gives core 00076 * information such as the number of KeyValuePairs in the store, and whether the 00077 * store has been initialised. 00078 * 00079 * After the KeyValueStore struct, KeyValuePairs are arranged contiguously until 00080 * the end of the block used as persistent storage. 00081 * 00082 * |-------8-------|--------48-------|-----|---------48--------| 00083 * | KeyValueStore | KeyValuePair[0] | ... | KeyValuePair[N-1] | 00084 * |---------------|-----------------|-----|-------------------| 00085 */ 00086 class MicroBitStorage 00087 { 00088 /** 00089 * Function for copying words from one location to another. 00090 * 00091 * @param from the address to copy data from. 00092 * 00093 * @param to the address to copy the data to. 00094 * 00095 * @param sizeInWords the number of words to copy 00096 */ 00097 void flashCopy(uint32_t* from, uint32_t* to, int sizeInWords); 00098 00099 /** 00100 * Function for populating the scratch page with a KeyValueStore. 00101 * 00102 * @param store the KeyValueStore struct to write to the scratch page. 00103 */ 00104 void scratchKeyValueStore(KeyValueStore store); 00105 00106 /** 00107 * Function for populating the scratch page with a KeyValuePair. 00108 * 00109 * @param pair the KeyValuePair struct to write to the scratch page. 00110 * 00111 * @param flashPointer the pointer in flash where this KeyValuePair resides. This pointer 00112 * is used to determine the offset into the scratch page, where the KeyValuePair should 00113 * be written. 00114 */ 00115 void scratchKeyValuePair(KeyValuePair pair, uint32_t* flashPointer); 00116 00117 public: 00118 00119 /** 00120 * Default constructor. 00121 * 00122 * Creates an instance of MicroBitStorage which acts like a KeyValueStore 00123 * that allows the retrieval, addition and deletion of KeyValuePairs. 00124 */ 00125 MicroBitStorage(); 00126 00127 /** 00128 * Writes the given number of bytes to the address specified. 00129 * 00130 * @param buffer the data to write. 00131 * 00132 * @param address the location in memory to write to. 00133 * 00134 * @param length the number of bytes to write. 00135 * 00136 * @note currently not implemented. 00137 */ 00138 int writeBytes(uint8_t *buffer, uint32_t address, int length); 00139 00140 /** 00141 * Method for erasing a page in flash. 00142 * 00143 * @param page_address Address of the first word in the page to be erased. 00144 */ 00145 void flashPageErase(uint32_t * page_address); 00146 00147 /** 00148 * Method for writing a word of data in flash with a value. 00149 * 00150 * @param address Address of the word to change. 00151 * 00152 * @param value Value to be written to flash. 00153 */ 00154 void flashWordWrite(uint32_t * address, uint32_t value); 00155 00156 /** 00157 * Places a given key, and it's corresponding value into flash at the earliest 00158 * available point. 00159 * 00160 * @param key the unique name that should be used as an identifier for the given data. 00161 * The key is presumed to be null terminated. 00162 * 00163 * @param data a pointer to the beginning of the data to be persisted. 00164 * 00165 * @param dataSize the size of the data to be persisted 00166 * 00167 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if the key or size is too large, 00168 * MICROBIT_NO_RESOURCES if the storage page is full 00169 */ 00170 int put(const char* key, uint8_t* data, int dataSize); 00171 00172 00173 /** 00174 * Places a given key, and it's corresponding value into flash at the earliest 00175 * available point. 00176 * 00177 * @param key the unique name that should be used as an identifier for the given data. 00178 * 00179 * @param data a pointer to the beginning of the data to be persisted. 00180 * 00181 * @param dataSize the size of the data to be persisted 00182 * 00183 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if the key or size is too large, 00184 * MICROBIT_NO_RESOURCES if the storage page is full 00185 */ 00186 int put(ManagedString key, uint8_t* data, int dataSize); 00187 00188 /** 00189 * Retreives a KeyValuePair identified by a given key. 00190 * 00191 * @param key the unique name used to identify a KeyValuePair in flash. 00192 * 00193 * @return a pointer to a heap allocated KeyValuePair struct, this pointer will be 00194 * NULL if the key was not found in storage. 00195 * 00196 * @note it is up to the user to free memory after use. 00197 */ 00198 KeyValuePair* get(const char* key); 00199 00200 /** 00201 * Retreives a KeyValuePair identified by a given key. 00202 * 00203 * @param key the unique name used to identify a KeyValuePair in flash. 00204 * 00205 * @return a pointer to a heap allocated KeyValuePair struct, this pointer will be 00206 * NULL if the key was not found in storage. 00207 * 00208 * @note it is up to the user to free memory after use. 00209 */ 00210 KeyValuePair* get(ManagedString key); 00211 00212 /** 00213 * Removes a KeyValuePair identified by a given key. 00214 * 00215 * @param key the unique name used to identify a KeyValuePair in flash. 00216 * 00217 * @return MICROBIT_OK on success, or MICROBIT_NO_DATA if the given key 00218 * was not found in flash. 00219 */ 00220 int remove(const char* key); 00221 00222 /** 00223 * Removes a KeyValuePair identified by a given key. 00224 * 00225 * @param key the unique name used to identify a KeyValuePair in flash. 00226 * 00227 * @return MICROBIT_OK on success, or MICROBIT_NO_DATA if the given key 00228 * was not found in flash. 00229 */ 00230 int remove(ManagedString key); 00231 00232 /** 00233 * The size of the flash based KeyValueStore. 00234 * 00235 * @return the number of entries in the key value store 00236 */ 00237 int size(); 00238 }; 00239 00240 #endif
Generated on Tue Jul 12 2022 20:39:13 by 1.7.2