IONX / EALib

Update version of EALib.

Dependencies:   FATFileSystem

Fork of EALib by IONX

QSPIFileSystem.h@2:1c6134c80dc5, 2013-09-27 (annotated)

Committer:
embeddedartists
Date:
Fri Sep 27 14:07:07 2013 +0000
Revision:
2:1c6134c80dc5
Parent:
0:0fdadbc3d852
Child:
10:f2409dc07e49
Added documentation of QSPIFileSystem

Who changed what in which revision?

UserRevisionLine numberNew contents of line
embeddedartists 0:0fdadbc3d852 1 #ifndef QSPIFILESYSTEM_H
embeddedartists 0:0fdadbc3d852 2 #define QSPIFILESYSTEM_H
embeddedartists 0:0fdadbc3d852 3
embeddedartists 0:0fdadbc3d852 4 #include "mbed.h"
embeddedartists 0:0fdadbc3d852 5 #include "FileSystemLike.h"
embeddedartists 0:0fdadbc3d852 6
embeddedartists 0:0fdadbc3d852 7 /** Access the filesystem on an QSPI flash using SPIFI
embeddedartists 0:0fdadbc3d852 8 *
embeddedartists 2:1c6134c80dc5 9 * One way to utilize the 8MByte of QSPI FLASH on the LPC4088 QuickStart Board
embeddedartists 2:1c6134c80dc5 10 * is to place a file system on it. The QSPIFileSystem is using the
embeddedartists 2:1c6134c80dc5 11 * FileSystemLike interface making using it is as simple as:
embeddedartists 2:1c6134c80dc5 12 *
embeddedartists 0:0fdadbc3d852 13 * @code
embeddedartists 0:0fdadbc3d852 14 * #include "mbed.h"
embeddedartists 0:0fdadbc3d852 15 * #include "QSPIFileSystem.h"
embeddedartists 0:0fdadbc3d852 16 *
embeddedartists 0:0fdadbc3d852 17 * QSPIFileSystem qspi("qspi");
embeddedartists 0:0fdadbc3d852 18 *
embeddedartists 0:0fdadbc3d852 19 * int main() {
embeddedartists 0:0fdadbc3d852 20 * if (!qspifs.isFormatted()) {
embeddedartists 0:0fdadbc3d852 21 * qspifs.format();
embeddedartists 0:0fdadbc3d852 22 * }
embeddedartists 0:0fdadbc3d852 23 *
embeddedartists 0:0fdadbc3d852 24 * FILE *fp = fopen("/qspi/myfile.txt", "w");
embeddedartists 0:0fdadbc3d852 25 * if (fp != NULL) {
embeddedartists 0:0fdadbc3d852 26 * fprintf(fp, "Hello World!\n");
embeddedartists 0:0fdadbc3d852 27 * fclose(fp);
embeddedartists 0:0fdadbc3d852 28 * }
embeddedartists 0:0fdadbc3d852 29 * }
embeddedartists 0:0fdadbc3d852 30 * @endcode
embeddedartists 2:1c6134c80dc5 31 *
embeddedartists 2:1c6134c80dc5 32 * The file system can be formatted to a specific size in increments of 1MByte
embeddedartists 2:1c6134c80dc5 33 * and will allways be placed at the top of the address range. For the 8 MByte
embeddedartists 2:1c6134c80dc5 34 * memory on the LPC4088 QuickStart Board this means:
embeddedartists 2:1c6134c80dc5 35 *
embeddedartists 2:1c6134c80dc5 36 * <pre>
embeddedartists 2:1c6134c80dc5 37 * 0x28000000 0x28800000
embeddedartists 2:1c6134c80dc5 38 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 39 * qspifs.format(1) | available for program | FS |
embeddedartists 2:1c6134c80dc5 40 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 41 * </pre><pre>
embeddedartists 2:1c6134c80dc5 42 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 43 * qspifs.format(2) | available for program | FileSystem |
embeddedartists 2:1c6134c80dc5 44 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 45 * </pre><pre>
embeddedartists 2:1c6134c80dc5 46 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 47 * qspifs.format(7) | PROG | FileSystem |
embeddedartists 2:1c6134c80dc5 48 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 49 * </pre><pre>
embeddedartists 2:1c6134c80dc5 50 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 51 * qspifs.format(8) | FileSystem |
embeddedartists 2:1c6134c80dc5 52 * |------|------|------|------|------|------|------|------|
embeddedartists 2:1c6134c80dc5 53 * </pre>
embeddedartists 2:1c6134c80dc5 54 * The file system must be placed at the top of the memory because the linker scripts
embeddedartists 2:1c6134c80dc5 55 * places your program at the bottom of the memory (if needed).
embeddedartists 2:1c6134c80dc5 56 *
embeddedartists 2:1c6134c80dc5 57 * The file system is using one or more blocks (each the size of one erase block) per
embeddedartists 2:1c6134c80dc5 58 * file. Each file is stored in a sequence of blocks. If a file is written to so that
embeddedartists 2:1c6134c80dc5 59 * it's size will occupy more than one block and the block after is already used by
embeddedartists 2:1c6134c80dc5 60 * a different file the entire file will be moved, like this:
embeddedartists 2:1c6134c80dc5 61 *
embeddedartists 2:1c6134c80dc5 62 * <pre>
embeddedartists 2:1c6134c80dc5 63 * |-------|-------|-------|-------|-------|-------|-------|
embeddedartists 2:1c6134c80dc5 64 * Before |///////| FILE1 | FILE2 | FILE3 |///////|///////|///////|
embeddedartists 2:1c6134c80dc5 65 * |-------|-------|-------|-------|-------|-------|-------|
embeddedartists 2:1c6134c80dc5 66 * </pre><pre>
embeddedartists 2:1c6134c80dc5 67 * After writing |-------|-------|-------|-------|-------|-------|-------|
embeddedartists 2:1c6134c80dc5 68 * to FILE2 |///////| FILE1 |///////| FILE3 | FILE2 |///////|
embeddedartists 2:1c6134c80dc5 69 * |-------|-------|-------|-------|-------|-------|-------|
embeddedartists 2:1c6134c80dc5 70 * </pre>
embeddedartists 2:1c6134c80dc5 71 *
embeddedartists 2:1c6134c80dc5 72 * <b>Note: </b>As each file takes up at least one block it will limit the total number of files that
embeddedartists 2:1c6134c80dc5 73 * can be stored on the file system. The formula for this is roughly
embeddedartists 2:1c6134c80dc5 74 * <pre>
embeddedartists 2:1c6134c80dc5 75 * max_num_files = fs_size_in_bytes / erase_block_size
embeddedartists 2:1c6134c80dc5 76 * </pre>
embeddedartists 2:1c6134c80dc5 77 * For the SPI flash on the LPC4088 QuickStart Board it means
embeddedartists 2:1c6134c80dc5 78 * <pre>
embeddedartists 2:1c6134c80dc5 79 * max_num_files = 8MByte / 4KByte = 2048
embeddedartists 2:1c6134c80dc5 80 * </pre>
embeddedartists 2:1c6134c80dc5 81 *
embeddedartists 2:1c6134c80dc5 82 * Some of the blocks are used to store the table of content (TOC) at the very end of
embeddedartists 2:1c6134c80dc5 83 * the spi flash. The TOC will contain a list of all blocks on the flash (even those
embeddedartists 2:1c6134c80dc5 84 * not used by the file system) and will mark each block as "reserved","in use" or "free".
embeddedartists 2:1c6134c80dc5 85 * For a file system that is 4MByte on a 8MByte flash half of the blocks will be marked
embeddedartists 2:1c6134c80dc5 86 * as "reserved".
embeddedartists 2:1c6134c80dc5 87 *
embeddedartists 2:1c6134c80dc5 88 * <b>Note: </b>The file system will not store any date/time information.
embeddedartists 2:1c6134c80dc5 89 *
embeddedartists 2:1c6134c80dc5 90 * <b>Note: </b>The file system will not store any file attributes (hidden/system/read only).
embeddedartists 2:1c6134c80dc5 91 *
embeddedartists 2:1c6134c80dc5 92 * <b>Note: </b>The file system stores the absolute path of each file (path + file name) in
embeddedartists 2:1c6134c80dc5 93 * the file's first block's first 256 bytes. Folders are never stored themselves. This has
embeddedartists 2:1c6134c80dc5 94 * the drawback that the file system cannot hold empty folders.
embeddedartists 0:0fdadbc3d852 95 */
embeddedartists 0:0fdadbc3d852 96 class QSPIFileSystem : public FileSystemLike {
embeddedartists 0:0fdadbc3d852 97 public:
embeddedartists 0:0fdadbc3d852 98
embeddedartists 0:0fdadbc3d852 99 /** Create the File System for accessing a QSPI Flash
embeddedartists 0:0fdadbc3d852 100 *
embeddedartists 0:0fdadbc3d852 101 * @param name The name used to access the virtual filesystem
embeddedartists 0:0fdadbc3d852 102 */
embeddedartists 0:0fdadbc3d852 103 QSPIFileSystem(const char* name);
embeddedartists 0:0fdadbc3d852 104
embeddedartists 0:0fdadbc3d852 105 virtual FileHandle *open(const char *filename, int flags);
embeddedartists 0:0fdadbc3d852 106 virtual int remove(const char *filename);
embeddedartists 0:0fdadbc3d852 107 virtual int rename(const char *oldname, const char *newname);
embeddedartists 0:0fdadbc3d852 108 virtual DirHandle *opendir(const char *name);
embeddedartists 0:0fdadbc3d852 109 virtual int mkdir(const char *name, mode_t mode);
embeddedartists 0:0fdadbc3d852 110
embeddedartists 0:0fdadbc3d852 111 /** Creates a new file system on the QSPI flash.
embeddedartists 0:0fdadbc3d852 112 * The file system will have the specified size and will always
embeddedartists 0:0fdadbc3d852 113 * be positioned at the end of the QSPI flash. If the fsSizeInMB is
embeddedartists 0:0fdadbc3d852 114 * less than the size of the QSPI flash the lower end of the flash
embeddedartists 0:0fdadbc3d852 115 * will be left untouched.
embeddedartists 0:0fdadbc3d852 116 *
embeddedartists 0:0fdadbc3d852 117 * @param fsSizeInMB The size of the file system
embeddedartists 0:0fdadbc3d852 118 *
embeddedartists 0:0fdadbc3d852 119 * @returns
embeddedartists 0:0fdadbc3d852 120 * 0 on success,
embeddedartists 0:0fdadbc3d852 121 * -1 on failure.
embeddedartists 0:0fdadbc3d852 122 */
embeddedartists 0:0fdadbc3d852 123 int format(unsigned int fsSizeInMB = 8);
embeddedartists 0:0fdadbc3d852 124
embeddedartists 0:0fdadbc3d852 125 /** Tests if there is a file system present on the QSPI flash
embeddedartists 0:0fdadbc3d852 126 *
embeddedartists 0:0fdadbc3d852 127 * @returns
embeddedartists 0:0fdadbc3d852 128 * True if a valid file system could be found,
embeddedartists 0:0fdadbc3d852 129 * False on failure.
embeddedartists 0:0fdadbc3d852 130 */
embeddedartists 0:0fdadbc3d852 131 bool isformatted();
embeddedartists 0:0fdadbc3d852 132
embeddedartists 0:0fdadbc3d852 133 /** Retrieves the start and end addresses for the file system.
embeddedartists 0:0fdadbc3d852 134 * The pStartAddr and pEndAddr will only be assigned values if the
embeddedartists 0:0fdadbc3d852 135 * function returns true.
embeddedartists 0:0fdadbc3d852 136 *
embeddedartists 0:0fdadbc3d852 137 * @param pStartAddr Will return the start of the file system area
embeddedartists 0:0fdadbc3d852 138 * @param pEndAddr Will return the end of the file system area
embeddedartists 0:0fdadbc3d852 139 *
embeddedartists 0:0fdadbc3d852 140 * @returns
embeddedartists 0:0fdadbc3d852 141 * True if there is a file system,
embeddedartists 0:0fdadbc3d852 142 * False on failure.
embeddedartists 0:0fdadbc3d852 143 */
embeddedartists 0:0fdadbc3d852 144 bool getMemoryBoundaries(uint32_t* pStartAddr, uint32_t* pEndAddr);
embeddedartists 0:0fdadbc3d852 145 };
embeddedartists 0:0fdadbc3d852 146
embeddedartists 0:0fdadbc3d852 147 #endif
embeddedartists 0:0fdadbc3d852 148
embeddedartists 0:0fdadbc3d852 149