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 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
#![no_std] extern crate byteorder; extern crate memchr; //pub mod error; pub use node::NodeIterator; pub use property::PropertyIterator; mod header; mod memory_reserve_map; mod blob; mod property; mod node; mod stringlist; pub use property::{PropertyValue, IsValue}; use memory_reserve_map::MemoryReserveMap; use property::Property; use blob::Blob; use node::{Node, Subnodes}; /// An interface for parsing flat device trees from an in memory buffer. /// /// For the time being the interface is read only and '[no_std]' with no heap /// allocations so it is usefull in early kernels where no memory allocation is /// brought up yet. pub struct FDT<'buf> { blob: Blob<'buf> } impl<'buf> FDT<'buf> { /// Creates a new FDT from a raw pointer. /// /// This method will also sanity check the data pointed to by the raw pointer /// to determine whether the data is a device tree and of a compatible version. /// /// # Safety /// /// This method is unsafe since we will dereference a raw pointer and act /// on the data pointed to. The data must be a valid flat device tree and /// no other references to this data must exist. /// /// # Errors /// /// If the sanity check fails (the pointer isn't pointing on a valid fdt) /// this method will return an error. Likewise, if the fdt is of an /// incompatible version this method will return an error. Other corruptions /// to the binary data is undefined behaivour and are prohibited to ensure /// safety. /// /// # Examples /// /// ``` /// use fdt::FDT; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// unsafe { /// let fdt = FDT::from_raw(dtb); /// assert!(fdt.is_ok()); /// } /// ``` /// Using a badly formatted dtb file will cause panic: /// ```should_panic /// # use fdt::FDT; /// let ptr = 0x1234 as *const u8; /// unsafe { /// let fdt = FDT::from_raw(ptr); /// } /// ``` pub unsafe fn from_raw(ptr: *const u8) -> Result<FDT<'buf>, ()> { // FDTError> { Ok(FDT { blob: Blob::from_raw(ptr)? }) } /// Returns the physical cpuid of the booting cpu. /// /// If the cpuid isn't available (device tree is of a version < 2) None is returned; /// /// # Examples /// /// ``` /// use fdt::FDT; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// let fdt; /// unsafe { fdt = FDT::from_raw(dtb).unwrap(); } /// /// let boot_cpuid = fdt.boot_cpuid_phys(); /// ``` pub fn boot_cpuid_phys(&self) -> Option<u32> { self.blob.header().boot_cpuid_phys() } /// Returns the total size in bytes of the flat device tree blob. /// /// # Examples /// /// ``` /// use fdt::FDT; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// let fdt; /// unsafe { fdt = FDT::from_raw(dtb).unwrap(); } /// /// let total_size = fdt.total_size(); /// // Allocate some memory /// ``` pub fn total_size(&self) -> u32 { self.blob.header().totalsize() } /// Returns the reserved memory map of the device tree. /// /// The reserved memory map contains a list of physical memory areas which /// are reserved and should not be allocated for other uses. /// /// The memory reserved map implements Iterator, so all entries can be /// accessed using common iterator methods. /// /// # Examples /// /// ``` /// use fdt::FDT; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// let fdt; /// unsafe { fdt = FDT::from_raw(dtb).unwrap(); } /// /// // List all the reserved memory entries in this .dtb (in this case there is only /// // one at address 0 with size 4096) /// for entry in fdt.memory_reserve_map() { /// assert_eq!(entry.address, 0); /// assert_eq!(entry.size, 0x1000); /// } /// ``` pub fn memory_reserve_map(&self) -> MemoryReserveMap<'buf>{ MemoryReserveMap::new(self.blob.rsvmap()) } /// Returns a [NodeIterator] over the nodes of the flat device tree. /// /// The nodes are iterated over in a depth first order. /// /// # Examples /// /// ``` /// use fdt::FDT; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// let fdt; /// unsafe { fdt = FDT::from_raw(dtb).unwrap(); } /// /// // Print all nodes /// for node in fdt.nodes() { /// println!("{}", node.name()); /// } /// ``` pub fn nodes(&'buf self) -> Subnodes<'buf> { Subnodes::new(self.blob.nodes(), 0) } // Utility methods /// Takes a phandle and returns the corresponding device [Node] /// /// Returns a [None] if no device [Node] with the requested phandle exists. /// All phandles are assumed to be unique and if multiple nodes share a /// phandle value, all but the first one will be ignored. /// /// # Examples /// /// ``` /// use fdt::{FDT, NodeIterator, PropertyValue}; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// let fdt; /// unsafe { fdt = FDT::from_raw(dtb).unwrap(); } /// /// // Fetch "cpus" node via it's phandle (in this particular .dtb 67) /// println!("{}", fdt.phandle(67).unwrap().name()); // prints "cpus" /// ``` pub fn phandle(&'buf self, phandle: u32) -> Option<Node<'buf>> { self.nodes().with_phandle(phandle) } /// Takes an alias and returns the corresponding device path /// /// Returns a [None] if the alias doesn't exist in the flat device tree. /// /// # Examples /// /// ``` /// use fdt::{FDT, NodeIterator, PropertyValue}; /// let dtb = include_bytes!("../tests/dt.dtb").as_ptr(); /// /// let fdt; /// unsafe { fdt = FDT::from_raw(dtb).unwrap(); } /// /// assert_eq!(fdt.alias("audio"), Some("/soc/audio")); /// /// let audio = fdt.nodes().with_path(fdt.alias("audio").unwrap()).next().unwrap(); /// assert_eq!(audio.property("compatible").unwrap().parse::<&str>().unwrap(), "brcm,bcm2835-audio\u{0}"); /// ``` pub fn alias(&'buf self, alias: &str) -> Option<&'buf str> { self.nodes().with_path("/aliases").nth(0).and_then( |aliases| aliases.property(alias)).and_then( |property| property.parse::<&str>().ok()).and_then( |string| string.split('\0').nth(0)) // aliases may have trailing null characters } }