Olli Vanhoja
mFS file system library for EEPROM memory chips.
Diff: mfs.h
- Revision:
- 10:211cb54339a0
- Parent:
- 9:52c01cb100ac
- Child:
- 11:6c4fcb9d6193
--- a/mfs.h Tue Feb 22 18:57:37 2011 +0000
+++ b/mfs.h Tue Feb 22 21:09:04 2011 +0000
@@ -39,18 +39,23 @@
* VERSION DATE WHO DETAIL
* 0.1 2011-02-21 Olli Vanhoja Initial release version
* 0.2 2011-02-21 Olli Vanhoja Documentational comments added
- * 0.3 2011-02-21 Olli Vanhoja *File::read issues fixed, rewind/forward
- * functions improved
- * *Added possibility change I2C speed
- * *I2C autoreset on failure
- * 0.4 2011-02-22 Olli Vanhoja *mfs::renameFile(char [20], char [20] function added
- * *Incresed fault tolerance by first allocating new
- * block and then linking to it from previous block
+ * 0.3 2011-02-21 Olli Vanhoja * File::read issues fixed, rewind/forward
+ * functions improved
+ * * Added possibility change I2C speed
+ * * I2C autoreset on failure
+ * 0.4 2011-02-22 Olli Vanhoja * mfs::renameFile(char [20], char [20] function added
+ * * Incresed fault tolerance by first allocating new
+ * block and then linking to it from previous block
+ * * Reconstructed initialization and use of some variables
+ * 0.5 2011-02-22 Olli Vanhoja * Improved documentation
+ * * Block variables changed from char to uint32_t for
+ * code optimization (and for possible 16bit update which
+ would technically allow 256 TB volume sizes)
+ * * Optimized file searching algorithms
*
* TODO :
- * *Directory support (VOL labeled blocks)
- * *Change 16bit integers to 32bit where it's possible
- *Support for >256 blocks
+ * * Directory support (VOL blocks?)
+ * * Support for >256 blocks
*H*/
#ifndef MFS_H
@@ -60,7 +65,7 @@
const unsigned int VOL_SIZE=65536; /**< EEPROM chip size in bytes */
const unsigned int BS=1024; /**< How many bytes per block (default: 4096 bytes) */
-const unsigned int BC=VOL_SIZE / BS; // 128 blocks
+const unsigned int BC=VOL_SIZE / BS; // block count
const char mEOF='\x01'; // End Of File/Section marked
const unsigned int BUF=400; /**< File buffer length */
@@ -78,90 +83,99 @@
*/
mfs(int i2c_address);
- /** Reads data from specified fs block
+ /** Read data from specified fs block
*
* @param *data Pointer for readed data
* @param block Block number.
* @param byte Selected byte.
* @param n Bytes to be read.
- * @returns Error code. 0 = OK, 1 = Incorrect input
+ * @returns Error code: 0 = OK, 1 = Incorrect input
*/
- char read(char *data, char block, uint32_t byte, uint32_t n);
+ char read(char *data, uint32_t block, uint32_t byte, uint32_t n);
- /** Writes data to specified fs block
+ /** Write data to specified fs block
*
* @param *data Pointer for readed data
* @param block Block number.
* @param byte Selected byte.
* @param n Bytes to be read.
- * @returns Error code. 0 = OK, 1 = Incorrect input
+ * @returns Error code: 0 = OK, 1 = Incorrect input
*/
- char write(char *data, char block, uint32_t byte, uint32_t n);
+ char write(char *data, uint32_t block, uint32_t byte, uint32_t n);
/** Locate next free block
*
* @param *blockOut Returns next free block from begining of the fs.
- * @returns Error code. 0 = OK, 1 = Out of space
+ * @returns Error code: 0 = OK, 1 = Out of space
*/
- char getNextFreeBlock(char *blockOut);
+ char getNextFreeBlock(uint32_t *blockOut);
/** Locates next starting file from parameter block
*
* @param block Start scanning from this block.
* @param *filenameOut Return name of the file found.
- * @returns Block number of the file found or 0xFFFF to indicate empty file system.
+ * @param Returns block number of the file found.
+ * @returns Error code: 0 = OK, 1 = Empty fs
*/
- uint32_t findNextFile(char block, char *filenameOut);
+ char findNextFile(uint32_t block, char *filenameOut, uint32_t *blockOut);
- /** Get number of the first block of the given file. (FBOF flag)
+ /** Get block number of the given file
+ *
+ * Returns block number of the block flaged with FBOF flag.
*
* @param filename[20] Filename input.
- * @returns Block number of the file or 0xFFFF to indicate that file not found.
+ * @param Returns block number of the first block of the given file.
+ * @returns Error code: 0 = OK, 1 = File not found
*/
- uint32_t getFirstBlockOfFile(char filename[20]);
+ char getFirstBlockOfFile(char filename[20], uint32_t *blockOut);
/** Create a new empty file
*
* Reserves one block for the file created.
*
* @param filename[20] Filename input.
- * @returns Error code. 0 = OK, 1 = File exists already, 2 = Out of space
+ * @returns Error code: 0 = OK, 1 = File exists already, 2 = Out of space
*/
char createFile(char filename[20]);
- /** Remove file from file system
+ /** Remove a file from the file system
*
* @param filename[20] Filename input.
- * @returns Error code. 0 = OK, 1 = File doesn't exists
+ * @returns Error code: 0 = OK, 1 = File doesn't exists
*/
char removeFile(char filename[20]);
- /** Rename file
+ /** Rename a file
*
- * @param filename[20] Filename input.
- * @returns Error code. 0 = OK, 1 = File doesn't exists
+ * @param oldFilename[20] Old filename.
+ * @param newFilename[20] New file name.
+ * @returns Error code: 0 = OK, 1 = File doesn't exists
*/
char renameFile(char oldFilename[20], char newFilename[20]);
/** Set user modifiable flags.
*
+ * \code
* desc RO|HIDDEN|LOCK
* bit 3 2 1
+ * \endcode
*
* @param *flags Flag input
* @param filename[20] Filename input.
- * @returns Error code. 0 = OK, 1 = File doesn't exists, 2 = File system is corrupted
+ * @returns Error code: 0 = OK, 1 = File doesn't exists, 2 = File system is corrupted
*/
char setFileFlags(char *flags, char filename[20]);
/** Read user modifiable flags.
*
+ * \code
* desc RO|HIDDEN|LOCK
* bit 3 2 1
+ * \endcode
*
* @param *flags Flag output
* @param filename[20] Filename input.
- * @returns Error code. 0 = OK, 1 = File doesn't exists
+ * @returns Error code: 0 = OK, 1 = File doesn't exists
*/
char getFileFlags(char *flags, char filename[20]);
@@ -169,20 +183,23 @@
*
* @returns Number of free blocks.
*/
- char free();
+ uint32_t free();
/** Format new file system
*
+ * \note Keep in mind that only first byte is checked for functionality and
+ * if it's broken the who file system is useless.
*
* @param createLabel Create volume label at the begining of the file system. (there is no specified use for volume labels atm).
- * @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.
+ * @returns Number of bad block headers.
*/
- char mkfs(char createLabel);
+ uint32_t mkfs(bool createLabel);
};
/** mFS File handle class
*
- * This class is used as a handle for files stored in mFS.
+ * This class provides a file handle and data manipulation methods to be
+ * used for files stored in mFS files system.
*/
class file {
private:
@@ -194,27 +211,17 @@
char currBlock; // Current block in use
uint32_t blockPos; // "head" position on the current block
public:
- /** Open new file handle
+ /** Create file handle
*
- * \warning {File must be created before it can be opened!
- * Opening non-existing file will trip the system to error();}
+ * \warning File must be created before it can be opened!
+ * Opening non-existing file will trip the system to error();
+ * If read only file is opened in rw mode system will trip to error().
*
* @param filename[20] Filename input.
- * @param operation 0 = read only, 1 = read and write. If read only file is opened in rw mode system will trip to error().
+ * @param operation 0 = read only, 1 = read and write.
*/
file(mfs *fs_ref, char filename[20], char operation);
- /** Open new file handle with timed flush
- *
- * \warning {File must be created before it can be opened!
- * Opening non-existing file will trip the system to error();}
- *
- * @param filename[20] Filename input.
- * @param operation 0 = read only, 1 = read and write. If read only file is opened in rw mode system will trip to error().
- * @param autoFlushInterval Interval between flushes in seconds.
- */
- file(mfs *fs_ref, char filename[20], char operation, float autoFlushInterval);
-
/** Close file handle
*
* Flushes the file and closes the handle.
@@ -229,20 +236,20 @@
/** Rewind n bytes back
*
* @param n Number of blocks to be rewinded.
- * @returns Error code. 0 = OK, 1 = First block of file.
+ * @returns Error code: 0 = OK, 1 = First block of file.
*/
char rewind(uint32_t n);
/** Forward one byte
*
- * @returns Error code. 0 = OK, 1 = End of file.
+ * @returns Error code: 0 = OK, 1 = End of file.
*/
char forward();
/** Forward n bytes
*
* @param n Number of blocks.
- * @returns Error code. 0 = OK, 1 = End of file.
+ * @returns Error code: 0 = OK, 1 = End of file.
*/
char forward(uint32_t n);
@@ -268,7 +275,7 @@
*
* @param data Input data.
* @param n Number of bytes to be read.
- * @returns Error code. 0 = OK, 1 = Flush failed.
+ * @returns Error code: 0 = OK, 1 = Flush failed.
*/
char write(char *data, uint32_t n);