Olli Vanhoja / mFS

mFS file system library for EEPROM memory chips.

mfs.h@9:52c01cb100ac, 2011-02-22 (annotated)

Committer:
HBP
Date:
Tue Feb 22 18:57:37 2011 +0000
Revision:
9:52c01cb100ac
Parent:
8:e67733ad4427
Child:
10:211cb54339a0
-file rename

-Increased fault tolerance

Who changed what in which revision?

UserRevisionLine numberNew contents of line
HBP 5:a0fe74dce80d 1 /** @file mfs.h */
HBP 0:cbf45dde2b49 2 /*H****************************************************************************
HBP 7:5ac5121bb4e0 3 * FILENAME : mfs.h *
HBP 7:5ac5121bb4e0 4 * *
HBP 7:5ac5121bb4e0 5 * DESCRIPTION : *
HBP 7:5ac5121bb4e0 6 * mFS file system implementation for mBED with external I2C EEEPROM. *
HBP 8:e67733ad4427 7 * *
HBP 8:e67733ad4427 8 * ---------------------------------------------------------------------------*
HBP 8:e67733ad4427 9 * "THE BEER-WARE LICENSE" (Revision 42): *
HBP 8:e67733ad4427 10 * <olli.vanhoja@gmail.com> wrote this file. As long as you retain this notice*
HBP 8:e67733ad4427 11 * you can do whatever you want with this stuff. If we meet some day, and you *
HBP 8:e67733ad4427 12 * think this stuff is worth it, you can buy me a beer in return Olli Vanhoja *
HBP 8:e67733ad4427 13 * ---------------------------------------------------------------------------*
HBP 8:e67733ad4427 14 * *
HBP 8:e67733ad4427 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
HBP 8:e67733ad4427 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *
HBP 8:e67733ad4427 17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL *
HBP 8:e67733ad4427 18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
HBP 8:e67733ad4427 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *
HBP 8:e67733ad4427 20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *
HBP 8:e67733ad4427 21 * DEALINGS IN THE SOFTWARE. *
HBP 8:e67733ad4427 22 * *
HBP 8:e67733ad4427 23 * *
HBP 8:e67733ad4427 24 * Block Flags: *
HBP 8:e67733ad4427 25 * 7:FBOF Begining of file *
HBP 8:e67733ad4427 26 * 6:LBOF Last block of file *
HBP 8:e67733ad4427 27 * 5:RO Read only file (Used only with FBOF) *
HBP 8:e67733ad4427 28 * 4:HIDDEN Hidden file (Used only with FBOF) *
HBP 8:e67733ad4427 29 * 3:INUSE Block in use *
HBP 8:e67733ad4427 30 * 2:NBAD Bad block (INV) *
HBP 8:e67733ad4427 31 * 1:VOL Volume label (Used only with FBOF) *
HBP 8:e67733ad4427 32 * 0:LOCK Locked file (Used only with FBOF) *
HBP 8:e67733ad4427 33 * *
HBP 8:e67733ad4427 34 * AUTHOR : Olli Vanhoja START DATE : 2011-02-18 *
HBP 8:e67733ad4427 35 ******************************************************************************
HBP 7:5ac5121bb4e0 36 *
HBP 7:5ac5121bb4e0 37 * CHANGES :
HBP 7:5ac5121bb4e0 38 *
HBP 7:5ac5121bb4e0 39 * VERSION DATE WHO DETAIL
HBP 7:5ac5121bb4e0 40 * 0.1 2011-02-21 Olli Vanhoja Initial release version
HBP 7:5ac5121bb4e0 41 * 0.2 2011-02-21 Olli Vanhoja Documentational comments added
HBP 7:5ac5121bb4e0 42 * 0.3 2011-02-21 Olli Vanhoja *File::read issues fixed, rewind/forward
HBP 7:5ac5121bb4e0 43 * functions improved
HBP 7:5ac5121bb4e0 44 * *Added possibility change I2C speed
HBP 7:5ac5121bb4e0 45 * *I2C autoreset on failure
HBP 7:5ac5121bb4e0 46 * 0.4 2011-02-22 Olli Vanhoja *mfs::renameFile(char [20], char [20] function added
HBP 9:52c01cb100ac 47 * *Incresed fault tolerance by first allocating new
HBP 9:52c01cb100ac 48 * block and then linking to it from previous block
HBP 7:5ac5121bb4e0 49 *
HBP 7:5ac5121bb4e0 50 * TODO :
HBP 9:52c01cb100ac 51 * *Directory support (VOL labeled blocks)
HBP 9:52c01cb100ac 52 * *Change 16bit integers to 32bit where it's possible
HBP 9:52c01cb100ac 53 *Support for >256 blocks
HBP 7:5ac5121bb4e0 54 *H*/
HBP 0:cbf45dde2b49 55
HBP 0:cbf45dde2b49 56 #ifndef MFS_H
HBP 0:cbf45dde2b49 57 #define MFS_H
HBP 0:cbf45dde2b49 58
HBP 0:cbf45dde2b49 59 #include "i2c_eeprom.h"
HBP 0:cbf45dde2b49 60
HBP 6:dd3346914d42 61 const unsigned int VOL_SIZE=65536; /**< EEPROM chip size in bytes */
HBP 6:dd3346914d42 62 const unsigned int BS=1024; /**< How many bytes per block (default: 4096 bytes) */
HBP 0:cbf45dde2b49 63 const unsigned int BC=VOL_SIZE / BS; // 128 blocks
HBP 0:cbf45dde2b49 64 const char mEOF='\x01'; // End Of File/Section marked
HBP 6:dd3346914d42 65 const unsigned int BUF=400; /**< File buffer length */
HBP 0:cbf45dde2b49 66
HBP 3:1cbc15648de1 67 /** mFS File System class
HBP 3:1cbc15648de1 68 *
HBP 3:1cbc15648de1 69 * This class is used as a handle for the fs in use.
HBP 3:1cbc15648de1 70 */
HBP 0:cbf45dde2b49 71 class mfs {
HBP 0:cbf45dde2b49 72 private:
HBP 0:cbf45dde2b49 73 i2c_eeprom *mem; // Only 512 kB I2C EEPROM is supported ATM
HBP 0:cbf45dde2b49 74 public:
HBP 3:1cbc15648de1 75 /** Create a new file system object
HBP 3:1cbc15648de1 76 *
HBP 3:1cbc15648de1 77 * @param xi2c_address a Physical I2C address of the EEPROM chip
HBP 3:1cbc15648de1 78 */
HBP 0:cbf45dde2b49 79 mfs(int i2c_address);
HBP 5:a0fe74dce80d 80
HBP 3:1cbc15648de1 81 /** Reads data from specified fs block
HBP 3:1cbc15648de1 82 *
HBP 3:1cbc15648de1 83 * @param *data Pointer for readed data
HBP 3:1cbc15648de1 84 * @param block Block number.
HBP 3:1cbc15648de1 85 * @param byte Selected byte.
HBP 3:1cbc15648de1 86 * @param n Bytes to be read.
HBP 3:1cbc15648de1 87 * @returns Error code. 0 = OK, 1 = Incorrect input
HBP 3:1cbc15648de1 88 */
HBP 9:52c01cb100ac 89 char read(char *data, char block, uint32_t byte, uint32_t n);
HBP 5:a0fe74dce80d 90
HBP 3:1cbc15648de1 91 /** Writes data to specified fs block
HBP 3:1cbc15648de1 92 *
HBP 3:1cbc15648de1 93 * @param *data Pointer for readed data
HBP 3:1cbc15648de1 94 * @param block Block number.
HBP 3:1cbc15648de1 95 * @param byte Selected byte.
HBP 3:1cbc15648de1 96 * @param n Bytes to be read.
HBP 3:1cbc15648de1 97 * @returns Error code. 0 = OK, 1 = Incorrect input
HBP 3:1cbc15648de1 98 */
HBP 9:52c01cb100ac 99 char write(char *data, char block, uint32_t byte, uint32_t n);
HBP 5:a0fe74dce80d 100
HBP 3:1cbc15648de1 101 /** Locate next free block
HBP 3:1cbc15648de1 102 *
HBP 3:1cbc15648de1 103 * @param *blockOut Returns next free block from begining of the fs.
HBP 3:1cbc15648de1 104 * @returns Error code. 0 = OK, 1 = Out of space
HBP 3:1cbc15648de1 105 */
HBP 3:1cbc15648de1 106 char getNextFreeBlock(char *blockOut);
HBP 5:a0fe74dce80d 107
HBP 3:1cbc15648de1 108 /** Locates next starting file from parameter block
HBP 3:1cbc15648de1 109 *
HBP 3:1cbc15648de1 110 * @param block Start scanning from this block.
HBP 3:1cbc15648de1 111 * @param *filenameOut Return name of the file found.
HBP 3:1cbc15648de1 112 * @returns Block number of the file found or 0xFFFF to indicate empty file system.
HBP 3:1cbc15648de1 113 */
HBP 9:52c01cb100ac 114 uint32_t findNextFile(char block, char *filenameOut);
HBP 5:a0fe74dce80d 115
HBP 3:1cbc15648de1 116 /** Get number of the first block of the given file. (FBOF flag)
HBP 3:1cbc15648de1 117 *
HBP 3:1cbc15648de1 118 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 119 * @returns Block number of the file or 0xFFFF to indicate that file not found.
HBP 3:1cbc15648de1 120 */
HBP 9:52c01cb100ac 121 uint32_t getFirstBlockOfFile(char filename[20]);
HBP 5:a0fe74dce80d 122
HBP 4:c77812997c9c 123 /** Create a new empty file
HBP 3:1cbc15648de1 124 *
HBP 3:1cbc15648de1 125 * Reserves one block for the file created.
HBP 3:1cbc15648de1 126 *
HBP 3:1cbc15648de1 127 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 128 * @returns Error code. 0 = OK, 1 = File exists already, 2 = Out of space
HBP 3:1cbc15648de1 129 */
HBP 0:cbf45dde2b49 130 char createFile(char filename[20]);
HBP 5:a0fe74dce80d 131
HBP 3:1cbc15648de1 132 /** Remove file from file system
HBP 3:1cbc15648de1 133 *
HBP 3:1cbc15648de1 134 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 135 * @returns Error code. 0 = OK, 1 = File doesn't exists
HBP 3:1cbc15648de1 136 */
HBP 0:cbf45dde2b49 137 char removeFile(char filename[20]);
HBP 5:a0fe74dce80d 138
HBP 7:5ac5121bb4e0 139 /** Rename file
HBP 7:5ac5121bb4e0 140 *
HBP 7:5ac5121bb4e0 141 * @param filename[20] Filename input.
HBP 7:5ac5121bb4e0 142 * @returns Error code. 0 = OK, 1 = File doesn't exists
HBP 7:5ac5121bb4e0 143 */
HBP 7:5ac5121bb4e0 144 char renameFile(char oldFilename[20], char newFilename[20]);
HBP 7:5ac5121bb4e0 145
HBP 3:1cbc15648de1 146 /** Set user modifiable flags.
HBP 3:1cbc15648de1 147 *
HBP 3:1cbc15648de1 148 * desc RO|HIDDEN|LOCK
HBP 3:1cbc15648de1 149 * bit 3 2 1
HBP 3:1cbc15648de1 150 *
HBP 3:1cbc15648de1 151 * @param *flags Flag input
HBP 3:1cbc15648de1 152 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 153 * @returns Error code. 0 = OK, 1 = File doesn't exists, 2 = File system is corrupted
HBP 3:1cbc15648de1 154 */
HBP 0:cbf45dde2b49 155 char setFileFlags(char *flags, char filename[20]);
HBP 5:a0fe74dce80d 156
HBP 3:1cbc15648de1 157 /** Read user modifiable flags.
HBP 3:1cbc15648de1 158 *
HBP 3:1cbc15648de1 159 * desc RO|HIDDEN|LOCK
HBP 3:1cbc15648de1 160 * bit 3 2 1
HBP 3:1cbc15648de1 161 *
HBP 3:1cbc15648de1 162 * @param *flags Flag output
HBP 3:1cbc15648de1 163 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 164 * @returns Error code. 0 = OK, 1 = File doesn't exists
HBP 3:1cbc15648de1 165 */
HBP 0:cbf45dde2b49 166 char getFileFlags(char *flags, char filename[20]);
HBP 5:a0fe74dce80d 167
HBP 3:1cbc15648de1 168 /** Get number of free blocks
HBP 3:1cbc15648de1 169 *
HBP 3:1cbc15648de1 170 * @returns Number of free blocks.
HBP 3:1cbc15648de1 171 */
HBP 9:52c01cb100ac 172 char free();
HBP 5:a0fe74dce80d 173
HBP 3:1cbc15648de1 174 /** Format new file system
HBP 3:1cbc15648de1 175 *
HBP 3:1cbc15648de1 176 *
HBP 3:1cbc15648de1 177 * @param createLabel Create volume label at the begining of the file system. (there is no specified use for volume labels atm).
HBP 3:1cbc15648de1 178 * @returns Number of bad block headers. Keep in mind that only first byte is checked and if it's broken the who file system is useless.
HBP 3:1cbc15648de1 179 */
HBP 3:1cbc15648de1 180 char mkfs(char createLabel);
HBP 0:cbf45dde2b49 181 };
HBP 0:cbf45dde2b49 182
HBP 4:c77812997c9c 183 /** mFS File handle class
HBP 4:c77812997c9c 184 *
HBP 5:a0fe74dce80d 185 * This class is used as a handle for files stored in mFS.
HBP 4:c77812997c9c 186 */
HBP 0:cbf45dde2b49 187 class file {
HBP 0:cbf45dde2b49 188 private:
HBP 0:cbf45dde2b49 189 mfs *fs; // Reference to the file system in use
HBP 0:cbf45dde2b49 190 char attr; // RW = 1; RO = 0
HBP 0:cbf45dde2b49 191 char buffer[BUF]; // Write buffer
HBP 9:52c01cb100ac 192 uint32_t bufPos; // "Cursor" position in buffer
HBP 0:cbf45dde2b49 193 char firstBlock; // First block of the file
HBP 0:cbf45dde2b49 194 char currBlock; // Current block in use
HBP 9:52c01cb100ac 195 uint32_t blockPos; // "head" position on the current block
HBP 0:cbf45dde2b49 196 public:
HBP 3:1cbc15648de1 197 /** Open new file handle
HBP 3:1cbc15648de1 198 *
HBP 9:52c01cb100ac 199 * \warning {File must be created before it can be opened!
HBP 9:52c01cb100ac 200 * Opening non-existing file will trip the system to error();}
HBP 3:1cbc15648de1 201 *
HBP 3:1cbc15648de1 202 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 203 * @param operation 0 = read only, 1 = read and write. If read only file is opened in rw mode system will trip to error().
HBP 3:1cbc15648de1 204 */
HBP 3:1cbc15648de1 205 file(mfs *fs_ref, char filename[20], char operation);
HBP 5:a0fe74dce80d 206
HBP 9:52c01cb100ac 207 /** Open new file handle with timed flush
HBP 9:52c01cb100ac 208 *
HBP 9:52c01cb100ac 209 * \warning {File must be created before it can be opened!
HBP 9:52c01cb100ac 210 * Opening non-existing file will trip the system to error();}
HBP 9:52c01cb100ac 211 *
HBP 9:52c01cb100ac 212 * @param filename[20] Filename input.
HBP 9:52c01cb100ac 213 * @param operation 0 = read only, 1 = read and write. If read only file is opened in rw mode system will trip to error().
HBP 9:52c01cb100ac 214 * @param autoFlushInterval Interval between flushes in seconds.
HBP 9:52c01cb100ac 215 */
HBP 9:52c01cb100ac 216 file(mfs *fs_ref, char filename[20], char operation, float autoFlushInterval);
HBP 9:52c01cb100ac 217
HBP 3:1cbc15648de1 218 /** Close file handle
HBP 3:1cbc15648de1 219 *
HBP 3:1cbc15648de1 220 * Flushes the file and closes the handle.
HBP 3:1cbc15648de1 221 */
HBP 0:cbf45dde2b49 222 ~file(); // Close file handle and flush
HBP 5:a0fe74dce80d 223
HBP 3:1cbc15648de1 224 /** Rewind to the start postion of the file
HBP 5:a0fe74dce80d 225 *
HBP 3:1cbc15648de1 226 */
HBP 3:1cbc15648de1 227 void rewind();
HBP 5:a0fe74dce80d 228
HBP 5:a0fe74dce80d 229 /** Rewind n bytes back
HBP 5:a0fe74dce80d 230 *
HBP 5:a0fe74dce80d 231 * @param n Number of blocks to be rewinded.
HBP 5:a0fe74dce80d 232 * @returns Error code. 0 = OK, 1 = First block of file.
HBP 5:a0fe74dce80d 233 */
HBP 9:52c01cb100ac 234 char rewind(uint32_t n);
HBP 5:a0fe74dce80d 235
HBP 5:a0fe74dce80d 236 /** Forward one byte
HBP 5:a0fe74dce80d 237 *
HBP 5:a0fe74dce80d 238 * @returns Error code. 0 = OK, 1 = End of file.
HBP 3:1cbc15648de1 239 */
HBP 3:1cbc15648de1 240 char forward();
HBP 5:a0fe74dce80d 241
HBP 5:a0fe74dce80d 242 /** Forward n bytes
HBP 5:a0fe74dce80d 243 *
HBP 5:a0fe74dce80d 244 * @param n Number of blocks.
HBP 5:a0fe74dce80d 245 * @returns Error code. 0 = OK, 1 = End of file.
HBP 5:a0fe74dce80d 246 */
HBP 9:52c01cb100ac 247 char forward(uint32_t n);
HBP 5:a0fe74dce80d 248
HBP 3:1cbc15648de1 249 /** Reads a string of bytes
HBP 3:1cbc15648de1 250 *
HBP 3:1cbc15648de1 251 * Always places '\0' at the end of string.
HBP 3:1cbc15648de1 252 *
HBP 3:1cbc15648de1 253 * @param data Output buffer.
HBP 3:1cbc15648de1 254 * @param n Number of bytes to be read.
HBP 5:a0fe74dce80d 255 * @returns Error code. 0 = OK, 1 = Last block of the file
HBP 3:1cbc15648de1 256 */
HBP 9:52c01cb100ac 257 void read(char *data, uint32_t n);
HBP 3:1cbc15648de1 258 /** Reads a binary array of bytes
HBP 3:1cbc15648de1 259 *
HBP 3:1cbc15648de1 260 * Doesn't add '\0' at the end of data array and doesn't respect mEOF byte.
HBP 3:1cbc15648de1 261 *
HBP 3:1cbc15648de1 262 * @param data Output buffer.
HBP 3:1cbc15648de1 263 * @param n Number of bytes to be read.
HBP 3:1cbc15648de1 264 */
HBP 5:a0fe74dce80d 265
HBP 9:52c01cb100ac 266 void readBin(char *data, uint32_t n);
HBP 3:1cbc15648de1 267 /** Write byte array to a file (buffer)
HBP 3:1cbc15648de1 268 *
HBP 3:1cbc15648de1 269 * @param data Input data.
HBP 3:1cbc15648de1 270 * @param n Number of bytes to be read.
HBP 3:1cbc15648de1 271 * @returns Error code. 0 = OK, 1 = Flush failed.
HBP 3:1cbc15648de1 272 */
HBP 5:a0fe74dce80d 273
HBP 9:52c01cb100ac 274 char write(char *data, uint32_t n);
HBP 5:a0fe74dce80d 275
HBP 3:1cbc15648de1 276 /** Flush file buffer
HBP 3:1cbc15648de1 277 * Writes buffer to the EEPROM chip in use.
HBP 3:1cbc15648de1 278 */
HBP 0:cbf45dde2b49 279 char flush();
HBP 0:cbf45dde2b49 280 };
HBP 0:cbf45dde2b49 281
HBP 0:cbf45dde2b49 282 #endif