On romType and GT1 compatibility

Using, learning, programming and modding the Gigatron and anything related.
Forum rules
Be nice. No drama.
Post Reply
User avatar
marcelk
Posts: 488
Joined: 13 May 2018, 08:26

On romType and GT1 compatibility

Post by marcelk »

Docs/GT1-format.txt only briefly mentions the romType zero-page variable. That is fine as long as there are no different ROMs, but that will change and from that point we'll need to give this variable a meaning. Actually that is backwards: we want some chance of compatibility between ROM versions so that GT1 files keep working, and to avoid frustration with users. At least we need some agreement beween ROM makers and GT1 makers of what constitutes of the stable part of the Gigatron ROM interface, and what doesn't.. romType is intended to be part of the solution (the other parts are interface.json, and this forum...).

[TL;DR]:
  1. romType will increase with every released ROM
  2. Check romType if your program uses features that are not present in ROM v1
  3. Only features described in interface.json should remain stable over ROM versions
[/TL;DR]

Purpose of romType variable

The intent is that GT1 applications can detect the presence of ROM features by inspecting only this memory location. There are two types of ROM features: those listed in interface.json, and those not listed there. Features might still be described elsewhere, but just by being documented doesn't make a feature part of the intended, stable, interface. The goal of interface.json is to provide a STABLE interface between GT1 files and ROM versions that can load such files. We only add new things to interface.json, never(*) remove, rename or change bindings once they are defined. This should help with future compatibility of GT1 files. Things that are not in interface.json can, and will, disappear or change at any time and should not be relied upon. (For example: some zero-page variables used by the video loop, certain SYS functions, specific entry points in code pages, location of application ROM images, built-in pictures, the shape of the font, values in ROM addresses etc...).

Value increases with ROM releases

romType is an unsigned 8-bit value that strictly goes up with each "official" ROM release, no matter how small the delta. So if you want to test for the presence of a feature, compare the magnitude of this value to that of the first ROM that introduced it. For historic reasons, the first romType value was 0x1c for ROMv1. Don't rely on the meaning of individual bits. Also, the value can go up by an arbitrary number with each release, so there no way to "calculate" the displayed version name as will be known by the user.

With this it is not possible that two "official" ROM releases have the same romType value. However, third-party ROMs with compatible GT1 loading capability are adviced to use the same romType value as the ROM version they were derived from.

End user is in control

The romType value is in RAM, not ROM! This is on purpose, so that the end user always has an escape hatch and can put a value in there that a troublesome GT1 file expects to see. The user has the final say on what happens on the system, not the file... So please don't try to second-guess the romType value as a programmer.

Don't crash

GT1 files that need a certain interface feature that is not present in earlier ROMs should degrade in performance or functionality, or fail gracefully, but definitely NOT crash. By publishng a file as GT1 you're signaling that you expect the file can be loaded with any past, present or future ROM version. To help remind the programmer which features were introduced after ROM v1, and therefore require a romType check before use, we'll add a ROM version number to their names.

32K vs. 64K

It is understood that a program that really requires an extended 64K memory crashes while loading on a 32K system. In that case please end the filename with "_64K.gt1". The main idea is still that a user doesn't get unexpected surprises.

Hack files

Of course the Gigatron is an open system, so there will be plenty of methods to detect what kind of ROM you're running on. If you make a GT1 file that you know depends on undocumented features (or better phrased: features not listed in interface.json), it is adviced to give it a different extension. For example 'Demo3_ROMv1only.gt1x' (I always append a 'x' to such experimental files with no expectation of compatibility.)

Evolution and process

We should be pragmatic about these rules. A list of simple numbers won't ever fully describe the exact boundary of the INTENDED interface: there will always be some assumptions that remain implicit, such as the meaning of certain values or the exact sequence of certain events. It is also possible that some feature wasn't declared as a stable interface, but that there are good reasons to make it so retro-actively. Please feel free to discuss in GitHub or in the user forum. Basically you're then asking "I'm using this implicit feature now and I would like it to keep working in future ROMs, can we fixate it and document it?".

Incompatible ROM upgrades

If we ever decide to make a truly incompatible step in ROM versions, one that breaks many GT1 files out there, we should start using a different extension for object files for what then has effectively become a new platform (GT2 comes to mind). This is conceivable if we ever change something really big about the architecture, such as the memory map or the vCPU instruction set. Of course we hope we can get very far without ever doing something like this...

(*) Have said that, we retro-actively removed 'SYS_Reset_36', 'SYS_NextByteIn_32' and 'SYS_LoaderPayloadCopy_34' from the interface files. Their inclusion turned out to be a bit premature and they had to change after ROM v1. There will be no alternative for SYS_ReadNextInput_32 and SYS_LoaderPayloadCopy_34 in interface.json soon: it is part of Loader, but that is logically not a GT1 file. 'SYS_Reset_36' was just an intermediate in the soft reset sequence. The proper way to initiate that is by redirecting the vCPU to vReset (0x1f0). So we have retro-actively added vReset to the interface.json files instead.
User avatar
marcelk
Posts: 488
Joined: 13 May 2018, 08:26

Re: On romType and GT1 compatibility

Post by marcelk »

As the GitHub lurkers would have noted, we've frozen a minor update to the kit's ROM ("v2"), before vacationing and getting to work on a much more substantial update planned for after this summer. The main reason is to make Snake more fun for color-blinded people. It was unfortunate we originally used green for edible dots and orange for the poisonous ones...

The built-in applications remain exactly the same. We've changed a few things under the hood however that low-level hackers might find interesting:
  • there are two extra scan line modes ("A-C-" proposed by at67, and "A---" proposed by HGM),
  • The Easter egg got replaced,
  • we fixed a bug fixed in the sound generation that caused some humming, and
  • the system startup is a bit snappier.
Reset.gcl use two new SYS function for the latter. Regarding compatibility, it is probably wise to stay clear from these functions for now, at least until people have MUCH more compelling reasons to go through an upgrade phase from ROM v1. [If still tempted to use these, please at least do a runtime romType check and provide a fall-back for the majority of users who have ROM v1.]

After summer we think we can have a "ROM v3" with BASIC supported in a proper manner, all kinds of keyboard support and, hopefully, some sprite acceleration and hopefully some of your built-in games. Such would really bring the platform to a next level.
Post Reply