device_tree_parser 0.4.0

// ABOUTME: Device tree node structure and property definitions
// ABOUTME: Provides tree building and traversal functionality

use super::error::DtbError;
use super::tokens::DtbToken;
use alloc::{vec, vec::Vec};
use core::convert::TryFrom;
use core::fmt::{self, Display, Formatter};
use core::ops::Index;

/// Strongly-typed property values in device trees.
///
/// Device tree properties can contain various data types. Provides type-safe
/// access to property values with zero-copy parsing from the original DTB buffer.
/// Use the ergonomic `TryFrom` traits for type conversions.
///
/// # Examples
///
/// ```rust
/// # use device_tree_parser::{PropertyValue, DtbError};
/// # use std::convert::TryFrom;
/// # fn example(value: &PropertyValue) -> Result<(), DtbError> {
/// match value {
///     PropertyValue::String(s) => println!("String: {}", s),
///     PropertyValue::U32(n) => println!("Number: {}", n),
///     PropertyValue::U32Array(_) => {
///         // Use TryFrom for ergonomic access
///         let numbers: Vec<u32> = Vec::<u32>::try_from(value)?;
///         println!("Array: {:?}", numbers);
///     }
///     PropertyValue::Bytes(data) => println!("Raw data: {} bytes", data.len()),
///     _ => {}
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum PropertyValue<'a> {
    /// Empty property (property exists but has no value).
    Empty,
    /// Null-terminated string value.
    ///
    /// Common for device names, compatible strings, and text properties.
    String(&'a str),
    /// Multiple null-terminated strings in sequence.
    ///
    /// Used for properties like `compatible` that list multiple values.
    StringList(Vec<&'a str>),
    /// 32-bit unsigned integer value.
    ///
    /// Common for simple numeric properties like counts and flags.
    U32(u32),
    /// Array of 32-bit unsigned integers (stored as raw bytes for zero-copy).
    ///
    /// Use `Vec::<u32>::try_from()` for ergonomic access. Common for register
    /// addresses, interrupt numbers, and GPIO specifications.
    U32Array(&'a [u8]),
    /// 64-bit unsigned integer value.
    ///
    /// Used for large addresses and sizes in 64-bit systems.
    U64(u64),
    /// Array of 64-bit unsigned integers (stored as raw bytes for zero-copy).
    ///
    /// Use `Vec::<u64>::try_from()` for ergonomic access.
    U64Array(&'a [u8]),
    /// Raw byte array for binary data.
    ///
    /// Used for MAC addresses, binary blobs, and vendor-specific data.
    Bytes(&'a [u8]),
}

/// Device tree property with name and typed value.
///
/// Properties are key-value pairs that describe characteristics of device tree
/// nodes. Can represent hardware registers, compatible strings, interrupt
/// mappings, and other device characteristics.
///
/// # Examples
///
/// ```rust
/// # use device_tree_parser::{Property, PropertyValue};
/// # use std::convert::TryFrom;
/// # fn example(prop: &Property) {
/// println!("Property: {} = {}", prop.name, prop.value);
///
/// // Type-safe value extraction
/// match &prop.value {
///     PropertyValue::String(s) => println!("String property: {}", s),
///     PropertyValue::U32(n) => println!("Numeric property: {}", n),
///     _ => {}
/// }
///
/// // Ergonomic type conversion
/// if let Ok(address) = u32::try_from(&prop.value) {
///     println!("Address: 0x{:08x}", address);
/// }
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct Property<'a> {
    /// Property name (e.g., "compatible", "reg", "interrupts").
    pub name: &'a str,
    /// Strongly-typed property value.
    pub value: PropertyValue<'a>,
}

/// Address specification for device tree nodes.
///
/// Represents the addressing configuration used by a node's children. This determines
/// how addresses and sizes are represented in properties like `reg` and `ranges`.
/// Most commonly, addresses use 2 cells (64-bit) and sizes use 1 cell (32-bit).
///
/// # Examples
///
/// ```rust
/// # use device_tree_parser::AddressSpec;
/// // Default addressing (2 address cells, 1 size cell)
/// let default_spec = AddressSpec::default();
/// assert_eq!(default_spec.address_cells(), 2);
/// assert_eq!(default_spec.size_cells(), 1);
///
/// // 32-bit addressing (1 address cell, 1 size cell)
/// let spec_32bit = AddressSpec::new(1, 1).unwrap();
///
/// // PCI addressing (3 address cells, 2 size cells)
/// let spec_pci = AddressSpec::new(3, 2).unwrap();
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AddressSpec {
    address_cells: u32,
    size_cells: u32,
}

impl AddressSpec {
    /// Default number of address cells (2 for 64-bit addresses).
    pub const DEFAULT_ADDRESS_CELLS: u32 = 2;

    /// Default number of size cells (1 for 32-bit sizes).
    pub const DEFAULT_SIZE_CELLS: u32 = 1;

    /// Maximum allowed address cells (4 for up to 128-bit addresses).
    pub const MAX_ADDRESS_CELLS: u32 = 4;

    /// Maximum allowed size cells (4 for up to 128-bit sizes).
    pub const MAX_SIZE_CELLS: u32 = 4;

    /// Creates a new address specification with validation.
    ///
    /// # Arguments
    ///
    /// * `address_cells` - Number of cells for addresses (1-4)
    /// * `size_cells` - Number of cells for sizes (0-4)
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidAddressCells` if `address_cells` is not in range 1-4.
    /// Returns `DtbError::InvalidSizeCells` if `size_cells` is not in range 0-4.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{AddressSpec, DtbError};
    /// // Valid specifications
    /// let spec = AddressSpec::new(2, 1)?;
    /// assert_eq!(spec.address_cells(), 2);
    ///
    /// // Invalid address cells
    /// assert!(AddressSpec::new(5, 1).is_err());
    ///
    /// // Size cells can be 0 (for address-only nodes)
    /// let addr_only = AddressSpec::new(2, 0)?;
    /// # Ok::<(), DtbError>(())
    /// ```
    pub fn new(address_cells: u32, size_cells: u32) -> Result<Self, DtbError> {
        if address_cells == 0 || address_cells > Self::MAX_ADDRESS_CELLS {
            return Err(DtbError::InvalidAddressCells(address_cells));
        }
        if size_cells > Self::MAX_SIZE_CELLS {
            return Err(DtbError::InvalidSizeCells(size_cells));
        }
        Ok(Self {
            address_cells,
            size_cells,
        })
    }

    /// Returns the number of cells used for addresses.
    #[must_use]
    pub const fn address_cells(&self) -> u32 {
        self.address_cells
    }

    /// Returns the number of cells used for sizes.
    #[must_use]
    pub const fn size_cells(&self) -> u32 {
        self.size_cells
    }

    /// Returns the total number of cells for a complete address/size pair.
    #[must_use]
    pub const fn total_cells(&self) -> u32 {
        self.address_cells + self.size_cells
    }

    /// Returns the byte size of addresses based on cell count.
    #[must_use]
    pub const fn address_size_bytes(&self) -> usize {
        (self.address_cells * 4) as usize
    }

    /// Returns the byte size of sizes based on cell count.
    #[must_use]
    pub const fn size_size_bytes(&self) -> usize {
        (self.size_cells * 4) as usize
    }

    /// Returns the total byte size for a complete address/size pair.
    #[must_use]
    pub const fn total_size_bytes(&self) -> usize {
        (self.total_cells() * 4) as usize
    }
}

impl Default for AddressSpec {
    /// Creates default address specification (2 address cells, 1 size cell).
    ///
    /// This is the most common configuration for 64-bit systems.
    fn default() -> Self {
        Self {
            address_cells: Self::DEFAULT_ADDRESS_CELLS,
            size_cells: Self::DEFAULT_SIZE_CELLS,
        }
    }
}

/// Address range entry from a device tree `ranges` property.
///
/// The `ranges` property provides mappings between address spaces of parent and child
/// bus domains. Each range specifies how to translate addresses from the child address
/// space to the parent address space.
///
/// # Examples
///
/// ```rust
/// # use device_tree_parser::{AddressRange, DtbError};
/// let range = AddressRange::new(0x0, 0x80000000, 0x10000000)?;
///
/// // Check if an address is in this range
/// assert!(range.contains(0x8000));
/// assert!(!range.contains(0x20000000));
///
/// // Translate a child address to parent address
/// let parent_addr = range.translate(0x8000)?;
/// assert_eq!(parent_addr, 0x80008000);
/// # Ok::<(), DtbError>(())
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AddressRange {
    /// Child address (in child's address space).
    child_address: u64,
    /// Parent address (in parent's address space).
    parent_address: u64,
    /// Size of the range in bytes.
    size: u64,
}

impl AddressRange {
    /// Creates a new address range with validation.
    ///
    /// # Arguments
    ///
    /// * `child_address` - Starting address in child's address space
    /// * `parent_address` - Starting address in parent's address space  
    /// * `size` - Size of the range in bytes
    ///
    /// # Errors
    ///
    /// Returns `DtbError::AddressTranslationError` if the range would cause
    /// address arithmetic overflow.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{AddressRange, DtbError};
    /// // Map child addresses 0x0-0xFFFFFF to parent 0x80000000-0x80FFFFFF
    /// let range = AddressRange::new(0x0, 0x80000000, 0x1000000)?;
    /// assert_eq!(range.child_address(), 0x0);
    /// assert_eq!(range.parent_address(), 0x80000000);
    /// assert_eq!(range.size(), 0x1000000);
    /// # Ok::<(), DtbError>(())
    /// ```
    pub fn new(child_address: u64, parent_address: u64, size: u64) -> Result<Self, DtbError> {
        // Validate that the range doesn't overflow
        if child_address.checked_add(size).is_none() {
            return Err(DtbError::AddressTranslationError(child_address));
        }
        if parent_address.checked_add(size).is_none() {
            return Err(DtbError::AddressTranslationError(parent_address));
        }

        Ok(Self {
            child_address,
            parent_address,
            size,
        })
    }

    /// Returns the child address (start of range in child address space).
    #[must_use]
    pub const fn child_address(&self) -> u64 {
        self.child_address
    }

    /// Returns the parent address (start of range in parent address space).
    #[must_use]
    pub const fn parent_address(&self) -> u64 {
        self.parent_address
    }

    /// Returns the size of the range in bytes.
    #[must_use]
    pub const fn size(&self) -> u64 {
        self.size
    }

    /// Returns the end address in child address space (exclusive).
    #[must_use]
    pub const fn child_end(&self) -> u64 {
        self.child_address + self.size
    }

    /// Returns the end address in parent address space (exclusive).
    #[must_use]
    pub const fn parent_end(&self) -> u64 {
        self.parent_address + self.size
    }

    /// Checks if a child address falls within this range.
    ///
    /// # Arguments
    ///
    /// * `address` - Address in child's address space to check
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{AddressRange, DtbError};
    /// let range = AddressRange::new(0x1000, 0x80001000, 0x1000)?;
    ///
    /// assert!(range.contains(0x1000));   // Start of range
    /// assert!(range.contains(0x1500));   // Middle of range
    /// assert!(!range.contains(0x2000));  // End of range (exclusive)
    /// assert!(!range.contains(0x500));   // Before range
    /// # Ok::<(), DtbError>(())
    /// ```
    #[must_use]
    pub const fn contains(&self, address: u64) -> bool {
        address >= self.child_address && address < self.child_end()
    }

    /// Translates a child address to the corresponding parent address.
    ///
    /// # Arguments
    ///
    /// * `child_addr` - Address in child's address space
    ///
    /// # Errors
    ///
    /// Returns `DtbError::AddressTranslationError` if the address is not
    /// within this range or if translation would cause overflow.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{AddressRange, DtbError};
    /// let range = AddressRange::new(0x0, 0x80000000, 0x10000)?;
    ///
    /// assert_eq!(range.translate(0x0)?, 0x80000000);     // Start
    /// assert_eq!(range.translate(0x8000)?, 0x80008000);  // Middle
    ///
    /// // Address outside range should fail
    /// assert!(range.translate(0x20000).is_err());
    /// # Ok::<(), DtbError>(())
    /// ```
    pub fn translate(&self, child_addr: u64) -> Result<u64, DtbError> {
        if !self.contains(child_addr) {
            return Err(DtbError::AddressTranslationError(child_addr));
        }

        let offset = child_addr - self.child_address;
        self.parent_address
            .checked_add(offset)
            .ok_or(DtbError::AddressTranslationError(child_addr))
    }
}

/// Device tree node representing a hardware component or logical grouping.
///
/// Device tree nodes form a hierarchical structure describing system hardware.
/// Each node has a name, properties describing its characteristics, and optionally
/// child nodes. Provides ergonomic access through Index traits, `IntoIterator`,
/// and search methods.
///
/// # Examples
///
/// ## Basic Access
///
/// ```rust
/// # use device_tree_parser::{DeviceTreeNode, PropertyValue};
/// # fn example(node: &DeviceTreeNode) {
/// println!("Node: {}", node.name);
/// println!("Properties: {}", node.properties.len());
/// println!("Children: {}", node.children.len());
///
/// // Find specific properties
/// if let Some(prop) = node.find_property("compatible") {
///     println!("Compatible: {}", prop.value);
/// }
/// # }
/// ```
///
/// ## Ergonomic Access (v0.3.0+)
///
/// ```rust
/// # use device_tree_parser::{DeviceTreeNode, DtbError};
/// # use std::convert::TryFrom;
/// # fn example(node: &DeviceTreeNode) -> Result<(), DtbError> {
/// // Property access using Index trait
/// if node.has_property("reg") {
///     let reg_prop = &node["reg"];
///     println!("Register: {}", reg_prop.value);
/// }
///
/// // Child access using Index trait
/// if !node.children.is_empty() {
///     let first_child = &node[0];
///     println!("First child: {}", first_child.name);
/// }
///
/// // Natural iteration over children
/// for child in node {
///     println!("Child: {}", child.name);
/// }
///
/// // Type-safe property conversion
/// if let Some(prop) = node.find_property("reg") {
///     let addresses: Vec<u32> = Vec::<u32>::try_from(&prop.value)?;
///     println!("Addresses: {:?}", addresses);
/// }
/// # Ok(())
/// # }
/// ```
///
/// ## Hardware Discovery
///
/// ```rust
/// # use device_tree_parser::DeviceTreeNode;
/// # fn example(root: &DeviceTreeNode) {
/// // Find specific nodes by path
/// if let Some(chosen) = root.find_node("/chosen") {
///     println!("Found chosen node");
/// }
///
/// // Find nodes by device type
/// let memory_nodes: Vec<_> = root
///     .iter_nodes()
///     .filter(|n| n.prop_string("device_type") == Some("memory"))
///     .collect();
/// println!("Found {} memory nodes", memory_nodes.len());
///
/// // Find compatible devices
/// let uart_nodes = root.find_compatible_nodes("arm,pl011");
/// println!("Found {} UART devices", uart_nodes.len());
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct DeviceTreeNode<'a> {
    /// Node name (e.g., "cpu@0", "memory@40000000", "uart@9000000").
    pub name: &'a str,
    /// Properties describing this node's characteristics.
    pub properties: Vec<Property<'a>>,
    /// Child nodes in the device tree hierarchy.
    pub children: Vec<DeviceTreeNode<'a>>,
}

impl<'a> DeviceTreeNode<'a> {
    /// Create a new device tree node
    #[must_use]
    pub fn new(name: &'a str) -> Self {
        Self {
            name,
            properties: Vec::new(),
            children: Vec::new(),
        }
    }

    /// Add a property to the node
    pub fn add_property(&mut self, property: Property<'a>) {
        self.properties.push(property);
    }

    /// Add a child node
    pub fn add_child(&mut self, child: DeviceTreeNode<'a>) {
        self.children.push(child);
    }

    /// Find a property by name
    #[must_use]
    pub fn find_property(&self, name: &str) -> Option<&Property<'a>> {
        self.properties.iter().find(|p| p.name == name)
    }

    /// Find a child node by name
    #[must_use]
    pub fn find_child(&self, name: &str) -> Option<&DeviceTreeNode<'a>> {
        self.children.iter().find(|c| c.name == name)
    }

    /// Find a node by path (e.g., "/cpus/cpu@0")
    #[must_use]
    pub fn find_node(&self, path: &str) -> Option<&DeviceTreeNode<'a>> {
        if path.is_empty() || path == "/" {
            return Some(self);
        }

        let path = path.strip_prefix('/').unwrap_or(path);
        let parts: Vec<&str> = path.split('/').collect();

        self.find_node_by_parts(&parts)
    }

    /// Find a node by path parts
    fn find_node_by_parts(&self, parts: &[&str]) -> Option<&DeviceTreeNode<'a>> {
        if parts.is_empty() {
            return Some(self);
        }

        let current_part = parts[0];
        let remaining_parts = &parts[1..];

        // Look for exact match first
        if let Some(child) = self.find_child(current_part) {
            return child.find_node_by_parts(remaining_parts);
        }

        // Look for address-based match (e.g., "cpu@0")
        for child in &self.children {
            if child.name.starts_with(current_part)
                && let Some(at_pos) = child.name.find('@')
            {
                let base_name = &child.name[..at_pos];
                if base_name == current_part {
                    return child.find_node_by_parts(remaining_parts);
                }
            }
        }

        None
    }

    /// Get property value as u32
    #[must_use]
    pub fn prop_u32(&self, name: &str) -> Option<u32> {
        self.find_property(name).and_then(|p| match &p.value {
            PropertyValue::U32(val) => Some(*val),
            PropertyValue::U32Array(bytes) if bytes.len() >= 4 => {
                Some(u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
            }
            _ => None,
        })
    }

    /// Get property value as string
    #[must_use]
    pub fn prop_string(&self, name: &str) -> Option<&str> {
        self.find_property(name).and_then(|p| match &p.value {
            PropertyValue::String(s) => Some(*s),
            PropertyValue::StringList(list) if !list.is_empty() => Some(list[0]),
            _ => None,
        })
    }

    /// Get property value as u32 array
    #[must_use]
    pub fn prop_u32_array(&self, name: &str) -> Option<Vec<u32>> {
        self.find_property(name).and_then(|p| match &p.value {
            PropertyValue::U32Array(bytes) => {
                let mut values = Vec::new();
                for chunk in bytes.chunks_exact(4) {
                    values.push(u32::from_be_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]));
                }
                Some(values)
            }
            PropertyValue::U32(val) => Some(vec![*val]),
            _ => None,
        })
    }

    /// Get property value as u64
    #[must_use]
    pub fn prop_u64(&self, name: &str) -> Option<u64> {
        self.find_property(name).and_then(|p| match &p.value {
            PropertyValue::U64(val) => Some(*val),
            PropertyValue::U64Array(bytes) if bytes.len() >= 8 => Some(u64::from_be_bytes([
                bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
            ])),
            _ => None,
        })
    }

    /// Get property value as bytes
    #[must_use]
    pub fn prop_bytes(&self, name: &str) -> Option<&[u8]> {
        self.find_property(name).and_then(|p| match &p.value {
            PropertyValue::Bytes(bytes) => Some(*bytes),
            _ => None,
        })
    }

    /// Check if property exists
    #[must_use]
    pub fn has_property(&self, name: &str) -> bool {
        self.find_property(name).is_some()
    }

    /// Get the number of address cells for this node.
    ///
    /// Returns the value of the `#address-cells` property, which specifies how many
    /// 32-bit cells are required to represent an address in child nodes. According
    /// to the device tree specification, this defaults to 2 if not specified.
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidAddressCells` if the property value is outside
    /// the valid range (1-4).
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(node: &DeviceTreeNode) -> Result<(), DtbError> {
    /// let address_cells = node.address_cells()?;
    /// println!("Address cells: {}", address_cells);
    /// # Ok(())
    /// # }
    /// ```
    pub fn address_cells(&self) -> Result<u32, DtbError> {
        match self.prop_u32("#address-cells") {
            Some(cells) => {
                if cells == 0 || cells > AddressSpec::MAX_ADDRESS_CELLS {
                    Err(DtbError::InvalidAddressCells(cells))
                } else {
                    Ok(cells)
                }
            }
            None => Ok(AddressSpec::DEFAULT_ADDRESS_CELLS), // Default to 2
        }
    }

    /// Get the number of size cells for this node.
    ///
    /// Returns the value of the `#size-cells` property, which specifies how many
    /// 32-bit cells are required to represent a size in child nodes. According
    /// to the device tree specification, this defaults to 1 if not specified.
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidSizeCells` if the property value is outside
    /// the valid range (0-4).
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(node: &DeviceTreeNode) -> Result<(), DtbError> {
    /// let size_cells = node.size_cells()?;
    /// println!("Size cells: {}", size_cells);
    /// # Ok(())
    /// # }
    /// ```
    pub fn size_cells(&self) -> Result<u32, DtbError> {
        match self.prop_u32("#size-cells") {
            Some(cells) => {
                if cells > AddressSpec::MAX_SIZE_CELLS {
                    Err(DtbError::InvalidSizeCells(cells))
                } else {
                    Ok(cells)
                }
            }
            None => Ok(AddressSpec::DEFAULT_SIZE_CELLS), // Default to 1
        }
    }

    /// Get the number of address cells for child nodes, with parent inheritance.
    ///
    /// This method searches for `#address-cells` property in this node first,
    /// then falls back to the parent node if not found, following the device
    /// tree specification for property inheritance.
    ///
    /// # Arguments
    ///
    /// * `parent` - Optional parent node for inheritance fallback
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidAddressCells` if the property value is outside
    /// the valid range (1-4).
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(node: &DeviceTreeNode, parent: Option<&DeviceTreeNode>) -> Result<(), DtbError> {
    /// let address_cells = node.address_cells_with_parent(parent)?;
    /// println!("Address cells: {}", address_cells);
    /// # Ok(())
    /// # }
    /// ```
    pub fn address_cells_with_parent(
        &self,
        parent: Option<&DeviceTreeNode<'a>>,
    ) -> Result<u32, DtbError> {
        // First check this node
        if let Some(cells) = self.prop_u32("#address-cells") {
            if cells == 0 || cells > AddressSpec::MAX_ADDRESS_CELLS {
                return Err(DtbError::InvalidAddressCells(cells));
            }
            return Ok(cells);
        }

        // Then check parent node
        if let Some(parent_node) = parent {
            if let Some(cells) = parent_node.prop_u32("#address-cells") {
                if cells == 0 || cells > AddressSpec::MAX_ADDRESS_CELLS {
                    return Err(DtbError::InvalidAddressCells(cells));
                }
                return Ok(cells);
            }
        }

        // Default fallback
        Ok(AddressSpec::DEFAULT_ADDRESS_CELLS)
    }

    /// Get the number of size cells for child nodes, with parent inheritance.
    ///
    /// This method searches for `#size-cells` property in this node first,
    /// then falls back to the parent node if not found, following the device
    /// tree specification for property inheritance.
    ///
    /// # Arguments
    ///
    /// * `parent` - Optional parent node for inheritance fallback
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidSizeCells` if the property value is outside
    /// the valid range (0-4).
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(node: &DeviceTreeNode, parent: Option<&DeviceTreeNode>) -> Result<(), DtbError> {
    /// let size_cells = node.size_cells_with_parent(parent)?;
    /// println!("Size cells: {}", size_cells);
    /// # Ok(())
    /// # }
    /// ```
    pub fn size_cells_with_parent(
        &self,
        parent: Option<&DeviceTreeNode<'a>>,
    ) -> Result<u32, DtbError> {
        // First check this node
        if let Some(cells) = self.prop_u32("#size-cells") {
            if cells > AddressSpec::MAX_SIZE_CELLS {
                return Err(DtbError::InvalidSizeCells(cells));
            }
            return Ok(cells);
        }

        // Then check parent node
        if let Some(parent_node) = parent {
            if let Some(cells) = parent_node.prop_u32("#size-cells") {
                if cells > AddressSpec::MAX_SIZE_CELLS {
                    return Err(DtbError::InvalidSizeCells(cells));
                }
                return Ok(cells);
            }
        }

        // Default fallback
        Ok(AddressSpec::DEFAULT_SIZE_CELLS)
    }

    /// Creates an `AddressSpec` for this node using proper inheritance rules.
    ///
    /// This is a convenience method that combines `address_cells` and `size_cells`
    /// with parent inheritance support to create a validated `AddressSpec`.
    ///
    /// # Arguments
    ///
    /// * `parent` - Optional parent node for inheritance fallback
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidAddressCells` or `DtbError::InvalidSizeCells`
    /// if the property values are outside valid ranges.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(node: &DeviceTreeNode, parent: Option<&DeviceTreeNode>) -> Result<(), DtbError> {
    /// let spec = node.create_address_spec(parent)?;
    /// println!("Address spec: {}+{} cells", spec.address_cells(), spec.size_cells());
    /// # Ok(())
    /// # }
    /// ```
    pub fn create_address_spec(
        &self,
        parent: Option<&DeviceTreeNode<'a>>,
    ) -> Result<AddressSpec, DtbError> {
        let address_cells = self.address_cells_with_parent(parent)?;
        let size_cells = self.size_cells_with_parent(parent)?;
        AddressSpec::new(address_cells, size_cells)
    }

    /// Parse the `ranges` property to extract address range mappings.
    ///
    /// The `ranges` property describes the mapping between child and parent address
    /// spaces. Each entry contains child address, parent address, and size fields.
    /// The number of cells for each field is determined by the node's cell properties.
    ///
    /// An empty `ranges` property indicates a 1:1 mapping between child and parent
    /// address spaces.
    ///
    /// # Arguments
    ///
    /// * `parent` - Optional parent node for cell inheritance
    /// * `child_address_cells` - Number of cells for child addresses (from this node)
    ///
    /// # Errors
    ///
    /// Returns `DtbError::InvalidRangesFormat` if the ranges data is malformed.
    /// Returns cell validation errors if address/size cell values are invalid.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(node: &DeviceTreeNode, parent: Option<&DeviceTreeNode>) -> Result<(), DtbError> {
    /// let ranges = node.ranges(parent, 2)?;
    ///
    /// for range in &ranges {
    ///     println!("Range: child=0x{:x} -> parent=0x{:x}, size=0x{:x}",
    ///         range.child_address(), range.parent_address(), range.size());
    /// }
    ///
    /// // Check if empty (1:1 mapping)
    /// if ranges.is_empty() {
    ///     println!("1:1 address mapping");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn ranges(
        &self,
        parent: Option<&DeviceTreeNode<'a>>,
        child_address_cells: u32,
    ) -> Result<Vec<AddressRange>, DtbError> {
        // Get the raw ranges property data
        let ranges_data = match self.find_property("ranges") {
            Some(prop) => match &prop.value {
                PropertyValue::Bytes(data) | PropertyValue::U32Array(data) => *data,
                PropertyValue::Empty => {
                    // Empty ranges property means 1:1 mapping
                    return Ok(Vec::new());
                }
                _ => return Err(DtbError::InvalidRangesFormat),
            },
            None => {
                // No ranges property means this node doesn't provide address translation
                return Ok(Vec::new());
            }
        };

        // Get address and size cells for parent (for parent address field)
        let parent_address_cells = self.address_cells_with_parent(parent)?;
        let parent_size_cells = self.size_cells_with_parent(parent)?;

        // Calculate the size of each range entry in bytes
        let child_addr_bytes = (child_address_cells * 4) as usize;
        let parent_addr_bytes = (parent_address_cells * 4) as usize;
        let size_bytes = (parent_size_cells * 4) as usize;
        let entry_size = child_addr_bytes + parent_addr_bytes + size_bytes;

        // Validate that the data size is a multiple of entry size
        if ranges_data.len() % entry_size != 0 {
            return Err(DtbError::InvalidRangesFormat);
        }

        let mut ranges = Vec::new();
        let mut offset = 0;

        while offset + entry_size <= ranges_data.len() {
            // Parse child address
            let child_address = parse_address_from_bytes(
                &ranges_data[offset..offset + child_addr_bytes],
                child_address_cells,
            )?;
            offset += child_addr_bytes;

            // Parse parent address
            let parent_address = parse_address_from_bytes(
                &ranges_data[offset..offset + parent_addr_bytes],
                parent_address_cells,
            )?;
            offset += parent_addr_bytes;

            // Parse size
            let size = parse_address_from_bytes(
                &ranges_data[offset..offset + size_bytes],
                parent_size_cells,
            )?;
            offset += size_bytes;

            // Create and validate the address range
            let range = AddressRange::new(child_address, parent_address, size)?;
            ranges.push(range);
        }

        Ok(ranges)
    }

    /// Translate a child address to the parent address space.
    ///
    /// This method performs single-level address translation by finding the
    /// appropriate range in this node's `ranges` property and translating
    /// the child address to the parent address space.
    ///
    /// # Arguments
    ///
    /// * `child_address` - Address in this node's address space to translate
    /// * `parent` - Optional parent node for cell inheritance
    /// * `child_address_cells` - Number of cells for child addresses
    ///
    /// # Errors
    ///
    /// Returns `DtbError::AddressTranslationError` if:
    /// - No matching range is found for the address
    /// - The address is outside all defined ranges
    /// - Address arithmetic would overflow
    ///
    /// Returns other errors for cell validation or ranges parsing failures.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(bus_node: &DeviceTreeNode, parent: Option<&DeviceTreeNode>) -> Result<(), DtbError> {
    /// // Translate device address 0x1000 to parent bus address space
    /// let parent_addr = bus_node.translate_address(0x1000, parent, 2)?;
    /// println!("Child address 0x1000 maps to parent address 0x{:x}", parent_addr);
    ///
    /// // If no ranges property exists, returns AddressTranslationError
    /// # Ok(())
    /// # }
    /// ```
    pub fn translate_address(
        &self,
        child_address: u64,
        parent: Option<&DeviceTreeNode<'a>>,
        child_address_cells: u32,
    ) -> Result<u64, DtbError> {
        // Get the ranges for this node
        let ranges = self.ranges(parent, child_address_cells)?;

        // If ranges is empty, this could mean:
        // 1. Empty ranges property (1:1 mapping) - translate directly
        // 2. No ranges property - no translation capability
        if ranges.is_empty() {
            // Check if ranges property exists but is empty (1:1 mapping)
            if self.has_property("ranges") {
                // Empty ranges property means 1:1 address mapping
                return Ok(child_address);
            }
            // No ranges property means this node doesn't provide translation
            return Err(DtbError::AddressTranslationError(child_address));
        }

        // Find the range that contains the child address
        for range in &ranges {
            if range.contains(child_address) {
                return range.translate(child_address);
            }
        }

        // No matching range found
        Err(DtbError::AddressTranslationError(child_address))
    }

    /// Translate an address through multiple levels of the device tree hierarchy.
    ///
    /// This method performs recursive address translation by walking up the device tree
    /// from the current node to the root, applying address translations at each level.
    /// It includes cycle detection and depth limits to prevent infinite recursion.
    ///
    /// # Arguments
    ///
    /// * `child_address` - Address in this node's address space to translate
    /// * `child_address_cells` - Number of cells for child addresses
    /// * `max_depth` - Maximum recursion depth (typically 10)
    ///
    /// # Errors
    ///
    /// Returns `DtbError::TranslationCycle` if a circular reference is detected.
    /// Returns `DtbError::MaxTranslationDepthExceeded` if recursion exceeds max_depth.
    /// Returns other translation errors for individual translation failures.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(device_node: &DeviceTreeNode) -> Result<(), DtbError> {
    /// // Translate address through complete bus hierarchy to CPU address space
    /// let cpu_addr = device_node.translate_address_recursive(0x1000, 2, 10)?;
    /// println!("Device address 0x1000 maps to CPU address 0x{:x}", cpu_addr);
    /// # Ok(())
    /// # }
    /// ```
    pub fn translate_address_recursive(
        &self,
        child_address: u64,
        child_address_cells: u32,
        max_depth: u32,
    ) -> Result<u64, DtbError> {
        self.translate_address_recursive_internal(
            child_address,
            child_address_cells,
            max_depth,
            &mut Vec::new(),
            0,
        )
    }

    /// Internal implementation of recursive address translation with cycle detection.
    ///
    /// This method maintains a visited nodes list to detect cycles and tracks
    /// recursion depth to prevent stack overflow.
    fn translate_address_recursive_internal(
        &self,
        mut current_address: u64,
        child_address_cells: u32,
        max_depth: u32,
        visited_nodes: &mut Vec<*const DeviceTreeNode<'a>>,
        current_depth: u32,
    ) -> Result<u64, DtbError> {
        // Check recursion depth limit
        if current_depth >= max_depth {
            return Err(DtbError::MaxTranslationDepthExceeded);
        }

        // Check for cycles using pointer comparison
        let self_ptr = self as *const DeviceTreeNode<'a>;
        if visited_nodes.contains(&self_ptr) {
            return Err(DtbError::TranslationCycle);
        }
        visited_nodes.push(self_ptr);

        // Find the parent node by traversing up the tree
        // Note: This is a simplified implementation. In a real device tree parser,
        // you would have parent references or a tree structure that allows upward traversal.
        // For now, we'll implement translation within the current node and assume
        // the caller provides the proper hierarchy context.

        // Try to translate at current level
        // If no ranges property exists, we've reached the root address space
        if !self.has_property("ranges") {
            // No more translation needed - we're at the root address space
            visited_nodes.pop();
            return Ok(current_address);
        }

        // Perform single-level translation at this node
        let parent_node: Option<&DeviceTreeNode<'a>> = None; // Would need parent reference
        match self.translate_address(current_address, parent_node, child_address_cells) {
            Ok(translated_address) => {
                current_address = translated_address;

                // If we successfully translated and have ranges, this is NOT the root.
                // In a complete implementation, we would continue recursively up the tree.
                // For now, we'll return the translated address.
                visited_nodes.pop();
                Ok(current_address)
            }
            Err(DtbError::AddressTranslationError(_)) => {
                // If translation fails and we have empty ranges (1:1 mapping)
                if self.has_property("ranges") {
                    if let Some(ranges_prop) = self.find_property("ranges") {
                        if matches!(ranges_prop.value, PropertyValue::Empty) {
                            // Empty ranges means 1:1 mapping, continue to parent
                            visited_nodes.pop();
                            return Ok(current_address);
                        }
                    }
                }
                visited_nodes.pop();
                Err(DtbError::AddressTranslationError(current_address))
            }
            Err(e) => {
                visited_nodes.pop();
                Err(e)
            }
        }
    }

    /// Translate addresses from device register property.
    ///
    /// Convenience method that extracts addresses from the `reg` property and
    /// translates them to the parent address space. Useful for getting CPU-visible
    /// addresses for device registers.
    ///
    /// # Arguments
    ///
    /// * `parent` - Optional parent node for cell inheritance
    ///
    /// # Errors
    ///
    /// Returns `DtbError` if reg property is malformed or translation fails.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(device_node: &DeviceTreeNode) -> Result<(), DtbError> {
    /// // Get translated device register addresses
    /// let addresses = device_node.translate_reg_addresses(None)?;
    /// for (addr, size) in addresses {
    ///     println!("Register: 0x{:x} (size: {})", addr, size);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn translate_reg_addresses(
        &self,
        parent: Option<&DeviceTreeNode<'a>>,
    ) -> Result<Vec<(u64, u64)>, DtbError> {
        let mut addresses = Vec::new();

        if let Some(reg) = self.prop_u32_array("reg") {
            let address_cells = self.address_cells_with_parent(parent)?;
            let size_cells = self.size_cells_with_parent(parent)?;
            let entry_size = (address_cells + size_cells) as usize;

            let mut i = 0;
            while i + entry_size <= reg.len() {
                // Parse address
                let mut address = 0u64;
                for j in 0..address_cells as usize {
                    address = (address << 32) | u64::from(reg[i + j]);
                }

                // Parse size
                let mut size = 0u64;
                for j in 0..size_cells as usize {
                    size = (size << 32) | u64::from(reg[i + address_cells as usize + j]);
                }

                // Translate address
                let translated_address = self
                    .translate_address(address, parent, address_cells)
                    .unwrap_or(address); // Fall back to original if translation fails

                addresses.push((translated_address, size));
                i += entry_size;
            }
        }

        Ok(addresses)
    }

    /// Get memory-mapped I/O regions for this device with address translation.
    ///
    /// Convenience method that combines register address parsing and translation
    /// to provide CPU-visible MMIO regions for this device.
    ///
    /// # Arguments
    ///
    /// * `parent` - Optional parent node for cell inheritance
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use device_tree_parser::{DeviceTreeNode, DtbError};
    /// # fn example(uart_node: &DeviceTreeNode) -> Result<(), DtbError> {
    /// let mmio_regions = uart_node.mmio_regions(None)?;
    /// for (addr, size) in mmio_regions {
    ///     println!("UART MMIO: 0x{:x} - 0x{:x}", addr, addr + size - 1);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn mmio_regions(
        &self,
        parent: Option<&DeviceTreeNode<'a>>,
    ) -> Result<Vec<(u64, u64)>, DtbError> {
        self.translate_reg_addresses(parent)
    }

    /// Get all nodes with a specific property
    #[must_use]
    pub fn find_nodes_with_property(&self, property_name: &str) -> Vec<&DeviceTreeNode<'a>> {
        let mut nodes = Vec::new();
        self.collect_nodes_with_property(property_name, &mut nodes);
        nodes
    }

    /// Recursively collect nodes with a specific property
    fn collect_nodes_with_property<'b>(
        &'b self,
        property_name: &str,
        nodes: &mut Vec<&'b DeviceTreeNode<'a>>,
    ) {
        if self.has_property(property_name) {
            nodes.push(self);
        }

        for child in &self.children {
            child.collect_nodes_with_property(property_name, nodes);
        }
    }

    /// Get all nodes with a specific compatible string
    #[must_use]
    pub fn find_compatible_nodes(&self, compatible: &str) -> Vec<&DeviceTreeNode<'a>> {
        let mut nodes = Vec::new();
        self.collect_compatible_nodes(compatible, &mut nodes);
        nodes
    }

    /// Recursively collect nodes with a specific compatible string
    fn collect_compatible_nodes<'b>(
        &'b self,
        compatible: &str,
        nodes: &mut Vec<&'b DeviceTreeNode<'a>>,
    ) {
        if let Some(compat_prop) = self.find_property("compatible") {
            match &compat_prop.value {
                PropertyValue::String(s) if *s == compatible => {
                    nodes.push(self);
                }
                PropertyValue::StringList(list) if list.contains(&compatible) => {
                    nodes.push(self);
                }
                _ => {}
            }
        }

        for child in &self.children {
            child.collect_compatible_nodes(compatible, nodes);
        }
    }

    /// Get iterator over all nodes (depth-first traversal)
    #[must_use]
    pub fn iter_nodes(&self) -> NodeIterator<'a, '_> {
        NodeIterator::new(self)
    }

    /// Get iterator over all properties
    pub fn iter_properties(&self) -> core::slice::Iter<'_, Property<'a>> {
        self.properties.iter()
    }

    /// Get iterator over child nodes
    pub fn iter_children(&self) -> core::slice::Iter<'_, DeviceTreeNode<'a>> {
        self.children.iter()
    }
}

// Trait implementations for better UX

/// Index trait for property access by name
impl<'a> Index<&str> for DeviceTreeNode<'a> {
    type Output = Property<'a>;

    fn index(&self, property_name: &str) -> &Self::Output {
        self.find_property(property_name)
            .unwrap_or_else(|| panic!("Property '{property_name}' not found"))
    }
}

/// Index trait for child access by index
impl<'a> Index<usize> for DeviceTreeNode<'a> {
    type Output = DeviceTreeNode<'a>;

    fn index(&self, index: usize) -> &Self::Output {
        &self.children[index]
    }
}

/// `IntoIterator` trait for iterating over child nodes
impl<'a> IntoIterator for &'a DeviceTreeNode<'a> {
    type Item = &'a DeviceTreeNode<'a>;
    type IntoIter = core::slice::Iter<'a, DeviceTreeNode<'a>>;

    fn into_iter(self) -> Self::IntoIter {
        self.children.iter()
    }
}

/// Display trait for `PropertyValue`
impl Display for PropertyValue<'_> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        match self {
            PropertyValue::Empty => write!(f, "<empty>"),
            PropertyValue::String(s) => write!(f, "\"{s}\""),
            PropertyValue::StringList(list) => {
                write!(f, "[")?;
                for (i, s) in list.iter().enumerate() {
                    if i > 0 {
                        write!(f, ", ")?;
                    }
                    write!(f, "\"{s}\"")?;
                }
                write!(f, "]")
            }
            PropertyValue::U32(val) => write!(f, "0x{val:x}"),
            PropertyValue::U32Array(bytes) => {
                write!(f, "[")?;
                for (i, chunk) in bytes.chunks_exact(4).enumerate() {
                    if i > 0 {
                        write!(f, ", ")?;
                    }
                    let val = u32::from_be_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]);
                    write!(f, "0x{val:x}")?;
                }
                write!(f, "]")
            }
            PropertyValue::U64(val) => write!(f, "0x{val:x}"),
            PropertyValue::U64Array(bytes) => {
                write!(f, "[")?;
                for (i, chunk) in bytes.chunks_exact(8).enumerate() {
                    if i > 0 {
                        write!(f, ", ")?;
                    }
                    let val = u64::from_be_bytes([
                        chunk[0], chunk[1], chunk[2], chunk[3], chunk[4], chunk[5], chunk[6],
                        chunk[7],
                    ]);
                    write!(f, "0x{val:x}")?;
                }
                write!(f, "]")
            }
            PropertyValue::Bytes(bytes) => {
                write!(f, "[")?;
                for (i, byte) in bytes.iter().enumerate() {
                    if i > 0 {
                        write!(f, ", ")?;
                    }
                    write!(f, "0x{byte:02x}")?;
                }
                write!(f, "]")
            }
        }
    }
}

/// Display trait for Property
impl Display for Property<'_> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "{} = {}", self.name, self.value)
    }
}

/// Display trait for `DeviceTreeNode`
impl Display for DeviceTreeNode<'_> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        self.fmt_with_indent(f, 0)
    }
}

impl DeviceTreeNode<'_> {
    fn fmt_with_indent(&self, f: &mut Formatter<'_>, indent: usize) -> fmt::Result {
        let indent_str = "  ".repeat(indent);

        if self.name.is_empty() {
            writeln!(f, "{indent_str}/ {{")?;
        } else {
            writeln!(f, "{indent_str}{} {{", self.name)?;
        }

        for property in &self.properties {
            writeln!(f, "{indent_str}  {property}")?;
        }

        for child in &self.children {
            child.fmt_with_indent(f, indent + 1)?;
        }

        writeln!(f, "{indent_str}}}")
    }
}

/// Default trait for `DeviceTreeNode`
impl Default for DeviceTreeNode<'_> {
    fn default() -> Self {
        Self {
            name: "",
            properties: Vec::new(),
            children: Vec::new(),
        }
    }
}

/// Default trait for `PropertyValue`
impl Default for PropertyValue<'_> {
    fn default() -> Self {
        PropertyValue::Empty
    }
}

/// `TryFrom` trait for converting `PropertyValue` to u32
impl<'a> TryFrom<&PropertyValue<'a>> for u32 {
    type Error = DtbError;

    fn try_from(value: &PropertyValue<'a>) -> Result<Self, Self::Error> {
        match value {
            PropertyValue::U32(val) => Ok(*val),
            PropertyValue::U32Array(bytes) if bytes.len() >= 4 => {
                Ok(u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
            }
            _ => Err(DtbError::InvalidToken),
        }
    }
}

/// `TryFrom` trait for converting `PropertyValue` to u64
impl<'a> TryFrom<&PropertyValue<'a>> for u64 {
    type Error = DtbError;

    fn try_from(value: &PropertyValue<'a>) -> Result<Self, Self::Error> {
        match value {
            PropertyValue::U64(val) => Ok(*val),
            PropertyValue::U64Array(bytes) if bytes.len() >= 8 => Ok(u64::from_be_bytes([
                bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
            ])),
            PropertyValue::U32(val) => Ok(u64::from(*val)),
            PropertyValue::U32Array(bytes) if bytes.len() >= 4 => {
                let val = u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
                Ok(u64::from(val))
            }
            _ => Err(DtbError::InvalidToken),
        }
    }
}

/// `TryFrom` trait for converting `PropertyValue` to &str
impl<'a> TryFrom<&PropertyValue<'a>> for &'a str {
    type Error = DtbError;

    fn try_from(value: &PropertyValue<'a>) -> Result<Self, Self::Error> {
        match value {
            PropertyValue::String(s) => Ok(*s),
            PropertyValue::StringList(list) if !list.is_empty() => Ok(list[0]),
            _ => Err(DtbError::InvalidToken),
        }
    }
}

/// `TryFrom` trait for converting `PropertyValue` to `Vec<u32>`
impl<'a> TryFrom<&PropertyValue<'a>> for Vec<u32> {
    type Error = DtbError;

    fn try_from(value: &PropertyValue<'a>) -> Result<Self, Self::Error> {
        match value {
            PropertyValue::U32Array(bytes) => {
                let mut values = Vec::new();
                for chunk in bytes.chunks_exact(4) {
                    values.push(u32::from_be_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]));
                }
                Ok(values)
            }
            PropertyValue::U32(val) => Ok(vec![*val]),
            _ => Err(DtbError::InvalidToken),
        }
    }
}

/// `TryFrom` trait for converting `PropertyValue` to &[u8]
impl<'a> TryFrom<&PropertyValue<'a>> for &'a [u8] {
    type Error = DtbError;

    fn try_from(value: &PropertyValue<'a>) -> Result<Self, Self::Error> {
        match value {
            PropertyValue::Bytes(bytes)
            | PropertyValue::U32Array(bytes)
            | PropertyValue::U64Array(bytes) => Ok(*bytes),
            _ => Err(DtbError::InvalidToken),
        }
    }
}

/// Iterator for depth-first traversal of device tree nodes
pub struct NodeIterator<'a, 'b> {
    stack: Vec<&'b DeviceTreeNode<'a>>,
}

impl<'a, 'b> NodeIterator<'a, 'b> {
    fn new(root: &'b DeviceTreeNode<'a>) -> Self {
        Self { stack: vec![root] }
    }
}

impl<'a, 'b> Iterator for NodeIterator<'a, 'b> {
    type Item = &'b DeviceTreeNode<'a>;

    fn next(&mut self) -> Option<Self::Item> {
        if let Some(node) = self.stack.pop() {
            // Add children to stack in reverse order for depth-first traversal
            for child in node.children.iter().rev() {
                self.stack.push(child);
            }
            Some(node)
        } else {
            None
        }
    }
}

/// Parse a multi-cell address value from big-endian bytes.
///
/// Device tree addresses can be 1-4 cells (4-16 bytes). This function
/// handles variable cell sizes and converts to a 64-bit address value.
///
/// # Arguments
///
/// * `bytes` - Raw bytes containing the address (must be 4*cells bytes)
/// * `cells` - Number of 32-bit cells (1-4)
///
/// # Errors
///
/// Returns `DtbError::InvalidAddressCells` if cells is not in range 1-4.
/// Returns `DtbError::MalformedHeader` if bytes length doesn't match cells.
///
/// # Examples
///
/// ```rust
/// # use device_tree_parser::DtbError;
/// # fn example() -> Result<(), DtbError> {
/// # use device_tree_parser::parse_address_from_bytes;
/// // Parse 2-cell address (8 bytes)
/// let bytes = [0x00, 0x00, 0x00, 0x10, 0x80, 0x00, 0x00, 0x00];
/// let addr = parse_address_from_bytes(&bytes, 2)?;
/// assert_eq!(addr, 0x1080000000);
/// # Ok(())
/// # }
/// ```
pub fn parse_address_from_bytes(bytes: &[u8], cells: u32) -> Result<u64, DtbError> {
    let expected_len = (cells * 4) as usize;
    if bytes.len() != expected_len {
        return Err(DtbError::MalformedHeader);
    }

    match cells {
        1 => {
            // 1 cell = 32-bit address
            let addr = u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
            Ok(u64::from(addr))
        }
        2 => {
            // 2 cells = 64-bit address
            Ok(u64::from_be_bytes([
                bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
            ]))
        }
        3 => {
            // 3 cells = 96-bit address (use lower 64 bits)
            Ok(u64::from_be_bytes([
                bytes[4], bytes[5], bytes[6], bytes[7], bytes[8], bytes[9], bytes[10], bytes[11],
            ]))
        }
        4 => {
            // 4 cells = 128-bit address (use lower 64 bits)
            Ok(u64::from_be_bytes([
                bytes[8], bytes[9], bytes[10], bytes[11], bytes[12], bytes[13], bytes[14],
                bytes[15],
            ]))
        }
        _ => Err(DtbError::InvalidAddressCells(cells)),
    }
}

/// Parse a null-terminated string from bytes
///
/// # Errors
///
/// Returns `DtbError::MalformedHeader` if no null terminator is found
/// or if the string contains invalid UTF-8.
pub fn parse_null_terminated_string(input: &[u8]) -> Result<(&[u8], &str), DtbError> {
    let null_pos = input
        .iter()
        .position(|&b| b == 0)
        .ok_or(DtbError::MalformedHeader)?;

    let string_bytes = &input[..null_pos];
    let string = core::str::from_utf8(string_bytes).map_err(|_| DtbError::MalformedHeader)?;

    Ok((&input[null_pos + 1..], string))
}

/// Parse node name after `FDT_BEGIN_NODE` token
///
/// # Errors
///
/// Returns `DtbError::MalformedHeader` if the node name is malformed.
pub fn parse_node_name(input: &[u8]) -> Result<(&[u8], &str), DtbError> {
    let (remaining, name) = parse_null_terminated_string(input)?;

    // Skip padding to 4-byte alignment
    let name_len = input.len() - remaining.len();
    let padding = DtbToken::calculate_padding(name_len);

    if remaining.len() < padding {
        return Err(DtbError::MalformedHeader);
    }

    Ok((&remaining[padding..], name))
}

/// Parse property data after `FDT_PROP` token
///
/// # Errors
///
/// Returns `DtbError::MalformedHeader` if input is too short or data is corrupted.
pub fn parse_property_data<'a>(
    input: &'a [u8],
    strings_block: &'a [u8],
) -> Result<(&'a [u8], Property<'a>), DtbError> {
    if input.len() < 8 {
        return Err(DtbError::MalformedHeader);
    }

    // Parse property length (4 bytes)
    let prop_len = u32::from_be_bytes([input[0], input[1], input[2], input[3]]) as usize;

    // Parse name offset (4 bytes)
    let name_offset = u32::from_be_bytes([input[4], input[5], input[6], input[7]]) as usize;

    // Skip the 8-byte header
    let remaining = &input[8..];

    if remaining.len() < prop_len {
        return Err(DtbError::MalformedHeader);
    }

    // Extract property data
    let prop_data = &remaining[..prop_len];

    // Calculate padding for 4-byte alignment
    let padding = DtbToken::calculate_padding(prop_len);
    let next_input = &remaining[prop_len + padding..];

    // Resolve property name from strings block
    let name = resolve_property_name(strings_block, name_offset)?;

    // Parse property value based on data
    let value = parse_property_value(prop_data);

    let property = Property { name, value };
    Ok((next_input, property))
}

/// Resolve property name from strings block using offset
fn resolve_property_name(strings_block: &[u8], offset: usize) -> Result<&str, DtbError> {
    if offset >= strings_block.len() {
        return Err(DtbError::MalformedHeader);
    }

    let string_data = &strings_block[offset..];
    let (_remaining, name) = parse_null_terminated_string(string_data)?;
    Ok(name)
}

/// Parse property value from raw bytes
fn parse_property_value(data: &[u8]) -> PropertyValue<'_> {
    if data.is_empty() {
        return PropertyValue::Empty;
    }

    // Try to parse as string(s) first
    if let Ok(string_value) = parse_as_strings(data) {
        return string_value;
    }

    // Try to parse as u32 array
    if data.len() % 4 == 0 && !data.is_empty() {
        // For single u32 value, parse it directly
        if data.len() == 4 {
            let value = u32::from_be_bytes([data[0], data[1], data[2], data[3]]);
            return PropertyValue::U32(value);
        }
        // Store raw bytes for arrays
        return PropertyValue::U32Array(data);
    }

    // Try to parse as u64 array
    if data.len() % 8 == 0 && !data.is_empty() {
        // For single u64 value, parse it directly
        if data.len() == 8 {
            let value = u64::from_be_bytes([
                data[0], data[1], data[2], data[3], data[4], data[5], data[6], data[7],
            ]);
            return PropertyValue::U64(value);
        }
        // Store raw bytes for arrays
        return PropertyValue::U64Array(data);
    }

    // Fall back to raw bytes
    PropertyValue::Bytes(data)
}

/// Try to parse data as string or string list
fn parse_as_strings(data: &[u8]) -> Result<PropertyValue<'_>, ()> {
    // Check if all bytes are valid UTF-8 or null
    if !data
        .iter()
        .all(|&b| b == 0 || (32..=126).contains(&b) || b == 9 || b == 10 || b == 13)
    {
        return Err(());
    }

    let mut strings = Vec::new();
    let mut start = 0;

    for (i, &byte) in data.iter().enumerate() {
        if byte == 0 {
            if start < i {
                let string_bytes = &data[start..i];
                if let Ok(s) = core::str::from_utf8(string_bytes) {
                    strings.push(s);
                } else {
                    return Err(());
                }
            }
            start = i + 1;
        }
    }

    // Handle case where last string doesn't end with null
    if start < data.len() {
        let string_bytes = &data[start..];
        if let Ok(s) = core::str::from_utf8(string_bytes) {
            strings.push(s);
        } else {
            return Err(());
        }
    }

    match strings.len() {
        0 => Ok(PropertyValue::Empty),
        1 => Ok(PropertyValue::String(strings[0])),
        _ => Ok(PropertyValue::StringList(strings)),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_device_tree_node_creation() {
        let node = DeviceTreeNode::new("test");
        assert_eq!(node.name, "test");
        assert!(node.properties.is_empty());
        assert!(node.children.is_empty());
    }

    #[test]
    fn test_parse_null_terminated_string() {
        let data = b"hello\0world";
        let result = parse_null_terminated_string(data);
        assert!(result.is_ok());
        let (remaining, string) = result.unwrap();
        assert_eq!(string, "hello");
        assert_eq!(remaining, b"world");
    }

    #[test]
    fn test_address_spec_creation() {
        // Valid specifications
        let spec1 = AddressSpec::new(2, 1).unwrap();
        assert_eq!(spec1.address_cells(), 2);
        assert_eq!(spec1.size_cells(), 1);
        assert_eq!(spec1.total_cells(), 3);

        let spec2 = AddressSpec::new(1, 2).unwrap();
        assert_eq!(spec2.address_cells(), 1);
        assert_eq!(spec2.size_cells(), 2);

        // Edge cases
        let spec_min = AddressSpec::new(1, 0).unwrap();
        assert_eq!(spec_min.address_cells(), 1);
        assert_eq!(spec_min.size_cells(), 0);

        let spec_max = AddressSpec::new(4, 4).unwrap();
        assert_eq!(spec_max.address_cells(), 4);
        assert_eq!(spec_max.size_cells(), 4);
    }

    #[test]
    fn test_address_spec_validation() {
        // Invalid address cells
        assert!(matches!(
            AddressSpec::new(0, 1),
            Err(DtbError::InvalidAddressCells(0))
        ));
        assert!(matches!(
            AddressSpec::new(5, 1),
            Err(DtbError::InvalidAddressCells(5))
        ));

        // Invalid size cells
        assert!(matches!(
            AddressSpec::new(2, 5),
            Err(DtbError::InvalidSizeCells(5))
        ));
    }

    #[test]
    fn test_address_spec_defaults() {
        let default_spec = AddressSpec::default();
        assert_eq!(default_spec.address_cells(), 2);
        assert_eq!(default_spec.size_cells(), 1);
        assert_eq!(default_spec.address_size_bytes(), 8);
        assert_eq!(default_spec.size_size_bytes(), 4);
        assert_eq!(default_spec.total_size_bytes(), 12);
    }

    #[test]
    fn test_address_spec_byte_calculations() {
        let spec = AddressSpec::new(3, 2).unwrap();
        assert_eq!(spec.address_size_bytes(), 12); // 3 cells * 4 bytes
        assert_eq!(spec.size_size_bytes(), 8); // 2 cells * 4 bytes
        assert_eq!(spec.total_size_bytes(), 20); // 5 cells * 4 bytes
    }

    #[test]
    fn test_parse_node_name() {
        let data = b"root\0\0\0\0next";
        let result = parse_node_name(data);
        assert!(result.is_ok());
        let (remaining, name) = result.unwrap();
        assert_eq!(name, "root");
        assert_eq!(remaining, b"next");
    }

    #[test]
    fn test_parse_property_value_u32() {
        let data = [0x12, 0x34, 0x56, 0x78];
        let value = parse_property_value(&data);
        assert_eq!(value, PropertyValue::U32(0x12345678));
    }

    #[test]
    fn test_parse_property_value_string() {
        let data = b"hello\0";
        let value = parse_property_value(data);
        match value {
            PropertyValue::String(s) => assert_eq!(s, "hello"),
            _ => panic!("Expected String value"),
        }
    }

    #[test]
    fn test_parse_property_value_empty() {
        let data = [];
        let value = parse_property_value(&data);
        assert_eq!(value, PropertyValue::Empty);
    }

    #[test]
    fn test_node_property_accessors() {
        let name1 = "test-u32";
        let name2 = "test-string";
        let value_str = "hello";
        let mut node = DeviceTreeNode::new("test");

        // Add u32 property
        node.add_property(Property {
            name: name1,
            value: PropertyValue::U32(42),
        });

        // Add string property
        node.add_property(Property {
            name: name2,
            value: PropertyValue::String(value_str),
        });

        assert_eq!(node.prop_u32("test-u32"), Some(42));
        assert_eq!(node.prop_string("test-string"), Some("hello"));
        assert_eq!(node.prop_u32("nonexistent"), None);
    }

    #[test]
    fn test_node_path_lookup() {
        let device_type = "device_type";
        let cpu_str = "cpu";
        let mut root = DeviceTreeNode::new("");
        let mut cpus = DeviceTreeNode::new("cpus");
        let mut cpu0 = DeviceTreeNode::new("cpu@0");

        cpu0.add_property(Property {
            name: device_type,
            value: PropertyValue::String(cpu_str),
        });

        cpus.add_child(cpu0);
        root.add_child(cpus);

        // Test root lookup
        assert!(root.find_node("/").is_some());
        assert!(root.find_node("").is_some());

        // Test path lookup
        assert!(root.find_node("/cpus").is_some());
        assert!(root.find_node("/cpus/cpu@0").is_some());
        assert!(root.find_node("/cpus/cpu").is_some()); // Should match cpu@0

        // Test non-existent path
        assert!(root.find_node("/nonexistent").is_none());
    }

    #[test]
    fn test_compatible_node_search() {
        let compatible = "compatible";
        let ns16550a = "ns16550a";
        let ns16550 = "ns16550";
        let mut root = DeviceTreeNode::new("");
        let mut uart1 = DeviceTreeNode::new("uart@1000");
        let mut uart2 = DeviceTreeNode::new("uart@2000");

        uart1.add_property(Property {
            name: compatible,
            value: PropertyValue::String(ns16550a),
        });

        uart2.add_property(Property {
            name: compatible,
            value: PropertyValue::StringList(vec![ns16550a, ns16550]),
        });

        root.add_child(uart1);
        root.add_child(uart2);

        let ns16550a_nodes = root.find_compatible_nodes("ns16550a");
        assert_eq!(ns16550a_nodes.len(), 2);

        let ns16550_nodes = root.find_compatible_nodes("ns16550");
        assert_eq!(ns16550_nodes.len(), 1);
    }

    #[test]
    fn test_node_iterator() {
        let mut root = DeviceTreeNode::new("");
        let mut child1 = DeviceTreeNode::new("child1");
        let child2 = DeviceTreeNode::new("child2");
        let grandchild = DeviceTreeNode::new("grandchild");

        child1.add_child(grandchild);
        root.add_child(child1);
        root.add_child(child2);

        let nodes: Vec<_> = root.iter_nodes().collect();
        assert_eq!(nodes.len(), 4); // root, child1, grandchild, child2

        // Check depth-first order
        assert_eq!(nodes[0].name, "");
        assert_eq!(nodes[1].name, "child1");
        assert_eq!(nodes[2].name, "grandchild");
        assert_eq!(nodes[3].name, "child2");
    }

    #[test]
    fn test_property_types() {
        let u32_prop = "u32-prop";
        let u64_prop = "u64-prop";
        let bytes_prop = "bytes-prop";
        let empty_prop = "empty-prop";
        let bytes_data = &[1u8, 2, 3, 4];
        let mut node = DeviceTreeNode::new("test");

        // Add various property types
        node.add_property(Property {
            name: u32_prop,
            value: PropertyValue::U32(42),
        });

        node.add_property(Property {
            name: u64_prop,
            value: PropertyValue::U64(0x123456789),
        });

        node.add_property(Property {
            name: bytes_prop,
            value: PropertyValue::Bytes(bytes_data),
        });

        node.add_property(Property {
            name: empty_prop,
            value: PropertyValue::Empty,
        });

        assert_eq!(node.prop_u32("u32-prop"), Some(42));
        assert_eq!(node.prop_u64("u64-prop"), Some(0x123456789));
        assert_eq!(node.prop_bytes("bytes-prop"), Some(&[1, 2, 3, 4][..]));
        assert!(node.has_property("empty-prop"));
        assert!(!node.has_property("nonexistent"));
    }

    #[test]
    fn test_ergonomic_traits() {
        use core::convert::TryFrom;

        let mut node = DeviceTreeNode::new("test");
        let mut child = DeviceTreeNode::new("child");

        // Add properties to test Index and TryFrom traits
        node.add_property(Property {
            name: "test-u32",
            value: PropertyValue::U32(42),
        });

        node.add_property(Property {
            name: "test-string",
            value: PropertyValue::String("hello"),
        });

        child.add_property(Property {
            name: "child-prop",
            value: PropertyValue::U32(100),
        });

        node.add_child(child);

        // Test Index trait for property access
        assert_eq!(node["test-u32"].name, "test-u32");
        assert_eq!(node["test-string"].name, "test-string");

        // Test Index trait for child access
        assert_eq!(node[0].name, "child");

        // Test IntoIterator trait
        let mut child_count = 0;
        for child in &node {
            child_count += 1;
            assert_eq!(child.name, "child");
        }
        assert_eq!(child_count, 1);

        // Test TryFrom trait
        let u32_val: u32 = u32::try_from(&node["test-u32"].value).unwrap();
        assert_eq!(u32_val, 42);

        let str_val: &str = <&str>::try_from(&node["test-string"].value).unwrap();
        assert_eq!(str_val, "hello");

        // Test Default trait
        let default_node = DeviceTreeNode::default();
        assert_eq!(default_node.name, "");
        assert!(default_node.properties.is_empty());
        assert!(default_node.children.is_empty());

        let default_value = PropertyValue::default();
        assert_eq!(default_value, PropertyValue::Empty);
    }

    #[test]
    fn test_address_cells_parsing() {
        // Test node with explicit #address-cells property
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });

        assert_eq!(node.address_cells().unwrap(), 2);

        // Test with invalid address cells (0)
        let mut invalid_node = DeviceTreeNode::new("test");
        invalid_node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(0),
        });

        assert!(matches!(
            invalid_node.address_cells(),
            Err(DtbError::InvalidAddressCells(0))
        ));

        // Test with invalid address cells (too high)
        let mut invalid_node2 = DeviceTreeNode::new("test");
        invalid_node2.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(5),
        });

        assert!(matches!(
            invalid_node2.address_cells(),
            Err(DtbError::InvalidAddressCells(5))
        ));

        // Test default value when property is missing
        let empty_node = DeviceTreeNode::new("test");
        assert_eq!(
            empty_node.address_cells().unwrap(),
            AddressSpec::DEFAULT_ADDRESS_CELLS
        );
    }

    #[test]
    fn test_size_cells_parsing() {
        // Test node with explicit #size-cells property
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        assert_eq!(node.size_cells().unwrap(), 1);

        // Test with size cells = 0 (valid for address-only nodes)
        let mut zero_size_node = DeviceTreeNode::new("test");
        zero_size_node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(0),
        });

        assert_eq!(zero_size_node.size_cells().unwrap(), 0);

        // Test with invalid size cells (too high)
        let mut invalid_node = DeviceTreeNode::new("test");
        invalid_node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(5),
        });

        assert!(matches!(
            invalid_node.size_cells(),
            Err(DtbError::InvalidSizeCells(5))
        ));

        // Test default value when property is missing
        let empty_node = DeviceTreeNode::new("test");
        assert_eq!(
            empty_node.size_cells().unwrap(),
            AddressSpec::DEFAULT_SIZE_CELLS
        );
    }

    #[test]
    fn test_address_cells_with_parent_inheritance() {
        // Create parent node with #address-cells
        let mut parent = DeviceTreeNode::new("parent");
        parent.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(3),
        });

        // Create child node without #address-cells
        let child = DeviceTreeNode::new("child");

        // Test inheritance from parent
        assert_eq!(child.address_cells_with_parent(Some(&parent)).unwrap(), 3);

        // Test child with its own property overrides parent
        let mut child_with_prop = DeviceTreeNode::new("child");
        child_with_prop.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });

        assert_eq!(
            child_with_prop
                .address_cells_with_parent(Some(&parent))
                .unwrap(),
            1
        );

        // Test no parent fallback to default
        assert_eq!(
            child.address_cells_with_parent(None).unwrap(),
            AddressSpec::DEFAULT_ADDRESS_CELLS
        );

        // Test invalid value in parent
        let mut invalid_parent = DeviceTreeNode::new("parent");
        invalid_parent.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(0),
        });

        assert!(matches!(
            child.address_cells_with_parent(Some(&invalid_parent)),
            Err(DtbError::InvalidAddressCells(0))
        ));
    }

    #[test]
    fn test_size_cells_with_parent_inheritance() {
        // Create parent node with #size-cells
        let mut parent = DeviceTreeNode::new("parent");
        parent.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(2),
        });

        // Create child node without #size-cells
        let child = DeviceTreeNode::new("child");

        // Test inheritance from parent
        assert_eq!(child.size_cells_with_parent(Some(&parent)).unwrap(), 2);

        // Test child with its own property overrides parent
        let mut child_with_prop = DeviceTreeNode::new("child");
        child_with_prop.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(0),
        });

        assert_eq!(
            child_with_prop
                .size_cells_with_parent(Some(&parent))
                .unwrap(),
            0
        );

        // Test no parent fallback to default
        assert_eq!(
            child.size_cells_with_parent(None).unwrap(),
            AddressSpec::DEFAULT_SIZE_CELLS
        );
    }

    #[test]
    fn test_create_address_spec() {
        // Test creating AddressSpec from node properties
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        let spec = node.create_address_spec(None).unwrap();
        assert_eq!(spec.address_cells(), 2);
        assert_eq!(spec.size_cells(), 1);
        assert_eq!(spec.total_cells(), 3);

        // Test with parent inheritance
        let mut parent = DeviceTreeNode::new("parent");
        parent.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        parent.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(2),
        });

        let child = DeviceTreeNode::new("child");
        let spec_with_parent = child.create_address_spec(Some(&parent)).unwrap();
        assert_eq!(spec_with_parent.address_cells(), 1);
        assert_eq!(spec_with_parent.size_cells(), 2);

        // Test default values when no properties exist
        let empty_node = DeviceTreeNode::new("empty");
        let default_spec = empty_node.create_address_spec(None).unwrap();
        assert_eq!(
            default_spec.address_cells(),
            AddressSpec::DEFAULT_ADDRESS_CELLS
        );
        assert_eq!(default_spec.size_cells(), AddressSpec::DEFAULT_SIZE_CELLS);
    }

    #[test]
    fn test_address_range_creation() {
        // Test valid range creation
        let range = AddressRange::new(0x1000, 0x80001000, 0x1000).unwrap();
        assert_eq!(range.child_address(), 0x1000);
        assert_eq!(range.parent_address(), 0x80001000);
        assert_eq!(range.size(), 0x1000);
        assert_eq!(range.child_end(), 0x2000);
        assert_eq!(range.parent_end(), 0x80002000);

        // Test overflow detection in child address
        assert!(matches!(
            AddressRange::new(u64::MAX, 0x80000000, 1),
            Err(DtbError::AddressTranslationError(_))
        ));

        // Test overflow detection in parent address
        assert!(matches!(
            AddressRange::new(0x1000, u64::MAX, 1),
            Err(DtbError::AddressTranslationError(_))
        ));
    }

    #[test]
    fn test_address_range_contains() {
        let range = AddressRange::new(0x1000, 0x80001000, 0x1000).unwrap();

        // Test addresses within range
        assert!(range.contains(0x1000)); // Start
        assert!(range.contains(0x1500)); // Middle
        assert!(range.contains(0x1FFF)); // Just before end

        // Test addresses outside range
        assert!(!range.contains(0x2000)); // End (exclusive)
        assert!(!range.contains(0x500)); // Before start
        assert!(!range.contains(0x3000)); // After end
    }

    #[test]
    fn test_address_range_translation() {
        let range = AddressRange::new(0x1000, 0x80001000, 0x1000).unwrap();

        // Test valid translations
        assert_eq!(range.translate(0x1000).unwrap(), 0x80001000); // Start
        assert_eq!(range.translate(0x1500).unwrap(), 0x80001500); // Middle
        assert_eq!(range.translate(0x1FFF).unwrap(), 0x80001FFF); // Just before end

        // Test invalid translations (outside range)
        assert!(matches!(
            range.translate(0x500),
            Err(DtbError::AddressTranslationError(0x500))
        ));
        assert!(matches!(
            range.translate(0x2000),
            Err(DtbError::AddressTranslationError(0x2000))
        ));

        // Test edge case with maximum values
        let max_range = AddressRange::new(0x0, u64::MAX - 10, 10).unwrap();
        assert_eq!(max_range.translate(0x5).unwrap(), u64::MAX - 5);
    }

    #[test]
    fn test_parse_address_from_bytes() {
        // Test 1-cell address (32-bit)
        let bytes1 = [0x12, 0x34, 0x56, 0x78];
        let addr1 = parse_address_from_bytes(&bytes1, 1).unwrap();
        assert_eq!(addr1, 0x12345678);

        // Test 2-cell address (64-bit)
        let bytes2 = [0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0];
        let addr2 = parse_address_from_bytes(&bytes2, 2).unwrap();
        assert_eq!(addr2, 0x123456789ABCDEF0);

        // Test 3-cell address (uses lower 64 bits - second and third cells)
        let bytes3 = [
            0x00, 0x11, 0x22, 0x33, // First cell (ignored)
            0x44, 0x55, 0x66, 0x77, // Second cell
            0x88, 0x99, 0xAA, 0xBB, // Third cell
        ];
        let addr3 = parse_address_from_bytes(&bytes3, 3).unwrap();
        assert_eq!(addr3, 0x445566778899AABB);

        // Test 4-cell address (uses lower 64 bits)
        let bytes4 = [
            0x00, 0x11, 0x22, 0x33, // First cell (ignored)
            0x44, 0x55, 0x66, 0x77, // Second cell (ignored)
            0x88, 0x99, 0xAA, 0xBB, // Third cell
            0xCC, 0xDD, 0xEE, 0xFF, // Fourth cell
        ];
        let addr4 = parse_address_from_bytes(&bytes4, 4).unwrap();
        assert_eq!(addr4, 0x8899AABBCCDDEEFF);

        // Test invalid cell count - 0 cells should fail on length check
        assert!(matches!(
            parse_address_from_bytes(&bytes1, 0),
            Err(DtbError::MalformedHeader)
        ));
        // 5 cells with correct length should fail on the match
        let bytes5 = [0u8; 20]; // 5 cells * 4 bytes
        assert!(matches!(
            parse_address_from_bytes(&bytes5, 5),
            Err(DtbError::InvalidAddressCells(5))
        ));

        // Test invalid byte length
        assert!(matches!(
            parse_address_from_bytes(&bytes1[..3], 1),
            Err(DtbError::MalformedHeader)
        ));
    }

    #[test]
    fn test_ranges_parsing_empty_property() {
        // Test node with empty ranges property (1:1 mapping)
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Empty,
        });

        let ranges = node.ranges(None, 2).unwrap();
        assert!(ranges.is_empty());
    }

    #[test]
    fn test_ranges_parsing_no_property() {
        // Test node without ranges property
        let node = DeviceTreeNode::new("test");
        let ranges = node.ranges(None, 2).unwrap();
        assert!(ranges.is_empty());
    }

    #[test]
    fn test_ranges_parsing_with_data() {
        // Create a node with 2 address cells, 1 size cell
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data: child_addr(2 cells) + parent_addr(2 cells) + size(1 cell)
        // Range 1: child=0x0, parent=0x80000000, size=0x10000
        // Range 2: child=0x20000, parent=0x90000000, size=0x8000
        let ranges_data = vec![
            // Range 1: child address (0x0 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
            // Range 1: parent address (0x80000000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00,
            // Range 1: size (0x10000 as 1 cell)
            0x00, 0x01, 0x00, 0x00, // Range 2: child address (0x20000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00,
            // Range 2: parent address (0x90000000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x90, 0x00, 0x00, 0x00,
            // Range 2: size (0x8000 as 1 cell)
            0x00, 0x00, 0x80, 0x00,
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        let ranges = node.ranges(None, 2).unwrap();
        assert_eq!(ranges.len(), 2);

        // Check first range
        let range1 = &ranges[0];
        assert_eq!(range1.child_address(), 0x0);
        assert_eq!(range1.parent_address(), 0x80000000);
        assert_eq!(range1.size(), 0x10000);

        // Check second range
        let range2 = &ranges[1];
        assert_eq!(range2.child_address(), 0x20000);
        assert_eq!(range2.parent_address(), 0x90000000);
        assert_eq!(range2.size(), 0x8000);
    }

    #[test]
    fn test_ranges_parsing_invalid_format() {
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Invalid ranges data (not multiple of entry size)
        // Entry size should be 2+2+1 = 5 cells = 20 bytes
        let invalid_data = vec![0u8; 19]; // 19 bytes is not divisible by 20
        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&invalid_data),
        });

        assert!(matches!(
            node.ranges(None, 2),
            Err(DtbError::InvalidRangesFormat)
        ));
    }

    #[test]
    fn test_ranges_parsing_with_inheritance() {
        // Create parent node with different address/size cells
        let mut parent = DeviceTreeNode::new("parent");
        parent.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        parent.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create child node without cell properties (inherits from parent)
        let mut child = DeviceTreeNode::new("child");

        // Create ranges data: child_addr(2 cells) + parent_addr(1 cell) + size(1 cell)
        // Range: child=0x1000, parent=0x80000000, size=0x1000
        let ranges_data = vec![
            // Child address (0x1000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
            // Parent address (0x80000000 as 1 cell)
            0x80, 0x00, 0x00, 0x00, // Size (0x1000 as 1 cell)
            0x00, 0x00, 0x10, 0x00,
        ];

        child.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        let ranges = child.ranges(Some(&parent), 2).unwrap();
        assert_eq!(ranges.len(), 1);

        let range = &ranges[0];
        assert_eq!(range.child_address(), 0x1000);
        assert_eq!(range.parent_address(), 0x80000000);
        assert_eq!(range.size(), 0x1000);
    }

    #[test]
    fn test_translate_address_successful() {
        // Create a node with address translation ranges
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data: child_addr(2 cells) + parent_addr(2 cells) + size(1 cell)
        // Range: child=0x1000, parent=0x80001000, size=0x1000
        let ranges_data = vec![
            // Child address (0x1000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
            // Parent address (0x80001000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, // Size (0x1000 as 1 cell)
            0x00, 0x00, 0x10, 0x00,
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test successful translation
        let translated = node.translate_address(0x1500, None, 2).unwrap();
        assert_eq!(translated, 0x80001500);

        // Test translation at range boundary (start)
        let translated = node.translate_address(0x1000, None, 2).unwrap();
        assert_eq!(translated, 0x80001000);

        // Test translation at range boundary (end - 1)
        let translated = node.translate_address(0x1FFF, None, 2).unwrap();
        assert_eq!(translated, 0x80001FFF);
    }

    #[test]
    fn test_translate_address_no_matching_range() {
        // Create a node with address translation ranges
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data: child=0x1000, parent=0x80001000, size=0x1000
        let ranges_data = vec![
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, // child address
            0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, // parent address
            0x00, 0x00, 0x10, 0x00, // size
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test address outside range (below)
        assert!(matches!(
            node.translate_address(0x500, None, 2),
            Err(DtbError::AddressTranslationError(0x500))
        ));

        // Test address outside range (above)
        assert!(matches!(
            node.translate_address(0x3000, None, 2),
            Err(DtbError::AddressTranslationError(0x3000))
        ));
    }

    #[test]
    fn test_translate_address_empty_ranges() {
        // Create a node with empty ranges property (1:1 mapping)
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Empty,
        });

        // Test 1:1 translation
        let translated = node.translate_address(0x1234, None, 2).unwrap();
        assert_eq!(translated, 0x1234);

        let translated = node.translate_address(0x0, None, 2).unwrap();
        assert_eq!(translated, 0x0);
    }

    #[test]
    fn test_translate_address_no_ranges_property() {
        // Create a node without ranges property
        let node = DeviceTreeNode::new("test");

        // Should return error for no translation capability
        assert!(matches!(
            node.translate_address(0x1000, None, 2),
            Err(DtbError::AddressTranslationError(0x1000))
        ));
    }

    #[test]
    fn test_translate_address_multiple_ranges() {
        // Create a node with multiple address translation ranges
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data with multiple ranges:
        // Range 1: child=0x0, parent=0x80000000, size=0x10000
        // Range 2: child=0x20000, parent=0x90000000, size=0x8000
        let ranges_data = vec![
            // Range 1: child address (0x0 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
            // Range 1: parent address (0x80000000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00,
            // Range 1: size (0x10000 as 1 cell)
            0x00, 0x01, 0x00, 0x00, // Range 2: child address (0x20000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00,
            // Range 2: parent address (0x90000000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x90, 0x00, 0x00, 0x00,
            // Range 2: size (0x8000 as 1 cell)
            0x00, 0x00, 0x80, 0x00,
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test translation in first range
        let translated = node.translate_address(0x5000, None, 2).unwrap();
        assert_eq!(translated, 0x80005000);

        // Test translation in second range
        let translated = node.translate_address(0x24000, None, 2).unwrap();
        assert_eq!(translated, 0x90004000);

        // Test address between ranges (should fail)
        assert!(matches!(
            node.translate_address(0x15000, None, 2),
            Err(DtbError::AddressTranslationError(0x15000))
        ));
    }

    #[test]
    fn test_translate_address_with_parent_inheritance() {
        // Create parent node with address/size cells
        let mut parent = DeviceTreeNode::new("parent");
        parent.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        parent.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create child node that inherits parent's cells
        let mut child = DeviceTreeNode::new("child");

        // Create ranges data: child_addr(2 cells) + parent_addr(1 cell) + size(1 cell)
        // Range: child=0x1000, parent=0x80000000, size=0x1000
        let ranges_data = vec![
            // Child address (0x1000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
            // Parent address (0x80000000 as 1 cell)
            0x80, 0x00, 0x00, 0x00, // Size (0x1000 as 1 cell)
            0x00, 0x00, 0x10, 0x00,
        ];

        child.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test translation with parent inheritance
        let translated = child.translate_address(0x1500, Some(&parent), 2).unwrap();
        assert_eq!(translated, 0x80000500);
    }

    #[test]
    fn test_translate_address_boundary_conditions() {
        // Create a node with precise range boundaries
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data: child=0x1000, parent=0x2000, size=0x1000
        let ranges_data = vec![
            // Child address (0x1000 as 1 cell)
            0x00, 0x00, 0x10, 0x00, // Parent address (0x2000 as 1 cell)
            0x00, 0x00, 0x20, 0x00, // Size (0x1000 as 1 cell)
            0x00, 0x00, 0x10, 0x00,
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test exactly at start of range
        let translated = node.translate_address(0x1000, None, 1).unwrap();
        assert_eq!(translated, 0x2000);

        // Test exactly at end of range (inclusive)
        let translated = node.translate_address(0x1FFF, None, 1).unwrap();
        assert_eq!(translated, 0x2FFF);

        // Test one byte before range (should fail)
        assert!(matches!(
            node.translate_address(0xFFF, None, 1),
            Err(DtbError::AddressTranslationError(0xFFF))
        ));

        // Test one byte after range (should fail)
        assert!(matches!(
            node.translate_address(0x2000, None, 1),
            Err(DtbError::AddressTranslationError(0x2000))
        ));
    }

    #[test]
    fn test_translate_address_zero_offset() {
        // Test translation where child and parent addresses have zero offset
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data: child=0x1000, parent=0x1000, size=0x1000 (no translation)
        let ranges_data = vec![
            0x00, 0x00, 0x10, 0x00, // child address
            0x00, 0x00, 0x10, 0x00, // parent address (same as child)
            0x00, 0x00, 0x10, 0x00, // size
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        let translated = node.translate_address(0x1500, None, 1).unwrap();
        assert_eq!(translated, 0x1500); // No translation offset
    }

    #[test]
    fn test_translate_address_large_addresses() {
        // Test with large 64-bit addresses
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(2),
        });

        // Create ranges data with large addresses
        // child=0x100000000, parent=0x200000000, size=0x100000000
        let ranges_data = vec![
            // Child address (0x100000000 as 2 cells)
            0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
            // Parent address (0x200000000 as 2 cells)
            0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x00,
            // Size (0x100000000 as 2 cells)
            0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        let translated = node.translate_address(0x150000000, None, 2).unwrap();
        assert_eq!(translated, 0x250000000);
    }

    #[test]
    fn test_translate_address_recursive_basic() {
        // Test basic recursive translation functionality
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges data: child=0x1000, parent=0x80001000, size=0x1000
        let ranges_data = vec![
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, // child address
            0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, // parent address
            0x00, 0x00, 0x10, 0x00, // size
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test recursive translation
        let translated = node.translate_address_recursive(0x1500, 2, 10).unwrap();
        assert_eq!(translated, 0x80001500);
    }

    #[test]
    fn test_translate_address_recursive_no_ranges() {
        // Test recursive translation when no ranges property exists (root address space)
        let node = DeviceTreeNode::new("root");

        // Should return the original address unchanged
        let translated = node.translate_address_recursive(0x1000, 2, 10).unwrap();
        assert_eq!(translated, 0x1000);
    }

    #[test]
    fn test_translate_address_recursive_empty_ranges() {
        // Test recursive translation with empty ranges (1:1 mapping)
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Empty,
        });

        // Should return the original address unchanged
        let translated = node.translate_address_recursive(0x1234, 2, 10).unwrap();
        assert_eq!(translated, 0x1234);
    }

    #[test]
    fn test_translate_address_recursive_max_depth() {
        // Test that recursion depth limit is enforced
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges that would normally translate
        let ranges_data = vec![
            0x00, 0x00, 0x10, 0x00, // child address
            0x00, 0x00, 0x20, 0x00, // parent address
            0x00, 0x00, 0x10, 0x00, // size
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test with depth limit of 0 (should exceed immediately)
        assert!(matches!(
            node.translate_address_recursive(0x1500, 1, 0),
            Err(DtbError::MaxTranslationDepthExceeded)
        ));
    }

    #[test]
    fn test_translate_address_recursive_cycle_detection() {
        // Test cycle detection using a single node that references itself
        let mut node = DeviceTreeNode::new("self-referencing");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // The cycle detection will prevent infinite recursion on the same node
        // In this simplified implementation, we test with a call that would
        // attempt to visit the same node multiple times

        // Create a scenario where we have ranges but no matching address
        let ranges_data = vec![
            0x00, 0x00, 0x20, 0x00, // child address (0x2000)
            0x00, 0x00, 0x30, 0x00, // parent address (0x3000)
            0x00, 0x00, 0x10, 0x00, // size (0x1000)
        ];

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // This should fail with translation error since 0x1000 is not in the range
        assert!(matches!(
            node.translate_address_recursive(0x1000, 1, 10),
            Err(DtbError::AddressTranslationError(0x1000))
        ));
    }

    #[test]
    fn test_translate_address_recursive_invalid_ranges() {
        // Test recursive translation with invalid ranges data
        let mut node = DeviceTreeNode::new("test");
        node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create invalid ranges data (wrong size)
        let invalid_ranges_data = vec![0x00, 0x00, 0x10]; // Only 3 bytes, should be 12

        node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&invalid_ranges_data),
        });

        // Should fail with ranges format error
        assert!(matches!(
            node.translate_address_recursive(0x1000, 1, 10),
            Err(DtbError::InvalidRangesFormat)
        ));
    }

    #[test]
    fn test_translate_address_recursive_complex_scenario() {
        // Test a more complex scenario with successful translation
        let mut bus_node = DeviceTreeNode::new("bus");
        bus_node.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        bus_node.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Create ranges that map 0x1000-0x1FFF to 0x90001000-0x90001FFF
        let ranges_data = vec![
            // Child address (0x1000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
            // Parent address (0x90001000 as 2 cells)
            0x00, 0x00, 0x00, 0x00, 0x90, 0x00, 0x10, 0x00, // Size (0x1000 as 1 cell)
            0x00, 0x00, 0x10, 0x00,
        ];

        bus_node.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test successful recursive translation
        let translated = bus_node.translate_address_recursive(0x1800, 2, 10).unwrap();
        assert_eq!(translated, 0x90001800);

        // Test with address outside range
        assert!(matches!(
            bus_node.translate_address_recursive(0x3000, 2, 10),
            Err(DtbError::AddressTranslationError(0x3000))
        ));
    }

    #[test]
    fn test_translate_reg_addresses() {
        // Test the convenience method for translating reg addresses
        let mut device = DeviceTreeNode::new("device");
        device.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(2),
        });
        device.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Add reg property with device addresses
        let reg_data = vec![
            // First register: address=0x1000, size=0x100
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, // address (2 cells)
            0x00, 0x00, 0x01, 0x00, // size (1 cell)
            // Second register: address=0x2000, size=0x200
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x20, 0x00, // address (2 cells)
            0x00, 0x00, 0x02, 0x00, // size (1 cell)
        ];

        device.add_property(Property {
            name: "reg",
            value: PropertyValue::U32Array(&reg_data),
        });

        // Add ranges for translation
        let ranges_data = vec![
            // Map 0x1000-0x2FFF to 0x80001000-0x80002FFF
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, // child address
            0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, // parent address
            0x00, 0x00, 0x20, 0x00, // size (covers both registers)
        ];

        device.add_property(Property {
            name: "ranges",
            value: PropertyValue::Bytes(&ranges_data),
        });

        // Test address translation
        let addresses = device.translate_reg_addresses(None).unwrap();
        assert_eq!(addresses.len(), 2);

        // Check first register
        assert_eq!(addresses[0].0, 0x80001000); // translated address
        assert_eq!(addresses[0].1, 0x100); // size unchanged

        // Check second register
        assert_eq!(addresses[1].0, 0x80002000); // translated address
        assert_eq!(addresses[1].1, 0x200); // size unchanged
    }

    #[test]
    fn test_mmio_regions() {
        // Test the mmio_regions convenience method
        let mut device = DeviceTreeNode::new("uart");
        device.add_property(Property {
            name: "#address-cells",
            value: PropertyValue::U32(1),
        });
        device.add_property(Property {
            name: "#size-cells",
            value: PropertyValue::U32(1),
        });

        // Add reg property
        let reg_data = [
            0x00, 0x00, 0x10, 0x00, // address: 0x1000
            0x00, 0x00, 0x01, 0x00, // size: 0x100
        ];

        device.add_property(Property {
            name: "reg",
            value: PropertyValue::U32Array(&reg_data),
        });

        // Test without translation (no ranges property)
        let mmio = device.mmio_regions(None).unwrap();
        assert_eq!(mmio.len(), 1);
        assert_eq!(mmio[0].0, 0x1000);
        assert_eq!(mmio[0].1, 0x100);
    }

    #[test]
    fn test_translate_reg_addresses_no_reg() {
        // Test with device that has no reg property
        let device = DeviceTreeNode::new("device");
        let addresses = device.translate_reg_addresses(None).unwrap();
        assert!(addresses.is_empty());
    }
}