🆕 ASAM API for hexfiles

Author: christoph2

docs/README.rst

@@ -323,6 +323,55 @@ The folling types are supported:
 
 In any case, endianess suffixes **_be** or **_le** are required.
 
+For ASAM workflows there are dedicated helpers with explicit byte-order names:
+
+.. code-block:: python
+
+   img0 = Image([Section(0x1000, bytes(64))])
+   img0.write_asam_numeric(0x1000, 0x11223344, "ULONG", "MSB_FIRST")
+   img0.write_asam_numeric(0x1004, 0x11223344, "ULONG", "MSB_FIRST_MSW_LAST")
+   img0.write_asam_numeric(0x1008, 0x11223344, "ULONG", "MSB_LAST_MSW_FIRST")
+
+   print(hex(img0.read_asam_numeric(0x1000, "ULONG", "MSB_FIRST")))
+   print(hex(img0.read_asam_numeric(0x1004, "ULONG", "MSB_FIRST_MSW_LAST")))
+   print(hex(img0.read_asam_numeric(0x1008, "ULONG", "MSB_LAST_MSW_FIRST")))
+
+   # All reads print 0x11223344 again.
+
+Supported ASAM byte orders:
+
+* MSB_FIRST
+* MSB_LAST
+* MSB_FIRST_MSW_LAST (word-swap)
+* MSB_LAST_MSW_FIRST (word-swap)
+* LITTLE_ENDIAN (legacy alias for MSB_LAST)
+* BIG_ENDIAN (legacy alias for MSB_FIRST)
+
+Supported ASAM numeric datatypes:
+
+* UBYTE, SBYTE
+* UWORD, SWORD
+* ULONG, SLONG
+* A_UINT64, A_INT64
+* FLOAT16_IEEE, FLOAT32_IEEE, FLOAT64_IEEE
+
+ASAM string helpers are available, too:
+
+.. code-block:: python
+
+   img0.write_asam_string(0x1020, "MOTOR", "ASCII")
+   img0.write_asam_string(0x1030, "Drehzahl", "UTF8")
+
+   print(img0.read_asam_string(0x1020, "ASCII"))
+   print(img0.read_asam_string(0x1030, "UTF8"))
+
+Supported ASAM string datatypes:
+
+* ASCII
+* UTF8
+* UTF16
+* UTF32
+
 Arrays are also supported.
 
 .. code-block:: python

docs/howto.rst

@@ -53,6 +53,28 @@ Read/write typed values at absolute addresses
    img.write_numeric_array(0x2004, [1, 2, 3, 4], "uint16_le")
    img.write_string(0x2010, "hello")
 
+Read/write ASAM values (incl. word-swap byte orders)
+-----------------------------------------------------
+
+.. code-block:: python
+
+   from objutils import Image, Section
+
+   img = Image([Section(0x3000, bytes(64))])
+
+   # ASAM numeric helpers
+   img.write_asam_numeric(0x3000, 0x11223344, "ULONG", "MSB_FIRST")
+   img.write_asam_numeric(0x3004, 0x11223344, "ULONG", "MSB_FIRST_MSW_LAST")
+   img.write_asam_numeric(0x3008, 0x11223344, "ULONG", "MSB_LAST_MSW_FIRST")
+
+   value0 = img.read_asam_numeric(0x3000, "ULONG", "MSB_FIRST")
+   value1 = img.read_asam_numeric(0x3004, "ULONG", "MSB_FIRST_MSW_LAST")
+   value2 = img.read_asam_numeric(0x3008, "ULONG", "MSB_LAST_MSW_FIRST")
+
+   # ASAM string helpers
+   img.write_asam_string(0x3010, "MOTOR", "ASCII")
+   name = img.read_asam_string(0x3010, "ASCII")
+
 Extract loadable image from ELF
 -------------------------------
 

docs/tutorial.rst

@@ -86,6 +86,57 @@ Supported scalar types:
 
 An endianness suffix (``_be`` or ``_le``) is required.
 
+ASAM byte order and datatype helpers
+------------------------------------
+
+For ECU/ASAM style type names and byte orders (including word-swap variants), use the dedicated ASAM helpers:
+
+.. code-block:: python
+
+   from objutils import Image, Section
+
+   img = Image([Section(0x2000, bytes(64))])
+
+   # ASAM numerics
+   img.write_asam_numeric(0x2000, 0x11223344, "ULONG", "MSB_FIRST")
+   img.write_asam_numeric(0x2004, 0x11223344, "ULONG", "MSB_FIRST_MSW_LAST")
+   img.write_asam_numeric(0x2008, 0x11223344, "ULONG", "MSB_LAST_MSW_FIRST")
+
+   # Roundtrip reads
+   a = img.read_asam_numeric(0x2000, "ULONG", "MSB_FIRST")
+   b = img.read_asam_numeric(0x2004, "ULONG", "MSB_FIRST_MSW_LAST")
+   c = img.read_asam_numeric(0x2008, "ULONG", "MSB_LAST_MSW_FIRST")
+
+   # ASAM strings
+   img.write_asam_string(0x2010, "MOTOR", "ASCII")
+   img.write_asam_string(0x2020, "Drehzahl", "UTF8")
+   s0 = img.read_asam_string(0x2010, "ASCII")
+   s1 = img.read_asam_string(0x2020, "UTF8")
+
+Supported ASAM byte orders:
+
+- ``MSB_FIRST``
+- ``MSB_LAST``
+- ``MSB_FIRST_MSW_LAST``
+- ``MSB_LAST_MSW_FIRST``
+- ``LITTLE_ENDIAN`` (legacy alias for ``MSB_LAST``)
+- ``BIG_ENDIAN`` (legacy alias for ``MSB_FIRST``)
+
+Supported ASAM numeric datatypes:
+
+- ``UBYTE``, ``SBYTE``
+- ``UWORD``, ``SWORD``
+- ``ULONG``, ``SLONG``
+- ``A_UINT64``, ``A_INT64``
+- ``FLOAT16_IEEE``, ``FLOAT32_IEEE``, ``FLOAT64_IEEE``
+
+Supported ASAM string datatypes:
+
+- ``ASCII``
+- ``UTF8``
+- ``UTF16``
+- ``UTF32``
+
 CLI companions
 --------------
 

objutils/__init__.py

@@ -13,7 +13,7 @@
 The first parameter is always the codec name.
 """
 
-__version__ = "0.9.1"
+__version__ = "0.10.0"
 
 __all__ = [
     "Image",

objutils/image.py

@@ -617,6 +617,29 @@ def write_numeric(self, addr: int, value: Union[int, float], dtype: str, **kws:
         """
         self._call_address_function("write_numeric", addr, value, dtype, **kws)
 
+    def read_asam_numeric(self, addr: int, dtype: str, byte_order: str = "MSB_LAST", **kws: Any) -> Union[int, float]:
+        """Read a numeric ASAM datatype with ECU byte order semantics."""
+        return self._call_address_function("read_asam_numeric", addr, dtype, byte_order, **kws)
+
+    def write_asam_numeric(
+        self,
+        addr: int,
+        value: Union[int, float],
+        dtype: str,
+        byte_order: str = "MSB_LAST",
+        **kws: Any,
+    ) -> None:
+        """Write a numeric ASAM datatype with ECU byte order semantics."""
+        self._call_address_function("write_asam_numeric", addr, value, dtype, byte_order, **kws)
+
+    def read_asam_string(self, addr: int, dtype: str, length: int = -1, **kws: Any) -> str:
+        """Read an ASAM string datatype (ASCII/UTF8/UTF16/UTF32)."""
+        return self._call_address_function("read_asam_string", addr, dtype, length, **kws)
+
+    def write_asam_string(self, addr: int, value: str, dtype: str, **kws: Any) -> None:
+        """Write an ASAM string datatype (ASCII/UTF8/UTF16/UTF32)."""
+        self._call_address_function("write_asam_string", addr, value, dtype, **kws)
+
     def read_numeric_array(self, addr: int, length: int, dtype: str, **kws: Any) -> list[Union[int, float]]:
         """Read array of numeric values from image.
 

objutils/section.py

@@ -157,7 +157,7 @@
 __copyright__ = """
     objutils - Object file library for Python.
 
-   (C) 2010-2025 by Christoph Schueler <github.com/Christoph2,
+   (C) 2010-2026 by Christoph Schueler <github.com/Christoph2,
                                         cpu12.gems@googlemail.com>
 
    All Rights Reserved
@@ -218,6 +218,7 @@
     "int32": "i",
     "uint64": "Q",
     "int64": "q",
+    "float16": "e",
     "float32": "f",
     "float64": "d",
 }
@@ -231,6 +232,7 @@
     "int32": 4,
     "uint64": 8,
     "int64": 8,
+    "float16": 2,
     "float32": 4,
     "float64": 8,
 }
@@ -241,13 +243,46 @@
     "be": ">",
 }
 
+ASAM_BYTEORDER_ALIASES = {
+    "LITTLE_ENDIAN": "MSB_LAST",
+    "BIG_ENDIAN": "MSB_FIRST",
+}
+
+ASAM_STRING_ENCODINGS = {
+    "ASCII": "ascii",
+    "UTF8": "utf-8",
+    "UTF16": "utf-16",
+    "UTF32": "utf-32",
+}
+
+ASAM_NUMERIC_DTYPES = {
+    "UBYTE": "uint8",
+    "SBYTE": "int8",
+    "UWORD": "uint16",
+    "SWORD": "int16",
+    "ULONG": "uint32",
+    "SLONG": "int32",
+    "A_UINT64": "uint64",
+    "A_INT64": "int64",
+    "FLOAT16_IEEE": "float16",
+    "FLOAT32_IEEE": "float32",
+    "FLOAT64_IEEE": "float64",
+}
+
+ASAM_ENDIAN_FOR_BYTEORDER = {
+    "MSB_FIRST": "be",
+    "MSB_LAST": "le",
+    "MSB_FIRST_MSW_LAST": "be",
+    "MSB_LAST_MSW_FIRST": "le",
+}
+
 TypeInformation = namedtuple("TypeInformation", "type byte_order size")
 
 DTYPE = re.compile(
     r"""
       (?:(?P<uns>u)?int(?P<len>8 | 16 | 32 | 64)(?P<sep>[-/_:])(?P<end> be | le))
     | (?P<byte>byte)
-    | (?P<flt>float)(?P<flen>32 | 64)""",
+    | (?P<flt>float)(?P<flen>16 | 32 | 64)""",
     re.IGNORECASE | re.VERBOSE,
 )
 
@@ -512,6 +547,50 @@ def _getformat(self, dtype: str, length: int = 1) -> str:
         else:
             return f"{BYTEORDER.get(bo)}{FORMATS.get(fmt)}"
 
+    def _resolve_asam_byteorder(self, byte_order: str) -> str:
+        normalized = byte_order.strip().upper()
+        normalized = ASAM_BYTEORDER_ALIASES.get(normalized, normalized)
+        if normalized not in ASAM_ENDIAN_FOR_BYTEORDER:
+            raise ValueError(f"Unsupported ASAM byte order {byte_order!r}")
+        return normalized
+
+    def _permute_asam_bytes_for_read(self, data: bytes, byte_order: str) -> bytes:
+        size = len(data)
+        if size <= 1:
+            return data
+        if byte_order == "MSB_FIRST_MSW_LAST":
+            if size % 2 != 0:
+                raise ValueError("MSB_FIRST_MSW_LAST requires even-sized numeric types")
+            return b"".join(data[idx + 1 : idx + 2] + data[idx : idx + 1] for idx in range(0, size, 2))
+        if byte_order == "MSB_LAST_MSW_FIRST":
+            if size % 2 != 0:
+                raise ValueError("MSB_LAST_MSW_FIRST requires even-sized numeric types")
+            return b"".join(data[idx + 1 : idx + 2] + data[idx : idx + 1] for idx in range(0, size, 2))
+        return data
+
+    def _permute_asam_bytes_for_write(self, data: bytes, byte_order: str) -> bytes:
+        size = len(data)
+        if size <= 1:
+            return data
+        if byte_order == "MSB_FIRST_MSW_LAST":
+            if size % 2 != 0:
+                raise ValueError("MSB_FIRST_MSW_LAST requires even-sized numeric types")
+            return b"".join(data[idx + 1 : idx + 2] + data[idx : idx + 1] for idx in range(0, size, 2))
+        if byte_order == "MSB_LAST_MSW_FIRST":
+            if size % 2 != 0:
+                raise ValueError("MSB_LAST_MSW_FIRST requires even-sized numeric types")
+            return b"".join(data[idx + 1 : idx + 2] + data[idx : idx + 1] for idx in range(0, size, 2))
+        return data
+
+    def _asam_numeric_dtype_to_internal(self, asam_dtype: str, asam_byte_order: str) -> str:
+        normalized_dtype = asam_dtype.strip().upper()
+        internal_dtype = ASAM_NUMERIC_DTYPES.get(normalized_dtype)
+        if internal_dtype is None:
+            raise TypeError(f"Unsupported ASAM datatype {asam_dtype!r}")
+        if internal_dtype in ("uint8", "int8"):
+            return internal_dtype
+        return f"{internal_dtype}_{ASAM_ENDIAN_FOR_BYTEORDER[asam_byte_order]}"
+
     def read(self, addr: int, length: int, **kws) -> bytes:
         """Read raw bytes from section at specified address.
 
@@ -675,6 +754,72 @@ def read_numeric_array(self, addr: int, length: int, dtype: str, **kws) -> Union
         data = self.data[offset : offset + data_size]
         return struct.unpack(fmt, data)
 
+    def read_asam_numeric(self, addr: int, dtype: str, byte_order: str = "MSB_LAST", **kws) -> Union[int, float]:
+        asam_byte_order = self._resolve_asam_byteorder(byte_order)
+        internal_dtype = self._asam_numeric_dtype_to_internal(dtype, asam_byte_order)
+        value = self.read_numeric(addr, internal_dtype, **kws)
+        if TYPE_SIZES.get(internal_dtype.split("_")[0], 0) <= 1:
+            return value
+
+        fmt = self._getformat(internal_dtype)
+        packed = struct.pack(fmt, value)
+        permuted = self._permute_asam_bytes_for_read(packed, asam_byte_order)
+        return struct.unpack(fmt, permuted)[0]
+
+    def write_asam_numeric(
+        self,
+        addr: int,
+        value: Union[int, float],
+        dtype: str,
+        byte_order: str = "MSB_LAST",
+        **kws,
+    ) -> None:
+        asam_byte_order = self._resolve_asam_byteorder(byte_order)
+        internal_dtype = self._asam_numeric_dtype_to_internal(dtype, asam_byte_order)
+        if TYPE_SIZES.get(internal_dtype.split("_")[0], 0) <= 1:
+            self.write_numeric(addr, value, internal_dtype, **kws)
+            return
+
+        fmt = self._getformat(internal_dtype)
+        packed = struct.pack(fmt, value)
+        permuted = self._permute_asam_bytes_for_write(packed, asam_byte_order)
+        self.write(addr, permuted)
+
+    def read_asam_string(self, addr: int, dtype: str, length: int = -1, **kws) -> str:
+        encoding = ASAM_STRING_ENCODINGS.get(dtype.strip().upper())
+        if encoding is None:
+            raise TypeError(f"Unsupported ASAM string datatype {dtype!r}")
+        if length == -1 and encoding in ("utf-8", "utf-16", "utf-32"):
+            offset = addr - self.start_address
+            if offset < 0:
+                raise InvalidAddressError(f"read_asam_string(0x{addr:08x}) access out of bounds.")
+            tail = self.data[offset:]
+            terminator = "\x00".encode(encoding=encoding)
+            pos = tail.find(terminator)
+            if pos != -1:
+                return tail[:pos].decode(encoding=encoding)
+            raise TypeError("Unterminated String!!!")
+        return self.read_string(addr, encoding=encoding, length=length, **kws)
+
+    def write_asam_string(self, addr: int, value: str, dtype: str, **kws) -> None:
+        encoding = ASAM_STRING_ENCODINGS.get(dtype.strip().upper())
+        if encoding is None:
+            raise TypeError(f"Unsupported ASAM string datatype {dtype!r}")
+        if encoding == "ascii":
+            self.write_string(addr, value, encoding=encoding, **kws)
+            return
+
+        offset = addr - self.start_address
+        if offset < 0:
+            raise InvalidAddressError(f"write_asam_string(0x{addr:08x}) access out of bounds.")
+        encoded = value.encode(encoding=encoding)
+        terminator = "\x00".encode(encoding=encoding)
+        total_length = len(encoded) + len(terminator)
+        if offset + total_length > self.length:
+            raise InvalidAddressError(f"write_asam_string(0x{addr:08x}) access out of bounds.")
+        self.data[offset : offset + len(encoded)] = encoded
+        self.data[offset + len(encoded) : offset + total_length] = terminator
+
     def write_numeric_array(self, addr: int, data: Union[list[int], list[float]], dtype: str, **kws) -> None:
         if not hasattr(data, "__iter__"):
             raise TypeError("data must be iterable")

objutils/tests/test_image.py

@@ -1330,5 +1330,18 @@ def test_write_uint8_array_boundary_case3_1():
         img.write_numeric_array(0x0FFF, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], "uint8_be")
 
 
+def test_image_write_read_asam_numeric_word_swap_32bit():
+    img = Image(Section(data=bytearray(16), start_address=0x1000))
+    img.write_asam_numeric(0x1000, 0x11223344, "ULONG", byte_order="MSB_LAST_MSW_FIRST")
+    assert img.read(0x1000, 4) == b"\x33\x44\x11\x22"
+    assert img.read_asam_numeric(0x1000, "ULONG", byte_order="MSB_LAST_MSW_FIRST") == 0x11223344
+
+
+def test_image_asam_string_ascii_roundtrip():
+    img = Image(Section(data=bytearray(16), start_address=0x1000))
+    img.write_asam_string(0x1000, "ABC", "ASCII")
+    assert img.read_asam_string(0x1000, "ASCII") == "ABC"
+
+
 if __name__ == "__main__":
     unittest.main()