P2-FLASH-FS

Flash FS - a filesystem for the FLASH chip on the P2 Edge Module.

The following files can be found at the top level of this repository:

Key Files	Description
`cgsm_flash_file_demo.zip`	Jon McPhalens Interactive Filesystem Demo
`flash_fs.spin2`	The complete FLASH driver object
`flash_fs.txt`	Object Interface Document for the FLASH driver

On this Page:

Flash Filesystem Features - key features of this filesystem / design goals
Adding the flash fs to your own project
Contributing - you can contribute to this project

Additional pages:

The flash_fs Object I/F Documentation - the object interface with documentation for each public method
SPI FLASH Datasheet - our FLASH Chip Datasheet
FS Theory of Operations - a detailed description of key concepts of this filesystem
Regression Testing Status - regression test code and output logs - growing as we certify each of the features (604+ tests so far)

Flash Filesystem Features

Key features of this Flash Filesystem for the P2 Edge Flash chip:

Wear-leveling write mechanism
Writes are stuctured to facilitate recovery of file structure after unplanned power failure
Block identification is independent of a blocks physical location
Filenames are 127 characters plus zero terminator
Seeks supported
File Append supported
Circular file writes supported
Coming Soon Can be accessed from all cogs (first cog to call mount() mounts the filesystem for all cogs to use.)
Coming soon Directory Support

Adding the Flash FS to your own project

This section describes how to quickly get the flash filesystem working in your project.

Download the latest flash_fs.spin2 file

Every time you wish to start a project using the flash filesystem you will want to download the latest version from the repository ironsheep/P2-FLASH-FS. In the list of files on the top page you will see the file flash_fs.spin2. You can download this single file to get the latest or you can navigate to the releases page where you can download the latest release which includes demo files as well as the filesystem object.

Include the Flash FS object in your top file

Place the downloaded flash_fs.spin2 in your project and in your top-level object include the flash object:

OBJ { Objects Used by this Object }

    flash  : "flash_fs"	           ' the Flash Filesystem

The driver keeps about ~4250 bytes per open file. The space is allocated for two open files by default. You can override this in your top-level file by changing the include to something like:

OBJ { Objects Used by this Object }

    flash  : "flash_fs"	 | MAX_FILES_OPEN = 4       ' the Flash Filesystem

In this case we are telling the compiler to allocate room for 4 simultaneously accessable files instead of the default two files.

Format() or Mount() the flash filesystem

At the start of your application will need to mount() the filesystem.

PRI main() | status

    status := flash.mount()	           ' start up the FLASH filesystem
    if status <> flash.SUCCESS
      '... you know that some blocks were corrupted and freed ...

If you know that that the flash chip in your P2 Edge module has never been formatted then you can call format instead of mount. (The format will then do the mount for you.)

PRI main()

    flash.format()	           ' start up the FLASH filesystem

work with files on flash as you would normally

Now that your filesystem is mounted you are free to do normal file operations. The filesystem API is very similar to the ANSI-C file handling API so this all should feel pretty natural to you.

Review the Flash F/S Object I/F Documentation then start reading and writing files!

Please Enjoy! Stephen

How to Contribute

This is a project supporting our P2 Development Community. Please feel free to contribute to this project. You can contribute in the following ways:

File Feature Requests or Issues (describing things you are seeing while using our code) at the Project Issue Tracking Page
Fork this repo and then add your code to it. Finally, create a Pull Request to contribute your code back to this repository for inclusion with the projects code. See CONTRIBUTING

Credits

Thank you to Chip Gracey for the excellent Flash File System 16MB written for the P2 which is the core of this fileysystem.

Thank you to Jon McPhalen for helping to specify the customer facing API for this filesystem and for guidance in our future directions for the upcoming dual filesystem driver as well. Jon also contributed his interactive filesystem demo.

Thank you also to members of the forum thread - "On-Board Flash File System" for also contributing ideas and guidance for implementation of this driver.

If you like my work and/or this has helped you in some way then feel free to help me out for a couple of ☕'s or 🍕 slices!

-OR- Patreon.com/IronSheep

Disclaimer and Legal

Parallax, Propeller Spin, and the Parallax and Propeller Hat logos are trademarks of Parallax Inc., dba Parallax Semiconductor

This project is a community project not for commercial use.

This project is in no way affiliated with, authorized, maintained, sponsored or endorsed by Parallax Inc., dba Parallax Semiconductor or any of its affiliates or subsidiaries.

License

Licensed under the MIT License.

Follow these links for more information:

refaqtor/P2-FLASH-FS