{"id":17647283,"url":"https://github.com/ironsheep/p2-flash-fs","last_synced_at":"2025-05-07T04:12:29.635Z","repository":{"id":189601011,"uuid":"680328118","full_name":"ironsheep/P2-FLASH-FS","owner":"ironsheep","description":"Chip's  Flash FS with a standard API for accessing the FLASH chip on the P2 Edge Module.","archived":false,"fork":false,"pushed_at":"2024-07-30T19:31:40.000Z","size":2274,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-07T04:12:12.324Z","etag":null,"topics":["driver","eeprom-storage","p2","p2-edge","p2asm","parallax-propeller","parallax-propeller-microcontroller","pasm2","spin2"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ironsheep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ironsheep","patreon":"IronSheep"}},"created_at":"2023-08-18T23:12:13.000Z","updated_at":"2023-10-12T13:46:50.000Z","dependencies_parsed_at":"2023-12-28T23:51:02.728Z","dependency_job_id":"15312a16-0cab-421b-8fe8-0e5f0fe19162","html_url":"https://github.com/ironsheep/P2-FLASH-FS","commit_stats":null,"previous_names":["ironsheep/p2-flash-fs"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ironsheep%2FP2-FLASH-FS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ironsheep%2FP2-FLASH-FS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ironsheep%2FP2-FLASH-FS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ironsheep%2FP2-FLASH-FS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ironsheep","download_url":"https://codeload.github.com/ironsheep/P2-FLASH-FS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252810274,"owners_count":21807759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["driver","eeprom-storage","p2","p2-edge","p2asm","parallax-propeller","parallax-propeller-microcontroller","pasm2","spin2"],"created_at":"2024-10-23T11:11:54.963Z","updated_at":"2025-05-07T04:12:29.604Z","avatar_url":"https://github.com/ironsheep.png","language":"Shell","funding_links":["https://github.com/sponsors/ironsheep","https://patreon.com/IronSheep","https://www.buymeacoffee.com/ironsheep","https://www.patreon.com/IronSheep?fan_landing=true"],"categories":[],"sub_categories":[],"readme":"# P2-FLASH-FS\nFlash FS - a filesystem for the FLASH chip on the P2 Edge Module.\n\n![Project Maintenance][maintenance-shield]\n\n[![License][license-shield]](LICENSE)\n\nThe following files can be found at the top level of this repository:\n\n| Key Files | Description |\n| --- | --- |\n| [`flash_fs.spin2`](./flash_fs.spin2) | The complete FLASH driver object\n| [`flash_fs.txt`](./flash_fs.txt) | Object Interface Document for the FLASH driver\n| [`cgsm_flash_file_demo.zip`](./cgsm_flash_file_demo.zip) | Jon McPhalens latest Interactive Filesystem Demo\n| [`flash_fs_demo.spin2`](./flash_fs_demo.spin2) | Chip's original light-weight non-interactive demo\n\n## Table of Contents\n\nOn this Page:\n\n- [Flash Filesystem Features](#flash-filesystem-features) - key features of this filesystem / design goals\n- [Adding the flash fs to your own project](#adding-the-flash-fs-to-your-own-project)\n- [Contributing](#how-to-contribute) - you can contribute to this project\n\nAdditional pages:\n\n- [The flash_fs Object I/F Documentation](flash_fs.txt) - the object interface with documentation for each public method\n- [SPI FLASH Datasheet](./DOCs/W25Q128JV-210823.pdf) - our FLASH Chip Datasheet\n- [FS Theory of Operations](THEOPSv2.md) - a detailed description of key concepts of this filesystem (See [v1.x FS Theory of...](THEOPS.md) for earlier version)\n- [Regression Testing Status](./RegresssionTests) - regression test code and output logs - growing as we certify each of the features (900+ tests so far)\n\n## Flash Filesystem Features\n\nKey features of this Flash Filesystem for the P2 Edge Flash chip:\n\n- Wear-leveling write mechanism\n- Writes are stuctured to facilitate recovery  of file structure after unplanned power failure\n- Block identification is independent of a blocks physical location\n- Filenames are 127 characters plus zero terminator\n- Seeks supported\n- File Append supported\n- Read-Modify-Write supported\n- Circular file writes supported \n- Supports multi-cog use (first cog to call mount() mounts the filesystem for all cogs to use.)\n- **Coming soon** *Directory Support* \n\n## Features of Note\n\nIn addition to standard file operations this filesystem contains a couple features worth noting:\n\n### Feature: Circular files\n\nCirculr files are useful when you want to record the most recent journal entries (or event log entries) in a file.\n\nOne writes to circular files by appending to them. At file open, one specifies a maximum limit to the file size in bytes, for example:\n\n```spin2\n    status := flash.open_circular(@\"filename\", \"a\", 8_192)\n    ... many writes ...\n    status := flash.close()\n```\n\nIn this example you see a file being limited to 8k bytes.  This means keep track of the last 8k bytes worth of journal or log entries.  Upon close the journal will be reduced to the requested limit. \n\nNOTE: Remember to call `flash.flush()` periodically to keep the pending writes small enough so that you don't run out of flash space.\n\nAn `open_circular(..., \"r\", 8_192)` is provided so that one can open the journal file and start reading at the front of the last 8_192 bytes in the file.\n\n\n### Feature: File Read-Modify-Write\n\nYou can now modiify existing files on flash.  Think of a file which contains fixed size records, maybe the state of an array of sensors where each sensor (or group of sensors) is in their own record within the file.\n\n```spin2\n    status := flash.open(@\"filename\", %\"r+\")  ' alternatively use FILEMODE_READ_EXTENDED for %\"r+\" \n    ... many  reads and/or replacing writes  ...\n    status := flash.close()\n```\n\nOpen the file with the new %\"r+\" mode., then seek to the record you wish to replace and write it (replacing the record already there.)  Continue by seeking to locations and writing new records. Of course you can seek to and read the existing records, too.  Lastly close the file as normal.\n\nWe also provide an open mode of `flash.open(@\"filename\", %\"w+\")` where you first have to write the new records before you can seek to them or replace them with new records.\n\nLastly we've added a `flash.create_file()` method which you can use to create an initialized file with empty records.  For example:\n\n```spin2\n    ' create empty file\n    status := flash.create_file(@\"filename\", $00, 4_096)\n    ' now do updates to the file\n    status := flash.open(@\"filename\", %\"r+\")\n    ... many  reads and/or replacing writes  ...\n    status := flash.close()\n```\n\nIn this example we are initilizing a file with 4k bytes of zeros.  You can use any byte value you wish for the fill value.\n\n## Migration from v1.4 to v2.0\n\nThere is NO migration needed if you are **not using Circular Files**.\n\nIf you are using Circular files and you need to preseve them instead of just creating new ones, then you will first want to copy your exising circular file to a new one. This creates the new file head block supporting circular seeks.\n\nExample copy file code:\n\n```spin2\nPUB exampleCopy(pOldFilename, pNewFilename) | status, rdHandle, rdLength, wrHandle, rdStatus, wrStatus, wrLength\n\n    ' remove existing file if it exists\n    if flash.exists(pNewFilename)\n      status := flash.delete(pNewFilename)\n\n    ifnot flash.exists(pNewFilename)\n        debug(\"Abort: no file to copy\")\n\n    ' open existng file in basic \"read\" mode\n    rdHandle := flash.open(pOldFilename, \"r\")\n    ' open new file with exact circular length of your orignal file\n    wrHandle := flash.open_circular(pNewFilename, \"a\", CIRCULAR_LEN_IN_BYTES)\n\n    repeat\n      rdLength := flash.read(rdHandle, @record, RECORD_LEN)\n      rdStatus := flash.error()\n      if rdStatus \u003c\u003e flash.SUCCESS and rdStatus \u003c\u003e flash.E_END_OF_FILE\n        debug(\"Abort: read error\")\n        quit\n\n      wrLength := flash.write(wrHandle, @record, rdLength)\n      wrStatus := flash.error()\n      if wrStatus \u003c\u003e flash.SUCCESS\n        debug(\"Abort: write error\")\n        quit\n\n      if rdStatus == flash.E_END_OF_FILE\n         debug(\"DONE: copy complete\")\n        quit\n\n    while wrStatus == flash.SUCCESS\n    ' and close our files\n    flash.close(rdHandle)\n    flash.close(wrHandle)\n\n```\n\n## Adding the Flash FS to your own project\n\nThis section describes how to quickly get the flash filesystem working in your project.\n\n### Download the latest flash_fs.spin2 file\n\nEvery 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](https://github.com/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](https://github.com/ironsheep/P2-FLASH-FS/releases) page where you can download the latest release which includes demo files as well as the filesystem object.\n\n### Include the Flash FS object in your top file\n\nPlace the downloaded `flash_fs.spin2` in your project and in your top-level object include the flash object:\n\n```spin2\nOBJ { Objects Used by this Object }\n\n    flash  : \"flash_fs\"\t           ' the Flash Filesystem\n```\n\nThe 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:\n\n```spin2\nOBJ { Objects Used by this Object }\n\n    flash  : \"flash_fs\"\t | MAX_FILES_OPEN = 4       ' the Flash Filesystem\n```\n\nIn this case we are telling the compiler to allocate room for 4 simultaneously accessable files instead of the default two files.\n\n### Format() or Mount() the flash filesystem\n\nAt the start of your application will need to mount() the filesystem.  \n\n```spin2\nPRI main() | status\n\n    status := flash.mount()\t           ' start up the FLASH filesystem\n    if status \u003c\u003e flash.SUCCESS\n      '... you know that some blocks were corrupted and freed ...\n```\n\nIf 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.)\n\n```spin2\nPRI main()\n\n    flash.format()\t           ' start up the FLASH filesystem\n```\n\n\n### Work with files on flash as you would normally\n\nNow 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.\n\nReview the [Flash F/S Object I/F Documentation](flash_fs.txt) then start reading and writing files!\n\nPlease Enjoy!\n*Stephen*\n\n## How to Contribute\n\nThis is a project supporting our P2 Development Community. Please feel free to contribute to this project. You can contribute in the following ways:\n\n- File **Feature Requests** or **Issues** (describing things you are seeing while using our code) at the [Project Issue Tracking Page](https://github.com/ironsheep/P2-FLASH-FS/issues)\n- 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](CONTRIBUTING.md)\n\n## Credits\n\nThank you to **Chip Gracey** for the excellent **Flash File System 16MB** written for the P2 which is the core of this fileysystem.\n\nThank 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.\n\nThank you also to members of the [forum thread - \"On-Board Flash File System\"](https://forums.parallax.com/discussion/175470/on-board-flash-file-system#latest) for also contributing ideas and guidance for implementation of this driver.\n\n---\n\n\u003e 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 :coffee:'s or :pizza: slices!\n\u003e\n\u003e [![coffee](https://www.buymeacoffee.com/assets/img/custom_images/black_img.png)](https://www.buymeacoffee.com/ironsheep) \u0026nbsp;\u0026nbsp; -OR- \u0026nbsp;\u0026nbsp; [![Patreon](./DOCs/images/patreon.png)](https://www.patreon.com/IronSheep?fan_landing=true)[Patreon.com/IronSheep](https://www.patreon.com/IronSheep?fan_landing=true)\n\n---\n\n## Disclaimer and Legal\n\n\u003e *Parallax, Propeller Spin, and the Parallax and Propeller Hat logos* are trademarks of Parallax Inc., dba Parallax Semiconductor\n\u003e\n\u003e This project is a community project not for commercial use.\n\u003e\n\u003e 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.\n\n---\n\n## License\n\nLicensed under the MIT License.\n\nFollow these links for more information:\n\n### [Copyright](copyright) | [License](LICENSE)\n\n[maintenance-shield]: https://img.shields.io/badge/maintainer-stephen%40ironsheep%2ebiz-blue.svg?style=for-the-badge\n\n\n[license-shield]: https://img.shields.io/badge/License-MIT-yellow.svg\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironsheep%2Fp2-flash-fs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fironsheep%2Fp2-flash-fs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fironsheep%2Fp2-flash-fs/lists"}