chore: document general and app attributes

Author: Joan-DwD

tockloader-lib/src/attributes/app_attributes.rs

@@ -12,12 +12,18 @@ use tokio_serial::SerialStream;
 use crate::bootloader_serial::{issue_command, Command, Response};
 use crate::errors::TockloaderError;
 
+///   Structure used to package an app's header and footer data.
+///   This structure is used to package together all relevant information like metadata about an app.
+///   The information is usually stored within a [TbfHeader], and one or more [TbfFooters](TbfFooterV2Credentials).
+///   For more details see <https://book.tockos.org/doc/tock_binary_format>
 #[derive(Debug)]
 pub struct AppAttributes {
     pub tbf_header: TbfHeader,
     pub tbf_footers: Vec<TbfFooter>,
 }
 
+///   Structure used to package a footers credential data and the size of the footer.
+///   This is where credentials of the footer is stored
 #[derive(Debug)]
 pub struct TbfFooter {
     pub credentials: TbfFooterV2Credentials,
@@ -39,8 +45,29 @@ impl AppAttributes {
             tbf_footers: footers_data,
         }
     }
-
-    // TODO: Document this function
+    ///   The function below is used to retrieve header and footer data
+    ///
+    ///   Starting from the 0x40000 address,
+    ///   using the ['parse_tbf_header_lengths'] function, we read the very first 8 bytes to determine:
+    ///
+    ///   - tbf-version
+    ///   - header_size
+    ///   - total_size
+    ///
+    ///   Afterwards, with the 'header_size' we just read,
+    ///   we read the the rest of the header information using the same function
+    ///   then, we save our binary app which marks the total size of the app and move on to the the footer.
+    ///
+    ///   Now, we calculate the total size of the footer.
+    ///
+    ///   Then, we compute the exact offset of the current footer.
+    ///
+    ///   Using it, we read the correct number of bytes from memory,
+    ///   construct a 'TbfFooter' struct from the raw bytes, and store it.
+    ///
+    ///   Once all footers for an app are gathered,
+    ///   we wrap the header, footers, and other metadata into an `AppAttributes` struct,
+    ///   and push it into the apps_details vector, which holds info for all flashed applications
     pub(crate) fn read_apps_data_probe(
         board_core: &mut Core,
         addr: u64,
@@ -63,7 +90,7 @@ impl AppAttributes {
             match parse_tbf_header_lengths(
                 &appdata
                     .try_into()
-                    .expect("Buffer length must be at least 8 bytes long."),
+                    .expect("Buffer length must be at least 8 bytes long."), // All attributes always add up to 8 bytes.
             ) {
                 Ok(data) => {
                     tbf_version = data.0;
@@ -81,16 +108,19 @@ impl AppAttributes {
             let header = parse_tbf_header(&header_data, tbf_version)
                 .map_err(TockloaderError::ParsingError)?;
 
-            let binary_end_offset = header.get_binary_end();
+            let binary_end_offset = header.get_binary_end(); // the end of the header marks the beginning of the footer
 
+            // 1. Calculate the total size of all footers by subtracting the binary's end offset (`binary_end_offset`) from the total application size (`total_size`).
+            // 2. Initialize the reading offset (`footer_offset`) to the start of the footers (right after the binary ends).
+            // 3. Loop until we've read all footers (when `footer_offset` reaches `total_size`):
             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;
 
             loop {
                 let mut appfooter =
-                    vec![0u8; (total_footers_size - (footer_offset - binary_end_offset)) as usize];
+                    vec![0u8; (total_footers_size - (footer_offset - binary_end_offset)) as usize]; // we take the size of the whole footer initially then decrease it by the size of the previous one as we don't know the size of the footer we are reading
 
                 board_core
                     .read(appaddr + footer_offset as u64, &mut appfooter)
@@ -102,10 +132,10 @@ impl AppAttributes {
                 footers.insert(footer_number, TbfFooter::new(footer_info.0, footer_info.1));
 
                 footer_number += 1;
-                footer_offset += footer_info.1 + 4;
+                footer_offset += footer_info.1 + 4; // the next footer begins using this relation: (footer_offset = binary_end_offset) += summation of (previous_footer_size + 4)
 
                 if footer_offset == total_size {
-                    break;
+                    break; // all footers have been processed.
                 }
             }
 
@@ -117,7 +147,18 @@ impl AppAttributes {
         }
     }
 
-    // TODO: Document this function
+    ///   This reads application metadata and footers from a device just like the previous function except it's done via serial.
+    ///
+    ///   Starting at the given address, this function:
+    ///
+    /// 1. Reads the initial 8 bytes of the app header to get version and size info.
+    /// 2. Reads the full app header based on that size.
+    /// 3. Reads and parses all app footers following the app binary.
+    /// 4. Collects and returns all app attributes found sequentially in memory.
+    ///
+    ///   Communicates using the Tockloader protocol’s `ReadRange` command and handles multiple apps until no more are found.
+    ///
+    ///   Returns a vector of app attributes or an error on failure.
     pub(crate) async fn read_apps_data_serial(
         port: &mut SerialStream,
         addr: u64,
@@ -127,13 +168,24 @@ impl AppAttributes {
         let mut apps_details: Vec<AppAttributes> = vec![];
 
         loop {
-            let mut pkt = (appaddr as u32).to_le_bytes().to_vec();
-            let length = (8_u16).to_le_bytes().to_vec();
+            let mut pkt = (appaddr as u32).to_le_bytes().to_vec(); // the tockloader protocol only supports up to 32 bytes, hence we converted acquiring 4 byte little endians.
+            let length = (8_u16).to_le_bytes().to_vec(); // 2 byte little endians
             for i in length {
                 pkt.push(i);
             }
 
-            let (_, appdata) =
+            // This sends a `ReadRange` command to the microcontroller to read 8 bytes of memory starting at `appaddr`,
+            // and receives the result over the serial connection.
+            // The microcontroller receives the command, checks the Command ID (`0x06` for `ReadRange`),
+            // then reads the 1-byte payload length and the actual payload:
+            // 4 bytes for the address (little-endian), and 2 bytes for the length to read (also little-endian).
+            // The microcontroller processes incoming bytes using a state machine like this:
+            // enum SerialState {
+            //  WaitingForCommand, // Awaiting the 1-byte command ID
+            //  WaitingForLength,  // Awaiting the 1-byte payload length
+            //  WaitingForPayload { command: u8, length: usize, buffer: Vec<u8> }, // Receiving payload
+            //   }
+            let (_, appdata) = // the first element in the tuple be returned is raw data so we ignore it and take the second which is the app data we need
                 issue_command(port, Command::ReadRange, pkt, true, 8, Response::ReadRange).await?;
 
             let tbf_version: u16;
@@ -158,7 +210,13 @@ impl AppAttributes {
             for i in length {
                 pkt.push(i);
             }
-
+            // This also sends a ReadRange command to fetch the full TBF header from the same app address (appaddr).
+            //
+            // The first read (8 bytes) gave us only the header lengths and total size,
+            // but now that we know the full header size (header_size), we send a new request to retrieve the entire header.
+            //
+            // The returned data (header_data) is a raw byte vector containing all fields of the TBF header,
+            // including version, flags, entry point, protected regions, package name, etc.
             let (_, header_data) = issue_command(
                 port,
                 Command::ReadRange,
@@ -187,6 +245,11 @@ impl AppAttributes {
                     pkt.push(i);
                 }
 
+                // Issue a ReadRange command over serial to fetch the next footer block.
+                //
+                // The response contains raw bytes starting from footer_offset, with the desired length.
+                //
+                // We ignore the first tuple element and keep only the returned footer bytes.
                 let (_, appfooter) = issue_command(
                     port,
                     Command::ReadRange,

tockloader-lib/src/attributes/decode.rs

@@ -2,6 +2,27 @@
 // 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. 8-byte null-padded UTF-8 key (e.g., "board__\0\0")
+/// 2. 1-byte value length (1-55)
+/// 3. Variable-length UTF-8 value (e.g., "nrf52840")
+/// 4. Null padding to fill 64 bytes
+///
+/// These attributes are obtained by:
+///
+/// 1. Reading physical memory from 0x600-0x9FF (1024 bytes = 16 attribute slots)
+/// 2. Decoding each 64-byte chunk into key-value pairs
+/// 3. Storing valid pairs in this struct
+///
+/// Tock attributes examples:
+///
+/// 1. board: Hardware platform name
+/// 2. arch: CPU architecture
+/// 3. appaddr: Application memory start address
+/// 4. boothash: Bootloader integrity checksum
+///     
+/// This structure used to hold the data of the attributes region at the 0x600-0x9FF range
 #[derive(Debug)]
 pub struct DecodedAttribute {
     pub key: String,
@@ -16,8 +37,25 @@ impl DecodedAttribute {
         }
     }
 }
-
-// TODO: explain what is happening here
+/// Function used to decode 64 byte chunks from the attributes region at the 0x600-0x9FF range
+///
+/// Each attribute follows this layout:
+///
+/// 1. Bytes 0–7: UTF-8 key string
+/// 2. Byte 8: Value length (1–55)
+/// 3. Bytes 9–63: UTF-8 value string
+///
+/// The function returns:
+///
+/// - `Some(DecodedAttribute)` containing the parsed key and value if valid
+/// - `None` if:
+/// - The value length is zero or exceeds 55 bytes (corrupt or uninitialized)
+/// - The value contains invalid UTF-8 data
+///
+/// Panics
+///
+/// This function panics if the input step is less than 64 bytes.
+/// The caller must ensure chunks are exactly 64 bytes.
 pub(crate) fn decode_attribute(step: &[u8]) -> Option<DecodedAttribute> {
     let raw_key = &step[0..8];
 
@@ -47,7 +85,11 @@ pub(crate) fn decode_attribute(step: &[u8]) -> Option<DecodedAttribute> {
     Some(DecodedAttribute::new(key, value))
 }
 
-// TODO: explain what is happening here
+/// Specifically used in the read_system_attributes fn from the system_attributes.rs
+///
+/// to decode the bytes of the sentinel kernel attribute.
+///
+/// It's used to decode utf-8 encoded bytes and return them as Strings
 pub(crate) fn bytes_to_string(raw: &[u8]) -> String {
     let decoder = utf8_decode::Decoder::new(raw.iter().cloned());