Standard file header
Rationale
Although Durango-X is a ROM-based computer, thus not depending on a proper filesystem, the use of a mass-storage device with ROM image files instead of "blowing" and switching physical (E)EPROMs is certainly convenient. Having into account the limitations of an 8-bit computer, especially when dealing with huge modern storage devices, a fully-featured filesystem implemented on the 6502 side would be pretty cumbersome; thus, an intermediate solution is proposed.
The idea behind this is to simply add a standard header to any ROM image (like any individual "file") which creates, by simple concatenation, a linked list of ROM images, easily sorted out by the Durango-X computer thru jumping between headers. This very same principle has been used on the minimOS Operating System as a means to manage ROM contents, but does apply to mass-storage devices as well, especially Solid-State ones (like a readily available SD card).
Tip
This kind of file system has been already implemented for use with the SD card interface on the Development Cartridge, and it's available for source code storage with EhBASIC
This header will provide adequate metadata, with some room for expansion. By the way, even if the desired software is going to live on an EPROM permanently and never downloaded from SD, it does not harm to have the Standard Header all the time, if you have 256 spare bytes for it.
Hardware support
The Durango-X Development Cartridge provides a convenient way to upload and run software on the Durango-X computer. It provides an extra 32 KiB RAM switchable with the standard ROM, plus an inexpensive SD-card interface. While standard ROMs (up to 16 KiB) can be placed on this cartridge for regular use, with a suitable bootloader firmware it allows choosing whithin the ROM images stored in the card, downloading any of them in a matter of seconds, and running the selected software flawlessly -- as the Development Cartridge may lock its RAM after downloading, making it read-only just like a regular ROM.
ROM images
The use of a standardised format for ROM images allows the use of both EPROM blowers and convenient download from SD card or Raspberry Pi from the very same binary.
Just like any other 6502 system, ROMs for Durango-X must have appropriate NMI/RESET/IRQ hardware vectors at the last addresses $FFFA-$FFFF. However, in order to be fully compliant, a suitable header plus some extra information at the end must be provided, according to this document.
Note
In order to be fully compliant with all devices, all ROM images must have a 512-byte multiple size, including all headers and footers.
Header format
A simple 256-byte block must be provided in front of any ROM image in order to be properly identified and linked to other images on the device.
| Offset | Size (bytes) | Contents | Description |
|---|---|---|---|
| 0 | 1 | $00 | Magic number #1 (NUL) |
| 1 | 2 | see table below | Signature |
| 3 | 2 | 16-bit pointer or ** if unused |
Loading address (for Pocket format only) |
| 5 | 2 | 16-bit pointer or ** if unused |
Execution address (for Pocket format only) |
| 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, usually library commit hash |
| 238 ($EE) | 8 | User Field 1 | 8-char string, free for the user, usually main code commit hash |
| 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). Optionally %vvvvrrrrpphhbbbb, where the whole revision number is a 6-bit number %hhrrrr. |
| 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) |
Note
additional metadata may be included just before the user field 2 (offset < 230), as long as a tighter limit is set to filename+comment total length.
Signatures list
In order not to depend on file extensions, the minimOS file system 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 |
pX |
< 24 KiB | Pocket executable to be loaded into standard RAM (under development) |
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. Compressed pictures aren't yes (as of v2.0) supported by the bootloader, and neither are Pocket executables.
Footer format
In order to be fully compliant with the Development Cartridge, some extra content must be provided at the end of the ROM image. More often than not, the actual code from any ROM will end before the standard $FFFA vectors initial address. We need to reserve the last 42 bytes for compliance, just as shown in the following example:
; (actual ROM code above)
.dsb $FFD6 - *, $FF ; padding to reserved area
.asc "DmOS" ; Durango-X ROM signature
.dsb $FFE1 - *, $FF ; padding to Development Cartridge interface
JMP ($FFFC) ; jump to (downloaded) RESET vector
.dsb $FFFA - *, $FF ; standard padding
.word nmi ; standard 6502 hard vectors for the supplied ROM
.word reset
.word irq
Note
While not absolutely necessary, it is highly recommended that the interrupt hard vectors point to JMP ($0200) (for IRQ) and JMP($0202) (for NMI), for ease of integration with debuggers. In this case, the startup code must fill the RAM vectors at $0200-$0203 to make them point to the supplied IRQ and NMI service routines (or to a stored RTI opcode, if not used).
Tip
Pocket format cannot supply the IRQ and NMI hard vectors, thus relies on setting the standard interrupt vectors at $0200 and $0202 as described above. The footer is not needed for this format.
Using ROM images
ROM images compliant with the aforementioned format are suitable for ROM chips, downloadable files stored in a Raspberry Pi server, or even joined into a Durango-X volume. Check the following link for more information about getting these running in Durango-X