fdt-rs 0.4.5

A flattened device tree parser for embedded no-std environments
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

use core::mem::size_of;
use core::str::from_utf8;

use crate::prelude::*;

use crate::base::DevTree;
use crate::error::DevTreeError;
use crate::spec::Phandle;

use crate::error::Result;

#[cfg(doc)]
use crate::base::DevTreeProp;

pub trait PropReader<'dt> {
    type NodeType;

    /// Returns the buffer associtated with the property's data.
    #[doc(hidden)]
    fn propbuf(&self) -> &'dt [u8];

    /// Returns offset of this property's name in the device tree buffer.
    #[doc(hidden)]
    fn nameoff(&self) -> usize;

    #[doc(hidden)]
    fn fdt(&self) -> &DevTree<'dt>;

    /// Returns the name of the property within the device tree.
    #[inline]
    fn name(&self) -> Result<&'dt str> {
        let str_offset = self.fdt().off_dt_strings() + self.nameoff();
        let name = self.fdt().buf().read_bstring0(str_offset)?;
        Ok(from_utf8(name)?)
    }

    /// Returns the length of the property value within the device tree
    #[inline]
    #[must_use]
    fn length(&self) -> usize {
        self.propbuf().len()
    }

    /// Returns the node which this property is contained within.
    fn node(&self) -> Self::NodeType;

    /// Read a big-endian [`u32`] from the provided offset in this device tree property's value.
    /// Convert the read value into the machines' native [`u32`] format and return it.
    ///
    /// If an offset which would cause this read to access memory outside of this property's value
    /// an [`Err`] containing [`DevTreeError::InvalidOffset`] will be returned.
    #[inline]
    fn u32(&self, index: usize) -> Result<u32> {
        // Safety: propbuf is guaranteed aligned to u32
        // We'll read without re-checking alignment
        unsafe {
            self.propbuf()
                .unsafe_read_be_u32(index * size_of::<u32>())
                .or(Err(DevTreeError::InvalidOffset))
        }
    }

    /// Read a big-endian [`u64`] from the provided offset in this device tree property's value.
    /// Convert the read value into the machines' native [`u64`] format and return it.
    ///
    /// If an offset which would cause this read to access memory outside of this property's value
    /// an [`Err`] containing [`DevTreeError::InvalidOffset`] will be returned.
    #[inline]
    fn u64(&self, index: usize) -> Result<u64> {
        self.propbuf()
            .read_be_u64(index * size_of::<u64>())
            .or(Err(DevTreeError::InvalidOffset))
    }

    /// A Phandle is simply defined as a u32 value, as such this method performs the same action as
    /// [`self.u32`]
    #[inline]
    fn phandle(&self, index: usize) -> Result<Phandle> {
        // Safety: propbuf is guaranteed aligned to u32
        // We'll read without re-checking alignment
        unsafe {
            self.propbuf()
                .unsafe_read_be_u32(index * size_of::<Phandle>())
                .or(Err(DevTreeError::InvalidOffset))
        }
    }

    /// Returns the string property as a string if it can be parsed as one.
    /// # Safety
    ///
    /// See the safety note of [`PropReader::u32`]
    #[inline]
    fn str(&self) -> Result<&'dt str> {
        self.iter_str().next()?.ok_or(DevTreeError::ParseError)
    }

    /// Returns the property as a string fallible_iterator.
    /// # Safety
    ///
    /// See the safety note of [`PropReader::u32`]
    #[inline]
    fn iter_str(&self) -> StringPropIter<'dt> {
        StringPropIter::new(self.propbuf())
    }
    /// Returns this property's data as a raw slice
    ///
    /// # Safety
    ///
    /// See the safety note of [`PropReader::get_u32`]
    #[inline]
    fn raw(&self) -> &'dt [u8] {
        self.propbuf()
    }
}

use fallible_iterator::FallibleIterator;

#[derive(Debug, Clone)]
pub struct StringPropIter<'dt> {
    offset: usize,
    propbuf: &'dt [u8],
}

impl<'dt> StringPropIter<'dt> {
    fn new(propbuf: &'dt [u8]) -> Self {
        Self { propbuf, offset: 0 }
    }
}

impl<'dt> FallibleIterator for StringPropIter<'dt> {
    type Error = DevTreeError;
    type Item = &'dt str;

    fn next(&mut self) -> Result<Option<Self::Item>> {
        if self.offset == self.propbuf.len() {
            return Ok(None);
        }
        if self.offset > self.propbuf.len() {
            return Err(DevTreeError::InvalidOffset);
        }

        let u8_slice = self.propbuf.read_bstring0(self.offset)?;
        // Include null byte
        self.offset += u8_slice.len() + 1;
        Ok(Some(from_utf8(u8_slice)?))
    }
}