Files
openhmi-nx/src/nxhmi/container.py
T

172 lines
6.1 KiB
Python
Raw Normal View History

"""The .HMI container: a small file system with a checksummed, duplicated file table.
Layout (all offsets absolute, little-endian):
0x000000 file table: count(u32), count * 28-byte entries, then table checksum (u32)
0x080000 exact backup copy of the file table (+ checksum)
0x380000 u32 0xFFFFFFFF marker
0x6FFFF8 b"ver21234"
0x700000 entry data, packed back to back
Entry (28 bytes): name[16] (NUL padded), start(u32), size(u32), deleted(u8), 3 more bytes
(not interpreted by us; kept as-is, written as 0 for new entries). A deleted entry also has
the first byte of its name set to 0 -- the Editor matches entries by name, so the flag alone
is not enough.
"""
from __future__ import annotations
import struct
from dataclasses import dataclass, field
from . import checksum
TABLE_OFFSET = 0x000000
BACKUP_TABLE_OFFSET = 0x080000
MARKER_OFFSET = 0x380000
VERSION_OFFSET = 0x6FFFF8
VERSION_MAGIC = b"ver21234"
DATA_OFFSET = 0x700000
ENTRY_SIZE = 28
MAX_TABLE_BYTES = BACKUP_TABLE_OFFSET - TABLE_OFFSET - 4
class HMIError(Exception):
pass
@dataclass
class Entry:
name: str
start: int
size: int
deleted: bool = False
extra: bytes = b"\0\0\0" # the 3 trailing entry bytes
raw_name: bytes = b"" # name exactly as stored (deleted entries are mangled)
def pack(self) -> bytes:
nm = self.raw_name if self.raw_name else self.name.encode("latin-1")
nm = nm[:16].ljust(16, b"\0")
if self.deleted:
nm = b"\0" + nm[1:]
return nm + struct.pack("<IIB", self.start, self.size, 1 if self.deleted else 0) + self.extra[:3].ljust(3, b"\0")
@dataclass
class HMIFile:
raw: bytearray
entries: list[Entry] = field(default_factory=list)
# ------------------------------------------------------------------ reading
@classmethod
def load(cls, path) -> "HMIFile":
with open(path, "rb") as f:
return cls.from_bytes(f.read())
@classmethod
def from_bytes(cls, data: bytes) -> "HMIFile":
raw = bytearray(data)
entries = cls._read_table(raw, TABLE_OFFSET)
if entries is None:
entries = cls._read_table(raw, BACKUP_TABLE_OFFSET)
if entries is None:
raise HMIError("both file tables are corrupt (checksum mismatch)")
return cls(raw, entries)
@staticmethod
def _read_table(raw: bytes, base: int):
if len(raw) < base + 4:
return None
count, = struct.unpack_from("<I", raw, base)
end = base + 4 + count * ENTRY_SIZE
if count > MAX_TABLE_BYTES // ENTRY_SIZE or end + 4 > len(raw):
return None
stored, = struct.unpack_from("<I", raw, end)
if checksum.table_crc(bytes(raw[base:end])) != stored:
return None
out = []
for i in range(count):
off = base + 4 + i * ENTRY_SIZE
nm, start, size, deleted = struct.unpack_from("<16sIIB", raw, off)
extra = bytes(raw[off + 25: off + 28])
out.append(Entry(nm.rstrip(b"\0").decode("latin-1"), start, size, bool(deleted), extra, nm))
return out
def live(self) -> list[Entry]:
return [e for e in self.entries if not e.deleted]
def find(self, name: str) -> Entry | None:
for e in self.entries:
if not e.deleted and e.name == name:
return e
return None
def read(self, name: str) -> bytes:
e = self.find(name)
if e is None:
raise KeyError(name)
return bytes(self.raw[e.start:e.start + e.size])
def names(self) -> list[str]:
return [e.name for e in self.live()]
def table_ok(self) -> tuple[bool, bool]:
return (self._read_table(self.raw, TABLE_OFFSET) is not None,
self._read_table(self.raw, BACKUP_TABLE_OFFSET) is not None)
# ------------------------------------------------------------------ writing
def write(self, name: str, data: bytes) -> None:
"""Replace (or add) an entry the way the Editor does: append the data at the end of the
file, mark the old entry deleted, add a new entry. Call fix_checksums()/save() after."""
old = self.find(name)
start = len(self.raw)
self.raw += data
if old is not None:
old.deleted = True
self.entries.append(Entry(name, start, len(data)))
def delete(self, name: str) -> None:
e = self.find(name)
if e is None:
raise KeyError(name)
e.deleted = True
def _table_bytes(self) -> bytes:
return struct.pack("<I", len(self.entries)) + b"".join(e.pack() for e in self.entries)
def _store_tables(self) -> None:
tbl = self._table_bytes()
if len(tbl) > MAX_TABLE_BYTES:
raise HMIError("file table too large")
blob = tbl + struct.pack("<I", checksum.table_crc(tbl))
for base in (TABLE_OFFSET, BACKUP_TABLE_OFFSET):
# clear the old table area (old one may have been longer)
old_count, = struct.unpack_from("<I", self.raw, base)
old_len = min(4 + old_count * ENTRY_SIZE + 4, MAX_TABLE_BYTES)
self.raw[base:base + max(old_len, len(blob))] = bytes(max(old_len, len(blob)))
self.raw[base:base + len(blob)] = blob
def to_bytes(self) -> bytes:
self._store_tables()
return bytes(self.raw)
def save(self, path) -> None:
with open(path, "wb") as f:
f.write(self.to_bytes())
def compacted(self) -> "HMIFile":
"""A fresh file containing only the live entries, packed from DATA_OFFSET."""
return build([(e.name, self.read(e.name)) for e in self.live()])
def build(items: list[tuple[str, bytes]]) -> HMIFile:
"""Create a new .HMI container from (name, data) pairs, in the given order."""
raw = bytearray(DATA_OFFSET)
struct.pack_into("<I", raw, MARKER_OFFSET, 0xFFFFFFFF)
raw[VERSION_OFFSET:VERSION_OFFSET + 8] = VERSION_MAGIC
entries = []
for name, data in items:
entries.append(Entry(name, len(raw), len(data)))
raw += data
f = HMIFile(raw, entries)
f._store_tables()
return f