minimOS file system
Rationale
While a ROM-based system like Durango-X may not depend on it, a file system for managing a mass-storage device is always desirable. But a limited 8-bit system may struggle with the large file systems found on today's storage devices. Thus, a simplified file system should be implemented.
The idea behind this is to simply add a header to any "file" which creates, by simple concatenation, a linked list, easily sorted out by the filesystem software by jumping between headers. This very same principle has been used on the minimOS Operating System as a means to manage ROM contents, but it's suitable for implementing a barebones filesystem in mass-storage devices as well, especially Solid-State ones (like a readily available SD card).
Durango-X volumes
Simply put, a volume is a concatenation of files, each of them preceded by a suitable header. Some padding must be applied at the end of every file, in case its length is not a 512-byte multiple, as required by most storage devices.
From the very first sector (the leading 256 bytes would suffice) of a volume, any file can be accessed as all headers form a linked list; from the file's size (conveniently rounded up to the nearest 512-byte multiple) you may compute the next file's sector number, and so on. When this points to a non-valid header (at least three magic numbers must be checked), the volume has ended.
Note
A single file (with the proper header) is suitable as a whole volume as well, as the sector following it is (very) likely to contain garbage, and will thus fail the header validation procedure.
Warning
In very rare circumstances, older device contents after the volume's end may be recognised as a valid header; this shouldn't be a concern as the only ill effect would be the "recovery" of older files after the volume's contents; but in case of doubt, you may add a fake sector suitably filled ($FF is convenient for most devices) after every volume, for extra safety.
Tip
Concatenating files and ROM images can be easily done with the cat command, like the following example:
cat image1.dux image2.dux image3.dux > durango.av
Volume location
From the point of view of the storage device filesystem, the Durango-X volume is represented by the durango.av file in the root directory of any FAT-formatted device.
Warning
Current bootloader software does NOT check for any host filesystem, assuming the volume is written from the very first block of the device. In Linux, a dd command is suitable for raw writing the volume onto the storage device.
Danger
The use of the dd command or any equivalent one is very risky as any incorrect parameter may result in data loss. Exert extreme caution when writing raw images!
Tip
Flashing the volume into the storage device with the current software can be done in Linux like this:
dd if=path-to/durango.av of=/dev/your-device
Take extreme caution when determining your-device, as any wrong choice will cause data loss.
Header format
Much like the ROM image format, a simple 256-byte block must be provided in front of any file in order to be properly identified and linked to other files on the volume.
| Offset | Size (bytes) | Contents | Description |
|---|---|---|---|
| 0 | 1 | $00 | Magic number #1 (NUL) |
| 1 | 2 | see table below | Signature |
| 3 | 4 | **** |
Reserved |
| 7 | 1 | $0D | Magic number #2 (CR) |
| 8 | n | Filename | C-string with filename |
| 8+n | 1 | $00 | NUL-termination for the above |
| 9+n | m | Comment | C-string with optional comment (n+m ≤ 220 in current version) |
| 9+n+m | 1 | $00 | NUL-termination for the above (mandatory: if no comment is present, two NULs are expected after filename) |
| 10+n+m | 220-n-m | usually $FF | padding |
| 230 ($E6) | 8 | User Field 2 | 8-char string, free for the user |
| 238 ($EE) | 8 | User Field 1 | 8-char string, free for the user |
| 246 ($F6) | 2 | Version (if applies) | Little-endian 16-bit %vvvvrrrrppbbbbbb, where v is version number, r revision, b build and p phase (%00=alpha, %01=beta, %10=Release Candidate, %11=final). |
| 248 ($F8) | 2 | Time | Last modification time in FAT format |
| 250 ($FA) | 2 | Date | Last modification date in FAT format |
| 252 ($FC) | 3 | file size | Includes the 256-byte header. Cannot be over 16 MiB in the current implementation; most likely below 64 KiB. |
| 255 ($FF) | 1 | $00 | Magic number #3 (NUL) |
Signatures list
In order not to depend on file extensions, the minimOS file systems adds a non-mutable file signature which describes the type of file stored afterwards. Currently supported signatures are shown in the table below:
| Signature | Size | Type |
|---|---|---|
dX |
< 64 KiB | executable ROM image |
dA |
< 16 MiB | generic file |
dL |
≤ 16 MiB | free space |
dR |
8.5 KiB | HIRES screen dump (256x256 1bpp) |
dS |
8.5 KiB | Colour screen dump (128x128 4bpp) |
dr |
< 8.5 KiB | RLE-compressed HIRES screen dump (256x256 1bpp) |
ds |
< 8.5 KiB | RLE-compressed Colour screen dump (128x128 4bpp) |
Note
Uncompressed screen dumps include a 256-byte empty leader, in order to be sector-aligned.