Olli Vanhoja / mFS

mFS file system library for EEPROM memory chips.

mfs.h@3:1cbc15648de1, 2011-02-21 (annotated)

Committer:
HBP
Date:
Mon Feb 21 09:51:05 2011 +0000
Revision:
3:1cbc15648de1
Parent:
0:cbf45dde2b49
Child:
4:c77812997c9c
Documentational comments added.

Who changed what in which revision?

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