API Reference

This page provides complete API documentation for AtPack Parser.

Core Classes

AtPackParser

The main parser class for working with AtPack files.

Main parser for AtPack files.

Source code in src/atpack_parser/parser/atpack.py

class AtPackParser:
    """Main parser for AtPack files."""

    def __init__(self, atpack_path: Union[str, Path]):
        """Initialize parser with AtPack file path."""
        self.atpack_path = Path(atpack_path)
        self.extractor = AtPackExtractor(self.atpack_path)
        self._metadata: Optional[AtPackMetadata] = None
        self._device_family: Optional[DeviceFamily] = None
        self._device_cache: Dict[str, Device] = {}

    @property
    def metadata(self) -> AtPackMetadata:
        """Get AtPack metadata."""
        if self._metadata is None:
            self._metadata = self._parse_metadata()
        return self._metadata

    @property
    def device_family(self) -> DeviceFamily:
        """Get detected device family."""
        if self._device_family is None:
            self._device_family = self._detect_device_family()
        return self._device_family

    def get_devices(self) -> List[str]:
        """Get list of all device names in the AtPack."""
        try:
            # Try to get from PDSC first
            pdsc_files = self.extractor.find_pdsc_files()
            if pdsc_files:
                pdsc_content = self.extractor.read_file(pdsc_files[0])
                pdsc_parser = PdscParser(pdsc_content)
                devices = pdsc_parser.list_devices()
                if devices:
                    return devices

            # Fallback: scan device files directly
            if self.device_family == DeviceFamily.ATMEL:
                atdf_files = self.extractor.find_atdf_files()
                devices = []
                for atdf_file in atdf_files:
                    device_name = Path(atdf_file).stem
                    devices.append(device_name)
                return sorted(devices)

            elif self.device_family == DeviceFamily.PIC:
                pic_files = self.extractor.find_pic_files()
                devices = []
                for pic_file in pic_files:
                    device_name = Path(pic_file).stem
                    devices.append(device_name)
                return sorted(devices)

            else:
                raise UnsupportedFormatError(
                    f"Unsupported device family: {self.device_family}"
                )

        except Exception as e:
            raise ParseError(f"Error getting device list: {e}")

    def get_device(self, device_name: str) -> Device:
        """Get detailed information for a specific device."""
        if device_name in self._device_cache:
            return self._device_cache[device_name]

        try:
            device = self._parse_device(device_name)
            self._device_cache[device_name] = device
            return device

        except Exception as e:
            raise DeviceNotFoundError(
                f"Device '{device_name}' not found or could not be parsed: {e}"
            )

    def get_device_registers(self, device_name: str) -> List[Any]:
        """Get registers for a specific device."""
        device = self.get_device(device_name)
        registers = []

        for module in device.modules:
            for reg_group in module.register_groups:
                registers.extend(reg_group.registers)

        return sorted(registers, key=lambda x: x.offset)

    def get_device_memory(self, device_name: str) -> List[Any]:
        """Get memory segments for a specific device."""
        device = self.get_device(device_name)
        return sorted(device.memory_segments, key=lambda x: x.start)

    def get_device_memory_hierarchical(self, device_name: str) -> List[Any]:
        """Get hierarchical memory layout for a specific device."""
        device = self.get_device(device_name)
        return device.memory_spaces

    def get_device_config(self, device_name: str) -> Dict[str, Any]:
        """Get configuration information for a specific device."""
        device = self.get_device(device_name)

        config = {
            "fuses": device.fuses,
            "config_words": device.config_words,
            "interrupts": device.interrupts,
            "signatures": device.signatures,
        }

        return config

    def list_files(self, pattern: Optional[str] = None) -> List[str]:
        """List files in the AtPack."""
        return self.extractor.list_files(pattern)

    def read_file(self, file_path: str) -> str:
        """Read a file from the AtPack."""
        return self.extractor.read_file(file_path)

    def get_device_specs(self, device_name: str) -> "DeviceSpecs":
        """Get comprehensive device specifications for a specific device."""
        from ..device_specs_extractor import extract_device_specs_from_atpack
        return extract_device_specs_from_atpack(self, device_name)

    def get_all_device_specs(self) -> List["DeviceSpecs"]:
        """Get comprehensive device specifications for all devices in the AtPack."""
        from ..device_specs_extractor import extract_all_device_specs_from_atpack
        return extract_all_device_specs_from_atpack(self)

    def _parse_metadata(self) -> AtPackMetadata:
        """Parse AtPack metadata from PDSC file."""
        pdsc_files = self.extractor.find_pdsc_files()

        if not pdsc_files:
            # Create minimal metadata
            return AtPackMetadata(
                name=self.atpack_path.stem,
                description=f"AtPack from {self.atpack_path.name}",
                vendor="Unknown",
                version="0.0.0",
            )

        try:
            pdsc_content = self.extractor.read_file(pdsc_files[0])
            pdsc_parser = PdscParser(pdsc_content)
            return pdsc_parser.parse_metadata()

        except Exception:
            # Return minimal metadata if parsing fails
            return AtPackMetadata(
                name=self.atpack_path.stem,
                description=f"AtPack from {self.atpack_path.name}",
                vendor="Unknown",
                version="0.0.0",
            )

    def _detect_device_family(self) -> DeviceFamily:
        """Detect device family from AtPack contents."""
        try:
            # Try PDSC first
            pdsc_files = self.extractor.find_pdsc_files()
            if pdsc_files:
                pdsc_content = self.extractor.read_file(pdsc_files[0])
                pdsc_parser = PdscParser(pdsc_content)
                family = pdsc_parser.detect_device_family()
                if family != DeviceFamily.UNSUPPORTED:
                    return family

            # Check file types
            atdf_files = self.extractor.find_atdf_files()
            pic_files = self.extractor.find_pic_files()

            if atdf_files and not pic_files:
                return DeviceFamily.ATMEL
            elif pic_files and not atdf_files:
                return DeviceFamily.PIC
            elif atdf_files and pic_files:
                # Both present - prefer ATMEL if more ATDF files
                if len(atdf_files) >= len(pic_files):
                    return DeviceFamily.ATMEL
                else:
                    return DeviceFamily.PIC

            return DeviceFamily.UNSUPPORTED

        except Exception:
            return DeviceFamily.UNSUPPORTED

    def _parse_device(self, device_name: str) -> Device:
        """Parse device information."""
        if self.device_family == DeviceFamily.ATMEL:
            return self._parse_atmel_device(device_name)
        elif self.device_family == DeviceFamily.PIC:
            return self._parse_pic_device(device_name)
        else:
            raise UnsupportedFormatError(
                f"Unsupported device family: {self.device_family}"
            )

    def _parse_atmel_device(self, device_name: str) -> Device:
        """Parse ATMEL device from ATDF file."""
        # Find ATDF file for device
        atdf_files = self.extractor.find_atdf_files()

        atdf_file = None
        for file_path in atdf_files:
            file_name = Path(file_path).stem
            if file_name.upper() == device_name.upper():
                atdf_file = file_path
                break

        if not atdf_file:
            raise DeviceNotFoundError(f"ATDF file for device '{device_name}' not found")

        try:
            atdf_content = self.extractor.read_file(atdf_file)
            atdf_parser = AtdfParser(atdf_content)
            return atdf_parser.parse_device(device_name)

        except Exception as e:
            raise ParseError(f"Error parsing ATDF file for '{device_name}': {e}")

    def _parse_pic_device(self, device_name: str) -> Device:
        """Parse PIC device from .pic file."""
        # Find PIC file for device
        pic_files = self.extractor.find_pic_files()

        pic_file = None
        for file_path in pic_files:
            file_name = Path(file_path).stem
            if file_name.upper() == device_name.upper():
                pic_file = file_path
                break

        if not pic_file:
            raise DeviceNotFoundError(f"PIC file for device '{device_name}' not found")

        try:
            pic_content = self.extractor.read_file(pic_file)
            pic_parser = PicParser(pic_content)
            return pic_parser.parse_device(device_name)

        except Exception as e:
            raise ParseError(f"Error parsing PIC file for '{device_name}': {e}")

    def to_dict(self) -> Dict[str, Any]:
        """Convert AtPack to dictionary representation."""
        return {
            "metadata": self.metadata.model_dump(),
            "device_family": self.device_family.value,
            "devices": self.get_devices(),
            "file_path": str(self.atpack_path),
        }

device_family property

Get detected device family.

metadata property

Get AtPack metadata.

__init__(atpack_path)

Initialize parser with AtPack file path.

Source code in src/atpack_parser/parser/atpack.py

def __init__(self, atpack_path: Union[str, Path]):
    """Initialize parser with AtPack file path."""
    self.atpack_path = Path(atpack_path)
    self.extractor = AtPackExtractor(self.atpack_path)
    self._metadata: Optional[AtPackMetadata] = None
    self._device_family: Optional[DeviceFamily] = None
    self._device_cache: Dict[str, Device] = {}

get_all_device_specs()

Get comprehensive device specifications for all devices in the AtPack.

Source code in src/atpack_parser/parser/atpack.py

def get_all_device_specs(self) -> List["DeviceSpecs"]:
    """Get comprehensive device specifications for all devices in the AtPack."""
    from ..device_specs_extractor import extract_all_device_specs_from_atpack
    return extract_all_device_specs_from_atpack(self)

get_device(device_name)

Get detailed information for a specific device.

Source code in src/atpack_parser/parser/atpack.py

def get_device(self, device_name: str) -> Device:
    """Get detailed information for a specific device."""
    if device_name in self._device_cache:
        return self._device_cache[device_name]

    try:
        device = self._parse_device(device_name)
        self._device_cache[device_name] = device
        return device

    except Exception as e:
        raise DeviceNotFoundError(
            f"Device '{device_name}' not found or could not be parsed: {e}"
        )

get_device_config(device_name)

Get configuration information for a specific device.

Source code in src/atpack_parser/parser/atpack.py

def get_device_config(self, device_name: str) -> Dict[str, Any]:
    """Get configuration information for a specific device."""
    device = self.get_device(device_name)

    config = {
        "fuses": device.fuses,
        "config_words": device.config_words,
        "interrupts": device.interrupts,
        "signatures": device.signatures,
    }

    return config

get_device_memory(device_name)

Get memory segments for a specific device.

Source code in src/atpack_parser/parser/atpack.py

def get_device_memory(self, device_name: str) -> List[Any]:
    """Get memory segments for a specific device."""
    device = self.get_device(device_name)
    return sorted(device.memory_segments, key=lambda x: x.start)

get_device_memory_hierarchical(device_name)

Get hierarchical memory layout for a specific device.

Source code in src/atpack_parser/parser/atpack.py

def get_device_memory_hierarchical(self, device_name: str) -> List[Any]:
    """Get hierarchical memory layout for a specific device."""
    device = self.get_device(device_name)
    return device.memory_spaces

get_device_registers(device_name)

Get registers for a specific device.

Source code in src/atpack_parser/parser/atpack.py

def get_device_registers(self, device_name: str) -> List[Any]:
    """Get registers for a specific device."""
    device = self.get_device(device_name)
    registers = []

    for module in device.modules:
        for reg_group in module.register_groups:
            registers.extend(reg_group.registers)

    return sorted(registers, key=lambda x: x.offset)

get_device_specs(device_name)

Get comprehensive device specifications for a specific device.

Source code in src/atpack_parser/parser/atpack.py

def get_device_specs(self, device_name: str) -> "DeviceSpecs":
    """Get comprehensive device specifications for a specific device."""
    from ..device_specs_extractor import extract_device_specs_from_atpack
    return extract_device_specs_from_atpack(self, device_name)

get_devices()

Get list of all device names in the AtPack.

Source code in src/atpack_parser/parser/atpack.py

def get_devices(self) -> List[str]:
    """Get list of all device names in the AtPack."""
    try:
        # Try to get from PDSC first
        pdsc_files = self.extractor.find_pdsc_files()
        if pdsc_files:
            pdsc_content = self.extractor.read_file(pdsc_files[0])
            pdsc_parser = PdscParser(pdsc_content)
            devices = pdsc_parser.list_devices()
            if devices:
                return devices

        # Fallback: scan device files directly
        if self.device_family == DeviceFamily.ATMEL:
            atdf_files = self.extractor.find_atdf_files()
            devices = []
            for atdf_file in atdf_files:
                device_name = Path(atdf_file).stem
                devices.append(device_name)
            return sorted(devices)

        elif self.device_family == DeviceFamily.PIC:
            pic_files = self.extractor.find_pic_files()
            devices = []
            for pic_file in pic_files:
                device_name = Path(pic_file).stem
                devices.append(device_name)
            return sorted(devices)

        else:
            raise UnsupportedFormatError(
                f"Unsupported device family: {self.device_family}"
            )

    except Exception as e:
        raise ParseError(f"Error getting device list: {e}")

list_files(pattern=None)

List files in the AtPack.

Source code in src/atpack_parser/parser/atpack.py

def list_files(self, pattern: Optional[str] = None) -> List[str]:
    """List files in the AtPack."""
    return self.extractor.list_files(pattern)

read_file(file_path)

Read a file from the AtPack.

Source code in src/atpack_parser/parser/atpack.py

def read_file(self, file_path: str) -> str:
    """Read a file from the AtPack."""
    return self.extractor.read_file(file_path)

to_dict()

Convert AtPack to dictionary representation.

Source code in src/atpack_parser/parser/atpack.py

def to_dict(self) -> Dict[str, Any]:
    """Convert AtPack to dictionary representation."""
    return {
        "metadata": self.metadata.model_dump(),
        "device_family": self.device_family.value,
        "devices": self.get_devices(),
        "file_path": str(self.atpack_path),
    }

Device Models

Data models representing device information.

Bases: BaseModel

Device information.

Source code in src/atpack_parser/models.py

class Device(BaseModel):
    """Device information."""

    name: str
    family: DeviceFamily
    architecture: Optional[str] = None
    series: Optional[str] = None

    # Memory information
    memory_segments: List[MemorySegment] = Field(default_factory=list)
    memory_spaces: List[MemorySpace] = Field(
        default_factory=list
    )  # Hierarchical memory layout

    # Modules and peripherals
    modules: List[Module] = Field(default_factory=list)

    # Configuration
    fuses: List[Fuse] = Field(default_factory=list)
    config_words: List[ConfigWord] = Field(default_factory=list)

    # Other information
    interrupts: List[Interrupt] = Field(default_factory=list)
    signatures: List[DeviceSignature] = Field(default_factory=list)
    electrical_parameters: List[ElectricalParameter] = Field(default_factory=list)

    # PIC-specific information (useful for PlatformIO board definitions)
    power_specs: Optional[PowerSpecification] = None
    oscillator_configs: List[OscillatorConfig] = Field(default_factory=list)
    programming_interface: Optional[ProgrammingInterface] = None
    pinout: List[PinInfo] = Field(default_factory=list)
    debug_capabilities: Optional[DebugCapabilities] = None
    architecture_info: Optional[ArchitectureInfo] = None
    detected_peripherals: List[str] = Field(default_factory=list)

    # ATMEL-specific information (useful for PlatformIO board definitions)
    atmel_package_variants: List[AtmelPackageVariant] = Field(default_factory=list)
    atmel_pinouts: List[AtmelPinoutInfo] = Field(default_factory=list)
    atmel_programming_interfaces: List[AtmelProgrammingInterface] = Field(
        default_factory=list
    )
    atmel_clock_info: Optional[AtmelClockInfo] = None
    atmel_gpio_info: List[AtmelGpioInfo] = Field(default_factory=list)

    # Additional metadata
    metadata: Dict[str, Any] = Field(default_factory=dict)

Bases: BaseModel

Memory segment information.

Source code in src/atpack_parser/models.py

class MemorySegment(BaseModel):
    """Memory segment information."""

    name: str
    start: int
    size: int
    type: Optional[str] = None
    page_size: Optional[int] = None
    section: Optional[str] = None
    address_space: Optional[str] = None
    parent_name: Optional[str] = (
        None  # Name of parent container (e.g., "ProgramSpace", "DataSpace")
    )
    children: List["MemorySegment"] = Field(default_factory=list)  # Child segments
    level: int = 0  # Hierarchy level (0=top level, 1=child, etc.)

Bases: BaseModel

Register information.

Source code in src/atpack_parser/models.py

class Register(BaseModel):
    """Register information."""

    name: str
    caption: Optional[str] = None
    offset: int
    size: int
    mask: Optional[int] = None
    initial_value: Optional[int] = None
    access: Optional[str] = None
    bitfields: List[RegisterBitfield] = Field(default_factory=list)

Bases: BaseModel

Register bitfield information.

Source code in src/atpack_parser/models.py

class RegisterBitfield(BaseModel):
    """Register bitfield information."""

    name: str
    caption: Optional[str] = None
    mask: int
    bit_offset: int
    bit_width: int
    values: Optional[Dict[int, str]] = None

Bases: BaseModel

Fuse configuration.

Source code in src/atpack_parser/models.py

class Fuse(BaseModel):
    """Fuse configuration."""

    name: str
    offset: int
    size: int
    mask: Optional[int] = None
    default_value: Optional[int] = None
    bitfields: List[FuseBitfield] = Field(default_factory=list)

Parser Modules

ATDF Parser

For parsing ATMEL Device Files (ATDF format).

Parser for ATMEL ATDF files.

Source code in src/atpack_parser/parser/atdf.py

class AtdfParser:
    """Parser for ATMEL ATDF files."""

    def __init__(self, xml_content: str):
        """Initialize with XML content."""
        self.parser = XmlParser(xml_content)

    def parse_device(self, device_name: Optional[str] = None) -> Device:
        """Parse device information from ATDF."""
        # Get device element
        if device_name:
            device_elements = self.parser.xpath(f'//device[@name="{device_name}"]')
        else:
            device_elements = self.parser.xpath("//device")

        if not device_elements:
            if device_name:
                raise ParseError(f"Device '{device_name}' not found in ATDF")
            else:
                raise ParseError("No device found in ATDF")

        device_element = device_elements[0]
        name = self.parser.get_attr(device_element, "name", "")
        architecture = self.parser.get_attr(device_element, "architecture", "")
        family_attr = self.parser.get_attr(device_element, "family", "")

        device = Device(
            name=name,
            family=DeviceFamily.ATMEL,
            architecture=architecture,
            series=family_attr,
        )

        # Parse memory segments
        device.memory_segments = self._parse_memory_segments(device_element)
        device.memory_spaces = self._parse_memory_spaces(device_element)

        # Parse modules/peripherals
        device.modules = self._parse_modules()

        # Parse fuses
        device.fuses = self._parse_fuses()

        # Parse interrupts
        device.interrupts = self._parse_interrupts()

        # Parse signatures
        device.signatures = self._parse_signatures()

        # Parse electrical parameters
        device.electrical_parameters = self._parse_electrical_parameters()

        # Parse additional ATMEL PlatformIO-useful information (use tree root for document-level info)
        device.atmel_package_variants = self._parse_atmel_package_variants(
            self.parser.tree
        )
        device.atmel_pinouts = self._parse_atmel_pinouts(self.parser.tree)
        device.atmel_programming_interfaces = self._parse_atmel_programming_interfaces(
            self.parser.tree
        )
        device.atmel_clock_info = self._parse_atmel_clock_info(self.parser.tree)
        device.atmel_gpio_info = self._parse_atmel_gpio_info(self.parser.tree)

        return device

    def _parse_memory_segments(
        self, device_element: etree._Element
    ) -> List[MemorySegment]:
        """Parse memory segments from device."""
        segments = []

        # Find address spaces
        address_spaces = self.parser.xpath(".//address-space", device_element)
        for addr_space in address_spaces:
            space_name = self.parser.get_attr(addr_space, "name", "")
            space_start = self.parser.get_attr_hex(addr_space, "start", 0)
            space_size = self.parser.get_attr_hex(addr_space, "size", 0)

            # Find memory segments within this address space
            memory_segments = self.parser.xpath(".//memory-segment", addr_space)
            if not memory_segments:
                # Add address space as a segment if no sub-segments
                segments.append(
                    MemorySegment(
                        name=space_name,
                        start=space_start,
                        size=space_size,
                        type=space_name,
                        address_space=space_name,
                    )
                )
            else:
                for mem_seg in memory_segments:
                    seg_name = self.parser.get_attr(mem_seg, "name", "")
                    seg_start = self.parser.get_attr_hex(mem_seg, "start", 0)
                    seg_size = self.parser.get_attr_hex(mem_seg, "size", 0)
                    seg_type = self.parser.get_attr(mem_seg, "type", "")
                    page_size = self.parser.get_attr_hex(mem_seg, "pagesize", 0)

                    segments.append(
                        MemorySegment(
                            name=seg_name,
                            start=seg_start,
                            size=seg_size,
                            type=seg_type,
                            page_size=page_size if page_size > 0 else None,
                            address_space=space_name,
                        )
                    )

        return segments

    def _parse_memory_spaces(self, device_element: etree._Element) -> List[MemorySpace]:
        """Parse hierarchical memory spaces from ATMEL device."""
        memory_spaces = []

        # Find address spaces
        address_spaces = self.parser.xpath(".//address-space", device_element)
        for addr_space in address_spaces:
            space_name = self.parser.get_attr(addr_space, "name", "")
            space_start = self.parser.get_attr_hex(addr_space, "start", 0)
            space_size = self.parser.get_attr_hex(addr_space, "size", 0)

            segments = []

            # Find memory segments within this address space
            memory_segments = self.parser.xpath(".//memory-segment", addr_space)
            if memory_segments:
                for mem_seg in memory_segments:
                    seg_name = self.parser.get_attr(mem_seg, "name", "")
                    seg_start = self.parser.get_attr_hex(mem_seg, "start", 0)
                    seg_size = self.parser.get_attr_hex(mem_seg, "size", 0)
                    seg_type = self.parser.get_attr(mem_seg, "type", "")
                    page_size = self.parser.get_attr_hex(mem_seg, "pagesize", 0)

                    segments.append(
                        MemorySegment(
                            name=seg_name,
                            start=seg_start,
                            size=seg_size,
                            type=seg_type,
                            page_size=page_size if page_size > 0 else None,
                            address_space=space_name,
                            parent_name=space_name,
                            level=1,
                        )
                    )

                # Create memory space with hierarchical segments
                memory_spaces.append(
                    MemorySpace(
                        name=space_name,
                        space_type="address-space",
                        start=space_start,
                        size=space_size,
                        segments=sorted(segments, key=lambda x: x.start),
                    )
                )
            else:
                # Create a single-segment memory space if no sub-segments
                segments.append(
                    MemorySegment(
                        name=space_name,
                        start=space_start,
                        size=space_size,
                        type=space_name,
                        address_space=space_name,
                        parent_name=None,  # Top-level
                        level=0,
                    )
                )

                memory_spaces.append(
                    MemorySpace(
                        name=space_name,
                        space_type="address-space",
                        start=space_start,
                        size=space_size,
                        segments=segments,
                    )
                )

        return memory_spaces

    def _parse_modules(self) -> List[Module]:
        """Parse modules/peripherals."""
        modules = []

        # Find all modules
        module_elements = self.parser.xpath("//modules/module")
        for module_element in module_elements:
            module_name = self.parser.get_attr(module_element, "name", "")
            module_caption = self.parser.get_attr(module_element, "caption", "")

            # Find register groups in this module
            register_groups = self._parse_register_groups_in_module(module_element)

            if register_groups:  # Only add modules with register groups
                modules.append(
                    Module(
                        name=module_name,
                        caption=module_caption,
                        register_groups=register_groups,
                    )
                )

        return modules

    def _parse_register_groups_in_module(
        self, module_element: etree._Element
    ) -> List[RegisterGroup]:
        """Parse register groups within a module."""
        groups = []

        # Find register-group definitions in the module
        rg_elements = self.parser.xpath(".//register-group", module_element)

        for rg_element in rg_elements:
            group_name = self.parser.get_attr(rg_element, "name", "")
            group_caption = self.parser.get_attr(rg_element, "caption", "")

            # Find registers in this group
            registers = self._parse_registers_in_group(rg_element, group_name)

            if registers:  # Only add groups with registers
                groups.append(
                    RegisterGroup(
                        name=group_name, caption=group_caption, registers=registers
                    )
                )

        return groups

    def _parse_registers_in_group(
        self, group_element: etree._Element, group_name: str
    ) -> List[Register]:
        """Parse registers within a register group."""
        registers = []

        # Look for registers directly in the group element
        register_elements = self.parser.xpath(".//register", group_element)

        # Also look for register-group definitions at the root level
        root_groups = self.parser.xpath(f'//register-group[@name="{group_name}"]')
        for root_group in root_groups:
            if root_group != group_element:  # Avoid duplicates
                register_elements.extend(self.parser.xpath(".//register", root_group))

        for reg_element in register_elements:
            register = self._parse_register(reg_element)
            if register:
                registers.append(register)

        return registers

    def _parse_register(self, register_element: etree._Element) -> Optional[Register]:
        """Parse a single register."""
        name = self.parser.get_attr(register_element, "name", "")
        if not name:
            return None

        caption = self.parser.get_attr(register_element, "caption", "")
        offset = self.parser.get_attr_hex(register_element, "offset", 0)
        size = self.parser.get_attr_int(register_element, "size", 1)
        mask = self.parser.get_attr_hex(register_element, "mask", 0)
        initval = self.parser.get_attr_hex(register_element, "initval", 0)
        access = self.parser.get_attr(register_element, "ocd-rw", "RW")

        # Parse bitfields
        bitfields = []
        bitfield_elements = self.parser.xpath(".//bitfield", register_element)
        for bf_element in bitfield_elements:
            bitfield = self._parse_bitfield(bf_element)
            if bitfield:
                bitfields.append(bitfield)

        return Register(
            name=name,
            caption=caption,
            offset=offset,
            size=size,
            mask=mask if mask > 0 else None,
            initial_value=initval if initval > 0 else None,
            access=access,
            bitfields=bitfields,
        )

    def _parse_bitfield(
        self, bitfield_element: etree._Element
    ) -> Optional[RegisterBitfield]:
        """Parse a register bitfield."""
        name = self.parser.get_attr(bitfield_element, "name", "")
        if not name:
            return None

        caption = self.parser.get_attr(bitfield_element, "caption", "")
        mask = self.parser.get_attr_hex(bitfield_element, "mask", 0)

        if mask == 0:
            return None

        # Calculate bit offset and width from mask
        bit_offset, bit_width = self._calculate_bit_range(mask)

        # Parse possible values
        values = None
        values_ref = self.parser.get_attr(bitfield_element, "values", "")
        if values_ref:
            values = self._parse_bitfield_values(values_ref)

        return RegisterBitfield(
            name=name,
            caption=caption,
            mask=mask,
            bit_offset=bit_offset,
            bit_width=bit_width,
            values=values,
        )

    def _parse_bitfield_values(self, values_ref: str) -> Dict[int, str]:
        """Parse bitfield possible values."""
        values = {}

        # Find value-group with this name
        value_groups = self.parser.xpath(f'//value-group[@name="{values_ref}"]')
        for vg in value_groups:
            value_elements = self.parser.xpath(".//value", vg)
            for value_element in value_elements:
                value_name = self.parser.get_attr(value_element, "name", "")
                value_caption = self.parser.get_attr(value_element, "caption", "")
                value_num = self.parser.get_attr_hex(value_element, "value", 0)

                if value_name:
                    values[value_num] = value_caption or value_name

        return values if values else None

    def _parse_fuses(self) -> List[Fuse]:
        """Parse fuse configurations."""
        fuses = []

        # Find fuse modules
        fuse_modules = self.parser.xpath('//modules/module[@name="FUSE"]')
        for fuse_module in fuse_modules:
            # Find register groups
            rg_elements = self.parser.xpath(
                './/register-group[@name="FUSE"]', fuse_module
            )
            for rg_element in rg_elements:
                # Find registers
                register_elements = self.parser.xpath(".//register", rg_element)
                for reg_element in register_elements:
                    fuse = self._parse_fuse_register(reg_element, fuse_module)
                    if fuse:
                        fuses.append(fuse)

        # Also look for fuse register-groups at root level
        root_fuse_groups = self.parser.xpath('//register-group[@name="FUSE"]')
        for rg_element in root_fuse_groups:
            register_elements = self.parser.xpath(".//register", rg_element)
            for reg_element in register_elements:
                fuse = self._parse_fuse_register(reg_element, None)
                if fuse:
                    fuses.append(fuse)

        return fuses

    def _parse_fuse_register(
        self, register_element: etree._Element, module_element: Optional[etree._Element]
    ) -> Optional[Fuse]:
        """Parse a fuse register."""
        name = self.parser.get_attr(register_element, "name", "")
        if not name:
            return None

        offset = self.parser.get_attr_hex(register_element, "offset", 0)
        size = self.parser.get_attr_int(register_element, "size", 1)
        mask = self.parser.get_attr_hex(register_element, "mask", 0)
        initval = self.parser.get_attr_hex(register_element, "initval", 0)

        # Parse bitfields
        bitfields = []
        bitfield_elements = self.parser.xpath(".//bitfield", register_element)
        for bf_element in bitfield_elements:
            bf_name = self.parser.get_attr(bf_element, "name", "")
            bf_caption = self.parser.get_attr(bf_element, "caption", "")
            bf_mask = self.parser.get_attr_hex(bf_element, "mask", 0)

            if bf_name and bf_mask > 0:
                bit_offset, bit_width = self._calculate_bit_range(bf_mask)

                # Parse values
                values = None
                values_ref = self.parser.get_attr(bf_element, "values", "")
                if values_ref and module_element is not None:
                    # Look for value-group in module
                    vg_elements = self.parser.xpath(
                        f'.//value-group[@name="{values_ref}"]', module_element
                    )
                    if vg_elements:
                        values = {}
                        for vg in vg_elements:
                            value_elements = self.parser.xpath(".//value", vg)
                            for v_element in value_elements:
                                v_name = self.parser.get_attr(v_element, "name", "")
                                v_caption = self.parser.get_attr(
                                    v_element, "caption", ""
                                )
                                v_value = self.parser.get_attr_hex(
                                    v_element, "value", 0
                                )
                                if v_name:
                                    values[v_value] = v_caption or v_name

                bitfields.append(
                    FuseBitfield(
                        name=bf_name,
                        description=bf_caption,
                        bit_offset=bit_offset,
                        bit_width=bit_width,
                        values=values,
                    )
                )

        return Fuse(
            name=name,
            offset=offset,
            size=size,
            mask=mask if mask > 0 else None,
            default_value=initval if initval > 0 else None,
            bitfields=bitfields,
        )

    def _parse_interrupts(self) -> List[Interrupt]:
        """Parse interrupt information."""
        interrupts = []

        interrupt_elements = self.parser.xpath("//interrupts/interrupt")
        for int_element in interrupt_elements:
            index = self.parser.get_attr_int(int_element, "index", 0)
            name = self.parser.get_attr(int_element, "name", "")
            caption = self.parser.get_attr(int_element, "caption", "")

            if name:
                interrupts.append(Interrupt(index=index, name=name, caption=caption))

        return sorted(interrupts, key=lambda x: x.index)

    def _parse_signatures(self) -> List[DeviceSignature]:
        """Parse device signatures."""
        signatures = []

        # Look for signature properties
        sig_elements = self.parser.xpath(
            '//property-group[@name="SIGNATURES"]/property'
        )
        for sig_element in sig_elements:
            name = self.parser.get_attr(sig_element, "name", "")
            value_str = self.parser.get_attr(sig_element, "value", "0")

            if name:
                try:
                    value = (
                        int(value_str, 16)
                        if value_str.startswith("0x")
                        else int(value_str)
                    )

                    # Extract address from name if it's SIGNATUREx
                    address = None
                    if name.startswith("SIGNATURE") and name[9:].isdigit():
                        address = int(name[9:])

                    signatures.append(
                        DeviceSignature(name=name, address=address, value=value)
                    )
                except ValueError:
                    pass

        return sorted(signatures, key=lambda x: x.address or 999)

    def _parse_electrical_parameters(self) -> List[ElectricalParameter]:
        """Parse electrical parameters."""
        parameters = []

        # Look for electrical parameter groups
        param_groups = self.parser.xpath(
            '//property-groups/property-group[contains(@name, "ELECTRICAL") or contains(@name, "ABSOLUTE") or contains(@name, "DC") or contains(@name, "AC")]'
        )

        for group in param_groups:
            group_name = self.parser.get_attr(group, "name", "")
            group_caption = self.parser.get_attr(group, "caption", "")

            # Parse properties in this group
            properties = self.parser.xpath(".//property", group)
            for prop in properties:
                name = self.parser.get_attr(prop, "name", "")
                caption = self.parser.get_attr(prop, "caption", "")
                description = self.parser.get_attr(prop, "description", "")

                # Parse min/typ/max values
                min_val = self.parser.get_attr(prop, "min", "")
                typ_val = self.parser.get_attr(prop, "typ", "")
                max_val = self.parser.get_attr(prop, "max", "")
                unit = self.parser.get_attr(prop, "unit", "")
                conditions = self.parser.get_attr(prop, "conditions", "")

                # Convert to float if possible
                min_value = (
                    float(min_val)
                    if min_val and min_val.replace(".", "").replace("-", "").isdigit()
                    else None
                )
                typ_value = (
                    float(typ_val)
                    if typ_val and typ_val.replace(".", "").replace("-", "").isdigit()
                    else None
                )
                max_value = (
                    float(max_val)
                    if max_val and max_val.replace(".", "").replace("-", "").isdigit()
                    else None
                )

                if name:
                    parameters.append(
                        ElectricalParameter(
                            name=name,
                            group=group_name,
                            caption=caption,
                            description=description,
                            min_value=min_value,
                            typical_value=typ_value,
                            max_value=max_value,
                            unit=unit,
                            conditions=conditions,
                        )
                    )

        return parameters

    def _parse_atmel_package_variants(
        self, root_element: etree._Element
    ) -> List[AtmelPackageVariant]:
        """Parse ATMEL package variant information."""
        variants = []

        # Look for variants in the ATDF structure
        variant_elements = self.parser.xpath("//variant", root_element)

        for variant in variant_elements:
            package = self.parser.get_attr(variant, "package", "")
            pinout = self.parser.get_attr(variant, "pinout", "")
            order_code = self.parser.get_attr(variant, "ordercode", "")

            # Temperature range
            temp_min_str = self.parser.get_attr(variant, "tempmin", "")
            temp_max_str = self.parser.get_attr(variant, "tempmax", "")
            temp_min = self._parse_float(temp_min_str)
            temp_max = self._parse_float(temp_max_str)

            # Speed and voltage specs
            speed_max_str = self.parser.get_attr(variant, "speedmax", "")
            speed_max = self._parse_int(speed_max_str)

            vcc_min_str = self.parser.get_attr(variant, "vccmin", "")
            vcc_max_str = self.parser.get_attr(variant, "vccmax", "")
            vcc_min = self._parse_float(vcc_min_str)
            vcc_max = self._parse_float(vcc_max_str)

            if package and pinout:
                variants.append(
                    AtmelPackageVariant(
                        package=package,
                        pinout=pinout,
                        order_code=order_code or None,
                        temp_min=temp_min,
                        temp_max=temp_max,
                        speed_max=speed_max,
                        vcc_min=vcc_min,
                        vcc_max=vcc_max,
                    )
                )

        return variants

    def _parse_atmel_pinouts(
        self, root_element: etree._Element
    ) -> List[AtmelPinoutInfo]:
        """Parse ATMEL pinout information."""
        pinouts = []

        # Look for pinout definitions
        pinout_elements = self.parser.xpath("//pinout", root_element)

        for pinout_elem in pinout_elements:
            name = self.parser.get_attr(pinout_elem, "name", "")
            caption = self.parser.get_attr(pinout_elem, "caption", "")

            # Get pins
            pin_elements = self.parser.xpath(".//pin", pinout_elem)
            pins = []

            for pin_elem in pin_elements:
                position = self.parser.get_attr(pin_elem, "position", "")
                pad = self.parser.get_attr(pin_elem, "pad", "")

                if position and pad:
                    pins.append({"position": position, "pad": pad})

            if name and pins:
                pinouts.append(
                    AtmelPinoutInfo(
                        name=name,
                        caption=caption or None,
                        pin_count=len(pins),
                        pins=pins,
                    )
                )

        return pinouts

    def _parse_atmel_programming_interfaces(
        self, root_element: etree._Element
    ) -> List[AtmelProgrammingInterface]:
        """Parse ATMEL programming interface information."""
        interfaces = []

        # Look for interface definitions
        interface_elements = self.parser.xpath("//interface", root_element)

        for interface_elem in interface_elements:
            name = self.parser.get_attr(interface_elem, "name", "")
            interface_type = self.parser.get_attr(interface_elem, "type", "")

            # Get interface properties
            properties = {}

            # Look for parameters
            param_elements = self.parser.xpath(".//param", interface_elem)
            for param_elem in param_elements:
                param_name = self.parser.get_attr(param_elem, "name", "")
                param_value = self.parser.get_attr(param_elem, "value", "")

                if param_name:
                    properties[param_name] = param_value

            if name and interface_type:
                interfaces.append(
                    AtmelProgrammingInterface(
                        name=name, interface_type=interface_type, properties=properties
                    )
                )

        return interfaces

    def _parse_atmel_clock_info(
        self, root_element: etree._Element
    ) -> Optional[AtmelClockInfo]:
        """Parse ATMEL clock system information."""
        clock_info = AtmelClockInfo()

        # Look for clock-related modules
        clock_modules = []
        module_elements = self.parser.xpath("//module", root_element)

        for module_elem in module_elements:
            module_name = self.parser.get_attr(module_elem, "name", "").upper()
            if any(
                clock_term in module_name
                for clock_term in ["CLK", "OSC", "CLOCK", "PLL"]
            ):
                module_info = {"name": self.parser.get_attr(module_elem, "name", "")}

                # Get instances
                instance_elements = self.parser.xpath(".//instance", module_elem)
                instances = []
                for inst_elem in instance_elements:
                    instances.append(dict(inst_elem.attrib))

                if instances:
                    module_info["instances"] = instances

                clock_modules.append(module_info)

        # Look for clock-related properties
        clock_properties = []
        prop_group_elements = self.parser.xpath("//property-group", root_element)

        for prop_group_elem in prop_group_elements:
            group_name = self.parser.get_attr(prop_group_elem, "name", "").lower()
            if any(
                clock_term in group_name for clock_term in ["clock", "osc", "frequency"]
            ):
                group_info = {
                    "name": self.parser.get_attr(prop_group_elem, "name", ""),
                    "properties": [],
                }

                prop_elements = self.parser.xpath(".//property", prop_group_elem)
                for prop_elem in prop_elements:
                    prop_info = dict(prop_elem.attrib)
                    if prop_elem.text:
                        prop_info["value"] = prop_elem.text.strip()
                    group_info["properties"].append(prop_info)

                clock_properties.append(group_info)

        # Look for maximum frequency in package variants
        max_frequency = None
        variant_elements = self.parser.xpath("//variant", root_element)
        for variant_elem in variant_elements:
            speed_max_str = self.parser.get_attr(variant_elem, "speedmax", "")
            speed_max = self._parse_int(speed_max_str)
            if speed_max and (max_frequency is None or speed_max > max_frequency):
                max_frequency = speed_max

        clock_info.clock_modules = clock_modules
        clock_info.clock_properties = clock_properties
        clock_info.max_frequency = max_frequency

        # Return None if no meaningful data
        if not clock_modules and not clock_properties and max_frequency is None:
            return None

        return clock_info

    def _parse_atmel_gpio_info(
        self, root_element: etree._Element
    ) -> List[AtmelGpioInfo]:
        """Parse ATMEL GPIO port information."""
        gpio_info = []

        # Look for GPIO/PORT modules
        module_elements = self.parser.xpath("//module", root_element)

        for module_elem in module_elements:
            module_name = self.parser.get_attr(module_elem, "name", "").upper()
            if module_name.startswith("PORT"):
                port_name = self.parser.get_attr(module_elem, "name", "")

                # Get instances
                instance_elements = self.parser.xpath(".//instance", module_elem)
                instances = []
                for inst_elem in instance_elements:
                    instances.append(dict(inst_elem.attrib))

                # Estimate pin count from instances (each instance typically represents one pin)
                pin_count = len(instances) if instances else None

                gpio_info.append(
                    AtmelGpioInfo(
                        port_name=port_name, instances=instances, pin_count=pin_count
                    )
                )

        return gpio_info

    def _parse_float(self, value_str: str) -> Optional[float]:
        """Parse a string to float, return None if invalid."""
        if not value_str:
            return None
        try:
            return float(value_str)
        except (ValueError, TypeError):
            return None

    def _parse_int(self, value_str: str) -> Optional[int]:
        """Parse a string to int, return None if invalid."""
        if not value_str:
            return None
        try:
            return int(value_str)
        except (ValueError, TypeError):
            return None

    def _calculate_bit_range(self, mask: int) -> tuple[int, int]:
        """Calculate bit offset and width from mask."""
        if mask == 0:
            return 0, 0

        # Find first set bit (bit offset)
        bit_offset = (mask & -mask).bit_length() - 1

        # Count consecutive bits
        temp_mask = mask >> bit_offset
        bit_width = 0
        while temp_mask & 1:
            bit_width += 1
            temp_mask >>= 1

        return bit_offset, bit_width

__init__(xml_content)

Initialize with XML content.

Source code in src/atpack_parser/parser/atdf.py

def __init__(self, xml_content: str):
    """Initialize with XML content."""
    self.parser = XmlParser(xml_content)

parse_device(device_name=None)

Parse device information from ATDF.

Source code in src/atpack_parser/parser/atdf.py

def parse_device(self, device_name: Optional[str] = None) -> Device:
    """Parse device information from ATDF."""
    # Get device element
    if device_name:
        device_elements = self.parser.xpath(f'//device[@name="{device_name}"]')
    else:
        device_elements = self.parser.xpath("//device")

    if not device_elements:
        if device_name:
            raise ParseError(f"Device '{device_name}' not found in ATDF")
        else:
            raise ParseError("No device found in ATDF")

    device_element = device_elements[0]
    name = self.parser.get_attr(device_element, "name", "")
    architecture = self.parser.get_attr(device_element, "architecture", "")
    family_attr = self.parser.get_attr(device_element, "family", "")

    device = Device(
        name=name,
        family=DeviceFamily.ATMEL,
        architecture=architecture,
        series=family_attr,
    )

    # Parse memory segments
    device.memory_segments = self._parse_memory_segments(device_element)
    device.memory_spaces = self._parse_memory_spaces(device_element)

    # Parse modules/peripherals
    device.modules = self._parse_modules()

    # Parse fuses
    device.fuses = self._parse_fuses()

    # Parse interrupts
    device.interrupts = self._parse_interrupts()

    # Parse signatures
    device.signatures = self._parse_signatures()

    # Parse electrical parameters
    device.electrical_parameters = self._parse_electrical_parameters()

    # Parse additional ATMEL PlatformIO-useful information (use tree root for document-level info)
    device.atmel_package_variants = self._parse_atmel_package_variants(
        self.parser.tree
    )
    device.atmel_pinouts = self._parse_atmel_pinouts(self.parser.tree)
    device.atmel_programming_interfaces = self._parse_atmel_programming_interfaces(
        self.parser.tree
    )
    device.atmel_clock_info = self._parse_atmel_clock_info(self.parser.tree)
    device.atmel_gpio_info = self._parse_atmel_gpio_info(self.parser.tree)

    return device

PIC Parser

For parsing Microchip PIC device files.

Parser for Microchip PIC files.

Source code in src/atpack_parser/parser/pic.py

class PicParser:
    """Parser for Microchip PIC files."""

    def __init__(self, xml_content: str):
        """Initialize with XML content."""
        self.parser = XmlParser(xml_content)

    def parse_device(self, device_name: Optional[str] = None) -> Device:
        """Parse device information from PIC file."""
        # Get device element - try with and without namespace
        if device_name:
            device_elements = self.parser.xpath(f'//edc:PIC[@edc:name="{device_name}"]')
            if not device_elements:
                device_elements = self.parser.xpath(
                    f'//*[local-name()="PIC" and @*[local-name()="name"]="{device_name}"]'
                )
        else:
            device_elements = self.parser.xpath("//edc:PIC")
            if not device_elements:
                device_elements = self.parser.xpath('//*[local-name()="PIC"]')

        if not device_elements:
            if device_name:
                raise ParseError(f"Device '{device_name}' not found in PIC file")
            else:
                raise ParseError("No device found in PIC file")

        device_element = device_elements[0]

        # Extract device name - try namespace and local name approaches
        name = (
            self.parser.get_attr(device_element, "name")
            or self.parser.get_attr(device_element, "{http://crownking/edc}name")
            or device_element.get("{http://crownking/edc}name")
            or ""
        )

        if not name and device_name:
            name = device_name

        # Extract series from architecture attribute
        arch = self.parser.get_attr(device_element, "arch", "")
        series = None
        if arch:
            # Convert arch like "16xxxx" to "PIC16"
            if arch.startswith("16"):
                series = "PIC16"
            elif arch.startswith("18"):
                series = "PIC18"
            elif arch.startswith("12"):
                series = "PIC12"
            elif arch.startswith("10"):
                series = "PIC10"
            else:
                series = f"PIC{arch}"

        device = Device(
            name=name, family=DeviceFamily.PIC, architecture="PIC", series=series
        )

        # Parse memory segments
        device.memory_segments = self._parse_memory_segments(device_element)
        device.memory_spaces = self._parse_memory_spaces(device_element)

        # Parse modules/peripherals
        device.modules = self._parse_modules(device_element)

        # Parse configuration words
        device.config_words = self._parse_config_words(device_element)

        # Parse interrupts
        device.interrupts = self._parse_interrupts(device_element)

        # Parse signatures/device IDs
        device.signatures = self._parse_signatures(device_element)

        # Additional metadata
        device.metadata = self._extract_metadata(device_element)

        # Parse additional PlatformIO-useful information
        device.power_specs = self._parse_power_specifications(device_element)
        device.oscillator_configs = self._parse_oscillator_configurations(
            device_element
        )
        device.programming_interface = self._parse_programming_interface(device_element)
        device.pinout = self._parse_pinout_info(device_element)
        device.debug_capabilities = self._parse_debug_capabilities(device_element)
        device.architecture_info = self._parse_architecture_info(device_element)
        device.detected_peripherals = self._detect_peripherals(device_element)

        return device

    def _parse_memory_segments(
        self, device_element: etree._Element
    ) -> List[MemorySegment]:
        """Parse memory segments from PIC device."""
        segments = []

        # Parse ProgramSpace - contains CodeSector elements for program memory
        program_space = self.parser.xpath(
            './/edc:ProgramSpace | .//*[local-name()="ProgramSpace"]', device_element
        )
        for ps in program_space:
            # Parse CodeSector elements
            code_sectors = self.parser.xpath(
                './/edc:CodeSector | .//*[local-name()="CodeSector"]', ps
            )
            for cs in code_sectors:
                start = self.parser.get_attr_hex(cs, "beginaddr", 0)
                end = self.parser.get_attr_hex(cs, "endaddr", 0)
                name = self.parser.get_attr(cs, "sectionname", "PROG")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=name,
                            start=start,
                            size=size,
                            type="program",
                            address_space="program",
                        )
                    )

        # Parse DataSpace - contains SFRDataSector and other data memory
        data_space = self.parser.xpath(
            './/edc:DataSpace | .//*[local-name()="DataSpace"]', device_element
        )
        for ds in data_space:
            # Parse SFRDataSector elements
            sfr_sectors = self.parser.xpath(
                './/edc:SFRDataSector | .//*[local-name()="SFRDataSector"]', ds
            )
            for sfr in sfr_sectors:
                start = self.parser.get_attr_hex(sfr, "beginaddr", 0)
                end = self.parser.get_attr_hex(sfr, "endaddr", 0)
                bank = self.parser.get_attr(sfr, "bank", "0")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=f"SFR_BANK{bank}",
                            start=start,
                            size=size,
                            type="sfr",
                            address_space="data",
                        )
                    )

            # Parse GPRDataSector elements (General Purpose Registers)
            gpr_sectors = self.parser.xpath(
                './/edc:GPRDataSector | .//*[local-name()="GPRDataSector"]', ds
            )
            for gpr in gpr_sectors:
                # Skip shadow sectors (they are mirrors of other memory regions)
                # Check for shadowidref attribute with both namespace and local name approaches
                shadow_ref = (
                    self.parser.get_attr(gpr, "shadowidref")
                    or self.parser.get_attr(gpr, "{http://crownking/edc}shadowidref")
                    or gpr.get("{http://crownking/edc}shadowidref")
                )
                if shadow_ref is not None:
                    continue

                start = self.parser.get_attr_hex(gpr, "beginaddr", 0)
                end = self.parser.get_attr_hex(gpr, "endaddr", 0)
                bank = self.parser.get_attr(gpr, "bank", "0")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=f"GPR_BANK{bank}",
                            start=start,
                            size=size,
                            type="gpr",
                            address_space="data",
                        )
                    )

            # Parse general DataSector elements
            data_sectors = self.parser.xpath(
                './/edc:DataSector | .//*[local-name()="DataSector"]', ds
            )
            for ds_elem in data_sectors:
                start = self.parser.get_attr_hex(ds_elem, "beginaddr", 0)
                end = self.parser.get_attr_hex(ds_elem, "endaddr", 0)
                name = self.parser.get_attr(ds_elem, "sectionname", "DATA")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=name,
                            start=start,
                            size=size,
                            type="data",
                            address_space="data",
                        )
                    )

        # Parse EEDataSpace for EEPROM
        ee_space = self.parser.xpath(
            './/edc:EEDataSpace | .//*[local-name()="EEDataSpace"]', device_element
        )
        for es in ee_space:
            ee_sectors = self.parser.xpath(
                './/edc:EESector | .//*[local-name()="EESector"]', es
            )
            for ee in ee_sectors:
                start = self.parser.get_attr_hex(ee, "beginaddr", 0)
                end = self.parser.get_attr_hex(ee, "endaddr", 0)

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name="EEPROM",
                            start=start,
                            size=size,
                            type="eeprom",
                            address_space="eeprom",
                        )
                    )

        return segments

    def _parse_modules(self, device_element: etree._Element) -> List[Module]:
        """Parse modules from PIC device SFR definitions."""
        modules = []

        # Find all SFRDataSector elements which contain the register definitions
        sfr_data_sectors = self.parser.xpath(
            './/edc:SFRDataSector | .//*[local-name()="SFRDataSector"]', device_element
        )

        for sfr_sector in sfr_data_sectors:
            bank = self.parser.get_attr(sfr_sector, "bank", "0")

            # Get all SFRDef elements in this sector
            sfr_defs = self.parser.xpath(
                './/edc:SFRDef | .//*[local-name()="SFRDef"]', sfr_sector
            )

            if sfr_defs:
                # Parse all registers in this bank
                all_registers = []
                for sfr_def in sfr_defs:
                    registers = self._parse_sfr_registers(sfr_def)
                    all_registers.extend(registers)

                if all_registers:
                    # Group registers by module - use bank as the module name for now
                    module_name = f"BANK{bank}"
                    register_group = RegisterGroup(
                        name=f"SFR_BANK{bank}",
                        caption=f"SFR Bank {bank}",
                        registers=all_registers,
                    )

                    module = Module(
                        name=module_name,
                        caption=f"Register Bank {bank}",
                        register_groups=[register_group],
                    )

                    modules.append(module)

        # Also look for NMMR (Non-Memory Mapped Registers)
        nmmr_places = self.parser.xpath(
            './/edc:NMMRPlace | .//*[local-name()="NMMRPlace"]', device_element
        )
        for nmmr_place in nmmr_places:
            sfr_defs = self.parser.xpath(
                './/edc:SFRDef | .//*[local-name()="SFRDef"]', nmmr_place
            )

            if sfr_defs:
                all_registers = []
                for sfr_def in sfr_defs:
                    registers = self._parse_sfr_registers(sfr_def)
                    all_registers.extend(registers)

                if all_registers:
                    register_group = RegisterGroup(
                        name="CORE", caption="Core Registers", registers=all_registers
                    )

                    module = Module(
                        name="CORE",
                        caption="Core Registers",
                        register_groups=[register_group],
                    )

                    modules.append(module)

        return modules

    def _parse_sfr_registers(self, sfr_def: etree._Element) -> List[Register]:
        """Parse a single register from an SFRDef element."""
        registers = []

        # Get basic register information
        reg_name = self.parser.get_attr(sfr_def, "name", "UNKNOWN")
        reg_addr = self.parser.get_attr_hex(sfr_def, "_addr", 0)
        access_pattern = self.parser.get_attr(sfr_def, "access", "nnnnnnnn")
        width = self.parser.get_attr_hex(sfr_def, "nzwidth", 0x8)
        description = self.parser.get_attr(sfr_def, "desc", "")

        # Parse bitfields from SFRFieldDef elements in SFRMode sections
        bitfields = []
        sfr_modes = self.parser.xpath(
            './/edc:SFRMode | .//*[local-name()="SFRMode"]', sfr_def
        )

        # Process DS.0 mode first (main definitions with proper masks)
        main_bitfields = {}
        for mode in sfr_modes:
            mode_id = self.parser.get_attr(mode, "id", "")
            if mode_id == "DS.0":
                field_defs = self.parser.xpath(
                    './/edc:SFRFieldDef | .//*[local-name()="SFRFieldDef"]', mode
                )

                current_bit_pos = 0  # Track sequential bit position for DS.0 mode

                for field_def in field_defs:
                    field_name = self.parser.get_attr(field_def, "name", "")
                    field_mask = self.parser.get_attr_hex(field_def, "mask", 0)
                    field_width = self.parser.get_attr_hex(field_def, "nzwidth", 1)
                    field_desc = self.parser.get_attr(field_def, "desc", "")

                    if field_name and field_mask > 0:
                        # For DS.0 mode, calculate bit position from mask
                        # But for single-bit masks (0x1), use sequential positioning
                        if field_mask == 0x1:
                            # Single bit field - use current position and calculate proper mask
                            bit_pos = current_bit_pos
                            actual_mask = 1 << bit_pos
                        else:
                            # Multi-bit field - use the provided mask
                            bit_pos = 0
                            temp_mask = field_mask
                            while temp_mask and (temp_mask & 1) == 0:
                                bit_pos += 1
                                temp_mask >>= 1
                            actual_mask = field_mask

                        bitfield = RegisterBitfield(
                            name=field_name,
                            caption=field_desc or field_name,
                            mask=actual_mask,
                            bit_offset=bit_pos,
                            bit_width=field_width,
                        )
                        bitfields.append(bitfield)
                        main_bitfields[field_name] = bitfield

                        current_bit_pos += field_width

        # Process other modes (like LT.0) for individual bit aliases
        for mode in sfr_modes:
            mode_id = self.parser.get_attr(mode, "id", "")
            if mode_id != "DS.0":  # Skip the main mode we already processed
                field_defs = self.parser.xpath(
                    './/edc:SFRFieldDef | .//*[local-name()="SFRFieldDef"]', mode
                )
                adjust_points = self.parser.xpath(
                    './/edc:AdjustPoint | .//*[local-name()="AdjustPoint"]', mode
                )

                current_bit_pos = 0  # Track current bit position for this mode

                # Build a list of all elements (fields and adjust points) in document order
                mode_elements = []
                for child in mode:
                    if child.tag.endswith("SFRFieldDef") or "SFRFieldDef" in child.tag:
                        mode_elements.append(("field", child))
                    elif (
                        child.tag.endswith("AdjustPoint") or "AdjustPoint" in child.tag
                    ):
                        mode_elements.append(("adjust", child))

                for elem_type, elem in mode_elements:
                    if elem_type == "adjust":
                        # Handle AdjustPoint to skip bits
                        offset = self.parser.get_attr_hex(elem, "offset", 1)
                        current_bit_pos += offset
                    elif elem_type == "field":
                        field_name = self.parser.get_attr(elem, "name", "")
                        field_mask = self.parser.get_attr_hex(elem, "mask", 0)
                        field_width = self.parser.get_attr_hex(elem, "nzwidth", 1)
                        field_desc = self.parser.get_attr(elem, "desc", "")

                        if field_name and field_mask > 0:
                            # For individual bit aliases, use sequential positioning
                            # but only if we don't already have this field from DS.0 mode
                            if field_name not in main_bitfields:
                                # Create proper mask based on current bit position
                                actual_mask = (
                                    field_mask << current_bit_pos
                                    if field_mask == 1
                                    else field_mask
                                )

                                bitfield = RegisterBitfield(
                                    name=field_name,
                                    caption=field_desc or field_name,
                                    mask=actual_mask,
                                    bit_offset=current_bit_pos,
                                    bit_width=field_width,
                                )
                                bitfields.append(bitfield)

                            current_bit_pos += field_width

        # Create the register
        if reg_addr > 0 or reg_name in [
            "WREG",
            "INDF",
        ]:  # Include special registers at address 0
            # Determine access mode from access pattern
            access_mode = "RW"  # Default
            if "r" in access_pattern.lower() and "w" not in access_pattern.lower():
                access_mode = "R"
            elif "w" in access_pattern.lower() and "r" not in access_pattern.lower():
                access_mode = "W"
            elif "-" in access_pattern:
                access_mode = "R"  # Read-only for unmapped bits

            register = Register(
                name=reg_name,
                caption=description or reg_name,
                offset=reg_addr,
                size=width // 8 if width >= 8 else 1,
                access=access_mode,
                bitfields=bitfields,
            )
            registers.append(register)

        return registers

    def _parse_config_words(self, device_element: etree._Element) -> List[ConfigWord]:
        """Parse configuration words from PIC device."""
        config_words = []

        # Look for configuration word definitions
        config_defs = self.parser.xpath(
            './/edc:ConfigDef | .//*[local-name()="ConfigDef"]', device_element
        )

        for config_def in config_defs:
            # Parse individual configuration words
            config_elements = self.parser.xpath(
                './/edc:ConfigWord | .//*[local-name()="ConfigWord"]', config_def
            )

            for config_elem in config_elements:
                addr = self.parser.get_attr_hex(config_elem, "addr", 0)
                default_val = self.parser.get_attr_hex(config_elem, "default", 0)
                mask = self.parser.get_attr_hex(config_elem, "mask", 0xFFFF)
                name = self.parser.get_attr(config_elem, "name", f"CONFIG{addr:04X}")

                # Parse configuration fields
                bitfields = []
                config_fields = self.parser.xpath(
                    './/edc:ConfigField | .//*[local-name()="ConfigField"]', config_elem
                )

                for field in config_fields:
                    field_name = self.parser.get_attr(field, "name", "")
                    field_mask = self.parser.get_attr_hex(field, "mask", 0)
                    field_desc = self.parser.get_attr(field, "desc", "")

                    if field_name and field_mask:
                        bit_offset, bit_width = self._calculate_bit_range(field_mask)

                        # Parse field values
                        values = {}
                        field_values = self.parser.xpath(
                            './/edc:ConfigValue | .//*[local-name()="ConfigValue"]',
                            field,
                        )
                        for value_elem in field_values:
                            val_name = self.parser.get_attr(value_elem, "name", "")
                            val_value = self.parser.get_attr_hex(value_elem, "value", 0)
                            val_desc = self.parser.get_attr(value_elem, "desc", "")

                            if val_name:
                                values[val_value] = val_desc or val_name

                        bitfield = RegisterBitfield(
                            name=field_name,
                            caption=field_desc or field_name,
                            mask=field_mask,
                            bit_offset=bit_offset,
                            bit_width=bit_width,
                            values=values if values else None,
                        )
                        bitfields.append(bitfield)

                if addr > 0:
                    config_words.append(
                        ConfigWord(
                            name=name,
                            address=addr,
                            default_value=default_val,
                            mask=mask,
                            bitfields=bitfields,
                        )
                    )

        return sorted(config_words, key=lambda x: x.address)

    def _parse_interrupts(self, device_element: etree._Element) -> List[Interrupt]:
        """Parse interrupt information from PIC device."""
        interrupts = []

        # Look for explicit interrupt definitions first
        int_defs = self.parser.xpath(
            './/edc:InterruptDef | .//*[local-name()="InterruptDef"]', device_element
        )

        for int_def in int_defs:
            int_elements = self.parser.xpath(
                './/edc:Interrupt | .//*[local-name()="Interrupt"]', int_def
            )

            for int_elem in int_elements:
                name = self.parser.get_attr(int_elem, "name", "")
                vector = self.parser.get_attr_int(int_elem, "vector", 0)
                desc = self.parser.get_attr(int_elem, "desc", "")

                if name:
                    interrupts.append(
                        Interrupt(index=vector, name=name, caption=desc or name)
                    )

        # If no explicit interrupts found, try to infer from common PIC interrupt registers
        if not interrupts:
            # Look for PIE (Peripheral Interrupt Enable) registers to infer interrupts
            sfr_data_sectors = self.parser.xpath(
                './/edc:SFRDataSector | .//*[local-name()="SFRDataSector"]',
                device_element,
            )

            interrupt_sources = set()

            for sfr_sector in sfr_data_sectors:
                sfr_defs = self.parser.xpath(
                    './/edc:SFRDef | .//*[local-name()="SFRDef"]', sfr_sector
                )

                for sfr_def in sfr_defs:
                    reg_name = self.parser.get_attr(sfr_def, "name", "")

                    # Check for interrupt-related registers
                    if reg_name in ["PIE1", "PIE2", "PIE3", "PIE4", "INTCON"]:
                        # Parse the bitfields to find interrupt enable bits
                        sfr_modes = self.parser.xpath(
                            './/edc:SFRMode | .//*[local-name()="SFRMode"]', sfr_def
                        )

                        for mode in sfr_modes:
                            field_defs = self.parser.xpath(
                                './/edc:SFRFieldDef | .//*[local-name()="SFRFieldDef"]',
                                mode,
                            )

                            for field_def in field_defs:
                                field_name = self.parser.get_attr(field_def, "name", "")

                                # Common PIC interrupt enable bit patterns
                                if (
                                    field_name.endswith("IE")
                                    or field_name.endswith("EN")
                                    or field_name
                                    in ["GIE", "PEIE", "T0IE", "INTE", "RBIE"]
                                ):
                                    # Map enable bit to interrupt name
                                    int_name = field_name.replace("IE", "").replace(
                                        "EN", ""
                                    )
                                    if int_name == "GI":
                                        int_name = "GLOBAL"
                                    elif int_name == "PEI":
                                        int_name = "PERIPHERAL"
                                    elif int_name == "T0I":
                                        int_name = "TIMER0"
                                    elif int_name == "INT":
                                        int_name = "EXTERNAL"
                                    elif int_name == "RBI":
                                        int_name = "PORTB_CHANGE"

                                    if int_name:
                                        interrupt_sources.add(int_name)

            # Create interrupt objects from the discovered sources
            for i, int_name in enumerate(sorted(interrupt_sources)):
                interrupts.append(
                    Interrupt(
                        index=i, name=f"{int_name}_INT", caption=f"{int_name} Interrupt"
                    )
                )

        return sorted(interrupts, key=lambda x: x.index)

    def _parse_signatures(
        self, device_element: etree._Element
    ) -> List[DeviceSignature]:
        """Parse device signatures from PIC device."""
        signatures = []

        # Look for DeviceIDSector elements
        device_id_sectors = self.parser.xpath(
            './/edc:DeviceIDSector | .//*[local-name()="DeviceIDSector"]',
            device_element,
        )

        for device_id_sector in device_id_sectors:
            addr = self.parser.get_attr_hex(device_id_sector, "beginaddr", 0)
            value = self.parser.get_attr_hex(device_id_sector, "value", 0)
            mask = self.parser.get_attr_hex(device_id_sector, "mask", 0xFFFF)
            region_id = self.parser.get_attr(device_id_sector, "regionid", "devid")

            if value > 0:
                signatures.append(
                    DeviceSignature(
                        address=addr,
                        value=value,
                        mask=mask,
                        name=f"DEVID_{region_id.upper()}",
                    )
                )

        return signatures

    def _extract_metadata(self, device_element: etree._Element) -> Dict[str, any]:
        """Extract additional device metadata."""
        metadata = {}

        # Device specifications
        specs = self.parser.xpath(
            './/edc:DeviceSpecs | .//*[local-name()="DeviceSpecs"]', device_element
        )
        for spec in specs:
            # Stack depth
            stack_depth = self.parser.get_attr_int(spec, "stackdepth", 0)
            if stack_depth > 0:
                metadata["stack_depth"] = stack_depth

            # CPU architecture details
            cpu_arch = self.parser.get_attr(spec, "arch", "")
            if cpu_arch:
                metadata["cpu_architecture"] = cpu_arch

        # Power specifications
        power_specs = self.parser.xpath(
            './/edc:PowerSpecs | .//*[local-name()="PowerSpecs"]', device_element
        )
        for power_spec in power_specs:
            supply_voltage = self.parser.get_attr(power_spec, "supply", "")
            if supply_voltage:
                metadata["supply_voltage"] = supply_voltage

        return metadata

    def _parse_power_specifications(
        self, device_element: etree._Element
    ) -> Optional[PowerSpecification]:
        """Parse power supply specifications from PIC device."""
        # Look for Power element
        power_elem = device_element.find(
            ".//edc:Power", {"edc": "http://crownking/edc"}
        )
        if power_elem is None:
            power_elem = device_element.find('.//*[local-name()="Power"]')

        if power_elem is None:
            return None

        power_spec = PowerSpecification()

        # High voltage MCLR capability
        has_hv_mclr = self.parser.get_attr(power_elem, "hashighvoltagemclr2", "")
        if has_hv_mclr:
            power_spec.has_high_voltage_mclr = has_hv_mclr.lower() == "true"

        # VDD specifications
        vdd_elem = power_elem.find(".//edc:VDD", {"edc": "http://crownking/edc"})
        if vdd_elem is None:
            vdd_elem = power_elem.find('.//*[local-name()="VDD"]')

        if vdd_elem is not None:
            power_spec.vdd_min = self._parse_float(
                self.parser.get_attr(vdd_elem, "minvoltage", "")
            )
            power_spec.vdd_max = self._parse_float(
                self.parser.get_attr(vdd_elem, "maxvoltage", "")
            )
            power_spec.vdd_nominal = self._parse_float(
                self.parser.get_attr(vdd_elem, "nominalvoltage", "")
            )
            power_spec.vdd_min_default = self._parse_float(
                self.parser.get_attr(vdd_elem, "mindefaultvoltage", "")
            )
            power_spec.vdd_max_default = self._parse_float(
                self.parser.get_attr(vdd_elem, "maxdefaultvoltage", "")
            )

        # VPP specifications (programming voltage)
        vpp_elem = power_elem.find(".//edc:VPP", {"edc": "http://crownking/edc"})
        if vpp_elem is None:
            vpp_elem = power_elem.find('.//*[local-name()="VPP"]')

        if vpp_elem is not None:
            power_spec.vpp_min = self._parse_float(
                self.parser.get_attr(vpp_elem, "minvoltage", "")
            )
            power_spec.vpp_max = self._parse_float(
                self.parser.get_attr(vpp_elem, "maxvoltage", "")
            )
            power_spec.vpp_default = self._parse_float(
                self.parser.get_attr(vpp_elem, "defaultvoltage", "")
            )

        # Return None if no meaningful data was found
        if not any(
            [
                power_spec.vdd_min,
                power_spec.vdd_max,
                power_spec.vdd_nominal,
                power_spec.vpp_min,
                power_spec.vpp_max,
                power_spec.vpp_default,
            ]
        ):
            return None

        return power_spec

    def _parse_oscillator_configurations(
        self, device_element: etree._Element
    ) -> List[OscillatorConfig]:
        """Parse oscillator configuration options from config words."""
        osc_configs = []

        # Look for configuration words with oscillator settings
        config_sectors = device_element.findall(
            ".//edc:ConfigFuseSector", {"edc": "http://crownking/edc"}
        )
        if not config_sectors:
            config_sectors = device_element.findall(
                './/*[local-name()="ConfigFuseSector"]'
            )

        for sector in config_sectors:
            dcr_defs = sector.findall(".//edc:DCRDef", {"edc": "http://crownking/edc"})
            if not dcr_defs:
                dcr_defs = sector.findall('.//*[local-name()="DCRDef"]')

            for dcr in dcr_defs:
                modes = dcr.findall(".//edc:DCRMode", {"edc": "http://crownking/edc"})
                if not modes:
                    modes = dcr.findall('.//*[local-name()="DCRMode"]')

                for mode in modes:
                    fields = mode.findall(
                        ".//edc:DCRFieldDef", {"edc": "http://crownking/edc"}
                    )
                    if not fields:
                        fields = mode.findall('.//*[local-name()="DCRFieldDef"]')

                    for field in fields:
                        field_name = self.parser.get_attr(field, "name", "")

                        # Check if this is an oscillator-related field
                        if "FOSC" in field_name or "OSC" in field_name.upper():
                            field_desc = self.parser.get_attr(field, "desc", "")
                            field_mask = self.parser.get_attr(field, "mask", "")

                            # Get semantic options for this field
                            semantics = field.findall(
                                ".//edc:DCRFieldSemantic",
                                {"edc": "http://crownking/edc"},
                            )
                            if not semantics:
                                semantics = field.findall(
                                    './/*[local-name()="DCRFieldSemantic"]'
                                )

                            for semantic in semantics:
                                osc_name = self.parser.get_attr(semantic, "cname", "")
                                osc_desc = self.parser.get_attr(semantic, "desc", "")
                                when_cond = self.parser.get_attr(semantic, "when", "")

                                if osc_name:
                                    # Look for legacy aliases
                                    legacy_alias = None
                                    try:
                                        aliases = semantic.findall(
                                            ".//edc:LegacyAlias",
                                            {"edc": "http://crownking/edc"},
                                        )
                                        if not aliases:
                                            # Use safer XPath without predicates
                                            aliases = []
                                            for elem in semantic.iter():
                                                if (
                                                    elem.tag.endswith("LegacyAlias")
                                                    or "LegacyAlias" in elem.tag
                                                ):
                                                    aliases.append(elem)

                                        if aliases:
                                            legacy_alias = self.parser.get_attr(
                                                aliases[0], "cname", ""
                                            )
                                    except (SyntaxError, Exception):
                                        # Skip legacy alias parsing if XPath fails
                                        legacy_alias = None

                                    osc_config = OscillatorConfig(
                                        name=osc_name,
                                        description=osc_desc or osc_name,
                                        config_mask=field_mask,
                                        when_condition=when_cond,
                                        c_name=osc_name,
                                        legacy_alias=legacy_alias,
                                    )
                                    osc_configs.append(osc_config)

        return osc_configs

    def _parse_programming_interface(
        self, device_element: etree._Element
    ) -> Optional[ProgrammingInterface]:
        """Parse programming interface specifications."""
        # Look for Programming element
        prog_elem = device_element.find(
            ".//edc:Programming", {"edc": "http://crownking/edc"}
        )
        if prog_elem is None:
            prog_elem = device_element.find('.//*[local-name()="Programming"]')

        if prog_elem is None:
            return None

        prog_interface = ProgrammingInterface()

        # Basic programming attributes
        prog_interface.erase_algorithm = self.parser.get_attr(
            prog_elem, "erasealgo", ""
        )
        prog_interface.memory_technology = self.parser.get_attr(
            prog_elem, "memtech", ""
        )

        has_lvp = self.parser.get_attr(prog_elem, "haslvp2", "")
        if has_lvp:
            prog_interface.has_low_voltage_programming = has_lvp.lower() == "true"

        lvp_thresh = self._parse_float(self.parser.get_attr(prog_elem, "lvpthresh", ""))
        if lvp_thresh:
            prog_interface.low_voltage_threshold = lvp_thresh

        tries = self._parse_int(self.parser.get_attr(prog_elem, "tries", ""))
        if tries:
            prog_interface.programming_tries = tries

        has_row_erase = self.parser.get_attr(prog_elem, "hasrowerasecmd", "")
        if has_row_erase:
            prog_interface.has_row_erase_command = has_row_erase.lower() == "true"

        # Parse programming wait times
        wait_times = prog_elem.findall(
            ".//edc:ProgrammingWaitTime", {"edc": "http://crownking/edc"}
        )
        if not wait_times:
            wait_times = prog_elem.findall('.//*[local-name()="ProgrammingWaitTime"]')

        for wait_elem in wait_times:
            prog_op = self.parser.get_attr(wait_elem, "progop", "")
            time_val = self._parse_int(self.parser.get_attr(wait_elem, "time", ""))
            time_units = self.parser.get_attr(wait_elem, "timeunits", "")

            if prog_op and time_val:
                prog_interface.wait_times[prog_op] = {
                    "time": time_val,
                    "units": time_units or "us",
                }

        # Parse programming row sizes
        row_sizes = prog_elem.findall(
            ".//edc:ProgrammingRowSize", {"edc": "http://crownking/edc"}
        )
        if not row_sizes:
            row_sizes = prog_elem.findall('.//*[local-name()="ProgrammingRowSize"]')

        for row_elem in row_sizes:
            prog_op = self.parser.get_attr(row_elem, "progop", "")
            nz_size = self._parse_int(self.parser.get_attr(row_elem, "nzsize", ""))

            if prog_op and nz_size:
                prog_interface.row_sizes[prog_op] = nz_size

        return prog_interface

    def _parse_pinout_info(self, device_element: etree._Element) -> List[PinInfo]:
        """Parse pinout and pin functionality information."""
        pins = []

        # Look for PinList element
        pin_list = device_element.find(
            ".//edc:PinList", {"edc": "http://crownking/edc"}
        )
        if pin_list is None:
            pin_list = device_element.find('.//*[local-name()="PinList"]')

        if pin_list is None:
            return pins

        # Get PPS (Peripheral Pin Select) flavor
        pps_flavor = self.parser.get_attr(pin_list, "ppsflavor", "")

        pin_elements = pin_list.findall(".//edc:Pin", {"edc": "http://crownking/edc"})
        if not pin_elements:
            pin_elements = pin_list.findall('.//*[local-name()="Pin"]')

        for pin_num, pin_elem in enumerate(pin_elements, 1):
            pin_info = PinInfo(physical_pin=pin_num)

            # Get virtual pins (pin functions)
            virtual_pins = pin_elem.findall(
                ".//edc:VirtualPin", {"edc": "http://crownking/edc"}
            )
            if not virtual_pins:
                virtual_pins = pin_elem.findall('.//*[local-name()="VirtualPin"]')

            functions = []
            primary_func = None

            for vpin in virtual_pins:
                func_name = self.parser.get_attr(vpin, "name", "")
                if func_name:
                    func = PinFunction(name=func_name)
                    functions.append(func)

                    if primary_func is None:
                        primary_func = func_name

                    # Categorize pin type
                    if not pin_info.pin_type:
                        if func_name in ["VDD", "VSS"]:
                            pin_info.pin_type = "power"
                        elif func_name in ["MCLR", "VPP"]:
                            pin_info.pin_type = "control"
                        elif func_name.startswith("AN") or "VREF" in func_name:
                            pin_info.pin_type = "analog"
                        elif func_name.startswith("OSC"):
                            pin_info.pin_type = "oscillator"
                        elif func_name.startswith("PGC") or func_name.startswith("PGD"):
                            pin_info.pin_type = "programming"
                        else:
                            pin_info.pin_type = "digital"

            pin_info.primary_function = primary_func
            pin_info.alternative_functions = functions
            pins.append(pin_info)

        return pins

    def _parse_debug_capabilities(
        self, device_element: etree._Element
    ) -> Optional[DebugCapabilities]:
        """Parse debug and hardware tool capabilities."""
        # Look for Breakpoints element
        bp_elem = device_element.find(
            ".//edc:Breakpoints", {"edc": "http://crownking/edc"}
        )
        if bp_elem is None:
            bp_elem = device_element.find('.//*[local-name()="Breakpoints"]')

        if bp_elem is None:
            return None

        debug_caps = DebugCapabilities()

        # Hardware breakpoint count
        hwbp_count = self._parse_int(self.parser.get_attr(bp_elem, "hwbpcount", ""))
        if hwbp_count:
            debug_caps.hardware_breakpoint_count = hwbp_count

        # Data capture capability
        has_data_capture = self.parser.get_attr(bp_elem, "hasdatacapture", "")
        if has_data_capture:
            debug_caps.has_data_capture = has_data_capture.lower() == "true"

        # ID byte
        id_byte = self.parser.get_attr(bp_elem, "idbyte", "")
        if id_byte:
            debug_caps.id_byte = id_byte

        return debug_caps

    def _parse_architecture_info(
        self, device_element: etree._Element
    ) -> Optional[ArchitectureInfo]:
        """Parse device architecture information."""
        arch_info = ArchitectureInfo()

        # Look for InstructionSet element
        instr_elem = device_element.find(
            ".//edc:InstructionSet", {"edc": "http://crownking/edc"}
        )
        if instr_elem is None:
            instr_elem = device_element.find('.//*[local-name()="InstructionSet"]')

        if instr_elem is not None:
            instr_set_id = self.parser.get_attr(instr_elem, "instructionsetid", "")
            if instr_set_id:
                arch_info.instruction_set = instr_set_id

        # Look for MemTraits element for hardware stack info
        mem_traits = device_element.find(
            ".//edc:MemTraits", {"edc": "http://crownking/edc"}
        )
        if mem_traits is None:
            mem_traits = device_element.find('.//*[local-name()="MemTraits"]')

        if mem_traits is not None:
            hwstack = self._parse_int(
                self.parser.get_attr(mem_traits, "hwstackdepth", "")
            )
            if hwstack:
                arch_info.hardware_stack_depth = hwstack

            # Code memory traits for word sizes
            code_traits = mem_traits.find(
                ".//edc:CodeMemTraits", {"edc": "http://crownking/edc"}
            )
            if code_traits is None:
                code_traits = mem_traits.find('.//*[local-name()="CodeMemTraits"]')

            if code_traits is not None:
                word_size = self._parse_int(
                    self.parser.get_attr(code_traits, "wordsize", "")
                )
                if word_size:
                    arch_info.code_word_size = word_size

            # Data memory traits
            data_traits = mem_traits.find(
                ".//edc:DataMemTraits", {"edc": "http://crownking/edc"}
            )
            if data_traits is None:
                data_traits = mem_traits.find('.//*[local-name()="DataMemTraits"]')

            if data_traits is not None:
                word_size = self._parse_int(
                    self.parser.get_attr(data_traits, "wordsize", "")
                )
                if word_size:
                    arch_info.data_word_size = word_size

        # Return None if no meaningful data was found
        if not any(
            [
                arch_info.instruction_set,
                arch_info.hardware_stack_depth,
                arch_info.code_word_size,
                arch_info.data_word_size,
            ]
        ):
            return None

        return arch_info

    def _detect_peripherals(self, device_element: etree._Element) -> List[str]:
        """Detect available peripherals from register definitions."""
        peripherals = set()

        # Extract peripheral info from SFR definitions
        sfr_defs = device_element.findall(
            ".//edc:SFRDef", {"edc": "http://crownking/edc"}
        )
        if not sfr_defs:
            sfr_defs = device_element.findall('.//*[local-name()="SFRDef"]')

        for sfr in sfr_defs:
            name = self.parser.get_attr(sfr, "name", "")
            if name:
                # Identify peripheral type from register name
                name_upper = name.upper()
                if any(
                    name_upper.startswith(timer)
                    for timer in [
                        "TMR",
                        "T0CON",
                        "T1CON",
                        "T2CON",
                        "T3CON",
                        "T4CON",
                        "T5CON",
                    ]
                ):
                    peripherals.add("TIMER")
                elif name_upper.startswith("CCP") or name_upper.startswith("PWM"):
                    peripherals.add("CCP_PWM")
                elif any(
                    name_upper.startswith(adc) for adc in ["ADC", "ADCON", "ADRES"]
                ):
                    peripherals.add("ADC")
                elif any(name_upper.startswith(spi) for spi in ["SSP", "SPI"]):
                    peripherals.add("SPI")
                elif any(
                    name_upper.startswith(uart) for uart in ["USART", "UART", "EUSART"]
                ):
                    peripherals.add("UART")
                elif any(name_upper.startswith(i2c) for i2c in ["I2C", "MSSP"]):
                    peripherals.add("I2C")
                elif name_upper.startswith("CM") or "CMCON" in name_upper:
                    peripherals.add("COMPARATOR")
                elif name_upper in [
                    "PIE1",
                    "PIE2",
                    "PIE3",
                    "PIE4",
                    "PIR1",
                    "PIR2",
                    "PIR3",
                    "PIR4",
                    "INTCON",
                ]:
                    peripherals.add("INTERRUPT_CONTROLLER")
                elif any(
                    name_upper.startswith(gpio) for gpio in ["TRIS", "PORT", "LAT"]
                ):
                    peripherals.add("GPIO")
                elif name_upper.startswith("WDT") or name_upper == "WDTCON":
                    peripherals.add("WATCHDOG")
                elif any(
                    name_upper.startswith(eep) for eep in ["EECON", "EEDATA", "EEADR"]
                ):
                    peripherals.add("EEPROM")
                elif any(name_upper.startswith(osc) for osc in ["OSC", "CLOCK"]):
                    peripherals.add("OSCILLATOR")

        return sorted(list(peripherals))

    def _parse_float(self, value_str: str) -> Optional[float]:
        """Parse a string to float, return None if invalid."""
        if not value_str:
            return None
        try:
            return float(value_str)
        except (ValueError, TypeError):
            return None

    def _parse_int(self, value_str: str) -> Optional[int]:
        """Parse a string to int, return None if invalid."""
        if not value_str:
            return None
        try:
            return int(value_str)
        except (ValueError, TypeError):
            return None

    def _parse_memory_spaces(self, device_element: etree._Element) -> List[MemorySpace]:
        """Parse hierarchical memory spaces from PIC device."""
        memory_spaces = []

        # Parse ProgramSpace - contains CodeSector elements for program memory
        program_spaces = self.parser.xpath(
            './/edc:ProgramSpace | .//*[local-name()="ProgramSpace"]', device_element
        )
        for ps in program_spaces:
            segments = []

            # Parse all types of sectors within ProgramSpace
            code_sectors = self.parser.xpath(
                './/edc:CodeSector | .//*[local-name()="CodeSector"]', ps
            )
            for cs in code_sectors:
                start = self.parser.get_attr_hex(cs, "beginaddr", 0)
                end = self.parser.get_attr_hex(cs, "endaddr", 0)
                name = self.parser.get_attr(cs, "sectionname", "PROG")
                region_id = self.parser.get_attr(cs, "regionid", "")
                section_desc = self.parser.get_attr(cs, "sectiondesc", "")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=name,
                            start=start,
                            size=size,
                            type="program",
                            section=section_desc,
                            address_space="program",
                            parent_name="ProgramSpace",
                            level=1,
                        )
                    )

            # Parse other sectors in ProgramSpace (UserIDSector, DeviceIDSector, ConfigFuseSector, etc.)
            other_sectors = [
                ('.//edc:UserIDSector | .//*[local-name()="UserIDSector"]', "userid"),
                (
                    './/edc:DeviceIDSector | .//*[local-name()="DeviceIDSector"]',
                    "deviceid",
                ),
                (
                    './/edc:ConfigFuseSector | .//*[local-name()="ConfigFuseSector"]',
                    "config",
                ),
                ('.//edc:EEDataSector | .//*[local-name()="EEDataSector"]', "eeprom"),
                ('.//edc:TestZone | .//*[local-name()="TestZone"]', "test"),
                (
                    './/edc:BACKBUGVectorSector | .//*[local-name()="BACKBUGVectorSector"]',
                    "debug",
                ),
            ]

            for xpath_expr, sector_type in other_sectors:
                sector_elements = self.parser.xpath(xpath_expr, ps)
                for elem in sector_elements:
                    start = self.parser.get_attr_hex(elem, "beginaddr", 0)
                    end = self.parser.get_attr_hex(elem, "endaddr", 0)
                    name = self.parser.get_attr(
                        elem, "sectionname", sector_type.upper()
                    )
                    region_id = self.parser.get_attr(elem, "regionid", "")
                    section_desc = self.parser.get_attr(elem, "sectiondesc", "")

                    if end > start:
                        size = end - start
                        segments.append(
                            MemorySegment(
                                name=name,
                                start=start,
                                size=size,
                                type=sector_type,
                                section=section_desc,
                                address_space="program",
                                parent_name="ProgramSpace",
                                level=1,
                            )
                        )

            if segments:
                memory_spaces.append(
                    MemorySpace(
                        name="ProgramSpace",
                        space_type="ProgramSpace",
                        segments=sorted(segments, key=lambda x: x.start),
                    )
                )

        # Parse DataSpace - contains SFRDataSector and other data memory
        data_spaces = self.parser.xpath(
            './/edc:DataSpace | .//*[local-name()="DataSpace"]', device_element
        )
        for ds in data_spaces:
            segments = []

            # Parse SFRDataSector elements
            sfr_sectors = self.parser.xpath(
                './/edc:SFRDataSector | .//*[local-name()="SFRDataSector"]', ds
            )
            for sfr in sfr_sectors:
                start = self.parser.get_attr_hex(sfr, "beginaddr", 0)
                end = self.parser.get_attr_hex(sfr, "endaddr", 0)
                bank = self.parser.get_attr(sfr, "bank", "0")
                region_id = self.parser.get_attr(sfr, "regionid", "")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=f"SFR_BANK{bank}",
                            start=start,
                            size=size,
                            type="sfr",
                            address_space="data",
                            parent_name="DataSpace",
                            level=1,
                        )
                    )

            # Parse GPRDataSector elements (General Purpose Registers)
            gpr_sectors = self.parser.xpath(
                './/edc:GPRDataSector | .//*[local-name()="GPRDataSector"]', ds
            )
            for gpr in gpr_sectors:
                # Skip shadow sectors (they are mirrors of other memory regions)
                # Check for shadowidref attribute with both namespace and local name approaches
                shadow_ref = (
                    self.parser.get_attr(gpr, "shadowidref")
                    or self.parser.get_attr(gpr, "{http://crownking/edc}shadowidref")
                    or gpr.get("{http://crownking/edc}shadowidref")
                )
                if shadow_ref is not None:
                    continue

                start = self.parser.get_attr_hex(gpr, "beginaddr", 0)
                end = self.parser.get_attr_hex(gpr, "endaddr", 0)
                bank = self.parser.get_attr(gpr, "bank", "0")
                region_id = self.parser.get_attr(gpr, "regionid", "")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=f"GPR_BANK{bank}",
                            start=start,
                            size=size,
                            type="gpr",
                            address_space="data",
                            parent_name="DataSpace",
                            level=1,
                        )
                    )

            # Parse general DataSector elements
            data_sectors = self.parser.xpath(
                './/edc:DataSector | .//*[local-name()="DataSector"]', ds
            )
            for ds_elem in data_sectors:
                start = self.parser.get_attr_hex(ds_elem, "beginaddr", 0)
                end = self.parser.get_attr_hex(ds_elem, "endaddr", 0)
                name = self.parser.get_attr(ds_elem, "sectionname", "DATA")
                region_id = self.parser.get_attr(ds_elem, "regionid", "")
                section_desc = self.parser.get_attr(ds_elem, "sectiondesc", "")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=name,
                            start=start,
                            size=size,
                            type="data",
                            section=section_desc,
                            address_space="data",
                            parent_name="DataSpace",
                            level=1,
                        )
                    )

            if segments:
                # Calculate total data space bounds from the endaddr attribute if available
                ds_end_attr = self.parser.get_attr(ds, "endaddr", None)
                try:
                    ds_size = int(ds_end_attr, 16) if ds_end_attr else None
                except (ValueError, TypeError):
                    ds_size = None

                memory_spaces.append(
                    MemorySpace(
                        name="DataSpace",
                        space_type="DataSpace",
                        start=0,  # DataSpace typically starts at 0
                        size=ds_size,
                        segments=sorted(segments, key=lambda x: x.start),
                    )
                )

        # Parse EEDataSpace for EEPROM (less common, but may exist)
        ee_spaces = self.parser.xpath(
            './/edc:EEDataSpace | .//*[local-name()="EEDataSpace"]', device_element
        )
        for es in ee_spaces:
            segments = []

            ee_sectors = self.parser.xpath(
                './/edc:EESector | .//*[local-name()="EESector"]', es
            )
            for ee in ee_sectors:
                start = self.parser.get_attr_hex(ee, "beginaddr", 0)
                end = self.parser.get_attr_hex(ee, "endaddr", 0)
                name = self.parser.get_attr(ee, "sectionname", "EEPROM")
                region_id = self.parser.get_attr(ee, "regionid", "")
                section_desc = self.parser.get_attr(ee, "sectiondesc", "")

                if end > start:
                    size = end - start
                    segments.append(
                        MemorySegment(
                            name=name,
                            start=start,
                            size=size,
                            type="eeprom",
                            section=section_desc,
                            address_space="eeprom",
                            parent_name="EEDataSpace",
                            level=1,
                        )
                    )

            if segments:
                memory_spaces.append(
                    MemorySpace(
                        name="EEDataSpace",
                        space_type="EEDataSpace",
                        segments=sorted(segments, key=lambda x: x.start),
                    )
                )

        return memory_spaces

__init__(xml_content)

Initialize with XML content.

Source code in src/atpack_parser/parser/pic.py

def __init__(self, xml_content: str):
    """Initialize with XML content."""
    self.parser = XmlParser(xml_content)

parse_device(device_name=None)

Parse device information from PIC file.

Source code in src/atpack_parser/parser/pic.py

def parse_device(self, device_name: Optional[str] = None) -> Device:
    """Parse device information from PIC file."""
    # Get device element - try with and without namespace
    if device_name:
        device_elements = self.parser.xpath(f'//edc:PIC[@edc:name="{device_name}"]')
        if not device_elements:
            device_elements = self.parser.xpath(
                f'//*[local-name()="PIC" and @*[local-name()="name"]="{device_name}"]'
            )
    else:
        device_elements = self.parser.xpath("//edc:PIC")
        if not device_elements:
            device_elements = self.parser.xpath('//*[local-name()="PIC"]')

    if not device_elements:
        if device_name:
            raise ParseError(f"Device '{device_name}' not found in PIC file")
        else:
            raise ParseError("No device found in PIC file")

    device_element = device_elements[0]

    # Extract device name - try namespace and local name approaches
    name = (
        self.parser.get_attr(device_element, "name")
        or self.parser.get_attr(device_element, "{http://crownking/edc}name")
        or device_element.get("{http://crownking/edc}name")
        or ""
    )

    if not name and device_name:
        name = device_name

    # Extract series from architecture attribute
    arch = self.parser.get_attr(device_element, "arch", "")
    series = None
    if arch:
        # Convert arch like "16xxxx" to "PIC16"
        if arch.startswith("16"):
            series = "PIC16"
        elif arch.startswith("18"):
            series = "PIC18"
        elif arch.startswith("12"):
            series = "PIC12"
        elif arch.startswith("10"):
            series = "PIC10"
        else:
            series = f"PIC{arch}"

    device = Device(
        name=name, family=DeviceFamily.PIC, architecture="PIC", series=series
    )

    # Parse memory segments
    device.memory_segments = self._parse_memory_segments(device_element)
    device.memory_spaces = self._parse_memory_spaces(device_element)

    # Parse modules/peripherals
    device.modules = self._parse_modules(device_element)

    # Parse configuration words
    device.config_words = self._parse_config_words(device_element)

    # Parse interrupts
    device.interrupts = self._parse_interrupts(device_element)

    # Parse signatures/device IDs
    device.signatures = self._parse_signatures(device_element)

    # Additional metadata
    device.metadata = self._extract_metadata(device_element)

    # Parse additional PlatformIO-useful information
    device.power_specs = self._parse_power_specifications(device_element)
    device.oscillator_configs = self._parse_oscillator_configurations(
        device_element
    )
    device.programming_interface = self._parse_programming_interface(device_element)
    device.pinout = self._parse_pinout_info(device_element)
    device.debug_capabilities = self._parse_debug_capabilities(device_element)
    device.architecture_info = self._parse_architecture_info(device_element)
    device.detected_peripherals = self._detect_peripherals(device_element)

    return device

PDSC Parser

For parsing Pack Description (PDSC) files.

Parser for PDSC files containing AtPack metadata.

Source code in src/atpack_parser/parser/pdsc.py

class PdscParser:
    """Parser for PDSC files containing AtPack metadata."""

    def __init__(self, xml_content: str):
        """Initialize with XML content."""
        self.parser = XmlParser(xml_content)

    def parse_metadata(self) -> AtPackMetadata:
        """Parse AtPack metadata from PDSC."""
        # Get package information
        package_name = self.parser.xpath_text("//package/@name", "Unknown")
        description = self.parser.xpath_text("//package/description/text()", "")
        vendor = self.parser.xpath_text("//package/@vendor", "Unknown")
        version = self.parser.xpath_text("//package/@version", "0.0.0")
        url = self.parser.xpath_text("//package/@url", "")

        return AtPackMetadata(
            name=package_name or "Unknown",
            description=description,
            vendor=vendor,
            version=version,
            url=url,
        )

    def list_devices(self) -> List[str]:
        """List all device names mentioned in PDSC."""
        device_names = []

        # Look for device definitions
        devices = self.parser.xpath("//devices/family/device/@Dname")
        device_names.extend([name for name in devices if isinstance(name, str)])

        # Also look for subfamily devices
        subfamily_devices = self.parser.xpath(
            "//devices/family/subFamily/device/@Dname"
        )
        device_names.extend(
            [name for name in subfamily_devices if isinstance(name, str)]
        )

        # Look for variant devices
        variant_devices = self.parser.xpath("//devices/family/device/variant/@Dvariant")
        device_names.extend([name for name in variant_devices if isinstance(name, str)])

        # Remove duplicates and sort
        return sorted(list(set(device_names)))

    def get_device_info(self, device_name: str) -> Optional[dict]:
        """Get basic device information from PDSC."""
        # Look for device by name
        device_elements = self.parser.xpath(
            f'//device[@Dname="{device_name}"] | //variant[@Dvariant="{device_name}"]'
        )

        if not device_elements:
            return None

        device_elem = device_elements[0]

        # Get family information
        family_elem = device_elem
        while family_elem is not None and family_elem.tag != "family":
            family_elem = family_elem.getparent()

        family_name = ""
        if family_elem is not None:
            family_name = self.parser.get_attr(family_elem, "Dfamily", "")

        # Extract device information
        processor = self.parser.get_attr(device_elem, "Dcore", "")
        clock = self.parser.get_attr(device_elem, "Dclock", "")
        flash_size = self.parser.get_attr(device_elem, "Dflash", "")
        ram_size = self.parser.get_attr(device_elem, "Dram", "")
        package = self.parser.get_attr(device_elem, "Dpackage", "")

        return {
            "name": device_name,
            "family": family_name,
            "processor": processor,
            "clock": clock,
            "flash_size": flash_size,
            "ram_size": ram_size,
            "package": package,
        }

    def detect_device_family(self) -> DeviceFamily:
        """Detect device family from PDSC content."""
        # Check vendor
        vendor = self.parser.xpath_text("//package/@vendor", "").upper()

        if "ATMEL" in vendor:
            return DeviceFamily.ATMEL
        elif "MICROCHIP" in vendor:
            # Could be either ATMEL (acquired by Microchip) or PIC
            # Check device families or processor types
            processors = self.parser.xpath("//device/@Dcore")
            families = self.parser.xpath("//family/@Dfamily")

            # Check for typical ATMEL processors
            atmel_processors = ["ARM", "AVR", "Cortex"]
            for proc in processors:
                if isinstance(proc, str):
                    for atmel_proc in atmel_processors:
                        if atmel_proc in proc.upper():
                            return DeviceFamily.ATMEL

            # Check for typical ATMEL families
            atmel_families = ["AVR", "SAM", "MEGA", "TINY"]
            for family in families:
                if isinstance(family, str):
                    for atmel_fam in atmel_families:
                        if atmel_fam in family.upper():
                            return DeviceFamily.ATMEL

            # Default to PIC for Microchip
            return DeviceFamily.PIC

        return DeviceFamily.UNSUPPORTED

    def get_file_references(self) -> dict:
        """Get file references from PDSC."""
        files = {"atdf": [], "pic": [], "headers": [], "docs": []}

        # Look for file elements
        file_elements = self.parser.xpath("//files/file")

        for file_elem in file_elements:
            file_name = self.parser.get_attr(file_elem, "name", "")
            file_category = self.parser.get_attr(file_elem, "category", "")

            if file_name:
                if file_name.lower().endswith(".atdf"):
                    files["atdf"].append(file_name)
                elif file_name.lower().endswith(".pic"):
                    files["pic"].append(file_name)
                elif file_category in ["header", "include"]:
                    files["headers"].append(file_name)
                elif file_category in ["doc", "documentation"]:
                    files["docs"].append(file_name)

        return files

__init__(xml_content)

Initialize with XML content.

Source code in src/atpack_parser/parser/pdsc.py

def __init__(self, xml_content: str):
    """Initialize with XML content."""
    self.parser = XmlParser(xml_content)

detect_device_family()

Detect device family from PDSC content.

Source code in src/atpack_parser/parser/pdsc.py

def detect_device_family(self) -> DeviceFamily:
    """Detect device family from PDSC content."""
    # Check vendor
    vendor = self.parser.xpath_text("//package/@vendor", "").upper()

    if "ATMEL" in vendor:
        return DeviceFamily.ATMEL
    elif "MICROCHIP" in vendor:
        # Could be either ATMEL (acquired by Microchip) or PIC
        # Check device families or processor types
        processors = self.parser.xpath("//device/@Dcore")
        families = self.parser.xpath("//family/@Dfamily")

        # Check for typical ATMEL processors
        atmel_processors = ["ARM", "AVR", "Cortex"]
        for proc in processors:
            if isinstance(proc, str):
                for atmel_proc in atmel_processors:
                    if atmel_proc in proc.upper():
                        return DeviceFamily.ATMEL

        # Check for typical ATMEL families
        atmel_families = ["AVR", "SAM", "MEGA", "TINY"]
        for family in families:
            if isinstance(family, str):
                for atmel_fam in atmel_families:
                    if atmel_fam in family.upper():
                        return DeviceFamily.ATMEL

        # Default to PIC for Microchip
        return DeviceFamily.PIC

    return DeviceFamily.UNSUPPORTED

get_device_info(device_name)

Get basic device information from PDSC.

Source code in src/atpack_parser/parser/pdsc.py

def get_device_info(self, device_name: str) -> Optional[dict]:
    """Get basic device information from PDSC."""
    # Look for device by name
    device_elements = self.parser.xpath(
        f'//device[@Dname="{device_name}"] | //variant[@Dvariant="{device_name}"]'
    )

    if not device_elements:
        return None

    device_elem = device_elements[0]

    # Get family information
    family_elem = device_elem
    while family_elem is not None and family_elem.tag != "family":
        family_elem = family_elem.getparent()

    family_name = ""
    if family_elem is not None:
        family_name = self.parser.get_attr(family_elem, "Dfamily", "")

    # Extract device information
    processor = self.parser.get_attr(device_elem, "Dcore", "")
    clock = self.parser.get_attr(device_elem, "Dclock", "")
    flash_size = self.parser.get_attr(device_elem, "Dflash", "")
    ram_size = self.parser.get_attr(device_elem, "Dram", "")
    package = self.parser.get_attr(device_elem, "Dpackage", "")

    return {
        "name": device_name,
        "family": family_name,
        "processor": processor,
        "clock": clock,
        "flash_size": flash_size,
        "ram_size": ram_size,
        "package": package,
    }

get_file_references()

Get file references from PDSC.

Source code in src/atpack_parser/parser/pdsc.py

def get_file_references(self) -> dict:
    """Get file references from PDSC."""
    files = {"atdf": [], "pic": [], "headers": [], "docs": []}

    # Look for file elements
    file_elements = self.parser.xpath("//files/file")

    for file_elem in file_elements:
        file_name = self.parser.get_attr(file_elem, "name", "")
        file_category = self.parser.get_attr(file_elem, "category", "")

        if file_name:
            if file_name.lower().endswith(".atdf"):
                files["atdf"].append(file_name)
            elif file_name.lower().endswith(".pic"):
                files["pic"].append(file_name)
            elif file_category in ["header", "include"]:
                files["headers"].append(file_name)
            elif file_category in ["doc", "documentation"]:
                files["docs"].append(file_name)

    return files

list_devices()

List all device names mentioned in PDSC.

Source code in src/atpack_parser/parser/pdsc.py

def list_devices(self) -> List[str]:
    """List all device names mentioned in PDSC."""
    device_names = []

    # Look for device definitions
    devices = self.parser.xpath("//devices/family/device/@Dname")
    device_names.extend([name for name in devices if isinstance(name, str)])

    # Also look for subfamily devices
    subfamily_devices = self.parser.xpath(
        "//devices/family/subFamily/device/@Dname"
    )
    device_names.extend(
        [name for name in subfamily_devices if isinstance(name, str)]
    )

    # Look for variant devices
    variant_devices = self.parser.xpath("//devices/family/device/variant/@Dvariant")
    device_names.extend([name for name in variant_devices if isinstance(name, str)])

    # Remove duplicates and sort
    return sorted(list(set(device_names)))

parse_metadata()

Parse AtPack metadata from PDSC.

Source code in src/atpack_parser/parser/pdsc.py

def parse_metadata(self) -> AtPackMetadata:
    """Parse AtPack metadata from PDSC."""
    # Get package information
    package_name = self.parser.xpath_text("//package/@name", "Unknown")
    description = self.parser.xpath_text("//package/description/text()", "")
    vendor = self.parser.xpath_text("//package/@vendor", "Unknown")
    version = self.parser.xpath_text("//package/@version", "0.0.0")
    url = self.parser.xpath_text("//package/@url", "")

    return AtPackMetadata(
        name=package_name or "Unknown",
        description=description,
        vendor=vendor,
        version=version,
        url=url,
    )

Exceptions

AtPackError

Base exception for parsing errors.

Bases: Exception

Base exception for AtPack parsing errors.

Source code in src/atpack_parser/exceptions.py

class AtPackError(Exception):
    """Base exception for AtPack parsing errors."""

    pass

DeviceNotFoundError

Exception raised when a device is not found.

Bases: AtPackError

Raised when a requested device is not found in the AtPack.

Source code in src/atpack_parser/exceptions.py

class DeviceNotFoundError(AtPackError):
    """Raised when a requested device is not found in the AtPack."""

    pass

CLI Interface

Command Line Application

The CLI application built with Typer.

Command Line Interface for AtPack Parser using Typer.

main(ctx, version=False)

🔧 AtPack Parser CLI - Parse AtPack files

Available command groups: • files - Manage AtPack files (list, info, extract) • devices - Device information (list, info, search, packages, pinout) • memory - Memory layouts (show) • registers - Register details (list, show) • config - Configuration data (show) • scan - Directory scanning • help-tree - Show command structure • interactive - Start interactive mode with Rich UI • tui - Launch Terminal User Interface

Use 'atpack COMMAND --help' for detailed help on each command. Use 'atpack help-tree' to see the complete command structure. Use 'atpack interactive' for an interactive experience with auto-completion.

Source code in src/atpack_parser/cli/__init__.py

@app.callback(invoke_without_command=True)
def main(
    ctx: typer.Context,
    version: Annotated[
        bool, typer.Option("--version", "-v", help="Show version")
    ] = False,
):
    """
    🔧 AtPack Parser CLI - Parse AtPack files

    Available command groups:
    • files    - Manage AtPack files (list, info, extract)
    • devices  - Device information (list, info, search, packages, pinout)
    • memory   - Memory layouts (show)
    • registers - Register details (list, show)
    • config   - Configuration data (show)
    • scan     - Directory scanning
    • help-tree - Show command structure
    • interactive - Start interactive mode with Rich UI
    • tui      - Launch Terminal User Interface

    Use 'atpack COMMAND --help' for detailed help on each command.
    Use 'atpack help-tree' to see the complete command structure.
    Use 'atpack interactive' for an interactive experience with auto-completion.
    """
    if version:
        from .. import __version__

        atpack = typer.style("AtPack", bg=typer.colors.BLUE)
        parser = typer.style("Parser", bg=typer.colors.WHITE, fg=typer.colors.BLACK)
        version = typer.style("v" + __version__, bg=typer.colors.RED)
        typer.echo(f"{atpack} {parser} {version}")
        raise typer.Exit()

    # If no command is provided, show help
    if ctx.invoked_subcommand is None:
        console.print(ctx.get_help())
        raise typer.Exit()

Usage Examples

Basic Parser Usage

from atpack_parser import AtPackParser

# Initialize parser
parser = AtPackParser("path/to/atpack.atpack")

# Get devices
devices = parser.get_devices()
device = parser.get_device("PIC16F877")

# Get device data
registers = parser.get_device_registers("PIC16F877")
memory = parser.get_device_memory("PIC16F877")

Error Handling

from atpack_parser import AtPackParser
from atpack_parser.exceptions import AtPackError, DeviceNotFoundError

try:
    parser = AtPackParser("invalid.atpack")
    device = parser.get_device("NonExistentDevice")
except AtPackError as e:
    print(f"Parse error: {e}")
except DeviceNotFoundError as e:
    print(f"Device not found: {e}")

Model Properties

Device Model

Property	Type	Description
name	str	Device name (e.g., "PIC16F877")
family	DeviceFamily	Device family (ATMEL/PIC)
architecture	Optional[str]	CPU architecture
series	Optional[str]	Device series
memory_segments	List[MemorySegment]	Memory layout
modules	List[Module]	Device modules/peripherals
fuses	List[Fuse]	Fuse configuration

Register Model

Property	Type	Description
name	str	Register name (e.g., "PORTB")
caption	Optional[str]	Register description
offset	int	Register address offset
size	int	Register size in bytes
mask	Optional[int]	Register mask
bitfields	List[RegisterBitfield]	List of bit fields
access	Optional[str]	Access type (read/write)

MemorySegment Model

Property	Type	Description
name	str	Segment name (e.g., "FLASH")
start	int	Starting address
size	int	Segment size in bytes
type	Optional[str]	Memory type
access	Optional[str]	Access permissions

RegisterBitfield Model

Property	Type	Description
name	str	Bit field name
caption	Optional[str]	Bit field description
mask	int	Bit mask
bit_offset	int	Starting bit position
bit_width	int	Number of bits
values	Optional[Dict[int, str]]	Possible values

Method Reference

AtPackParser Methods

__init__(atpack_path: Union[str, Path])

Initialize the parser with an AtPack file path.

Parameters: - atpack_path: Path to the AtPack file

Raises: - FileNotFoundError: If the file doesn't exist

get_devices() -> List[str]

Get all device names in the AtPack.

Returns: - List of device names

get_device(device_name: str) -> Device

Get a specific device by name.

Parameters: - device_name: Name of the device

Returns: - Device object

Raises: - DeviceNotFoundError: If device is not found

get_device_registers(device_name: str) -> List[Register]

Get all registers for a device.

Parameters: - device_name: Name of the device

Returns: - List of Register objects

get_device_memory(device_name: str) -> List[MemorySegment]

Get memory layout for a device.

Parameters: - device_name: Name of the device

Returns: - List of MemorySegment objects

Version Information

To get version information:

import atpack_parser
print(atpack_parser.__version__)

Contributing

For information about contributing to the API, see the Development section.