docs: add docs for patch and string_block

Signed-off-by: Woshiluo Luo <[email protected]>

Author: woshiluo

src/ser/mod.rs

@@ -8,6 +8,8 @@ use crate::ser::patch::Patch;
 
 const RSVMAP_LEN: usize = 16;
 
+/// Serialize the data to dtb, with a list fof Patch, write to the `writer`.
+///
 /// We do run-twice on convert, first time to generate string block, second time todo real
 /// structure.
 pub fn to_dtb<'se, T>(data: &T, list: &'se [Patch<'se>], writer: &'se mut [u8]) -> Result<(), Error>
@@ -45,6 +47,7 @@ where
         data.serialize(&mut ser)?;
         ser.dst.step_by_u32(FDT_END);
     }
+    // Make header
     {
         let header = unsafe { &mut *(header.as_mut_ptr() as *mut Header) };
         header.magic = u32::from_be(DEVICE_TREE_MAGIC);

src/ser/patch.rs

@@ -1,10 +1,15 @@
 use super::serializer::Serializer;
 use core::cell::Cell;
 
+/// Since this crate is mostly work with `noalloc`, we use `Patch` and `PatchList` for change or
+/// add on a dtb.
 pub struct Patch<'se> {
-    name: &'se str,
     pub data: &'se dyn erased_serde::Serialize,
+    name: &'se str,
+
+    /// This patch match how many item between its path and serializer.
     matched_depth: Cell<usize>,
+    /// Show this patch have been parsed.
     parsed: Cell<bool>,
 }
 
@@ -20,6 +25,7 @@ impl<'se> Patch<'se> {
     }
 
     #[inline(always)]
+    /// Reset the status of patch.
     pub fn init(&self) {
         self.matched_depth.set(0);
         self.parsed.set(false);
@@ -40,6 +46,7 @@ impl<'se> Patch<'se> {
 
     // I hope to impl serde::ser::Serializer, but erase_serialize's return value is different from
     // normal serialize, so we do this.
+    /// Serialize this patch with serializer.
     #[inline(always)]
     pub fn serialize(&self, serializer: &mut Serializer<'se>) {
         self.parsed.set(true);
@@ -49,6 +56,7 @@ impl<'se> Patch<'se> {
     }
 }
 
+/// Here is a list of `Patch`, and have some methods for update `Patch` status.
 pub struct PatchList<'se> {
     list: &'se [Patch<'se>],
 }
@@ -86,6 +94,8 @@ impl<'se> PatchList<'se> {
     }
 
     #[inline(always)]
+    /// Return a list which is on this level, but haven't been parsed, which usually means this
+    /// patch is for adding.
     pub fn add_list(&self, depth: usize) -> impl Iterator<Item = &'se Patch<'se>> + use<'se> {
         self.list.iter().filter(move |x| {
             x.matched_depth.get() == depth && x.get_depth() == depth + 1 && !x.parsed.get()

src/ser/serializer.rs

@@ -5,18 +5,23 @@ use super::string_block::StringBlock;
 use crate::common::*;
 
 #[derive(Clone, Copy)]
+// The enum for current parsing type.
 enum ValueType {
     Node,
     Prop,
 }
 
+/// Serializer
+/// - `dst`: Pointer of distance &[u8] and the ref of &[u8].
+/// - `current_value_type`, `current_name`, `current_dep`: For recursive.
 pub struct Serializer<'se> {
     pub dst: &'se mut Pointer<'se>,
     string_block: &'se mut StringBlock<'se>,
-    value_type: ValueType,
+    patch_list: &'se mut PatchList<'se>,
+
+    current_value_type: ValueType,
     current_name: &'se str,
     current_dep: usize,
-    patch_list: &'se mut PatchList<'se>,
 }
 
 impl<'se> Serializer<'se> {
@@ -31,7 +36,7 @@ impl<'se> Serializer<'se> {
             string_block: cache,
             current_dep: 0,
             current_name: "",
-            value_type: ValueType::Node,
+            current_value_type: ValueType::Node,
             patch_list,
         }
     }
@@ -49,7 +54,9 @@ impl<'se> SerializeDynamicField<'se> for &mut Serializer<'se> {
         T: serde::ser::Serialize + ?Sized,
     {
         let prop_header_offset = self.dst.step_by_prop();
-        let prev_type = self.value_type;
+
+        // Save prev
+        let prev_type = self.current_value_type;
         let prev_name = self.current_name;
         self.current_dep += 1;
         self.current_name = key;
@@ -66,7 +73,7 @@ impl<'se> SerializeDynamicField<'se> for &mut Serializer<'se> {
 
         // We now know how long the prop value.
         // TODO: make we have some better way than put nop, like move this block ahead.
-        if let ValueType::Node = self.value_type {
+        if let ValueType::Node = self.current_value_type {
             self.dst
                 .write_to_offset_u32(prop_header_offset - 4, FDT_NOP);
         } else {
@@ -80,10 +87,12 @@ impl<'se> SerializeDynamicField<'se> for &mut Serializer<'se> {
             );
         }
 
-        self.value_type = prev_type;
-        self.current_name = prev_name;
         self.dst.step_align();
+
+        // Load prev
         self.patch_list.step_back(self.current_dep);
+        self.current_value_type = prev_type;
+        self.current_name = prev_name;
         self.current_dep -= 1;
 
         Ok(())
@@ -258,7 +267,7 @@ impl serde::ser::Serializer for &mut Serializer<'_> {
     }
 
     fn serialize_u32(self, v: u32) -> Result<Self::Ok, Self::Error> {
-        self.value_type = ValueType::Prop;
+        self.current_value_type = ValueType::Prop;
         self.dst.step_by_u32(v);
         Ok(())
     }
@@ -280,7 +289,7 @@ impl serde::ser::Serializer for &mut Serializer<'_> {
     }
 
     fn serialize_str(self, v: &str) -> Result<Self::Ok, Self::Error> {
-        self.value_type = ValueType::Prop;
+        self.current_value_type = ValueType::Prop;
         v.bytes().for_each(|x| {
             self.dst.step_by_u8(x);
         });
@@ -289,7 +298,7 @@ impl serde::ser::Serializer for &mut Serializer<'_> {
     }
 
     fn serialize_bytes(self, v: &[u8]) -> Result<Self::Ok, Self::Error> {
-        self.value_type = ValueType::Prop;
+        self.current_value_type = ValueType::Prop;
         v.iter().for_each(|x| self.dst.step_by_u8(*x));
         Ok(())
     }
@@ -347,7 +356,7 @@ impl serde::ser::Serializer for &mut Serializer<'_> {
     }
 
     fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error> {
-        self.value_type = ValueType::Prop;
+        self.current_value_type = ValueType::Prop;
         Ok(self)
     }
 
@@ -389,7 +398,7 @@ impl serde::ser::Serializer for &mut Serializer<'_> {
         } else {
             self.dst.step_by_name(self.current_name);
         }
-        self.value_type = ValueType::Node;
+        self.current_value_type = ValueType::Node;
         Ok(self)
     }
 

src/ser/string_block.rs

@@ -1,17 +1,24 @@
+/// StringBlock
+/// As spec said, dtb have a block called string block for saving prop names.
 pub struct StringBlock<'se> {
     end: &'se mut usize,
     data: &'se mut [u8],
 }
 
 impl<'se> StringBlock<'se> {
+    /// Make a new string block.
+    ///
+    /// For get how long is string block, we make `end` as a mut ref.
     #[inline(always)]
     pub fn new(dst: &'se mut [u8], end: &'se mut usize) -> StringBlock<'se> {
         StringBlock { data: dst, end }
     }
 
-    /// Will panic when len > end
-    /// TODO: show as error
-    /// Return (Result String, End Offset)
+    // TODO: show as error
+    /// Assume the passing `offset` is the start of a string, and return this string.
+    /// Return (Result String, End Offset).
+    ///
+    /// Will panic when len > end.
     #[inline(always)]
     pub fn get_str_by_offset(&self, offset: usize) -> (&str, usize) {
         if offset > *self.end {
@@ -44,6 +51,7 @@ impl<'se> StringBlock<'se> {
         result
     }
 
+    /// Find a string. If not found, insert it.
     #[inline(always)]
     pub fn find_or_insert(&mut self, name: &str) -> usize {
         let mut current_pos = 0;