Diff: QSPIFileSystem.h

Revision:

2:1c6134c80dc5

Parent:

0:0fdadbc3d852

Child:

10:f2409dc07e49

--- a/QSPIFileSystem.h	Thu Sep 26 08:25:49 2013 +0000
+++ b/QSPIFileSystem.h	Fri Sep 27 14:07:07 2013 +0000
@@ -6,6 +6,10 @@
 
 /** Access the filesystem on an QSPI flash using SPIFI
  *
+ * One way to utilize the 8MByte of QSPI FLASH on the LPC4088 QuickStart Board 
+ * is to place a file system on it. The QSPIFileSystem is using the
+ * FileSystemLike interface making using it is as simple as:
+ *
  * @code
  * #include "mbed.h"
  * #include "QSPIFileSystem.h"
@@ -24,6 +28,70 @@
  *     }
  * }
  * @endcode
+ *
+ * The file system can be formatted to a specific size in increments of 1MByte 
+ * and will allways be placed at the top of the address range. For the 8 MByte 
+ * memory on the LPC4088 QuickStart Board this means:
+ * 
+ * <pre>
+ *                    0x28000000                                               0x28800000
+ *                         |------|------|------|------|------|------|------|------|
+ * qspifs.format(1)        |   available for program                        |  FS  |
+ *                         |------|------|------|------|------|------|------|------|
+ *                                                                                  </pre><pre>
+ *                         |------|------|------|------|------|------|------|------|
+ * qspifs.format(2)        |   available for program                 | FileSystem  |
+ *                         |------|------|------|------|------|------|------|------|
+ *                                                                                  </pre><pre>
+ *                         |------|------|------|------|------|------|------|------|
+ * qspifs.format(7)        | PROG |                 FileSystem                     |
+ *                         |------|------|------|------|------|------|------|------|
+ *                                                                                  </pre><pre>
+ *                         |------|------|------|------|------|------|------|------|
+ * qspifs.format(8)        |                       FileSystem                      |
+ *                         |------|------|------|------|------|------|------|------|
+ * </pre>
+ * The file system must be placed at the top of the memory because the linker scripts 
+ * places your program at the bottom of the memory (if needed).
+ *
+ * The file system is using one or more blocks (each the size of one erase block) per 
+ * file. Each file is stored in a sequence of blocks. If a file is written to so that 
+ * it's size will occupy more than one block and the block after is already used by
+ * a different file the entire file will be moved, like this:
+ *
+ * <pre>
+ *                   |-------|-------|-------|-------|-------|-------|-------|
+ * Before            |///////| FILE1 | FILE2 | FILE3 |///////|///////|///////|
+ *                   |-------|-------|-------|-------|-------|-------|-------|
+ *                                                                            </pre><pre>
+ * After writing     |-------|-------|-------|-------|-------|-------|-------|
+ * to FILE2          |///////| FILE1 |///////| FILE3 |     FILE2     |///////|
+ *                   |-------|-------|-------|-------|-------|-------|-------|
+ * </pre>
+ *
+ * <b>Note: </b>As each file takes up at least one block it will limit the total number of files that
+ * can be stored on the file system. The formula for this is roughly 
+ * <pre>
+ *          max_num_files = fs_size_in_bytes / erase_block_size
+ * </pre>
+ * For the SPI flash on the LPC4088 QuickStart Board it means
+ * <pre>
+ *          max_num_files = 8MByte / 4KByte = 2048
+ * </pre>
+ *
+ * Some of the blocks are used to store the table of content (TOC) at the very end of
+ * the spi flash. The TOC will contain a list of all blocks on the flash (even those
+ * not used by the file system) and will mark each block as "reserved","in use" or "free".
+ * For a file system that is 4MByte on a 8MByte flash half of the blocks will be marked
+ * as "reserved".
+ * 
+ * <b>Note: </b>The file system will not store any date/time information.
+ *
+ * <b>Note: </b>The file system will not store any file attributes (hidden/system/read only).
+ *
+ * <b>Note: </b>The file system stores the absolute path of each file (path + file name) in 
+ * the file's first block's first 256 bytes. Folders are never stored themselves. This has 
+ * the drawback that the file system cannot hold empty folders. 
  */
 class QSPIFileSystem : public FileSystemLike {
 public: