{"id":15395471,"url":"https://github.com/stef/stfs","last_synced_at":"2025-04-16T00:11:13.190Z","repository":{"id":43631538,"uuid":"69999636","full_name":"stef/stfs","owner":"stef","description":"st filesystem for embedded flash systems","archived":false,"fork":false,"pushed_at":"2017-03-12T18:02:19.000Z","size":50,"stargazers_count":12,"open_issues_count":0,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T03:11:15.243Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stef.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-04T19:40:08.000Z","updated_at":"2024-08-26T08:08:46.000Z","dependencies_parsed_at":"2022-08-25T19:40:41.830Z","dependency_job_id":null,"html_url":"https://github.com/stef/stfs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fstfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fstfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fstfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stef%2Fstfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stef","download_url":"https://codeload.github.com/stef/stfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249173086,"owners_count":21224483,"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":[],"created_at":"2024-10-01T15:28:27.995Z","updated_at":"2025-04-16T00:11:13.173Z","avatar_url":"https://github.com/stef.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"stfs - simple tabular file system\n\n    this file system is meant for the embedded flash of cortex-m3\n    micro controller. I tried yaffs, but it used too much memory, and\n    since the cortex-M3 controller already handles the low level\n    stuff, is not really suited for this purpose. stfs uses no heap,\n    and is also otherwise as the name hints: simple.\n\nstfs is a log-structured appending file system for embedded flash\ndevices, that expose the flash mapped as memory.\n\n  - assumes that you have only a few 4KB-128KB erasable blocks - all\n    of the same size.\n\n  - stfs provides only directories and files, but no other types like\n    pipes, links, etc. also no file metadata like timestamps or access\n    permissions.\n\n  - filenames are max 32 bytes long, files max 64KB - both settings\n    are configurable, but otherwise untested.\n\n  - always reserves one empty block for vacuuming.\n\n  - default chunksize is 128B with fs metadata included. unlike other\n    flash file systems where the block size is usually limited by 512B.\n\n  - totally single threaded\n\nLicense\n\n    stfs is licensed LGPLV2.1+.\n\napi\n\n   currently the api provides the following posix-like interfaces:\n\n   directory handling functions: mkdir, rmdir, opendir, readdir,\n\n   file handling functions: open, lseek, write, read, close, unlink, truncate\n\n   generic functions: init\n\nhow to play with it\n\n    1st of all this is a simulation, a toy. if you want to use it in\n    your micro controller you have to adapt a few things. like how you\n    write chunks and erase blocks. But you can play with it on your\n    computer. Compile everything with the makefile:\n\n    `CFLAGS=\"-DDEBUG_LEVEL=3\" make all`\n\n    where the debug level can be:\n       - 0 is quiet,\n       - 1 - errors,\n       - 2 - info,\n       - 3 - debug.\n\n    if you want to fuzz, you probably want to go with level 0, when\n    you debug you can play with other levels.\n\n    after compiling, you get `stfs` and `afl`.\n\n`stfs` test binary\n   `stfs` demos how to use stfs, executes a few test cases and then\n    dumps the whole fs into ./test.img.\n\nafl\n    `afl` is a simple script interpreter:\n\n    afl.c - reads stdin to execute script on in-RAM stfs and dump the result into test.img\n    commands are\n    m \u003cpath\u003e - mkdir\n    x \u003cpath\u003e - rmdir\n    o 0|64 \u003cstring\u003e - open 64==O_CREAT\n    w \u003cfd\u003e \u003csize\u003e - write\n    r \u003cfd\u003e \u003csize\u003e - read\n    s \u003cfd\u003e \u003cpos\u003e \u003cwhence\u003e - seek\n    c \u003cfd\u003e - close\n    t \u003csize\u003e \u003cpath\u003e - truncate\n    d \u003cpath\u003e - unlink\n\n    \u003cpath\u003e is always length prefixed, space-separated, e.g.:\n    m 5 /root\n        ^ path\n      ^ length of path\n\n    ./afl is also used by stfsfuzz.py, if you want to use it with afl,\n    you should compile without logging and dumping of the fs image.\n\n    you can find a few sample test cases in `testcases/`\n\npython tools\n\n    there's two python tools: stfsfuzz.py and anaimg.py\n\n    stfsfuzz.py runs `afl` repeatedly each time testing a different\n    random command, if the command returns something else than -1, it\n    is recorded in ./fuzz.script and keep this command in the test\n    case for subsequent commands to be appended. in the background\n    `afl` always dumps the latest fs image into `test.img`\n\n    `anaimg.py` loads `test.img` and prints a condensed sequence of\n    the chunks, the directory layout with file sizes, and the block\n    statistics.\n\npython deps\n\n   `pip install construct sh`\n\ndata structure\n\n   chunk_size = 128\n   chunks_per_block = 1024\n\n   4 different chunk types are used:\n\n   empty = 0xff (1B) irrelevant(all 0xff) (127B)\n   inode (128B)- contain file meta information\n     - chunktype (0xAA) (1B)\n     - directory | file (1b)\n     - size (2B)\n     - parent_directory_obj_id (4B)\n     - obj_id (4B)\n     - name_len (6b)\n     - name (32B)\n     - data (84B)\n   data (7B) - contain data\n    - chunktype (0xCC) (1B)\n    - seq_id (2B)\n    - obj_id (4B)\n    - data blob (chunksize-metasize)\n   deleted = 0x00 (1B) irrelevant(all 0x00) (127B)\n\n   inode with oid 1 is the root directory and virtual\n\nimportant implementation todo\n\n   In case you adapat this code, please replace the call to\n   `random(3)` in `stfs_init()` and in vacuum() to the cryptographic\n   random function of your system such as /dev/random or /dev/urandom\n   on Unix-like systems, and CryptGenRandom on Windows.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstef%2Fstfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstef%2Fstfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstef%2Fstfs/lists"}