Nokia N-Gage and Symbian File Formats

game.n-gage                          -- MIME multipart/mixed
  |
  +-- Part 0: metadata.xml            -- retailer info, store metadata
  |
  +-- Part 1: game.sis               -- SIS v9.x (SISX) package
  |     |
  |     +-- SISController             -- compressed manifest (file paths, metadata)
  |     |
  |     +-- SISData                   -- compressed file payloads
  |           |
  |           +-- runtime.exe         -- E32 image (Marmalade loader)
  |           +-- game.s3e            -- S3E binary (actual game code)
  |           +-- data.dtrz           -- DTRZ archive (game assets)
  |           +-- icon.png            -- resources
  |           +-- ...
  |
  +-- Part 2: patch.sis              -- optional partial upgrade

-- N-Gage Distribution Package
-- MIME multipart/mixed envelope containing SIS installation archives

struct NGagePackage {
  content_type     : "multipart/mixed; boundary=<boundary>"
  parts[]          : {
    headers        : MIMEHeaders          -- Content-Type, Content-Transfer-Encoding
    body           : u8[...]              -- XML metadata | SIS binary data
  }

  -- Part 0: retailer metadata (text/xml)
  -- Part 1: main SIS package (application/sis)
  -- Part 2+: optional partial upgrades

  -- ================================================================
  -- SIS v9.x (SISX) - Type-Length-Value encoded installation archive
  -- ================================================================

  struct SISField {                       -- base TLV container
    type           : u32le                -- field type ID (0..41)
    length         : u32le                -- MSB set: bits[4..30]=len, bits[0..3]=pad
    data           : u8[length]
    _padding       : u8[0..3]             -- align to 4 bytes
  }

  struct SISArray {                       -- typed array (elements omit type field)
    type           : u32le                -- always 2
    length         : u32le
    element_type   : u32le                -- type ID of contained elements
    elements[]     : { length : u32le, data : u8[length], _pad : u8[0..3] }
  }

  struct SISCompressed {
    algorithm      : u32le                -- 0=none, 1=deflate (zlib-wrapped)
    uncompressed   : u64le                -- expected output size
    data           : u8[...]              -- compressed payload
  }

  struct SISContents {                    -- root (type 12)
    controller_crc : SISControllerChecksum?
    data_crc       : SISDataChecksum?
    controller     : SISCompressed {

      struct SISController {              -- type 13
        info         : SISInfo {
          uid        : u32le              -- unique package identifier
          vendor     : SISString          -- UCS-2 encoded
          names      : SISArray<SISString> -- per language
          vendors    : SISArray<SISString>
          version    : { major, minor, build : u32le }
          created    : SISDateTime
          type       : u8                 -- 0=install, 1=augment, 2=patch
          flags      : u8
        }
        options      : SISSupportedOptions
        languages    : SISSupportedLanguages
        prereqs      : SISPrerequisites
        properties   : SISProperties
        logo         : SISLogo?

        install      : SISInstallBlock {
          files      : SISArray {
            struct SISFileDescription {
              target   : SISString        -- e.g. "!:\sys\bin\game.exe"
              mime     : SISString
              caps     : SISCapabilities?
              hash     : SISHash
              op       : u32le            -- 1=install, 2=run, 4=text, 8=null
              op_opts  : u32le
              comp_len : u64le
              raw_len  : u64le
              file_idx : u32le            -- index into DataUnit files
            }
          }
          embedded   : SISArray<SISController>  -- sub-packages
          if_blocks  : SISArray<SISIf>         -- conditional installs
        }

        signatures   : SISSignatureCertificateChain*
        data_index   : u32le              -- selects DataUnit
      }
    }

    data           : SISData {
      units        : SISArray {
        struct SISDataUnit {
          files    : SISArray {
            struct SISFileData {
              payload : SISCompressed<bytes>
            }
          }
        }
      }
    }
  }

  struct SISHeader {                      -- precedes SISContents (16 bytes)
    uid1           : u32le                -- 0x10201A7A
    uid2           : u32le
    uid3           : u32le                -- package UID
    uid_checksum   : u32le
  }

  -- ================================================================
  -- E32 Image - Symbian OS executable (ARM)
  -- ================================================================

  struct E32ImageHeaderV {                -- 124 bytes
    uid1           : u32le                -- 0x1000007A=EXE, 0x10000079=DLL
    uid2           : u32le
    uid3           : u32le                -- application UID
    uid_checksum   : u32le
    signature      : u8[4]               -- "EPOC"
    header_crc     : u32le
    module_version : u32le
    compression    : u32le                -- 0x101F7AFC=deflate, 0x102822AA=bytepair
    tools_version  : u32le
    timestamp      : u64le
    flags          : u32le                -- bit0=DLL, bit3-4=ABI, bit8=debug
    code_size      : u32le
    data_size      : u32le
    heap_min       : u32le
    heap_max       : u32le
    stack_size     : u32le
    bss_size       : u32le
    entry_point    : u32le                -- offset from code_base
    code_base      : u32le
    data_base      : u32le
    dll_ref_count  : u32le
    export_offset  : u32le
    export_count   : u32le
    text_size      : u32le
    code_offset    : u32le                -- file offset to code section
    data_offset    : u32le
    import_offset  : u32le
    code_reloc_off : u32le
    data_reloc_off : u32le
    priority       : u16le                -- 350 = foreground
    cpu_identifier : u16le                -- 0x2000=ARM, 0x2001=ARMv4

    struct E32ImportSection {            -- at import_offset
      total_size   : u32le
      blocks[]     : {
        dll_name_off : u32le            -- offset to DLL name string
        num_imports  : u32le
      }
      ordinals     : u32le[...]           -- import ordinal numbers
      dll_names    : cstring[...]         -- null-terminated ASCII
    }

    struct E32ExportTable {              -- at export_offset
      addresses    : u32le[export_count]  -- relative to code_base
    }

    struct BytepairHeader {              -- if compression = 0x102822AA
      _reserved    : u32le[3]
      unpacked     : u32le
      marker       : u8                   -- 0=256 pairs, else pair count
      pairs        : u8[marker*2]
      data         : u8[...]
    }
  }

  -- ================================================================
  -- S3E Binary - Marmalade SDK game code
  -- ================================================================

  struct S3EHeader {                      -- "XE3U" magic
    magic          : u8[4]               -- "XE3U" 0x55335845
    version        : u32le                -- e.g. 4.14.1 packed
    flags          : u16le
    arch           : u16le                -- 0=ARMv4t, 1=ARMv4, 2=ARMv5t, 3=ARMv5te
    fixup_offset   : u32le
    fixup_size     : u32le
    code_offset    : u32le
    code_file_size : u32le                -- code + initialized data on disk
    code_mem_size  : u32le                -- code_file_size + BSS
    sig_offset     : u32le
    sig_size       : u32le
    entry_offset   : u32le                -- relative to base_addr
    config_offset  : u32le                -- INI-format config block
    config_size    : u32le
    base_addr      : u32le                -- link-time base address
    extra_offset   : u32le
    extra_size     : u32le
    ext_hdr_size   : u32le
    data_offset    : u32le                -- if ext_hdr_size >= 8

    struct FixupSection {                -- at fixup_offset, repeated
      type         : u32le                -- 0=symbols, 1=internal, 2=ARM ext, 3-4=Thumb ext
      size         : u32le                -- includes this 8-byte header

      if type == 0 {                    -- symbol table
        count      : u16le
        names      : cstring[count]       -- S3E API names (ASCII, null-terminated)
      }
      if type == 1 {                    -- internal relocations
        count      : u32le
        offsets    : u32le[count]         -- words needing base fixup
      }
      if type == 2..4 {                 -- external relocations (ARM/Thumb)
        count      : u32le
        entries[]  : {
          off_hi   : u16le
          off_lo   : u16le
          sym_idx  : u16le              -- index into symbol table
        }
      }
    }

    -- API stubs generated at load time:
    -- stub[i] = SVC #(0xFE0000|i) + BX LR (8 bytes each)
  }
}

-- MIME multipart/mixed envelope
Content-Type: multipart/mixed; boundary="<boundary-string>"

--<boundary>
Content-Type: text/xml              -- Part 0: retailer metadata (XML)
[XML body]

--<boundary>
Content-Type: application/sis       -- Part 1: main SIS installation package
[SIS binary data]

--<boundary>
Content-Type: application/sis       -- Part 2: partial upgrade (optional)
[SIS binary data]

--<boundary>--                        -- terminator

struct SISHeader {
  uid1          : u32le       -- 0x10201A7A (fixed magic)
  uid2          : u32le       -- reserved
  uid3          : u32le       -- package UID
  uid_checksum  : u32le       -- checksum of UIDs
}                                -- total: 16 bytes

struct SISField {
  type          : u32le       -- field type identifier (see table below)
  length        : u32le       -- data length in bytes
                                  -- if MSB set: bits[31]=1, bits[4..30]=length, bits[0..3]=padding
                                  -- if MSB clear: length is value, padding = (4 - len%4) % 4
  data          : u8[length]  -- field payload
  _padding      : u8[0..3]   -- zero bytes to 4-byte boundary
}

struct SISArray {
  type          : u32le       -- always 2 (SISArray)
  length        : u32le       -- total array data size
  element_type  : u32le       -- type ID of contained elements
  elements[]    : {           -- repeated until length consumed:
    length      : u32le       --   element data size (NO type field)
    data        : u8[length]  --   element payload
    _padding    : u8[0..3]   --   align to 4-byte boundary
  }
}

struct SISContents {
  controller_checksum  : SISControllerChecksum?   -- optional CRC-16
  data_checksum        : SISDataChecksum?         -- optional CRC-16
  controller           : SISCompressed<SISController>
  data                 : SISData
}

struct SISController {
  info              : SISInfo
  options           : SISSupportedOptions
  languages         : SISSupportedLanguages
  prerequisites     : SISPrerequisites
  properties        : SISProperties
  logo              : SISLogo?                -- optional
  install_block     : SISInstallBlock         -- file list + conditions
  signatures        : SISSignatureCertificateChain*  -- 0 or more
  data_index        : SISDataIndex            -- u32: index into SISData units
}

struct SISInfo {
  uid              : SISUid                  -- u32: unique package identifier
  vendor_name      : SISString               -- UCS-2 encoded
  names            : SISArray<SISString>     -- one per supported language
  vendor_names     : SISArray<SISString>     -- one per supported language
  version          : SISVersion              -- {major, minor, build} as 3x u32
  creation_time    : SISDateTime
  install_type     : u8                      -- see Install Types table
  install_flags    : u8
}

struct SISData {
  data_units    : SISArray<SISDataUnit>   -- one per controller
}

struct SISDataUnit {
  file_data     : SISArray<SISFileData>   -- actual file contents
}

struct SISFileData {
  data          : SISCompressed<bytes>    -- individually compressed file
}

struct SISCompressed {
  algorithm          : u32le       -- 0 = none, 1 = deflate (RFC 1951)
  uncompressed_size  : u64le       -- expected output size
  compressed_data    : u8[...]     -- deflate stream (zlib-wrapped)
}                                   -- total: 12 + compressed_data

struct SISInstallBlock {
  files                : SISArray<SISFileDescription>  -- files to install
  embedded_controllers : SISArray<SISController>      -- embedded sub-packages
  if_blocks            : SISArray<SISIf>             -- conditional install rules
}

struct SISFileDescription {
  target              : SISString       -- install path, e.g. "c:\sys\bin\game.exe"
  mime_type           : SISString       -- MIME type
  capabilities        : SISCapabilities? -- only for executables
  hash                : SISHash
  operation           : u32le           -- 1=install, 2=run, 4=text, 8=null
  operation_options   : u32le
  length              : u64le           -- compressed size
  uncompressed_length : u64le
  file_index          : u32le           -- index into DataUnit file array
}

-- Standard SISX:
SISData -> Array<DataUnit> -> Array<FileData>

-- N-Gage variant:
SISData -> Array<Array<DataUnit>> -> Array<Array<FileData>>

function unwrapNestedArrays(data, targetType, maxDepth) {
  if (maxDepth <= 0) return null;
  const arrayType = readU32(data, 0);
  if (arrayType === targetType) return data;
  if (arrayType === 2) {  // SISArray
    const length = readU32(data, 4);
    const inner = data.slice(8, 8 + length);
    return unwrapNestedArrays(inner, targetType, maxDepth - 1);
  }
  return null;
}

Controller A (data_index=0)         -- uses data_units[0]
  |
  +-- Controller B (data_index=1)    -- absolute = 0+1 = data_units[1]
  |
  +-- Controller C (data_index=2)    -- absolute = 0+2 = data_units[2]
        |
        +-- Controller D (data_index=1) -- absolute = 0+2+1 = data_units[3]

struct E32ImageHeaderV {
  -- UIDs and identity (16 bytes)
  uid1              : u32le       -- 0x1000007A (EXE) or 0x10000079 (DLL)
  uid2              : u32le       -- secondary UID
  uid3              : u32le       -- application UID
  uid_checksum      : u32le       -- CRC of uid1..uid3

  -- Header metadata (16 bytes)
  signature         : u8[4]       -- "EPOC" 0x434F5045
  header_crc        : u32le       -- CRC-32 of header
  module_version    : u32le       -- major.minor.build packed
  compression_type  : u32le       -- see compression table

  -- Build info (12 bytes)
  tools_version     : u32le
  time_lo           : u32le       -- build timestamp (low 32 bits)
  time_hi           : u32le       -- build timestamp (high 32 bits)

  -- Flags and sizes (28 bytes)
  flags             : u32le       -- EXE/DLL, ABI version, debug, SMP-safe
  code_size         : u32le       -- size of code section
  data_size         : u32le       -- size of initialized data
  heap_size_min     : u32le
  heap_size_max     : u32le
  stack_size        : u32le
  bss_size          : u32le       -- uninitialized data (zeroed at load)

  -- Addresses (12 bytes)
  entry_point       : u32le       -- offset from code_base
  code_base        : u32le       -- base address for code
  data_base         : u32le       -- base address for data

  -- Import/Export info (16 bytes)
  dll_ref_count     : u32le       -- number of imported DLLs
  export_offset     : u32le       -- offset to export table
  export_count      : u32le       -- number of exported functions
  text_size         : u32le       -- size of text section within code

  -- Section offsets (20 bytes)
  code_offset       : u32le       -- file offset to code
  data_offset       : u32le       -- file offset to data
  import_offset     : u32le       -- file offset to import table
  code_reloc_offset : u32le       -- file offset to code relocations
  data_reloc_offset : u32le       -- file offset to data relocations

  -- CPU and priority (4 bytes)
  priority          : u16le       -- process priority (350 = foreground)
  cpu_identifier    : u16le       -- target CPU (see CPU types)
}                                   -- total: 124 bytes (0x7C) base header

struct E32ImportSection {
  total_size    : u32le           -- size of entire import section
  blocks        : E32ImportBlock[dll_ref_count]
  -- followed by ordinal arrays and DLL name strings
}

struct E32ImportBlock {
  dll_name_offset  : u32le        -- offset from import section start to DLL name
  num_imports      : u32le        -- number of imported ordinals
}                                   -- total: 8 bytes per DLL

struct BytepairHeader {
  _reserved       : u32le[3]    -- 12 bytes reserved
  unpacked_size   : u32le       -- decompressed output size
  marker          : u8          -- 0 = 256 pairs, else = pair count
  pair_table      : u8[marker*2] -- substitution pairs
  compressed_data : u8[...]     -- bytes referencing pair table
}

struct E32ExportTable {
  addresses     : u32le[export_count]  -- function addresses relative to code_base
}

struct S3EHeader {
  magic           : u8[4]       -- "XE3U" 0x55335845
  version         : u32le       -- major.minor.patch packed (e.g. 4.14.1)
  flags           : u16le
  arch            : u16le       -- 0=ARMv4t, 1=ARMv4, 2=ARMv5t, 3=ARMv5te
  fixup_offset    : u32le       -- offset to fixup/relocation section
  fixup_size      : u32le       -- total fixup section size
  code_offset     : u32le       -- offset to code+data blob
  code_file_size  : u32le       -- bytes on disk (code + initialized data)
  code_mem_size   : u32le       -- code_file_size + BSS
  sig_offset      : u32le       -- signature section
  sig_size        : u32le
  entry_offset    : u32le       -- entry point relative to base_addr
  config_offset   : u32le       -- offset to embedded config text (INI-like)
  config_size     : u32le
  base_addr       : u32le       -- original link-time base address
  extra_offset    : u32le
  extra_size      : u32le
  ext_hdr_size    : u32le       -- extended header size
  data_offset     : u32le       -- if ext_hdr_size >= 8: data section offset
}

-- Typical memory layout after S3E load
0x00000000 - 0x00000FFF  null page (writes dropped)
0x00001000 - 0x00001007  halt stub: NOP + B . (infinite loop)
0x00100000 - code end   code section (write-protected)
code end   - data end   initialized data section (RW)
data end   - mem end    BSS (zeroed at load, RW)
mem end+4K - stubs end  S3E API stubs (SVC + BX LR pairs)
0x00300000              framebuffer (176x208, 16bpp = 73216 bytes)
0x02000000              heap base (malloc arena)

struct FixupSection {
  type    : u32le       -- 0=symbols, 1=internal relocs, 2-4=external relocs
  size    : u32le       -- total section size (including this header)
  data    : u8[size-8]  -- section-specific payload
}

-- stub[i] at stubBase + i*8:
0xEFFExxxx    SVC #(0xFE0000 | i)   -- trap to HLE handler
0xE12FFF1E    BX  LR                -- return to caller

-- ARM BL instruction encoding:
--   bits[31:28] = condition (preserved from original)
--   bits[27:25] = 101 (branch opcode)
--   bit[24]     = L (1 for BL, 0 for B)
--   bits[23:0]  = signed offset / 4

stubAddr  = stubBase + symbolIndex * 8
callAddr  = loadBase + relocOffset
offset24  = (stubAddr - (callAddr + 8)) >> 2  -- ARM pipeline: PC = addr + 8
newInstr  = (origInstr & 0xF0000000) | 0x0B000000 | (offset24 & 0x00FFFFFF)

-- Thumb BL encoding (two halfwords, little-endian in memory):
--   halfword[0] = 0xF000 | offset_hi[10:0]   (prefix)
--   halfword[1] = 0xE800 | offset_lo[10:0]   (suffix, BLX)

offset    = stubAddr - (callAddr + 4)          -- Thumb pipeline: PC = addr + 4
offset_hi = (offset >> 12) & 0x7FF
offset_lo = (offset >> 1)  & 0x7FF

-- Written as bytes (little-endian):
mem[addr+0] = offset_hi & 0xFF
mem[addr+1] = 0xF0 | ((offset_hi >> 8) & 0x07)
mem[addr+2] = offset_lo & 0xFF
mem[addr+3] = 0xE8 | ((offset_lo >> 8) & 0x07)