{"id":50140348,"url":"https://github.com/lupusarqentum/foxramdisk","last_synced_at":"2026-05-30T07:00:57.489Z","repository":{"id":359883846,"uuid":"1247866459","full_name":"lupusarqentum/foxramdisk","owner":"lupusarqentum","description":"Linux module to provide a block device featuring RAM-backed storage and compression capabilities","archived":false,"fork":false,"pushed_at":"2026-05-23T23:19:27.000Z","size":37,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T02:02:55.072Z","etag":null,"topics":["compression","linux-kernel-module","ramdisk"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lupusarqentum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T22:16:29.000Z","updated_at":"2026-05-24T07:32:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lupusarqentum/foxramdisk","commit_stats":null,"previous_names":["lupusarqentum/foxramdisk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lupusarqentum/foxramdisk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupusarqentum%2Ffoxramdisk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupusarqentum%2Ffoxramdisk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupusarqentum%2Ffoxramdisk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupusarqentum%2Ffoxramdisk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lupusarqentum","download_url":"https://codeload.github.com/lupusarqentum/foxramdisk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lupusarqentum%2Ffoxramdisk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33501704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"online","status_checked_at":"2026-05-26T02:00:06.821Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["compression","linux-kernel-module","ramdisk"],"created_at":"2026-05-24T01:01:44.142Z","updated_at":"2026-05-28T05:00:34.534Z","avatar_url":"https://github.com/lupusarqentum.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux kernel compressed RAM disk\n\nA C Linux kernel module that provides a block device with RAM-backed storage and compression capabilities to reduce memory efficiency.\n\nThis project is implemented mainly for fun and educational purposes. No warranties of correctness or fitness for any particular purpose are given.\n\n## Features\n\n- RAM-backed block devices\n- Optional compression\n- Multiple devices\n- Runtime device creation\n- Per-device statistics via sysfs or convenience script\n- Discard and write-zeroes support to reduce memory usage\n\n## Current Limitations\n\nBoth are planned to be improved.\n\n- No runtime device removal\n- Only one I/O operation can happen at a time.\n\n## Building\n\nThe project is expected to be built on **Fedora Server** with **Linux kernel 6.18**. Other distributions and Linux kernel versions are out of support, though they might work as well.\n\nThe Linux kernel must be configured to support 842 and deflate algorithms (it does by default on Fedora).\n\nTo build the project on Fedora Server, you need to install build dependencies:\n\n```bash\nsudo dnf install gcc make kernel-devel kernel-headers\n```\n\nAfter installing dependencies and cloning the repository, simply run make:\n\n```bash\nmake all\n```\n\nThis will produce the module ```.ko``` file that can be loaded.\n\n## Loading the module and creating devices\n\nSimply use ```insmod``` or ```modprobe``` to load the module you have just built. You can pass the following module parameters:\n\n- ```initial_devices_count```: number of devices to create at module load (**uint, optional, defaults to 1**)\n- ```default_capacity```: initial capacity of newly created devices in 4096-bytes long blocks (**ulong, optional, defaults to 4096 blocks (16 MiB)**)\n- ```default_compression```: name of the compression algorithm to be used by newly created devices (**string, optional, defaults to ```deflate```**)\n\nRecognized compression algorithm names are:\n\n- ```nocomp```: to disable compression and store data uncompressed\n- ```842```: 842 algorithm\n- ```deflate```: deflate algorithm\n\nBlock devices created by the module receive ```/dev/foxramdiskN``` dev files in ```/dev```, where ```N``` is the device number.\n\n```default_capacity``` and ```default_compression``` parameters can be set after the module has loaded. Example:\n\n```bash\necho -n \"nocomp\" \u003e /sys/module/foxramdisk/parameters/default_compression\n```\n\nThis would change neither capacity nor compression algorithm of devices already created.\n\nYou can hot-add new devices without restarting the module. They will be created with ```default_capacity``` and use ```default_compression```.\n\nTo do that, read from ```hot_add``` file:\n\n```bash\ncat /sys/class/foxramdisk-control/hot_add\n```\n\nIf it succeeds at creating a new device, you will successfully read a device number attached to the new device. Device number is a number that's appended to foxramdisk in device file, e.g., ```/dev/foxramdisk7```.\n\n## Using devices\n\nYou can use them like any other block devices, for example, you can format partition tables, filesystems, swaps, or use utilities such as ```dd```.\n\nThe module collects statistics on I/O to devices and their storage representation. You can manually read sysfs files for individual stats. For example, the following command will show total size of compressed blocks:\n\n```bash\nsudo cat /sys/block/foxramdiskN/storage_stat/compressed_data_size\n```\n\nAdditionally, you can use convenience script ```rd_display_stats.sh``` located in the ```script``` folder of this repository. This script will read all stats for you and format them for easier reading. Run script with no arguments to display its help page:\n\n```bash\n./script/rd_display_stats.sh\n```\n\nAn example of using the script:\n\n```bash\n$ ./script/rd_display_stats.sh -h /dev/foxramdiskN\n\nBytes written:                   282.21 MiB\nBytes read:                      4.00 KiB\nBytes discarded:                 0.00 B\nFailed reads:                    0\nFailed writes:                   0\nFailed discards:                 0\n\nBlock size in bytes:             4096\nIncompressible blocks:           8120\nIncompressible blocks data size: 31.72 MiB\nZeroed blocks:                   990081\nZeroed blocks logical size:      3.78 GiB\nCompressed blocks:               50375\nCompressed blocks logical size:  196.78 MiB\nCompressed data size:            36.82 MiB\n\nCompression algorithm:           deflate\n\nCompression ratio:               5.344\n    Incompressible blocks are not considered.\nEffective compression ratio:     3.334\n    Incompressible blocks are treated as compression ratio 1:1.\n```\n\n## Removing devices and unloading the module\n\nCurrently, there is no way to hot-remove a device. As a workaround, you can discard all of its content to free the memory it uses for storage (though it will still use some memory for metadata):\n\n```bash\nsudo blkdiscard /dev/foxramdiskN\n```\n\nYou can easily unload the module with the help of ```rmmod``` command. All existing devices and their data will be lost.\n\n## Planned Updates\n\nIf you want to implement any of these, please contact me beforehand. If you have an idea about a new update not listed here, you can open an issue or contact me.\n\nNew updates ideas:\n\n- hot-remove a device\n- change device size and compression algorithm on the fly\n- reduce memory footprint of metadata\n- allocate per-CPU compressor contexts to allow concurrent I/O, switch to per-block locks instead of per-device lock\n- support more compression algorithms\n- repository: testing \u0026 CI\n\n## How to Contribute\n\nThere are multiple ways to help the project.\n\nYou can:\n\n- open an issue or contact the developer, if you find a bug\n- send a PR fixing a bug, if you find one\n- write new code for planned updates and send a Pull Request on GitHub. See the next sections for coding conventions and technical information.\n\n## Coding Conventions\n\nHere are conventions used in this project:\n\n- Use [**conventional commit**](https://www.conventionalcommits.org/) messages.\n- Write your code with Linux kernel coding style in mind. All code in this repository is checked for code style violations by kernel **```checkpatch.pl```** script. It would be nice to check your code as well.\n- Ensure your code **builds and runs** as expected.\n- Write kernel-doc comments for all public functions. These comments should be consumable by kernel doc tools. For functions, you should document invariants, argument boundaries, **thread safety, and whether or not a function may sleep**.\n\n## Testing \u0026 CI\n\nCI and testing infrastructure are planned, but not yet implemented.\n\n## Project Architecture \u0026 Documentation\n\nYou can find and view doc comments directly in the source code, or generate docs using ```kernel-doc``` script found in the Linux kernel repository. What follows is a general architecture overview.\n\nThe code is split across different files.\n\n- ```src/ramdisk_store.h``` and ```src/ramdisk_store.c``` are responsible for actual storage logic. The data is organized into ```RD_BLOCK_SIZE``` blocks that can be independently accessed by ```rd_write```, ```rd_read``` and ```rd_write_zeroes``` function calls.\n- ```src/ramdisk.c``` is responsible for all communication with the Linux kernel API, such as module parameters, sysfs entries, disk registration, etc. It also receives I/O requests, processes them and calls ```ramdisk_store.h``` to complete them.\n- ```src/ramdisk_compressor.h``` and ```src/ramdisk_compressor.c``` provide a unified interface of compression algorithms for ```ramdisk_store```, as well as a registry to find these compressors by their name.\n\nA few important notes:\n\n- For every supported compression algorithm, there is corresponding ```.c``` file that is included by ```ramdisk_compressor.c```.\n- If compression is not desired, there is a ```\"nocomp\"``` compression algorithm. For every compress call it returns an error indicating the block is incompressible, effectively forcing the storage to store data uncompressed.\n- ```ramdisk_store``` implementation: all I/O requests (function calls read, write, write zeroes/discard) are passed to ```rd_io_high``` function. This function will switch on the operation code and call one of the \"low\" functions: ```rd_write_low```, ```rd_read_low```, or ```rd_write_zeroes_low```. \"low\" functions focus on I/O logic only, they don't do user arguments validation, mutual exclusion, and statistics update. ```rd_io_high``` function can be thought as a decorator that adds this functionality to more focused I/O functions.\n- Each block is represented by a ```struct rd_block``` that holds pointer to the data buffer (if applicable), the data buffer size and *state*.\n\nA block might be in one of the following *states*:\n\n- **zeroed**: the block is filled with zero bytes only. For efficiency, no data buffer is allocated for this block. This is the initial state of all blocks and also their state after discard operations.\n- **compressed**: the data buffer contains compressed data that needs to be decompressed to be read.\n- **raw**: reader can read block data directly without decompression. It could have happened because the block data is incompressible (e.g. random data) or the compression is disabled. The size field must be set to ```RD_BLOCK_SIZE```.\n\nDiscard and write zeroes operations are implemented identically and both transition blocks to zeroed state.\n\n## License, Authors and Contact Information\n\n[GPL-2.0](./LICENSE.md)\n\nCopyright (C) 2026 - Grigoriy Loboda\n\nSee my GitHub page for contact information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flupusarqentum%2Ffoxramdisk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flupusarqentum%2Ffoxramdisk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flupusarqentum%2Ffoxramdisk/lists"}