Skip to content

Commit a36045c

Browse files
repnoprepnop
committed
wip: more docs + remove some methods in favor of direct field access
1 parent 904823f commit a36045c

12 files changed

+91
-57
lines changed

‎src/nodes.rs

+35-14
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,20 @@ pub trait AsNode<'a, P: ParserWithMode<'a>> {
3636
fn as_node(&self) -> Node<'a, P>;
3737
}
3838

39+
/// A node name that can searched with.
3940
#[derive(Debug, Clone, Copy)]
4041
pub enum SearchableNodeName<'a> {
42+
/// Node name without the unit address
4143
Base(&'a str),
44+
/// Node name with the unit address
4245
WithUnitAddress(NodeName<'a>),
4346
}
4447

4548
/// Convert from a type that can potentially represent a node name that is able
4649
/// to be searched for during lookup operations.
4750
///
48-
/// Currently, two type impls are defined:
51+
/// Currently, two type impls are defined on types other than
52+
/// [`SearchableNodeName`]:
4953
/// 1. [`NodeName`]: corresponds directly to a
5054
/// [`SearchableNodeName::WithUnitAddress`].
5155
/// 2. [`&str`]: attempts to parse the `str` as `name@unit-address`,
@@ -56,6 +60,13 @@ pub trait IntoSearchableNodeName<'a>: Sized + crate::sealed::Sealed {
5660
fn into_searchable_node_name(self) -> SearchableNodeName<'a>;
5761
}
5862

63+
impl crate::sealed::Sealed for SearchableNodeName<'_> {}
64+
impl<'a> IntoSearchableNodeName<'a> for SearchableNodeName<'a> {
65+
fn into_searchable_node_name(self) -> SearchableNodeName<'a> {
66+
self
67+
}
68+
}
69+
5970
impl crate::sealed::Sealed for NodeName<'_> {}
6071
impl<'a> IntoSearchableNodeName<'a> for NodeName<'a> {
6172
fn into_searchable_node_name(self) -> SearchableNodeName<'a> {
@@ -75,9 +86,12 @@ impl<'a> IntoSearchableNodeName<'a> for &'a str {
7586
}
7687
}
7788

89+
/// A node name, split into its component parts.
7890
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7991
pub struct NodeName<'a> {
92+
/// Node name.
8093
pub name: &'a str,
94+
/// Optional unit address specified after the `@`.
8195
pub unit_address: Option<&'a str>,
8296
}
8397

@@ -108,7 +122,7 @@ pub struct Node<'a, P: ParserWithMode<'a>> {
108122
impl<'a, P: ParserWithMode<'a>> Node<'a, P> {
109123
/// Change the type of this node's [`PanicMode`] to [`NoPanic`].
110124
#[inline(always)]
111-
pub(crate) fn fallible(self) -> FallibleNode<'a, P> {
125+
pub fn fallible(self) -> FallibleNode<'a, P> {
112126
self.alt()
113127
}
114128

@@ -377,6 +391,8 @@ impl<Granularity> RawNode<Granularity> {
377391
}
378392
}
379393

394+
/// Allows for searching and iterating over all of the properties of a given
395+
/// [`Node`].
380396
pub struct NodeProperties<'a, P: ParserWithMode<'a> = (AlignedParser<'a>, Panic)> {
381397
data: &'a [<P as Parser<'a>>::Granularity],
382398
strings: StringsBlock<'a>,
@@ -394,6 +410,7 @@ impl<'a, P: ParserWithMode<'a>> NodeProperties<'a, P> {
394410
}
395411
}
396412

413+
/// Create an iterator over the properties in the [`Node`].
397414
#[inline(always)]
398415
pub fn iter(self) -> NodePropertiesIter<'a, P> {
399416
NodePropertiesIter { properties: self.alt(), _mode: core::marker::PhantomData }
@@ -426,6 +443,7 @@ impl<'a, P: ParserWithMode<'a>> NodeProperties<'a, P> {
426443
}))
427444
}
428445

446+
/// Attempt to find a property with the provided name.
429447
#[inline]
430448
#[track_caller]
431449
pub fn find(&self, name: &str) -> P::Output<Option<NodeProperty<'a>>> {
@@ -465,6 +483,7 @@ impl<'a, P: ParserWithMode<'a>> IntoIterator for NodeProperties<'a, P> {
465483
}
466484
}
467485

486+
/// See [`NodeProperties::iter`].
468487
#[derive(Clone)]
469488
pub struct NodePropertiesIter<'a, P: ParserWithMode<'a> = (AlignedParser<'a>, Panic)> {
470489
properties: NodeProperties<'a, (P::Parser, NoPanic)>,
@@ -486,10 +505,13 @@ impl<'a, P: ParserWithMode<'a>> Iterator for NodePropertiesIter<'a, P> {
486505
}
487506
}
488507

508+
/// Generic node property.
489509
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
490510
pub struct NodeProperty<'a> {
491-
name: &'a str,
492-
value: &'a [u8],
511+
/// Property name.
512+
pub name: &'a str,
513+
/// Raw property value.
514+
pub value: &'a [u8],
493515
}
494516

495517
impl<'a> NodeProperty<'a> {
@@ -498,22 +520,15 @@ impl<'a> NodeProperty<'a> {
498520
Self { name, value }
499521
}
500522

501-
#[inline(always)]
502-
pub fn name(&self) -> &'a str {
503-
self.name
504-
}
505-
506-
#[inline(always)]
507-
pub fn value(&self) -> &'a [u8] {
508-
self.value
509-
}
510-
523+
/// Attempt to convert this property's value to the specified
524+
/// [`PropertyValue`] type.
511525
#[inline(always)]
512526
pub fn as_value<V: PropertyValue<'a>>(&self) -> Result<V, InvalidPropertyValue> {
513527
V::parse(self.value)
514528
}
515529
}
516530

531+
/// Allows for searching and iterating over the children of a given [`Node`].
517532
pub struct NodeChildren<'a, P: ParserWithMode<'a> = (AlignedParser<'a>, Panic)> {
518533
data: &'a [<P as Parser<'a>>::Granularity],
519534
parent: &'a RawNode<<P as Parser<'a>>::Granularity>,
@@ -523,6 +538,7 @@ pub struct NodeChildren<'a, P: ParserWithMode<'a> = (AlignedParser<'a>, Panic)>
523538
}
524539

525540
impl<'a, P: ParserWithMode<'a>> NodeChildren<'a, P> {
541+
/// Create an iterator over the [`Node`]'s children.
526542
#[inline(always)]
527543
pub fn iter(&self) -> NodeChildrenIter<'a, P> {
528544
NodeChildrenIter {
@@ -559,6 +575,10 @@ impl<'a, P: ParserWithMode<'a>> NodeChildren<'a, P> {
559575
})
560576
}
561577

578+
/// Attempt to find the first child matching the provided name, see
579+
/// [`IntoSearchableNodeName`] for more details. If the name lacks a unit
580+
/// address, unit addresses on the children will be ignored when checking if
581+
/// the name matches.
562582
#[inline]
563583
#[track_caller]
564584
pub fn find<'n, N>(&self, name: N) -> P::Output<Option<Node<'a, P>>>
@@ -609,6 +629,7 @@ impl<'a, P: ParserWithMode<'a>> IntoIterator for NodeChildren<'a, P> {
609629
}
610630
}
611631

632+
/// See [`NodeChildren::iter`].
612633
#[derive(Clone)]
613634
pub struct NodeChildrenIter<'a, P: ParserWithMode<'a> = (AlignedParser<'a>, Panic)> {
614635
children: NodeChildren<'a, (P::Parser, NoPanic)>,

‎src/nodes/aliases.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ where
8484
#[track_caller]
8585
fn next(&mut self) -> Option<Self::Item> {
8686
Some(P::to_output(match self.properties.next() {
87-
Some(Ok(prop)) => crate::tryblock!({ Ok((prop.name(), prop.as_value::<&'a str>()?)) }),
87+
Some(Ok(prop)) => crate::tryblock!({ Ok((prop.name, prop.as_value::<&'a str>()?)) }),
8888
Some(Err(e)) => Err(e),
8989
None => return None,
9090
}))

‎src/nodes/chosen.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,9 @@ impl<'a, P: ParserWithMode<'a>> Chosen<'a, P> {
3030
pub fn bootargs(self) -> P::Output<Option<&'a str>> {
3131
P::to_output(crate::tryblock!({
3232
for prop in self.node.properties()?.into_iter().flatten() {
33-
if prop.name() == "bootargs" {
33+
if prop.name == "bootargs" {
3434
return Ok(Some(
35-
core::str::from_utf8(&prop.value()[..prop.value().len() - 1])
35+
core::str::from_utf8(&prop.value[..prop.value.len() - 1])
3636
.map_err(|_| FdtError::ParseError(ParseError::InvalidCStrValue))?,
3737
));
3838
}
@@ -91,7 +91,7 @@ impl<'a, P: ParserWithMode<'a>> Chosen<'a, P> {
9191
.into_iter()
9292
.find_map(|n| match n {
9393
Err(e) => Some(Err(e)),
94-
Ok(property) => match property.name() == "stdout-path" {
94+
Ok(property) => match property.name == "stdout-path" {
9595
false => None,
9696
true => Some(property.as_value::<&'a str>().map_err(Into::into).map(|s| {
9797
let (path, params) =
@@ -151,7 +151,7 @@ impl<'a, P: ParserWithMode<'a>> Chosen<'a, P> {
151151
.into_iter()
152152
.find_map(|n| match n {
153153
Err(e) => Some(Err(e)),
154-
Ok(property) => match property.name() == "stdin-path" {
154+
Ok(property) => match property.name == "stdin-path" {
155155
false => None,
156156
true => Some(property.as_value::<&str>().map_err(Into::into).map(|s| {
157157
let (path, params) =

‎src/nodes/cpus.rs

+8-8
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ impl<'a, P: ParserWithMode<'a>> Cpus<'a, P> {
3737
pub fn common_timebase_frequency(&self) -> P::Output<Option<u64>> {
3838
P::to_output(crate::tryblock!({
3939
match self.node.properties()?.find("timebase-frequency")? {
40-
Some(prop) => match prop.value().len() {
40+
Some(prop) => match prop.value.len() {
4141
4 => Ok(Some(u64::from(prop.as_value::<u32>()?))),
4242
8 => Ok(Some(prop.as_value::<u64>()?)),
4343
_ => Err(FdtError::InvalidPropertyValue),
@@ -55,7 +55,7 @@ impl<'a, P: ParserWithMode<'a>> Cpus<'a, P> {
5555
pub fn common_clock_frequency(&self) -> P::Output<Option<u64>> {
5656
P::to_output(crate::tryblock!({
5757
match self.node.properties()?.find("clock-frequency")? {
58-
Some(prop) => match prop.value().len() {
58+
Some(prop) => match prop.value.len() {
5959
4 => Ok(Some(u64::from(prop.as_value::<u32>()?))),
6060
8 => Ok(Some(prop.as_value::<u64>()?)),
6161
_ => Err(FdtError::InvalidPropertyValue),
@@ -181,15 +181,15 @@ impl<'a, P: ParserWithMode<'a>> Cpu<'a, P> {
181181
return Err(FdtError::MissingRequiredProperty("reg"));
182182
};
183183

184-
if reg.value().is_empty() {
184+
if reg.value.is_empty() {
185185
return Err(FdtError::InvalidPropertyValue);
186186
}
187187

188188
let Some(address_cells) = self.node.parent().unwrap().property::<AddressCells>()? else {
189189
return Err(FdtError::MissingRequiredProperty("#address-cells"));
190190
};
191191

192-
Ok(CpuIds { reg: reg.value(), address_cells: address_cells.0, _collector: core::marker::PhantomData })
192+
Ok(CpuIds { reg: reg.value, address_cells: address_cells.0, _collector: core::marker::PhantomData })
193193
}))
194194
}
195195

@@ -208,7 +208,7 @@ impl<'a, P: ParserWithMode<'a>> Cpu<'a, P> {
208208
pub fn clock_frequency(self) -> P::Output<u64> {
209209
P::to_output(crate::tryblock!({
210210
match self.node.properties()?.find("clock-frequency")? {
211-
Some(prop) => match prop.value().len() {
211+
Some(prop) => match prop.value.len() {
212212
4 => Ok(u64::from(prop.as_value::<u32>()?)),
213213
8 => Ok(prop.as_value::<u64>()?),
214214
_ => Err(FdtError::InvalidPropertyValue),
@@ -222,7 +222,7 @@ impl<'a, P: ParserWithMode<'a>> Cpu<'a, P> {
222222
.find("clock-frequency")?
223223
.ok_or(FdtError::MissingRequiredProperty("clock-frequency"))?;
224224

225-
match prop.value().len() {
225+
match prop.value.len() {
226226
4 => Ok(u64::from(prop.as_value::<u32>()?)),
227227
8 => Ok(prop.as_value::<u64>()?),
228228
_ => Err(FdtError::InvalidPropertyValue),
@@ -248,7 +248,7 @@ impl<'a, P: ParserWithMode<'a>> Cpu<'a, P> {
248248
pub fn timebase_frequency(self) -> P::Output<u64> {
249249
P::to_output(crate::tryblock!({
250250
match self.node.properties()?.find("timebase-frequency")? {
251-
Some(prop) => match prop.value().len() {
251+
Some(prop) => match prop.value.len() {
252252
4 => Ok(u64::from(prop.as_value::<u32>()?)),
253253
8 => Ok(prop.as_value::<u64>()?),
254254
_ => Err(FdtError::InvalidPropertyValue),
@@ -262,7 +262,7 @@ impl<'a, P: ParserWithMode<'a>> Cpu<'a, P> {
262262
.find("timebase-frequency")?
263263
.ok_or(FdtError::MissingRequiredProperty("timebase-frequency"))?;
264264

265-
match prop.value().len() {
265+
match prop.value.len() {
266266
4 => Ok(u64::from(prop.as_value::<u32>()?)),
267267
8 => Ok(prop.as_value::<u64>()?),
268268
_ => Err(FdtError::InvalidPropertyValue),

‎src/nodes/memory.rs

+5-5
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ impl<'a, P: ParserWithMode<'a>> Memory<'a, P> {
7575
P::to_output(crate::tryblock!({
7676
match self.node.properties()?.find("initial-mapped-area")? {
7777
Some(prop) => {
78-
let value = prop.value();
78+
let value = prop.value;
7979
if value.len() != (/* effective address */8 + /* physical address */ 8 + /* size */ 4) {
8080
return Err(FdtError::InvalidPropertyValue);
8181
}
@@ -207,13 +207,13 @@ impl<'a, P: ParserWithMode<'a>> ReservedMemoryChild<'a, P> {
207207
// from the `NodeChildrenIter` struct
208208
let size_cells = self.node.parent().unwrap().property::<SizeCells>()?.unwrap_or(SizeCells(1));
209209

210-
if size.value().len() % size_cells.0 != 0 {
210+
if size.value.len() % size_cells.0 != 0 {
211211
return Err(FdtError::InvalidPropertyValue);
212212
}
213213

214214
let mut builder = <C as CellCollector>::Builder::default();
215215

216-
for component in size.value().chunks_exact(4) {
216+
for component in size.value.chunks_exact(4) {
217217
if builder.push(u32::from_be_bytes(component.try_into().unwrap())).is_err() {
218218
return Ok(Some(Err(CollectCellsError)));
219219
}
@@ -240,13 +240,13 @@ impl<'a, P: ParserWithMode<'a>> ReservedMemoryChild<'a, P> {
240240
// from the `NodeChildrenIter` struct
241241
let size_cells = self.node.parent().unwrap().property::<SizeCells>()?.unwrap_or(SizeCells(1));
242242

243-
if alignment.value().len() % size_cells.0 != 0 {
243+
if alignment.value.len() % size_cells.0 != 0 {
244244
return Err(FdtError::InvalidPropertyValue);
245245
}
246246

247247
let mut builder = <C as CellCollector>::Builder::default();
248248

249-
for component in alignment.value().chunks_exact(4) {
249+
for component in alignment.value.chunks_exact(4) {
250250
if builder.push(u32::from_be_bytes(component.try_into().unwrap())).is_err() {
251251
return Ok(Some(Err(CollectCellsError)));
252252
}

‎src/pretty_print.rs

+6-6
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ fn print_properties<'a, P: Parser<'a>>(
132132
any_props = true;
133133
let prop = prop?;
134134

135-
match prop.name() {
135+
match prop.name {
136136
"reg" => {
137137
write!(f, "{:width$}reg = <", ' ', width = depth * 4 + 4)?;
138138
for (i, reg) in node.reg()?.unwrap().iter::<u64, Option<u64>>().enumerate() {
@@ -155,12 +155,12 @@ fn print_properties<'a, P: Parser<'a>>(
155155
writeln!(f, "{:width$}{} = <{:#04x}>;", ' ', name, prop.as_value::<u32>()?, width = depth * 4 + 4)?;
156156
}
157157
_ => match prop.as_value::<&str>() {
158-
Ok("") => writeln!(f, "{:width$}{};", ' ', prop.name(), width = depth * 4 + 4)?,
159-
Ok(value) => writeln!(f, "{:width$}{} = {:?};", ' ', prop.name(), value, width = depth * 4 + 4)?,
160-
_ => match prop.value().len() {
161-
0 => writeln!(f, "{:width$}{};", ' ', prop.name(), width = depth * 4 + 4)?,
158+
Ok("") => writeln!(f, "{:width$}{};", ' ', prop.name, width = depth * 4 + 4)?,
159+
Ok(value) => writeln!(f, "{:width$}{} = {:?};", ' ', prop.name, value, width = depth * 4 + 4)?,
160+
_ => match prop.value.len() {
161+
0 => writeln!(f, "{:width$}{};", ' ', prop.name, width = depth * 4 + 4)?,
162162
_ => {
163-
write!(f, "{:width$}{} = <", ' ', prop.name(), width = depth * 4 + 4)?;
163+
write!(f, "{:width$}{} = <", ' ', prop.name, width = depth * 4 + 4)?;
164164

165165
for (i, n) in prop.as_value::<U32List>()?.iter().enumerate() {
166166
if i != 0 {

0 commit comments

Comments
 (0)