*****************************************************************
* File format of the TiEmu v2.xx and 3.xx image files           *
* Documentation by Romain Lievin <roms@tilp.info>               *
*                                                               *
* Begin: 2005/05/17                                             *
* Last update: 2010/05/11                                       *
*****************************************************************


Remark: I use the C notation for numbers (12: decimal, 0x1A: hexadecimal, 
'C': character). Moreover, all words are in LSB-MSB format.

This document describes the file format of *.img files.
An TiEmu image file is a composite file which contains:
- a header section
- a pure data section


The TiEmu v2.xx/3.xx image format (revision 2) => IMG_INFO in src/core/images.h
----------------------------------------------

  The following is a table of the bytes that make up such a file.

  Address             Size   What It Contains
  ---------------------------------------------------------------------------
  0x00-0x0F   0-15    16     a signature: "TiEmu img v2.00" (NULL-padded)

  0x10-0x13   16-19   4      structure revision (2)
  0x14-0x17   20-23   4      offset to the data section (0x40)
  0x18        24      1      calculator type (2 = TI92)
  0x19-0x1F   25-29   5      firmware revision (e.g. "2.08\0")
  0x1E        30      1      FLASH/PROM (2/0)
  0x1F        31      1      has boot (1/0)
  0x20-0x23   32-35   4      pure data size
  0x24        36      1      hw type (1/2/3/4)
  0x25        37      1      ROM base address
  0x26        38-59   n      filled with 0 (reserved for future use)
  0x3c-0x3f   60-63   4      pointer on data (unused here)

  0x40-..     64-..          pure data (ROM image)

NOTE: TIEmu versions before 3.03 are buggy: on 64-bit platforms, due to the
use of long and pointer types, they expect 8 bytes instead of 4 for the
structure revision, offset to data section, pure data size and pointer to
data fields.
As a result, older TIEmu versions crash when trying to load images generated
on a 32-bit platform on a 64-bit platform, and vice-versa.
TIEmu 3.03 and later can gracefully handle the loading on 64-bit platforms
of images generated on 32-bit platforms, and vice-versa.



Calculator type (libtifiles defs):

#define TI92        (1 << 0)
#define TI89        (1 << 1)
#define TI92p       (1 << 2)
#define V200        (1 << 3)
#define TI89t       (1 << 4)
 
Note: FLASH upgrades do not have boot block.


The TiEmu v2.xx/3.xx save format (revision 21) => SAV_INFO in src/core/state.h
----------------------------------------------

  The following is a table of the bytes that make up a such file.

  Before this header, there is a "TiEmu v2.00 image format" header.
  And next, there is the following header:

  Address             Size   What It Contains
  ---------------------------------------------------------------------------
  0x40-0x43   0-3     4      structure revision (21)
  0x44-0x47   4-7     4      size of structure
  0x48-0x4b   8-11    4      offset to M68K area
  0x4c-0x4f   12-15   4      offset to IO area
  0x50-0x53   16-19   4      offset to RAM area
  0x54-0x57   20-23   4      offset to HW infos
  0x58-0x5b   24-27   4      offset to FLASH changes
  0x5c-0x5f   28-31   4      offset to bkpts area
  0x60-0x63   32-35   4      offset to image location (size + string)
  0x64-...                   pure data (see below)

NOTE: TIEmu versions before 3.04 are buggy: on 64-bit platforms, due to the
use of long and pointer types, they expect 8 bytes instead of 4 for all
fields of the SAV_INFO structure, and a number of fields of structures below.
As a result, older TIEmu versions crash when trying to load save files generated
on a 32-bit platform on a 64-bit platform, and vice-versa.

@M68K: => regstruct in src/core/uae/newcpu.h

@IO:
  HW1 I/O ports: @HW.io_size bytes
  HW2 I/O ports: @HW.io2_size bytes
  HW3 I/O ports: @HW.io3_size bytes

@RAM:
  RAM contents: @HW.ram_size bytes

@HW: => Ti68kHardware in src/core/ti68k_def.h
  Ti68kHardware structure contents. See below and note at the bottom of the page:

  typedef struct
  {
    time_t  s;
    int    ms;
  } TTIME;

  typedef struct
  {
    // misc (non hardware pseudo-constants)
    int      calc_type;

    int      ram_size;  // RAM size
    int      rom_size;  // ROM size
    int      io_size;  // HWx io size
    int      io2_size;  // HW2 io size
    int      io3_size;  // HW3 io size

    uint32_t rom_base;  // ROM base address
    int      rom_flash;  // ROM type
    char     rom_version[5];  // ROM/AMS version 

    int      hw_type;  // HW1/2/3/4

    int      ti92v1;    // ROM v1.x(y)
    int      ti92v2;    // ROM v2.x

    int      lcd_w;    // LCD physical width
    int      lcd_h;    // LCD physical height

    // keyboard
    int      on_key;

    // lcd
    uint32_t lcd_adr;  // LCD address (as $4c00)
    char*    lcd_ptr;  // direct pointer to LCD in PC RAM
    int      contrast;
    int      log_w;    // LCD logical width
    int      log_h;    // LCD logical height
    int      on_off;
    unsigned long lcd_tick;// used by grayscales

    // memory
    uint8_t*      rom;    // ROM
    uint8_t*      ram;    // RAM
    uint8_t*      io;      // HW1/2/3 i/o ports
    uint8_t*      io2;    // HW2/3   i/o ports
    uint8_t*      io3;    // HW3     i/o ports
    uint8_t*      unused;    // unused

    uint32_t      initial_ssp;// SSP at vector #0
    uint32_t      initial_pc;  // PC  at vector #1

    // timer
    uint8_t       timer_value;// Current timer value
    uint8_t       timer_init;  // Value to reload

    // rtc (hw2)
    uint8_t       rtc_value;  // RTC value

    // rtc (hw3)
    TTIME         rtc3_ref;  // time reference
    TTIME         rtc3_beg;  // time value when
    TTIME         rtc3_load;  // clock is load

    // protection
    int           protect;    // hw protection state
    uint32_t      archive_limit;  // archive memory limit
    int           ram_exec[64];  // RAM page execution protection bitmask

  } Ti68kHardware;

@FLASH: => FLASH_WSM in src/core/ti_hw/flash.h
  For p blocks (p = @HW.rom_size >> 16):
    4 bytes: whether bank has been modified
      If modified:
        64KB: FLASH page contents eg. @HW.rom[p<<16]

@bkpts: => Ti68kBreakpoints in src/core/ti68k_def.h & ADDR_RANGE/ADDR_BITS in src/core/dbg/bkpts.h
  code:
    4 bytes: number of bkpts
      4 bytes: address
      ...
      4 bytes: address
  
  exception:
    same as above
  
  pgmentry:
    same as above
  
  mem_rb:
    same as above
  
  mem_rw:
    same as above
  
  mem_rl:
    same as above
  
  mem_wb:
    same as above
  
  mem_ww:
    same as above
  
  mem_wl:
    same as above
  
  mem_rng_r:
    4 bytes: number of breakpoints
      8 bytes: lower & upper value
      ...
      8 bytes: lower & upper value
  
  mem_rng_w:
    same as above

  bits: (added in rev. 21)
    4 bytes: number of breakpoints
      4 bytes: address
      2 bytes: checks & states
      2 bytes: padding (00)

@image location: 
  4 bytes : string length + 1
  m bytes: ROM image filename (NULL-terminated)

  4 bytes: string length + 1
  n bytes: TIB image filename (NULL-terminated)

Note:
  sizeof(char)   = 1
  sizeof(int)    = 4
  sizeof(long)   = 4
  sizeof(void *) = 8

Note2: if structure is stored in file, padding may appear to round-up size to 4 bytes.
