feat: implement bitfield support

Author: MrIndeciso

libdestruct/__init__.py

@@ -15,14 +15,17 @@
 from libdestruct.c import c_int, c_long, c_str, c_uint, c_ulong
 from libdestruct.common.array import array, array_of
 from libdestruct.common.attributes import offset
+from libdestruct.common.bitfield import bitfield_of
 from libdestruct.common.enum import enum, enum_of
 from libdestruct.common.ptr.ptr import ptr
 from libdestruct.common.struct import ptr_to, ptr_to_self, struct
 from libdestruct.libdestruct import inflate, inflater
 
 __all__ = [
+    "Resolver",
     "array",
     "array_of",
+    "bitfield_of",
     "c_int",
     "c_long",
     "c_str",
@@ -36,6 +39,5 @@
     "ptr",
     "ptr_to",
     "ptr_to_self",
-    "Resolver",
     "struct",
 ]

libdestruct/c/struct_parser.py

@@ -14,10 +14,37 @@
 
 from pycparser import c_ast, c_parser
 
+from libdestruct.c.c_integer_types import c_char, c_int, c_long, c_short, c_uchar, c_uint, c_ulong, c_ushort
 from libdestruct.common.array.array_of import array_of
+from libdestruct.common.bitfield.bitfield_of import bitfield_of
 from libdestruct.common.ptr.ptr_factory import ptr_to, ptr_to_self
 from libdestruct.common.struct import struct
 
+# Mapping from ctypes types to libdestruct native integer types (needed for bitfields)
+_CTYPES_TO_NATIVE = {
+    ctypes.c_byte: c_char,
+    ctypes.c_char: c_char,
+    ctypes.c_ubyte: c_uchar,
+    ctypes.c_short: c_short,
+    ctypes.c_ushort: c_ushort,
+    ctypes.c_int: c_int,
+    ctypes.c_uint: c_uint,
+    ctypes.c_long: c_long,
+    ctypes.c_ulong: c_ulong,
+    ctypes.c_longlong: c_long,
+    ctypes.c_ulonglong: c_ulong,
+    ctypes.c_int8: c_char,
+    ctypes.c_int16: c_short,
+    ctypes.c_int32: c_int,
+    ctypes.c_int64: c_long,
+    ctypes.c_uint8: c_uchar,
+    ctypes.c_uint16: c_ushort,
+    ctypes.c_uint32: c_uint,
+    ctypes.c_uint64: c_ulong,
+    ctypes.c_size_t: c_ulong,
+    ctypes.c_ssize_t: c_long,
+}
+
 if TYPE_CHECKING:
     from libdestruct.common.obj import obj
 
@@ -81,14 +108,25 @@ def struct_to_type(struct_node: c_ast.Struct) -> type[struct]:
     elif not struct_node.decls:
         raise ValueError("Struct must have fields.")
 
+    class_dict = {}
+
     for decl in struct_node.decls:
         name = decl.name
         typ = type_decl_to_type(decl.type, struct_node)
         fields[name] = typ
 
+        # Handle bitfields: decl.bitsize is set when the declaration has ": N"
+        if decl.bitsize is not None:
+            bit_width = int(decl.bitsize.value)
+            # Convert ctypes types to native libdestruct types for bitfield backing
+            native_type = _CTYPES_TO_NATIVE.get(typ, typ)
+            class_dict[name] = bitfield_of(native_type, bit_width)
+            fields[name] = native_type
+
     type_name = struct_node.name if struct_node.name else "anon_struct"
 
-    return type(type_name, (struct,), {"__annotations__": fields})
+    class_dict["__annotations__"] = fields
+    return type(type_name, (struct,), class_dict)
 
 
 def ptr_to_type(ptr: c_ast.PtrDecl, parent: c_ast.Struct | None = None) -> type[obj]:

libdestruct/common/bitfield/__init__.py

@@ -0,0 +1,11 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from libdestruct.common.bitfield.bitfield import bitfield
+from libdestruct.common.bitfield.bitfield_field import BitfieldField
+from libdestruct.common.bitfield.bitfield_of import bitfield_of
+
+__all__ = ["BitfieldField", "bitfield", "bitfield_of"]

libdestruct/common/bitfield/bitfield.py

@@ -0,0 +1,100 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from libdestruct.common.obj import obj
+
+if TYPE_CHECKING:  # pragma: no cover
+    from libdestruct.backing.resolver import Resolver
+
+
+class bitfield(obj):
+    """A bitfield within a backing integer type."""
+
+    _backing_instance: obj
+    """The inflated backing integer instance (shared with sibling bitfields)."""
+
+    _bit_offset: int
+    """The starting bit position within the backing integer."""
+
+    _bit_width: int
+    """The number of bits this field occupies."""
+
+    _signed: bool
+    """Whether to sign-extend when reading."""
+
+    _is_group_owner: bool
+    """Whether this bitfield owns the backing bytes (first in its group)."""
+
+    def __init__(
+        self: bitfield,
+        resolver: Resolver,
+        backing_instance: obj,
+        bit_offset: int,
+        bit_width: int,
+        signed: bool,
+        is_group_owner: bool,
+    ) -> None:
+        """Initialize the bitfield.
+
+        Args:
+            resolver: The backing resolver.
+            backing_instance: The already-inflated backing integer (shared across bitfields in the same group).
+            bit_offset: The starting bit position within the backing integer.
+            bit_width: The number of bits this field occupies.
+            signed: Whether to sign-extend when reading.
+            is_group_owner: Whether this bitfield is the first in its group (owns the backing bytes).
+        """
+        super().__init__(resolver)
+        self._backing_instance = backing_instance
+        self._bit_offset = bit_offset
+        self._bit_width = bit_width
+        self._signed = signed
+        self._mask = (1 << bit_width) - 1
+        self._is_group_owner = is_group_owner
+        # Owner reports the full backing size; non-owners report 0
+        self.size = backing_instance.size if is_group_owner else 0
+
+    def get(self: bitfield) -> int:
+        """Return the value of the bitfield."""
+        raw = self._backing_instance.get()
+        # For signed backing types, raw may be negative. Work with unsigned representation.
+        if raw < 0:
+            raw += 1 << (self._backing_instance.size * 8)
+        value = (raw >> self._bit_offset) & self._mask
+        if self._signed and (value >> (self._bit_width - 1)) & 1:
+            value -= 1 << self._bit_width
+        return value
+
+    def _set(self: bitfield, value: int) -> None:
+        """Set the value of the bitfield."""
+        masked_value = value & self._mask
+        raw = self._backing_instance.get()
+        if raw < 0:
+            raw += 1 << (self._backing_instance.size * 8)
+        raw = (raw & ~(self._mask << self._bit_offset)) | (masked_value << self._bit_offset)
+        total_bits = self._backing_instance.size * 8
+        is_signed = hasattr(self._backing_instance, "signed") and self._backing_instance.signed
+        if is_signed and raw >= (1 << (total_bits - 1)):
+            raw -= 1 << total_bits
+        self._backing_instance._set(raw)
+
+    def to_bytes(self: bitfield) -> bytes:
+        """Return the serialized representation of the backing type.
+
+        Only the group owner emits bytes; non-owners return empty bytes
+        to avoid duplication when the struct serializes all members.
+        """
+        if self._is_group_owner:
+            return self._backing_instance.to_bytes()
+        return b""
+
+    def to_str(self: bitfield, _: int = 0) -> str:
+        """Return a string representation of the bitfield."""
+        return f"{self.get()}"

libdestruct/common/bitfield/bitfield_field.py

@@ -0,0 +1,40 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from libdestruct.common.field import Field
+
+if TYPE_CHECKING:  # pragma: no cover
+    from libdestruct.backing.resolver import Resolver
+    from libdestruct.common.obj import obj
+
+
+class BitfieldField(Field):
+    """A generator for a bitfield within a struct."""
+
+    base_type: type[obj]
+
+    def __init__(self: BitfieldField, backing_type: type, bit_width: int) -> None:
+        """Initialize the bitfield field.
+
+        Args:
+            backing_type: The backing integer type (e.g., c_int, c_uint).
+            bit_width: The number of bits this field occupies.
+        """
+        self.backing_type = backing_type
+        self.bit_width = bit_width
+        self.base_type = backing_type
+
+    def inflate(self: BitfieldField, resolver: Resolver) -> obj:
+        """Inflate the field. Not used directly — struct_impl handles bitfield inflation."""
+        raise NotImplementedError("BitfieldField inflation is handled by struct_impl.")
+
+    def get_size(self: BitfieldField) -> int:
+        """Returns 0 — bitfields do not independently advance the struct offset."""
+        return 0

libdestruct/common/bitfield/bitfield_of.py

@@ -0,0 +1,30 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from libdestruct.common.bitfield.bitfield_field import BitfieldField
+
+if TYPE_CHECKING:  # pragma: no cover
+    from libdestruct.common.obj import obj
+
+
+def bitfield_of(backing_type: type[obj], bit_width: int) -> BitfieldField:
+    """Create a bitfield descriptor for use in struct annotations.
+
+    Args:
+        backing_type: The backing integer type (e.g., c_int, c_uint).
+        bit_width: The number of bits this field occupies.
+    """
+    if bit_width <= 0:
+        raise ValueError("Bit width must be positive.")
+
+    if hasattr(backing_type, "size") and bit_width > backing_type.size * 8:
+        raise ValueError(f"Bit width {bit_width} exceeds backing type size ({backing_type.size * 8} bits).")
+
+    return BitfieldField(backing_type, bit_width)

libdestruct/common/bitfield/bitfield_tracker.py

@@ -0,0 +1,118 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from libdestruct.common.bitfield.bitfield import bitfield
+
+if TYPE_CHECKING:  # pragma: no cover
+    from libdestruct.backing.resolver import Resolver
+    from libdestruct.common.bitfield.bitfield_field import BitfieldField
+    from libdestruct.common.obj import obj
+    from libdestruct.common.type_registry import TypeRegistry
+
+
+class BitfieldTracker:
+    """Tracks bitfield group state during struct field inflation.
+
+    Consecutive bitfields with the same backing type are packed into a shared
+    backing integer instance. This class manages the grouping, bit offset
+    tracking, and byte offset advancement.
+    """
+
+    def __init__(self: BitfieldTracker) -> None:
+        """Initialize the tracker with no active group."""
+        self._bit_offset: int = 0
+        self._backing_type: type | None = None
+        self._backing_instance: obj | None = None
+
+    @property
+    def active(self: BitfieldTracker) -> bool:
+        """Return whether a bitfield group is currently active."""
+        return self._backing_type is not None
+
+    def flush(self: BitfieldTracker) -> int:
+        """Close the current bitfield group and return the byte size to advance.
+
+        Returns:
+            The backing type's byte size if a group was active, 0 otherwise.
+        """
+        if self._backing_type is not None:
+            size = self._backing_type.size
+            self._backing_type = None
+            self._backing_instance = None
+            self._bit_offset = 0
+            return size
+        return 0
+
+    def create_bitfield(
+        self: BitfieldTracker,
+        field: BitfieldField,
+        inflater: TypeRegistry,
+        resolver: Resolver,
+        current_offset: int,
+    ) -> tuple[bitfield, int]:
+        """Create a bitfield instance, managing group transitions.
+
+        Args:
+            field: The BitfieldField descriptor.
+            inflater: The type registry for inflating the backing type.
+            resolver: The struct's resolver.
+            current_offset: The current byte offset in the struct.
+
+        Returns:
+            A tuple of (bitfield_instance, byte_offset_delta).
+            The delta is nonzero only when a new group starts (flushing the old one).
+        """
+        backing_type = field.backing_type
+        bit_width = field.bit_width
+        backing_size_bits = backing_type.size * 8
+        offset_delta = 0
+
+        # Start a new group if the backing type changed or bits would overflow
+        if self._backing_type is not backing_type or self._bit_offset + bit_width > backing_size_bits:
+            offset_delta = self.flush()
+            self._backing_type = backing_type
+            self._backing_instance = inflater.inflater_for(backing_type)(
+                resolver.relative_from_own(current_offset + offset_delta, 0),
+            )
+
+        is_owner = self._bit_offset == 0
+        signed = getattr(backing_type, "signed", False)
+
+        result = bitfield(
+            resolver.relative_from_own(current_offset + offset_delta, 0),
+            self._backing_instance,
+            self._bit_offset,
+            bit_width,
+            signed,
+            is_owner,
+        )
+        self._bit_offset += bit_width
+        return result, offset_delta
+
+    def compute_size(self: BitfieldTracker, field: BitfieldField) -> int:
+        """Account for a bitfield during size computation, without inflating.
+
+        Args:
+            field: The BitfieldField descriptor.
+
+        Returns:
+            The byte size delta (nonzero only when a new group starts).
+        """
+        backing_type = field.backing_type
+        bit_width = field.bit_width
+        backing_size_bits = backing_type.size * 8
+        size_delta = 0
+
+        if self._backing_type is not backing_type or self._bit_offset + bit_width > backing_size_bits:
+            size_delta = self.flush()
+            self._backing_type = backing_type
+
+        self._bit_offset += bit_width
+        return size_delta