version.txt

Detecting the EmuTOS version
============================

It has always been possible to detect the presence of EmuTOS (rather
than TOS), by looking at offset 0x2c in the OSHEADER structure
(which is located at the start of the ROM (*)).  This contains the ASCII
bytes 'ETOS' if EmuTOS is the OS.  However, the various version numbers
that are available from fixed locations or via system calls are not
directly related to the EmuTOS version; rather they contain the version
of Atari TOS that is 'closest' to the current EmuTOS version in available
features/behaviour.  So it has not been possible to easily determine the
version of EmuTOS from the binary.

As of 29/October/2019, EmuTOS version information is available via a new
structure called the 'Extended OS header'.  It is located at offset 0x34
from the beginning of the ROM, and you may check for its presence by
verifying that the first 4 bytes are ASCII 'OSXH'.

Following 'OSXH' is a long containing the length of the entire structure
(currently 25), and then 4 binary bytes containing the version, in the
following sequence:
    . major version
    . minor version
    . fix version
        normally zero, but would be non-zero for a hot-fix release (also
        for versions earlier than 1.0, e.g. version 0.9.12 has 12 here)
    . unofficial flag
        zero indicates an official release, otherwise it's a snapshot
        or custom release
For example, for official release 1.0, the 4 bytes are 0x01000000; for
a snapshot release based on official release 11.5, the 4 bytes would
be 0x0b050001.

Following this are these informational fields:
    . a long containing the offset to the version string, as displayed
      on the EmuTOS startup screen and the EmuDesk 'About' dialog box.
      NOTE: this offset is from the start of the ROM, *not* the start of
      the header extension!
    . a long containing various flags, mainly for the use of emulators
    . a word containing a bit mask of the machines that this EmuTOS
      image can run on; bit mapping is as follows:
        0         ST / MegaST
        1         STe / MegaSTe
        2         TT
        3         Falcon
        4         FireBee
        5         M548X evaluation boards
        6         Amiga
        7         (currently reserved)
        8         ARAnyM
       9-15       (currently reserved)
    . a word containing a bit mask of the processors that this EmuTOS
      image can run on; bit mapping is as follows:
        0         68000
        1         68010
        2         68020
        3         68030
        4         68040
        5         68060
        6         68080
        7         (currently reserved)
        8         ColdFire V4e
       9-15       (currently reserved)
Following this is a user-patchable field:
     . a byte containing the default cold boot delay, in seconds.  This
       may be used to allow slow hard disks devices to come ready before
       EmuTOS attempts to access them.  The current default value is 0.

(*) How to find the OSHEADER structure:
- At runtime: OSHEADER address can be found in the sysbase system
  variable, located at 0x4f2.
- In ROM for Atari hardware: OSHEADER is always located at the beginning
  of the ROM, at offset 0.
- In ROM for non-Atari hardware, or special Atari variants such as PRG
  or cartridge, OSHEADER is not located at the very beginning. Actual
  offset may vary. You need to search for 'ETOS' in the first kilobyte,
  for example. Then subtract 0x2c to find the actual start of OSHEADER.
  You may look for the extended OS header afterwards (see OSXH above),
  but remember that all offsets are actually relative to the start of
  OSHEADER.