91 lines
2.7 KiB
Markdown
91 lines
2.7 KiB
Markdown
|
# EROMFS Module
|
||
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
||
|
|
| :----- | :-------------------- | :---------- | :------ |
|
||
|
|
| 2021-11-13 | [Johny Mattsson](https://github.com/jmattsson) |[Johny Mattsson](https://github.com/jmattsson) | [heaptrace.c](../../components/modules/eromfs.c)|
|
||
|
|
|
||
|
|
EROMFS (Embedded Read-Only Mountable File Sets) provides a convenient mechanism
|
||
|
|
for bundling file sets into the firmware image itself. The main use cases
|
||
|
|
envisaged for this is static web site content and default "skeleton" files
|
||
|
|
that may be used to populate SPIFFS on first boot.
|
||
|
|
|
||
|
|
When enabling the `eromfs` module one or more file sets ("volumes") must be
|
||
|
|
declared. Each such volume is identified by name, and may be mounted anywhere
|
||
|
|
supported by the [Virtual File System](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/vfs.html). Once mounted, the included
|
||
|
|
files are available on a read-only basis to any thread wanting to access them.
|
||
|
|
|
||
|
|
Note that EROMFS does not support directories per se, but will store the
|
||
|
|
directory path as part of the filename just as SPIFFS does. As such it is
|
||
|
|
only possible to list the root of the volume, not subdirectories (since
|
||
|
|
they don't exist).
|
||
|
|
|
||
|
|
## eromfs.list
|
||
|
|
Returns a list of the bundled file sets (volumes).
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
eromfs.list()
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
None.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
An array with the names of the bundled volumes.
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
for _, volname in ipairs(eromfs.list()) do print(volname) end
|
||
|
|
```
|
||
|
|
|
||
|
|
## eromfs.mount
|
||
|
|
Mounts a volume at a specified point in the virtual file system.
|
||
|
|
|
||
|
|
Note that it is technically possible to mount a volume multiple times on
|
||
|
|
different mount points. The benefit of doing so however is questionable.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
eromfs.mount(volname, mountpt)
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `volname` the name of the volume to mount, e.g. `myvol`.
|
||
|
|
- `mountpt` where to mount said volume. Must start with '/', e.g. `/myvol`.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil` on success. Raises an error if the named volume cannot be found, or
|
||
|
|
cannot be mounted.
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
-- Assumes the volume named "myvol" exists
|
||
|
|
eromfs.mount('myvol', '/somewhere')
|
||
|
|
for name,size in pairs(file.list('/somewhere')) do print(name, size) end
|
||
|
|
```
|
||
|
|
|
||
|
|
## eromfs.unmount
|
||
|
|
Unmounts the specified EROMFS volume from the given mount point.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
eromfs.unmount(volname, mountpt)
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `volname` the name of the volume to mount.
|
||
|
|
- `mountpt` the current mount point of the volume.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil` if:
|
||
|
|
- the volume was successfully unmounted; or
|
||
|
|
- the volume was not currently mounted at the given mount point
|
||
|
|
|
||
|
|
Raises an error if:
|
||
|
|
- the unmounting fails for some reason; or
|
||
|
|
- a different EROMFS volume is mounted on the given mount point
|
||
|
|
|
||
|
|
#### Example
|
||
|
|
```lua
|
||
|
|
eromfs.unmount('myvol', '/somewhere')
|
||
|
|
```
|