112 lines
3.9 KiB
Plaintext
112 lines
3.9 KiB
Plaintext
UXN ROM METADATA PROPOSAL v2 (wip)
|
|
|
|
by d6
|
|
|
|
TL;DR SUMMARY
|
|
|
|
i'm proposing a standardized "prelude" to uxn roms which can be used by
|
|
emulators but also by external programs to understand what a rom is and what
|
|
it can do.
|
|
|
|
METADATA DEVICE
|
|
|
|
PORT WIDTH NAME DESCRIPTION
|
|
f0 2 bytes version rom data/metadata version
|
|
f2 2 bytes fields address of text metadata fields
|
|
f4 2 bytes icon-type icon depth, transparency, and size
|
|
f6 2 bytes icon-data address of icon data
|
|
f8 2 bytes max-addr maximum memory address used
|
|
fa 2 bytes manifest potato manifest
|
|
fc 2 bytes unused
|
|
fe 2 bytes unused
|
|
|
|
some requirements:
|
|
|
|
- metadata writes must come before other writes
|
|
+ writes must be: LIT2 ?? ?? LIT f? DEO2 (i.e. 6 bytes)
|
|
+ writes to System/r, g, and b are treated as metadata
|
|
these are optional but provide hinting about icon rendering
|
|
they must have the form LIT2 ?? ?? LIT .System/r DEO2
|
|
- version (f0) must come first
|
|
- after that, metadata writes can have any order
|
|
- this means roms with metadata have 6-48 bytes of header
|
|
+ duplicate metadata writes will be ignored
|
|
+ addresses in the zero page (i.e. 0000) are ignored
|
|
|
|
this means that metadata parsers can read the header
|
|
in groups of six bytes. for example:
|
|
|
|
- a0 WX YZ 80 f0 37 ( uxn version WXYZ )
|
|
- a0 WX YZ 80 f2 37 ( metadata text fields start at address WXYZ )
|
|
- a0 WX YZ 80 f4 37 ( icon depth, transparency, and size defined by WXYZ )
|
|
- a0 WX YZ 80 f6 37 ( icon data starts at address WXYZ )
|
|
- a0 WX YZ 80 f8 37 ( rom won't read/write addresses > WXYZ )
|
|
- a0 WX YZ 80 fa 37 ( rom menu data starts at address WXYZ )
|
|
|
|
FIELD DESCRIPTIONS
|
|
|
|
VERSION (f0)
|
|
|
|
this is just a two byte value. my idea is to have a fixed first byte
|
|
for uxn (e.g. "u") and then use version numbers starting from 00,
|
|
which we would increase anytime we change the behavior of the VM
|
|
(either devices or opcodes). this would make it possible for emulators
|
|
to give good error messages when roms can't be supported.
|
|
|
|
the first byte is present so that if someone later decides to fork uxn
|
|
they can choose a different letter. at that point how they use version
|
|
numbers is up to them (they could either do their own thing or follow
|
|
the uxn versions) but again it would make it easier to understand what
|
|
is going on.
|
|
|
|
FIELDS (f2)
|
|
|
|
this field is the address of the following four text fields:
|
|
|
|
- name
|
|
- version
|
|
- author
|
|
- description
|
|
|
|
the strings are each null-terminated, so the address should point to
|
|
the start of the name. fields can be empty. there is no fixed limit on
|
|
size but especially the first three fields should ideally fit on one
|
|
line of text.
|
|
|
|
ICON TYPE (f4)
|
|
|
|
icon depth, transparency, and size as specified by two bytes.
|
|
|
|
bit 16: color 1 transparency (0x8000 transparent, 0x0000 opaque)
|
|
bits 15-10: unused
|
|
bit 9: color depth (0x0100 2-bit color, 0x0000 1-bit color)
|
|
bits 5-8: icon width in tiles (0x10 = 1 tile, 0x20 = 2 tiles, etc.)
|
|
bits 1-4: icon height in tiles (0x01 = 1 tile, 0x02 = 2 tiles, etc.)
|
|
|
|
examples:
|
|
- 0x0000: no icon (0x0 icon size)
|
|
- 0x0011: 8x8 icons with 1-bit color and no transparency
|
|
- 0x8122: 16x16 icons with 2-bit color and transparency
|
|
- 0x8033: 24x24 icons with 2-bit color and no transparency
|
|
|
|
ICON DATA (f6)
|
|
|
|
this is a list of absolute addresses for tile data. its length is
|
|
determined by the dimensions specified in ICON TYPE. for example, if
|
|
icon type is 0x0022 (16x16 icon) then there would be 8 bytes
|
|
representing the addresses of 4 tiles.
|
|
|
|
MAX ADDR (f8)
|
|
|
|
this optional field lets a rom specificy the maximum address it will
|
|
read from or write to. currently it is purely informational but in the
|
|
future emulators could enforce this limit. it might also be useful for
|
|
an operating system running on varvara which is trying to
|
|
load/store/swap memory for multiple roms.
|
|
|
|
MANIFEST (fa)
|
|
|
|
this is the manifest data as specified by potato.
|
|
|
|
see http://wiki.xxiivv.com/site/manifest.html
|