https://github.com/s95rob/romfs
Tiny ROM-based filesystem library and packing tool for 32-bit embedded devices
https://github.com/s95rob/romfs
c embedded embedded-systems gbadev homebrew microcontroller rom
Last synced: 3 months ago
JSON representation
Tiny ROM-based filesystem library and packing tool for 32-bit embedded devices
- Host: GitHub
- URL: https://github.com/s95rob/romfs
- Owner: s95rob
- License: mit
- Created: 2025-09-30T04:13:30.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-09-30T22:53:26.000Z (4 months ago)
- Last Synced: 2025-10-01T00:25:34.753Z (4 months ago)
- Topics: c, embedded, embedded-systems, gbadev, homebrew, microcontroller, rom
- Language: C
- Homepage:
- Size: 5.86 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# romfs
A tiny ROM-based filesystem library and packing tool for 32-bit embedded devices. Pack files into a flat binary archive and index by filename.
## Building and Usage
`romfs` uses CMake for build system configuration. Clone this repository, add the repository as a CMake subdirectory and link against CMake target `romfs`.
In your project's code, simply initialize `romfs` and use it to index your data:
```c
// Declared some place elsewhere...
#define MY_PROJECT_ROM_ADDR 0x08000000
void do_something_with_data(volatile void* data, uint32_t size);
// ...
#include "romfs.h"
if (!romfs_init((volatile void*)MY_PROJECT_ROM_ADDR)) {
// romfs failed to initialize...
}
romfs_file my_file;
if (romfs_find(&my_file, "myfile1.txt")) {
do_something_with_data(my_file.data, my_file.size);
} else {
// romfs_find failed to find "myfile1.txt" ...
}
```
Additionally, there is an executable `romfs-pack`. This is a packing tool that will create a compiled ROM filesystem, `rom.bin`. It is designed to be integrated into build scripts, taking file names as command line arguments to be compiled.
Example:
```bash
romfs-pack myfile1.txt myfile2.png myfile3.mp3
```
## Specification
`romfs` uses a lightweight binary specification for indexing and storing files. The final produced binary file from the packing tool `romfs-pack` contains a header chunk, file entry chunk and binary chunk.
### Header
Stores the magic number identifier (ASCII string "`DATA`") and number of file entries in the file entry chunk.
| Name | Bytes |
|---|---|
| Magic number | 4 |
| Number of file entries | 4 |
### File entry chunk
Each file entry in the file entry chunk describes where and how large each file's associated binary data is. File names are stored hashed for size efficiency, and the binary offset points to the beginning of the file's binary data in relation to the binary chunk's beginning.
| Name | Bytes |
|---|---|
| Hashed file name | 4 |
| Binary byte length | 4 |
| Binary offset | 4 |
### Binary chunk
The final chunk of the ROM filesystem contains a flat binary blob of all packed files.