chore: document general and app attributes

Signed-off-by: Mohamed Daoudo <mohamed.daoudo@stud.fils.upb.ro>

Author: Joan-DwD

tockloader-lib/src/attributes/app_attributes.rs

@@ -12,12 +12,20 @@ use tokio_serial::SerialStream;
 use crate::bootloader_serial::{issue_command, Command, Response};
 use crate::errors::TockloaderError;
 
+/// This structure contains all relevant information about a tock application.
+///
+/// All data is stored either within [TbfHeader]s, or [TbfFooter]s.
+///
+/// See also <https://book.tockos.org/doc/tock_binary_format>
 #[derive(Debug)]
 pub struct AppAttributes {
     pub tbf_header: TbfHeader,
     pub tbf_footers: Vec<TbfFooter>,
 }
 
+/// This structure represents a footer of a Tock application. Currently, footers
+/// only contain credentials, which are used to verify the integrity of the
+/// application.
 #[derive(Debug)]
 pub struct TbfFooter {
     pub credentials: TbfFooterV2Credentials,
@@ -40,7 +48,19 @@ impl AppAttributes {
         }
     }
 
-    // TODO: Document this function
+    /// Retrieve all application attributes from the device's memory using a
+    /// probe-rs connection.
+    ///
+    /// Applications are layed out in memory sequentially, starting from the
+    /// `appaddr` address. This function will attempt to read all applications
+    /// until it fails to parse.
+    ///
+    /// # Parameters
+    /// - `board_core`: Core access, obtained from a
+    ///   [ProbeRSConnection](crate::connection::ProbeRSConnection)
+    /// - `addr`: The starting address of the first application in memory.
+    ///   Board-specific. See also
+    ///   [BoardSettings](crate::board_settings::BoardSettings).
     pub(crate) fn read_apps_data_probe(
         board_core: &mut Core,
         addr: u64,
@@ -49,6 +69,8 @@ impl AppAttributes {
         let mut apps_counter = 0;
         let mut apps_details: Vec<AppAttributes> = vec![];
 
+        // All applications are stored sequentially in memory, so we read until
+        // we fail to parse.
         loop {
             let mut appdata = vec![0u8; 8];
 
@@ -60,6 +82,11 @@ impl AppAttributes {
             let header_size: u16;
             let total_size: u32;
 
+            // The first 8 bytes of the application data contain the TBF header
+            // lengths and version.
+            //
+            // Note on expect: `read` always fills up the entire buffer, which
+            // was previously declared as 8 bytes.
             match parse_tbf_header_lengths(
                 &appdata
                     .try_into()
@@ -81,14 +108,24 @@ impl AppAttributes {
             let header = parse_tbf_header(&header_data, tbf_version)
                 .map_err(TockloaderError::ParsingError)?;
 
+            // The end of the application binary marks the beginning of the
+            // footer.
+            //
+            // TODO(george-cosma): This is not always true, `get_binary_end`
+            // does not make sense if the application is just padding. This can
+            // crash the process.
             let binary_end_offset = header.get_binary_end();
 
             let mut footers: Vec<TbfFooter> = vec![];
             let total_footers_size = total_size - binary_end_offset;
             let mut footer_offset = binary_end_offset;
             let mut footer_number = 0;
 
+            // Try to parse footers until we reach the end of the application.
             loop {
+                // We don't know the size of the current footer, so we read the
+                // remaining bytes in the application (`footer_offset -
+                // binary_end_offset`) , even if we overread.
                 let mut appfooter =
                     vec![0u8; (total_footers_size - (footer_offset - binary_end_offset)) as usize];
 
@@ -102,6 +139,7 @@ impl AppAttributes {
                 footers.insert(footer_number, TbfFooter::new(footer_info.0, footer_info.1));
 
                 footer_number += 1;
+                // we add 4 because that is the size of TL part of the TLV header (2 bytes type + 2 bytes length)
                 footer_offset += footer_info.1 + 4;
 
                 if footer_offset == total_size {
@@ -117,7 +155,19 @@ impl AppAttributes {
         }
     }
 
-    // TODO: Document this function
+    /// Retrieve all application attributes from the device's memory using a
+    /// serial connection.
+    ///
+    /// Applications are layed out in memory sequentially, starting from the
+    /// `appaddr` address. This function will attempt to read all applications
+    /// until it fails to parse.
+    ///
+    /// # Parameters
+    /// - `port`: Serial access, obtained from a
+    ///   [SerialConnection](crate::connection::SerialConnection)
+    /// - `addr`: The starting address of the first application in memory.
+    ///   Board-specific. See also
+    ///   [BoardSettings](crate::board_settings::BoardSettings).
     pub(crate) async fn read_apps_data_serial(
         port: &mut SerialStream,
         addr: u64,
@@ -126,20 +176,30 @@ impl AppAttributes {
         let mut apps_counter = 0;
         let mut apps_details: Vec<AppAttributes> = vec![];
 
+        // All applications are stored sequentially in memory, so we read until
+        // we fail to parse.
         loop {
+            // The tockloader protocol only supports 32-bit architectures,
+            // though in the future support will be extended to 64-bit.
             let mut pkt = (appaddr as u32).to_le_bytes().to_vec();
             let length = (8_u16).to_le_bytes().to_vec();
             for i in length {
                 pkt.push(i);
             }
 
+            // Read the first 8 bytes, which is the length of a TLV header.
             let (_, appdata) =
                 issue_command(port, Command::ReadRange, pkt, true, 8, Response::ReadRange).await?;
 
             let tbf_version: u16;
             let header_size: u16;
             let total_size: u32;
 
+            // The first 8 bytes of the application data contain the TBF header
+            // lengths and version.
+            //
+            // Note on expect: `read` always fills up the entire buffer, which
+            // was previously declared as 8 bytes.
             match parse_tbf_header_lengths(
                 &appdata[0..8]
                     .try_into()
@@ -159,6 +219,7 @@ impl AppAttributes {
                 pkt.push(i);
             }
 
+            // Read the rest of the header
             let (_, header_data) = issue_command(
                 port,
                 Command::ReadRange,
@@ -178,7 +239,11 @@ impl AppAttributes {
             let mut footer_offset = binary_end_offset;
             let mut footer_number = 0;
 
+            // Try to parse footers until we reach the end of the application.
             loop {
+                // We don't know the size of the current footer, so we read the
+                // remaining bytes in the application (`footer_offset -
+                // binary_end_offset`) , even if we overread.
                 let mut pkt = (appaddr as u32 + footer_offset).to_le_bytes().to_vec();
                 let length = ((total_footers_size - (footer_offset - binary_end_offset)) as u16)
                     .to_le_bytes()
@@ -187,6 +252,7 @@ impl AppAttributes {
                     pkt.push(i);
                 }
 
+                // Read the next header (and perhaps data beyond it)
                 let (_, appfooter) = issue_command(
                     port,
                     Command::ReadRange,
@@ -203,6 +269,7 @@ impl AppAttributes {
                 footers.insert(footer_number, TbfFooter::new(footer_info.0, footer_info.1));
 
                 footer_number += 1;
+                // we add 4 because that is the size of TL part of the TLV header (2 bytes type + 2 bytes length)
                 footer_offset += footer_info.1 + 4;
 
                 if footer_offset == total_size {

tockloader-lib/src/attributes/decode.rs

@@ -2,6 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OXIDOS AUTOMOTIVE 2024.
 
+/// Attributes are key-value pairs that describe hardware configuration, stored
+/// in a fixed 64-byte format:
+///
+/// 1. Bytes 0–7: UTF-8 key string with null-byte padding for shorter strings
+/// 2. Byte 8: Value length (Must be between 1 and 55)
+/// 3. Bytes 9–63: UTF-8 value string. Null-padded to length.
+///
+/// See also <https://book.tockos.org/doc/kernel_attributes.html?highlight=attributes#header-format>
 #[derive(Debug)]
 pub struct DecodedAttribute {
     pub key: String,
@@ -17,7 +25,15 @@ impl DecodedAttribute {
     }
 }
 
-// TODO: explain what is happening here
+/// Internal function used to decode the raw data into a [DecodedAttribute].
+///
+/// # Params
+/// - `step` - byte array of at least 64 bytes.
+///
+/// # Returns
+/// - `None` for an invalid property (invalid value length or invalid utf-8
+///   data).
+/// - `Some(_)` otherwise
 pub(crate) fn decode_attribute(step: &[u8]) -> Option<DecodedAttribute> {
     let raw_key = &step[0..8];
 
@@ -47,7 +63,14 @@ pub(crate) fn decode_attribute(step: &[u8]) -> Option<DecodedAttribute> {
     Some(DecodedAttribute::new(key, value))
 }
 
-// TODO: explain what is happening here
+// TODO(george-cosma) replace this function with std::str::from_utf8(...). It
+// does the same thing.
+
+/// Transform a byte-slice into a String.
+///
+/// # Panics
+///
+/// This code panics if the given bytes are not utf-8 representable
 pub(crate) fn bytes_to_string(raw: &[u8]) -> String {
     let decoder = utf8_decode::Decoder::new(raw.iter().cloned());