Olli Vanhoja / mFS

mFS file system library for EEPROM memory chips.

mfs.h@6:dd3346914d42, 2011-02-21 (annotated)

Committer:
HBP
Date:
Mon Feb 21 18:34:40 2011 +0000
Revision:
6:dd3346914d42
Parent:
5:a0fe74dce80d
Child:
7:5ac5121bb4e0
updated some comments...

Who changed what in which revision?

UserRevisionLine numberNew contents of line
HBP 5:a0fe74dce80d 1 /** @file mfs.h */
HBP 0:cbf45dde2b49 2 /*H****************************************************************************
HBP 0:cbf45dde2b49 3 * FILENAME : mfs.h *
HBP 0:cbf45dde2b49 4 * *
HBP 0:cbf45dde2b49 5 * DESCRIPTION : *
HBP 0:cbf45dde2b49 6 * mFS file system implementation for mBED with external I2C EEEPROM. *
HBP 0:cbf45dde2b49 7 * *
HBP 0:cbf45dde2b49 8 * Block Flags: *
HBP 0:cbf45dde2b49 9 * 7:FBOF Begining of file *
HBP 0:cbf45dde2b49 10 * 6:LBOF Last block of file *
HBP 0:cbf45dde2b49 11 * 5:RO Read only file (Used only with FBOF) *
HBP 0:cbf45dde2b49 12 * 4:HIDDEN Hidden file (Used only with FBOF) *
HBP 0:cbf45dde2b49 13 * 3:INUSE Block in use *
HBP 0:cbf45dde2b49 14 * 2:NBAD Bad block (INV) *
HBP 0:cbf45dde2b49 15 * 1:VOL Volume label (Used only with FBOF) *
HBP 0:cbf45dde2b49 16 * 0:LOCK Locked file (Used only with FBOF) *
HBP 0:cbf45dde2b49 17 * *
HBP 0:cbf45dde2b49 18 * AUTHOR : Olli Vanhoja START DATE : 2011-02-18 *
HBP 0:cbf45dde2b49 19 *******************************************************************************
HBP 0:cbf45dde2b49 20 *
HBP 0:cbf45dde2b49 21 * CHANGES :
HBP 0:cbf45dde2b49 22 *
HBP 5:a0fe74dce80d 23 * VERSION DATE WHO DETAIL
HBP 5:a0fe74dce80d 24 * 0.1 2011-02-21 Olli Vanhoja Initial release version
HBP 5:a0fe74dce80d 25 * 0.2 2011-02-21 Olli Vanhoja Documentational comments added
HBP 5:a0fe74dce80d 26 * 0.3 2011-02-21 Olli Vanhoja *File::read issues fixed, rewind/forward
HBP 5:a0fe74dce80d 27 * functions improved
HBP 5:a0fe74dce80d 28 * *Added possibility change I2C speed
HBP 5:a0fe74dce80d 29 * *I2C autoreset on failure
HBP 0:cbf45dde2b49 30 *
HBP 0:cbf45dde2b49 31 *H*/
HBP 0:cbf45dde2b49 32
HBP 0:cbf45dde2b49 33 #ifndef MFS_H
HBP 0:cbf45dde2b49 34 #define MFS_H
HBP 0:cbf45dde2b49 35
HBP 0:cbf45dde2b49 36 #include "i2c_eeprom.h"
HBP 0:cbf45dde2b49 37
HBP 6:dd3346914d42 38 const unsigned int VOL_SIZE=65536; /**< EEPROM chip size in bytes */
HBP 6:dd3346914d42 39 const unsigned int BS=1024; /**< How many bytes per block (default: 4096 bytes) */
HBP 0:cbf45dde2b49 40 const unsigned int BC=VOL_SIZE / BS; // 128 blocks
HBP 0:cbf45dde2b49 41 const char mEOF='\x01'; // End Of File/Section marked
HBP 6:dd3346914d42 42 const unsigned int BUF=400; /**< File buffer length */
HBP 0:cbf45dde2b49 43
HBP 0:cbf45dde2b49 44 typedef unsigned short int uint16;
HBP 0:cbf45dde2b49 45
HBP 3:1cbc15648de1 46 /** mFS File System class
HBP 3:1cbc15648de1 47 *
HBP 3:1cbc15648de1 48 * This class is used as a handle for the fs in use.
HBP 3:1cbc15648de1 49 */
HBP 0:cbf45dde2b49 50 class mfs {
HBP 0:cbf45dde2b49 51 private:
HBP 0:cbf45dde2b49 52 i2c_eeprom *mem; // Only 512 kB I2C EEPROM is supported ATM
HBP 0:cbf45dde2b49 53 public:
HBP 3:1cbc15648de1 54 /** Create a new file system object
HBP 3:1cbc15648de1 55 *
HBP 3:1cbc15648de1 56 * @param xi2c_address a Physical I2C address of the EEPROM chip
HBP 3:1cbc15648de1 57 */
HBP 0:cbf45dde2b49 58 mfs(int i2c_address);
HBP 5:a0fe74dce80d 59
HBP 3:1cbc15648de1 60 /** Reads data from specified fs block
HBP 3:1cbc15648de1 61 *
HBP 3:1cbc15648de1 62 * @param *data Pointer for readed data
HBP 3:1cbc15648de1 63 * @param block Block number.
HBP 3:1cbc15648de1 64 * @param byte Selected byte.
HBP 3:1cbc15648de1 65 * @param n Bytes to be read.
HBP 3:1cbc15648de1 66 * @returns Error code. 0 = OK, 1 = Incorrect input
HBP 3:1cbc15648de1 67 */
HBP 5:a0fe74dce80d 68 char read(char *data, char block, unsigned int byte, unsigned int n);
HBP 5:a0fe74dce80d 69
HBP 3:1cbc15648de1 70 /** Writes data to specified fs block
HBP 3:1cbc15648de1 71 *
HBP 3:1cbc15648de1 72 * @param *data Pointer for readed data
HBP 3:1cbc15648de1 73 * @param block Block number.
HBP 3:1cbc15648de1 74 * @param byte Selected byte.
HBP 3:1cbc15648de1 75 * @param n Bytes to be read.
HBP 3:1cbc15648de1 76 * @returns Error code. 0 = OK, 1 = Incorrect input
HBP 3:1cbc15648de1 77 */
HBP 5:a0fe74dce80d 78 char write(char *data, char block, unsigned int byte, unsigned int n);
HBP 5:a0fe74dce80d 79
HBP 3:1cbc15648de1 80 /** Locate next free block
HBP 3:1cbc15648de1 81 *
HBP 3:1cbc15648de1 82 * @param *blockOut Returns next free block from begining of the fs.
HBP 3:1cbc15648de1 83 * @returns Error code. 0 = OK, 1 = Out of space
HBP 3:1cbc15648de1 84 */
HBP 3:1cbc15648de1 85 char getNextFreeBlock(char *blockOut);
HBP 5:a0fe74dce80d 86
HBP 3:1cbc15648de1 87 /** Locates next starting file from parameter block
HBP 3:1cbc15648de1 88 *
HBP 3:1cbc15648de1 89 * @param block Start scanning from this block.
HBP 3:1cbc15648de1 90 * @param *filenameOut Return name of the file found.
HBP 3:1cbc15648de1 91 * @returns Block number of the file found or 0xFFFF to indicate empty file system.
HBP 3:1cbc15648de1 92 */
HBP 5:a0fe74dce80d 93 unsigned int findNextFile(unsigned int block, char *filenameOut);
HBP 5:a0fe74dce80d 94
HBP 3:1cbc15648de1 95 /** Get number of the first block of the given file. (FBOF flag)
HBP 3:1cbc15648de1 96 *
HBP 3:1cbc15648de1 97 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 98 * @returns Block number of the file or 0xFFFF to indicate that file not found.
HBP 3:1cbc15648de1 99 */
HBP 0:cbf45dde2b49 100 uint16 getFirstBlockOfFile(char filename[20]);
HBP 5:a0fe74dce80d 101
HBP 4:c77812997c9c 102 /** Create a new empty file
HBP 3:1cbc15648de1 103 *
HBP 3:1cbc15648de1 104 * Reserves one block for the file created.
HBP 3:1cbc15648de1 105 *
HBP 3:1cbc15648de1 106 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 107 * @returns Error code. 0 = OK, 1 = File exists already, 2 = Out of space
HBP 3:1cbc15648de1 108 */
HBP 0:cbf45dde2b49 109 char createFile(char filename[20]);
HBP 5:a0fe74dce80d 110
HBP 3:1cbc15648de1 111 /** Remove file from file system
HBP 3:1cbc15648de1 112 *
HBP 3:1cbc15648de1 113 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 114 * @returns Error code. 0 = OK, 1 = File doesn't exists
HBP 3:1cbc15648de1 115 */
HBP 0:cbf45dde2b49 116 char removeFile(char filename[20]);
HBP 5:a0fe74dce80d 117
HBP 3:1cbc15648de1 118 /** Set user modifiable flags.
HBP 3:1cbc15648de1 119 *
HBP 3:1cbc15648de1 120 * desc RO|HIDDEN|LOCK
HBP 3:1cbc15648de1 121 * bit 3 2 1
HBP 3:1cbc15648de1 122 *
HBP 3:1cbc15648de1 123 * @param *flags Flag input
HBP 3:1cbc15648de1 124 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 125 * @returns Error code. 0 = OK, 1 = File doesn't exists, 2 = File system is corrupted
HBP 3:1cbc15648de1 126 */
HBP 0:cbf45dde2b49 127 char setFileFlags(char *flags, char filename[20]);
HBP 5:a0fe74dce80d 128
HBP 3:1cbc15648de1 129 /** Read user modifiable flags.
HBP 3:1cbc15648de1 130 *
HBP 3:1cbc15648de1 131 * desc RO|HIDDEN|LOCK
HBP 3:1cbc15648de1 132 * bit 3 2 1
HBP 3:1cbc15648de1 133 *
HBP 3:1cbc15648de1 134 * @param *flags Flag output
HBP 3:1cbc15648de1 135 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 136 * @returns Error code. 0 = OK, 1 = File doesn't exists
HBP 3:1cbc15648de1 137 */
HBP 0:cbf45dde2b49 138 char getFileFlags(char *flags, char filename[20]);
HBP 5:a0fe74dce80d 139
HBP 3:1cbc15648de1 140 /** Get number of free blocks
HBP 3:1cbc15648de1 141 *
HBP 3:1cbc15648de1 142 * @returns Number of free blocks.
HBP 3:1cbc15648de1 143 */
HBP 0:cbf45dde2b49 144 uint16 free();
HBP 5:a0fe74dce80d 145
HBP 3:1cbc15648de1 146 /** Format new file system
HBP 3:1cbc15648de1 147 *
HBP 3:1cbc15648de1 148 *
HBP 3:1cbc15648de1 149 * @param createLabel Create volume label at the begining of the file system. (there is no specified use for volume labels atm).
HBP 3:1cbc15648de1 150 * @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 151 */
HBP 3:1cbc15648de1 152 char mkfs(char createLabel);
HBP 0:cbf45dde2b49 153 };
HBP 0:cbf45dde2b49 154
HBP 4:c77812997c9c 155 /** mFS File handle class
HBP 4:c77812997c9c 156 *
HBP 5:a0fe74dce80d 157 * This class is used as a handle for files stored in mFS.
HBP 4:c77812997c9c 158 */
HBP 0:cbf45dde2b49 159 class file {
HBP 0:cbf45dde2b49 160 private:
HBP 0:cbf45dde2b49 161 mfs *fs; // Reference to the file system in use
HBP 0:cbf45dde2b49 162 char attr; // RW = 1; RO = 0
HBP 0:cbf45dde2b49 163 char buffer[BUF]; // Write buffer
HBP 0:cbf45dde2b49 164 unsigned int bufPos; // "Cursor" position in buffer
HBP 0:cbf45dde2b49 165 char firstBlock; // First block of the file
HBP 0:cbf45dde2b49 166 char currBlock; // Current block in use
HBP 0:cbf45dde2b49 167 unsigned int blockPos; // "head" position on the current block
HBP 0:cbf45dde2b49 168 void needsFlush(); // check if flush is needed before read operation
HBP 0:cbf45dde2b49 169 public:
HBP 3:1cbc15648de1 170 /** Open new file handle
HBP 3:1cbc15648de1 171 *
HBP 3:1cbc15648de1 172 * File must be created before it can be opened!
HBP 3:1cbc15648de1 173 *
HBP 3:1cbc15648de1 174 * @param filename[20] Filename input.
HBP 3:1cbc15648de1 175 * @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 176 */
HBP 3:1cbc15648de1 177 file(mfs *fs_ref, char filename[20], char operation);
HBP 5:a0fe74dce80d 178
HBP 3:1cbc15648de1 179 /** Close file handle
HBP 3:1cbc15648de1 180 *
HBP 3:1cbc15648de1 181 * Flushes the file and closes the handle.
HBP 3:1cbc15648de1 182 */
HBP 0:cbf45dde2b49 183 ~file(); // Close file handle and flush
HBP 5:a0fe74dce80d 184
HBP 3:1cbc15648de1 185 /** Rewind to the start postion of the file
HBP 5:a0fe74dce80d 186 *
HBP 3:1cbc15648de1 187 */
HBP 3:1cbc15648de1 188 void rewind();
HBP 5:a0fe74dce80d 189
HBP 5:a0fe74dce80d 190 /** Rewind n bytes back
HBP 5:a0fe74dce80d 191 *
HBP 5:a0fe74dce80d 192 * @param n Number of blocks to be rewinded.
HBP 5:a0fe74dce80d 193 * @returns Error code. 0 = OK, 1 = First block of file.
HBP 5:a0fe74dce80d 194 */
HBP 5:a0fe74dce80d 195 char rewind(uint16 n);
HBP 5:a0fe74dce80d 196
HBP 5:a0fe74dce80d 197 /** Forward one byte
HBP 5:a0fe74dce80d 198 *
HBP 5:a0fe74dce80d 199 * @returns Error code. 0 = OK, 1 = End of file.
HBP 3:1cbc15648de1 200 */
HBP 3:1cbc15648de1 201 char forward();
HBP 5:a0fe74dce80d 202
HBP 5:a0fe74dce80d 203 /** Forward n bytes
HBP 5:a0fe74dce80d 204 *
HBP 5:a0fe74dce80d 205 * @param n Number of blocks.
HBP 5:a0fe74dce80d 206 * @returns Error code. 0 = OK, 1 = End of file.
HBP 5:a0fe74dce80d 207 */
HBP 5:a0fe74dce80d 208 char forward(uint16 n);
HBP 5:a0fe74dce80d 209
HBP 3:1cbc15648de1 210 /** Reads a string of bytes
HBP 3:1cbc15648de1 211 *
HBP 3:1cbc15648de1 212 * Always places '\0' at the end of string.
HBP 3:1cbc15648de1 213 *
HBP 3:1cbc15648de1 214 * @param data Output buffer.
HBP 3:1cbc15648de1 215 * @param n Number of bytes to be read.
HBP 5:a0fe74dce80d 216 * @returns Error code. 0 = OK, 1 = Last block of the file
HBP 3:1cbc15648de1 217 */
HBP 0:cbf45dde2b49 218 void read(char *data, unsigned int n);
HBP 3:1cbc15648de1 219 /** Reads a binary array of bytes
HBP 3:1cbc15648de1 220 *
HBP 3:1cbc15648de1 221 * Doesn't add '\0' at the end of data array and doesn't respect mEOF byte.
HBP 3:1cbc15648de1 222 *
HBP 3:1cbc15648de1 223 * @param data Output buffer.
HBP 3:1cbc15648de1 224 * @param n Number of bytes to be read.
HBP 3:1cbc15648de1 225 */
HBP 5:a0fe74dce80d 226
HBP 0:cbf45dde2b49 227 void readBin(char *data, unsigned int n);
HBP 3:1cbc15648de1 228 /** Write byte array to a file (buffer)
HBP 3:1cbc15648de1 229 *
HBP 3:1cbc15648de1 230 * @param data Input data.
HBP 3:1cbc15648de1 231 * @param n Number of bytes to be read.
HBP 3:1cbc15648de1 232 * @returns Error code. 0 = OK, 1 = Flush failed.
HBP 3:1cbc15648de1 233 */
HBP 5:a0fe74dce80d 234
HBP 3:1cbc15648de1 235 char write(char *data, unsigned int n);
HBP 5:a0fe74dce80d 236
HBP 3:1cbc15648de1 237 /** Flush file buffer
HBP 3:1cbc15648de1 238 * Writes buffer to the EEPROM chip in use.
HBP 3:1cbc15648de1 239 */
HBP 0:cbf45dde2b49 240 char flush();
HBP 0:cbf45dde2b49 241 };
HBP 0:cbf45dde2b49 242
HBP 0:cbf45dde2b49 243 #endif